1# Resident subagents
2
3> **V0.x breaking change:** zut no longer supports subprocess subagent state.
4> Previous state is ignored rather than read or migrated; remove it when you
5> no longer need it. Existing child jobs are never resumed.
6
7> **V0.x breaking change:** the separate `subagent_spawn`, `subagent_status`,
8> `subagent_stop`, and `subagent_resume` tools are replaced by one `subagent`
9> tool with `spawn`, `status`, `stop`, and `resume` actions.
10> `--tools subagent_spawn` no longer selects anything; use
11> `--tools subagent:spawn`, or bare `--tools subagent` for every action.
12> Under `--no-yolo`, "always allow" is remembered per action
13> (`subagent:status` and `subagent:spawn` are separate grants), so approving a
14> read-only `status` call never pre-approves `spawn`, `stop`, or `resume`.
15
16Subagents are independent `core.Agent` conversations resident in the same zut
17process as their parent. A child has a stable, private session identity, its own
18provider client and tool registry, a cancellation boundary, and an authoritative
19journal. Starting a child never launches another zut executable.
20
21## Profiles
22
23Profiles are Markdown files discovered from `~/.agents/agents/*.md` and paths
24in `ZUT_AGENT_PROFILES`. They are inputs only; zut does not execute them.
25
26```markdown
27---
28name: reviewer
29description: Read-only code reviewer
30tools: [read, grep]
31model: openai-codex/gpt-5.6-luna
32thinking: high
33systemPromptMode: replace
34inheritProjectContext: false
35inheritSkills: false
36fastMode: false
37---
38
39Inspect the requested scope and report evidence-backed findings.
40```
41
42`tools` is a capability boundary. An omitted value inherits the child-safe
43catalogue, `tools: []` grants no tools, and an explicit list replaces the
44default. The child-safe catalogue contains only tools offered by the parent
45that are also available in the resolved child runtime; parent-only scheduling
46and extension tools are never inherited. Names unavailable to the child
47(including host-only extensions) and tools denied by `subagents.allowed_tools`
48are omitted from an explicit list; they never grant the child additional
49access. `model`, `provider`, `thinking`,
50the prompt mode, project/skill inheritance, and `fastMode` are resolved before
51the child is accepted. Spawn-level model, provider, reasoning, and fast-mode
52values take precedence where supplied.
53
54Children are always fresh conversations: they receive the delegated task and
55resolved host/profile context, never the parent transcript or hidden reasoning.
56They cannot recursively create more children.
57
58## Lifecycle and persistence
59
60The manager records each accepted child under its managed state root:
61
62```text
63subagents/<child-id>/
64  transcript.jsonl  # accepted turns, finalized messages, and compaction checkpoints
65  owner.lock        # host-ownership coordination; do not modify or remove
66  .transcript-backup-* # retained private pre-repair transcript, when repaired
67  metadata.json     # rebuildable bounded state
68  result.json       # latest outcome, final summary, artifacts
69  patch.diff        # optional worktree capture
70```
71
72Acceptance is durable before the `subagent` tool's `spawn` action reports
73success. Finalized user, assistant, tool-call, and tool-result messages are
74journaled; streamed deltas and hidden reasoning are not exposed as ordinary
75history. A tool call is stored before execution and reconciliation repairs
76incomplete call/result pairs. A context-overflow recovery appends one
77`child.compacted` checkpoint carrying the replacement transcript; resume
78starts from the newest checkpoint, while the paged history view still shows
79everything appended before it.
80
81All children stop when the host exits. On the next start, queued or running
82turns are marked `interrupted`; zut never replays their task. Resume only with
83an explicit new prompt through the `subagent` tool's `resume` action, the
84child-session composer, or `/subagents resume <id> <prompt>`.
85
86Multiple zut processes may share a state root. Each resident journal has one
87host owner at a time. A process that finds a child owned elsewhere reports it
88as such and does not inspect, recover, or modify its transcript. Resume that
89child from its owning host or after the owner exits. On a subsequent safe
90reconciliation, zut repairs only the known legacy false-recovery sequence; it
91leaves any ambiguous journal corruption untouched. A repair retains the
92pre-repair transcript as `.transcript-backup-*`; it can contain private session
93data and is intentionally not removed automatically.
94
95The `subagent` tool's `status` action reports `owned_elsewhere: true` when
96another process owns a child. The field is omitted when false. A foreign-owned
97child cannot be resumed, or have its history or result read, from this process.
98
99The global scheduler admits the oldest eligible accepted prompt, runs at most
100one turn for each child, and defaults to six concurrent turns. Set
101`subagents.max_concurrent` to a positive limit to override it. Queueing is
102unlimited by default; a positive `subagents.queue_timeout` cancels an accepted
103prompt that has not received a slot and records its terminal failure durably.
104`subagents.allowed_tools` is an allowlist for child-visible tools and
105`subagents.allowed_roots` limits eligible child workspaces. Resident children
106have no cumulative token budget and no child-only step cap: a child inherits
107the parent's resolved limit, including the unlimited default. A turn is bounded
108by the provider context window, with one compaction recovery, and by an
109explicit parent `--max-steps`. Removed legacy
110settings, including `tui_subagent_position` and `subagents.budget_ratio`, are
111ignored. Resident journals written by older versions are read with explicit
112translation (an old `budget_exhausted` outcome reconciles as failure) or, for
113unknown versions, left untouched on disk and excluded from automatic
114discovery. Incompatible journals cannot be resumed; start a new child
115instead. Other journal recovery errors are still reported.
116
117Compatibility notes: new journals write version 3 and carry no budget
118fields, baselines, or exhaustion states. Version 2 archives are read with
119explicit translation and their transcripts are never rewritten by
120translation. `result.json` keeps a deprecated `handoff` field that stays
121empty for new results and remains readable for archives. The `subagent` tool's
122`status` action no longer exposes `budget` or `budget_source` fields.
123
124### Context reminders
125
126When a child's last-turn prompt reaches 85%, 90%, or 95% of its model context
127window, the runner injects a non-blocking reminder into the next provider
128request:
129
130```text
131Context usage is at NN% of the model window. Finish the current task, report
132results, limits, and remaining verifications, and do not start broad new work.
133```
134
135Each band fires at most once per child runner and reminders never block a turn.
136A jump straight to a higher band delivers one reminder for that band, and usage
137that falls does not re-deliver a band. Reminders travel as developer context in
138the live request; the durable transcript keeps only finalized history. Usage is
139the last-turn prompt size (input plus cache read/write tokens) against the
140resolved context window; an unknown window never triggers a reminder. The
141per-turn gauge resets when the host restarts and when a recovery compacts the
142context, so neither event reports a stale percentage. The band ladder itself
143advances at most once per child runner: a restart starts a fresh ladder, while a
144compacted child is reminded again only when usage reaches a higher band.
145
146### Context-overflow recovery
147
148A provider request that exceeds the model context window ends the turn. When
149the transcript holds at least four messages, the child recovers once per turn:
150it compacts the transcript, keeps the two most recent messages verbatim,
151journals the replacement as a `child.compacted` record, and continues the same
152turn. A compaction or persistence failure restores the pre-compaction
153transcript and fails the turn, and a second overflow stays terminal. Recovery
154never replenishes an explicit parent `--max-steps`: when the allowance is
155already spent, the checkpoint is still written for a later resume, but the turn
156is not continued.
157
158Explicit resume replays the newest checkpoint instead of the full append-only
159log. The history views (`/subagents logs`, `HistoryPage`, `subagent://` refs)
160still show the append-only log, including pre-compaction records. A build that
161predates checkpoint support cannot resume such a child correctly; downgrading
162is unsupported.
163
164The summarization request itself can be rejected when a single oversized
165message leaves nothing to summarize away. The turn then fails with the original
166provider error and no checkpoint is written, so the child keeps failing on
167resume until its transcript shrinks. Recovery is a best effort, not a
168guarantee.
169
170Retrieve the saved result without executing a model:
171
172```json
173{"action":"status","agent_id":"<child-id>","include_result":true}
174```
175
176Pass this to the `subagent` tool's `status` action, then reconcile the history
177and artifacts before repeating any side effects. The `subagent` tool's explicit
178`resume` action after a terminal failure continues the retained session,
179workspace, and cumulative cost. It does not automatically retry the task.
180Ordinary follow-ups continue the existing session.
181
182`required: true` makes a delegated result an obligation of the parent turn.
183Failed, cancelled, and interrupted required work remains
184unresolved until an explicit successful follow-up. Reading a saved result or
185accepting a recovery prompt does not satisfy the obligation. A host restart never
186retries it automatically.
187
188## Delegation ownership
189
190Interactive proactive delegation keeps the primary agent on the critical path.
191Process start says nothing about the task, and the workers it needs only become
192knowable once the user states the request. Routing therefore happens then: the
193reply that starts the work names the parts the primary keeps on the critical
194path and the profile that owns each delegable part, before it implements or
195spawns anything. It states plainly when nothing is worth delegating rather than
196forcing a worker. The routing guidance is part of the prompt only when
197launch-time policy exposes the spawn action.
198Before spawning, it selects useful local work and delegates only a concrete,
199bounded sidecar with a non-overlapping question, responsibility, package, or
200file set. Immediate blockers and tightly coupled work stay local. While a child
201is active, it owns that scope; the primary continues only its preselected
202independent work instead of repeating the investigation, review, testing, or
203implementation. If an explicit user request or active workflow hands blocking
204work to a child, the primary yields for the completion update. Once a worktree
205child succeeds, the primary may apply and verify its captured patch without
206redoing the delegated task.
207
208Explicit headless `--orchestrate` remains manager-only. Its primary divides the
209request into disjoint worker scopes, coordinates active children, and yields
210rather than implementing or reproducing delegated work. Children do not inherit
211the parent's strict orchestrator role. Headless orchestration waits for every
212accepted child before continuing its completion wave; `required: true`
213additionally creates a durable obligation. When proactive
214interactive delegation cannot spawn because of launch-time policy, the primary
215continues locally; a strict headless orchestrator instead reports the missing
216required capability.
217
218## Tools and slash commands
219
220The model-facing tool keeps one logical name and four actions, selected by its
221`action` argument. Launch-time gating is per action: `--tools subagent` grants
222every action, `--tools subagent:<action>` grants one, and `--no-tools` disables
223all of them.
224
225- `subagent` accepts an `action` of `spawn`, `status`, `stop`, or `resume`.
226  - `spawn` accepts `task`, optional `agent`, `model` and `provider`,
227    `reasoning`, `fast_mode`, `required`, `wait`, and `isolation` (`shared` or
228    `worktree`).
229    `wait` is an explicit whole-second value from 1 through 300; when omitted,
230    spawning returns immediately. A timed-out wait leaves the
231    accepted child active, whether it is queued or running. Do not retry that
232    task until it reaches a terminal failure, cancellation, or interruption. It
233    returns a logical `subagent://<id>` reference.
234  - `status` accepts optional `agent_id` and `include_result`, and returns
235    bounded current state for one child or the current set immediately. With
236    `agent_id` and `include_result: true`, it also reads the saved terminal
237    result without model execution. Without this option it remains
238    metadata-only; foreign-owned results cannot be read. Result-read errors
239    distinguish foreign ownership, a missing saved result, and permission
240    denial without exposing filesystem paths or saved content.
241  - `stop` accepts `agent_id` and stops one live child.
242  - `resume` accepts `agent_id`, `prompt`, and optional `wait`. `prompt` is an
243    explicit follow-up prompt for an existing child. After a terminal failure,
244    inspect the saved result before resuming; resume continues the retained
245    session. `wait` uses the same 1–300 second bound as `spawn` and waits for
246    the accepted follow-up turn, returning its outcome or reporting the timeout
247    while the child stays active.
248
249Child execution started by the `subagent` tool's `spawn` or `resume` action is
250asynchronous unless it receives an explicit `wait` value. For an unwaited call,
251completion arrives through the host’s typed completion update; the `subagent`
252tool's `status` action returns immediately and does not wait for completion. Do
253not use sleep loops, repeated status calls, journal files, or terminal UI
254inspection as a completion signal.
255In interactive mode, a result received while the primary is busy enters the
256visible **sliding in** queue and reaches the model at its next safe boundary,
257without interrupting a model request or tool call and without waiting for other
258children. Results already queued are not repeated when the parent turn ends.
259Undelivered results remain queued after a provider or compaction error for the
260next turn; they do not automatically retry the failed request. Explicit
261cancellation clears pending queue entries. The queue is in memory, while the
262child’s saved result remains available through the `subagent` tool's `status`
263action.
264When the primary is idle, each child completion immediately starts the next
265parent turn instead of waiting for its siblings. The host update names the
266finished child and lists sibling agent IDs that are still running. A completion
267that arrives while that parent turn is active slides into its queue. Headless
268orchestration still waits for every accepted child before its next parent turn.
269Successful completions include the final visible assistant summary, capped at
270256 KiB; open the child session for the complete durable transcript.
271
272`/subagents` opens the resident-child list, ordered by the latest state change.
273Each row leads with the profile (or model), shows a human terminal state such
274as `completed`, a relative update time, and a short ID. Press Down from the
275main composer to open this list without clearing a draft when a child exists.
276Use arrows and Enter to open a child session; `/subagents new <task>` creates a child; `/subagents logs <id>`
277opens its history; `/subagents result <id>` shows the bounded final summary;
278`kill <id>` stops it; and `resume <id> <prompt>` continues it.
279
280The child session uses the same transcript renderer as the main session.
281Recent history is bounded and loaded asynchronously; PgUp asks for an older
282page. Up/Down preserves the current reading position, and PgDn returns to the
283live tail after unread updates accumulate. The screen combines durable finalized
284history with an immutable in-memory projection of the active turn. Enter submits
285the local composer only after the manager durably accepts it; Esc closes the session. History may contain task
286text, tool arguments, tool results, and source-derived output, so treat it as
287private local session data.
288
289## Worktrees and references
290
291Shared children use the host working directory. With `isolation: "worktree"`,
292zut prepares a detached Git worktree and captures a patch and changed-file list
293on successful completion or non-cancelled failure. Failed turns retain
294partial work in the worktree, along with any captured patch and changed-file
295list. zut never applies a captured patch automatically. Failed or interrupted
296worktrees are retained for inspection; an idle successful worktree is cleaned
297when its child is explicitly stopped.
298
299Use the `subagent` tool's `status` action with `agent_id` and
300`include_result: true` to retrieve the saved result, `changed_files`, and
301`patch_ref` when a patch was captured. The
302patch bytes are stored in `subagents/<child-id>/patch.diff` under the managed
303state root shown above; logical references are identifiers, not filesystem
304paths. Inspect the retained worktree and patch before resuming or applying
305partial changes.
306
307New terminal journal records also save the capture metadata, so reconciliation
308can restore it if `result.json` is missing or corrupt. Older records remain
309readable, but cannot reconstruct artifact metadata they never recorded.
310
311Logical references avoid exposing runtime paths:
312
313```text
314subagent://<id>
315subagent://<id>/history
316subagent://<id>/result
317subagent://<id>/patch
318```
319
320## Provider caching
321
322Each main and child conversation sends a stable logical session ID and a new
323turn ID per accepted prompt to the provider layer. Provider adapters decide
324whether and how to use them: OpenAI/Codex translates a supported stable session
325into its cache key and routing header, while other adapters preserve deterministic
326request input and use only cache controls their provider/model/endpoint supports.
327An OpenAI-compatible wire shape is not itself evidence that a cache extension
328or transport feature is available. Models continue through their declared
329provider transport; a transport change must not change the logical session or
330turn identity used by the provider request.