@maestrofrontier/frontier 1.4.4 → 1.5.0

package/docs/codex.md

@@ -1,98 +1,167 @@
-# Maestro on Codex
-
-Codex reads `AGENTS.md` natively, no adapter file needed. This page
-maps Maestro's concepts onto Codex specifics. All behavior below was
-verified against the official Codex docs
-([AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md),
-[Automations](https://developers.openai.com/codex/app/automations.md),
-[Subagents](https://developers.openai.com/codex/subagents.md))
-on 2026-06-12.
-
-## AGENTS.md semantics
-
-Codex discovers instruction files in this order:
-
-1. **Global:** `~/.codex/AGENTS.override.md` if present, else
-   `~/.codex/AGENTS.md`.
-2. **Project:** walking from the Git root down to the current working
-   directory, checking each level for `AGENTS.override.md`, then
-   `AGENTS.md`.
-
-Files are concatenated root-down with blank lines between them; files
-closer to your current directory appear later in the combined prompt
-and therefore override earlier guidance. Codex skips empty files,
-discovers once per run, and stops adding files once the combined set
-hits `project_doc_max_bytes` (32 KiB by default).
-
-Practical consequences for Maestro:
-
-- **Placement:** put Maestro's `AGENTS.md` at the repository root. If
-  you already have a project `AGENTS.md`, append Maestro's content to
-  it (Codex concatenates by directory level, not by file).
-- **Budget:** Maestro's always-on kernel is ~8 KB, a quarter of the
-  default 32 KiB cap, leaving room for your project instructions
-  (the full S2-S6 protocol lives in `docs/orchestration.md`, read on
-  demand). If you layer nested `AGENTS.md` files, watch the cap:
-  Codex silently stops adding files beyond it.
-- **Global install:** putting Maestro in `~/.codex/AGENTS.md` applies
-  the doctrine to every project; per-repo files then layer on top and
-  win where they conflict.
-
-## Multi-agent routing (S2-S6 mapping)
-
-Codex supports subagent workflows in the CLI and app, but current Codex
-docs specify that subagents spawn only when the user explicitly asks for
-them. Practical mapping for Maestro:
-
-- If the user did **not** explicitly ask for subagents, parallel
-  agents, or delegation, emit the counted S1 verdict and continue
-  single-agent even when the portable gate would otherwise route to
-  S2-S6.
-- If the user explicitly asked for subagents/parallel work and the S1
-  gate returns multi-agent, map Maestro's Planner, Specialists, and
-  Staff Engineer to Codex subagents. Keep specialist prompts scoped and
-  cap parallel groups at 4 as usual.
-- Claude Code agent teams do not transfer to Codex. Codex subagents are
-  the only Codex-native mapping for Maestro specialists.
-
-## Long-horizon operation (S10 mapping)
-
-Claude Code maps S10 to `/loop`, `/schedule`, and `ScheduleWakeup`.
-The Codex analog is **Automations** (Codex app, automations pane):
-recurring prompts that run in the background on minute-based, daily,
-weekly, or cron schedules.
-
-| Maestro S10 concept | Codex mechanism |
-|---|---|
-| Self-paced session loop | **Thread automations**, heartbeat-style recurring wake-up calls attached to the current thread, preserving conversation context |
-| Durable scheduled routine | **Standalone/project automations**, independent runs; findings land in the Triage inbox (auto-archived when there is nothing to report) |
-| Checkpoint artifact | Same convention: one `_<task>.md` in the repo root (gitignore `_*`), read first on every run, holding phase status, findings with sources, decisions with rationale |
-| Scripted/CI iteration | `codex exec "<prompt>"` non-interactive runs |
-
-S10 rules apply unchanged: hard caps on iterations, completion criteria
-declared up front, externalized state (the thread is not durable
-memory), and an explicit final report instead of a zombie loop. For
-project-scoped automations note the Codex requirement that the local
-app is running and the project is on disk.
-
-## What does not transfer
-
-Codex has no user-hook system equivalent to Claude Code's, so Maestro's
-structural enforcement pack (subagent guard, loop guard, phase-scope
-guard, gate telemetry) does not run on Codex. The prose doctrine in
-`AGENTS.md` is the enforcement surface; S7.3's verification gate relies
-on the model honoring it rather than on a hook.
-
-The Maestro context bar also does not apply: Codex CLI ships a native
-context-usage indicator (`/statusline` picker, or `context` in
-`[tui].status_line` in `~/.codex/config.toml`).
-
-## Skills and the Frontier ON indicator
-
-`maestro install --target codex` installs the `frontier`, `terse`, `settings`,
-and `update` Maestro commands as Codex skills (no-clobber) to
-`.agents/skills/<name>/SKILL.md` (per-repo) or `~/.agents/skills/<name>/SKILL.md`
-(global). When `maestro frontier status --scope codex` reports mode != off, the
-`frontier` skill instructs Codex to lead its reply with
-`Maestro Frontier ON (<label>)` — `single · <model>` or `fusion · <preset>`. When
-mode is off, no indicator line appears.
+# Maestro on Codex
+
+Codex reads `AGENTS.md` natively, no adapter file needed. This page
+maps Maestro's concepts onto Codex specifics. All behavior below was
+verified against the official Codex docs
+([AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md),
+[config reference](https://developers.openai.com/codex/config-reference#configtoml),
+[plugin-bundled hooks](https://developers.openai.com/codex/hooks#plugin-bundled-hooks),
+[Automations](https://developers.openai.com/codex/app/automations.md),
+[Subagents](https://developers.openai.com/codex/subagents.md))
+on 2026-06-12.
+
+## AGENTS.md semantics
+
+Codex discovers instruction files in this order:
+
+1. **Global:** `~/.codex/AGENTS.override.md` if present, else
+   `~/.codex/AGENTS.md`.
+2. **Project:** walking from the Git root down to the current working
+   directory, checking each level for `AGENTS.override.md`, then
+   `AGENTS.md`.
+
+Files are concatenated root-down with blank lines between them; files
+closer to your current directory appear later in the combined prompt
+and therefore override earlier guidance. Codex skips empty files,
+discovers once per run, and stops adding files once the combined set
+hits `project_doc_max_bytes` (32 KiB by default).
+
+Practical consequences for Maestro:
+
+- **Placement:** put Maestro's `AGENTS.md` at the repository root. If
+  you already have a project `AGENTS.md`, append Maestro's content to
+  it (Codex concatenates by directory level, not by file).
+- **Budget:** Maestro's always-on kernel is ~8 KB, a quarter of the
+  default 32 KiB cap, leaving room for your project instructions
+  (the full S2-S6 protocol lives in `docs/orchestration.md`, read on
+  demand). If you layer nested `AGENTS.md` files, watch the cap:
+  Codex silently stops adding files beyond it.
+- **Global install:** putting Maestro in `~/.codex/AGENTS.md` applies
+  the doctrine to every project; per-repo files then layer on top and
+  win where they conflict.
+
+## Config, hooks, and trust
+
+Codex user config lives at `~/.codex/config.toml`. Project overrides can
+live in `.codex/config.toml`, but Codex loads project-local config,
+hooks, and rules only for trusted projects. Untrusted projects skip
+those local surfaces.
+
+Codex also supports plugin-bundled lifecycle hooks. Enabled plugins can
+ship hooks alongside user, project, and managed hooks; the default plugin
+hook file is `hooks/hooks.json`, and manifests can reference `./` paths
+or inline hook definitions. Treat plugin hooks as executable code:
+review and trust the plugin before enabling them. Codex sets
+`PLUGIN_ROOT` and `PLUGIN_DATA` for plugin hooks, and also sets
+`CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` for compatibility.
+
+For Codex CLI/Desktop, install Maestro as a native Codex plugin:
+
+```text
+codex plugin marketplace add mbanderas/maestro
+codex plugin add maestro@maestro
+```
+
+The repo is a Codex marketplace because it ships
+`.agents/plugins/marketplace.json`; the plugin itself is described by
+`.codex-plugin/plugin.json`. That manifest points at the plugin-bundled Codex
+skills (`./skills/`); the hook bundle lives at Codex's default plugin hook path
+`./hooks/hooks.json`, so Codex can install the plugin without `npx`. Restart
+Codex or start a new thread after changing plugin installation/trust state,
+then review and trust the bundled hooks before expecting autorun.
+
+`maestro install --target codex` remains as a portable/manual fallback when
+you specifically want to copy files into a project instead of installing the
+Codex plugin.
+
+## Multi-agent routing (S2-S6 mapping)
+
+Codex supports subagent workflows in the CLI and app, but current Codex
+docs specify that subagents spawn only when the user explicitly asks for
+them. Practical mapping for Maestro:
+
+- If the user did **not** explicitly ask for subagents, parallel
+  agents, or delegation, emit the counted S1 verdict and continue
+  single-agent even when the portable gate would otherwise route to
+  S2-S6.
+- If the user explicitly asked for subagents/parallel work and the S1
+  gate returns multi-agent, map Maestro's Planner, Specialists, and
+  Staff Engineer to Codex subagents. Keep specialist prompts scoped and
+  cap parallel groups at 4 as usual.
+- Claude Code agent teams do not transfer to Codex. Codex subagents are
+  the only Codex-native mapping for Maestro specialists.
+
+## Long-horizon operation (S10 mapping)
+
+Claude Code maps S10 to `/loop`, `/schedule`, and `ScheduleWakeup`.
+The Codex analog is **Automations** (Codex app, automations pane):
+recurring prompts that run in the background on minute-based, daily,
+weekly, or cron schedules.
+
+| Maestro S10 concept | Codex mechanism |
+|---|---|
+| Self-paced session loop | **Thread automations**, heartbeat-style recurring wake-up calls attached to the current thread, preserving conversation context |
+| Durable scheduled routine | **Standalone/project automations**, independent runs; findings land in the Triage inbox (auto-archived when there is nothing to report) |
+| Checkpoint artifact | Same convention: one `_<task>.md` in the repo root (gitignore `_*`), read first on every run, holding phase status, findings with sources, decisions with rationale |
+| Scripted/CI iteration | `codex exec "<prompt>"` non-interactive runs |
+
+S10 rules apply unchanged: hard caps on iterations, completion criteria
+declared up front, externalized state (the thread is not durable
+memory), and an explicit final report instead of a zombie loop. For
+project-scoped automations note the Codex requirement that the local
+app is running and the project is on disk.
+
+## Frontier autorun and scope
+
+Frontier is off until you arm it. For Codex, the normal workflow is:
+
+```text
+maestro frontier mode fusion --preset chatgpt-duo --scope codex-project
+maestro frontier mode fusion --preset frontier-trio --judge chatgpt --synth chatgpt --scope codex-project
+maestro frontier mode off --scope codex-project
+```
+
+Once the Maestro Codex plugin hook is installed, enabled, and trusted,
+normal Codex prompts route through Frontier until you turn it off.
+`maestro frontier run "<prompt>" ...` remains available for advanced/debug
+one-offs, but it is not the everyday Codex flow.
+
+Project/workspace scope is the recommended default for repo installs:
+it keeps one repository's armed state from leaking into another. In a
+Codex plugin context Maestro resolves this automatically to a
+`codex-<8hex>` workspace scope. From a shell in the repo, pass
+`--scope codex-project` (or `codex-workspace`) to resolve the same project
+scope. Global/user scope is optional: choose an explicit name such as
+`--scope codex-global` only when you deliberately want the same state across
+projects.
+
+Use the same active scope for all lifecycle commands:
+
+```text
+maestro frontier status --scope codex-project
+maestro frontier mode off --scope codex-project
+maestro frontier mode fusion --preset chatgpt-duo --scope codex-project
+maestro frontier mode fusion --preset frontier-trio --judge chatgpt --synth chatgpt --scope codex-project
+```
+
+## What differs from Claude Code
+
+Claude Code-specific UI such as the Maestro context bar does not apply:
+Codex CLI ships a native
+context-usage indicator (`/statusline` picker, or `context` in
+`[tui].status_line` in `~/.codex/config.toml`).
+
+## Skills and the Frontier ON indicator
+
+Codex skills can live in personal `$HOME/.agents/skills`, repo
+`.agents/skills`, or installed plugins. The normal Codex path is the Maestro
+plugin, which bundles `maestro-frontier`, `maestro-settings`, `maestro-terse`,
+and `maestro-update` from `./skills/`. The portable
+`maestro install --target codex` fallback still installs those same skills to
+`.agents/skills/<name>/SKILL.md` for project installs or
+`~/.agents/skills/<name>/SKILL.md` for global/user installs.
+
+When `maestro frontier status --scope codex-project` reports mode != off,
+the `maestro-frontier` skill instructs Codex to lead its reply with
+`Maestro Frontier ON (<label>)` — `single · <model>` or `fusion · <preset>`. When
+mode is off, no indicator line appears.

package/docs/orchestration.md

@@ -1,168 +1,168 @@
-# Maestro Multi-Agent Orchestration: Full Protocol (S2-S6)
-
-Loaded on demand: read this file when the Decision Gate
-([AGENTS.md](../AGENTS.md) S1) returns a multi-agent verdict. The
-kernel's compact protocol is a subset of this document and suffices
-when this file is unavailable. Relocated verbatim from the always-on
-doctrine in v1.2, content here extends the kernel, never overrides
-it.
-
----
-
-## Gate constraints (S1 detail)
-
-- Max 4 specialists per group.
-- >60% shared files or <=3 files in one chain: single-agent.
-- Overlapping ownership erases parallelism; high-centrality: bias
-  single.
-- Specialists must differ in role or context, not split identical
-  work, homogeneous splits underperform one agent with the same
-  budget. Split-design rule for the Planner, not a gate downgrade.
-- Parallelizability first: specialization pays only when subtasks are
-  structurally independent. Coupled subtasks: single-agent wins at
-  equal token budget, gains that ignore total compute don't count.
-- Adversarial review is the best-evidenced multi-agent win. Review
-  and debate panels: 3 specialists (odd, no ties); 4 stays the cap
-  for parallel workstreams.
-- How to split (and whether a split is too homogeneous) is the
-  Planner's call (S2), made after the spawn, never the gate's.
-
----
-
-## 2. Planner [MULTI-AGENT]
-
-First sub-agent, created by calling the Task/Agent tool, never
-simulated inline by the orchestrator. No specialist work before
-Planner returns.
-
-Produces: subtasks with boundaries, dependency map, parallel groups
-(max 4), per-task file scope + objective + acceptance criteria, flags
-for single-agent subtasks and high-risk items, cross-talk pairs,
-token-cost assessment (flag >60% overlap), task-class match.
-
-Fewer broader > many narrow. Flag ambiguity, don't assume.
-
-Reading: recommends single-agent -> switch. Ambiguities -> surface.
-
-Task classes: Feature (spec/implement/test/integrate),
-Bug (reproduce/root-cause/fix/regress),
-Refactor (scope/refactor/test/verify),
-Audit (discover/analyze/consolidate), Docs+code (change/update/check).
-
----
-
-## 3. Specialists [MULTI-AGENT]
-
-Manifest fields: ROLE, TASK, FILES (read/modify), UPSTREAM,
-ORIENTATION, ASSUMPTIONS, OUTPUT, ACCEPT, TOOLS (scoped), RULES (S7
-injected). ROLE = procedural workflow (step sequence + acceptance
-criteria), never a bare job title, identity labels alone don't
-change behavior.
-
-No conversation history, other tasks, full plan, or unrelated
-context. Isolation is the advantage. Out of scope: report and stop.
-
----
-
-## 4. Cross-Talk [MULTI-AGENT]
-
-After each group: check if A modified B's files, changed B's
-interfaces, invalidated B's assumptions, or produced B's inputs.
-
-Route minimum context from A to B. If B completed, spawn correction
-agent. Orchestrator: spawn, sequence, detect, route, deliver. Never
-plan, code, review, or do specialist work.
-
----
-
-## 5. Staff Engineer [MULTI-AGENT]
-
-Final sub-agent. Reviews integrated output.
-
-Packet: changed files + diffs, objective, decisions, risks,
-questions. Expand for: core architecture, security, central
-abstractions.
-
-Check: requirements met, specialist contradictions, cross-breakage
-(interfaces/imports/types/state), architectural drift, verification
-(S7.3), dead code/orphaned imports/incomplete renames,
-surgical-scope violations (S7.4).
-
-Returns PASS or FAIL (issues + owner + fix). Max 2 cycles, then
-deliver with issues listed.
-
-High-risk or contested verdicts: adversarial panel of 3 (odd, no
-ties), each prompted to refute, not confirm.
-
----
-
-## 6. Orchestrator Discipline [MULTI-AGENT]
-
-- Route minimum viable info (signature, not 200-line diff)
-- Checkpoint before spawns/handoffs/resumes: objective, files,
-  requirements, decisions, risks, next action
-- Structured artifacts > transcript carryover
-- Stable scaffolds for cache reuse; no per-specialist rephrasing
-- Track agent status; report blocks immediately
-- Resume from latest artifact, not full history
-- Specialist fails: report, ask user. No silent retry >1
-- Deliver what asked. No gold-plating. Hooks > prompt reminders
-
----
-
-## 9. Model Routing: full table
-
-Pick the cheapest model that handles the task. Orchestrator decides
-at spawn time; Planner (S2) assigns per subtask.
-
-| Tier | When | Examples |
-|------|------|----------|
-| Haiku | No edits, single source, low reasoning | Status lookup, chat, format, classify, extract |
-| **Sonnet** | 1-3 file edits, known scope. **Default** | Bug fix, refactor, test, review, docs |
-| Opus | 4+ files, novel design, high reversal cost | Architecture, security review, complex debug |
-| Frontier (Fable-class) | Orchestrator tier: long-horizon autonomous work, 1M-context audits, frontier reasoning | Orchestration, system design, deep multi-file debug, adversarial synthesis |
-
-When unsure: Sonnet.
-
-### Output caps
-
-Agent prompts MUST specify max response length. Oversized results
-bloat parent context and trigger compaction.
-
-| Agent tier | Cap | Exception |
-|------------|-----|-----------|
-| Haiku | 100 words | - |
-| Sonnet | 500 words | Code output (uncapped) |
-| Opus | Uncapped | - |
-| Frontier | Uncapped | - |
-| Explore | 200 words | Always, regardless of model |
-
-Explore agents: "report in under 200 words" in every prompt.
-
-### Tool-call budgets
-
-Action tokens are the third cost lever, beside output caps (above)
-and S8 input compression. Every subagent prompt carries a tool-call
-budget (manifest field `toolBudget`); idea adapted from
-claude-token-efficient (MIT).
-
-| Task type | Budget |
-|-----------|--------|
-| Routine subtask, known scope | ~20 calls |
-| Read-only research / Explore | ~10 calls |
-| Multi-file implementation | scale with file count; state it explicitly |
-
-Discipline inside the budget: read-first-write-once (read each
-needed file once, then edit, no re-read loops); one diagnostic read
-per failure, then the S7.3 two-attempt rule applies (stop, re-read
-from scratch, change approach). Budget exhausted: report progress
-and the named gap, never burn calls polling.
-Research agents returning raw dumps waste more tokens than they save.
-
----
-
-## Self-evaluation (relocated S7.6)
-
-- Two perspectives: perfectionist critique + pragmatist accept
-- Bug autopsy: root cause vs symptom, prevention
-- After 2 failures: stop, re-read from scratch, different approach
+# Maestro Multi-Agent Orchestration: Full Protocol (S2-S6)
+
+Loaded on demand: read this file when the Decision Gate
+([AGENTS.md](../AGENTS.md) S1) returns a multi-agent verdict. The
+kernel's compact protocol is a subset of this document and suffices
+when this file is unavailable. Relocated verbatim from the always-on
+doctrine in v1.2, content here extends the kernel, never overrides
+it.
+
+---
+
+## Gate constraints (S1 detail)
+
+- Max 4 specialists per group.
+- >60% shared files or <=3 files in one chain: single-agent.
+- Overlapping ownership erases parallelism; high-centrality: bias
+  single.
+- Specialists must differ in role or context, not split identical
+  work, homogeneous splits underperform one agent with the same
+  budget. Split-design rule for the Planner, not a gate downgrade.
+- Parallelizability first: specialization pays only when subtasks are
+  structurally independent. Coupled subtasks: single-agent wins at
+  equal token budget, gains that ignore total compute don't count.
+- Adversarial review is the best-evidenced multi-agent win. Review
+  and debate panels: 3 specialists (odd, no ties); 4 stays the cap
+  for parallel workstreams.
+- How to split (and whether a split is too homogeneous) is the
+  Planner's call (S2), made after the spawn, never the gate's.
+
+---
+
+## 2. Planner [MULTI-AGENT]
+
+First sub-agent, created by calling the Task/Agent tool, never
+simulated inline by the orchestrator. No specialist work before
+Planner returns.
+
+Produces: subtasks with boundaries, dependency map, parallel groups
+(max 4), per-task file scope + objective + acceptance criteria, flags
+for single-agent subtasks and high-risk items, cross-talk pairs,
+token-cost assessment (flag >60% overlap), task-class match.
+
+Fewer broader > many narrow. Flag ambiguity, don't assume.
+
+Reading: recommends single-agent -> switch. Ambiguities -> surface.
+
+Task classes: Feature (spec/implement/test/integrate),
+Bug (reproduce/root-cause/fix/regress),
+Refactor (scope/refactor/test/verify),
+Audit (discover/analyze/consolidate), Docs+code (change/update/check).
+
+---
+
+## 3. Specialists [MULTI-AGENT]
+
+Manifest fields: ROLE, TASK, FILES (read/modify), UPSTREAM,
+ORIENTATION, ASSUMPTIONS, OUTPUT, ACCEPT, TOOLS (scoped), RULES (S7
+injected). ROLE = procedural workflow (step sequence + acceptance
+criteria), never a bare job title, identity labels alone don't
+change behavior.
+
+No conversation history, other tasks, full plan, or unrelated
+context. Isolation is the advantage. Out of scope: report and stop.
+
+---
+
+## 4. Cross-Talk [MULTI-AGENT]
+
+After each group: check if A modified B's files, changed B's
+interfaces, invalidated B's assumptions, or produced B's inputs.
+
+Route minimum context from A to B. If B completed, spawn correction
+agent. Orchestrator: spawn, sequence, detect, route, deliver. Never
+plan, code, review, or do specialist work.
+
+---
+
+## 5. Staff Engineer [MULTI-AGENT]
+
+Final sub-agent. Reviews integrated output.
+
+Packet: changed files + diffs, objective, decisions, risks,
+questions. Expand for: core architecture, security, central
+abstractions.
+
+Check: requirements met, specialist contradictions, cross-breakage
+(interfaces/imports/types/state), architectural drift, verification
+(S7.3), dead code/orphaned imports/incomplete renames,
+surgical-scope violations (S7.4).
+
+Returns PASS or FAIL (issues + owner + fix). Max 2 cycles, then
+deliver with issues listed.
+
+High-risk or contested verdicts: adversarial panel of 3 (odd, no
+ties), each prompted to refute, not confirm.
+
+---
+
+## 6. Orchestrator Discipline [MULTI-AGENT]
+
+- Route minimum viable info (signature, not 200-line diff)
+- Checkpoint before spawns/handoffs/resumes: objective, files,
+  requirements, decisions, risks, next action
+- Structured artifacts > transcript carryover
+- Stable scaffolds for cache reuse; no per-specialist rephrasing
+- Track agent status; report blocks immediately
+- Resume from latest artifact, not full history
+- Specialist fails: report, ask user. No silent retry >1
+- Deliver what asked. No gold-plating. Hooks > prompt reminders
+
+---
+
+## 9. Model Routing: full table
+
+Pick the cheapest model that handles the task. Orchestrator decides
+at spawn time; Planner (S2) assigns per subtask.
+
+| Tier | When | Examples |
+|------|------|----------|
+| Haiku | No edits, single source, low reasoning | Status lookup, chat, format, classify, extract |
+| **Sonnet** | 1-3 file edits, known scope. **Default** | Bug fix, refactor, test, review, docs |
+| Opus | 4+ files, novel design, high reversal cost | Architecture, security review, complex debug |
+| Frontier (Fable-class) | Orchestrator tier: long-horizon autonomous work, 1M-context audits, frontier reasoning | Orchestration, system design, deep multi-file debug, adversarial synthesis |
+
+When unsure: Sonnet.
+
+### Output caps
+
+Agent prompts MUST specify max response length. Oversized results
+bloat parent context and trigger compaction.
+
+| Agent tier | Cap | Exception |
+|------------|-----|-----------|
+| Haiku | 100 words | - |
+| Sonnet | 500 words | Code output (uncapped) |
+| Opus | Uncapped | - |
+| Frontier | Uncapped | - |
+| Explore | 200 words | Always, regardless of model |
+
+Explore agents: "report in under 200 words" in every prompt.
+
+### Tool-call budgets
+
+Action tokens are the third cost lever, beside output caps (above)
+and S8 input compression. Every subagent prompt carries a tool-call
+budget (manifest field `toolBudget`); idea adapted from
+claude-token-efficient (MIT).
+
+| Task type | Budget |
+|-----------|--------|
+| Routine subtask, known scope | ~20 calls |
+| Read-only research / Explore | ~10 calls |
+| Multi-file implementation | scale with file count; state it explicitly |
+
+Discipline inside the budget: read-first-write-once (read each
+needed file once, then edit, no re-read loops); one diagnostic read
+per failure, then the S7.3 two-attempt rule applies (stop, re-read
+from scratch, change approach). Budget exhausted: report progress
+and the named gap, never burn calls polling.
+Research agents returning raw dumps waste more tokens than they save.
+
+---
+
+## Self-evaluation (relocated S7.6)
+
+- Two perspectives: perfectionist critique + pragmatist accept
+- Bug autopsy: root cause vs symptom, prevention
+- After 2 failures: stop, re-read from scratch, different approach