Evaluate task subagent capability in Junior via Pi SDK

[dcramer]

Summary

We should add a task-subagent capability to Junior so the main agent can delegate scoped work (recon/planning/review/implementation) and consume structured results.

What I checked (Pi SDK / pi-mono)

I reviewed local sources in ~/src/pi-mono:

• Pi coding-agent philosophy explicitly states no built-in sub-agents and points users to extensions/custom implementations.
  • packages/coding-agent/README.md:408
• Pi SDK docs explicitly list this as a supported use case: "Build custom tools that spawn sub-agents".
  • packages/coding-agent/docs/sdk.md:11
• Extensions docs include a concrete subagent/ example.
  • packages/coding-agent/docs/extensions.md:1953
• The example implementation spawns separate pi subprocesses (spawn("pi", ["--mode", "json", "-p", "--no-session", ...])), supports single/parallel/chain, and streams intermediate updates.
  • packages/coding-agent/examples/extensions/subagent/index.ts:4
  • packages/coding-agent/examples/extensions/subagent/index.ts:247
  • packages/coding-agent/examples/extensions/subagent/index.ts:409

Fit with Junior

Junior currently uses @mariozechner/pi-agent-core directly (not coding-agent extension runtime), with a custom tool wrapper layer:

• Tool registration path: packages/junior/src/chat/tools/index.ts
• Tool definition shape is final-result oriented (execute(input, options)), no partial update callback exposed at this layer: packages/junior/src/chat/tools/definition.ts
• Agent bridge currently executes tools and returns one result; status hooks are start/end, not streaming tool deltas: packages/junior/src/chat/respond.ts:398

This means:

• MVP delegation is feasible quickly (single delegated task, final result only).
• Parity with Pi's full subagent UX (parallel/chain with live updates and richer UI/state) requires additional plumbing in Junior's tool layer and delivery surface.

Recommendation

Implement in phases:

Phase 1 (MVP, low/medium effort)

• Add a taskSubagent tool that runs one delegated task in a separate subprocess with constrained tools/model.
• Return summarized/final output only (no live partial updates).
• Add timeout + cancellation + explicit max task size.
• Restrict to trusted local agent definitions (or explicit allowlist).

Phase 2 (higher effort)

• Add optional parallel/chain orchestration.
• Extend Junior tool execution path to support progressive tool updates (not just start/end status).
• Add richer telemetry and guardrails (cost/tokens per subtask, recursion limits, fan-out limits).

Rough effort

• Phase 1: ~1-2 days (including tests).
• Phase 2: ~3-5 days depending on streaming UX and observability depth.

Proposed acceptance criteria (Phase 1)

• New tool can delegate one task and return deterministic final output.
• Delegated task uses isolated prompt/context and bounded toolset.
• Timeouts/abort work and failures are surfaced as structured errors.
• Unit/integration coverage for success, timeout, and non-zero exit cases.
• Logs include subagent invocation metadata (model, duration, exit_code, token/cost if available).