pi-subtask

Isolated background conversation forks for Pi.

pi-subtask runs delegated work in isolated pi --mode rpc processes. Each child receives a snapshot of the parent's active conversation branch, uses its own context window and session file, and reports its final result back automatically.

Features

• /subtask <task> starts a background fork with the user's active tool set.
• /subtask stop <id> stops an active run and its process tree.
• /subtasks opens a keyboard-first Control Tower for active and recent runs.
• The model-facing subtask tool starts a strict read-only fork and returns a receipt immediately.
• Parent branch checks prevent results from being injected into an unrelated branch.
• Child prompts use RPC stdin; prompts and API keys are never copied into process arguments.
• Concurrency, wall-clock, inactivity, stderr, JSON-line, and result-output limits are enforced.
• Nested subtask fan-out is disabled in child processes.

Defaults are intentionally conservative: four concurrent runs, 30-minute wall-clock timeout, five-minute inactivity timeout, and a 50 KiB / 2,000-line delivered result. The complete result remains available in the child session.

Control Tower UI

While runs are active, a compact themed activity rail appears below the editor with status, short run ID, elapsed time, and capability. Completion messages render a concise result by default; press Ctrl+O to expand provenance, output metrics, and the child session path.

Open /subtasks for the focused inspector:

• ↑ / ↓ or j / k: select a run
• Enter: toggle expanded details
• s: stop the selected active run
• Esc: close and restore editor focus

The UI uses Pi theme semantics and never replaces the user's editor component.

Install

Requires Node.js 22.19+ and Pi >=0.84.2.

pi install npm:@nguyenquangthai/pi-subtask

Pin a release for reproducible environments:

pi install npm:@nguyenquangthai/pi-subtask@1.0.1
# or install the matching Git tag
pi install git:github.com/QuangThai/pi-subtask@v1.0.1

Pi packages execute with the permissions of your user account. Review third-party extension source before installation.

Development

git clone https://github.com/QuangThai/pi-subtask.git
cd pi-subtask
npm install
pi --extension ./src/index.ts

Public interface and versioning

Version 1.x treats these user-facing interfaces as stable:

• /subtask <task> starts a background run with the user's active tools.
• /subtask stop <id> stops an active run and its process tree.
• /subtasks opens the run inspector.
• The model-facing subtask tool accepts { task: string }, starts a read-only run, and returns a receipt immediately.

Breaking command or tool-schema changes require a new major version. Child session internals and the custom completion-message payload are implementation details. Pi compatibility remains constrained by the peer dependency range declared in package.json.

See CHANGELOG.md for user-visible changes and the release checklist for maintainer steps.

Security model

• Model-created runs only receive active read, grep, find, and ls tools.
• User-created /subtask runs inherit the parent's active tools and should be treated accordingly.
• Child prompts use RPC stdin; prompts and API keys are not copied into process arguments.
• Process lifetime, concurrency, stderr, protocol records, and delivered output are bounded.
• Child output is untrusted delegated output and should be reviewed before consequential use.

Verify

npm run check
npm test
npm pack --dry-run

# Basic real-model E2E (incurs provider usage)
npm run e2e -- D:/path/to/a/project-with-pi-subtask-installed

# Edge-case matrix (incurs provider usage)
npm run e2e:matrix -- D:/path/to/a/project-with-pi-subtask-installed

The test suite exercises session snapshots, strict JSONL parsing, headless dialog cancellation, startup/wall/inactivity timeouts, stop behavior, process-tree termination, concurrency reservation, tool ceilings, branch-safe delivery guards, and strict UTF-8-safe output caps. Real-model E2E artifacts contain prompts and outputs, are created with private file permissions where the platform supports POSIX modes (Windows inherits directory ACLs), and should be deleted when no longer needed.

Current limitations

• Parent sessions must be persisted and contain at least one entry.
• Runs are not reconciled after parent restart or extension reload.
• Completion delivery is not durably acknowledged; a parent crash between child completion and message injection can leave the result only in the child session.
• Live child transcript, steering, and resume are not implemented yet.
• Model-created runs are limited to active read, grep, find, and ls tools.
• Use stored credentials or provider environment variables. A transient parent --api-key is deliberately not forwarded to child process arguments.

Child session files are written against Pi's exported session version. Pi 0.84.2 is the minimum tested baseline; compatibility must be revalidated before relying on newer Pi APIs.