--- id: PX-PLAN-PIXXMV4M type: plan title: Hornets Claude Delegation spec: PX-SPEC-WQR3XWPQ status: draft --- ## Outcome Deliver one complete general delegation path from Pi to Claude Code, with communication MCP, native Pi question fallback, cancellation, and continuation. Implements the first independently usable part of [Hornets](../../specs/PX-SPEC-WQR3XWPQ-hornets-cross-harness-delegation/index.md). Plan prerequisites: none. [Codex parity](../PX-PLAN-2W7CNSCD-hornets-codex-parity-and-optional-bridges/index.md) depends on this working path; Ask events and peer review do not. ## Evidence boundary Local version/help inspection found Claude Code 2.1.319 and Codex CLI 0.167.0. No login-status, authentication, model invocation, native MCP attachment, or continuation was exercised during planning. Claude help documents print/streamed output, explicit session resume, invocation-local MCP config, and native permission controls. Print mode skips the workspace trust dialog; bare mode changes credential/config behavior, so neither trust nor native defaults may be assumed from a flag name. Current [Claude CLI reference](https://code.claude.com/docs/en/cli-reference) and [MCP documentation](https://code.claude.com/docs/en/mcp) guide execution-time capability checks, not a blanket version-compatibility claim. ## Structure and behavior dependencies Start with a real task through one adapter; each subsequent behavior extends that same task lifecycle. ```mermaid flowchart TB T["Hornets tool request"] --> R["Task runtime and ownership"] R --> C["Claude adapter"] C --> H["Claude Code harness"] H --> B["Task-scoped communication MCP"] B --> P["Parent context and progress"] B --> Q["Native Pi questions"] B --> A["Artifact references"] H --> F["Result and continuation locator"] F --> N["Continue exact harness session"] N --> R ``` ## Ordered behaviors 1. **Discover capability and complete a non-review task.** Create `extensions/hornets/` with lazy `index.ts`, `src/tool.ts`, `src/runtime.ts`, and `src/adapters/claude.ts`; integrate package/tasks, root TypeScript reference, debug/settings codegen as needed. Expose task submission and local capability/status discovery without creating a general harness framework. Confirm documented CLI flags/event records against selected executable version/help; unsupported contracts fail explicitly. Use native Node process ownership, argument arrays, selected cwd, and bounded streaming capture; preserve native tools/auth/config unless deliberate task options override them. Run one read-only research or document-production task through the real Pi tool and return output, attributable progress, effective/requested settings, and available session/model/usage evidence. Missing executable, malformed output, nonzero exit, unauthenticated response, and unknown auth remain distinct from success. Presence does not prove authenticated operation; status probes must not consume model requests or alter login state. 2. **Communicate with the parent while Pi awaits the task.** Add task-owned `src/bridge.ts` and `src/questions.ts`; use a supported MCP server library rather than importing Pi's private MCP implementation. Prefer parent-owned loopback MCP service with invocation-local harness configuration; verify actual Claude support before freezing transport details. Establish task-bound routing and context/progress/question/artifact operations, not arbitrary SDK evaluation or parent-tool mirroring. Child receives parent awareness and task brief; context retrieval returns deliberately supplied knowledge/references, not full parent transcript or credentials. Native Pi UI answers questions independently of the parent's next model turn, with explicit unavailable response in headless mode. A controlled child demonstrates all four communication operations during an outstanding Pi delegation; stale/foreign task messages cannot affect another task. Keep any bridge secret out of ordinary output, diagnostics, and persisted task summaries; no persistent harness-config edit. 3. **Cancel, fail, and continue without orphaning ownership.** `src/runtime.ts` tracks task generation, active harness process, MCP connection, question ownership, progress, and terminal result. Parent abort/session replacement/reload/shutdown settles bridge calls and pending questions, stops owned processes with bounded escalation, and reports actual cleanup evidence. Preserve artifacts and partial evidence; completed-looking output followed by harness failure cannot become success. Continuation uses exact recorded harness/session identity, reapplies fresh task MCP configuration, and updates task context without relying on replacing a persisted system-prompt snapshot. Missing sessions, stale bridge configuration, cancellation races, and concurrent continuation writers fail explicitly rather than starting or overwriting another task. Native permission-required/denied behavior is surfaced; never add automatic permission/trust bypass to make noninteractive execution work. 4. **Use the built extension independently.** Add `src/render.ts`, schema-bound `src/debug.ts`, README/banner/config generation, and generated local helpers through repository conventions. Keep normal rows compact with native expansion; show originating harness/task, meaningful current progress, output/artifact references, and accurate terminal status. Declare only imported dependencies centrally through workspace manifests/lock; use packaged native helper entrypoints only if the chosen MCP transport actually needs them. Contract tests load `index.ts` through the owned Pi fixture; controlled native child fixtures exercise streamed records, bridge calls, hung processes, delayed answers, and cleanup. Build/relocate Hornets outside the checkout with Ask, Relop, and Dilemma absent; exercise a non-review task and native question fallback. Measure startup/context impact without model calls when possible; report any provider-token measurement requiring separate authorization. ## Verification and completion boundary - Current planning checks prove installed version/help only; implementation must record a supported-version baseline from actual operation. - Focused deterministic tests cover missing CLI, supported/unsupported capability, auth-required/unknown, transport failure, split output records, overflow, cancellation, shutdown, and continuation collisions. - Native Claude acceptance requires deliberate human authorization for model use and existing harness auth; no automated login/install or provider substitution. - Capture one real non-review task, parent-awareness MCP calls, native human question, cancellation, and exact-session continuation; fixtures alone do not establish native compatibility. - If live prerequisites are unavailable, retain useful discovery/fixture verification but report native acceptance blocked rather than completing the whole Hornets spec. - Add and validate Hornets Mise `lint`, `test`, `check`, and `verify-package`; run root `//:check`/`//:test` at integration without implicit full CI or unrelated E2E. - Temp configs/transcripts/fixtures belong in OS temp and are cleaned when no longer needed; harness-owned native session records remain under its own supported lifecycle. ## Exit criteria - [ ] Built Hornets completes and continues a native Claude task through an explicitly verified CLI interface. - [ ] Child can retrieve parent context, report progress/artifacts, and ask a human while Pi awaits its result. - [ ] Hornets works without Ask, Dilemma, Relop, peer-review skill, or Codex being installed. - [ ] Missing/unsupported CLI, unknown/auth-required, failure, cancellation, stale messages, and cleanup gaps remain honest outcomes. - [ ] Native permissions, tools, credentials, and persistent user configuration are not silently replaced or bypassed. - [ ] Relocated fixture tests and separately authorized native acceptance are recorded with their actual scope.