98 lines
4.5 KiB
Markdown
98 lines
4.5 KiB
Markdown
# 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:
|
|
|
|
- [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
|
|
- [Codex slash commands](https://learn.chatgpt.com/docs/reference/slash-commands)
|
|
- [Codex workspace analytics](https://learn.chatgpt.com/docs/enterprise/workspace-analytics)
|
|
|
|
## 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:
|
|
|
|
1. Objective: one concrete outcome.
|
|
2. Allowed scope: exact files, directories, or read-only tools.
|
|
3. Forbidden actions: especially external writes, commits, pushes, and deploys.
|
|
4. Acceptance criteria: observable evidence of completion.
|
|
5. Verification: exact checks the worker may run.
|
|
6. 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:
|
|
|
|
1. Lists active agents when their state changes or the user asks for status.
|
|
2. Reports completion, interruption, or escalation with the worker's evidence.
|
|
3. Identifies all files changed by workers before integration.
|
|
4. Reviews the diff and performs final verification itself.
|
|
5. 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.
|