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 ///etc. agent types for this — an arcgentic-installed project ships those agent types (see , , at the repo root) and their names match the V2 role names, but they implement a different, incompatible V1/v0.2 contract (V1's 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.

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>'
   

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.