Multi-Agent Governor

Treat parallelism as an execution budget, not an agent-count target. Optimize for elapsed time and correctness while preventing duplicated work, stale reviews, full-history forks, and unbounded QA loops.

Hard Limits

• Use at most 3 first-wave agents.
• Use at most 2 final QA agents.
• Use at most 5 agents total and 4 concurrently.
• Use 1 QA wave by default; allow a second only for a verified blocking defect.
• Do not let subagents spawn descendants.
• Keep one integration owner: the main agent.
• Disable full-history inheritance; use fork_context: false when the platform supports it.
• Keep each context capsule at or below 6 KB.
• Close completed agents immediately.

User phrases such as "多多多派 Agent" or "不用省 token" raise urgency and evidence coverage. They do not override these limits.

Choose the Execution Primitive

Before spawning, classify every work item:

Work item	Execute with
Independent expert judgment or bounded writing	Agent
File reads, searches, API calls, shell commands	Approved parallel/batch tool calls
Counting, hashing, schema checks, formulas, overflow, string scans	Deterministic script
Critical path, conflict resolution, final edits	Main agent

Do not use agents merely to parallelize I/O. If fewer than 2 independent reasoning lanes exist, keep the task local or use only 1 sidecar agent even when the user asks for many.

Read references/orchestration-policy.md when decomposition or model routing is non-obvious.

Run Protocol

1. Define the run

Identify:

• concrete objective and newest user instruction;
• immutable source files and their hashes;
• critical path owned by the main agent;
• independent lanes with disjoint ownership;
• deterministic acceptance tests;
• user deadline and quality posture.

Create a manifest:

python3 scripts/init_run.py \
  --objective "<objective>" \
  --source /absolute/path/to/input \
  --mode fast-deep \
  --deadline-minutes 90

Use --main-thread-id when the current platform exposes a stable thread id. Store temporary run state under /tmp/multi-agent-runs/; do not place it beside user deliverables.

2. Build minimal capsules

Create one capsule per independent lane:

python3 scripts/add_capsule.py \
  --manifest /tmp/multi-agent-runs/<run-id>/run-manifest.json \
  --lane-id evidence-qa \
  --role explorer \
  --objective "Verify financing and source claims" \
  --input /absolute/path/to/workbook.xlsx \
  --deliverable "Structured findings only" \
  --acceptance "Every finding includes file/sheet/range evidence" \
  --exclusion "Do not edit source files"

Pass the capsule path and necessary file paths to the agent. Do not paste the long conversation, entire file contents, intended conclusion, or another agent's diagnosis. See references/agent-contracts.md.

3. Execute wave one

• Spawn only the lanes that can proceed independently.
• Keep urgent blocking work local instead of delegating it and waiting.
• Assign disjoint file or responsibility ownership.
• Continue meaningful main-agent work immediately after spawning.
• Reuse an existing agent only when the new task depends on its prior local context.
• Register agent ids with scripts/update_run.py agent-start.

When a command returns a session id, register it and poll that exact session until exit_code is present. Never rerun a command merely because the first call returned no output.

4. Integrate once

The main agent reviews findings, resolves conflicts, and writes the integrated artifact once. Agents must not concurrently edit the same deliverable.

Register the integrated build and hashes:

python3 scripts/update_run.py build \
  --manifest /tmp/multi-agent-runs/<run-id>/run-manifest.json \
  --artifact /absolute/path/to/output

5. Run deterministic gates first

Run format, schema, test, count, hash, formula, overflow, link, and prohibited-language checks before asking agents to review. Domain skills supply their own gates.

Then verify build freshness:

python3 scripts/check_freshness.py \
  --manifest /tmp/multi-agent-runs/<run-id>/run-manifest.json \
  --include-sources

6. Run one QA wave

Use no more than 2 non-overlapping QA lenses, such as:

• factual/data consistency;
• visual/narrative/user-perspective quality.

Every QA capsule must include the current build_id and artifact hashes. Do not edit artifacts while QA is running. Discard a result if freshness fails. Fix verified blockers in one batch. Do not spawn another broad review wave for cosmetic suggestions.

Read references/quality-gates.md for severity and stop rules.

7. Close and report

• Close every agent as soon as its result is integrated.
• Confirm every registered command session has an exit code.
• Mark the run complete only after acceptance tests pass.
• Collect elapsed time and usage from the platform's native telemetry when available. When running inside Codex, the bundled adapter can read local thread metrics:

python3 scripts/collect_usage.py \
  --manifest /tmp/multi-agent-runs/<run-id>/run-manifest.json \
  --write

• Report gross tokens, cached input, fresh non-cached input plus output, agent count, and wall time when the platform exposes them. Never fabricate unavailable metrics.

Stop Conditions

Stop when all deterministic acceptance tests pass and no blocking QA finding remains. Do not continue because another reviewer might produce a different preference.

Escalate to the user before exceeding 5 agents, starting a second QA wave, changing frozen source files, or resolving a genuine product/business judgment that cannot be inferred safely.

Failure Prevention

• Do not accept reviews without matching build hashes.
• Do not mix findings produced against different artifact versions.
• Do not ask multiple agents the same broad question.
• Do not use a high-reasoning model for mechanical verification.
• Do not mark a run complete while agents or command sessions remain active.
• Do not treat cached-token volume as fresh-token consumption; report both.