Agent Protocol

---
name: agent-protocol
description: Use when producing any agent response
---

# Agent Protocol

Every agent turn writes one contract -- what it was asked, what it found, what it changed, how it ended -- during the turn, not composed at the close. The twelve principles run that arc, ground to close.

## 1. Your contract is the delivery; your final message is only the signal that the turn ended

The gate validates only your persisted contract: one found unfinalized -- or no row at all -- rejects the close however complete your message reads (`_resolve_subagent_stop_gate_full`). The message carries no copy. Address it to the orchestrator, in two lines: the closing state and the `contract_id` -- nothing the row already holds.

## 2. You were born with a contract -- adopt it, do not create another

`# Your Contract` names it on a fresh dispatch, a `# Contract Draft (resumed)` block on a resumed one; your first `gaia contract set/add/fill --draft-id <contract_id>` adopts that draft, and every later call carries `--draft-id` too -- omitted, the CLI targets the most recently touched draft, which is not necessarily yours. Copy `agent_id` verbatim into `agent_status.agent_id`. `AGENT_ID_FORMAT` checks the identifier's shape, never its ownership, so a stray `gaia contract init` mints a rival identity the gate accepts while your real contract is reaped unfinalized; a bare `init` fits exactly one turn, the one that arrived with no contract block at all.

## 3. Ground yourself before acting

Ask what already governs this, in precedence: injected context -> memory, queryable past the sample you were sent -> the code, which outranks any description of it -> the skills -> outside. A skill the code refutes is outranked by it AND is itself a finding: name the skill and the contradicting symbol in `open_gaps`, or the drift outlives your turn to be rediscovered by the next agent that trusts it. A goal often carries a COORDINATE -- a contract id, a memory slug, a brief name -- and `read-map.md`, beside this file, is the verb that opens it. Announce no tool sequence and claim no reach in advance.

That precedence settles claims about existing behavior, not the quality or permission
of that behavior. A normative requirement is not refuted merely because current code
violates it; use `code-standards` for that distinction when producing or judging code.

## 4. Local and reversible work just happens; what goes out into the world is asked once

Commits, files and branches need no signature; operations that leave the local
workspace follow `security-tiers` classification. When that routes to T3,
`subagent-request-approval` owns request construction and `execution` owns the
post-grant lifecycle.

Approval is authority to attempt execution; it is never evidence that execution
happened. When consuming a failed COMMAND_SET result, reconcile and report the
completed indexes, the failed index, and untouched indexes as three distinct
states. A failed COMMAND_SET is terminal/frozen: route any retry or untouched
work through fresh investigation and the approval branch rather than inferring
that the original decision still authorizes it.

## 5. The record is written in flight, at the cadence of what would hurt to lose

If the turn is cut, only what you already wrote exists; everything else survives in the transcript as narrative and dies as evidence. Write a finding the instant re-deriving it would cost more than recording it, and be resumable before any step whose outcome you cannot predict -- a record composed at the close is a second telling, made under the pressure that ends the turn, and it drops fields. Seven lists carry it: `fill` each ONCE (it refuses to discard), `add` extends, `set` replaces, as the evidence arrives, never in one pass at the close: `files_checked`, `patterns_checked`, `commands_run`, `key_outputs`, `verbatim_outputs`, `open_gaps`, and `cross_layer_impacts` -- what your change reached outside the file you were sent to, which no other field records for you. `patterns_checked` is written the moment you SEARCH, not at the close, and above all when the search returns NOTHING: the file you opened comes back in `files_checked` and the command you ran comes back in `commands_run`, but a `grep` that matched zero lines is held by no other field -- unwritten as it happens, the negative it proves is gone.

`report_prose` sits beside these seven lists, never inside them: the why, the discovery order when it explains the result, the purpose frame, the synthesis judgment -- for the orchestrator and the next agent reading the row, never the end user. No evidence here, and no re-narrating a list.

Each `key_outputs` entry is one coordinate or one verifiable claim -- a symbol, an id, a count, a path, a quoted line -- never a paragraph; a paragraph belongs to `report_prose`. `user_facing_summary` is the only channel that reaches the user's display (`agent-contract-handoff`); write it in the plain register when a human will read the result.

## 6. The phase is declared before doing that phase's work

Write `framing`, `investigating`, `planning`, `executing` or `verifying` before that phase's work, not after: reading as "investigating, four files in" rather than as an opaque box decides whether the orchestrator waits or dispatches over the top of you. Write only the phases you entered.

## 7. Every increment closes verified, and fixing starts by going back to the sources

Close each piece verified before starting the next, by result and never by exit code -- failures compound, and separating two entangled ones costs more than verifying the first. On failure, search before retrying: a rejected contract is a problem of form, reissued complete without re-investigating; a rejected operation is a problem of knowledge, and varying the attempt only stacks another state.

## 8. Before declaring yourself blocked, ask

Three doors come first: the answer is in the goal you received, in context or memory you can query, or it is a material choice only the user can make -- then close `NEEDS_INPUT` naming the concrete options. `BLOCKED` is the fourth and costliest: an answered question comes back with your draft unreset, while a block is routed to whoever owns the obstacle, with none of what you found.

## 9. The producer does not verify its own production

Evidence is the command's output, not your assertion about it: a `COMPLETE` needs a `pass` in `evidence_report.verification.result` (`VERIFICATION_RESULT`), which cannot tell a fabricated one from a real one. A plan-task-bound turn cannot seal itself (`_blind_verification_required`); it closes `NEEDS_VERIFICATION` for an independent verifier.

## 10. Every turn closes by declaring a state

`IN_PROGRESS`, `BLOCKED`, `NEEDS_INPUT`, `APPROVAL_REQUEST`, `NEEDS_VERIFICATION`, `COMPLETE`; only `COMPLETE` is terminal, anything outside the six is rejected (`PLAN_STATUS`). Set `agent_status.agent_state` to the closing value, then `gaia contract finalize --draft-id <contract_id>` last: it is the only promotion of that row to a clean close, and it refuses `IN_PROGRESS` (`cmd_finalize`). Add `--plan-task-id <id>` when the turn executes a plan task, and never pass `--session-id` unless the dispatch handed one over -- the born row already carries it, and an invented `unknown` corrupts it.

## 11. Degrading honestly costs less than faking

What you could not do, what you did not verify and what stayed open go in the record: a gap declared gets routed, a gap hidden surfaces later. A complete-looking turn with one invented field is worth nothing.

## 12. Your worktree is scoped to what you touch

A turn about to write to a repository works inside its own worktree, created with `gaia worktree create` and released with `gaia worktree release` at close. It is born at `<workspace>/.project-worktrees/<project>/<id>`, where `<workspace>` is the root `gaia scan` recorded for the workspace that registered the repository -- an unregistered repository is refused, never guessed -- on a branch started from the remote's default branch as just fetched -- never from the live tree's HEAD -- unless `--base` names another commit. A turn that only reads stays on the live tree instead: a worktree is a checkout of one branch, so it cannot see work still uncommitted in the main tree, and an investigation run inside it reports on a state nobody is actually in -- that half carries as much weight as the other. Two turns concurrently on the same repo today share one tree and one index, and that already cost real work here: a mid-turn branch checkout landed one session's commit on the other's branch, and an agent ran `git stash push` believing itself alone in a tree several agents were sharing.

## Where to go next
- `reference.md` -- the argument behind each principle, the state machines, storage and recovery, what the gate rejects; `agent-contract-handoff` -- envelope schema; `examples.md` -- filled envelopes; `read-map.md` -- read verbs. Then `investigation` -> `security-tiers` -> `command-execution` for one operation or `subagent-request-approval` -> `execution` for a COMMAND_SET; orchestrator-side: `orchestrator-present-approval`, `pending-approvals`, `agent-response`.