Resumable workers + two-tier steering: task_id to continue a worker's session, queue-vs-trigger message primitives (OpenCode + Codex patterns)

[justrach]

From the orchestration research: OpenCode returns a task_id from every spawn so the parent can RESUME the same worker with its accumulated context for follow-ups instead of re-briefing a fresh agent; Codex splits steering into send_message (queue only, no turn — cheap nudge) vs followup_task (queue + trigger turn — active replan), two tools with two costs.

graff workers today are one-shot: a follow-up question re-pays the whole brief + exploration. Proposal: (1) the subagent tool returns a worker id; a subagent_resume input (id + message) continues that worker's session — its transcript already persists under .graff/subagents/, so this is plumbing, not new state; (2) distinguish queued steering from turn-triggering steering per the Codex split so a nudge doesn't cost a full turn. Live precedent from this very session: the ultracode implementation agent died at a session limit mid-acceptance and was resumed with full context via exactly this mechanism at the orchestrator level — workers deserve the same.

Interacts with: #219 (durable attempt ledger), the #390 budget ledger (a resumed worker draws from the same pool), and the escalation ladder (a failed R1 scout could be resumed with findings-so-far instead of escalating cold to R2).

🤖 Generated with Claude Code

https://claude.ai/code/session_01QbsV84fdmf39Bh2RF8LdPs

[justrach]

Substantial overlap with #417 (retained, addressable subagents with parent-child steer messaging, from the prime-agent analysis): the task_id-to-continue primitive is #417's rehydrate-on-message, and queue-vs-trigger maps to its queued-not-awaited delivery modes. Worth merging the two designs before either is built.

[justrach]

Merged design covering this and #417 is up as #450 (docs/subagent-steering-design.md).

One correction that changes the scope of this issue, flagged here because the estimate rests on it: this issue states the worker's transcript already persists under .graff/subagents/, so resume is "plumbing, not new state". Checking the source, cards.zig:writeSubagentDetail persists id, label, kind, status, elapsed_ms, tools, the task prompt and the final report, as markdown. There is no message history, no tool-call record and no provider state. Resuming a worker with its accumulated context needs history that is currently discarded when the pool thread finishes.

So worker-history persistence is slice 1 of the merged design rather than an implementation detail, and it collides with #441 (which excludes subagents from the append-only transcript by design). The design resolves that with opt-in retained: true per spawn, so #441 keeps its default and unretained workers keep today's behaviour exactly.

The good news is that identity is further along than either issue assumed: background spawns already carry a stable id plus a mutex-guarded registry, just in memory only.

[justrach]

Opted-in workers now retain conversation state and return a stable task identifier. Feedback can be queued without running a turn, and explicit continuation restores prior context while preserving ownership and shared-budget constraints. Fixed on the release branch in fe6790f. Broader registry and sibling-addressing work remains tracked separately.