pi-cli-subagent

A Pi extension that adds a dispatch tool: hand a task to an installed external CLI coding agent — Codex CLI or Claude Code — and get its response back inline in your Pi session.

Dispatch is blocking and read-only. The external agent can read your workspace and run read-only commands, but it cannot modify your working tree.

• Why: it produces genuinely independent verification — a different model, a different toolchain, a different set of habits — without pulling all of that agent's context into your Pi session.
• Not: background execution, session resume, or write-enabled delegation.

Requirements

| Requirement | Notes | | --- | --- | | Pi with extension support | The host that loads this package. | | Node.js ≥ 22.6 | Only for development (--experimental-strip-types). Runtime uses Pi's Node. | | codex on PATH | Codex CLI, installed and authenticated. Needed for cli: "codex". | | claude on PATH | Claude Code, installed and authenticated. Needed for cli: "claude". |

You only need the CLI(s) you actually intend to dispatch to. If a CLI is missing, that dispatch fails with a clear cli-not-installed error rather than hanging.

The CLIs are runtime dependencies of your environment, not bundled by this package. Authentication is entirely theirs — this extension never handles your credentials.

Installation

Use it as a project-local extension

The extension is already wired into this repository at .pi/extensions/agent-dispatch/index.ts. Run Pi from this directory and the dispatch tool is available.

Install as a Pi package

pi install /absolute/path/to/pi-cli-subagent
pi install ./relative/path/to/pi-cli-subagent
pi install git:github.com/user/pi-cli-subagent@v1

Or try it without installing:

pi -e /absolute/path/to/pi-cli-subagent

The package manifest (pi.extensions in package.json) points at the extension entry point:

"pi": { "extensions": ["./.pi/extensions/agent-dispatch/index.ts"] }

Enable or disable it with pi config (press Tab to switch between global and project settings).

Usage

The extension registers exactly one tool, dispatch.

| Parameter | Required | Description | | --- | --- | --- | | task | yes | The task to hand to the external agent. Passed through unchanged. | | cli | yes | Which agent to run: "codex" or "claude". | | model | no | Model identifier passed to the CLI unmodified. Omit to use the CLI's own configured default. | | effort | no | Reasoning effort level. Omit to use the CLI's configured default. | | scope | no | Optional scope hint appended after the task (e.g. a directory or file list). |

You rarely call this tool by hand — Pi's model decides to, based on your request:

Have Codex review my uncommitted changes for risk.

Ask Claude, on high effort, to review this file for race conditions.

Get a second opinion from Codex on the schema in src/db.ts.

Because task is passed through verbatim, review framing, output format, and "second opinion" behavior are all just prompts — nothing is hardcoded. The only standing instruction added is a short nudge to assess the evidence independently. model and effort are never translated between CLIs; if you name them, they go straight to the CLI.

Model and effort resolution

• Omit model/effort → the CLI's own configured default is used.
• Name model/effort → passed through unvalidated, except for Codex, which is pre-validated against its model catalogue (codex debug models) so an unsupported value fails fast with the valid alternatives listed.
• The result reports CLI-confirmed model/effort separately from what you requested. Values the CLI does not report are labelled not reported rather than guessed.

The read-only guarantee

Dispatch refuses to run at all if it cannot enforce read-only across the complete launch configuration — shell, file tools, hooks, and MCP servers — not just shell commands. This is enforced by each CLI's own sandbox, never by asking the agent nicely.

| CLI | Key launch restrictions | | --- | --- | | Codex | -s read-only, --ignore-user-config, --ignore-rules, --disable hooks, --disable plugins | | Claude | --safe-mode, --strict-mcp-config, --tools Read,Bash, sandbox forced on with allowUnsandboxedCommands: false and the workspace root in denyWrite |

Note that read-only protects your working tree. It does not establish confidentiality or prevent network side effects. See TODO.md.

Failures

Failures are typed and reported with diagnostics rather than thrown. A failed dispatch sets isError: true and names the cause.

| Kind | Meaning | | --- | --- | | missing-cli / unsupported-cli | No cli, or an unrecognized one. | | cli-not-installed | The CLI binary is not on PATH. | | read-only-unavailable | The adapter cannot enforce read-only; dispatch refuses. | | invalid-request | Rejected by preflight (e.g. an unsupported Codex model). | | spawn | The process could not be launched. | | nonzero-exit / signal | The CLI exited non-zero or was killed by a signal. | | error-envelope | The CLI reported an error in its terminal envelope. | | malformed-stream | The CLI emitted unparseable output. | | missing-terminal | Exit 0 with no recognizable terminal result. | | cancelled / shutdown | Cancelled by the caller, or the session is shutting down. |

Reported usage (tokens/cost) is preserved on both success and failure.

Development

Setup

npm run link-deps   # symlink Pi runtime packages from your installed Pi
npm run typecheck   # tsc --noEmit
npm test            # node --test over test/*.test.ts

link-deps exists so tsc and the test runner resolve the Pi peer packages (@earendil-works/*, typebox) from your local Pi installation without a network install. Only the Pi runtime packages and @types/node are linked.

Tests

All tests run against a fake CLI (test/fixtures/fake-cli.mjs) that emits scripted JSONL, so the suite is deterministic, fast, and free. It covers stream parsing, failure classification, process lifecycle and cleanup, cancellation, signal handling, and argument construction.

Live checks

node --experimental-strip-types scripts/live-check.mts <repo>

This harness makes real, paid CLI calls and is run manually, not in CI. It verifies the things fixtures cannot: that each CLI accepts the launch flags, that read-only denials actually happen and the tree is unchanged, and that live streams parse. Use a throwaway repo.

Architecture

.pi/extensions/agent-dispatch/
  index.ts             Extension entry: owns the process registry, wires tools
  tool.ts              `dispatch` tool registration + isError patching
  dispatch-core.ts     CLI-agnostic dispatch logic (no Pi imports)
  runner.ts            Spawn, stream, terminate, classify the outcome
  process-registry.ts  Tracks child process groups; kills on cancel/shutdown
  adapters/            One module per CLI: codex.ts, claude.ts, util.ts
  prompt.ts, render.ts, types.ts

Adding a CLI means adding one adapter and no changes to the tool. An adapter implements CliAdapter (types.ts):

• buildCommand(req, defaults) → the exact argv/env to spawn (required)
• parseLine(line, state) → normalized stream events (required)
• extractResult(state) → final text, usage, identity, terminal/error flags (required)
• preflight(req, ctx) → validate a request and resolve defaults (optional)
• discoverModels(ctx) → enumerate models/efforts (optional)

Every adapter normalizes its CLI's output into the same event stream, so dispatch-core.ts contains zero CLI-specific knowledge.

Known limitations

Security caveats and deferred work are tracked in TODO.md. The two most important: the child environment uses a denylist, not an allowlist; and detached descendants can escape process-group cleanup.

License

MIT © 2026 Daniel Carter