--- id: PX-SPEC-WQR3XWPQ type: spec title: Hornets Cross-Harness Delegation --- ## Intent Let Pi agents delegate general tasks to other agent harnesses while maintaining useful parent/child communication. Initial harnesses: Claude Code and Codex. Hornets is semantically PiPi for external harnesses, not a review product. ## Scope In: explicit harness selection, task submission, working-directory selection, progress, results, session continuation, cancellation, availability discovery, task-scoped communication MCP. Out: review policy, reviewer pools, automatic harness installation/login, automatic provider fallback, wholesale Pi tool mirroring, generic remote SDK evaluation, perfect sandbox guarantees, new dashboard. Implementation, research, review, diagnosis, and document production use the same task primitive. ## Delegation contract A request identifies the intended harness, task, relevant context and constraints, working directory, and any deliberate execution choices. Harness-specific permission, model, resource, and continuation differences remain visible rather than being presented as identical Pi sessions. Harnesses own their tools, execution mechanics, native approvals, and authentication. Return observable progress, final outcome, usable continuation locator when available, artifact references, and reported identity/usage with explicit unknowns. Failure or cancellation can return partial evidence but must not look like successful completion. Continuing a task preserves its harness/session identity; unsupported, missing, or expired sessions fail explicitly rather than silently starting unrelated work. No concurrent writers compete over the same continued session. ## Parent communication Every delegated agent learns that its parent Pi session exists, what its assignment is, and how to use the available communication bridge. Parent-supplied knowledge is task-relevant; full transcripts, credentials, and unrelated private context are not automatically copied. The MCP primarily supports context retrieval, human questions, progress updates, and artifact reporting. Any additional Pi capability is a deliberately exposed semantic operation, not arbitrary access to the SDK or all parent tools. Progress identifies the originating task and keeps parent-visible state current without flooding chat. Artifact delivery reports produced content or references with useful metadata; it does not automatically open, upload, publish, or overwrite user artifacts. Questions identify the originating harness/task, await an actual answer, and retain cancellation and unavailable outcomes. Bridge requests remain serviceable while parent Pi awaits the delegated result; human questions must not require a new parent model turn to avoid deadlock. Task-scoped MCP setup must not require persistent edits to the user's harness configuration. ## Interaction model Harness mechanics stay external; MCP carries parent awareness and communication. ```mermaid sequenceDiagram participant P as Parent Pi participant H as External harness participant U as Human P->>H: Task, context, communication bridge H-->>P: Progress or context request P-->>H: Relevant parent context H->>P: Human question through bridge P->>U: Attributed question U-->>P: Answer or dismissal P-->>H: Correlated outcome H-->>P: Result, artifacts, continuation information ``` ## Availability and authentication Hornets loads and remains inspectable even when neither harness exists. Executable presence, supported capabilities, authentication observation, and user preference are separate facts. Discovery performs cheap local checks; expensive probes are deferred until needed and must not block Pi startup. Use non-consuming, non-mutating status information when supported; otherwise authentication remains unknown until an authorized operation establishes more. Missing CLI, unsupported version/capability, login required, unknown auth, launch failure, and runtime failure produce distinct actionable outcomes. Availability observations can become stale and are revised from actual execution failures. Do not infer intended harnesses/providers from saved logins or environment keys. Do not install harnesses, initiate login, copy Pi credentials, or silently change selected harness/model to recover. ## Ownership and independence Each delegation owns its harness work, communication connection, pending questions, progress, and result/artifact references. Cancellation, parent-session invalidation, or shutdown ends owned work and bridge requests; late replies cannot affect another task or session. Preserve user-produced artifacts and report cleanup failures rather than implying unconfirmed termination. Hornets works without Ask, Relop, Dilemma, or the peer-review skill. [Ask Question Events](../PX-SPEC-JCJZVDBZ-ask-question-events/index.md) is an optional richer question service; absent or unclaimed service uses native Pi UI when available, otherwise reports unavailable. Do not redisplay an already-presented question silently after provider failure. No sibling runtime imports or dependency on sibling-owned storage. ## Acceptance criteria - [ ] Claude Code and Codex each support task submission, observable progress, attributable final results, cancellation, and native continuation where available. - [ ] Delegation supports non-review work through the same public contract. - [ ] A child can retrieve relevant parent context, ask a human question, report progress, and deliver artifact references while parent awaits completion. - [ ] Parent sees correct task/harness attribution; answers and late events cannot cross tasks, continued sessions, or parent-session boundaries. - [ ] Hornets remains usable for discovery with zero harnesses installed and distinguishes absent CLI, login required, unknown auth, unsupported capability, and runtime failure. - [ ] Authentication and model selection stay harness-owned; no automatic installation, login, credential copying, persistent harness-config edits, or unapproved fallback occurs. - [ ] Without Ask, interactive questions use native Pi UI; without any usable question provider/UI, requests terminate as unavailable rather than hanging. - [ ] Cancellation and shutdown settle pending questions and communication, stop owned work, and accurately report incomplete cleanup or partial results. - [ ] Artifact reporting does not implicitly open, publish, upload, or overwrite artifacts; missing usage or identity is reported as unknown. - [ ] Hornets functions independently of peer-review policy, Relop, Dilemma, and Ask and preserves root installation and sibling-isolation law.