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.
• Subagents are loaded from ~/.pi/subagents/*.md (user config only).
• The subagent tool is only registered when at least one subagent exists.
• 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.
• A prompt's .md body replaces pi's default system prompt (passed via --system-prompt). It is the entire system prompt; do not write it as an appendage. Pi still tacks on AGENTS.md/skills/date/cwd.
• Retries reuse the same session and append a new user message nudging the child to finalize. The system prompt is stable across attempts (cache-friendly).

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.