Files

Evan Reichard 5c5cdb3aec refactor(subagent): split responsibilities and isolate child prompt

- Extract validateAgent, toToolResult, runAgentWithRetries so index.ts
  is wiring only; orchestration, validation, and result shaping each own
  their concern.
- Separate runner internals: createRunState, handleEvent (pure event
  reducer), spawnPi (process lifecycle), runOnce (single attempt).
- Track attempt/maxAttempts on SubagentStatus; surface "try x/y" in the
  UI without overwriting the user-facing task with the retry preamble.
- Replace pi's default system prompt (--system-prompt) instead of
  appending, so the subagent .md body is authoritative.
- Document prompt-replacement and retry/cache semantics in AGENTS.md.

2026-05-12 15:02:49 -04:00

1.5 KiB

Raw Blame History

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.
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.

1.5 KiB Raw Blame History

Repo Guidelines

Scope

Key Behavior

Validation

Commands

Style

1.5 KiB

Raw Blame History