/cvg-multi-session

name: cvg-multi-session
description: Orchestrate real specialist sessions as one monitored multi-agent workflow. Use when the user asks to coordinate or supervise multiple agent sessions, planning or implementation loops, or worker/reviewer handoffs, on Codex threads or Claude Code background agents.
argument-hint: "[goal, plan path, worktree, or workflow description]"

Multi-Session Workflow

Use this skill when the current session should act as an **orchestrator** over other real specialist sessions.

The workflow is repo-independent. Specialist prompts should carry only the coordination data the specialist cannot infer from the selected role skill and source artifact. Do not paste broad repo rules, likely-file lists, old phase state, or role-skill procedures unless they are task-specific authority.

Non-Negotiable Protocol Gates

Apply these gates before any planner, worker, reviewer, QA runner, or quality reviewer is launched.

Gate 0: Transport Binding

Tool contracts and existing user authorization govern task creation, delegation and external actions; a skill invocation does not grant additional permissions.

Bind the specialist operations to the current platform before applying any other gate:

| Operation | Codex | Claude Code | |---|---|---| | Spawn specialist | `create_thread` | `Agent` tool with `run_in_background: true` | | Continue specialist | `send_message_to_thread` on the same thread id | `SendMessage` to the agent id | | Verify identity | `read_thread` on the returned thread id | agent id in the `Agent` tool result | | Inspect output | `wait_threads` and `read_thread` | `TaskOutput` or the completion notification | | Wait | one bounded `wait_threads` call, then heartbeat handoff if still active | end the turn; the harness re-invokes the orchestrator on `<task-notification>` |

The authoritative specialist identity is always the id returned by the platform tool — never an id the specialist writes in prose. Do not accept placeholder specialist identity in callback templates.

On Claude Code, background specialists can spawn their own subagents (auxiliary reviewers, researchers), and a completed specialist is resumed from its persisted transcript when continued with `SendMessage`. Both loop requirements are natively supported; do not flatten a specialist's internal delegation into the orchestrator.

If the transport tools are not available after searching for them, report a tool-layer blocker. Do not fall back to inline simulation of a specialist.

Gate 1: Real Specialist Session

Specialists must run as real, individually addressable platform sessions: Codex threads or Claude Code background agents.

• Spawn a new specialist with the spawn operation unless the user explicitly named an existing specialist session.
• Continue an existing specialist with the continue operation.
• Verify every specialist id immediately after creation or selection with the Gate 0 verify operation.
• Do not use local shell jobs, detached processes, or inline role-play in the orchestrator turn as substitutes for a real specialist session.
• Do not treat a process id, shell job id, or model-generated id as a specialist id.
• If the id returned by the spawn operation cannot be verified, stop the workflow and retry with the platform specialist tools or report a tool-layer blocker.
• If the platform specialist tools are not loaded, search for them first. If they still cannot be loaded, report a tool-layer blocker.

(Claude Code) The specialist tools to search for are `Agent`, `SendMessage`, and `TaskOutput`. The `Agent` tool result already carries the authoritative agent id; no separate read or identity note is needed.

Gate 2: Orchestrator Callback Transport

Every specialist prompt must include:

• the callback destination,
• exact callback template,
• instruction to include `Audit artifact: <absolute path>` when the specialist

creates or receives an audit artifact.

On Claude Code, the specialist's final message is the callback: the harness delivers it to the orchestrator as the completion notification, so the specialist must format that final message per the callback template.

If the specialist creates or receives an audit artifact, the callback must include `Audit artifact: <absolute path>`.

The specialist must use the verified id supplied by the orchestrator in its callback body.

The orchestrator treats the phase as pending until the callback is visible.

Gate 3: Waiting Handoff

Waiting is handled by the platform, not by manual polling.

Handoff sequence:

1. Send the specialist work with the spawn or continue operation. 2. Verify the specialist id per Gate 1. 3. Tell the user the specialist id. 4. End the active turn and let the platform deliver the callback.

(Claude Code) The harness re-invokes the orchestrator with a `<task-notification>` when the specialist completes; no heartbeat exists or is needed.

Do not emulate waiting with `sleep`, repeated reads, shell loops, timers, or repeated status checks in the same assistant turn — on either platform.

This gate forbids in-turn waiting, not background watchers: a background watcher command that exits when its condition holds (the hybrid loops' codex-completion watcher) is the platform's single-completion shape and ends the turn properly — arming one is not a violation of this gate.

A wake-up turn (heartbeat on Codex, task notification on Claude Code) may do one status check. If the specialist is still active, report one short status and stop. Do not sleep and check again.

Continue immediately only when an explicit callback is already present or the specialist is already shown as completed.

Gate 4: Role-Specific Review Feedback

Reviewer feedback returns to the same planner or worker session that produced the reviewed artifact, via the continue operation.

The orchestrator adjudicates scope and severity against the original user outcome, authorized changes and concrete evidence before routing repairs