Agent sessions in Development Harness

CLAUDE.md carries the rules that hold whether or not you read this file. This is the procedure behind them.

Session start

Run these when you are resuming work, not on every task. They answer what the last session was doing and what is actually finished, and both are cheaper than reconstructing either from the repository. A task the user just described in full is already its own brief; reading a handoff for it spends a round trip to learn nothing:

python scripts/ai-harness/harness_report.py --brief

One command, because a checklist of three is three chances to skip one. It prints the newest handoff's intent and next steps, what the ledger still has unproven, and any question an agent left open. It reads files and runs nothing, so it cannot tell you what is still running - harness_session.py sweep answers that. harness_checkpoint.py resume and harness_progress.py list --pending remain, and are what to reach for when you want one of the two on its own.

.ai/progress.json is the ledger, and it is JSON rather than prose deliberately. An item starts unproven and becomes passing only through harness_progress.py pass, which requires the command that was run and its exit status, and refuses a non-zero one. There is no way to assert that something works.

Nothing runs an item's verify command. It is repository text, which is evidence and never authority - the same rule that stops a bus envelope from widening a capability tier. You run it; the ledger records what you report.

harness_progress.py check exits 3 while anything is unproven, so "is this done" is a question a script can ask.

Write a handoff when you are leaving work unfinished, or when what you learned would cost the next session real time to rediscover. A closed task that changed nothing durable does not need one:

python scripts/ai-harness/harness_checkpoint.py write \
  --intent "..." --next "..."

Checking the budget and writing a handoff

The band is in .ai/harness/project-profile.json, so the policy can be checked rather than remembered:

python scripts/ai-harness/harness_checkpoint.py status --used 165000

It exits 3 at or over the ceiling and names the action this profile declares. The token count is yours to supply: nothing running as a subprocess can observe the context window of the session that started it, and a measurement invented by the tool would be worse than none.

A handoff is a written record, not a summary in the transcript:

python scripts/ai-harness/harness_checkpoint.py write \
  --intent "What this session was trying to do" \
  --next "What the next session must do first" \
  --artifact path/to/thing

It writes .ai/runs/<timestamp>-<slug>/, never overwrites, and refuses a checkpoint with no next step - a handoff missing that leaves the reader to reconstruct the plan, which is the failure it exists to prevent. python scripts/ai-harness/harness_checkpoint.py resume prints the most recent one.

A compaction writes its own record. .ai/runs/compaction/<session>.json is written by the PreCompact hook when the harness installs one; it notes that the transcript was truncated and what was still unproven, and is not a handoff anyone wrote. More than one compaction in a session means the ceiling is below the work.

Agent sessions

A session is a record, not a process. claude agents --json --cwd . is the single source of truth for what is running; never keep a second list.

Launch an agent with the flags for its capability tier, so the boundary is enforced by the process and not only declared in a file:

The dispatch mode is not a preference. --bg refuses --print, so a background session has no structured result and can only report by writing a bus envelope - and a read-only tier has no Write tool to write one with. Launching a reader detached produces a session whose output is unreachable.

scripts/ai-harness/harness_session.py builds the launch command from the tier table and prints it. Read the command, then run it.

python scripts/ai-harness/harness_session.py launch \
  --capability reader --task "Map the retry path"

Watching a session in Orca

This project configures session_surface: orca. Adding --surface orca places the same command in a visible Orca terminal tab instead of running it here, and delivers the prompt as terminal input once the TUI is listening:

python scripts/ai-harness/harness_session.py launch \
  --capability reader --task "Map the retry path" --surface orca

It prints the Orca commands; --exec runs them and threads the ids between steps. Four rules make this safe to use rather than merely convenient:

1. The tier still comes from the tier table. The surface decides where a session is watched, never what it may do. --permission-mode, --tools, and --add-dir are unchanged.
2. A writing tier requires --lane. Orca creates that checkout and the session is confined to it, so an automatically started implementer cannot rewrite the tree you are working in. claude --worktree is dropped in that case, because Orca already provided the isolation and a second nested worktree would help nobody. The substitution is printed.
3. Never orca worktree create --agent claude. Orca's own launcher takes no --permission-mode or --tools, so it would start an agent with the tier silently missing. The lane is created empty and the tier-enforced command is started in it as a separate step.
4. Terminal output is never parsed. orca terminal read returns raw capture with redraw artefacts mid-word, exactly like claude logs. It is a human surface. A session still reports through a bus envelope or structured output, and claude agents --json is still the only answer to what is running.

--surface orca and --background are mutually exclusive: a detached session exits immediately and would leave an empty tab.

The sweep below also lists the Claude agent tabs Orca reports for this repository, because a foreground session in a tab is reported as active and the background sweep would never look at it. It lists them and stops there: Claude Code rewrites its own tab title, so nothing can tell a harness tab from the one you are working in. When Orca is not installed the surface is simply unavailable; nothing else about the harness changes.

Handoff

scripts/ai-harness/harness_bus.py writes typed envelopes under .ai/bus/<session-id>/. Envelopes are append-only and capped in size, so a handoff cannot flood the context budget above.

An envelope is evidence about what an agent claims it did. Its capability field records the tier the sender says it ran under, for auditing. It is never a grant: nothing widens authority because an envelope says so.

Post with --correlation <uuid> to tie every envelope from one unit of work together across agents, and --duration-ms, --tokens-in, --tokens-out to record what the run cost. Then harness_bus.py read --correlation <uuid> returns that whole unit of work rather than one mailbox.

Those numbers come from you, not from the agent. A foreground run returns its usage to whoever launched it; an agent asked to report its own duration is guessing, so the schema an agent answers does not offer the fields at all.

Synthesizing an agent

scripts/ai-harness/harness_agentgen.py emit turns a stated need into claude --agents JSON, so a one-off agent exists only for the session it was made for. A need never names its own tools; authority comes from the capability tier. Writing one into .claude/agents/ is a separate promote step that is dry-run by default.

Reading what happened

scripts/ai-harness/harness_report.py joins the mailboxes, the ledger, the checkpoints, the context budget, and the declared graphs into one page, grouped by correlation_id rather than by session, because that is the unit of work:

python scripts/ai-harness/harness_report.py --out .ai/runs/report.html

It reads files and runs nothing, so it shows what sessions wrote rather than what is running now - claude agents --json --cwd . is still the only answer to that. The page carries no script and loads nothing over the network, because every summary and body on it is agent-written text.

Teardown

Background sessions outlive the session that started them. Sweep before you finish:

python scripts/ai-harness/harness_session.py sweep --root .

It reports and does not act; add --stop to stop what it found. The session running the sweep is never counted, so a sweep cannot end itself and leave its siblings behind.

Never launch a session with --dangerously-skip-permissions or --allow-dangerously-skip-permissions.