pi-better-subagents 0.9.2 → 0.10.0

package/README.md

@@ -12,11 +12,12 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
 
 ## Core Features
 - Non-blocking subagent launches, with an optional role and named-agent catalog (`docs/agent-catalog.md`, `docs/agent-catalog-lifecycle.md`).
+- Typed foreground `subagent_spawn_batch` launch receipts for native Pi codemode (Pi 0.99.1+), preserving direct tool calls, per-run callbacks, and batch capacity/catalog guarantees. See [codemode batch launches](docs/usage.md#codemode-batch-launches).
 - Default OS write sandboxing on macOS and Linux.
 - Explicit tool allowlists for child sessions.
 - Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status. A live child handles its own tool errors; the parent is woken only for actionable incidents, and children can classify handled failures with `failure_disposition`.
 - Live background-work navigator for active runs.
-- Harness-owned run timing: every run gets a soft deadline (30 min, then a wrap-up steer into the child and one parent wake, stopped after 5 min grace), a hard ceiling (90 min), and a no-progress wake (10 min). Override per spawn with `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`, or globally in `config.json` / `PI_SUBAGENT_*_MINUTES`. See [usage notes](docs/usage.md#run-timing-deadline-ceiling-stuck).
+- Harness-owned run timing: every run gets a no-progress wake (10 min), while wall-clock soft deadlines and hard ceilings are opt-in so productive agents are not stopped solely for taking a long time. Configure per spawn with `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`, or globally in `config.json` / `PI_SUBAGENT_*_MINUTES`. See [usage notes](docs/usage.md#run-timing-deadline-ceiling-stuck).
 
 ## Install
 
@@ -44,14 +45,14 @@ nontrivial role-owned task, while the foreground coordinates, integrates, and
 verifies. See [usage notes](docs/usage.md#delegation-mode).
 
 `agents_catalog` shows each role's and named agent's default model and effort,
-such as `role developer "Developer" … default openai/gpt-6-sol@high`. Roles are
+such as `role developer "Developer" … default openai/gpt-6.1-sol@high`. Roles are
 listed and passed by short name (`role: "developer"`); the stored id
 `role.developer` also works, and named agents keep their full id
 (`agent: "agent.payments"`). To launch on that default, omit
 `model` and `thinking` on a role or agent spawn; name one only for a stated
 reason. When a launch's model or effort differs from the default, its launch
 line says so, for example
-`model openai/gpt-6-astra@high (role developer default openai/gpt-6-sol@high)`.
+`model openai/gpt-6-astra@high (role developer default openai/gpt-6.1-sol@high)`.
 
 ## When To Use
 

package/batch.mjs

@@ -14,6 +14,64 @@ import { assertTimingParams } from "./timing.ts";
 
 const VALID_CAPACITY_MODES = new Set(["reject", "launch-available"]);
 
+/** Public codemode receipt; details alone are not returned to nested callers. */
+export const batchLaunchOutputSchema = {
+    type: "object",
+    properties: {
+        status: { type: "string", enum: ["launched", "partial", "not-launched", "clarification-needed"] },
+        batchId: { type: "string" },
+        batchName: { type: "string" },
+        launched: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: { job: { type: "integer", minimum: 1 }, name: { type: "string" }, id: { type: "string" }, modelNote: { type: "string" } },
+                required: ["job", "name", "id"],
+                additionalProperties: false,
+            },
+        },
+        failed: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: { job: { type: "integer", minimum: 1 }, name: { type: "string" }, reason: { type: "string" } },
+                required: ["job", "name", "reason"],
+                additionalProperties: false,
+            },
+        },
+        skipped: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: { job: { type: "integer", minimum: 1 }, name: { type: "string" } },
+                required: ["job", "name"],
+                additionalProperties: false,
+            },
+        },
+        message: { type: "string" },
+        choices: { type: "array", items: { type: "string" } },
+    },
+    required: ["status", "launched", "failed", "skipped"],
+    additionalProperties: false,
+};
+
+/** Launch success is not run completion; partial receipts retain every created run. */
+export function batchLaunchResult({ batchId, batchName, launched, skipped, failed }) {
+    const receipt = {
+        status: launched.length === 0 ? "not-launched" : failed.length || skipped.length ? "partial" : "launched",
+        batchId,
+        ...(batchName !== undefined ? { batchName } : {}),
+        launched,
+        failed,
+        skipped,
+    };
+    return {
+        content: [{ type: "text", text: formatBatchLaunchResponse(receipt) }],
+        details: receipt,
+        structuredContent: receipt,
+    };
+}
+
 /**
  * Overlay per-job options on top of shared options. Only defined keys are
  * inherited; booleans keep their false values.

package/catalog-runtime.ts

@@ -256,9 +256,9 @@ export async function clarifyCatalogRequest(
  * Launch-line note for a catalog run whose effective model or effort differs
  * from the role or agent default. The wording names the cause, so a fallback
  * or a capped effort is not mistaken for a caller override:
- * - override: `model openai/gpt-6-astra@high (role developer default openai/gpt-6-sol@high)`
- * - fallback: `model xai/grok-4.7@high (role developer default openai/gpt-6-sol@high unavailable; foreground fallback)`
- * - capped effort: `model openai/gpt-6-sol@medium (role developer default openai/gpt-6-sol@high; effort capped at medium by the model)`
+ * - override: `model openai/gpt-6-astra@high (role developer default openai/gpt-6.1-sol@high)`
+ * - fallback: `model xai/grok-4.7@high (role developer default openai/gpt-6.1-sol@high unavailable; foreground fallback)`
+ * - capped effort: `model openai/gpt-6.1-sol@medium (role developer default openai/gpt-6.1-sol@high; effort capped at medium by the model)`
  * Undefined for a non-catalog run, a definition with no default, or a launch
  * that matches the default. Only the fields the definition sets are compared.
  */

package/catalog-schema.ts

@@ -72,10 +72,10 @@ export const PARSER_LIMITS = {
  * runtime already uses. Tiers are catalog policy, not benchmark rankings.
  */
 export const APPROVED_ROLE_DEFAULTS = [
-    { id: "role.researcher", name: "Researcher", model: "openai/gpt-6-sol", effort: "medium", tier: "balanced" },
+    { id: "role.researcher", name: "Researcher", model: "openai/gpt-6.1-sol", effort: "medium", tier: "balanced" },
     { id: "role.explorer", name: "Explorer", model: "openai/gpt-6-luna", effort: "medium", tier: "efficient" },
-    { id: "role.product-manager", name: "Product Manager", model: "openai/gpt-6-sol", effort: "medium", tier: "balanced" },
-    { id: "role.developer", name: "Developer", model: "openai/gpt-6-sol", effort: "high", tier: "balanced" },
+    { id: "role.product-manager", name: "Product Manager", model: "openai/gpt-6.1-sol", effort: "medium", tier: "balanced" },
+    { id: "role.developer", name: "Developer", model: "openai/gpt-6.1-sol", effort: "high", tier: "balanced" },
     { id: "role.reviewer", name: "Reviewer", model: "openai/gpt-6-astra", effort: "medium", tier: "frontier" },
     { id: "role.architect", name: "Architect", model: "openai/gpt-6-astra", effort: "high", tier: "frontier" },
 ] as const;

package/docs/agent-catalog-operations.md

@@ -52,7 +52,7 @@ Codex applies the agent file's model and `model_reasoning_effort` ahead of the c
 
 `agents_catalog` accepts `list` and `inspect` only. It uses the same inspection view as `/agents show`. It has no write path. Launch remains `subagent_spawn` or the batch tool, with at most one `agent` or `role` selector. Those selectors are lifecycle's wiring, not this tool.
 
-A list line names a role by its short name (`role developer "Developer" …`), the form the `role` field takes; the inspect header, `identity.id`, and the structured `id` keep the stored id `role.developer`. Named agents show their full `agent.<slug>` id in both. Each list line and the inspect header end with the definition's default model and effort when one is set, such as `default openai/gpt-6-sol@high`: a role's own default, or a named agent's override or inherited role default. The structured view carries the same value as `defaults: { model, effort, label }`, or `null` when neither is set. A spawn that omits `model` and `thinking` uses it. When a catalog launch's model or effort differs from it, the launch line (and each batch job line) adds a note such as `model openai/gpt-6-astra@high (role developer default openai/gpt-6-sol@high)`; a named agent's note reads `agent default …`. Only the fields the definition sets are compared. The note names the cause: a fallback from an unavailable default reads `(role developer default openai/gpt-6-sol@high unavailable; foreground fallback)` (or `same-tier` / `configured-default`), and an effort the model cannot run adds `effort capped at <level> by the model`.
+A list line names a role by its short name (`role developer "Developer" …`), the form the `role` field takes; the inspect header, `identity.id`, and the structured `id` keep the stored id `role.developer`. Named agents show their full `agent.<slug>` id in both. Each list line and the inspect header end with the definition's default model and effort when one is set, such as `default openai/gpt-6.1-sol@high`: a role's own default, or a named agent's override or inherited role default. The structured view carries the same value as `defaults: { model, effort, label }`, or `null` when neither is set. A spawn that omits `model` and `thinking` uses it. When a catalog launch's model or effort differs from it, the launch line (and each batch job line) adds a note such as `model openai/gpt-6-astra@high (role developer default openai/gpt-6.1-sol@high)`; a named agent's note reads `agent default …`. Only the fields the definition sets are compared. The note names the cause: a fallback from an unavailable default reads `(role developer default openai/gpt-6.1-sol@high unavailable; foreground fallback)` (or `same-tier` / `configured-default`), and an effort the model cannot run adds `effort capped at <level> by the model`.
 
 ## Lifecycle attachment
 

package/docs/agent-catalog.md

@@ -16,7 +16,7 @@ id: role.developer
 name: Developer
 description: Implements a requested change in the existing system.
 defaults:
-  model: openai/gpt-6-sol
+  model: openai/gpt-6.1-sol
   effort: high
   tier: balanced
 ---
@@ -100,10 +100,10 @@ Model availability, same-tier fallback, and nearest-effort adjustment are not de
 
 | Role | Stored id | Name | Model | Effort | Tier |
 | --- | --- | --- | --- | --- | --- |
-| `researcher` | `role.researcher` | Researcher | `openai/gpt-6-sol` | medium | balanced |
+| `researcher` | `role.researcher` | Researcher | `openai/gpt-6.1-sol` | medium | balanced |
 | `explorer` | `role.explorer` | Explorer | `openai/gpt-6-luna` | medium | efficient |
-| `product-manager` | `role.product-manager` | Product Manager | `openai/gpt-6-sol` | medium | balanced |
-| `developer` | `role.developer` | Developer | `openai/gpt-6-sol` | high | balanced |
+| `product-manager` | `role.product-manager` | Product Manager | `openai/gpt-6.1-sol` | medium | balanced |
+| `developer` | `role.developer` | Developer | `openai/gpt-6.1-sol` | high | balanced |
 | `reviewer` | `role.reviewer` | Reviewer | `openai/gpt-6-astra` | medium | frontier |
 | `architect` | `role.architect` | Architect | `openai/gpt-6-astra` | high | frontier |
 

package/docs/agent-model-resolution.md

@@ -10,7 +10,7 @@ Normative rules are R3, R4, R8, and the resolver half of R10. Prose parsing and
 - It does not grant tools, sandbox modes, extensions, or presets. Inspection copies the catalog `capabilities` object (`grantedByCatalog: false`).
 - It does not call a provider. Availability is one `getAvailable()` snapshot from the foreground registry. `find()` only explains that a known model is outside that set.
 - It does not retry, and it does not substitute after a child has started. `automaticRetry` and `substitutionAfterStart` are false. `startupFailure.action` is `surface-error-no-retry-no-substitution`. A later provider initialization failure is a lifecycle error.
-- It does not invent tier candidates. Built-in tiers name the approved models and have empty candidate lists. `openai/gpt-6-sol`, `openai/gpt-6-luna`, and `openai/gpt-6-astra` are not substitutes.
+- It does not invent tier candidates. Built-in tiers name the approved models and have empty candidate lists. `openai/gpt-6.1-sol`, `openai/gpt-6-luna`, and `openai/gpt-6-astra` are not substitutes.
 
 ## Precedence
 

package/docs/usage.md

@@ -0,0 +1,695 @@
+# pi-better-subagents
+
+A better subagent extension for [pi](https://github.com/earendil-works/pi-coding-agent).
+
+Not a clone of Claude Code's subagents — a rethink of what a subagent system
+should be: **autonomous, non-blocking, and safe by default.** You delegate work
+and keep going; each subagent runs on its own in an isolated process, confined to
+what it needs, and reports back when it's done. No blocking waits, no
+back-channel for it to stall on, no unbounded blast radius.
+
+```
+launch is the result · completion triggers fetch · the foreground never blocks
+```
+
+## Delegation Mode
+
+Set `delegationMode` in this package's `config.json` to `manual`, `adaptive`, or
+`coordinator` (default `adaptive`). This controls foreground delegation guidance,
+not child permissions or catalog definitions. `/subagents` reports the active
+mode; `/subagents mode manual|adaptive|coordinator` overrides it for the current
+session without editing config. Other arguments show usage. `/reload` retains
+this override; new sessions use config, while resuming a session restores that
+session's override.
+
+- **Manual:** no proactive delegation, including in plan mode. A user request or
+  explicit workflow requirement may still delegate.
+- **Adaptive:** delegate useful, substantial independent work while continuing
+  foreground work; keep small or coupled tasks local.
+- **Coordinator:** use `agents_catalog` to discover current roles and delegate
+  every nontrivial task owned by an available role, passing the role by its
+  short name (`role: "developer"`). The foreground owns
+  orchestration, cross-role decisions, unowned or ambiguous work, integration,
+  and final verification. Current role descriptions, including custom catalog
+  overrides, determine ownership.
+
+All modes retain the no-polling rule and require inspection of delegated results
+before final verification. `pi-better-plan` follows the active mode when a plan
+is present; without this extension it uses adaptive guidance.
+
+## Principles
+
+- **The foreground never blocks.** Launching a subagent *is* the deliverable —
+  `subagent_spawn` starts a detached `pi -p` child and returns immediately,
+  leaving the session free for the human. When the child finishes, it sends a
+  lightweight trigger; the foreground calls `subagent_result` and presents the
+  result (as a `followUp`, never cutting into work in progress). The foreground
+  is nudged once, at completion — never on a wait/poll loop.
+- **Subagents are autonomous; communication is one-way (parent → child).** The
+  parent front-loads everything the child needs into the spawn; the child runs to
+  completion and **returns a result**. There is no mid-task child→parent blocking
+  call for a subagent to waste wall-clock on — a child missing a piece of info
+  resolves it from what it was given, or records it unavailable and returns.
+- **Safe by default.** Every subagent is OS-sandboxed — writes confined to its
+  working directory, reads and network open — and scoped to an explicit tool
+  allowlist. It can't corrupt the parent, escape its directory, or recurse into
+  more subagents without opt-in.
+- **Observable.** A live status widget and on-demand queries show each run's
+  elapsed time and token/cost spend.
+
+### Observable progress
+
+Subagent health uses the shared 60-second quiet and 5-minute stalled defaults,
+while preserving its stricter child-event semantics: active tool calls,
+compaction, and model retry/error phases explain silence rather than becoming
+stale. For a cross-extension override, set `PI_BETTER_STALL_QUIET_MS` and
+`PI_BETTER_STALL_MS` in milliseconds. Existing subagent `config.json` health
+thresholds continue to take precedence for subagent health.
+
+## Tools
+
+| Tool | Blocks? | What it does |
+|------|---------|--------------|
+| `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`, and the [timing](#run-timing-deadline-ceiling-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`. |
+| `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`; same optional params as `subagent_spawn`), `onCapacity` (`reject` or `launch-available`). |
+| `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. |
+| `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. |
+| `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. |
+| `subagent_stop` | never | SIGTERM a running run's process group. |
+
+## Codemode batch launches
+
+On Pi 0.99.1 or newer, enable native codemode alongside the existing direct
+tools with `defaultTools: ["+codemode"]` and `codemode.mode: "on"`. SDK sessions
+must also load Pi's `createCodemodeExtension()`. This support is for the
+foreground coordinator; it does not enable codemode in confined children or
+change sandbox admission.
+
+`subagent_spawn_batch` returns the same readable text to direct callers and a
+structured launch receipt to codemode scripts. No text parsing is needed:
+
+```javascript
+const receipt = await tools.subagent_spawn_batch({
+  batchName: "inspection",
+  shared: { tools: "read,bash" },
+  jobs: [
+    { role: "explorer", prompt: "Map the request handling path." },
+    { role: "reviewer", prompt: "Review the current changes for regressions." }
+  ]
+});
+store("inspection-launch", receipt);
+text(receipt);
+```
+
+| Field | Meaning |
+|-------|---------|
+| `status` | `launched`: every effective job launched; `partial`: some launched and some failed or were skipped; `not-launched`: none launched; `clarification-needed`: selection needs a human decision and nothing launched. These are launch outcomes, never completion outcomes. |
+| `batchId`, `batchName` | Assigned batch identity and optional label. No batch ID is assigned for clarification. |
+| `launched` | `{ job, name, id, modelNote? }` for each created run. |
+| `failed` | `{ job, name, reason }` for launch failures, including later jobs not attempted after a reject-mode launch failure. |
+| `skipped` | `{ job, name }` for jobs omitted because capacity was full in `launch-available` mode. |
+| `message`, `choices` | Explanation and selection options on a clarification receipt. |
+
+`job` is a 1-based position in the effective batch order, after any confirmed
+role split. All three job lists are always present. Invalid input and whole-batch
+capacity rejection still throw, so codemode callers must catch those errors.
+Returned partial or no-launch receipts do not throw; inspect `status` and every
+list instead of treating a fulfilled promise as complete success.
+
+Await the launch call and print or retain its receipt before returning from the
+script. Codemode `store()` writes persist only if the script succeeds; launched
+runs are not rolled back if the script later fails, times out, or is interrupted.
+Use the durable run registry to recover IDs when needed, and `subagent_stop` to
+stop a run. Script cancellation is not a stop request. Collect results after
+completion callbacks with `subagent_result`; do not poll or keep a script open
+waiting for completion. Callbacks and capacity/catalog guarantees remain owned
+by the existing harness runtime.
+
+## Run timing (deadline, ceiling, stuck)
+
+Timeout control belongs to the harness, not to the prompt or the skill that
+launched the run. A time limit written into a prompt is enforced by nothing, and
+a parent that only notices late tends to kill a child that was still making
+progress. Every run gets stall detection by default. Elapsed-time limits are
+opt-in because total runtime does not distinguish a slow agent from a stalled
+one.
+
+| Control | Default | What happens |
+|---------|---------|--------------|
+| Soft deadline (`deadline_minutes`) | Off | When configured, the child gets one steering message (delivered through Pi's steer queue after its current tool call finishes): stop starting new work, commit or save what is done, and report what is complete, what is not, and where the work is. The parent gets one wake saying so. |
+| Grace (`grace_minutes`) | 5 | Grace starts when the steering message actually reaches the child, which is after its current tool call. While the message is still waiting behind a running tool call, the deadline stop is held, so a test run that began just before the deadline is not killed mid-run. If the child has not finished by the end of grace, the harness stops it; the ordinary completion callback reports `killed; stopped: deadline`. A child that completes inside grace is not stopped; its surfaces say `deadline: finished in grace`. |
+| Hard ceiling (`max_minutes`) | Off | When configured, the run is stopped at once, without grace or a steer, and reported as `stopped: ceiling`. The ceiling bounds everything, including a tool call that never ends and an orphaned run (child gone, its process group still alive). |
+| Stuck window (`stuck_minutes`) | 10 | No progress (see below) for this long wakes the parent once (`stuck`). It never stops the run. After new progress, a later stuck spell wakes again. |
+
+`0` turns a control off. `null` or an omitted value means "inherit": on
+`subagent_spawn` that is the configured default; on a `subagent_spawn_batch` job
+it is the `shared` value, then the configured default. Values are minutes and
+may be fractional. A job's own number (including `0`) wins over `shared`.
+
+**Known limits of the deadline hold.**
+
+- `max_minutes: 0` turns the ceiling off, and the ceiling is the only control
+  that bounds a tool call that never ends. With it off, a steer stuck behind a
+  hung tool call is never delivered, the deadline stop stays held, and the run
+  is never stopped. Opt into a ceiling when a command must have a wall-clock
+  bound.
+- The parent reads at most the last 32 MiB of a child log after `/reload`. If
+  the log is larger and the running tool call started before that window, the
+  parent cannot see the call, so the hold is lost and grace counts from when
+  the steer was sent. The child can be stopped mid-call.
+- The child confirms delivery by matching the steer's exact text in its
+  conversation. If another extension rewrites user input (an input-transform
+  hook), the text no longer matches, no receipt is written, and grace silently
+  counts from when the steer was sent instead of when it arrived.
+
+**Progress**, defined simply: any successful tool call that is not an exact
+repeat of an earlier call in the same run. "Exact repeat" means the same tool
+name and the same arguments, with null and absent optional fields treated alike
+(as in #336) and key order ignored. A successful file-mutating tool (`edit`,
+`write`, `multi_edit`, `apply_patch`, `str_replace`, `write_file`, and similarly
+named tools), a `git commit`, and a success directly after a failed call always
+count, even when repeated. Re-reading the same file or re-running the same command with the same
+arguments does not reset the stuck window, so a read-only research child making
+distinct calls is never flagged, while one looping on the same read is. The
+harness remembers up to 4096 distinct calls per run as fixed-size hashes of the
+name and normalized arguments; past that the oldest is forgotten, so a call from
+long ago counts again. Time the child spends waiting on a running tool call does not count toward the
+stuck window, so a child in the middle of a 20-minute test run is waiting, not
+stuck. A command that hangs is bounded only when the caller opts into a deadline
+or ceiling.
+The other stuck signal is the existing escalation: the same operation failing
+three times wakes the parent once as an `Action required` incident
+([failure observations](failure-observations.md)).
+
+**Where the reason shows.** `subagent_list` rows, `subagent_output`,
+`subagent_result`, and completion callbacks carry `stopped: deadline`,
+`deadline: wrapping up`, `deadline: finished in grace` (completed after the
+deadline), `deadline: passed` (ended some other way after the deadline, for
+example it crashed or a user stopped it), `stopped: ceiling`, or `stuck`. The spawn response lists the limits in force.
+
+**Global defaults.** Precedence is spawn parameter, then environment, then
+`config.json`, then the built-in default:
+
+| Setting | Environment | `config.json` |
+|---------|-------------|---------------|
+| Soft deadline | `PI_SUBAGENT_DEADLINE_MINUTES` | `deadlineMinutes` |
+| Grace | `PI_SUBAGENT_GRACE_MINUTES` | `graceMinutes` |
+| Hard ceiling | `PI_SUBAGENT_MAX_MINUTES` | `maxMinutes` |
+| Stuck window | `PI_SUBAGENT_STUCK_MINUTES` | `stuckMinutes` |
+
+**Durability and delivery.** The policy and its one-shot markers (steer
+requested, deadline wake, stuck wake, stop reason) are stored in the run's
+metadata at launch, so `/reload` keeps the deadline and never repeats a wake.
+The parent checks timing on its 15-second supervision tick. The steer travels
+through a request file in the run directory, read by a small harness extension
+loaded into every child (it registers no tools and runs no commands). When the
+message enters the child's conversation, the extension writes a receipt file
+next to the request; grace starts at that time. The extension runs in the
+trusted Pi process, and the child's confined tools cannot write the run
+directory, so a child cannot forge a receipt. Without a receipt and with no
+tool call running (for example, a child started without the extension), grace
+runs from when the steer was requested. Wakes follow `callback:false` and session ownership like other callbacks.
+Runs launched before this feature have no timing record and are not timed.
+
+Output-control parameters are spelled the same across subagents and background
+tasks: `max_bytes` and `lines`. The older spellings `maxBytes` and `tail_lines`
+are deprecated aliases; both work, and the canonical name wins when both are
+given.
+
+## Non-blocking, by construction
+
+- **Process isolation.** Each run is a `detached` + `unref`'d `pi -p` process.
+  Its context can't clog the parent, its crash can't corrupt parent state, and
+  its output is durable in a log file.
+- **Completions trigger one batched turn that fetches durable results.** Ordinary
+  terminal callbacks accumulate for 100 ms and share one
+  `pi.sendMessage(..., { deliverAs: "followUp", triggerTurn: true })` notification
+  with background-task completions from the same Pi host. Each row contains only
+  source, id, label, terminal status, and the `subagent_result` lookup. Full
+  results and logs stay in durable tools and are never embedded in the callback.
+  Set `PI_BETTER_CALLBACK_BATCH_MS` to `0` through `5000` milliseconds to tune
+  the accumulation window; invalid values use 100 ms. A failed handoff keeps the
+  pending records retryable, and `/reload` recovers records explicitly marked
+  pending. `callback:false` sends no model message; read the durable result later
+  with `subagent_result`.
+- **The prompt guidelines forbid polling.** The foreground agent is told, in the
+  tool guidelines, that spawning is done and it must not loop on `output`/`result`
+  or sleep to wait.
+
+## Autonomy & safety
+
+Every subagent is confined by default, and the confinement is **self-contained** —
+it does not depend on any other extension being installed.
+
+- **Task sandbox (default on, macOS and Linux).** Pi startup, authentication,
+  provider transport, and session persistence run as trusted runtime operations.
+  Admitted task tools run under `sandbox-exec` or Linux Bubblewrap. Project files
+  default to Read / write and outside files to Read, including `~/.pi`; runtime
+  control files remain protected. Commands use private scratch plus explicit
+  runtime exceptions for `/tmp` and the current user's macOS temporary and MDS
+  cache directories when Outside is Read or Read/write. Credential and control
+  denials retain precedence. See the permission details below.
+- **Tool allowlist.** Confined children admit only verified read/write/edit/bash
+  implementations, the guarded `apply_patch`, and the trusted tools ticked in
+  `/sandbox`. Other requested tools are reported as unavailable, with the reason.
+- **No runaway recursion.** Confined children cannot spawn nested agents.
+  `allow_nested:true` loads nested-agent support only for unconfined children.
+
+### Write sandbox
+
+The shared `sandbox-core` and `task-sandbox` modules enforce task operations in
+both Main and Subagents. The defaults are Main Off and Subagents On. Subagents
+use Project files = Write & delete and Outside project = **Write**: tasks write
+across home and temp (tool caches such as `~/.gradle` and `~/.npm` just work), but
+outside the workspace they can only remove or rename files in temp, hidden home
+entries, and worktree folders (`.worktrees/`, `*-worktrees/`). Credential files
+default to readable but not writable, so npm, git over SSH, and authenticated
+CLIs can reuse their normal user configuration. This exposes known file-based
+credentials to confined subagents; set Stored credentials to Off to hide them.
+Shell startup files, `~/.pi`, `~/.claude`,
+`~/.agents`, and harness state cannot be written, removed, or renamed. Rename-based
+saves and git commits in a sibling repository fail under Write; set Outside
+project to Write & delete when a task needs that. Linux uses a stricter fallback
+where ordinary home folders are read-only. See
+[pi-better-sandbox](../../pi-better-sandbox/README.md) and
+[ADR 0008](../../../docs/adr/0008-write-without-delete.md). Commands and network
+default On. A subagent's project root is its selected workspace (`cwd` / `sandbox_dir`),
+or its disposable clone. `/sandbox off` changes Main, not Subagents.
+
+Pi runs as the trusted runtime so it can take settings/authentication locks,
+connect to its provider, and persist sessions. A mandatory guard loads before
+the task can run. Its immutable launch snapshot controls shell commands and
+kernel-confined file workers. Task access to `~/.pi` follows the outside and
+credential-file rules; there are no writable lock exceptions. Runtime code,
+configuration, and control files remain protected from task writes.
+
+Commands Off still permits file tools according to their file permissions.
+Network Off blocks task network access while Pi's provider transport remains
+available. The confined file worker has an 8 MiB file limit and rejects larger
+files explicitly; use confined commands for larger files when commands are On.
+
+`read`, `write`, `edit`, and `bash` have verified adapters. Extension tools are
+chosen in `/sandbox` → Subagents · Tools
+([ADR 0009](../../../docs/adr/0009-guarded-and-trusted-subagent-tools.md)):
+
+- **Guarded:** `apply_patch`, a harness adapter with the Codex tool's name,
+  schema and patch format. Every add, update, move and delete goes through the
+  guarded file operations, so the Project files / Outside project levels apply:
+  Write refuses deletes and moves outside disposable places, Read refuses
+  writes, credential files and protected paths are refused. The whole patch is
+  checked first; no file is left half-patched, and a failure part-way reports
+  what was and wasn't applied. It is added for a child that may `edit` or
+  `write`, or asks for it.
+- **Trusted:** third-party tools you tick (default `web_fetch` and `web_search`).
+  Their package is loaded into the child and they run in the child Pi process,
+  **outside the file rules**. The child admits one only when both its name and
+  its package match the ticked entry, so another package registering the same
+  name is refused. A single extension file with no package manifest is loaded
+  and admitted by itself, never its directory. Known network tool names
+  (`web_fetch`, `web_search`, `firecrawl_scrape`, `firecrawl_extract`, `mcp`, `mcpScript`, `remote_bash`, and any `mcp__*` name) are refused while Network access is Off; this is a name list, not a
+  network sandbox. A ticked tool whose package can't be found is refused at launch. Ticked tools
+  join the default tool list; an explicit `tools` list still decides.
+
+Other tools are disabled in confined children and listed in launch output with
+the reason. The launch line shows what was admitted, for example
+`Runtime: isolated · guarded apply_patch · trusted web_fetch (@juicesharp/rpiv-web-tools)`.
+Provider extensions are trusted runtime code; arbitrary extension tools are not
+admitted merely because their names were requested. Confined children disable project
+runtime configuration and inherited extension discovery. Startup or backend
+failure never falls back to an unconfined child.
+
+You still start Pi normally. The subagent package's internal launcher requires
+Pi SDK 0.82.1 or newer; it is not a replacement user-facing Pi command.
+
+### Git-mutating subagents and linked worktrees
+
+A sandboxed subagent that will mutate Git should set **`git_clone_workspace:true`**
+on `subagent_spawn`. The parent prepares a fresh, self-contained Git clone whose
+`.git/` directory lives **inside the sandbox writable root**, then runs the child
+in that clone.
+
+Why this matters: a linked Git worktree (created with `git worktree add`) has a
+`.git` file that points back to administrative state under the main repository,
+typically outside the sandbox directory. A sandbox that only allows writes under
+the worktree directory therefore cannot support normal Git producer operations
+such as fetch, rebase, commit, and push — the child stalls or fails when Git
+tries to write metadata it cannot reach. `git_clone_workspace:true` avoids this
+by cloning the repository with a real `.git/` directory inside the writable root.
+
+The clone uses:
+
+```
+git clone --reference-if-able <local-reference-repo> --dissociate \
+          <remote-url> <sandbox-workspace>
+```
+
+`--reference-if-able` borrows local objects from the parent repository during
+setup; `--dissociate` removes the alternates link afterwards, so the clone is
+self-contained and safe to delete. The clone source prefers the source
+workspace's upstream remote URL (`origin` when set) so the disposable
+workspace's `origin` points at the real remote rather than the parent working
+tree — pushes therefore target upstream, not the sandboxed parent. The local
+repository is used only as a reference (and as a content fallback when no
+remote is configured). Source remotes are re-synced after clone. The
+checked-out branch/commit matches the source workspace at spawn time.
+Repo-local Git identity settings from the source (`user.name`, `user.email`,
+and `user.signingkey` when set) are copied into the clone so ordinary commits
+work without reconfiguring identity inside the disposable workspace.
+
+If the source workspace is a linked worktree, the clone is prepared from the
+main repository's object database and the requested branch/commit; the child is
+never launched into the structurally broken linked-worktree sandbox. If clone
+preparation fails, the spawn fails fast with a message explaining that the
+linked-worktree Git metadata is outside the sandbox and recommending
+`git_clone_workspace:true`.
+
+The mandatory task guard is independent of optional guardrails extensions.
+Adding a package to the tool map does not make its tools safe to execute outside
+the task boundary.
+
+## Tool scoping (allowlist)
+
+Precedence, highest first: the per-call `tools` param → `config.json`
+`defaultTools` → a built-in default (`read, bash, edit, write, web_search,
+web_fetch`; just `read, bash` in a `clean` child). `exclude_tools` subtracts on
+top.
+
+`config.json` (next to the extension) also sets:
+
+- `defaultModel` — model for spawns that don't specify one (`null` = inherit the
+  foreground model).
+- `delegationMode` — foreground policy (`manual`, `adaptive`, or `coordinator`;
+  default `adaptive`). `/subagents mode ...` changes only the current session.
+- `maxConcurrent` — how many subagents may run at once (**default 4**). A spawn
+  past the cap is rejected until a running one finishes.
+
+## The allowlist also decides what LOADS
+
+For confined children, the requested list is first restricted to tools with
+verified task adapters and the trusted tools ticked in `/sandbox`; only the
+ticked tools' packages load. `toolExtensions` still chooses which package to
+load for a tool (an override), but the child admits it only if that is the
+ticked package. Provider extensions can still load as trusted runtime
+dependencies. Nested spawning and
+inherited extension discovery are currently unavailable under confinement.
+
+The mapping behavior below applies to unconfined children and to admitted
+runtime dependencies:
+
+The `tools` allowlist does double duty: it is both what the child may call **and**
+which extension *code* is loaded into it. A child launches as
+
+```
+pi -p --mode json --no-extensions -e <package backing a requested tool> ...
+```
+
+so a package that backs no requested tool never loads. With the default
+allowlist (`read, bash, edit, write, web_search, web_fetch`) exactly one package
+loads — the web-tools one — and `web_fetch` works normally.
+
+Two maps in `config.json` drive it:
+
+- `toolExtensions` — tool name → package(s) providing it. Built-ins (`read`,
+  `bash`, `edit`, `write`) need no entry.
+- `providerExtensions` — provider → auth package. Model auth is not tool-shaped:
+  `xai/grok-4.5` needs `pi-xai-oauth` loaded whatever tools it was granted.
+
+Ask for a tool with no mapping and the spawn still succeeds, but says so at
+launch — the tool simply will not exist in the child.
+
+`clean:true` is the narrowest case of the same mechanism: no extensions at all.
+For unconfined children, `allow_nested:true` loads this package into the child;
+without it, nested spawning is unavailable. Confined children disable nesting
+regardless of this flag until a verified adapter exists.
+
+`inheritExtensions: true` in `config.json` restores the old load-everything
+behavior. It is **operator-only** — no spawn parameter can reach it, so the child
+model cannot widen its own runtime. It also re-exposes the failure below.
+
+### Why: a subagent that loads everything can die mid-turn reporting success
+
+Loading every installed package means inheriting their startup side effects. A
+package that replaces builtin `bash` with a `detached` + `unref()` spawn breaks
+`pi -p`: on a parallel `bash` + `read` batch the in-process `read` finishes, the
+unref'd `bash` doesn't hold the event loop, Node drains, and the child **exits 0
+mid-turn** — no `tool_execution_end`, no `agent_end`. Historically, exit 0 was
+indistinguishable from a clean finish, so all 17 observed mid-turn exits were
+reported as ✓ completed. Finalization now requires terminal agent evidence and
+no unmatched tool starts. Lifecycle validation classifies runs as `complete`,
+`incomplete_no_terminal_event`, `incomplete_open_tools`, `failed_exit`, or
+`killed`; incoherent exit-0 streams are recorded as failed with named lifecycle
+diagnostics on `subagent_result` and attention wording on completion callbacks.
+
+A tool allowlist alone cannot fix this. `--tools` restricts what the model may
+*call*; the package already overrode builtin `bash` at startup, so the `bash` in
+your allowlist **is** the broken one. Measured with the default 6 tools:
+
+| runtime | tool starts / ends | terminal event |
+|---|---|---|
+| all extensions loaded | 2 / 1 | none — exits 0 mid-turn |
+| `--no-extensions -e <web-tools>` | 3 / 3 | `agent_settled`, `web_fetch` OK |
+
+A package *denylist* isn't expressible either: pi has only `-e <path>` (add one)
+and `--no-extensions` (all off) — there is no "load all except X" flag. Naming
+what you want is the only mechanism that excludes anything, and it excludes
+future offenders too, with no name to keep updated.
+
+### Known incompatibility: `pi-patty-bg-tasks`
+
+**`pi-patty-bg-tasks` (tested at 1.1.6) is incompatible with subagents and must
+not be loaded into a child.** It is the package that produced the failure above:
+it replaces builtin `bash` and spawns `detached` + `proc.unref()`
+(`src/spawn.ts`), which in print mode drains the event loop mid-turn. Bisected
+against all 18 installed packages — alone it reproduces; every other package
+alone is fine.
+
+The default configuration already excludes it, structurally, because it backs no
+requested tool. You only re-expose it by setting `inheritExtensions: true`, or by
+mapping a tool to it in `toolExtensions`. Don't.
+
+A proper fix belongs upstream — preserve builtin `bash` semantics when overriding
+it, keep foreground subprocesses referenced until the tool promise settles, and
+put genuinely detached work behind a separate background-task tool.
+
+## Status & cost tracking
+
+Driven by the child's `--mode json` usage events:
+
+- **Live widget** above the editor while any subagent runs — a spinner per run
+  with elapsed time, the current tool, and running token/cost spend, ticking once
+  a second. It clears itself when the last run finishes. (TUI/RPC only; silent in
+  `-p`/print mode.)
+- **On demand** — `subagent_list`, `subagent_output`, and `subagent_result` are
+  bounded current-session pages (see `docs/issue-312-output.md`). They omit
+  ordered tool-name sequences and default token/cost lines. Pass
+  `include: ["cost"]` to `subagent_output` or `subagent_result` for one spend
+  line (`spend: 1.2k tok (↑400 ↓800) · $0.0034`) and `include: ["tools"]` for
+  one tool-call line (`tools: 7 calls · distinct: bash, read, edit`). The human
+  toast may still include elapsed + spend; the model-facing callback does not.
+- **Folded result display.** In interactive TUI sessions, `subagent_result`
+  renders a compact preview by default so long child answers do not flood the
+  transcript. Clicking the tool row, or using the row expand action, shows the
+  full bounded result. This is a display concern only: the tool still returns
+  the complete bounded `content` payload to the model.
+
+Spend is summed from each finalized assistant turn's `usage` (so multi-turn
+tool-using runs total correctly), and cost comes straight from the model's
+reported per-request cost.
+
+## Subagent navigator (TUI)
+
+In an interactive TUI session, a **subagent navigator** lets you inspect and
+organize runs without asking the model to call a tool. The running-subagents
+widget can be focused from an empty input line for quick actions; detail output
+opens in the overlay. Print/RPC modes do not install the navigator; tool access
+is unchanged in every mode.
+
+### Open
+
+- With the editor **empty** and at least one non-dismissed current-parent run
+  still running, press `←` to focus the main-window subagent list above the
+  input line.
+- If the editor contains text, `←` keeps normal cursor-left behavior.
+- While running runs exist, the default footer shows `← subagents · N`. The
+  live widget also includes a secondary `← to navigate` hint on its title line
+  for terminals that do not render the default footer status. The hint clears
+  when no non-dismissed current-parent run is still running.
+- While the main-window list is focused, the title hint changes to
+  `Enter to view · x to stop`; the selected row is marked with `›`. Press
+  `↓` from the bottom row to return to the input line.
+- The Subagents lane pins an informational `main` row above child runs. It
+  shows the foreground model, effort, active tool, context tokens, and active
+  elapsed time. It is not selectable and can never become an `x` stop target.
+- `↑` moves to the previous row when multiple running rows are shown. `↓`
+  moves toward the input line, returning to normal input from the bottom row.
+- `Enter` opens the selected run's live detail view. `x` stops the selected
+  running run using shared `subagent_stop` semantics and dismisses it from the
+  navigator.
+
+### Detail view
+
+- Detail uses the same command-sheet treatment, with section rules for the
+  inspector groups and command bars at the top and bottom of the view.
+- Tool-call log rows wrap within the detail width instead of truncating. Source
+  row boundaries and indentation are retained, with long paths and JSON values
+  preferring delimiter breaks before a hard wrap. Header and metadata geometry
+  is unchanged.
+- Shows status (colorized), model/effort, elapsed, tools, spend, and parsed
+  output, plus sectioned health: process identity/liveness, activity,
+  compaction, active tool, model call/error, last log write, thresholds, and
+  callback notification timestamps. Compaction, active tool, and model state
+  are separate sections. The view refreshes about once per second while open.
+- The transcript shows up to the latest 25 rows by default; `l` switches
+  between 25 and 10 rows. The row count is a cap, not a guarantee: the metadata
+  lines (provider, id, model, elapsed, tools, spend, pid, pgid) always stay
+  visible, and on a short terminal the transcript shows only as many of its
+  newest rows as fit below them. `subagent_result` and `subagent_output` page
+  sizes are unaffected.
+- Detail opened from the main-window list closes back to the main page; the
+  main-window selection remains on the viewed run when it is still visible.
+- `x` arms Stop for a running run, or Dismiss for a terminal run.
+- `esc` closes the detail view and returns to the main page.
+
+### Two-press `x` stop/dismiss
+
+- First `x` on the selected (list) or viewed (detail) run arms the action for three
+  seconds and shows a footer hint: `x again to stop <name>` while running, or
+  `x again to dismiss <name>` when terminal.
+- Second `x` within the window, on the **same** run, acts:
+  - **Running** — stop the process group (shared `subagent_stop` semantics),
+    mark killed, then dismiss from the navigator.
+  - **Terminal** — dismiss only; terminal status is not rewritten.
+- Changing selection, leaving the view, closing the overlay, arming timeout,
+  reload, and session teardown all disarm close and clear the confirm hint.
+
+### Dismissal is navigator-only
+
+Dismissed runs leave the navigator list and footer count. Logs, prompt, session
+data, metadata, and id-based tool access stay intact. `subagent_list`,
+`subagent_output`, `subagent_result`, and `subagent_stop` still resolve dismissed
+run ids. Dismissal survives `/reload` as dismissed in the navigator.
+
+### Reload and teardown
+
+`/reload` and session restart reinstall the empty-editor wrapper without stacking
+duplicate handlers, republish the footer count, and clear any leftover overlay
+timers or close-confirm state. Session shutdown disposes open navigator timers
+and clears navigator footer statuses (TUI only).
+
+## Design notes
+
+- Runtime lives outside any repo, under `$TMPDIR/pi-better-subagents/`
+  (`runs/<id>/` holds `output.log`, `prompt.md`, `meta.json`; `sessions/` holds
+  child session state). The `meta.json` sidecar is authoritative, so `list` /
+  `output` / `result` survive turns, `/reload`, and pi restarts.
+- The child runs `--mode json`; `subagent_result` / `subagent_output` **parse**
+  the event stream and return just the bounded final answer (no tool-name history).
+  Non-JSON banner/warning lines fail to parse and are dropped, so the result is
+  clean. The prompt is passed as a **positional argument**, never `@file` — some
+  models refuse an @-attached file as untrusted content.
+- The child gets **only** the explicit prompt — no silent parent-context bleed.
+- `--approve` is **off by default** (headless runs can't prompt for trust).
+
+
+## Parent-process scoping
+
+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.
+
+## Supervision health (`orphaned` / `lost`)
+
+While a current-parent run is `running` or `orphaned`, a periodic health tick
+reconciles process-group evidence only (see `docs/adr/0002-process-group-only-subagent-health.md`):
+
+- **`orphaned`** — direct supervision of the child is broken, but related
+  process-group work may still be alive. Non-terminal and non-final; operationally
+  unhealthy immediately. The coordinator (when `callback:true`) gets one durable
+  ATTENTION follow-up naming `subagent_result` / `subagent_output` / `subagent_stop`
+  so it can inspect artifacts and decide whether to wait, stop, or retry. Human
+  `ui.notify` still fires when `callback:false`.
+- **`lost`** — no related process remains and no coherent terminal completion was
+  observed. Terminal with unknown outcome (not the same as `failed`). Same one-shot
+  ATTENTION follow-up + diagnostic `subagent_result` path with best-available
+  artifacts.
+
+Orphaned/lost callbacks use the same non-interrupting
+`{ deliverAs: "followUp", triggerTurn: true }` mechanics, but bypass the ordinary
+completion accumulation window and retain distinct ATTENTION wording. Per-status
+markers on `meta.json` (`orphanedCallbackSentAt` / `lostCallbackSentAt`) are written
+only after a successful handoff and dedupe across reloads and repeated health ticks.
+Persisted unmarked orphaned/lost states are recovered on the health ticker after
+`/reload` even when process evidence does not produce a fresh transition.
+
+Pi's optional `followUpMode: all` remains useful when completion groups arrive
+after an earlier 100 ms batch has already flushed: Pi can consume those queued
+follow-ups in one later agent turn. This extension does not change Pi core or
+Pi's default follow-up mode.
+
+### Surfacing health (tools + passive widget)
+
+Multi-dimensional observations (`stale`, long tool, compacting / long compaction,
+model error/retry, plus process `orphaned` / `lost`) are computed from durable
+status + child-event evidence and surfaced on existing paths without a parallel
+health model:
+
+- **`subagent_list`** — durable `orphaned` / `lost` status brackets; degraded
+  compact facts only when actionable. Healthy/quiet rows stay on the compact format.
+- **`subagent_output` / `subagent_result`** — `[health: …]` diagnostics for
+  orphaned, lost, and degraded running runs; #65 orphaned/lost result bodies kept.
+- **Passive live widget** — healthy/quiet unchanged; degraded (and orphaned) may
+  show a short suffix. Still `setWidget` only — never focusable.
+- **`callback:false`** suppresses coordinator follow-up only; human `ui.notify` and
+  TUI/passive visibility remain.
+
+## Install
+
+Linux sandboxing requires the system `bubblewrap` package. Install it before
+launching sandboxed children:
+
+```bash
+# Debian/Ubuntu
+sudo apt-get install bubblewrap
+# Fedora/RHEL
+sudo dnf install bubblewrap
+# Arch Linux
+sudo pacman -S bubblewrap
+```
+
+When `bwrap` is absent, explicit sandbox requests fail with an installation hint;
+default-on sandboxing preserves the documented direct-execution fallback. Once
+`bwrap` is selected, a launch failure fails closed rather than retrying the child
+without confinement.
+
+Symlink the project into pi's auto-discovered extensions dir:
+
+```bash
+ln -sfn "$PWD" ~/.pi/agent/extensions/pi-better-subagents
+```
+
+Then `/reload` (or restart pi). It appears as `pi-better-subagents`.
+
+> Do **not** add it to `settings.json`'s `extensions` array — a live pi session
+> rewrites that file on its own saves and drops hand-added entries. Auto-discovery
+> via the symlink is stable. Quick throwaway test without installing:
+> `pi -e ./index.ts`.
+
+## Tests
+
+Unit tests (`node --test tests/*.test.mjs`) cover the pure logic — widget
+rendering, completion delivery, and extension resolution.
+
+Real integration smoke tests live in [`tests/`](tests/) — a subagent using
+`web_fetch`, one driving `gh`, env inheritance through the sandbox, and headless
+isolation surviving a parallel `bash` + `read` batch. See
+[`tests/README.md`](tests/README.md).
+
+## Roadmap
+
+Tracked in [issues](https://github.com/1aboveio/pi-better-subagents/issues).
+Near-term:
+
+- Guarantee subagent autonomy — verify/deny any child→parent supervision
+  back-channel so a child can never block on the parent ([#1](https://github.com/1aboveio/pi-better-subagents/issues/1)).
+- Make `callback:true` a lightweight trigger instead of embedding the full result
+  twice ([#2](https://github.com/1aboveio/pi-better-subagents/issues/2)) — **done**.
+- Named agent-definition files (per-agent system prompt + tool allowlist) and
+  chain/parallel orchestration.

package/index.ts

@@ -17,7 +17,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
 import * as PiTui from "@earendil-works/pi-tui";
 import { CustomEditor } from "@earendil-works/pi-coding-agent";
-import { matchesKey, Key, truncateToWidth } from "@earendil-works/pi-tui";
+import { matchesKey, Key, truncateToWidth, type AutocompleteItem } from "@earendil-works/pi-tui";
 import { Type } from "@earendil-works/pi-ai";
 import {
     CLOSE_CONFIRM_STATUS_KEY,
@@ -103,7 +103,8 @@ import {
 } from "./health.ts";
 import {
     assignBatchJobNames,
-    formatBatchLaunchResponse,
+    batchLaunchOutputSchema,
+    batchLaunchResult,
     mergeJobOptions,
     nextBatchId,
     planBatchLaunches,
@@ -160,6 +161,18 @@ import {
 } from "./catalog-runtime.ts";
 import { defaultUserRoot, type CatalogSnapshot } from "./catalog-store.ts";
 
+const SUBAGENT_MODE_ACTIONS: readonly AutocompleteItem[] = [
+    { value: "mode manual", label: "mode manual", description: "Delegate only when explicitly requested" },
+    { value: "mode adaptive", label: "mode adaptive", description: "Delegate substantial independent work" },
+    { value: "mode coordinator", label: "mode coordinator", description: "Delegate role-owned work by default" },
+];
+
+export function subagentsArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+    const prefix = argumentPrefix.trimStart().toLowerCase();
+    const matches = SUBAGENT_MODE_ACTIONS.filter((action) => action.value.startsWith(prefix));
+    return matches.length > 0 ? [...matches] : null;
+}
+
 /** The tools this extension registers — excluded from children by default so a
  *  subagent cannot recursively spawn more subagents unless explicitly allowed. */
 const SUBAGENT_TOOLS = [
@@ -1792,7 +1805,7 @@ export default function (pi: ExtensionAPI) {
             "The tools param is both the tool allowlist AND what determines which extensions load in the child (e.g. tools='read,bash,web_fetch' loads only the web-tools package). Ask for the tools the task needs and nothing more; clean:true gives a built-ins-only child. Without an agent or role, pick a model with the model param (e.g. 'xai/grok-4.5@high'); providerless model patterns are resolved by Pi, while provider/model is deterministic and loads mapped provider extensions.",
             ...CATALOG_GUIDELINES,
             "By default the subagent is sandboxed. Human settings in /sandbox control file, credential-file, command, and network permissions; sandbox:false cannot override an enabled human profile. Without published settings, legacy write confinement applies. Set callback:false to finish quietly — then read the result on demand via subagent_result.",
-            "Every run is timed by the harness: a soft deadline (default 30 min) steers the child to wrap up and wakes you once, the run is stopped after grace_minutes (reason deadline), a hard ceiling (default 90 min) stops it without grace (reason ceiling), and no progress for stuck_minutes (default 10) wakes you once (reason stuck). Set deadline_minutes/max_minutes/stuck_minutes to fit the task instead of writing a time limit into the prompt; do not stop a slow child that is still making progress.",
+            "Every run has harness-owned stall detection: no progress for stuck_minutes (default 10) wakes you once without stopping the run. Elapsed-time limits are opt-in: deadline_minutes steers the child to wrap up and later stops it after grace_minutes, while max_minutes stops it without grace. Do not set elapsed-time limits merely because a task may take a while; use them only when the work needs a real wall-clock bound.",
             "Use git_clone_workspace:true when the subagent will mutate Git in a sandbox. The parent prepares a disposable, self-contained clone with a real .git/ directory inside the sandbox root, so linked-worktree metadata outside the sandbox cannot stall the child.",
         ],
         parameters: Type.Object({
@@ -1890,7 +1903,12 @@ export default function (pi: ExtensionAPI) {
         description:
             "Launch several independent background pi subagents at once. Each job becomes a " +
             "normal subagent run with its own run id, process, log, and metadata. " +
-            "'shared' options are applied to every job; per-job options override them.",
+            "'shared' options are applied to every job; per-job options override them. " +
+            "Codemode callers receive a structured launch receipt: status, batchId when assigned, " +
+            "and launched, failed, skipped arrays with 1-based effective job positions (after any confirmed role split). Inspect all arrays; " +
+            "a returned receipt is not proof that every job launched or completed. " +
+            "Await the launch call and preserve its receipt. Script cancellation does not stop launched runs; use subagent_stop.",
+        outputSchema: batchLaunchOutputSchema,
         promptSnippet: "Launch a batch of background subagents at once",
         promptGuidelines: [
             "When delegation is permitted by the active mode, use subagent_spawn_batch for several independent assigned tasks. It returns immediately with a batch id and one run id per launched job.",
@@ -1981,7 +1999,17 @@ export default function (pi: ExtensionAPI) {
                     p.jobs.map((job) => mergeJobOptions(p.shared, job) as CatalogJobFields),
                     { hasUI: catalogHost.hasUI === true, select: catalogHost.select },
                 );
-                if (clarified.status === "clarification-needed") return catalogResult(clarified) as ReturnType<typeof text>;
+                if (clarified.status === "clarification-needed") return {
+                    ...catalogResult(clarified),
+                    structuredContent: {
+                        status: "clarification-needed",
+                        message: clarified.message,
+                        choices: [...clarified.choices],
+                        launched: [],
+                        failed: [],
+                        skipped: [],
+                    },
+                };
                 p.jobs = clarified.jobs as typeof p.jobs;
                 validateBatchPlan({ shared: undefined, jobs: p.jobs, onCapacity: p.onCapacity, config: cfg });
             }
@@ -2011,9 +2039,9 @@ export default function (pi: ExtensionAPI) {
 
             const names = assignBatchJobNames(p.jobs);
             const batchId = nextBatchId();
-            const launched: { name: string; id: string; modelNote?: string }[] = [];
-            const failed: { name: string; reason: string }[] = [];
-            const skipped: { name: string }[] = [];
+            const launched: { job: number; name: string; id: string; modelNote?: string }[] = [];
+            const failed: { job: number; name: string; reason: string }[] = [];
+            const skipped: { job: number; name: string }[] = [];
             // How many reject-mode reserved slots are still held (not yet committed/released).
             let reservedRemaining = launchAvailable ? 0 : p.jobs.length;
 
@@ -2027,7 +2055,7 @@ export default function (pi: ExtensionAPI) {
                 if (launchAvailable) {
                     if (!gate.tryReserve(1, maxConcurrent)) {
                         for (let j = i; j < p.jobs.length; j++) {
-                            skipped.push({ name: names[j] });
+                            skipped.push({ job: j + 1, name: names[j] });
                         }
                         break;
                     }
@@ -2052,12 +2080,12 @@ export default function (pi: ExtensionAPI) {
                     const { id, modelNote } = await spawnSubagentRun(ctx, { ...merged, name }, { batchId, batchName: p.batchName });
                     gate.commit(1);
                     if (!launchAvailable) reservedRemaining -= 1;
-                    launched.push({ name, id, ...(modelNote ? { modelNote } : {}) });
+                    launched.push({ job: i + 1, name, id, ...(modelNote ? { modelNote } : {}) });
                 } catch (err) {
                     gate.release(1);
                     if (!launchAvailable) reservedRemaining -= 1;
                     const reason = err instanceof Error ? err.message : String(err);
-                    failed.push({ name, reason });
+                    failed.push({ job: i + 1, name, reason });
                     if (!launchAvailable) {
                         // reject mode: leave already-launched runs running, release any
                         // still-held later reservations, and report every later job as failed.
@@ -2067,13 +2095,14 @@ export default function (pi: ExtensionAPI) {
                         }
                         for (let j = i + 1; j < p.jobs.length; j++) {
                             failed.push({
+                                job: j + 1,
                                 name: names[j],
                                 reason: "not launched due to earlier job failure in reject mode",
                             });
                         }
-                        return text(formatBatchLaunchResponse({
+                        return batchLaunchResult({
                             batchId, batchName: p.batchName, launched, skipped, failed,
-                        }));
+                        });
                     }
                     // launch-available: failure did not consume a slot — continue so
                     // later jobs can use remaining capacity (backfill).
@@ -2086,7 +2115,7 @@ export default function (pi: ExtensionAPI) {
                 reservedRemaining = 0;
             }
 
-            return text(formatBatchLaunchResponse({ batchId, batchName: p.batchName, launched, skipped, failed }));
+            return batchLaunchResult({ batchId, batchName: p.batchName, launched, skipped, failed });
         },
     });
 
@@ -2138,6 +2167,7 @@ export default function (pi: ExtensionAPI) {
         agentOperations.registerCommands(pi);
         pi.registerCommand("subagents", {
             description: "Show or change the current-session delegation mode",
+            getArgumentCompletions: subagentsArgumentCompletions,
             async handler(args, ctx) {
                 const tokens = args.trim().split(/\s+/).filter(Boolean);
                 if (tokens.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",
@@ -47,6 +47,7 @@
     "config.json",
     "README.md",
     "roles/**/*.md",
+    "docs/usage.md",
     "docs/agent-catalog.md",
     "docs/agent-catalog-operations.md",
     "docs/agent-model-resolution.md",

package/roles/role.developer.md

@@ -5,7 +5,7 @@ id: role.developer
 name: Developer
 description: Owns implementation and focused tests; excludes architecture policy and independent review.
 defaults:
-  model: openai/gpt-6-sol
+  model: openai/gpt-6.1-sol
   effort: high
   tier: balanced
 ---

package/roles/role.product-manager.md

@@ -5,7 +5,7 @@ id: role.product-manager
 name: Product Manager
 description: Owns user-visible requirements and acceptance criteria; excludes technical design and implementation.
 defaults:
-  model: openai/gpt-6-sol
+  model: openai/gpt-6.1-sol
   effort: medium
   tier: balanced
 ---

package/roles/role.researcher.md

@@ -5,7 +5,7 @@ id: role.researcher
 name: Researcher
 description: Owns external-source evidence and factual uncertainty; excludes repo mapping and changes.
 defaults:
-  model: openai/gpt-6-sol
+  model: openai/gpt-6.1-sol
   effort: medium
   tier: balanced
 ---

package/shared-sandbox-core.ts

@@ -228,10 +228,7 @@ const CREDENTIAL_LOCATIONS = [
     ".docker/config.json", ".npmrc", ".netrc", ".git-credentials", ".pi/agent/auth.json",
 ] as const;
 
-/**
- * Credential stores added by the broad-write profile. They are never readable
- * or writable there, whatever the Stored credentials row says.
- */
+/** Credential stores added to the Stored credentials row by the broad-write profile. */
 const BROAD_CREDENTIAL_LOCATIONS = [
     "Library/Keychains", ".claude/.credentials.json", ".claude.json", ".gnupg",
     ".codex/auth.json", ".cargo/credentials.toml", ".cargo/credentials", ".pgpass", ".config/rclone",
@@ -386,10 +383,7 @@ function compile(
     return {
         writableRoot, denyWrite, home: policy.home,
         ...(policy.permissions && {
-            // The broad-write profile's credential deny list is not optional.
-            permissions: broadMode
-                ? { ...policy.permissions, storedCredentials: "off" as const }
-                : { ...policy.permissions },
+            permissions: { ...policy.permissions },
             credentialPaths: broadMode ? broadCredentialPaths(policy.home, seams) : credentialFilePaths(policy.home, seams),
             compatibilityWrite,
             runtimeWrite,
@@ -598,7 +592,7 @@ export function evaluateReadAccess(
     const permissions = policy.permissions;
     if (!permissions) return { allowed: true, path };
     if (policy.broad) {
-        const denied = isCredential(path, policy) ||
+        const denied = (isCredential(path, policy) && permissions.storedCredentials === "off") ||
             (permissions.projectFiles === "off" && contains(policy.writableRoot, path));
         return denied ? { allowed: false, path, reason: "read-denied" } : { allowed: true, path };
     }
@@ -652,7 +646,8 @@ function evaluateBroadWrite(
     for (const denied of [...policy.denyWrite, ...broad.codePaths]) {
         if (contains(denied, path)) return { allowed: false, path, reason: "write-denied", deniedBy: denied };
     }
-    if (isCredential(path, policy)) return { allowed: false, path, reason: "permission-denied" };
+    if (isCredential(path, policy)) return canWrite(policy.permissions!.storedCredentials)
+        ? { allowed: true, path } : { allowed: false, path, reason: "permission-denied" };
     if (policy.runtimeWrite?.some((root) => contains(root, path))) return { allowed: true, path };
     if (contains(policy.writableRoot, path)) {
         return canWrite(policy.permissions!.projectFiles)
@@ -808,7 +803,8 @@ export function resetRecoverySnapshotClock(): void {
 }
 
 function broadProtectedPaths(policy: CompiledSandboxWritePolicy, broad: CompiledBroadWrite): string[] {
-    return [...policy.denyWrite, ...(policy.credentialPaths ?? []), ...broad.codePaths,
+    return [...policy.denyWrite,
+        ...(policy.permissions?.storedCredentials === "read-write" ? [] : policy.credentialPaths ?? []), ...broad.codePaths,
         ...(!canWrite(policy.permissions?.projectFiles) ? [policy.writableRoot] : [])];
 }
 
@@ -927,7 +923,7 @@ function buildBroadProfile(policy: CompiledSandboxWritePolicy, seams: SandboxSea
         `(allow file-write-unlink (regex #"^${home}/(.+/)?[.]worktrees/."))`,
         `(allow file-write-unlink (regex #"^${home}/(.+/)?[^/]+-worktrees/."))`,
     );
-    // The fixed deny list overrides every grant above. A rule naming
+    // Write-denied controls and credentials override every broad grant above. A rule naming
     // `file-write-unlink` outranks a `file-write*` wildcard whatever their
     // order (verified on the real kernel), so each protected path also gets an
     // explicit unlink denial; otherwise the removal grants above would reopen it.
@@ -936,8 +932,8 @@ function buildBroadProfile(policy: CompiledSandboxWritePolicy, seams: SandboxSea
     if (!canWrite(permissions.projectFiles)) denyWrite(project);
     for (const path of broad.codePaths) denyWrite(path);
     for (const path of policy.credentialPaths ?? []) {
-        rules.push(`(deny file-read* (subpath ${sbpl(path)}))`);
-        denyWrite(path);
+        if (permissions.storedCredentials === "off") rules.push(`(deny file-read* (subpath ${sbpl(path)}))`);
+        if (permissions.storedCredentials !== "read-write") denyWrite(path);
     }
     for (const path of policy.denyWrite) denyWrite(path);
     // Renaming an ancestor would move a protected subtree to an unprotected path,
@@ -1350,9 +1346,11 @@ function maskSources(profilePath: string): { directory: string; file: string } {
  * the root is read-only; temp, the workspace, hidden home entries and worktree
  * folders are writable (removal included); ordinary top-level home folders and
  * home itself stay read-only, so sibling repositories cannot even be edited in
- * place there. Credentials are masked by empty mode-000 mounts; code that runs
- * later and caller-denied paths are read-only binds. Every writable bind and
- * protected leaf is a mount point, which Linux refuses to rename. A protected
+ * place there. Off credentials are masked by empty mode-000 mounts, Read
+ * credentials are read-only binds, and Read / write credentials follow the
+ * surrounding broad-write rules. Code that runs later and caller-denied paths
+ * are read-only binds. Every writable bind and protected leaf is a mount point,
+ * which Linux refuses to rename. A protected
  * symlink inside a writable directory (a stow link in `~/.config`) makes that
  * directory read-only with each existing entry bound writable again, so only
  * new top-level entries there are refused.
@@ -1373,14 +1371,15 @@ function buildLinuxBroadCommand(
         throw new Error("Linux bubblewrap cannot separate removal from writing for Project files; use Write & delete or Read.");
     }
     const credentials = policy.credentialPaths ?? [];
+    const protectedCredentials = permissions.storedCredentials === "read-write" ? [] : credentials;
     const writeDenied = [...broad.codePaths, ...policy.denyWrite];
     if (permissions.projectFiles === "read-write" &&
-        [...credentials, ...writeDenied].some((path) => path !== project && contains(path, project))) {
+        [...protectedCredentials, ...writeDenied].some((path) => path !== project && contains(path, project))) {
         throw new Error("Linux bubblewrap cannot make a project writable inside a protected directory.");
     }
     const list = seams.listDirectory ?? systemListDirectory;
     const exists = (path: string) => (seams.pathExists ?? existsSync)(path);
-    const protectedPaths = [...credentials, ...writeDenied];
+    const protectedPaths = [...protectedCredentials, ...writeDenied];
     const insideProtected = (path: string) => protectedPaths.some((guard) => contains(guard, path));
 
     const writable = new Set<string>();
@@ -1498,7 +1497,10 @@ function buildLinuxBroadCommand(
             readOnly.add(path);
         }
     };
-    for (const path of credentials) guard(path, true);
+    for (const path of credentials) {
+        if (permissions.storedCredentials === "off") guard(path, true);
+        else if (permissions.storedCredentials === "read") guard(path, false);
+    }
     for (const path of writeDenied) guard(path, false);
     if (permissions.projectFiles === "read") readOnly.add(project);
 

package/tier-policy.ts

@@ -49,13 +49,13 @@ export interface NormalizedTierPolicy {
 }
 
 /**
- * Approved model membership only. `openai/gpt-6-sol`, `openai/gpt-6-luna`, and
+ * Approved model membership only. `openai/gpt-6.1-sol`, `openai/gpt-6-luna`, and
  * `openai/gpt-6-astra` are not fallbacks for each other.
  */
 export const DEFAULT_TIER_POLICY = {
     tiers: {
         efficient: { members: ["openai/gpt-6-luna"], candidates: [] },
-        balanced: { members: ["openai/gpt-6-sol"], candidates: [] },
+        balanced: { members: ["openai/gpt-6.1-sol"], candidates: [] },
         frontier: { members: ["openai/gpt-6-astra"], candidates: [] },
     },
 } as const satisfies TierPolicy;

package/timing.ts

@@ -1,5 +1,5 @@
 /**
- * Harness-owned run timing: a soft deadline with grace, a hard ceiling, and
+ * Harness-owned run timing: optional elapsed-time limits and default-on
  * no-progress (stuck) detection for every subagent run.
  *
  * Timeout control belongs to the harness, not to the prompt or the skill that
@@ -22,9 +22,10 @@
  * with null/absent optional fields treated alike as in #336). A successful
  * `edit`/`write`, a `git commit`, and a success directly after a failure always
  * count, even when repeated. Re-reading the same file or re-running the same
- * command with the same arguments does not. Time spent waiting on a running tool call does not count toward
- * the stuck window, so a child in the middle of a 20-minute test run is not
- * stuck; a hung command is bounded by the deadline and the ceiling instead.
+ * command with the same arguments does not. Time spent waiting on a running
+ * tool call does not count toward the stuck window, so a child in the middle
+ * of a 20-minute test run is not stuck. A caller that needs to bound a
+ * possibly hung command can opt into a ceiling.
  */
 
 import { createHash } from "node:crypto";
@@ -34,9 +35,9 @@ export type TimingReason = TimingStopReason | "stuck";
 
 /** Built-in defaults, in minutes. `0` disables that control. */
 export const DEFAULT_TIMING_MINUTES = Object.freeze({
-    deadline: 30,
+    deadline: 0,
     grace: 5,
-    max: 90,
+    max: 0,
     stuck: 10,
 });
 
@@ -151,9 +152,9 @@ export function resolveRunTiming(input: {
 // ---- tool parameters -------------------------------------------------------
 
 const TIMING_DESCRIPTIONS = {
-    deadline_minutes: "Soft deadline in minutes (default 30; 0 = none; null or omitted = inherit: in a batch job the shared value, otherwise the default). At the deadline the child is told to stop starting new work, commit what is done, and report, and you get one wake. Grace starts when the message reaches the child (after its current tool call); if it has not finished by then, the harness stops it with reason deadline.",
+    deadline_minutes: "Optional soft deadline in minutes (default: none; 0 = none; null or omitted = inherit: in a batch job the shared value, otherwise the default). At the deadline the child is told to stop starting new work, commit what is done, and report, and you get one wake. Grace starts when the message reaches the child (after its current tool call); if it has not finished by then, the harness stops it with reason deadline.",
     grace_minutes: "Minutes after the wrap-up message reaches the child before the run is stopped (default 5; null or omitted = inherit).",
-    max_minutes: "Hard ceiling in minutes (default 90; 0 = none; null or omitted = inherit). The run is stopped at once, without grace, with reason ceiling.",
+    max_minutes: "Optional hard ceiling in minutes (default: none; 0 = none; null or omitted = inherit). The run is stopped at once, without grace, with reason ceiling.",
     stuck_minutes: "No-progress window in minutes (default 10; 0 = off; null or omitted = inherit). Progress is any successful tool call that is not an exact repeat of an earlier one (same tool, same arguments); edits, writes, commits, and a success after a failure always count. Time inside a running tool call does not count. Wakes you once per stuck spell; never stops the run.",
 } as const;