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/return-signal exchange). Dispatching a role through one of those types would run the wrong contract.
     • multi-session-subthread mode: call Agent with the same prompt but run_in_background: true.
     • Either way, Agent's return carries a real, resumable agentId — that is what you record as the broker thread-id in step 5, not actions[0].thread_id (for a create action that field is only a placeholder, not a real agent id).
   • kind: "reuse":
     • Do NOT call Agent — that would create a brand-new agent and orphan this role's existing context. actions[0].thread_id is already the real, previously-recorded agentId for this role.
     • Call SendMessage with to = actions[0].thread_id and message = actions[0].prompt.
     • SendMessage delivers asynchronously — it does not hand you the reply inline the way a foreground Agent call does. Treat this like a background dispatch: end your turn after step 6 and wait for the reply to arrive as a message from that agent.

5. Record the session — kind: "create" only, using the agentId Agent returned as the broker thread-id:

   arcgentic v2-record-session \
     --state .agentic-rounds/state.yaml \
     --host claude-code-broker \
     --role <planner|developer|test|auditor> \
     --thread-id <agentId>

   kind: "reuse": skip this step. The role is already recorded from its earlier dispatch — that recorded thread is exactly why this action was reuse instead of create. Re-running v2-record-session with the same thread-id would be harmless/idempotent, but it records nothing new, so there is no reason to run it.

6. Record the dispatch, using the thread-id from step 4 (the new agentId for create, or actions[0].thread_id for reuse):

   arcgentic v2-dispatch-role \
     --state .agentic-rounds/state.yaml \
     --host claude-code-broker \
     --role <planner|developer|test|auditor> \
     --thread-id <thread-id-from-step-4>

   This puts the Orchestrator to sleep waiting for this role's reply. In background mode (a multi-session-subthread create dispatch, or any reuse dispatch — those go through SendMessage, which is always asynchronous), end your turn here: you'll resume via the task-notification (background Agent) or the peer's reply message (SendMessage). In foreground mode (a single-session-subagent create dispatch via a foreground Agent call), continue directly to the next step in this same turn — you already have the role's output from step 4.

7. Collect the role's output:
   • Foreground Agent call: its return value IS the role's output — continue directly to step 8 in the same turn, no waiting.
   • Background Agent call: wait for the task-notification. When it arrives, its content is the role's output. Do not poll ListAgents for completion — the notification is the completion signal.
   • SendMessage (reuse dispatch): wait for the agent's reply message. When it arrives, its content is the role's output — validate it for the footer exactly like a fresh Agent call's return value (step 8, next).
8. Validate the output contains exactly one ```arcgentic-role-return ... ``` fenced JSON footer (or the ARCGENTIC_ROLE_RETURN ... END_ARCGENTIC_ROLE_RETURN marker form). If it's missing or malformed, use SendMessage to resume the same agent (by its agentId) with a corrective instruction: "Your last response was missing the required arcgentic-role-return footer. Re-send your summary with exactly one such footer, formatted as instructed." Repeat step 8 with the resumed agent's reply. This is the same fail-closed contract the hook fallback enforces via decision: block — here it's enforced by you, the orchestrator, checking directly, since there is no external hook watching this session.

9. Record the signal, which wakes the Orchestrator:

   arcgentic v2-return-signal \
     --state .agentic-rounds/state.yaml \
     --signal-json '<the footer JSON from step 8>'

10. Go back to step 1 and dispatch the next role.

Procedure — hook fallback

Use this procedure only when tier 0's Agent/SendMessage/ListAgents are not available in this session.

1. Install project-local Claude Code hooks once:

   arcgentic claude-code-broker install-hooks \
     --settings .claude/settings.local.json \
     --state .agentic-rounds/state.yaml

   The installed Stop/SubagentStop hook calls:

   arcgentic claude-code-broker handle-stop \
     --state .agentic-rounds/state.yaml

   The hook reads Claude Code's last_assistant_message, extracts the arcgentic-role-return footer, runs the same V2 return validation, updates .agentic-rounds/state.yaml, and writes a broker inbox record under .agentic-rounds/claude-code-broker/inbox/.

2. Initialize or read V2 host state:

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

3. If orchestrator_status is sleeping, stop immediately. The broker is waiting for pending_role; do not dispatch another role.

4. If orchestrator_status is active, create or resume only the single role context in actions, then record its broker id:

   arcgentic v2-record-session \
     --state .agentic-rounds/state.yaml \
     --host claude-code-broker \
     --role <planner|developer|test|auditor> \
     --thread-id <broker-session-id>

5. Inject only that role's prompt. The developer does not receive auditor reasoning. The auditor does not receive developer chat transcript. The planner owns phase decisions.

6. After injecting the role prompt, put the Orchestrator to sleep and end the Orchestrator turn:

   arcgentic v2-dispatch-role \
     --state .agentic-rounds/state.yaml \
     --host claude-code-broker \
     --role <planner|developer|test|auditor> \
     --thread-id <broker-session-id>

7. Require every role turn to end with RoleReturnSignal JSON.

8. Record the signal. This wakes the Orchestrator and clears the pending dispatch:

   arcgentic v2-return-signal \
     --state .agentic-rounds/state.yaml \
     --signal-json '<RoleReturnSignal JSON>'

9. Re-run v2-session-plan --host claude-code-broker and dispatch the next role.

Hook guidance

When hooks are available, configure stop hooks to extract the role's final response and pass it back to the orchestrator as context. The hook must not invent a PASS/NEEDS_FIX outcome. It only transports the role's own RoleReturnSignal.

The bundled hook runtime uses official Claude Code Stop/SubagentStop input fields, especially last_assistant_message and stop_hook_active. If the Orchestrator is sleeping and the role output lacks a valid footer, the hook blocks once with a corrective reason. If stop_hook_active is already true, it does not block again, preventing hook recursion.

Fail-closed rules

• If a role returns prose without valid RoleReturnSignal, do not advance.
• If the broker cannot identify which role produced a signal, do not advance.
• If the Orchestrator is sleeping, do not dispatch more work until the pending role returns.
• If a role tries to rename itself outside the four fixed titles, reject it.
• If Claude Code transport is unavailable, fall back to explicit copy-back rather than pretending automation succeeded.