# 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/agent/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.