Agents consilium

Consilium v5: Multi-Agent Review & Delegation

Query external AI agents for independent expert opinions, structured code review, or full-YOLO task delegation. Review modes stay read-only. Delegate hands the whole task to exactly one explicitly selected agent in the caller's CWD.

Public CLI (only entrypoint)

scripts/consilium review ask [...]
scripts/consilium review code --depth basic|specialists|super|ultra [...]
scripts/consilium delegate -a <exact-agent-id> [...]
scripts/consilium delegate -a <exact-agent-id> --steerable [...]
scripts/consilium delegate steer RUN_ID [--mode auto|queue|interrupt] [...]
scripts/consilium delegate status RUN_ID [--json]
scripts/consilium delegate cancel RUN_ID
scripts/consilium --list-agents

Old public scripts (consensus-query.sh, code-review.sh, superreview.sh, ultrareview.sh, *-query.sh) were removed in v5. Internal modules live under scripts/lib/.

Why this skill

Different frontier models see different things. Parallel independent reviews surface issues and alternatives one model alone misses. Consilium keeps agents independent (no debate, no cross-contamination) and lets the caller adjudicate.

Modes

Mode	Read/write	Purpose
review ask	read-only	Open-ended question → parallel opinions
review code --depth basic	read-only	2 specialists: security + correctness
review code --depth specialists	read-only	5 specialists
review code --depth super	read-only	Multi-stage superreview + LLM judge
review code --depth ultra	read-only	Multi-stage ultrareview + LLM judge
delegate -a <id>	full YOLO	One agent implements the task in CWD

review ask

scripts/consilium review ask "Should we use Postgres or SQLite?"
scripts/consilium review ask --xml --prompt-file prompt.md
scripts/consilium review ask -a codex,grok "Review this approach"
scripts/consilium review ask -a 'opencode-go-*' -x opencode-go-minimax "Q"
scripts/consilium --list-agents

Exit codes: 0 all ok · 2 partial · 3 all failed · 4 config · 5 usage.

review code

scripts/consilium review code path/to/file.py
scripts/consilium review code --depth specialists --xml path/to/file.py
git diff HEAD | scripts/consilium review code --diff
scripts/consilium review code --depth super path/to/file.cs
scripts/consilium review code --depth ultra --dry-run path/to/file.cs

• basic (default): security + correctness, fixed 2 passes, quoted-code validation.
• specialists: + performance, architecture, consistency.
• super / ultra: multi-stage discovery + deterministic dedup + LLM judge (same stage layouts as v4 superreview/ultrareview).

Exit codes for review code (basic/specialists): 0 all specialists ok · 2 partial (report still emitted from successes) · 3 all failed · 4 config · 5 usage.

Review is always read-only. Do not use Grok's /review slash command — consilium owns review semantics.

delegate

scripts/consilium delegate -a grok "Implement the caching layer described in DESIGN.md"
scripts/consilium delegate -a codex --prompt-file task.md

• Exact agent id required (-a). No globs, no default agent, no multi-select.
• Full YOLO in the caller's CWD: no sandbox, no approval prompts, no confirmation flag.
• Supported: Codex CLI, Claude Code, OpenCode, native Grok Build.
• Gemini is review-only — delegate rejects gemini-cli.

delegate --steerable

Long-lived single-agent session with a filesystem mailbox. Prints run_id=… early on stderr; final answer still goes to stdout when the run completes.

scripts/consilium delegate -a grok --steerable "Implement the caching layer"
# other terminal / later:
scripts/consilium delegate steer run_<id> --mode auto "Prefer Redis over memcached"
scripts/consilium delegate status run_<id> --json
scripts/consilium delegate cancel run_<id>

Required workflow for the calling agent

Use this sequence whenever the user may want to redirect an active delegate:

1. Run the command from the target project CWD. Start it in a long-running process/PTY or in the background so the calling agent remains able to read progress and issue control commands. Do not wait synchronously for the final stdout before attempting to steer.
2. Read early stderr and capture the exact run_id=run_<id>. Keep the original process handle open: its stderr is the live progress stream and its stdout will contain the final answer.
3. If CONSILIUM_STEER_DIR was overridden for the start command, pass the same environment value to every later steer, status, and cancel command.
4. Send only new information or a clear course correction. Do not repeat the entire original task. Use --prompt-file or stdin for long guidance.
5. Use --mode auto unless the user explicitly needs different semantics. Record the returned client_id and seq. For Grok, auto/queue is the productive default for additive details. Use interrupt only to replace the current direction: every later interrupt intentionally supersedes the prompt currently running, including an earlier steer.
6. Treat the immediate accepted response as mailbox persistence only. Query delegate status RUN_ID --json, find the matching client_id, and inspect mailbox_status, delivery_class, backend_ack, and error.
7. Continue observing the original process. Later backend events may advance the steer from request_sent/queued to running and completed, or end it as cancelled, dropped, failed, or rejected.
8. Wait for the original delegate process to finish and consume its stdout as the final answer. Use cancel only when intentionally stopping the whole delegated run.

Choose the mode deliberately:

Mode	Use when	Important consequence
auto	Normal clarification, extra constraint, or preferred direction	Uses the safest native behavior available for that backend
queue	The current work may finish; apply guidance at the backend's next safe boundary	May not affect the currently executing turn; for Grok it is a real next-turn FIFO entry
interrupt	The current direction is wrong and its partial work should be abandoned	May cancel the active turn/tool flow; Claude rejects it instead of silently downgrading

Interpret steer status precisely:

mailbox_status	Meaning
accepted	Persisted locally; the supervisor has not dispatched it yet
delivering	The supervisor is currently calling the backend adapter
request_sent	Written to the backend transport; no application evidence yet
queued	Queued/accepted by the backend but not yet observed running
awaiting_queue_resolution	Grok returned Cancelled for a never-observed-running prompt; wait for the authoritative next queue snapshot before deciding merged vs dropped
merged	Grok combined this steer text into another running prompt; keep observing that linked prompt
running	The backend correlated the steer with an active prompt/turn; this does not prove the requested effect happened
completed	That steer prompt ended without a cancellation/error stop reason; verify artifacts/result for semantic compliance
incomplete	Grok stopped the steer at a token limit; its requested work may be partial
applied	A backend with a direct replay/injection acknowledgement confirmed receipt; still verify task effects when they matter
cancelled	The steer turn started but was cancelled, commonly by a later interrupt; do not assume its requested work happened
superseded	A later Grok interrupt (sendNow) intentionally replaced this steer; inspect superseded_by_prompt_id
dropped	Grok removed a never-observed-running prompt and later queue evidence did not show a merge
abandoned	The overall delegate run ended before this steer produced a terminal protocol outcome
failed / rejected	The steer did not complete normally; inspect error / backend_ack and decide whether to retry or start a new run

For retry-safe automation, provide a stable --client-id:

scripts/consilium delegate steer run_<id> \
  --client-id requirement-cache-backend-v1 \
  --mode auto \
  --prompt-file steer.md

Retry the same client_id only with identical guidance, mode, and kind. Changing any of them is an idempotency conflict and is rejected. If the run is already terminal or its mailbox is closed, do not keep retrying that run; start a new delegate with the remaining task. Do not put secrets into steer guidance unless persistence in private raw/audit artifacts is intentional.

• Large task/guidance bodies travel via files or mailbox JSON — never large argv/env.
• Mailbox accepted ≠ protocol delivery, execution, or compliance. status shows delivery_class and backend evidence separately.
• Protocol lifecycle is backend-specific. Never reinterpret request_sent, queued, or running as proof that guidance changed files or the final answer. completed proves prompt lifecycle completion, not semantic compliance.
• Registry root: CONSILIUM_STEER_DIR (default under user cache). Permissions: registry/run dirs 0700, state files 0600. Symlink run dirs are rejected.
• An active supervisor periodically validates its registry independently of model output. If its own run metadata is deleted or malformed, it safely rebuilds the private run structure, emits registry_recovered, and keeps the harness running. Unsafe symlink/ownership failures remain degraded instead of being overwritten; they cannot suppress the model's final stdout, and final artifacts are attempted before service-state finalization.
• Steerable always keeps a service registry + protocol artifacts (mailbox, audit, raw/normalized/final under the private registry run or the configured CONSILIUM_RUN_DIR) for observability — even when CONSILIUM_SAVE_OUTPUTS=0 disables ordinary review/delegate archival. With SAVE_OUTPUTS=0, protocol artifacts never land in the project cwd; meta.artifacts_dir records the private 0700 path. Registry is independent of output archival.
• Client ids are never used as path components (SHA-256 safe names); original client_id is stored in JSON. Idempotent retry requires the same content hash, mode, and kind; otherwise conflict is rejected.
• Terminal transition serializes with enqueue: remaining open mailbox messages are failed with an explicit reason; no accepted/delivering message is left without a terminal outcome.

Honest delivery matrix

Backend	auto	queue	interrupt
Claude Code	same_turn (stream-json stdin + user replay)	same as auto	rejected (no silent downgrade)
Codex CLI	same_turn (turn/steer + expectedTurnId)	same as auto	abort_and_prompt (turn/interrupt → wait turn/completed for that turn → turn/start); stale turn id → explicit reject
OpenCode	step_inject (prompt_async at step boundary; works while busy)	same as auto	abort_and_prompt (session abort then prompt); loopback-only URL + redirect re-validation; per-run OPENCODE_SERVER_PASSWORD Basic auth (password never logged/stored); message.part.updated is cumulative per part id
Grok Build	queue_next_turn (concurrent ACP session/prompt; server FIFO)	same as auto	cancel_and_send (second prompt with _meta.sendNow: true + own promptId)

Grok steerable uses native ACP grok agent stdio concurrent prompt queue semantics (not same-turn injection, not external holding of prompts until first completion). Attribution uses _meta.promptId on notifications and x.ai/session/prompt_complete / _x.ai/session/prompt_complete, plus _x.ai/queue/changed (entries[].id, runningPromptId, runningCombinedTexts). Writing a concurrent session/prompt is request_sent/queued; runningPromptId or prompt-attributed updates advance it only to running. When Grok combines a queued follower into another prompt, consilium reports merged, links merged_into_prompt_id, and follows the front prompt to a terminal outcome. Grok deliberately returns a Cancelled RPC for a combined follower before its authoritative runningCombinedTexts broadcast, so consilium first reports awaiting_queue_resolution; the next queue snapshot resolves that state to merged or dropped. end_turn becomes completed; max_tokens becomes incomplete; refusal becomes rejected; a normal cancellation becomes cancelled; cancelTrigger=send_now becomes superseded and links superseded_by_prompt_id; error, rate_limit, and unknown stop reasons become failed. Grok transport events cannot prove that the model semantically obeyed guidance, so the Grok adapter never claims applied. steer() itself never waits on Grok: it returns transport state immediately so the supervisor can accept more guidance and stream/reconcile lifecycle events. Terminal outcomes cannot be overwritten by late weaker acknowledgements except the evidence-backed refinement cancelled → superseded. If the whole run ends while a steer is still lifecycle-open, it becomes abandoned instead of remaining stuck. Only agent_message_chunk (and confirmed aliases) contributes to final text; agent_thought_chunk is progress/thought only; user_message_chunk is replay only.

Codex interrupt uses a local protocol-ack wait (bounded handshake for the interrupted turn's turn/completed) — not a global run timeout. Ordinary turn/completed with status completed ends this delegate run (not a permanent idle session).

Claude authoritative result events complete the adapter even if stdin remains open; stderr is always drained. Same-turn steers remain possible until that result.

Observability contract

Stream	Content
stderr	Compact semantic live progress (`[consilium] start
stdout	Clean final answer only
artifacts	Per-run dir under CONSILIUM_OUTPUT_DIR (or CONSILIUM_RUN_DIR): raw/*.jsonl, normalized/*.jsonl, final/*.txt, final.txt. Keys are per-invocation: plain agent id for ask/delegate, agent.role for basic/specialists code review, explicit stage/index keys for super/ultra discovery (<stage>.<index>.<agent>.<role>), and judge.primary.<agent> / judge.fallback.<agent> for judge attempts. Fan-out never relies on ambient inherited CONSILIUM_ARTIFACT_KEY alone.

Architecture: backend_cmd | normalize_stream.py --raw-out --progress --extract-text. Each raw line is persisted and normalized immediately; progress reaches stderr before process completion. PIPESTATUS preserves backend exit (timeout/signal) and Grok end/error validation independently.

Disable ordinary review/delegate archival with CONSILIUM_SAVE_OUTPUTS=0. Steerable runs still maintain their service registry (CONSILIUM_STEER_DIR) and protocol artifacts needed for steer/status/cancel observability.

Resource-limit contract

Consilium is unlimited by default:

• no wrapper timeout (AGENT_TIMEOUT=0);
• no max-turns, step, token, response-length, or budget flags;
• prompts travel over stdin or a temporary prompt file, never as large argv values;
• delegate reads file/stdin//dev/stdin task sources exactly once into a private temporary file, so pseudo-files and non-seekable streams work in both one-shot and steerable modes;
• raw, normalized, and final artifacts are not truncated;
• final text is streamed to disk rather than buffered as one in-memory response.

Provider context windows, model output limits, and limits in user/managed harness configuration still apply. To add an explicit watchdog for an ordinary review or one-shot delegate invocation, set AGENT_TIMEOUT to a positive number of seconds. Steerable runs intentionally have no wrapper deadline; observe them with status and stop them explicitly with cancel.

Backends & read-only / YOLO flags

Backend	Review (read-only)	Delegate (YOLO)
codex-cli	exec --sandbox read-only + ask-for-approval never	--dangerously-bypass-approvals-and-sandbox
claude-code	--permission-mode plan + disallowed Edit/Write	--dangerously-skip-permissions
opencode	--agent plan	--agent build --auto
grok-build	--sandbox read-only + tool allowlist/denylist (plan alone is not read-only)	--always-approve, no sandbox
gemini-cli	--approval-mode plan	not supported

Native Grok Build (default Grok path)

"grok": {
  "enabled": true,
  "backend": "grok-build",
  "model": "grok-4.5",
  "effort": "high",
  "role": "analyst",
  "label": "Grok 4.5 (native)"
}

• One-shot headless: grok --prompt-file … --output-format streaming-json (--prompt-file is the documented single-turn-from-file path; equivalent class to -p/--single for inline prompts)
• Final text = concatenation of type=text event data fields
• Success requires process exit 0, an end event, and no error event
• OpenCode xai/grok-4.5 remains as disabled fallback (opencode-xai-grok45)

Configuration

config.json at the skill root (CONSILIUM_CONFIG override). Per agent:

Field	Purpose
enabled	Default participation in review ask / basic code agent pool
backend	codex-cli | claude-code | opencode | grok-build | gemini-cli
model	Model id
role	analyst | lateral | specialist roles
effort	Backend-specific reasoning effort
label	Display name
supports_delegate	Optional; false for review-only agents

Shell escaping

Prefer --prompt-file, stdin, or a single-quoted heredoc for prompts with backticks, $, !, or quotes. Double-quoted positionals are expanded by the shell and can hang backends waiting on stdin.

A shell-interpolation warning is emitted only for positional prompts that still contain ` or $(...). Content from --prompt-file or stdin is never warned (code samples legitimately contain those characters).

scripts/consilium review ask --prompt-file prompt.md
scripts/consilium review ask "$(cat <<'EOF'
Explain `foo` and $PATH handling.
EOF
)"

When to use which

Situation	Command
Architecture / brainstorm	review ask
Quick file/diff review	review code (basic)
High-stakes PR file	review code --depth specialists or super
Max coverage	review code --depth ultra
“Just implement this” with one agent	delegate -a <id>
Delegate while retaining the ability to redirect it mid-run	delegate -a <id> --steerable

Environment variables

• CONSILIUM_CONFIG, CONSILIUM_AGENTS, CONSILIUM_EXCLUDE
• CONSILIUM_OUTPUT_DIR, CONSILIUM_RUN_DIR, CONSILIUM_SAVE_OUTPUTS
• CONSILIUM_STEER_DIR — registry root for steerable runs
• AGENT_TIMEOUT (0/unset = unlimited; positive integer = opt-in seconds for ordinary review/one-shot delegate; steerable remains unlimited)
• Per-backend: CODEX_MODEL / CODEX_EFFORT, CLAUDE_MODEL / CLAUDE_EFFORT, OPENCODE_MODEL / OPENCODE_EFFORT, GROK_MODEL / GROK_EFFORT, GEMINI_MODEL, GEMINI_API_KEY. Non-empty model/effort variables override config.json for that invocation in both ordinary and steerable modes. OpenCode effort maps to its model variant; use none to omit the variant consistently.

Tests

scripts/tests/run.sh

Uses fake backend CLIs; asserts argv safety (review sandboxes vs delegate YOLO), exact agent selection, stdout/stderr separation, artifacts, Grok streaming-json success/failure, live progress before backend exit, and steerable-delegate mailbox/adapters (Claude/Codex/OpenCode/Grok transport fakes, concurrent Grok queue + sendNow, cancel, idempotency, cleanup). Default suite is offline — no network/model spend.

Opt-in real smoke (spends tokens):

CONSILIUM_STEER_SMOKE=1 bash scripts/tests/steer/smoke_real.sh -a grok

Prerequisites

• Codex CLI — codex-cli backend
• OpenCode — opencode backend
• Claude Code — claude-code backend
• Grok Build CLI (grok) — grok-build backend
• Gemini CLI — optional, review-only
• Python 3