pi-subagents/AGENTS.md

Repo Guidelines

Scope

This repo implements the subagent pi extension in index.ts.

Key Behavior

• Parent-facing tool: subagent.
• Internal child-only tool: subagent_finalize.
• Never register subagent_finalize in the parent context; only when PI_SUBAGENT_CHILD=1.
• Subagent sessions are sticky and persisted at: ~/.pi/subagent-sessions/<cwd-hash>/<agent>_<sessionId>.jsonl.
• Omitting sessionId creates a new UUID-backed session.
• Passing sessionId resumes the same agent/cwd child session.

Validation

• Child agents must finish by calling subagent_finalize.
• Valid success: status=SUCCESS with non-empty result.
• Valid error: status=ERROR with non-empty error; result is optional partial findings.
• If finalization is missing/invalid, retry by continuing the same sticky session, capped by MAX_FINALIZE_RETRIES.

Commands

• Typecheck: npm run typecheck
• Lint: npm run lint

Style

• Keep the extension simple; avoid debug metadata unless needed.
• Do not expose retry internals to the parent by default.
• Prefer precise tool/context isolation over prompt-only enforcement.