Handoff
Orchestrator — cross-session A2A (channel:prompt vs channel:artifact). Shared vocabulary → process-skill-composition.md.
References: pack.md · output.md · handoff-subagent-dispatch.md
When you calibrate claims, read research-basis.md.
Entry gate
- New chat intended — same-session continuation without transfer is out of scope.
- Channel chosen —
prompt (user) or artifact (model-invoked).
Non-negotiables
- Pointers not bodies — paths, URLs, SHAs. Never paste plans, PRDs, or diffs into handoff.
- Honest state — done vs in-progress vs broken. When you claim progress, cite commits or tests.
- Redact secrets, tokens, and PII before write or paste.
- Channel prompt — user
/handoff → no disk (_agent/handoffs/ forbidden).
- Channel artifact — model-invoked → subagent write mandatory. Coordinator-primary write is a violation.
Workflow
- Pick the channel, pack, and goal — use the closest rows in pack.md. These values control production only.
- Gather — minimal bullets from thread. Omit empty categories.
- Deliver —
channel:prompt → fenced receiving prompt per output.md in pragmatic STEchannel:artifact → handoff-subagent-dispatch.md → paste stub only
Execution interface map
Use this map when the request says "handoff via X client."
- Pick channel from producer intent:
prompt for user-directed handoff (/handoff)artifact for model-invoked context-pressure continuation
- Build one canonical payload from
pack, goal, and thread claims.
- Route to the client interface:
prompt: emit receiving prompt block and hand it to next chat startup.artifact: write <workspace>/_agent/handoffs/<filename>.md, then emit only the read stub.
- Validate output with the client-specific rule.
Cross-client default behavior
| Interface |
Transport rule |
Producer action |
Required receive artifact |
| Codex |
Chat thread controls |
channel:prompt for user handoff, channel:artifact for model-invoked |
channel:prompt block or handoff artifact path |
| Cursor |
Conversation continuation |
channel:prompt into fresh chat unless artifact hook is explicitly available |
Prompt block |
| Claude Code |
Chat continuation |
channel:prompt into fresh chat; if client-specific task API exists, pass block as first user message |
Prompt block |
| Claude API / GPT-like interface |
Chat continuation |
channel:prompt is required; map fields to a user-visible handoff message |
Prompt block |
| ChatGPT UI / web chat |
Chat continuation |
channel:prompt with Open workspace target first line |
Prompt block |
| GitHub Copilot Chat |
IDE continuation |
channel:prompt only; no shared artifact path unless local host exposes handoff write |
Prompt block |
| Generic MCP / custom client |
API-specific |
map to canonical payload fields; if no artifact support, downgrade to prompt |
Prompt block (or artifact path if supported) |
When an interface does not expose an artifact API, always fall back to channel:prompt.
Codex API branch
Use this when the ask explicitly targets Codex API execution.
- Build
channel:prompt payload from plan claims.
- Prefer one of:
- start fresh chat with the prompt payload if orchestration is in user flow.
- use
create_thread for a new Codex task, then send_message_to_thread with the prompt block for handoff bootstrap.
- For
channel:artifact, call handoff with channel:artifact via your orchestration flow, spawn the subagent writer path, then emit only the stub pointing to <workspace>/_agent/handoffs/<filename>.md.
Avoid fabricating any unsupported Codex tool calls. If a required API is unavailable, document fallback at channel:prompt.
High-volume interface notes
- For clients with both UI and API modes, document the mode explicitly in your own orchestration.
- If a client has a structured conversation API, preserve the same fields and map only into its initial message payload.
- For IDE-native chat clients, prefer prompt mode with explicit workspace.
Interface execution boundaries
- Don’t hard-code any one chat stack’s control API as the only supported path.
- Do not include
channel and pack inside receiving content.
- Don’t skip the redaction rule for any interface.
- Don’t write handoff files from the coordinator for
channel:artifact; spawn/coordinate the subagent path when required.
If the next session needs only review state, use consumer overlay blocks instead of Pack: full.
Consumer bindings
Project-specific injected context is appended on skill read.
1---2name: handoff3description: Agent-to-agent cross-session transfer — pointers not bodies. Channel prompt (user /handoff) or artifact (model-invoked subagent). Pack and Goal are open vocabulary. Orchestrator for continuing work in a fresh chat. Not same-session continuation without a new chat.4---56# Handoff78<!-- source-of-truth: compact session transfer — **what to rip out**, not full orchestration. -->9<!-- doc-meta: owner=eng | last-reviewed=2026-09-01 -->1011**Orchestrator** — cross-session A2A (`channel:prompt` vs `channel:artifact`). Shared vocabulary → [process-skill-composition.md](https://raw.githubusercontent.com/csark0812/toolbox/main/references/process-skill-composition.md).1213References: [pack.md](references/pack.md) · [output.md](references/output.md) · [handoff-subagent-dispatch.md](references/handoff-subagent-dispatch.md)1415When you calibrate claims, read [research-basis.md](references/research-basis.md).1617## Entry gate1819- **New chat** intended — same-session continuation without transfer is out of scope.20- **Channel** chosen — `prompt` (user) or `artifact` (model-invoked).2122## Non-negotiables23241. **Pointers not bodies** — paths, URLs, SHAs. Never paste plans, PRDs, or diffs into handoff.252. **Honest state** — done vs in-progress vs broken. When you claim progress, cite commits or tests.263. **Redact** secrets, tokens, and PII before write or paste.274. **Channel prompt** — user `/handoff` → **no disk** (`_agent/handoffs/` forbidden).285. **Channel artifact** — model-invoked → subagent write mandatory. Coordinator-primary write is a **violation**.2930## Workflow31321. **Pick the channel, pack, and goal** — use the closest rows in [pack.md](references/pack.md). These values control production only.332. **Gather** — minimal bullets from thread. Omit empty categories.343. **Deliver** —35 - `channel:prompt` → fenced receiving prompt per [output.md](references/output.md) in pragmatic STE36 - `channel:artifact` → [handoff-subagent-dispatch.md](references/handoff-subagent-dispatch.md) → paste stub only3738## Execution interface map3940Use this map when the request says "handoff via X client."41421. Pick channel from producer intent:43 - `prompt` for user-directed handoff (`/handoff`)44 - `artifact` for model-invoked context-pressure continuation452. Build one canonical payload from `pack`, `goal`, and thread claims.463. Route to the client interface:47 - `prompt`: emit receiving prompt block and hand it to next chat startup.48 - `artifact`: write `<workspace>/_agent/handoffs/<filename>.md`, then emit only the read stub.494. Validate output with the client-specific rule.5051### Cross-client default behavior5253| Interface | Transport rule | Producer action | Required receive artifact |54| ------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |55| Codex | Chat thread controls | `channel:prompt` for user handoff, `channel:artifact` for model-invoked | `channel:prompt` block or handoff artifact path |56| Cursor | Conversation continuation | `channel:prompt` into fresh chat unless artifact hook is explicitly available | Prompt block |57| Claude Code | Chat continuation | `channel:prompt` into fresh chat; if client-specific task API exists, pass block as first user message | Prompt block |58| Claude API / GPT-like interface | Chat continuation | `channel:prompt` is required; map fields to a user-visible handoff message | Prompt block |59| ChatGPT UI / web chat | Chat continuation | `channel:prompt` with `Open workspace` target first line | Prompt block |60| GitHub Copilot Chat | IDE continuation | `channel:prompt` only; no shared artifact path unless local host exposes handoff write | Prompt block |61| Generic MCP / custom client | API-specific | map to canonical payload fields; if no artifact support, downgrade to prompt | Prompt block (or artifact path if supported) |6263When an interface does not expose an artifact API, always fall back to `channel:prompt`.6465### Codex API branch6667Use this when the ask explicitly targets Codex API execution.68691. Build `channel:prompt` payload from plan claims.702. Prefer one of:71 - start fresh chat with the prompt payload if orchestration is in user flow.72 - use `create_thread` for a new Codex task, then `send_message_to_thread` with the prompt block for handoff bootstrap.733. For `channel:artifact`, call `handoff` with `channel:artifact` via your orchestration flow, spawn the subagent writer path, then emit only the stub pointing to `<workspace>/_agent/handoffs/<filename>.md`.7475Avoid fabricating any unsupported Codex tool calls. If a required API is unavailable, document fallback at `channel:prompt`.7677### High-volume interface notes7879- For clients with both UI and API modes, document the mode explicitly in your own orchestration.80- If a client has a structured conversation API, preserve the same fields and map only into its initial message payload.81- For IDE-native chat clients, prefer prompt mode with explicit workspace.8283### Interface execution boundaries8485- Don’t hard-code any one chat stack’s control API as the only supported path.86- Do not include `channel` and `pack` inside receiving content.87- Don’t skip the redaction rule for any interface.88- Don’t write handoff files from the coordinator for `channel:artifact`; spawn/coordinate the subagent path when required.8990If the next session needs only review state, use consumer overlay blocks instead of `Pack: full`.9192## Consumer bindings9394Project-specific injected context is appended on skill read.
csark0812