Controlled Codex subagent governance

This repository uses subagents as visible, bounded workers. The primary Sol agent remains accountable for requirements, architecture, decisions, integration, verification, commits, pushes, deployments, and user communication.

Official references:

Available project agents

Agent	Model	Access	Intended work
`spark_explorer`	`gpt-5.3-codex-spark`	read-only filesystem; external reads by policy	Code-path discovery, Ops reads, contract inventories, test/log triage
`spark_worker`	`gpt-5.3-codex-spark`	workspace write	Small edits within an explicit path allowlist and targeted verification

Unpinned supporting work defaults to gpt-5.6-terra with low reasoning. The primary agent must keep demanding or ambiguous work on Sol.

Hard operating limits

At most two subagent threads may run concurrently.
At most one write-capable subagent may run at a time.
Subagents may not create more subagents.
Only the primary agent may commit, push, deploy, mutate Ops or another external system, install dependencies, or approve an expanded scope.
Parallel writers must never touch overlapping files. The default is one writer.
A worker gets one implementation pass and at most one corrective retry.
Scope drift, an architectural decision, a required unlisted file, or a second failed verification ends the worker turn and escalates to the primary agent.

Mandatory task packet

Every delegation must state:

Objective: one concrete outcome.
Allowed scope: exact files, directories, or read-only tools.
Forbidden actions: especially external writes, commits, pushes, and deploys.
Acceptance criteria: observable evidence of completion.
Verification: exact checks the worker may run.
Output: a short structured summary, not raw logs.

Full conversation history should not be copied into a worker unless the task genuinely requires it. Prefer a compact, self-contained packet.

User-visible lifecycle

The primary agent announces every delegation before it starts using this ledger:

Agent	Model	Mode	Task	Allowed scope	State
agent name	pinned model	read or write	bounded objective	paths/tools	planned/running/waiting/completed/interrupted

The primary agent then:

Lists active agents when their state changes or the user asks for status.
Reports completion, interruption, or escalation with the worker's evidence.
Identifies all files changed by workers before integration.
Reviews the diff and performs final verification itself.
Includes a final agent ledger in the user handoff.

The desktop app exposes each subagent thread for inspection. The user can ask the primary agent to stop one agent or all agents at any time. The primary agent must interrupt the requested threads immediately unless an atomic tool call is already finishing.

Token and usage visibility

Current documented controls are deliberately separated:

The subagent panel/thread view shows agent count, activity, status, and results.
/status shows the current chat's context usage and rate limits.
Workspace/Codex analytics provide workspace-level aggregated reporting when the account and role expose those dashboards or APIs.

The official Codex documentation does not currently promise an exact real-time per-subagent token total in the desktop orchestration panel. Therefore:

Never invent or estimate a token count and present it as measured.
Record the model, agent turns, start/end state, scope, verification, and outcome.
If the product exposes measured per-thread usage, report that value verbatim.
Treat fewer agents and smaller task packets as the primary token-control tools.
Use /status inside the relevant agent thread when thread-local context usage is needed and available.

Escalation policy

Clear read-heavy work: spark_explorer.
Clear small implementation: spark_worker.
Multi-file reasoning, review, or repeated Spark failure: Terra.
Architecture, geospatial math, migrations, security, cross-system contracts, final acceptance, and all consequential decisions: primary Sol agent.

Subagents are an optimization mechanism, never a substitute for ownership.

4.5 KiB Raw Blame History