# @shog-lab/pi-subagent

**Spawn focused sub-pi processes from inside pi.**

Registers a single `spawn_subagent` tool. Your agent calls it with a `cwd` + `prompt`; pi-subagent spawns a clean child pi (no extensions, no inherited context), waits for it to finish, returns the response.

Useful for: isolated code analysis, parallel exploration, "classify this content without bias from my loaded context", running a focused sub-task in a different directory.

## Install

```bash
npm i -D @shog-lab/pi-subagent
```

pnpm:

```bash
pnpm add -D @shog-lab/pi-subagent
INIT_CWD="$PWD" pnpm exec pi-subagent-init
```

`postinstall` still tries to symlink `dist/extensions/subagent/` into the host repo's `.pi/extensions/` for npm users. pnpm users should run the explicit init command because pnpm may block lifecycle scripts.

## Tool

| Tool | Args | Purpose |
|---|---|---|
| `spawn_subagent` | `cwd: string`, `prompt: string`, `timeout?: number` (seconds, default 300, max 600) | Spawn a child pi at `cwd` with `prompt`, return its response text and token usage |

The child pi runs with `--no-extensions`, `--no-skills`, `--no-prompt-templates`, and `--no-context-files` — it's a clean slate that only sees the focused task prompt.

## Why a separate package

`spawn_subagent` is infrastructure (child-process spawning helper), not a leaf tool like `web_search`. Previously bundled in `@shog-lab/pi-toolkit` for historical reasons; extracted in toolkit 0.3.0 so it can evolve independently and so users who want JUST subagent capability don't have to pull in mmx CLI / agent-browser deps.

## Migration from @shog-lab/pi-toolkit < 0.3.0

If you previously got `spawn_subagent` via toolkit:

```bash
npm i -D @shog-lab/pi-subagent
# now both packages contribute: toolkit gives web_search / mcp-bridge,
# pi-subagent gives spawn_subagent
```

No code change needed in your agent prompts — the tool name (`spawn_subagent`) is unchanged.

## Dependencies

```json
{
  "peerDependencies": {
    "@earendil-works/pi-coding-agent": "^0.74.0"
  },
  "dependencies": {
    "@shog-lab/pi-utils": "*",
    "@sinclair/typebox": "^0.34.0"
  }
}
```

## License

MIT