pi-better-subagents 0.25.0 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/usage.md CHANGED
@@ -96,74 +96,85 @@ thresholds continue to take precedence for subagent health.
96
96
 
97
97
  | Tool | Blocks? | What it does |
98
98
  |------|---------|--------------|
99
- | `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, `retain_session` (keep the completed conversation and workspace available for `subagent_resume`), and the [timing](#run-timing-deadline-ceiling-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`. |
100
- | `subagent_spawn_batch` | never | Launch several independent subagents at once. Each job becomes a normal run. Params: `batchName`, `shared` (options applied to every job), `jobs[]` (each needs `prompt`; launch options follow the declared batch schema, which omits `retain_session`), `onCapacity` (`reject` or `launch-available`). |
101
- | `subagent_resume` | never | Continue a completed run in its own saved conversation. Params: `id` (the completed attempt), `prompt` (the next user turn — do not restate the task or role), optional `model`/`thinking` (explicit escalation only; otherwise the saved recipe wins), `callback`, and the timing overrides. Returns a NEW run id with the same native session id and `resumedFrom` lineage. See [continuing a completed subagent](#continuing-a-completed-subagent). |
102
- | `subagent_release` | never | Release `retain_session` protection for a completed conversation and its workspace. Nothing is deleted now and no completed result is rewritten; ordinary cleanup may reclaim the artifacts afterwards. Only the owning foreground session may release. |
99
+ | `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, optional `session_id` or `session_name` (continue a saved conversation), and the [timing](#run-timing-deadline-ceiling-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`. |
100
+ | `subagent_spawn_batch` | never | Launch several independent subagents at once. Each job becomes a normal run. Params: `batchName`, `shared` (options applied to every job), `jobs[]` (each needs `prompt`; optional per-job `session_id` or `session_name` continues a saved conversation), `onCapacity` (`reject` or `launch-available`). |
103
101
  | `subagent_settings` | never | Read-only effective settings and capacity snapshot. No parameters. Returns `delegationMode`, `maxConcurrent`, per-setting `sources` (`session` or `config`), a stable settings `revision`, `runningCount`, `pendingCount`, `occupiedSlots`, and `availableSlots`. The limit is a ceiling, not a target; spawn admission rechecks live capacity. |
104
- | `subagent_list` | never | Compact current-session list (default 10 rows / 1 KiB page). Params: `all` (machine-global / foreign session), `limit` (default 10, max 100), `cursor`, `max_bytes` (max 4 KiB), `status` (`running`, `completed`, `failed`, `killed`, `exited`, durable `orphaned`, `lost`). Incident counts are compact; no spend/tool histories. |
102
+ | `subagent_list` | never | Compact list for the current folder and descendants across foreground sessions (default 10 rows / 1 KiB page). Each row includes `session_id`. Params: `all` (machine-global search), `limit` (default 10, max 100), `cursor`, `max_bytes` (max 4 KiB), `status` (`running`, `completed`, `failed`, `killed`, `exited`, durable `orphaned`, `lost`). Incident counts are compact; no spend/tool histories. |
105
103
  | `subagent_output` | never | Bounded current-session excerpt (default 1 KiB / 10 lines). Params: `id`, `lines` (`tail_lines` is a deprecated alias), `cursor` (a returned `nextCursor`, `statusCursor`, or `incidentCursor`), `max_bytes` (max 4 KiB; raw 16 KiB default, 64 KiB max), `mode` (`raw` pages retained log bytes), `include` (`["cost"]`, `["tools"]`, or both: opt-in spend and tool-count lines), `all` (foreign-session id). Missing/unreadable logs are gaps, not empty healthy output. |
106
104
  | `subagent_result` | never | Finished-run answer for the current session (2048-byte page). Params: `id`, `cursor` (a returned `nextCursor` continues the answer; `statusCursor` / `incidentCursor` also accepted), `max_bytes` (maximum 8192 bytes), `lines` (optional line cap per answer page), `mode` (`raw`), `include` (`["cost"]`, `["tools"]`, or both), `all` (foreign-session id). Failures and exceptional lifecycle facts come before progress; no tool-name histories. TUI folding is display-only. |
107
105
  | `subagent_stop` | never | SIGTERM a running run's process group. |
108
106
 
109
- ## Continuing a completed subagent
110
-
111
- A finished subagent can be given more work in **its own conversation** instead
112
- of starting a fresh worker that has lost the context. Both single and batch
113
- launches save sessions normally; `subagent_resume` needs no retention flag.
114
- `retain_session` only protects saved artifacts from ordinary cleanup. Releasing
115
- that protection does not prevent resume while the history and workspace still exist:
116
-
117
- | Step | What happens |
118
- |------|--------------|
119
- | `subagent_spawn` with `retain_session: true` | Marks the conversation and its workspace as retained while follow-up may be needed. The child still ends normally and a parked owner occupies **no** concurrency slot. Ordinary one-shot runs omit it and are unchanged. |
120
- | `subagent_resume({ id, prompt, … })` | Starts a NEW attempt: new run id, log, result, timing record, and capacity slot. The native session id, the exact saved conversation, and the frozen launch recipe stay the same, and the new attempt records `resumedFrom`/`rootRunId` lineage. `prompt` is the next user turn; the original task and role instructions already live in the history. |
121
- | `subagent_release({ id })` | Releases retention without deleting anything. Logs, results, and completed metadata stay intact; ordinary cleanup may reclaim the conversation and workspace afterwards. |
122
-
123
- Continuation rules:
124
-
125
- - Only a `completed` attempt can be continued. A running or orphaned attempt
126
- must be stopped first; `failed`, `killed`, and `lost` attempts are not
127
- continuation targets.
128
- - Only the foreground session that launched the run may continue or release it.
129
- - The saved conversation must still exist and must name the same native session
130
- id and workspace. A missing, ambiguous, or mismatched history refuses instead
131
- of starting a replacement conversation, and a missing workspace refuses too.
132
- Continuation passes the exact validated `--session` path; Pi's create-if-missing
133
- fallbacks are never used.
134
- - The attempt keeps the recipe's effective tools, exclusions, clean/nesting and
135
- approval intent, confinement, and model/effort. Pass `model`/`thinking` only to
136
- escalate explicitly for that attempt. Current mandatory human permissions are
137
- re-applied every time; a profile that would change confinement refuses instead
138
- of silently running the conversation under different rules.
139
- - Resolved extension implementations are recorded too. If current tool/provider
140
- configuration would silently replace one, continuation refuses; an explicit model
141
- escalation can select its required provider without changing tool implementations.
142
- - A continuation never prepares another Git clone. It reuses the recorded
143
- workspace, including uncommitted work. Age/size cleanup protects all attempts that
144
- own shared conversation resources while a continuation or pending admission uses them.
145
- - Retain the implementation owner through review fixes. Resume an independent reviewer
146
- only to finish an unfinished review on the same HEAD/scope; after a completed round,
147
- start a fresh reviewer with the retained findings and existing selected review scope.
148
- - One conversation admits one writer. A cross-process lease is held from
149
- admission through child lifetime and finalization; duplicate requests are
150
- refused, and a lease left behind by a dead process (or by an already
151
- finalized attempt) is recovered conservatively. Lease/retention mutations use a
152
- short kernel-owned SQLite transaction; retained launches and continuation require
153
- a runtime with `node:sqlite` (Node 24 recommended). Ordinary one-shot launches
154
- remain available without it. A dead coordinator with no published child metadata
155
- is ambiguous and cannot authorize another writer.
156
- - Retention uses the existing temporary runtime storage. It is a bounded
157
- availability promise, not permanent storage: if system temp is reaped, the
158
- history is gone and continuation refuses with a clear error.
107
+ ## Finding a saved conversation
108
+
109
+ `subagent_list()` searches the current folder and its descendants, including runs
110
+ from other foreground sessions. Use `subagent_list({ all: true })` for a global
111
+ search. Each row shows both the attempt id and `session_id`; use the session id
112
+ when continuing work. A continuation keeps that session id while receiving a new
113
+ attempt id.
114
+
115
+ ```javascript
116
+ subagent_list()
117
+ subagent_list({ all: true })
118
+ ```
119
+
120
+ Local name lookup follows the same folder scope. A duplicate name is not resolved
121
+ by choosing the newest conversation; use one of the reported session ids instead.
122
+
123
+ ## Continuing a saved conversation
124
+
125
+ Use the same spawn tool for new work and follow-up work:
126
+
127
+ ```javascript
128
+ subagent_spawn({ name: "implementation", prompt: "Implement the change." })
129
+ subagent_spawn({ session_id: "<saved-session-id>", prompt: "Fix the review findings." })
130
+ subagent_spawn({ session_name: "implementation", prompt: "Fix the review findings." })
131
+ ```
132
+
133
+ A launch without a session selector starts a new conversation. With a selector,
134
+ `prompt` is the next user turn; the original task and role are already saved.
135
+ Each attempt gets a new run id, log, timing record, and capacity slot while the
136
+ native session id and history stay the same. The launch recipe preserves the
137
+ worker's role, tools, model, and workspace, including uncommitted changes.
138
+
139
+ `session_name` is an exact display-name match within the current folder and its
140
+ descendants. Several attempts of the same conversation count once. If several
141
+ conversations share the name, spawn reports matching session ids and refuses to
142
+ guess. Use `subagent_list({ all: true })` to find conversations elsewhere and
143
+ pass `session_id`. `name` remains a new-launch label.
144
+
145
+ Single and batch launches save native Pi sessions and completed launch recipes
146
+ durably in the Pi agent directory. No retention flag or release tool is needed.
147
+ Temporary event logs can be cleaned up independently. Missing or manually deleted
148
+ history is never recreated by continuation. Older recipes pointing at temporary
149
+ session files remain usable only while those original files exist.
150
+
151
+ A different foreground session may continue a conversation. The new attempt's
152
+ callback goes to its caller; previous attempts keep their original evidence.
153
+ Only a completed conversation with an existing workspace and verified saved
154
+ history can continue. One conversation admits one writer: active or orphaned
155
+ attempts and live writer leases refuse competing launches. Continuation requires
156
+ a runtime with `node:sqlite` (Node 24 recommended).
157
+
158
+ Current mandatory human permissions apply on every attempt. A change that would
159
+ alter confinement or replace recorded tool implementations refuses continuation.
160
+ Only explicit model/effort escalation changes the saved model choice; a continued
161
+ worker does not silently inherit the caller's model or re-resolve its role.
162
+
163
+ Use per-job `session_id` or `session_name` in `subagent_spawn_batch`. A batch may
164
+ mix fresh and continued jobs. Keep one job per conversation; the writer lease
165
+ rejects competing jobs.
166
+
167
+ If new parameters are missing after an npm upgrade, run `/reload` in Pi.
168
+ Updating files on disk does not replace extension code already loaded in a live
169
+ session.
159
170
 
160
171
  ## Codemode batch launches
161
172
 
162
173
  On Pi 0.99.1 or newer, enable native codemode alongside the existing direct
163
174
  tools with `defaultTools: ["+codemode"]` and `codemode.mode: "on"`. SDK sessions
164
175
  must also load Pi's `createCodemodeExtension()`. This support is for the
165
- foreground coordinator; it does not enable codemode in confined children or
166
- change sandbox admission.
176
+ foreground coordinator. Child codemode is enabled separately by the default
177
+ tool set and preserves sandbox tool admission.
167
178
 
168
179
  `subagent_spawn_batch` returns the same readable text to direct callers and a
169
180
  structured launch receipt to codemode scripts. No text parsing is needed:
@@ -514,10 +525,17 @@ the task boundary.
514
525
  ## Tool scoping (allowlist)
515
526
 
516
527
  Precedence, highest first: the per-call `tools` param → `config.json`
517
- `defaultTools` → a built-in default (`read, bash, edit, write, web_search,
528
+ `defaultTools` → a built-in default (`read, bash, edit, write, codemode, web_search,
518
529
  web_fetch`; just `read, bash` in a `clean` child). `exclude_tools` subtracts on
519
530
  top.
520
531
 
532
+ On Pi 0.99.1 or newer, default children explicitly load native `codemode` even
533
+ with extension discovery disabled. Custom tool lists must include `codemode`;
534
+ `exclude_tools: "codemode"` removes it. Older SDKs keep their existing tools.
535
+ In confined children, nested tool calls pass through the task guard. Direct
536
+ classifier and image-model globals are disabled there because they bypass tool
537
+ hooks. Unconfined children retain native model globals.
538
+
521
539
  User configuration lives in
522
540
  `~/.pi/agent/settings.json` under `piBetterHarness.subagents` (under
523
541
  `PI_CODING_AGENT_DIR` when set). The old user config migrates on first use.
@@ -741,10 +759,12 @@ state. Session shutdown disposes open navigator timers.
741
759
 
742
760
  ## Design notes
743
761
 
744
- - Runtime lives outside any repo, under `$TMPDIR/pi-better-subagents/`
745
- (`runs/<id>/` holds `output.log`, `prompt.md`, `meta.json`; `sessions/` holds
746
- child session state). The `meta.json` sidecar is authoritative, so `list` /
747
- `output` / `result` survive turns, `/reload`, and pi restarts.
762
+ - Temporary run evidence lives outside any repo under `$TMPDIR/pi-better-subagents/`
763
+ (`runs/<id>/` holds `output.log`, `prompt.md`, and `meta.json`). Native child
764
+ sessions and compact completed-attempt recipes persist under the Pi agent
765
+ directory in `subagents/sessions` and `subagents/attempts`. Event-log cleanup
766
+ does not remove the saved conversation or recipe. Existing legacy recipes keep
767
+ their original session paths.
748
768
  - The child runs `--mode json`; `subagent_result` / `subagent_output` **parse**
749
769
  the event stream and return just the bounded final answer (no tool-name history).
750
770
  Non-JSON banner/warning lines fail to parse and are dropped, so the result is
@@ -756,7 +776,7 @@ state. Session shutdown disposes open navigator timers.
756
776
 
757
777
  ## Parent-process scoping
758
778
 
759
- The live widget, default `subagent_list`, concurrency cap, and `session_start` ticker only include runs this pi process spawned (`spawnPid === process.pid`). The on-disk registry stays machine-global for durability. Default `subagent_list` is current-session, newest first, 10 compact rows / 1 KiB. Pass `limit:N` (max 100) or `max_bytes` (max 4 KiB) for an explicit larger page. Pass `all:true` for a global / foreign-session view. Pass `status:[...]` to filter by effective status: `running`, `completed`, `failed`, `killed`, transient `exited`, or durable `orphaned` / `lost`. Id-based `subagent_result` / `subagent_output` default to the current session; pass `all:true` to read a foreign-session id. Unknown ownership is a gap, not “not found”; when the current session identity cannot be read, no run's ownership is treated as verified and `all:true` is required. List pages are reached with the returned `nextCursor` (every run is reachable, not only the first 100). Runs whose metadata is missing or corrupt are reported as gaps and counted on lists, never as nonexistent.
779
+ The live widget, concurrency cap, and supervision ticker track this Pi process's runs. `subagent_list` searches the current folder and its descendants across foreground sessions; `all:true` searches globally. Rows show the attempt id and the native `session_id`, so a listed conversation can be continued explicitly. Results are newest first, with 10 rows / 1 KiB by default. Use `limit` (max 100), `max_bytes` (max 4 KiB), and `status` filters as needed. Cursors are bound to the local folder or global scope and cannot be replayed from a different folder. Id-based `subagent_result` and `subagent_output` keep their current-session scope; use `all:true` to read another session's run evidence. Unknown ownership remains an explicit gap for those evidence tools. Saved conversation discovery and continuation do not require the original foreground session to exist.
760
780
 
761
781
  ## Supervision health (`orphaned` / `lost`)
762
782
 
package/extensions.mjs CHANGED
@@ -33,7 +33,8 @@
33
33
  * pi -p --no-extensions "list your tools" -> read, bash, edit, write
34
34
  * A builtin needs no extension, so it never counts as unmapped.
35
35
  */
36
- export const BUILTIN_TOOLS = ["read", "bash", "edit", "write"];
36
+ // codemode is supplied by the harness child adapter, not a discovered package.
37
+ export const BUILTIN_TOOLS = ["read", "bash", "edit", "write", "codemode"];
37
38
 
38
39
  /** Marker spec meaning "this extension's own package" (for allow_nested). */
39
40
  export const SELF_SPEC = "self";