You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Each successful turn returns a session value with `id`, `output`, and `generation`. `subagent` creates an ID at generation 1. `prompt` keeps that ID and increments its generation. `fork` creates a different ID whose generation is one greater than the supplied source value; it does not advance the source session. `subagents({})` returns active sessions in ID order. A session whose initial prompt is still in progress appears as `{ id, status: "starting" }`; it can be closed by ID but cannot be prompted or forked until the initial `subagent` call returns its complete handle. Completed sessions retained for reuse appear as their latest values. Close a session with either `close(value)` or `close({ id: value.id })`; the latter is useful when only an ID is available. Closing an unknown ID fails with `unknown subagent session`. Kit sends ACP `session/close` when the harness advertises it. A standalone process without that capability is terminated when its handle is dropped. If native-fork siblings share a process and the harness cannot close one logical session, `close` fails rather than claiming success or disrupting the siblings.
26
+
Each successful turn returns a session value with `id`, `name`, `output`, and `generation`. `subagent` creates an ID at generation 1. `prompt` keeps that ID and name while incrementing its generation. `fork` creates a different ID and uses its own preferred or fallback name; its generation is one greater than the supplied source value, and it does not advance the source session. Close a session with either `close(value)` or `close({ id: value.id })`; the latter is useful when only an ID is available. Closing an unknown ID fails with `unknown subagent session`. Kit sends ACP `session/close` when the harness advertises it. A standalone process without that capability is terminated when its handle is dropped. If native-fork siblings share a process and the harness cannot close one logical session, `close` fails rather than claiming success or disrupting the siblings.
23
27
24
28
Always pass the latest completed value back to `prompt` or `fork`. Reusing an older value fails with `stale subagent generation N; current generation is M`. This prevents two continuations from silently racing on one session. Calls on an individual ACP session are serialized, while separate forked sessions can be prompted concurrently.
25
29
26
-
The optional `harness` and `model` arguments belong only on `subagent`. `harness` overrides the user's configured harness preference. `model` selects an exact model value ID advertised by that harness through its ACP session configuration, or a model alias configured for that harness. Omit either argument to retain the configured preference. `prompt` and `fork` retain the original session's harness and model. An explicit model fails before the first prompt if the harness does not advertise a selectable `model` option or rejects the value.
30
+
The optional `name` argument is preferred on `subagent` and `fork`; `prompt` has no naming input and preserves the session name. The optional `harness` and `model` arguments belong only on `subagent`. `harness` overrides the user's configured harness preference. `model` selects an exact model value ID advertised by that harness through its ACP session configuration, or a model alias configured for that harness. Omit either argument to retain the configured preference. `prompt` and `fork` retain the original session's harness and model. An explicit model fails before the first prompt if the harness does not advertise a selectable `model` option or rejects the value.
31
+
32
+
## Inspect display names
33
+
34
+
The calling model should give each new `subagent` and `fork` a concise role-oriented display name based on its task, such as `Round 2 Implementer` or `Reviewer`. This uses the model already making the tool call; Kit does not make a separate naming request. The name is display metadata and never changes the prompt sent to the child. Omitting `name`, or supplying an invalid name, uses the lowest available `Agent N` label.
35
+
36
+
Kit trims preferred names and accepts 1–32 bytes of printable ASCII. Names compare case-insensitively among one parent's direct live children; clashes receive the lowest available numeric suffix, with the base shortened as needed to stay within 32 bytes. The immutable `s-…` ID remains authoritative; names never select handles.
37
+
38
+
A name is reserved when creation starts. A failed creation releases it; otherwise the reservation survives starting, working, idle, and reusable failures until `close` or terminal retirement. Nested Kit processes allocate independently, so separate descendant branches can generate duplicate visible names in the agent roster even though each parent keeps its direct-child names unique.
39
+
40
+
Use `subagents({})` to inspect live direct children. Each row contains `id`, `name`, `status`, `generation`, and the bounded current task summary. Closed and terminally retired children are omitted.
27
41
28
42
## Require structured JSON output with `output_schema`
|`Ctrl+K`| Kill the selected running background tool call; otherwise delete to the end of the editor line |
42
42
|`Ctrl+O`, or click a tool card | Fold or unfold raw tool output |
43
43
|`Ctrl+Y`| Copy the latest agent response as original Markdown |
@@ -73,9 +73,19 @@ Press `Command+B` to detach the newest running foreground top-level compose call
73
73
74
74
At an idle, non-empty editor, `Ctrl+C` clears the prompt instead of unexpectedly discarding it and quitting in one step; press it again with the empty editor to quit.
75
75
76
+
## Monitor subagents in the agent roster
77
+
78
+
Press `Ctrl+R` or enter the exact local command `/agents` while idle to toggle the agent roster. The roster keeps its own visibility and scroll position. The roster covers every subagent observable to the current top-level Kit process tree, whether its call is foreground or background and regardless of the focused transcript block or tool call. Direct children are tree roots, and nested Kit descendants appear immediately beneath their parent at arbitrary depth in an always-expanded tree. Siblings retain lifecycle/creation/ID ordering within each parent, so an active child remains grouped beneath an idle parent instead of moving across subtrees. A descendant whose parent event has not arrived temporarily appears as a root with `Name · via Parent` and automatically reparents when the parent arrives. Generic ACP has no portable child-session enumeration, so agents created privately inside a generic harness cannot appear unless the harness forwards compatible Kit runtime events.
79
+
80
+
Each row uses two lines, with tree connectors and indentation continuing across both. The first contains a glyph and display name; the second contains the bounded task summary and a duration right-aligned to the panel's inner edge. When starting or forking a subagent, the parent model preferably supplies a concise role-oriented name such as `Round 2 Implementer` or `Reviewer`; omitted or invalid names fall back to `Agent N`, and case-insensitive sibling collisions receive a numeric suffix. Task text truncates before the reserved duration column. The glyph palette is yellow `Pulse::Child` for `starting`, cyan `Pulse::Tool` for `working`, and dim `○` for ordinary or successful `idle`. A failed reusable idle row shows a red `✗` for four seconds after its failure timestamp, then returns to dim `○`; a failed terminal or removed tombstone shows the red `✗` for four seconds, then its row is deleted. Active durations update on animation ticks, freeze when the generation becomes idle or fails, and restart for a later prompt.
81
+
82
+
A fixed footer remains visible while rows scroll, for example `3 agents · 2 working · 1 idle`; it includes the total and only nonzero `starting`, `working`, and `idle` buckets. Foreground and background are not separate buckets. Footer accounting remains lifecycle-based during the four-second grace: reusable failures count as idle immediately, while closed and terminally retired handles leave the live total immediately even while a tombstone remains visible. Idle rows remain until their handles are closed.
83
+
84
+
When the agent roster is visible, terminals at least 108 columns wide show the transcript beside a fixed 46-column panel. Terminals at most 107 columns wide stack the transcript and roster with a 55/45 height split. Hiding the roster restores the transcript to the full main area.
85
+
76
86
## Manage sessions and compact from the TUI
77
87
78
-
The TUI handles `/new`, `/resume`, `/sessions`, `/close`, `/model`, and `/effort` as exact local slash-command tokens. It also discovers agent commands through ACP and highlights them without interpreting them locally:
88
+
The TUI handles `/new`, `/resume`, `/sessions`, `/close`, `/model`, `/effort`, and `/agents` as exact local slash-command tokens. It also discovers agent commands through ACP and highlights them without interpreting them locally:
79
89
80
90
```text
81
91
/new
@@ -88,9 +98,10 @@ The TUI handles `/new`, `/resume`, `/sessions`, `/close`, `/model`, and `/effort
88
98
/model
89
99
/effort
90
100
/effort high
101
+
/agents
91
102
```
92
103
93
-
These local commands are available only while the session is idle. `/new` closes the current session and starts a fresh persisted session. It clears the visible transcript but does not delete or alter the previous session, which remains resumable by its ID. Text following `/new` becomes the new session's first prompt. `/resume <session-id>` closes the current session, resumes the requested durable session, and replays its transcript; selecting the already-active ID is a no-op. `/sessions` opens a visible newest-first selector for the same workspace; Up and Down move, Enter uses the existing resume flow, and Esc closes the dialog. `/close` closes the current session and exits the TUI.
104
+
These local commands are available only while the session is idle. `/agents` toggles the agent roster without starting a model turn. `/new` closes the current session and starts a fresh persisted session. It clears the visible transcript but does not delete or alter the previous session, which remains resumable by its ID. Text following `/new` becomes the new session's first prompt. `/resume <session-id>` closes the current session, resumes the requested durable session, and replays its transcript; selecting the already-active ID is a no-op. `/sessions` opens a visible newest-first selector for the same workspace; Up and Down move, Enter uses the existing resume flow, and Esc closes the dialog. `/close` closes the current session and exits the TUI.
94
105
95
106
`/model` opens the model selector. `/effort` opens the advertised ACP reasoning-effort selector; `/effort default|low|medium|high` selects directly. In either dialog, Tab toggles saving the selection to `~/.kit/config.toml`, Enter selects, and Esc closes. Saving `default` removes top-level `reasoning_effort`; other values update it without replacing unrelated TOML. A new or resumed process starts from the resolved CLI/TOML default unless the selection was saved.
0 commit comments