Resident subagents
V0.x breaking change: zut no longer supports subprocess subagent state.
Previous state is ignored rather than read or migrated; remove it when you
no longer need it. Existing child jobs are never resumed.
Subagents are independent core.Agent conversations resident in the same zut
process as their parent. A child has a stable, private session identity, its own
provider client and tool registry, a cancellation boundary, and an authoritative
journal. Starting a child never launches another zut executable.
Profiles
Profiles are Markdown files discovered from ~/.agents/agents/*.md, paths in
ZUT_AGENT_PROFILES, and the ~/.pi/agent/agents/*.md compatibility discovery
location. They are inputs only; zut does not execute them.
---
name: reviewer
description: Read-only code reviewer
tools: [read, grep]
model: openai-codex/gpt-5.6-luna
thinking: high
systemPromptMode: replace
inheritProjectContext: false
inheritSkills: false
fastMode: false
---
Inspect the requested scope and report evidence-backed findings.
tools is a capability boundary. An omitted value inherits the child-safe
catalogue, tools: [] grants no tools, and an explicit list replaces the
default. Names unavailable to the child (including host-only extensions) and
tools denied by subagents.allowed_tools are omitted from an explicit list;
they never grant the child additional access. model, provider, thinking,
the prompt mode, project/skill inheritance, and fastMode are resolved before
the child is accepted. A spawn-level model, provider, reasoning, or fast-mode
override takes precedence where supplied.
Children are always fresh conversations: they receive the delegated task and
resolved host/profile context, never the parent transcript or hidden reasoning.
They cannot recursively create more children.
Lifecycle and persistence
The manager records each accepted child under its managed state root:
subagents/<child-id>/
transcript.jsonl # authoritative accepted turns and finalized messages
owner.lock # host-ownership coordination; do not modify or remove
.transcript-backup-* # retained private pre-repair transcript, when repaired
metadata.json # rebuildable bounded state
result.json # latest state plus a bounded final assistant summary
patch.diff # optional worktree capture
Acceptance is durable before subagent_spawn reports success. Finalized user,
assistant, tool-call, and tool-result messages are journaled; streamed deltas
and hidden reasoning are not exposed as ordinary history. A tool call is stored
before execution and reconciliation repairs incomplete call/result pairs.
All children stop when the host exits. On the next start, queued or running
turns are marked interrupted; zut never replays their task. Resume only with
an explicit new prompt through subagent_resume, the child-session composer,
or /subagents resume <id> <prompt>.
Multiple zut processes may share a state root. Each resident journal has one
host owner at a time. A process that finds a child owned elsewhere reports it
as such and does not inspect, recover, or modify its transcript. Resume that
child from its owning host or after the owner exits. On a subsequent safe
reconciliation, zut repairs only the known legacy false-recovery sequence; it
leaves any ambiguous journal corruption untouched. A repair retains the
pre-repair transcript as .transcript-backup-*; it can contain private session
data and is intentionally not removed automatically.
subagent_status reports owned_elsewhere: true when another process owns a
child. The field is omitted when false. A foreign-owned child cannot be resumed,
or have its history or result read, from this process.
The global scheduler admits the oldest eligible accepted prompt, runs at most
one turn for each child, and defaults to six concurrent turns. Set
subagents.max_concurrent to a positive limit to override it. Queueing is
unlimited by default; a positive subagents.queue_timeout cancels an accepted
prompt that has not received a slot and records its terminal failure durably.
subagents.allowed_tools is an allowlist for child-visible tools and
subagents.allowed_roots limits eligible child workspaces. Removed legacy
settings, including tui_subagent_position, are ignored.
required: true makes a delegated result an obligation of the parent turn.
Failed, cancelled, and interrupted required work remains unresolved until an
explicit successful follow-up. A host restart never retries it automatically.
The model-facing tools retain their logical names:
subagent_spawn accepts task, optional agent, model and provider,
reasoning, fast_mode, required, and isolation (shared or
worktree). It returns a logical subagent://<id> reference.subagent_status returns bounded state for one child or the current set.subagent_stop stops one live child.subagent_resume accepts an explicit follow-up prompt for an existing child.
These calls are asynchronous. Completion arrives through the host’s typed
completion update, not process polling. Do not use sleep loops, repeated
status calls, journal files, or terminal UI inspection as a completion signal.
Successful completions include the final visible assistant summary, capped at
256 KiB; open the child session for the complete durable transcript.
/subagents opens the resident-child list, ordered by the latest state change.
Each row leads with the profile (or model), shows a human terminal state such
as completed, a relative update time, and a short ID. Press Down from the
main composer to open this list without clearing a draft when a child exists.
Use arrows and Enter to open a child session; /subagents new <task> creates a child; /subagents logs <id>
opens its history; /subagents result <id> shows the bounded final summary;
kill <id> stops it; and resume <id> <prompt> continues it.
The child session uses the same transcript renderer as the main session.
Recent history is bounded and loaded asynchronously; PgUp asks for an older
page. Up/Down preserves the current reading position, and PgDn returns to the
live tail after unread updates accumulate. The screen combines durable finalized
history with an immutable in-memory projection of the active turn. Enter submits
the local composer only after the manager durably accepts it; Esc closes the session. History may contain task
text, tool arguments, tool results, and source-derived output, so treat it as
private local session data.
Worktrees and references
Shared children use the host working directory. With isolation: "worktree",
zut prepares a detached Git worktree, captures a patch and changed-file list on
successful completion, and never applies that patch automatically. Failed or
interrupted worktrees are retained for inspection; an idle successful worktree
is cleaned when its child is explicitly stopped.
Logical references avoid exposing runtime paths:
subagent://<id>
subagent://<id>/history
subagent://<id>/result
subagent://<id>/patch
Provider caching
Each main and child conversation sends a stable logical session ID and a new
turn ID per accepted prompt to the provider layer. Provider adapters decide
whether and how to use them: OpenAI/Codex translates a supported stable session
into its cache key and routing header, while other adapters preserve deterministic
request input and use only cache controls their provider/model/endpoint supports.
An OpenAI-compatible wire shape is not itself evidence that a cache extension
or transport feature is available. Models continue through their declared
provider transport; a transport change must not change the logical session or
turn identity used by the provider request.
source
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
7Subagents are independent `core.Agent` conversations resident in the same zut
8process as their parent. A child has a stable, private session identity, its own
9provider client and tool registry, a cancellation boundary, and an authoritative
10journal. Starting a child never launches another zut executable.
11
12## Profiles
13
14Profiles are Markdown files discovered from `~/.agents/agents/*.md`, paths in
15`ZUT_AGENT_PROFILES`, and the `~/.pi/agent/agents/*.md` compatibility discovery
16location. They are inputs only; zut does not execute them.
17
18```markdown
19---
20name: reviewer
21description: Read-only code reviewer
22tools: [read, grep]
23model: openai-codex/gpt-5.6-luna
24thinking: high
25systemPromptMode: replace
26inheritProjectContext: false
27inheritSkills: false
28fastMode: false
29---
30
31Inspect the requested scope and report evidence-backed findings.
32```
33
34`tools` is a capability boundary. An omitted value inherits the child-safe
35catalogue, `tools: []` grants no tools, and an explicit list replaces the
36default. Names unavailable to the child (including host-only extensions) and
37tools denied by `subagents.allowed_tools` are omitted from an explicit list;
38they never grant the child additional access. `model`, `provider`, `thinking`,
39the prompt mode, project/skill inheritance, and `fastMode` are resolved before
40the child is accepted. A spawn-level model, provider, reasoning, or fast-mode
41override takes precedence where supplied.
42
43Children are always fresh conversations: they receive the delegated task and
44resolved host/profile context, never the parent transcript or hidden reasoning.
45They cannot recursively create more children.
46
47## Lifecycle and persistence
48
49The manager records each accepted child under its managed state root:
50
51```text
52subagents/<child-id>/
53 transcript.jsonl # authoritative accepted turns and finalized messages
54 owner.lock # host-ownership coordination; do not modify or remove
55 .transcript-backup-* # retained private pre-repair transcript, when repaired
56 metadata.json # rebuildable bounded state
57 result.json # latest state plus a bounded final assistant summary
58 patch.diff # optional worktree capture
59```
60
61Acceptance is durable before `subagent_spawn` reports success. Finalized user,
62assistant, tool-call, and tool-result messages are journaled; streamed deltas
63and hidden reasoning are not exposed as ordinary history. A tool call is stored
64before execution and reconciliation repairs incomplete call/result pairs.
65
66All children stop when the host exits. On the next start, queued or running
67turns are marked `interrupted`; zut never replays their task. Resume only with
68an explicit new prompt through `subagent_resume`, the child-session composer,
69or `/subagents resume <id> <prompt>`.
70
71Multiple zut processes may share a state root. Each resident journal has one
72host owner at a time. A process that finds a child owned elsewhere reports it
73as such and does not inspect, recover, or modify its transcript. Resume that
74child from its owning host or after the owner exits. On a subsequent safe
75reconciliation, zut repairs only the known legacy false-recovery sequence; it
76leaves any ambiguous journal corruption untouched. A repair retains the
77pre-repair transcript as `.transcript-backup-*`; it can contain private session
78data and is intentionally not removed automatically.
79
80`subagent_status` reports `owned_elsewhere: true` when another process owns a
81child. The field is omitted when false. A foreign-owned child cannot be resumed,
82or have its history or result read, from this process.
83
84The global scheduler admits the oldest eligible accepted prompt, runs at most
85one turn for each child, and defaults to six concurrent turns. Set
86`subagents.max_concurrent` to a positive limit to override it. Queueing is
87unlimited by default; a positive `subagents.queue_timeout` cancels an accepted
88prompt that has not received a slot and records its terminal failure durably.
89`subagents.allowed_tools` is an allowlist for child-visible tools and
90`subagents.allowed_roots` limits eligible child workspaces. Removed legacy
91settings, including `tui_subagent_position`, are ignored.
92
93`required: true` makes a delegated result an obligation of the parent turn.
94Failed, cancelled, and interrupted required work remains unresolved until an
95explicit successful follow-up. A host restart never retries it automatically.
96
97## Tools and slash commands
98
99The model-facing tools retain their logical names:
100
101- `subagent_spawn` accepts `task`, optional `agent`, `model` and `provider`,
102 `reasoning`, `fast_mode`, `required`, and `isolation` (`shared` or
103 `worktree`). It returns a logical `subagent://<id>` reference.
104- `subagent_status` returns bounded state for one child or the current set.
105- `subagent_stop` stops one live child.
106- `subagent_resume` accepts an explicit follow-up prompt for an existing child.
107
108These calls are asynchronous. Completion arrives through the host’s typed
109completion update, not process polling. Do not use sleep loops, repeated
110status calls, journal files, or terminal UI inspection as a completion signal.
111Successful completions include the final visible assistant summary, capped at
112256 KiB; open the child session for the complete durable transcript.
113
114`/subagents` opens the resident-child list, ordered by the latest state change.
115Each row leads with the profile (or model), shows a human terminal state such
116as `completed`, a relative update time, and a short ID. Press Down from the
117main composer to open this list without clearing a draft when a child exists.
118Use arrows and Enter to open a child session; `/subagents new <task>` creates a child; `/subagents logs <id>`
119opens its history; `/subagents result <id>` shows the bounded final summary;
120`kill <id>` stops it; and `resume <id> <prompt>` continues it.
121
122The child session uses the same transcript renderer as the main session.
123Recent history is bounded and loaded asynchronously; PgUp asks for an older
124page. Up/Down preserves the current reading position, and PgDn returns to the
125live tail after unread updates accumulate. The screen combines durable finalized
126history with an immutable in-memory projection of the active turn. Enter submits
127the local composer only after the manager durably accepts it; Esc closes the session. History may contain task
128text, tool arguments, tool results, and source-derived output, so treat it as
129private local session data.
130
131## Worktrees and references
132
133Shared children use the host working directory. With `isolation: "worktree"`,
134zut prepares a detached Git worktree, captures a patch and changed-file list on
135successful completion, and never applies that patch automatically. Failed or
136interrupted worktrees are retained for inspection; an idle successful worktree
137is cleaned when its child is explicitly stopped.
138
139Logical references avoid exposing runtime paths:
140
141```text
142subagent://<id>
143subagent://<id>/history
144subagent://<id>/result
145subagent://<id>/patch
146```
147
148## Provider caching
149
150Each main and child conversation sends a stable logical session ID and a new
151turn ID per accepted prompt to the provider layer. Provider adapters decide
152whether and how to use them: OpenAI/Codex translates a supported stable session
153into its cache key and routing header, while other adapters preserve deterministic
154request input and use only cache controls their provider/model/endpoint supports.
155An OpenAI-compatible wire shape is not itself evidence that a cache extension
156or transport feature is available. Models continue through their declared
157provider transport; a transport change must not change the logical session or
158turn identity used by the provider request.