@jerryan/pi-subagent-tools 0.1.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 0.4.0
+
+### Changed
+
+- **Sandbox bash now uses real-layout mounts instead of a fixed `/repo`.**
+  On posix, `$HOME` is mounted at its own path (plus the project root when
+  the cwd is outside home — read-only agents may read other projects); on
+  Windows, every existing drive is mounted at MSYS form (`C:\` = `/c`).
+  Sandbox paths match host paths one-to-one, so paths move verbatim between
+  bash and the `read` tool. Everything outside the mounts remains per-call
+  in-memory scratch.
+- **Switched `just-bash` for the `@jerryan/just-bash` fork** (^3.10.0),
+  which adds the Windows native-spelling path translation the real-layout
+  scheme relies on, plus extra default utilities (jq, yq, sqlite3, rg,
+  xan).
+- **New sandboxed `python` tool for review/explore children**: stdlib-only
+  WASM CPython over the same read-only filesystem, for dependency-free
+  analysis scripts. It is a separate tool — NOT a `python3` command in
+  the bash sandbox — because a bare `python3` on PATH implies the native
+  interpreter (project env, pip), a capability the WASM build doesn't
+  have; the dedicated tool makes the stdlib-only contract explicit.
+  (The role allowlist must name `python`: pi filters customTools through
+  it — a custom-only tool name missing from the allowlist is silently
+  dropped.)
+- **`just-git` bumped to ^1.9.0**, which fixes the CRLF `.gitignore`
+  parsing quirk (Windows checkouts with `core.autocrlf=true` had ignore
+  rules silently no-op inside the sandbox).
+- Trimmed the sandboxed bash tool description to behavioral deltas from
+  stock bash (read-only, no network, stateless per call).
+
+## 0.3.0
+
+### Changed
+
+- **Review/explore children now get a sandboxed read-only `bash`** instead of
+  the `grep`/`find`/`ls` builtins plus the dedicated `git` tool. The sandbox
+  is a just-bash interpreter over a composed filesystem: the project root
+  mounted read-only at `/repo` (OverlayFs) over a writable in-memory base
+  (MountableFs) providing `/dev/null` and per-call scratch (`/tmp`). Git is
+  provided by just-git inside the sandbox (network disabled). Read-only is
+  now enforced at the capability layer — the filesystem rejects every write
+  to the project (redirects, `rm`, `sed -i`, git object/ref updates) —
+  replacing the per-subcommand git policy table. The tool surface shrinks to
+  `read` + `bash`; the sandboxed `bash` shadows the builtin (custom tools
+  win over builtins), so there is no configuration in which a raw builtin
+  bash reaches a read-only child.
+- The dedicated `git` tool is removed; git inspection (log, diff, show,
+  blame, grep, ls-files) goes through the sandbox.
+  Known limitation: just-git's `.gitignore` parser does not strip carriage
+  returns — on Windows (CRLF `.gitignore`) ignore rules silently no-op, so
+  `git status` walks the unpruned worktree (slow) and reports ignored paths
+  as untracked; the tool description steers agents to targeted commands.
+
+### Added
+
+- New runtime dependencies: `just-bash`, `just-git`.
+
+## 0.2.0
+
+**Subagents now run in-process** via the pi SDK (`createAgentSession`) instead
+of as spawned `pi` subprocesses. Requires pi >= 0.84.
+
+- **New `follow_up` tool.** Every spawn result includes an agent id
+  (e.g. `delegate-1`). `follow_up({ agent, task })` continues that agent's
+  session with full context — for refining work, asking questions, or
+  recovering from incomplete/failed results. Agents keep their original role,
+  tools, and cwd for life.
+- **Interactive prompts route to the parent TUI.** Subagent `select` /
+  `confirm` / `input` / `editor` requests are bridged to the parent's UI
+  instead of silently falling back to defaults (ui-bridge.ts).
+- **Agent lifetime management.** Agents are kept in a registry and disposed
+  only after 10+ idle turns (running agents are never disposed), or when the
+  owning session ends.
+- Tool errors are now reported by throwing, matching pi >= 0.84 tool semantics.
+- The read-only git tool is fully async (subagents share the parent's event
+  loop; a blocking exec would freeze the TUI), and its read-only enforcement
+  is now a per-subcommand policy table — mutating flags (`branch -D`,
+  `diff --output=...`) and branch creation via positional args are rejected.
+
+Breaking changes:
+
+- Removed `delegate`'s `context` parameter (was a no-op placeholder).
+- Recursion guard is now structural (child sessions get exactly the tools
+  injected by the extension) — the `PI_SUBAGENT_TOOLS_ROLE` env var is gone.
+- Child sessions no longer load user/project extensions (created with
+  `noExtensions: true`); skills and system prompts still apply. **Exception:**
+  delegate children DO discover user/project extensions (they are workers and
+  need the parent's environment, including guard extensions) — with this
+  extension itself excluded from discovery (that exclusion is the recursion
+  guard) and project-local extensions excluded in untrusted projects.
+
 ## 0.1.1
 
 - Add delegate system prompt. Subagents now do the work directly instead of discussing plans. Minor uncertainties proceed with stated assumptions; major obstacles are reported back with a suggestion to re-delegate.

package/README.md

@@ -1,70 +1,102 @@
-# @jerryan/pi-subagent-tools
-
-A minimal pi extension for delegating work to isolated subagent processes. Three tools, one job each. The agent is a **project manager** — delegate by default, dive in only when necessary.
-
-## What makes this different?
-
-Every subagent is a fresh `pi` process with an isolated context window. No agent definitions to write, no configuration files to maintain, no mode-switching parameters to misconfigure. Each tool's name *is* the contract:
-
-- **`review`** — always read-only, always in the current project. You can't forget to lock it down.
-- **`explore`** — always read-only, requires a target directory. Picks up the target project's settings, skills, and context.
-- **`delegate`** — general-purpose worker. Inherits the parent's tools and system prompt for optimal cache reuse. Optional CWD and skills.
-
-## Installation
-
-```bash
-pi install npm:@jerryan/pi-subagent-tools
-```
-
-The extension is available the next time you start a pi session.
-
-## Tools
-
-### `review`
-
-Review code, diffs, or files in the current project. The reviewer is always read-only — it cannot modify files or execute commands.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `task` | string | Yes | What to review |
-| `skills` | string[] | No | Skills to load via `--skill` |
-
-### `explore`
-
-Map a project directory. The explorer runs in the target directory, picking up its `.pi/settings.json`, skills, AGENTS.md, and other context files. Always read-only.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `task` | string | Yes | What to explore |
-| `cwd` | string | Yes | Target project directory |
-| `skills` | string[] | No | Skills to load via `--skill` |
-
-### `delegate`
-
-General-purpose worker. No tool filtering, no system prompt override — the subagent inherits the parent's full environment, enabling cache hits when used with context inheritance (future).
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `task` | string | Yes | Task to delegate |
-| `cwd` | string | No | Working directory (defaults to parent's CWD) |
-| `skills` | string[] | No | Skills to load via `--skill` |
-| `context` | `"fresh"` \| `"inherit"` | No | Context mode (not yet implemented) |
-
-## Recursion guard
-
-Subagents cannot spawn further subagents beyond one level:
-
-| Parent role | `review` | `explore` | `delegate` |
-|-------------|:--:|:--:|:--:|
-| Parent (normal) | ✓ | ✓ | ✓ |
-| Delegate child | ✓ | ✓ | Rejects at runtime |
-| Review / explore child | — | — | — |
-
-## Related
-
-- **[pi-subagents](https://github.com/nicobailon/pi-subagents)** — Feature-rich implementation with agent definitions, background runs, session forking, inter-process communication, and a full management UI. The definitive reference for what's possible, though possibly more than most workflows need.
-- **[pi-subagent-lite](https://github.com/JerryAZR/pi-subagent-lite)** — Ultra-minimal (~250 lines). A single `task` tool with minimal context overhead.
-
-## License
-
-MIT
+# @jerryan/pi-subagent-tools
+
+A minimal pi extension for delegating work to subagents. Four tools, one job each. The agent is a **project manager** — delegate by default, dive in only when necessary.
+
+## What makes this different?
+
+Every subagent is an isolated `AgentSession` running in-process via the pi SDK — its own context window, its own tools, no configuration files to maintain. Each tool's name *is* the contract:
+
+- **`review`** — always read-only, always in the current project. You can't forget to lock it down.
+- **`explore`** — always read-only, requires a target directory. Picks up the target project's settings, skills, and context.
+- **`delegate`** — general-purpose worker with full tool access. Optional CWD and skills.
+- **`follow_up`** — continue any spawned agent's session with full context. No re-explaining, no lost work.
+
+Interactive prompts from subagents (confirmations, selections, inputs) appear in your TUI instead of silently falling back to defaults.
+
+## Installation
+
+```bash
+pi install npm:@jerryan/pi-subagent-tools
+```
+
+The extension is available the next time you start a pi session. Requires pi >= 0.84.
+
+## Tools
+
+### `review`
+
+Review code, diffs, or files in the current project. The reviewer is always read-only: it gets `read`, a sandboxed bash (just-bash over real-layout read-only mounts — your home dir, or all drives on Windows — so grep, find, sed, git log/diff/blame all work and paths match the host verbatim; every write fails at the filesystem), and a sandboxed stdlib-only python for analysis scripts.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task` | string | Yes | What to review |
+| `skills` | string[] | No | Skills to load |
+
+### `explore`
+
+Map a project directory. The explorer runs in the target directory, picking up its `.pi/settings.json`, skills, AGENTS.md, and other context files. Always read-only, with the same sandboxed bash and python as the reviewer.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task` | string | Yes | What to explore |
+| `cwd` | string | Yes | Target project directory |
+| `skills` | string[] | No | Skills to load |
+
+### `delegate`
+
+General-purpose worker. Full tool access (read, bash, edit, write), and loads your user/project extensions like a fresh pi would — custom tools and guard extensions apply to the worker just as they do to you. Uses the parent's current model and thinking level.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task` | string | Yes | Task to delegate |
+| `cwd` | string | No | Working directory (defaults to parent's CWD) |
+| `skills` | string[] | No | Skills to load |
+
+### `follow_up`
+
+Send a follow-up task to a previously spawned subagent, continuing its session with full context. The agent retains its original role, tools, and working directory — a reviewer stays read-only forever.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent` | string | Yes | Agent id from a previous result (e.g. `delegate-1`) |
+| `task` | string | Yes | Follow-up task or question |
+
+Every spawn and follow-up result ends with the agent's id:
+
+```
+<the subagent's output>
+
+---
+agent: delegate-1
+```
+
+Unknown or expired ids fail loudly with the list of live agents — never a silent fresh spawn.
+
+## Agent lifetime
+
+Agents live in a per-session registry. Cleanup is recency-based:
+
+- An agent idle for more than **10 turns** of the owning session is disposed.
+- Running agents are never disposed. Recently active agents are never disposed — there is no count cap; a burst of 20 parallel delegates all run to completion.
+- All agents are disposed when the owning session ends.
+
+## Recursion guard
+
+Subagent nesting is capped structurally — child sessions are created with extension discovery disabled, so they get exactly the tools the extension injects:
+
+| Parent role | `review` | `explore` | `delegate` | `follow_up` |
+|-------------|:--:|:--:|:--:|:--:|
+| Parent (normal) | ✓ | ✓ | ✓ | ✓ |
+| Delegate child | ✓ | ✓ | Rejects at runtime | ✓ |
+| Review / explore child | — | — | — | — |
+
+A delegate child's agents live in their own registry with their own ids.
+
+## Related
+
+- **[pi-subagents](https://github.com/nicobailon/pi-subagents)** — Feature-rich implementation with agent definitions, background runs, session forking, inter-process communication, and a full management UI. The definitive reference for what's possible, though possibly more than most workflows need.
+- **[pi-subagent-lite](https://github.com/JerryAZR/pi-subagent-lite)** — Ultra-minimal (~250 lines). A single `task` tool with minimal context overhead.
+
+## License
+
+MIT