@cr1ms0n/pi-subagent 0.8.7 → 0.8.9

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.8.9 — 2026-09-16
+
+### Restore the stable 0.8.7 behavior
+
+- Restore the `0.8.7` source behavior after the withdrawn `0.8.8` release. Remote Context ownership and model gating remain in the separate `pi-openai-toolkit` project.
+
 ## 0.8.7 — 2026-09-14
 
 ### Provider-safe tool schemas

package/docs/ARCHITECTURE.md

@@ -1,125 +1,125 @@
-# Architecture contract
-
-`pi-subagent` is split by ownership boundary:
-
-- `runner.ts`: one child process, Pi RPC protocol (JSONL commands on stdin, events on
-  stdout — a superset of `--mode json`), cancellation, process trees, budgets, and a live
-  stdin command channel used for mid-run steering. Extension UI dialogs from headless
-  children are auto-cancelled so they can never hang a run; stdin is closed after
-  `agent_settled` so RPC children shut down cleanly. Budget breaches steer a wrap-up
-  message and allow grace turns before SIGTERM (`wrappedUp` marks a clean conclusion).
-  A stall watchdog flags protocol silence, probes liveness via `get_state`, and kills
-  after a second window so retry can take over. Group kills verify process start-time
-  identity (Linux `/proc`, macOS/BSD `ps lstart`) before signalling a possibly-recycled
-  PID; transcript joins happen only on message boundaries, not per-chunk ticks.
-- Retry with model fallback lives in `orchestrator.ts` (`isTransientFailure`): queue
-  timeouts, stalls, spawn errors, and provider errors re-run the same spec on the next
-  fallback model with accumulated usage; task-quality failures never retry.
-- `context: "fork"` spawns the child with `--fork <parent session file>` so it starts
-  from a real branched copy of the parent conversation. Fail-fast when the parent
-  session is not persisted; single-task only.
-- `registry.ts`: one parent-session runtime, run state, snapshots, resume locks, and the
-  single LiveRun→snapshot/persisted-result projections used by every consumer.
-- `semaphore.ts`: per-parent-runtime child-process limit.
-- `process-lock.ts`: machine-wide durable coordination under `~/.pi/subagent-locks/` —
-  exclusive per-child-session resume locks, global concurrency slots, and run process
-  identity records for orphan reconcile.
-- `launch.ts`: resolve the child `pi` invocation via `PI_SUBAGENT_BIN` or
-  `process.execPath` + CLI entry (bare PATH name only as last-resort fallback).
-- `persistence.ts`: versioned active-branch event folding and bounded child transcript metadata.
-- `maintenance.ts`: filesystem GC (session files) and abort-race helpers; kept out of persistence.
-- `usage.ts`: provider-reported root/subagent/combined accounting.
-- `policy.ts` / `schema.ts`: discriminated request validation and safe capability profiles. `schema.ts` retains the canonical TypeBox validators and derives provider-safe tool-schema projections; `extension.ts` registers those projections while validating calls with the originals. Pi context-management control-plane tools remain available to child allowlists without granting project-file write access.
-- `config.ts`: defaults ← `~/.pi/subagent.json` ← `PI_SUBAGENT_*` env overrides.
-- `structured.ts`: structured-output contract (dependency-free JSON-Schema subset
-  validation, fenced json:result extraction, contract/repair prompts) and
-  conservative double-encoded-arg repair. The runner gates the child's settle on
-  validation and runs one steer-based repair round before accepting failure.
-- `agents.ts`: named agent files (`.pi/agents/`, `.agents/agents/`, global agent dir).
-  Flat-YAML frontmatter + markdown persona body; resolved in policy with explicit
-  params > agent file > profile taskDefaults > parent inheritance. Catalog refreshes
-  lazily (5s TTL) so new files work mid-session; symlinks and oversized files skipped.
-- `notifications.ts`: background-run completion batching. Successes group within a
-  debounce window (hard cap on hold time); failures bypass batching and flush
-  immediately; delivered-state is re-checked at flush time so a consuming `wait`
-  suppresses the redundant notification.
-- `ui.ts`: renderers, footer status and `/subagents` inspector. The ambient widget
-  (extension-side) shows BACKGROUND runs only — foreground runs render inline as the
-  tool result, so widget display would double-render them.
-- `extension.ts`: wiring only; no business logic. Nested children at the depth ceiling do
-  not re-register the tool; only top-level parents run maintenance.
-
-Invariants:
-
-1. A run belongs to exactly one parent session key and cannot update another session.
-2. No more than `maxActiveProcesses` children run per extension runtime, and no more than
-   `maxGlobalActive` across every Pi parent process on the machine.
-3. Cancellation prevents queued tasks from spawning.
-4. A child session may have only one direct resume writer at a time, enforced by an
-   in-memory lock *and* a durable file lock under `lockDir` that survives crashes and
-   coordinates across independent parent processes.
-5. Parallel write-capable tasks need isolated worktrees/distinct cwd or explicit unsafe opt-in.
-6. Every tool response is globally capped to 50 KB / 2,000 lines; full data lives in artifacts/transcripts.
-7. Status is compact; wait is the one-shot deliverable.
-8. On shutdown or tree navigation, child runs are cancelled and awaited for a bounded grace period.
-9. On startup, orphan process groups recorded under `lockDir` are reaped (SIGTERM then SIGKILL)
-   before any matching child session is eligible for resume. `$state: "lost"` is a labeling
-   that keeps `resumeBlocked` until reconciliation proves death.
-10. Billed usage is folded once per root message and once per full child run UUID.
-11. Checkpoint persistence events are lightweight (state, usage, process identity, pointers).
-    Full transcripts and final output are persisted exactly once, in the terminal event.
-12. High-frequency registry "changed" events coalesce (trailing window); state transitions,
-    new child sessions, billed-usage advances, and terminal events flush immediately.
-13. `wait` is interruptible: aborting a wait returns promptly and does NOT cancel the
-    background run. Only `cancel` (or parent shutdown) aborts a run.
-14. Budget stops (`max_turns`/`max_cost`) with at least one completed turn end as `partial`
-    and deliver their output normally. Streams truncated after useful assistant output also
-    end as `partial`. Timeouts report `state: "timeout"` with `timeoutPhase`.
-15. `timeout_ms` covers the whole task, including semaphore queue time, but the phase
-    (queued / starting / running) is recorded so agents can apply the right retry policy.
-16. Worktrees live under a durable root (`~/.pi/subagent-worktrees`), never a purgeable OS
-    tmpdir. Startup maintenance (top-level parents only) prunes stale git registrations,
-    removes unchanged leftovers, and sweeps changed-but-expired worktrees. Live-run
-    worktrees are always shielded. `include_wip` worktrees carry the parent's WIP patch in
-    the handle: `diff`/`apply` subtract it when subtraction is clean and otherwise report
-    the combined delta with an explicit `[includes parent WIP]` warning — never silently
-    wrong; a worktree containing only the untouched WIP patch counts as unchanged.
-17. Process-tree reaping after a clean exit can be disabled per task with `keep_background`
-    (for legitimately backgrounded work such as dev servers); forced stops always reap.
-18. Protocol completion prefers Pi's `agent_settled` event. Legacy `agent_end` without
-    `willRetry` is accepted for older Pi builds; `agent_end` with `willRetry: true` is
-    treated as non-terminal.
-19. Depth and spawn-policy parsing fail closed on malformed values: env scrubbing cannot
-    silently reset the depth counter to top-level, and a malformed `PI_SUBAGENT_SPAWNS`
-    disables spawning rather than unrestricting it.
-20. Budget breaches (`max_turns`/`max_cost`) steer a wrap-up message and allow grace
-    turns before SIGTERM; a child that concludes within grace ends `partial` with
-    `wrappedUp: true`. `graceTurns: 0` restores immediate stops.
-21. Transient failures (queued timeout, stall, spawn error, provider error, protocol
-    truncation) retry up to `maxRetries` extra attempts, escalating through
-    `fallback_models`; usage accumulates across attempts and `attemptedModels` is
-    recorded. Task-quality failures (nonzero exit with complete protocol, cancellation,
-    budget stop, running timeout) never retry.
-22. The stall watchdog treats protocol silence as suspect, not fatal: after
-    `stallAfterMs` the task is flagged and probed via `get_state` (a live child's
-    answer clears the flag); only continued silence for `stallKillAfterMs` more kills
-    the child — which is then a transient failure eligible for retry.
-23. Only `async: true` runs notify on completion and appear in the ambient widget.
-    Notification delivery respects delivered-once: a `wait` that consumed the run
-    suppresses the notification.
-24. Named agent files supply per-field defaults only; explicit request params always
-    win, and capability profiles fail closed regardless of what an agent file declares.
-25. Structured-output validation never discards paid work: schema failure after the
-    repair round downgrades completed → partial with `structuredError`, and the raw
-    text still delivers. Validation is enforced on the parent side of the process
-    boundary — the child cannot self-attest.
-26. Arg repair only decodes free-text fields with high-signal escape patterns
-    (literal \n or \") and no real newlines; identifier fields, tool lists, and
-    Windows-path-like strings are never modified.
-27. Global slots are depth-tiered: `tryAcquireGlobalSlot(runId, depth)` admits only while
-    `activeAtOrBelowDepth(depth) < maxGlobalActive - reservedFor(depth)`, holding slots
-    back for deeper tiers so a full-width spawn tree cannot deadlock on its own children.
-    Slot records without a `depth` field count as depth 0.
-28. `action: "plan"` is a truth oracle: it runs the exact validation and preflights of a
-    real spawn and returns the resolved plan without spawning — never a softer check, and
-    never a registry entry.
+# Architecture contract
+
+`pi-subagent` is split by ownership boundary:
+
+- `runner.ts`: one child process, Pi RPC protocol (JSONL commands on stdin, events on
+  stdout — a superset of `--mode json`), cancellation, process trees, budgets, and a live
+  stdin command channel used for mid-run steering. Extension UI dialogs from headless
+  children are auto-cancelled so they can never hang a run; stdin is closed after
+  `agent_settled` so RPC children shut down cleanly. Budget breaches steer a wrap-up
+  message and allow grace turns before SIGTERM (`wrappedUp` marks a clean conclusion).
+  A stall watchdog flags protocol silence, probes liveness via `get_state`, and kills
+  after a second window so retry can take over. Group kills verify process start-time
+  identity (Linux `/proc`, macOS/BSD `ps lstart`) before signalling a possibly-recycled
+  PID; transcript joins happen only on message boundaries, not per-chunk ticks.
+- Retry with model fallback lives in `orchestrator.ts` (`isTransientFailure`): queue
+  timeouts, stalls, spawn errors, and provider errors re-run the same spec on the next
+  fallback model with accumulated usage; task-quality failures never retry.
+- `context: "fork"` spawns the child with `--fork <parent session file>` so it starts
+  from a real branched copy of the parent conversation. Fail-fast when the parent
+  session is not persisted; single-task only.
+- `registry.ts`: one parent-session runtime, run state, snapshots, resume locks, and the
+  single LiveRun→snapshot/persisted-result projections used by every consumer.
+- `semaphore.ts`: per-parent-runtime child-process limit.
+- `process-lock.ts`: machine-wide durable coordination under `~/.pi/subagent-locks/` —
+  exclusive per-child-session resume locks, global concurrency slots, and run process
+  identity records for orphan reconcile.
+- `launch.ts`: resolve the child `pi` invocation via `PI_SUBAGENT_BIN` or
+  `process.execPath` + CLI entry (bare PATH name only as last-resort fallback).
+- `persistence.ts`: versioned active-branch event folding and bounded child transcript metadata.
+- `maintenance.ts`: filesystem GC (session files) and abort-race helpers; kept out of persistence.
+- `usage.ts`: provider-reported root/subagent/combined accounting.
+- `policy.ts` / `schema.ts`: discriminated request validation and safe capability profiles. `schema.ts` retains the canonical TypeBox validators and derives provider-safe tool-schema projections; `extension.ts` registers those projections while validating calls with the originals. Pi context-management control-plane tools remain available to child allowlists without granting project-file write access.
+- `config.ts`: defaults ← `~/.pi/subagent.json` ← `PI_SUBAGENT_*` env overrides.
+- `structured.ts`: structured-output contract (dependency-free JSON-Schema subset
+  validation, fenced json:result extraction, contract/repair prompts) and
+  conservative double-encoded-arg repair. The runner gates the child's settle on
+  validation and runs one steer-based repair round before accepting failure.
+- `agents.ts`: named agent files (`.pi/agents/`, `.agents/agents/`, global agent dir).
+  Flat-YAML frontmatter + markdown persona body; resolved in policy with explicit
+  params > agent file > profile taskDefaults > parent inheritance. Catalog refreshes
+  lazily (5s TTL) so new files work mid-session; symlinks and oversized files skipped.
+- `notifications.ts`: background-run completion batching. Successes group within a
+  debounce window (hard cap on hold time); failures bypass batching and flush
+  immediately; delivered-state is re-checked at flush time so a consuming `wait`
+  suppresses the redundant notification.
+- `ui.ts`: renderers, footer status and `/subagents` inspector. The ambient widget
+  (extension-side) shows BACKGROUND runs only — foreground runs render inline as the
+  tool result, so widget display would double-render them.
+- `extension.ts`: wiring only; no business logic. Nested children at the depth ceiling do
+  not re-register the tool; only top-level parents run maintenance.
+
+Invariants:
+
+1. A run belongs to exactly one parent session key and cannot update another session.
+2. No more than `maxActiveProcesses` children run per extension runtime, and no more than
+   `maxGlobalActive` across every Pi parent process on the machine.
+3. Cancellation prevents queued tasks from spawning.
+4. A child session may have only one direct resume writer at a time, enforced by an
+   in-memory lock *and* a durable file lock under `lockDir` that survives crashes and
+   coordinates across independent parent processes.
+5. Parallel write-capable tasks need isolated worktrees/distinct cwd or explicit unsafe opt-in.
+6. Every tool response is globally capped to 50 KB / 2,000 lines; full data lives in artifacts/transcripts.
+7. Status is compact; wait is the one-shot deliverable.
+8. On shutdown or tree navigation, child runs are cancelled and awaited for a bounded grace period.
+9. On startup, orphan process groups recorded under `lockDir` are reaped (SIGTERM then SIGKILL)
+   before any matching child session is eligible for resume. `$state: "lost"` is a labeling
+   that keeps `resumeBlocked` until reconciliation proves death.
+10. Billed usage is folded once per root message and once per full child run UUID.
+11. Checkpoint persistence events are lightweight (state, usage, process identity, pointers).
+    Full transcripts and final output are persisted exactly once, in the terminal event.
+12. High-frequency registry "changed" events coalesce (trailing window); state transitions,
+    new child sessions, billed-usage advances, and terminal events flush immediately.
+13. `wait` is interruptible: aborting a wait returns promptly and does NOT cancel the
+    background run. Only `cancel` (or parent shutdown) aborts a run.
+14. Budget stops (`max_turns`/`max_cost`) with at least one completed turn end as `partial`
+    and deliver their output normally. Streams truncated after useful assistant output also
+    end as `partial`. Timeouts report `state: "timeout"` with `timeoutPhase`.
+15. `timeout_ms` covers the whole task, including semaphore queue time, but the phase
+    (queued / starting / running) is recorded so agents can apply the right retry policy.
+16. Worktrees live under a durable root (`~/.pi/subagent-worktrees`), never a purgeable OS
+    tmpdir. Startup maintenance (top-level parents only) prunes stale git registrations,
+    removes unchanged leftovers, and sweeps changed-but-expired worktrees. Live-run
+    worktrees are always shielded. `include_wip` worktrees carry the parent's WIP patch in
+    the handle: `diff`/`apply` subtract it when subtraction is clean and otherwise report
+    the combined delta with an explicit `[includes parent WIP]` warning — never silently
+    wrong; a worktree containing only the untouched WIP patch counts as unchanged.
+17. Process-tree reaping after a clean exit can be disabled per task with `keep_background`
+    (for legitimately backgrounded work such as dev servers); forced stops always reap.
+18. Protocol completion prefers Pi's `agent_settled` event. Legacy `agent_end` without
+    `willRetry` is accepted for older Pi builds; `agent_end` with `willRetry: true` is
+    treated as non-terminal.
+19. Depth and spawn-policy parsing fail closed on malformed values: env scrubbing cannot
+    silently reset the depth counter to top-level, and a malformed `PI_SUBAGENT_SPAWNS`
+    disables spawning rather than unrestricting it.
+20. Budget breaches (`max_turns`/`max_cost`) steer a wrap-up message and allow grace
+    turns before SIGTERM; a child that concludes within grace ends `partial` with
+    `wrappedUp: true`. `graceTurns: 0` restores immediate stops.
+21. Transient failures (queued timeout, stall, spawn error, provider error, protocol
+    truncation) retry up to `maxRetries` extra attempts, escalating through
+    `fallback_models`; usage accumulates across attempts and `attemptedModels` is
+    recorded. Task-quality failures (nonzero exit with complete protocol, cancellation,
+    budget stop, running timeout) never retry.
+22. The stall watchdog treats protocol silence as suspect, not fatal: after
+    `stallAfterMs` the task is flagged and probed via `get_state` (a live child's
+    answer clears the flag); only continued silence for `stallKillAfterMs` more kills
+    the child — which is then a transient failure eligible for retry.
+23. Only `async: true` runs notify on completion and appear in the ambient widget.
+    Notification delivery respects delivered-once: a `wait` that consumed the run
+    suppresses the notification.
+24. Named agent files supply per-field defaults only; explicit request params always
+    win, and capability profiles fail closed regardless of what an agent file declares.
+25. Structured-output validation never discards paid work: schema failure after the
+    repair round downgrades completed → partial with `structuredError`, and the raw
+    text still delivers. Validation is enforced on the parent side of the process
+    boundary — the child cannot self-attest.
+26. Arg repair only decodes free-text fields with high-signal escape patterns
+    (literal \n or \") and no real newlines; identifier fields, tool lists, and
+    Windows-path-like strings are never modified.
+27. Global slots are depth-tiered: `tryAcquireGlobalSlot(runId, depth)` admits only while
+    `activeAtOrBelowDepth(depth) < maxGlobalActive - reservedFor(depth)`, holding slots
+    back for deeper tiers so a full-width spawn tree cannot deadlock on its own children.
+    Slot records without a `depth` field count as depth 0.
+28. `action: "plan"` is a truth oracle: it runs the exact validation and preflights of a
+    real spawn and returns the resolved plan without spawning — never a softer check, and
+    never a registry entry.

package/docs/SECURITY.md

@@ -1,88 +1,88 @@
-# Security model
-
-Pi packages run with full system access. This extension spawns child `pi`
-processes that inherit the parent environment (including provider credentials)
-and can use tools according to their capability profile.
-
-## What subagents can do
-
-| Profile | Default tools | Writes? |
-|---------|---------------|---------|
-| `explore` | `read`, `grep`, `find`, `ls` (+ safe extras and Pi context tools) | No project-file writes |
-| `review` | same as explore | No project-file writes |
-| `general` | inherited active tools (+ Pi context tools) | Yes if `bash`/`edit`/`write` are active |
-
-Parallel mode defaults to `explore` to avoid concurrent shared writes.
-
-## Hard rules
-
-1. **Read-only means no project-file mutation.** `bash` can rewrite the disk and is never part of
-   an explore/review profile. Pi context-management tools (`new_context`,
-   `get_context_remaining`, `history`, `notes`) are an explicit control-plane
-   exception: they may update continuity notes/window state but cannot access
-   the project write tools.
-2. **Parallel writers** require `isolation: "worktree"`, distinct `cwd` values,
-   or an explicit `allow_shared_writes: true` opt-in.
-3. **Depth is capped** (`maxDepth`, default 2). Nested children at the ceiling do
-   not re-register the subagent tool. Depth is scheduling metadata — `bash` or an
-   env-scrubbing wrapper can still invoke `pi` directly, so treat it as an
-   accidental-recursion guard, not a security boundary.
-   **Spawn allowlists** (`spawns:` in agent frontmatter, env `PI_SUBAGENT_SPAWNS`)
-   refine that same guard: a child may be limited to named personas, or to none
-   (tool not registered). Like depth, this is not a sandbox — children can still
-   shell out to `pi`.
-4. **Process caps** limit concurrency both per parent session (`maxActiveProcesses`)
-   and machine-wide (`maxGlobalActive`, default 16).
-5. **Transcripts** under `~/.pi/subagent-sessions` may contain task content, tool
-   output, and secrets that appeared in context. Protect that directory. Task text
-   is delivered via stdin (not argv) so it stays out of `ps` listings, but it is
-   still written into the child session log.
-6. **Background permission prompts** are limited because children run headless
-   (RPC mode). Extension UI dialogs raised inside a child are auto-cancelled so
-   they can never hang a run — which also means a child can never obtain
-   interactive consent. Prefer restricted tools for async/background runs.
-11. **Steering messages** (`action: "steer"` and the overlay `s` key) inject text
-    into a running child's conversation with user-level authority. Anything that
-    can call the subagent tool can steer any live run in the same session.
-7. **Process cleanup.** On POSIX, children run in their own process group so tree
-   kills work for ordinary descendants. Parent (re)start reaps orphans recorded
-   under `~/.pi/subagent-locks/runs/` so resume cannot race a still-alive writer.
-   Grandchildren that call `setsid()` can still escape a simple process-group kill.
-8. **Resume exclusivity.** Direct resume takes a durable per-session file lock;
-   concurrent parents cannot append to the same child session.
-9. **Profiles are tool-selection policy, not a sandbox.** Children inherit
-   `$HOME`, SSH/cloud credentials, network access, and the parent filesystem.
-   Git worktrees only isolate the checkout. For untrusted tasks, use an outer
-   container/cgroup/network policy.
-10. **`max_cost` is accounting, not a hard provider gate.** Usage arrives after a
-    turn; orphans may spend money the ledger never sees. Combine with provider
-    account budgets for hard spend limits.
-
-## Trust and project cwd
-
-If `cwd` points outside the parent project, the child inherits whatever local
-project config/trust applies to that path. Treat external `cwd` as elevated risk
-and prefer read-only profiles when exploring third-party trees.
-
-## Output artifacts
-
-`output` files are written by the child. Resolve paths carefully and reject
-duplicate output paths across parallel workers.
-
-## Named agent files
-
-Agent files (`.pi/agents/`, `.agents/agents/`, global agent dir) inject their
-body into the child's system prompt and set its model/tools/budgets. A
-project-level agent file shapes subagent behavior the same way project
-extensions and skills do — review them like code when working in untrusted
-repositories. Mitigations: capability profiles still fail closed (an agent
-cannot grant write tools under `explore`/`review`), symlinked agent files are
-skipped, names are validated against traversal characters, and files over
-64KB are ignored.
-
-## Machine-wide state
-
-`~/.pi/subagent-locks/` holds session locks, global concurrency slots, and run
-process identity records. It is per-user (under `$HOME`) and must not be shared
-across untrusted users/containers without care — a compromised client could
-interfere with lock reclaim on the same account.
+# Security model
+
+Pi packages run with full system access. This extension spawns child `pi`
+processes that inherit the parent environment (including provider credentials)
+and can use tools according to their capability profile.
+
+## What subagents can do
+
+| Profile | Default tools | Writes? |
+|---------|---------------|---------|
+| `explore` | `read`, `grep`, `find`, `ls` (+ safe extras and Pi context tools) | No project-file writes |
+| `review` | same as explore | No project-file writes |
+| `general` | inherited active tools (+ Pi context tools) | Yes if `bash`/`edit`/`write` are active |
+
+Parallel mode defaults to `explore` to avoid concurrent shared writes.
+
+## Hard rules
+
+1. **Read-only means no project-file mutation.** `bash` can rewrite the disk and is never part of
+   an explore/review profile. Pi context-management tools (`new_context`,
+   `get_context_remaining`, `history`, `notes`) are an explicit control-plane
+   exception: they may update continuity notes/window state but cannot access
+   the project write tools.
+2. **Parallel writers** require `isolation: "worktree"`, distinct `cwd` values,
+   or an explicit `allow_shared_writes: true` opt-in.
+3. **Depth is capped** (`maxDepth`, default 2). Nested children at the ceiling do
+   not re-register the subagent tool. Depth is scheduling metadata — `bash` or an
+   env-scrubbing wrapper can still invoke `pi` directly, so treat it as an
+   accidental-recursion guard, not a security boundary.
+   **Spawn allowlists** (`spawns:` in agent frontmatter, env `PI_SUBAGENT_SPAWNS`)
+   refine that same guard: a child may be limited to named personas, or to none
+   (tool not registered). Like depth, this is not a sandbox — children can still
+   shell out to `pi`.
+4. **Process caps** limit concurrency both per parent session (`maxActiveProcesses`)
+   and machine-wide (`maxGlobalActive`, default 16).
+5. **Transcripts** under `~/.pi/subagent-sessions` may contain task content, tool
+   output, and secrets that appeared in context. Protect that directory. Task text
+   is delivered via stdin (not argv) so it stays out of `ps` listings, but it is
+   still written into the child session log.
+6. **Background permission prompts** are limited because children run headless
+   (RPC mode). Extension UI dialogs raised inside a child are auto-cancelled so
+   they can never hang a run — which also means a child can never obtain
+   interactive consent. Prefer restricted tools for async/background runs.
+11. **Steering messages** (`action: "steer"` and the overlay `s` key) inject text
+    into a running child's conversation with user-level authority. Anything that
+    can call the subagent tool can steer any live run in the same session.
+7. **Process cleanup.** On POSIX, children run in their own process group so tree
+   kills work for ordinary descendants. Parent (re)start reaps orphans recorded
+   under `~/.pi/subagent-locks/runs/` so resume cannot race a still-alive writer.
+   Grandchildren that call `setsid()` can still escape a simple process-group kill.
+8. **Resume exclusivity.** Direct resume takes a durable per-session file lock;
+   concurrent parents cannot append to the same child session.
+9. **Profiles are tool-selection policy, not a sandbox.** Children inherit
+   `$HOME`, SSH/cloud credentials, network access, and the parent filesystem.
+   Git worktrees only isolate the checkout. For untrusted tasks, use an outer
+   container/cgroup/network policy.
+10. **`max_cost` is accounting, not a hard provider gate.** Usage arrives after a
+    turn; orphans may spend money the ledger never sees. Combine with provider
+    account budgets for hard spend limits.
+
+## Trust and project cwd
+
+If `cwd` points outside the parent project, the child inherits whatever local
+project config/trust applies to that path. Treat external `cwd` as elevated risk
+and prefer read-only profiles when exploring third-party trees.
+
+## Output artifacts
+
+`output` files are written by the child. Resolve paths carefully and reject
+duplicate output paths across parallel workers.
+
+## Named agent files
+
+Agent files (`.pi/agents/`, `.agents/agents/`, global agent dir) inject their
+body into the child's system prompt and set its model/tools/budgets. A
+project-level agent file shapes subagent behavior the same way project
+extensions and skills do — review them like code when working in untrusted
+repositories. Mitigations: capability profiles still fail closed (an agent
+cannot grant write tools under `explore`/`review`), symlinked agent files are
+skipped, names are validated against traversal characters, and files over
+64KB are ignored.
+
+## Machine-wide state
+
+`~/.pi/subagent-locks/` holds session locks, global concurrency slots, and run
+process identity records. It is per-user (under `$HOME`) and must not be shared
+across untrusted users/containers without care — a compromised client could
+interfere with lock reclaim on the same account.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cr1ms0n/pi-subagent",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "Community fork of Luke Parke's pi-subagent with explicit model policy and model visibility for Pi",
   "type": "module",
   "license": "MIT",