/claude-code-session-broker

name: claude-code-session-broker
description: Use when running Arcgentic V2 in Claude Code and fixed Planner, Developer, and Auditor role sessions must be coordinated through a broker.

claude-code-session-broker

Use this skill for Claude Code V2 parity. Claude Code does not expose the same Codex thread tools to Arcgentic, so V2 parity is broker-backed: the broker keeps the same four-role state contract and uses native Claude Code tooling (subagents via `Agent`/`SendMessage`/`ListAgents`), hooks, or explicit copy-back, depending on what the host supports — see "Broker priority" below for the exact three transports and their order.

Relevant host capabilities:

• Subagents provide isolated role contexts within a session, and back

tier 0's `Agent`/`SendMessage`/`ListAgents` dispatch: <https://code.claude.com/docs/en/sub-agents>

• Hooks can observe stop events and final assistant output, and back the

hook-backed broker fallback: <https://code.claude.com/docs/en/hooks>

• Agent Teams (<https://code.claude.com/docs/en/agent-teams>) coordinate

across separate sessions when enabled, but they are a different host feature from this skill's three transports below. Tier 0 supersedes Agent Teams for V2 dispatch — do not treat Agent Teams as a live, separate transport option here.

Contract

V2 still has exactly five role identities:

• `Orchestrator`
• `Planner`
• `Developer`
• `Test`
• `Auditor`

Do not create round-numbered role identities. Store round identity in state and prompt payloads.

Broker priority

Use the strongest available transport, checked in this order:

1. **Native tooling (tier 0)** — if this session's own tool list includes `Agent`, `SendMessage`, and `ListAgents`, use them directly (see "Procedure — tier 0" below). For a first-time dispatch to a role (`kind: "create"`), dispatch is synchronous for a foreground `Agent` call (you get the role's output the moment the call returns — no external event to wait for) or notification-driven for a background `Agent` call (a task-notification arrives with the role's output when it finishes); either way, `Agent`'s result carries a resumable `agentId` you record as the broker `thread-id`. For a repeat dispatch to a role that already has a recorded thread (`kind: "reuse"` — e.g. a `needs_fix` loop back to Developer), skip `Agent` entirely and use `SendMessage` against that already-recorded `agentId` instead; its reply arrives asynchronously, like a background `Agent` call's notification. 2. **Hook-backed broker (fallback)** — use when tier 0's three tools are not present in this session (see "Procedure — hook fallback" below). 3. **Explicit copy-back (last resort)** — when neither of the above is available: the role session returns `RoleReturnSignal` in its own output, and a human or the orchestrator manually runs `arcgentic v2-return-signal` with that JSON. No automation attempts this on its own; do not pretend it succeeded silently.

All three transports write the same state shape via the same CLI commands (`v2-session-plan`, `v2-record-session`, `v2-dispatch-role`, `v2-return-signal`) — only how the role's prompt gets delivered and its output gets collected differs.

Procedure — tier 0 (native tooling)

Check once per session, before dispatching anything: does your own tool list include `Agent`, `SendMessage`, and `ListAgents`? If yes, use this procedure. If no, skip to "Procedure — hook fallback" below.

1. Get the dispatch plan:

   arcgentic v2-session-plan \
     --state .agentic-rounds/state.yaml \
     --host claude-code-broker \
     --user-request '<current user request>'

2. If the JSON's `orchestrator_status` is `sleeping`, stop immediately — a role is already dispatched and pending; do not dispatch another.

3. If `orchestrator_status` is `active`, read `actions[0]`. Its `prompt` field is the complete, ready-to-send role prompt (it already contains the `arcgentic-role-return` footer instructions — do not edit it, do not add or remove content). Its `kind` field is either `"create"` (no thread is recorded for this role yet) or `"reuse"` (this role already has a recorded thread from an earlier dispatch — e.g. Developer's `needs_fix` loop back to Developer, Auditor's `audit_in_progress` retry, or a new round's Planner dispatch after the previous round closed). `reuse` is normal, common V2 routing, not an edge case — branch on `kind` in step 4 below.

4. Dispatch, branching on `actions[0].kind`:

• `kind: "create"`: before calling `Agent`, your own working

directory must already be the target project root. `Agent` has no working-directory parameter of its own — a dispatched agent inherits your shell's cwd and has no other way to learn where the project is, so if the orchestrator's shell has not already `cd`'d into the project root, the role prompt's relative file paths (e.g. `.agentic-rounds/state.yaml`, `docs/plans/...`) will resolve against the wrong directory. (This does not apply to `kind: "reuse"` below — that dispatches via `SendMessage` to an already-running agent, which already has its own working directory from when it was first created.)

• `single-session-subagent` mode: call the `Agent` tool with

`prompt` = `actions[0].prompt`, `run_in_background: false` (foreground — you get the result directly in this same turn), and `subagent_type: "general-purpose"`. Do NOT use arcgentic's own `planner`/`developer`/`auditor`/etc. agent types for this — an arcgentic-installed project ships those agent types (see `agents/planner.md`, `agents/developer.md`, `agents/auditor.md` at the repo root) and their names match the V2 role names, but they implement a different, incompatible V1/v0.2 contract (V1's `planner` agent produces "18/12/10-section handoff docs", not a V2 role-prompt/