@jerryan/pi-subagent-tools 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+## 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.
+
+## 0.1.0
+
+Initial release. Delegate, review, and explore tools via isolated pi subagent processes.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Zerui An
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,14 +1,17 @@
 # @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.
+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 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:
+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. Inherits the parent's tools and system prompt for optimal cache reuse. Optional CWD and skills.
+- **`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
 
@@ -16,49 +19,78 @@ Every subagent is a fresh `pi` process with an isolated context window. No agent
 pi install npm:@jerryan/pi-subagent-tools
 ```
 
-The extension is available the next time you start a pi session.
+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 cannot modify files or execute commands.
+Review code, diffs, or files in the current project. The reviewer is always read-only: it gets `read` plus a sandboxed bash (just-bash over a read-only mount of your project — grep, find, sed, git log/diff/blame all work; every write fails at the filesystem).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `task` | string | Yes | What to review |
-| `skills` | string[] | No | Skills to load via `--skill` |
+| `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.
+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 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 via `--skill` |
+| `skills` | string[] | No | Skills to load |
 
 ### `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).
+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 via `--skill` |
-| `context` | `"fresh"` \| `"inherit"` | No | Context mode (not yet implemented) |
+| `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
 
-Subagents cannot spawn further subagents beyond one level:
+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 | — | — | — | — |
 
-| Parent role | `review` | `explore` | `delegate` |
-|-------------|:--:|:--:|:--:|
-| 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