Agent and editor reference

Rendered from docs/reference-agents.md in the engine repository, where a correction belongs, and where the test suite executes every example on this page.

An editor and an agent read a model through the same doors, and there are more of them than the command line. This page is normative for that surface taken as a whole: which doors there are, what each answers, what none of them does, what posture each takes towards @"..." includes, and which implementation carries it.

Each door’s own specification is elsewhere and is linked from the table below. Nothing here repeats a tool list, an option or an exit table: the API reference specifies every verb, the language server specifies the protocol and the library behind it, and the errors reference specifies the exit codes and the codes a report carries.

Contents#

• The doors
• The machine answer
• What none of them does
• Includes, by door
• The teaching topics
• Which implementation has it
• Related

The doors#

A door is a way in, not a tier: the tool server answers with the report the verb prints, and the verb prints what the library returned. One question has one answer whichever door it arrives by, which is the property that makes a transcript in a document and a tool call in an agent the same evidence.

The machine answer#

--format json is a per-verb option rather than a global one: fmt, template and agentsmd do not take it, and refuse it by name.

Where a verb does answer JSON it answers one object, and every one of them opens with the same block:

aontu trace --format json is the one exception: it answers its record alone, under trace.

How an answer says whether it holds is one of three shapes. The shape belongs to the verb rather than to the run, so a document that does not hold changes the values and never the keys:

A refusal is an answer, and the findings say what was refused. The key they arrive under is the verb’s too:

A verb that reports no findings says what it could not do in a field of its own instead: view’s loss, jsonschema’s lossy and render --check’s drift.

A caller branches on ok or on verdict rather than parsing prose, and the exit code carries the same answer: the errors reference is normative for it. Each verb’s own section names the fields beside these.

The tool server keeps the same rule at the protocol level: a tool whose document does not hold answers with its own report and isError: false, because the report is the answer. isError is reserved for a call that could not be made at all, such as an unknown tool, a malformed argument, or a file argument the server does not serve.

What none of them does#

These hold across every door, and each is the property an integrator needs before wiring one into something that runs unattended:

• The language server never writes a file. It answers, and the editor owns the buffer.
• The tool server never writes a file. set answers the new overlay text, and the caller owns the write.
• init never overwrites. If any member of the trio already stands in the directory it refuses before writing any of them, so a refused run leaves nothing half written.
• agentsmd --write changes only what lies between its two markers. Everything outside them is left exactly as it was, which is what makes it safe to re-run and safe to point at a file someone else writes prose in.
• A --check run writes nothing. It compares and exits.
• Evaluation never reaches the network. A module resolves from local stores only; the package verbs are the only ones that fetch, and they say so by name.

Includes, by door#

@"..." reads a file while a document is evaluated, so every door that evaluates a document a caller supplied has a posture towards it. The postures are the trust contract; this is which door takes which by default.

A server that evaluates source from a caller is exactly the place an unconfined include is a mistake, which is why the tool server denies them until a root says otherwise, and why a path argument is refused until then too.

The teaching topics#

aontu help lists what the binary carries, and aontu help <topic> prints one. Each is staged into both implementations at build time from its source, and both suites hold the staged copy to that source byte for byte, so the answer travels with the binary rather than with a checkout.

aontu help with no topic lists them, aontu --help documents the verbs and their flags, and --format json answers either as an object.

Which implementation has it#

The tool server is the one door with no Go half. Its role there is the embedded API, which carries the same calls.

Related#

• The language server for the protocol surface, the library API in both implementations, and how diagnostics are computed.
• The MCP server for the tools, what each answers, and the confinement the --root posture adds.
• The trust contract for what an include may read, and what a profile confines.
• Exit codes in the errors reference for the verdict every verb carries out of a run.
• Grammar reference for the published grammars and what holds them to the engine.
• Give an agent an entrypoint and wire your editor for the two jobs in recipe form.