Documentation for the fsagent harness. If you read in order, each page builds on the previous one; every page links back here.
- Architecture — the three layers, the membrane, the design principles everything else follows.
- Tool declarations — the
ToolDefinitionschema: what every tool must declare, and what the schema refuses to accept. - Functions — the byte-level primitive layer underneath the tools.
- Pipeline — Sandbox → Policy → Friction → Execute → Git → Trajectory, in depth.
- Policy — the YAML rule engine: groups and tools in rules, whitelists, precedence, shaped denials.
- Friction — overwrite, unique-match, and recursive confirmations; first attempt fails informatively, the retry is an informed action.
- Tiers & recovery — what the harness can honestly
promise about reversibility, and the machinery behind it (git auto-commit,
_trash/staging). - Trajectory — the append-only session log.
- Failure shaping — the catalog of errors that tell the model what to do next.
- Testing — TDD conventions and how the shaped messages are pinned by exact-string tests.
- Roadmap — open flags and unbuilt layers.
- Agent & sub-agents — wiring tools to a model; the
exploreread-only sub-agent and how it shares enforcement. - Tool reference — one page per tool, with args, returns, and verbatim failure examples.