Subagents

codexclaw lets you assign a model and prompt override to each subagent role, persisted in .codexclaw/subagents.json and exposed over MCP.

Roles

Four roles cover the common subagent workflow:

• explorer — broad codebase investigation and research.
• reviewer — adversarial audit and review.
• executor — focused implementation.
• architect — read-only design proposals and checks of main-owned executable plans.

Formal P keeps the required design sequence: architect proposal, main’s executable plan, then reflection by the same architect before independent review. The existing C0/C1 fast path and explicit user limits still apply. See the workflow guide for phase requirements.

Architect on V1 and native-role hosts

Choose from the live spawn schema, not the model name or a version setting:

• If agent_type: "architect" is exposed, use that native role.
• If there is no agent_type field, use the supported message or text-items channel with CXC-ROLE: architect before TASK:. Attach dev and dev-architecture and explicitly prohibit writes, child spawns and goal/FSM changes. This V1 logical role needs no exception approval, registration or restart.
• If agent_type exists but architect is missing, the native setup is incomplete. With installation authorization, run cxc subagents register architect, start a fresh session and verify the role appears. Do not substitute explorer or reviewer.

The logical V1 role describes task scope; it does not select a native read-only sandbox. If native isolation is explicitly required, report its absence. Architect model/effort/prompt settings and explicit caller overrides retain their existing rules on both routes. Registration preserves user edits and does not pin a model. The architect still supplies a proposal and checks the same plan; a separate reviewer performs the independent audit. The registrar also supports register executor.

MCP tools

Tool	Purpose
subagents_get	Read the per-role config: mode, model, promptOverride.
subagents_set	Update one role’s config.
catalog_list	List selectable models — Codex-native first, then ocx-backed when active.

subagents_set

{
  "role": "reviewer",           // explorer | reviewer | executor | architect
  "mode": "model",              // "default" (main model) or "model" (needs a model id)
  "model": "gpt-5.5",           // required when mode is "model"
  "promptOverride": "..."       // optional per-role prompt, or null
}

Only role is required. mode: "default" uses the main model; mode: "model" requires a model id from catalog_list.

Configuring from the GUI

The GUI dashboard wraps these tools with model pickers and prompt editors so you can set roles without hand-editing JSON.

The pre-tool-use-attaching-skills hook wires into live spawn_agent calls on both surfaces, but it does not choose skills. Dispatchers explicitly name each required skill with preferred [$cxc-<name>](skill://<abs SKILL.md>) links or the plugin-native $codexclaw:cxc-<name> fallback. When the spawn message is plaintext, the hook normalizes known broken/bare mentions and inlines recognized SKILL.md bodies on V2-shaped spawns. Native ChatGPT-backend V2 can give the hook ciphertext. Recognized canonical Fernet-shaped messages are preserved byte-for-byte: no skill text, affordance or leaf guard is appended to them. The hook reports the omitted prompt guards; structural checks identify an opaque frame but do not authenticate or decrypt it. For plaintext messages where no skill body can be inlined, the hook appends a [CXC-SKILL-AFFORDANCE] telling the child to self-load named skills. Configured omitted model/reasoning_effort injection remains available for non-full-history spawns. It never invents role baselines or inferred surface skills. Role config, resolver, and spawn-wrapper are all shipped (L9).

First fallback

Each role can keep one optional fallback model with its own reasoning effort. Select both models from the existing catalog: for example xai/grok-4.6 followed by cursor/grok-4.6. The IDs distinguish the provider routes. This is ordered failover, not round robin: a healthy primary keeps receiving work.

Global and project settings use the same whole-role inheritance as primary settings. Old configurations have no fallback. Removing a project override also restores the global fallback. A null fallback effort inherits the original session’s effort, not the primary role’s effort.

cxc subagents set executor --fallback-model cursor/grok-4.6 --fallback-effort high
cxc subagents set executor --clear-fallback

The same flags apply to explorer, reviewer and architect. Only a returned main-direct action permits main to reclaim remaining work from a managed dispatch. A ready action requires a fresh claim; stop or reconcile permits neither a replacement nor direct takeover. Independent review remains outstanding when required; main-agent work does not satisfy it.

Execution and evidence

CXC’s managed dispatch protocol selects candidates and records attempts. The main agent still calls native spawn/wait tools. SessionStart supplies the protocol when fallbacks are configured; the delegation skill documents the sequence. Existing direct native calls remain possible and are not automatically retried by a hook. Settings alone do not establish that a native host delivered every failure code.

cxc subagents dispatch accepts one JSON object on stdin. Begin with {"action":"start","sessionId":"<native-session>","dispatchId":"<unique-task>","role":"executor"}. Claim the returned attempt with action:claim and attemptId. Only action:spawn authorizes one call; include its marker at the start of the native task message. Report creation/completion or failure, and inspect action:status after a lost response. Records live under .codexclaw/dispatches/<session>/<dispatch>.json.

Quota/model availability failures can select the fallback. Policy, permission, authentication and cancellation failures stop. Ambiguous creation or ongoing work must be reconciled before replacement; stopped executors require a change review and cleanup evidence. Unknown error prose does not trigger blind rotation.

Confirmed stagnation or unusable final output uses a separate outcome:task_failed report with taskFailure: {kind: "stagnation" | "unusable_output", evidence: "..."}. Include the recorded child ID, executionState:stopped, and reconciliation describing termination and partial-work inspection. Both evidence strings must be non-empty and at most 2000 characters. This report has no provider error; it uses the same bounded handoff and returned actions as provider recovery. Cancellation, exhausted limits and a wait timeout alone are not task failures. Validate final work before reporting outcome:complete, which cannot be reopened for recovery.

OCX retains its own retries and global/per-model fallback. The two-attempt limit applies to CXC-issued native attempts, not every downstream provider request. Requested and observed models are recorded separately; an unobserved actual model stays unknown. No quota balance, even split, or universal native-hook delivery is implied by configuring a fallback.