# pi-sequential-subagent

A deliberately small subagent package for
[Pi](https://pi.dev): one tool, one fresh child Pi, one task at a time.

It does not define roles, agents, chains, parallel modes, model selectors, or
configuration fields. The parent calls `subagent` with a single multiline
`task`; the child runs sequentially and returns its final response.

## Install

```sh
pi install npm:pi-sequential-subagent
```

Restart Pi after installation. The package registers the native `subagent`
tool and a matching discovery skill.

## Use

Ask naturally:

```text
Use a subagent to inspect the parser and explain why escaped newlines fail.
Do not edit files. Return the likely cause and the smallest safe fix.
```

Or explicitly:

```text
/skill:subagent
Inspect the parser and explain why escaped newlines fail.
Do not edit files. Return the likely cause and the smallest safe fix.
```

The tool schema has one field:

```json
{
  "task": "A self-contained multiline task"
}
```

## What the child inherits

The child is a new Pi process in the parent's working directory. It receives
Pi's normal global and project prompts, context files, settings, tools,
extensions, packages, and skills. It does not receive the parent's
conversation.

The working tree is shared. If the task permits edits, the child edits the same
files as the parent.

## Live output and artifacts

Thinking, assistant text, tool activity, retries, and diagnostics stream through
the parent tool call while the child works.

Every run stores its prompt, complete JSON event stream, diagnostics, native
session, final response, and metadata below:

```text
.pi/subagents/runs/
```

Add that directory to the project's ignore file if the artifacts should not be
committed.

## Deliberate constraints

- Exactly one sequential child per tool call.
- Exactly one multiline task parameter.
- No named or hardcoded agent roles.
- No conversation fork or copied parent transcript.
- No parallel, background, chain, resume, or model-selection modes.
- The child is instructed not to delegate recursively.

These constraints are the point of the package. For configurable agents,
parallelism, chains, or resumable workflows, use one of Pi's larger subagent
packages instead.

## Local development

```sh
npm test
npm pack --dry-run
pi -e ./extensions/index.ts
```

## Security

Pi extensions execute with the user's permissions. The child shares the
parent's working directory and available credentials. Install only reviewed
code and make edit permissions explicit in delegated tasks.

## License

MIT