claude-code-session-broker

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

   ```bash
   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

From Arch1eSUN/Arcgentic, MIT.

More from Arch1eSUN/Arcgentic