Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
9.7 KB
Raw Blame

Subagent steering: merged design for #417 and #392

Status: opt-in retained worker history, queue-only feedback and explicit completed-worker continuation are implemented; see ADR 0170. Set retained: true on a direct subagent call, then use its opaque task_id with agent_message (queue only) or subagent_resume (start continuation). Unretained workers preserve their existing behavior. Live background-child feedback also remains available through numeric handles; see ADR 0116. The broader identity unification, aliases, append-only registry, sibling addressing and unified trigger API below remain proposed. The implementation uses owned atomic checkpoints, not the proposed registry/transcript format. Finite-budget continuation across process restart is refused because the live shared budget cannot safely be reconstructed. Historical source inventory below describes the pre-implementation state.

The broader proposal supersedes the separate proposals in #417 (retained, addressable subagents with parent-child steer messaging) and #392 (resumable workers + two-tier steering). Read alongside #393, which supplies the containment rules this design must not violate.

Why these two issues have to merge

They describe one mechanism from two directions. #417 approaches it from addressability (a durable child registry, children reachable by name, messages that steer a running child). #392 approaches it from resumption (a task id returned by spawn, a follow-up that continues the same worker rather than re-briefing a fresh one, and a queue-versus-trigger split on the steering call). Neither is implementable without most of the other: resumption needs an identity that outlives the spawn, and addressing needs somewhere for a completed child's state to live.

Built separately they would produce two id schemes, two registries, and two message paths. The repo already carries the cost of that pattern once, see "Two id schemes today" below.

What actually exists today (verified against the source, 2026-08-06)

This matters because one of the two issues rests on a premise that is false.

Background spawns already have identity and a registry. subagent.zig carries AgentJob and g_agent_jobs: a stable incrementing u32 id, a session-global mutex-guarded list, non-blocking spawn on io.concurrent, and non-destructive polling through the agent_output tool. run_in_background: true hands the model that id immediately. The admission counter is deliberately independent of RunBudget.active to avoid a starvation deadlock, and that reasoning applies unchanged to anything this design adds.

But that registry is in memory only. It dies with the process. The id is a process-local counter, so it is not stable across a resume and cannot address anything after restart.

What persists per subagent is an inspection artifact, not a session. cards.zig:writeSubagentDetail writes .graff/subagents/<id>.md containing id, label, kind, status, elapsed_ms, tools, the task prompt, and the final report. There is no message history, no tool-call record, no provider state.

Correction to #392. That issue states the worker's "transcript already persists under .graff/subagents/, so this is plumbing, not new state." That is not the case. Only the final report persists, as markdown. Resuming a worker "with its accumulated context" requires persisting the worker's actual message history, which is currently discarded when the pool thread finishes. #392 is therefore materially larger than its own estimate, and the history-persistence prerequisite is the first slice, not an afterthought.

Two id schemes today. cards.zig:subagentId produces sa-<3-digit ordinal>-<8 hex>, stable across runs for the same label+prompt+ordinal, and used for inspect links. Background jobs use the u32 counter. These name the same conceptual thing and must be unified before either issue is built, or the registry will key on one and the artifacts on the other.

Depth is already contained. Subagents cannot spawn subagents: execSubagent gates on from_sub, returning "subagents cannot spawn subagents". #393's depth cap is therefore partly enforced already, and this design must not open a hole in it (see Containment).

The collision with #441

#441 (append-only per-session transcript) explicitly excludes subagents, on the stated grounds that their history is "never persisted by design". #392 and #417 require exactly that history to exist.

These are not reconcilable by picking a side, because both defaults are right for their case. A fire-and-forget worker's context is genuinely disposable, and persisting every fan-out worker's full history by default would be a significant and unrequested disk and privacy cost. A worker the parent intends to steer or resume must retain history or the feature is meaningless.

Resolution: retention is opt-in per spawn. The subagent tool gains retained: true. Only retained workers get a transcript under the #441 mechanism. #441 keeps its exclusion as the default and gains one documented exception rather than an unconditional reversal. Unretained workers keep exactly today's behavior, byte for byte.

This also gives the model a real cost signal: retention is a choice with a price, made at spawn time when the parent knows whether a follow-up is likely.

The merged design

Identity

One scheme. The sa-<ordinal>-<hash> form wins, because it is already stable across runs and already appears in persisted artifacts and inspect links. The background-job u32 becomes an internal index into the in-memory registry, not an identity the model ever sees. Every id the model receives, from a foreground spawn, a background spawn, or a resume, is the sa- form.

Names from #417 are an alias, never the identity. A model-chosen name resolves to an id within the family scope. Identity itself stays harness-assigned, which preserves #417's own requirement that sender identity is never model-supplied.

Registry

One append-only JSONL per parent session, last-write-wins on replay, tombstones on delete, following #417's shape. It records id, name alias, status, the worker's transcript ref, and the spawn parameters needed to rehydrate. It lives under the parent's session directory and shares the session lifecycle and sweep that #409 established, the same lifecycle #441 follows. No second cleanup path.

Steering: one primitive, one flag

#392's Codex-derived split (send_message queues only; followup_task queues and triggers a turn) and #417's "steer a running child's turn" unify into a single delivery call with a trigger boolean:

child state trigger: false trigger: true
running queued into the child's next turn, no extra turn cost queued; already turning, so identical to false
idle, retained queued, sits until something triggers rehydrate from registry, deliver, run a turn
completed, unretained rejected with an actionable error rejected with an actionable error

The trigger: false path against a running child is the cheap nudge #392 wants, and the queue-not-await delivery #417 requires. Collapsing to one tool with a flag beats two tools because the expensive case is then visibly the exception.

Delivery is queued and never awaited. This is the hard invariant from #417: mutual sends between two busy agents must not deadlock. It composes with the existing admission design, whose comment already documents why holding an outer slot across a child's lifetime deadlocks. Steering must not introduce a wait that reproduces that bug.

Rehydration

Messaging a completed retained child reconstructs its session from the transcript plus the registry row, then runs one turn. This is where the #441 mechanism earns its second use: the transcript is the rehydration source, not just a grep target.

Containment (#393)

Retention and steering must not become a hole in the depth cap:

  • A retained child is still a child. It cannot spawn or steer, so no cycles.
  • Steering is family-scoped: parent to child, and siblings only within one parent. No addressing across session boundaries.
  • Size limits per message and a small rate bucket per (sender, recipient) pair, per #417.
  • A resumed worker draws from the same #390 budget ledger as the original spawn. It is the same worker continuing, not a new allocation.

Slices

  1. Persist retained worker history. Add retained: true to the subagent tool; route those workers through #441's transcript writer. Nothing addressable yet. This is #392's real prerequisite and the honest first slice.
  2. Unify identity and add the durable registry. Collapse the two id schemes onto sa-, write the append-only registry, expose subagent_list.
  3. Steering. One delivery call with trigger, queued and never awaited, running children only.
  4. Rehydration. Completed retained children resume from transcript, which turns on the idle and completed rows of the table above.

Slices 1 and 2 are worth doing even if 3 and 4 are never built: they make worker output durable and inspectable, which the trajectory and #419 overview work both want independently.

Open questions

  • Retention default for workflow workers specifically. They are the most numerous spawns and the least likely to be steered, so the default should probably stay off even when a parent sets retention for direct spawns.
  • Transcript size cap for workers, which should likely be tighter than a root session's, given fan-out multiplies it.
  • Whether a tombstoned child's transcript is deleted immediately or swept with the session. Immediate deletion is better for privacy, worse for postmortem.