Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

.system/plans/PX-PLAN-PIXXMV4M-hornets-claude-delegation/index.md

Raw
Rendered preview

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. Plan prerequisites: none. Codex parity 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 and MCP documentation 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.

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