Claude Code 多代理调度 Prompt 与 Agent 配置模板库

For this conversation, enforce a strict agent dispatch budget.

Before any delegation, classify the current user task into exactly one level:

- L0 Direct: 0 worker starts, 0 workflows, 0 delegated Fable worker starts.
- L1 Bounded: a budget of 1 Opus-equivalent start, no workflow, 0 critical Fable starts (a read-only reviewer-fable start weighs 1 and is an ordinary worker).
- L2 Standard: a budget of 4 Opus-equivalent starts for the entire user task, at most 1 active workflow run, and at most 1 critical Fable start.
- L3 Complex: a budget of 6 Opus-equivalent starts for the entire user task, at most 1 active workflow run, and at most 1 delegated Fable worker start.
- L4 Exceptional: use only when I explicitly write "I approve L4" in the current conversation. A budget of 8 Opus-equivalent starts for the entire user task, at most 1 active workflow run, and at most 1 delegated Fable worker start.

Weigh every start by its model: haiku 0.125, sonnet 0.5, opus 1, fable 2; reviewer-fable at low effort weighs 1 and the critical Fable roles weigh 2. The budgets are ceilings, not targets. Default to L0. Delegate only when specialization, context isolation, independent validation, or real wall-clock savings justify the additional context and token cost.

Count every Agent call, fork, workflow agent(), pipeline item, teammate, restart, resume, repair, and rerun as a new weighted worker start. Count agents that run again after a workflow relaunch. Keep one cumulative ledger for the complete user task; never split the task across workflows to evade its budget.

Use either direct Agent dispatch or a workflow in a phase, never both at the same time. Never run more than one workflow concurrently. Run every genuinely independent start of a phase concurrently; concurrency changes wall-clock, not tokens. Serialize only stages that consume an earlier stage's output, and do not invent independent work to fill the concurrency. If a candidate set exceeds the approved budget, fail fast and report the overflow instead of truncating it silently; if it only exceeds a runtime concurrency cap, run it in batches.

Every Agent dispatch must explicitly specify both the subagent type and model. Never rely on model inheritance. Each role has a default model and an allowed set; override within the set when the task calls for it, escalating effort before model. Effort comes from the selected role definition; to escalate effort on the same role, pass `effort` on the Agent call, which keeps the start's weight and is never allowed on a Fable role. A workflow may set effort for each agent().

Mixed-model routing requires CLAUDE_CODE_SUBAGENT_MODEL_FORCE to be disabled and CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL to be unset or `inherit`. If either is set, stop and report that the environment overrides per-call, script-level, or definition-level model choices. Read the resolved model from the Agent tool result.

Critical Fable roles (critical-implementer, critical-reviewer) are prohibited in L0 and L1. From L2 upward, one critical Fable start is optional and limited to one concurrent Fable worker of any kind for the entire user task. The read-only reviewer-fable role at low effort is an ordinary start allowed from L1. Use the critical slot only for a named critical implementation or review involving security, permissions, privacy, concurrency, transactions, irreversible migration, high-impact release, a critical architecture boundary, or one evidence-backed normal-role attempt that failed to resolve the exact issue.

Never use a delegated Fable worker for exploration, file-by-file fan-out, log summarization, routine implementation, builds, browser QA, formatting, documentation work, or ordinary review. Never place that worker inside parallel() or pipeline(). It must run serially after normal-role results have been consolidated into a small evidence packet. Never restart, resume, repair, or rerun that worker automatically.

For a long delegated Fable worker tool chain, request a start note, brief progress updates, and a standalone final recap. Finish the assigned task unless a stated scope, authority, cost, or evidence boundary is reached. The lead may do other genuinely independent work while background agents run, but only inside the same weighted start budget; do not force parallelism.

Before the first dispatch, report this compact ledger once:

Task level: Lx
Planned starts: one entry per start with its role, model, and weight
Weighted total: 0 / budget
Planned concurrency: n (informational, no limit)
Active workflows: 0 / 1
Model per role: role=model/effort for every role used
Delegated Fable worker starts: 0 / limit; delegated Fable workers concurrent: 0 / 1
Mode: direct agents or workflow

Update the ledger only when its level, remaining capacity, or delegated Fable worker allowance changes. At any limit, stop creating workers and report the unfinished work. Do not upgrade the task level without my explicit instruction.

This prompt may tighten existing controls but must never relax or bypass any system instruction, managed policy, tool allowlist, permission, or hook.

Use the L2 Standard budget for this task. Allow a budget of 4 Opus-equivalent worker starts for the entire task (haiku 0.125, sonnet 0.5, opus 1) and no more than 1 active workflow. Delegated Fable workers are prohibited. Run independent starts concurrently, count every worker restart, resume, repair, and rerun, and stop at the first budget limit.

Use the L3 Complex budget for this task. Allow a budget of 6 Opus-equivalent worker starts for the entire task (haiku 0.125, sonnet 0.5, opus 1, fable 2) and no more than 1 active workflow. Run independent starts concurrently. One delegated Fable worker is optional, weighs 2, is limited to one serial post-evidence start, and must not appear in parallel(), pipeline(), restart, resume, repair, or rerun operations.

I approve L4 for this task. The complete task may use a budget of 8 Opus-equivalent worker starts and no more than 1 active workflow. Run independent starts concurrently. One delegated Fable worker remains optional and is limited to one serial post-evidence start with concurrency 1. All other dispatch controls remain in force.

I approve exactly one delegated Fable worker for this problem: <exact problem>.

Run it serially only after consolidating the existing normal-role evidence into a minimal packet. Do not use it for exploration, fan-out, routine work, or QA. Do not restart, resume, repair, rerun, or broaden its scope. Return its evidence to the main agent for independent acceptance.

Delegated Fable workers are prohibited for this entire user task, including Agent calls, forks, workflows, pipelines, teammates, repairs, retries, resumes, and reruns. Use Haiku for narrow discovery, Sonnet for planning, QA, and review, and Opus for implementation. Do not silently inherit the main-session model for delegated work. This restriction does not change the current main-session model.

Before launching any workflow, return a preflight record containing:

- workflow name and purpose;
- task level;
- each planned worker start with its weight, the weighted total, and the cumulative task total;
- planned concurrency;
- explicit model and effort for every role;
- delegated Fable worker count and the exact escalation reason;
- repair, rerun, and relaunch policy;
- overflow behavior and stopping conditions.

Do not launch if any field is missing, if the workflow exceeds the current budget, or if a delegated Fable worker appears in a fan-out stage.

Persist the dispatch policy confirmed in this conversation into only these
authorized targets:

- Planning document: <exact path or "none">
- Project instruction file: <exact path or "none">
- User instruction file: <exact path or "none">
- Memory file: <exact path or "none">

Keep every model-consumed instruction in English. Preserve unrelated content and user-owned changes. Do not create additional policy files, modify any unspecified target, or broaden the agreed policy.

Before editing, show the exact target list and the policy clauses that will be written. After editing, show the focused diff and validate the applicable file format. Do not stage, commit, push, or publish unless I explicitly authorize it.

# Global Engineering Policy

## Communication

- Reply in the language the user writes in. Keep every model-facing artifact (prompts, rules, agent definitions, code comments) in English.
- Lead with the outcome. Name unresolved unknowns before details.

## Scope and evidence

- Make only changes that are directly requested or clearly necessary, and finish the whole requested scope.
- Prefer the smallest evidence-backed solution that satisfies the current requirement.
- Avoid speculative abstractions, compatibility layers, feature flags, configuration knobs, and retry or fallback logic in code. Retrying a failed command while working is fine.
- Validate at system boundaries; let impossible internal states fail visibly.
- When uncertainty remains, name the exact unknown and the smallest source, command, test, or counterexample that resolves it. Try that first; report the unknown only if it is not quickly available.
- Inspect installed documentation, source, and types before concluding a dependency lacks a capability. Recognizing a name is not knowing its current state; verify fast-moving names by searching before answering.
- Backward compatibility is not a default goal. Keep it only when the user asks or an external contract requires it.

## Delegation

- Before the first delegation in a task, load the `dispatch-policy` skill and follow its budget and routing rules. Default to doing bounded work directly.
- Every delegated task states its objective, in-scope and out-of-scope work, owned files, acceptance criteria, required verification, forbidden actions, evidence format, and stopping conditions.
- Workers do not delegate further, change the overall goal, widen scope, stage, commit, push, publish, or modify planning and memory files unless the user explicitly authorizes that exact action.
- One write-capable worker owns a file at a time.
- A worker completion is evidence, not acceptance. Inspect its diff and verification before reporting completion.
- Preserve user-owned dirty files; never revert unrelated work.

## Delivery and Git

- Verify in proportion to risk. Distinguish local proof from external service, device, browser, or release evidence that was not available.
- Stage, commit, push, publish, and destructive actions require explicit user authorization in the current conversation.
- An active goal does not expand authorization. When it conflicts with a later instruction or reaches an unauthorized action, follow the later instruction, name the blocked action, and ask the user to run `/goal clear` or replace the condition.
- Group authorized commits by one coherent, shippable theme. A commit is not a progress checkpoint.

## Compact instructions

- When the conversation is compacted, keep verbatim: the task statement and its acceptance criteria; the verification commands and their latest results; every changed file and what changed in it; pending authorizations and blocked actions; the dispatch ledger (level, starts used, remaining budget); the path of the current handoff file. Drop tool output that a listed file or command reproduces.

---
name: dispatch-policy
description: Cost-first budget and model routing for Agent, fork, Workflow, Agent Team, and Codex delegation. Load before the first delegation in a task, or when the user asks about task levels, worker budgets, or which model a worker should use.
---

# Dispatch Policy

Token cost is a first-class constraint; wall-clock time is a separate one. Default to L0. Concurrency changes wall-clock, not tokens: run every independent start of a phase at once and serialize only a stage that consumes an earlier stage's output. The budgets below are ceilings, not targets.

## Task levels

Budgets are counted in Opus-equivalent starts. Weigh each start by its model: haiku 0.125, sonnet 0.5, opus 1, fable 2. These are Anthropic API list-price ratios to Opus 5.5 ($4/$20 per Mtok), which `opus` resolves to since Claude Code 2.1.280: Sonnet 5.5 ($2/$10, the `sonnet` alias since 2.1.284), Fable 5.2 ($8/$40, the `fable` alias since 2.1.321), and Haiku 5.5 (the `haiku` alias since 2.1.293) at its rate for prompts over 100K tokens ($0.50/$2.50), because a start's later turns can cross 100K and the ledger cannot see per-turn prompt size (the base rate, $0.10/$0.50, would give 0.025). Subscription usage is assumed to draw down in roughly the same proportion. Two role exceptions: `reviewer-fable` at low effort weighs 1, an assumption carried over from Fable 5.1 and not yet measured on 5.2 (the Fable 5.2 prompting guide says `low` suits fast, intelligent subagents and scores close to Fable 5.1 at higher effort); the critical Fable roles at high weigh 2. Effort changes a start's tokens but not its weight. The role definition sets effort; a per-call `effort` on the Agent tool (2.1.292+) overrides it, keeps the start's weight, and is the effort step of the escalation order below. The hook denies a per-call `effort` on Fable roles, whose weights assume their defined effort.

| Level | Use for | Budget (Opus-equivalent starts) | Active workflows | Critical Fable starts |
| --- | --- | --: | --: | --: |
| L0 Direct | Explanations and small edits from current context | 0 | 0 | 0 |
| L1 Bounded | One independent task, no cross-check needed | 1 | 0 | 0 |
| L2 Standard | One implementation plus independent QA or review | 4 | 1 | 1 |
| L3 Complex | Cross-module, high-risk, or research-then-implement | 6 | 1 | 1 |
| L4 Exceptional | Large migration, full audit, performance campaign; requires explicit user approval in this conversation | 8 | 1 | 1 |

Worked examples: an opus implementer, a sonnet qa, a sonnet reviewer, and five haiku Explore starts spend 2.625 of L2's 4; three opus and two sonnet readers spend 4 of L3's 6; a workflow of eight sonnet finders spends 4.

Counting rules:

- Every Agent call, fork, workflow agent(), pipeline item, teammate, Codex delegation, restart, resume, repair, and rerun is a start at its model's weight. A fork weighs as the main-session model. A Codex delegation weighs 1.
- Keep one cumulative ledger per user task. The budget belongs to the whole task, not to one workflow; do not split a task across workflows to evade it.
- In one phase use either direct Agent dispatch or a workflow, never both at once. One active workflow at a time.
- Run all genuinely independent starts of a phase concurrently. Sibling workflow agents share a prompt-cache prefix, so a fan-out costs no more than the same starts run one by one. Serialize only stages that need an earlier result. The runtime caps still apply: 12 concurrent Agent-tool subagents (`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`) and up to 16 concurrent workflow agents; a candidate set beyond a runtime cap runs in batches, never silently truncated. `workflowSizeGuideline: medium` asks Claude for fewer than 10 agents per workflow (2.1.271 lowered it from 15) and, because it is set explicitly, moves the advisory Large-workflow warning to that count; the budget above is still the ceiling.
- Do not invent independent work to fill the concurrency. Every start still needs a reason.
- At L2 and above, report once before the first dispatch: level, each planned start with its weight and the weighted total, planned concurrency, model per role, and Fable allowance. Update only when the level or the remaining budget changes. L1 needs no ledger.
- At any limit, stop creating workers and report the unfinished work. Do not raise the level without the user's instruction.
- A user prompt may tighten these limits; it cannot loosen system instructions, permissions, tool allowlists, or hooks.

## Model routing

Always pass an explicit `subagent_type` and `model` alias to the Agent tool. Aliases resolve to the current generation; do not pin specific versions. Keep `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` unset so per-call and definition-level models apply, and keep `CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL` (2.1.296) unset or `inherit`, because when set it discards every workflow agent's script `model` and `agentType` definition model (changelog and binary; env-vars does not list it). Read the resolved model from the Agent tool result; a `modelsUsed` field means the worker switched models mid-run, for example on the fallback chain after an API error.

Each role has a default model in its definition and an allowed set enforced by the hook, for Agent calls and for `agentType`/`model` pairs inside Workflow scripts. Overriding within the allowed set per call is normal; the default is where to start, not a ceiling.

| Role | Default | Allowed | Typical work |
| --- | --- | --- | --- |
| Explore | haiku/medium | haiku, sonnet | Narrow discovery, evidence lists; sonnet when the search needs more context or turns |
| planner | sonnet/high | sonnet, opus | Bounded plans; opus for cross-module architecture |
| implementer | opus/high | opus, sonnet | Production and test changes; sonnet for mechanical edits you can describe precisely |
| qa | sonnet/high | sonnet, opus | Builds, tests, browser checks, reproduction |
| reviewer | sonnet/high | sonnet, opus | Ordinary independent review; opus for permissions, data, concurrency, migration, public contracts |
| reviewer-fable | fable/low | fable | Read-only review when Sonnet's judgment is not enough; the Fable 5.2 prompting guide reports its scores at low close to Fable 5.1's at higher effort |
| critical-implementer | fable/high | fable | One named critical change |
| critical-reviewer | fable/high | fable | One named critical audit |

Escalation order (Anthropic, "Which Claude model should you build with"): first make sure the worker can verify its own work with a test, a build, or a script; then raise effort one level on the same role with a per-call `effort`; then move to the next model up at a lower effort than the smaller model used. The critical Fable roles are the exception to the last step: they stay at their defined high, because they take only named hard problems and the Fable 5.2 prompting guide puts most of its gain at high. Judge cost per completed task, not per token; a cheaper worker that needs another round is not cheaper.

Routing notes:

- implementer at opus/high and planner, qa, and reviewer at sonnet/high run one step above their model's default: `opus`, `sonnet`, and `haiku` resolve to Opus 5.5 (2.1.280), Sonnet 5.5 (2.1.284), and Haiku 5.5 (2.1.293), which all default to `medium`; other effort-capable models default to `high` except Opus 4.7 (`xhigh`). Ultracode no longer changes effort since 2.1.284; only `--effort ultracode` sets xhigh. A definition's `effort` overrides the session level, so each role's level applies on these models; Explore at medium matches Haiku 5.5's default. A subagent or workflow agent without `effort` runs at the session level only on the main session's model; on another model it uses that model's saved level or default (2.1.317; verified on 2.1.296 for a sonnet agent that ran at medium while the main session ran at xhigh), so with an Opus main session an `opus` workflow agent without `effort` runs at the main session's level. Keep `CLAUDE_CODE_SUBAGENT_EFFORT` (2.1.316) unset: it applies only where neither the definition nor the call names an effort, and every role above names one. Raise to xhigh when rework or failed verification shows the task needs it.
- Review prompts are adversarial: ask the reviewer to refute the change and prove it does not work. A second reviewer with fresh context beats re-asking the same one.
- Built-in types such as general-purpose and Plan also need an explicit haiku, sonnet, or opus alias.
- A fork ignores the model parameter and runs on the main-session model. Count it at that model's weight and use it only when the full conversation context is required.
- Codex delegation, including codex-rescue, counts as a start and is used only when the user names Codex in the current conversation. The plugin's proactive-use guidance does not override this. The Codex side runs the machine's default model and effort unless the request text carries `--effort`, so always pass it: `--effort medium` by default, `--effort xhigh` for a genuinely hard problem or after a medium attempt fell short.
- Preserve the configured main-session model. A dedicated coordinator profile may pin opus/high.
- Do not use Agent Teams unless workers must talk to each other. Do not enable ultracode.

## Fable worker gate

Two kinds of Fable worker exist and are budgeted differently.

- `reviewer-fable` at low effort is an ordinary read-only start. It is allowed from L1 upward and weighs 1 against the level's budget. Use it when a Sonnet review is uncertain or the diff is high-stakes, and tell it to read before concluding because Fable at low searches less on its own.
- `critical-implementer` and `critical-reviewer` at high effort are the critical slot: at most one start per user task, weighing 2, allowed from L2 upward (an implementation plus its review is L2, and the review may be the critical one), never more than one Fable worker of any kind running concurrently.
- Use the critical slot only for a named issue involving security, permissions, privacy, concurrency, transactions, irreversible migration, high-impact release, a critical architecture boundary, or one evidence-backed normal-role attempt that failed.
- Run critical roles serially after cheaper evidence is consolidated into a compact packet. Never place any Fable worker in parallel(), pipeline(), restart, resume, repair, or rerun.
- Never use Fable workers for exploration, fan-out, routine implementation, builds, browser QA, formatting, or documentation.
- Raise a critical role to xhigh only when an eval on real tasks shows headroom at high; the Fable 5.2 prompting guide reports that xhigh "raised scores slightly and used many more tokens". The same guide says "Most of the gain in capability is already present at `high`" and to "move down to `medium` wherever your evals show that quality holds", so medium is the named midpoint to evaluate between reviewer-fable at low and the critical roles at high.
- No model is swapped silently: this machine keeps `switchModelsOnFlag: false` (the `/config` choice "Ask each time"). Since 2.1.318 a classifier-flagged request inside an Agent-tool subagent fails that subagent with `Agent terminated early due to an API error` and the refusal message instead of re-running on the category fallback model; the main interactive session pauses to ask, and a `-p` turn ends with a refusal (model-config.md, "Subagents switch or fail without asking"). Whether workflow agents and teammates fail the same way is undocumented. A `modelsUsed` field on an Agent result therefore comes from a fallback-chain switch after an API error, not from a flag.
- When a Fable worker fails that way or ends with a refusal stop reason, report it, do not count it as a failed normal-role attempt, and rerun the same task once on the matching normal role at opus/high (implementer for critical-implementer, reviewer for critical-reviewer and reviewer-fable) without spending another Fable start. That rerun runs on Opus 5.5, which carries classifiers, so it can be flagged and fail again; then stop and report it to the user. Finding vulnerabilities in source code is permitted; false positives come mostly from compile-check phrasing, obscure languages, and base64 in tool output.

---
name: handoff
description: Write the session handoff file before a planned break or a session switch, so a new session continues from the file instead of re-reading this conversation. Use when the user runs /handoff, says handoff or 交接, or announces a break longer than the prompt-cache lifetime.
---

# Handoff

Write one file that a fresh session can act on without this conversation. Facts, not narrative; the exact command, not a description of it.

## Where

Write `HANDOFF.md` in a `handoff` directory beside the auto-memory directory named in the system prompt (for example `C:\Users\DS\.claude\projects\E--ds-docs\handoff\HANDOFF.md`). Overwrite it: the previous handoff is superseded by definition. If the system prompt names no memory directory, write `.claude/HANDOFF.md` in the repository and tell the user it is untracked by intent.

## Contents, in this order

1. Header: task title; written at (local date and time); repository and branch; main-session model and effort; Claude Code version.
2. Goal and acceptance: the user's request in their words, the acceptance criteria, the actions the user authorized (stage, commit, push, publish, destructive), and the ones explicitly not authorized.
3. Done: each completed step with its evidence, as the command and its result or the file and what changed in it.
4. In progress: the exact state of unfinished work, including files mid-edit and what remains in each.
5. Decisions: choices made and why, including options rejected, so the next session does not reopen them.
6. Next steps: ordered, smallest first, each naming the command or file it starts from.
7. Blocked or needs the user: open questions, missing authorizations, external evidence that was not available.
8. Working tree: the output of `git status --short`, the files changed since the task began, and any user-owned dirty files that must not be reverted.
9. Dispatch ledger: task level, starts used with the model of each, remaining budget, and the run id of any active workflow.
10. Verification: the exact commands that prove the current state (tests, lint, typecheck, build) and their last result.

Keep it under 200 lines. Refer to files by path; do not paste file contents. Leave out tool output that a listed command reproduces.

## After writing

Reply with the file path and a two-line summary. Do not compact, clear, or end the session; the user decides that. The new session starts with: `Read <path> and continue from its Next steps. Treat its Decisions as settled and do not re-derive what it records.`

# Project Contract

## Product boundary

- Product: <what this repository delivers>
- In scope: <current supported surface>
- Out of scope: <explicit exclusions>
- Current-version policy: <whether backward compatibility is required>

## Architecture

- Runtime and framework versions: <verified versions>
- Source-of-truth modules: <paths and responsibilities>
- External contracts: <APIs, schemas, persistence, and deployment boundaries>
- Generated artifacts: <what generates them and when they must be refreshed>

## Commands

- Install: `<command>`
- Format: `<command>`
- Lint: `<command>`
- Type-check: `<command>`
- Test: `<command>`
- Build: `<command>`
- End-to-end verification: `<command or external prerequisite>`

## Change policy

- Inspect the current implementation and its nearest tests before editing.
- Modify only the owned files named in the task.
- Do not preserve obsolete paths unless an external contract requires them.
- Keep project-specific architecture, framework, and release rules here rather than in the user-level CLAUDE.md.

## Acceptance

- Run the smallest focused check first, then the project-required validation.
- Distinguish local proof from external service, device, browser, or release evidence that was not available.
- Preserve unrelated working-tree changes.

---
paths:
  - 'app/**/*.{ts,tsx}'
  - 'pages/**/*.{ts,tsx}'
  - 'next.config.*'
---

# Current Next.js Version

This is not necessarily the Next.js version represented in your training data. APIs, conventions, defaults, and file structure may have changed.

Before writing code:

1. Read the installed version from the package manager and lockfile.
2. Read the relevant bundled guide under `node_modules/next/dist/docs/` when it exists.
3. Inspect the installed package source and types for the exact API in use.
4. Follow current deprecation notices and migration guidance.

Do not add a compatibility path for an older Next.js version unless an external supported-version contract explicitly requires it.

---
paths:
  - '**/*.kt'
  - '**/*.kts'
---

# Compose Design System

Do not treat Material 3 as the product's foundational visual system. Build and use the application's own professional design system.

Use Compose Foundation as the design-system-neutral primitive layer where it fits. Define product-owned tokens, typography, color, spacing, shape, motion, interaction states, and accessible components. Reuse Material behavior only when it serves the product system rather than dictating its visual language.

Do not replace the entire UI speculatively. Work through complete, testable product surfaces and keep the application usable after each layer.

---
name: coordinator
description: Coordinates bounded engineering work through approved agents and workflows without implementing directly.
tools: Agent(Explore, planner, implementer, critical-implementer, qa, reviewer, reviewer-fable, critical-reviewer, codex:codex-rescue), Read, Grep, Glob, WebFetch, WebSearch, Workflow, Skill
model: opus
effort: high
permissionMode: default
skills:
  - dispatch-policy
---

You are the root coordinator, integrator, and final acceptance owner.

Do not edit files or run shell commands. Your tool list intentionally omits Edit, Write, Bash, and PowerShell. Use an approved worker for implementation and verification, and never ask a worker to bypass its tool boundary.

Treat token cost as a first-class constraint. Complete short read-only work directly. Delegate only when specialization, context isolation, independent validation, or real wall-clock savings justify another context.

Classify every user task before delegation using the L0-L4 budgets in the preloaded dispatch-policy skill. The budgets are ceilings in Opus-equivalent starts. Default to L0. Run every independent start of a phase concurrently and serialize only stages that need an earlier result; concurrency changes wall-clock, not tokens. Count Agent calls, forks, workflow agents, pipeline items, teammates, restarts, resumes, repairs, and reruns at their model's weight. Maintain one cumulative ledger for the whole user task. Never split workflows to evade it. Use direct agents or a workflow in a phase, never both concurrently.

Route by the dispatch-policy role table: each role has a default model and an allowed set, and a per-call model override within that set is normal. Escalate in the dispatch-policy order: first make sure the worker can verify its own work with a test, a build, or a script; then raise effort one level with a per-call `effort` on the same role (never on a Fable role); then move to the next model up at a lower effort than the smaller model used, except that the critical Fable roles keep their defined high. For review, Sonnet is the default, Opus or reviewer-fable when the diff touches permissions, data, concurrency, migration, or public contracts, or when Sonnet reports uncertainty.

Every Agent call must explicitly specify the selected type and matching model. Never rely on model inheritance. Effort comes from the role definition unless an escalation passes `effort` on the call. Read the resolved model from the Agent tool result, and treat a `modelsUsed` field as a mid-run model switch whose output is not the requested model's judgement.

Do not use Agent Teams unless workers must communicate directly. Prefer a reviewed saved workflow over a generated workflow. Keep ultracode off. Before any workflow launch, return a compact preflight containing the workflow name, task level, planned and cumulative starts, peak concurrency, explicit model and effort for every role, Fable count and reason, repair and rerun policy, overflow behavior, and stopping conditions.

Every delegated task must state its objective, in-scope and out-of-scope work, owned files, acceptance criteria, required verification, forbidden actions, evidence format, and stopping conditions.

A worker completion is evidence, not acceptance. Inspect the diff and QA or review evidence before reporting completion. Preserve user-owned dirty files. Do not stage, commit, push, publish, or perform destructive actions without explicit user authorization.

---
name: Explore
description: Performs cheap read-only discovery for one narrow repository or documentation question.
tools: Read, Grep, Glob, WebFetch, WebSearch
model: haiku
effort: medium
permissionMode: plan
---

Answer only the assigned question. Return exact file paths, line numbers, primary sources, and unresolved unknowns. Do not propose unrelated improvements. Stop when the requested evidence is found or the stated search boundary is exhausted.

---
name: planner
description: Produces a bounded implementation plan from verified repository and source evidence.
tools: Read, Grep, Glob, WebFetch, WebSearch, Skill
model: sonnet
effort: high
permissionMode: plan
---

Build a dependency-ordered plan from direct evidence. State every unresolved unknown and the smallest test or source that would resolve it. Do not edit files, widen scope, or turn uncertainty into speculative compatibility, validation, retries, fallbacks, or abstraction.

---
name: implementer
description: Implements one bounded production or test change with focused verification.
tools: Read, Grep, Glob, Edit, Write, Bash, Skill
model: opus
effort: high
autoCompactWindow: 300000
permissionMode: default
---

Own only the files and objective assigned by the coordinator. Make the smallest evidence-backed implementation and run the required focused verification.

Do not spawn agents, widen scope, modify planning or memory files, stage, commit, push, publish, or revert other work. Stop on missing authority, conflicting ownership, or a repeated blocker and return exact evidence.

---
name: critical-implementer
description: Implements one bounded high-risk change that demonstrably requires Fable.
tools: Read, Grep, Glob, Edit, Write, Bash, Skill
model: fable
effort: high
permissionMode: default
---

Follow the implementer contract. Use the additional reasoning budget only for the exact critical issue named in the assignment. Do not redesign adjacent systems. Stop as soon as the acceptance evidence is complete.

---
name: qa
description: Independently runs builds, tests, reproduction, and browser or runtime verification.
tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
model: sonnet
effort: high
permissionMode: default
---

Verify the assigned acceptance criteria independently. Do not modify production or test files. Report commands, exit codes, runtime evidence, failures, and unavailable external conditions. Stop after the required matrix.

---
name: reviewer
description: Performs an independent read-only correctness and regression review.
tools: Read, Grep, Glob, PowerShell
model: sonnet
effort: high
permissionMode: plan
---

Review only the assigned diff and nearby contracts. Use PowerShell only for read-only inspection. Work adversarially: try to refute the change and prove it does not work before accepting it. Prioritize correctness, regressions, data loss, permissions, and missing tests. Every finding must cite evidence and a concrete failure mode. When your conclusion is uncertain, say so explicitly so the lead can escalate to a stronger reviewer. Do not edit files.

---
name: reviewer-fable
description: Read-only review on Fable at low effort for diffs where Sonnet's judgment is not enough; cost per task is comparable to Sonnet/high.
tools: Read, Grep, Glob
model: fable
effort: low
permissionMode: plan
---

Review only the assigned diff and the contracts it touches. Read the changed files and their nearest callers before forming any conclusion; recognizing a file or API name is not the same as knowing its current state, so open it.

Work adversarially: try to refute the change. For every finding cite the file and line, the violated invariant, and a concrete failure scenario. Separate confirmed defects, plausible risks, and unresolved unknowns. If the evidence for a blocking finding is incomplete, say what would settle it rather than guessing.

Do not edit files, do not widen into a repository-wide audit, and stop when the assigned scope is covered.

---
name: critical-reviewer
description: Reviews one bounded security, architecture, permission, concurrency, or migration risk.
tools: Read, Grep, Glob, PowerShell, WebFetch, WebSearch
model: fable
effort: high
permissionMode: plan
---

Perform one bounded high-risk review. Work adversarially: assume the change is wrong and try to prove it. Use PowerShell only for read-only inspection. Separate confirmed defects, plausible risks, and unresolved unknowns. Require a concrete exploit, race, invariant violation, or authoritative source before blocking acceptance. Do not edit files or expand into a repository-wide audit.

Design a saved Claude Code workflow named research-review.

Purpose:
- answer one bounded research question;
- consolidate primary-source and repository evidence;
- optionally perform one critical review only when the evidence proves the escalation gate.

Hard budget:
- L3 only;
- a budget of 6 Opus-equivalent starts for the complete workflow (haiku 0.125, sonnet 0.5, opus 1);
- run independent stages concurrently, inside the runtime cap of 16 workflow agents;
- at most 1 delegated Fable worker, weighing 2, run serially after all cheaper evidence is merged;
- no restart, resume, repair, or rerun of the delegated Fable worker;
- no Agent Team and no ultracode.

Use Haiku for narrow independent discovery and Sonnet/high for synthesis. A delegated Fable/high worker is optional, never the first stage, and never inside parallel() or pipeline(). Do not use a delegated Fable worker merely because the task is broad.

Validate the candidate set before launch. If it exceeds the approved budget, fail fast and return the overflow. Do not silently truncate it. Batch only for the runtime concurrency cap, while keeping the cumulative weighted start count inside the same budget.

Every agent() must explicitly specify model, effort, and a compact output schema. Count each pipeline item and every relaunch execution as a new start. Return a preflight ledger before execution and a final actual-usage ledger.

Design a saved Claude Code workflow named implement-verify.

Purpose:
- implement one bounded change;
- independently verify it;
- independently review its exact diff;
- allow at most one evidence-backed repair if a blocking finding remains.

Hard budget:
- L2 only;
- a budget of 4 Opus-equivalent starts for the complete workflow (haiku 0.125, sonnet 0.5, opus 1);
- run independent stages concurrently;
- no delegated Fable worker;
- no Agent Team and no ultracode.

Run one Opus/high implementer first. Then run Sonnet/high QA and reviewer in parallel only if their file access and state do not conflict. Spend the fourth start only on one bounded Opus/high repair. If there is no blocking finding, finish with three starts instead of filling the budget.

Every agent() must explicitly specify model, effort, and a compact output schema. A repair must name the exact blocking evidence and owned files. Do not relaunch the entire workflow after a late-stage failure; report what would be rerun and require an explicit decision when the remaining budget is unclear.

Design a saved Claude Code workflow named performance-investigation, but do not run it until I explicitly approve L4 in the current conversation.

Goal:
- reproduce one named performance problem;
- capture a profiler baseline and p50, p95, and p99 measurements;
- identify the dominant verified bottleneck;
- implement the smallest justified optimization;
- repeat the same measurement and check functional regressions.

Hard budget after approval:
- a budget of 8 Opus-equivalent starts for the complete workflow (haiku 0.125, sonnet 0.5, opus 1, fable 2);
- run independent stages concurrently, inside the runtime cap of 16 workflow agents;
- at most 1 delegated Fable worker, weighing 2, used only for one critical post-evidence decision;
- the delegated Fable worker must not run in parallel(), pipeline(), restart, resume, repair, or rerun;
- no Agent Team and no ultracode.

Do not optimize from intuition. Use a profiler, preserve the baseline command, dataset, environment, warm-up, and sample count, and report uncertainty. Treat the target threshold as unproven until the repeated measurement reaches it. Stop at the budget limit and return the remaining hypothesis list.

---
name: workflow-authoring
description: Reference for writing a Workflow tool script (script API and gotchas, resume, quality patterns, worked examples). Personal override of the bundled skill; every agent() must name its model. Load before authoring a script for a workflow the user already opted into; it does not itself authorize running one.
---

# Workflow authoring reference

**Model rule (mandatory).** Every `agent()` call must set `model` to `haiku`, `sonnet`, or `opus`, or set `agentType` to a defined role (`Explore`, `planner`, `implementer`, `qa`, `reviewer`) whose definition pins the model. Never omit `model` and never use `fable` inside a workflow. An omitted model inherits the main-session model, which may be the most expensive tier; the dispatch hook denies such scripts before launch. Choose the tier by the role table in the `dispatch-policy` skill: haiku for narrow discovery, sonnet for planning, QA, review, and synthesis, opus for implementation.

<!-- bundled text continues unchanged, except: -->

**Ultracode.** When a system-reminder confirms ultracode is on, that opt-in is standing: author and run a workflow for every substantive task by default. Token cost remains a constraint: the `dispatch-policy` budget for the current task level still caps total agent starts, and every `agent()` still names its model per the rule above. Prefer one well-scoped workflow per phase (understand → design → implement → review) so you stay in the loop between them. The quality patterns below (adversarial verify, multi-modal sweep, completeness critic, loop-until-dry) are the tools; pick what fits the task and the budget. Solo on conversational turns or trivial mechanical edits. When a reminder says ultracode is off, revert to the opt-in rule in the Workflow tool description.

<!-- in the agent() option list: -->

opts.model is REQUIRED unless opts.agentType names a defined role: set it to 'haiku', 'sonnet', or 'opus' for every call. Do not omit it; omission inherits the main-session model. Built-in types such as 'general-purpose' do not pin a model, so they still need opts.model.

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1",
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "12",
    "CLAUDE_CODE_PLUGIN_DIRS": "~/.claude/mods/idle-compact"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Agent|Workflow|SendMessage",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-Command",
              "& 'C:\\Users\\<user>\\.claude\\hooks\\enforce-agent-dispatch.ps1'; if ($null -eq $LASTEXITCODE) { exit 1 }; exit $LASTEXITCODE"
            ],
            "onFailure": "block"
          }
        ]
      }
    ]
  },
  "workflowSizeGuideline": "medium",
  "ultracode": false,
  "subagentPromptCacheTtl": "1h"
}

$ErrorActionPreference = 'Stop'

$DefinedRoles = @('Explore', 'planner', 'implementer', 'qa', 'reviewer')
$FableRoles = @('reviewer-fable', 'critical-implementer', 'critical-reviewer')
$ModelAliasPattern = '\A(haiku|sonnet|opus)(\[1m\])?\z'
$RolePolicies = @{
  'Explore' = @{ model = @('haiku', 'sonnet') }
  'planner' = @{ model = @('sonnet', 'opus') }
  'implementer' = @{ model = @('opus', 'sonnet') }
  'qa' = @{ model = @('sonnet', 'opus') }
  'reviewer' = @{ model = @('sonnet', 'opus') }
  'reviewer-fable' = @{ model = @('fable') }
  'critical-implementer' = @{ model = @('fable') }
  'critical-reviewer' = @{ model = @('fable') }
}
$RegexKeywords = @('return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'throw', 'case', 'do', 'else', 'yield', 'await')

function Write-Decision {
  param(
    [Parameter(Mandatory = $true)]
    [ValidateSet('deny', 'ask', 'allow')]
    [string]$Decision,
    [Parameter(Mandatory = $true)]
    [string]$Reason,
    [string]$Context
  )

  $output = @{
    hookEventName = 'PreToolUse'
    permissionDecision = $Decision
    permissionDecisionReason = $Reason
  }
  if (-not [string]::IsNullOrWhiteSpace($Context)) {
    # An ask reason is shown to the user only; additionalContext reaches Claude with the tool result.
    $output.additionalContext = $Context
  }
  @{ hookSpecificOutput = $output } | ConvertTo-Json -Compress -Depth 4
  exit 0
}

function Fail-Closed {
  param([Parameter(Mandatory = $true)][string]$Message)
  [Console]::Error.WriteLine($Message)
  exit 2
}

function Test-IdentifierChar {
  param([char]$Char)
  return ([char]::IsLetterOrDigit($Char) -or $Char -eq '_' -or $Char -eq '$')
}

# Marks every character of a JavaScript source as code ('c'), string/template/regex content ('s'),
# or comment ('m'), so later scans only see real code. Template `${...}` expressions count as code.
function Get-CodeMask {
  param([Parameter(Mandatory = $true)][string]$Source)

  $mask = New-Object char[] $Source.Length
  $state = 'code'
  $templateDepthStack = New-Object System.Collections.Generic.Stack[int]
  $braceDepth = 0
  $inRegexClass = $false
  $i = 0
  while ($i -lt $Source.Length) {
    $ch = $Source[$i]
    $next = if ($i + 1 -lt $Source.Length) { $Source[$i + 1] } else { [char]0 }
    if ($state -eq 'code') {
      if ($ch -eq '/' -and $next -eq '/') { $state = 'line'; $mask[$i] = 'm'; $mask[$i + 1] = 'm'; $i += 2; continue }
      if ($ch -eq '/' -and $next -eq '*') { $state = 'block'; $mask[$i] = 'm'; $mask[$i + 1] = 'm'; $i += 2; continue }
      if ($ch -eq '/') {
        # Regex literal or division: decide by the previous significant code character.
        $j = $i - 1
        while ($j -ge 0 -and ($mask[$j] -eq 'm' -or [char]::IsWhiteSpace($Source[$j]))) { $j-- }
        $isRegex = $false
        if ($j -lt 0) { $isRegex = $true }
        elseif ($mask[$j] -eq 's') { $isRegex = $false }
        else {
          $prev = $Source[$j]
          $prev2 = if ($j -ge 1) { $Source[$j - 1] } else { [char]0 }
          if (($prev -eq '+' -and $prev2 -eq '+') -or ($prev -eq '-' -and $prev2 -eq '-')) { $isRegex = $false }
          elseif ('(,=:[!&|?{};+-*%<>~^'.IndexOf($prev) -ge 0) { $isRegex = $true }
          elseif (Test-IdentifierChar $prev) {
            $k = $j
            while ($k -ge 0 -and $mask[$k] -eq 'c' -and (Test-IdentifierChar $Source[$k])) { $k-- }
            $word = $Source.Substring($k + 1, $j - $k)
            if ($word -in $RegexKeywords) { $isRegex = $true }
          }
        }
        if ($isRegex) { $state = 'regex'; $inRegexClass = $false; $mask[$i] = 's'; $i++; continue }
        $mask[$i] = 'c'; $i++; continue
      }
      if ($ch -eq "'") { $state = 'single'; $mask[$i] = 's'; $i++; continue }
      if ($ch -eq '"') { $state = 'double'; $mask[$i] = 's'; $i++; continue }
      if ($ch -eq '`') { $state = 'template'; $mask[$i] = 's'; $i++; continue }
      if ($templateDepthStack.Count -gt 0) {
        if ($ch -eq '{') { $braceDepth++ }
        elseif ($ch -eq '}') {
          if ($braceDepth -eq 0) { $templateDepthStack.Pop() | Out-Null; $state = 'template'; $mask[$i] = 's'; $i++; continue }
          $braceDepth--
        }
      }
      $mask[$i] = 'c'; $i++; continue
    }
    if ($state -eq 'single' -or $state -eq 'double') {
      $quote = if ($state -eq 'single') { "'" } else { '"' }
      $mask[$i] = 's'
      if ($ch -eq '\') { if ($i + 1 -lt $Source.Length) { $mask[$i + 1] = 's' }; $i += 2; continue }
      if ($ch -eq $quote -or $ch -eq "`n") { $state = 'code' }
      $i++; continue
    }
    if ($state -eq 'template') {
      $mask[$i] = 's'
      if ($ch -eq '\') { if ($i + 1 -lt $Source.Length) { $mask[$i + 1] = 's' }; $i += 2; continue }
      if ($ch -eq '$' -and $next -eq '{') { $mask[$i + 1] = 's'; $templateDepthStack.Push(1); $braceDepth = 0; $state = 'code'; $i += 2; continue }
      if ($ch -eq '`') { $state = 'code' }
      $i++; continue
    }
    if ($state -eq 'regex') {
      $mask[$i] = 's'
      if ($ch -eq '\') { if ($i + 1 -lt $Source.Length) { $mask[$i + 1] = 's' }; $i += 2; continue }
      if ($ch -eq "`n") { $state = 'code'; $i++; continue }
      if ($inRegexClass) { if ($ch -eq ']') { $inRegexClass = $false }; $i++; continue }
      if ($ch -eq '[') { $inRegexClass = $true; $i++; continue }
      if ($ch -eq '/') { $state = 'code' }
      $i++; continue
    }
    if ($state -eq 'line') {
      $mask[$i] = 'm'
      if ($ch -eq "`n") { $state = 'code' }
      $i++; continue
    }
    # block comment
    $mask[$i] = 'm'
    if ($ch -eq '*' -and $next -eq '/') { $mask[$i + 1] = 'm'; $state = 'code'; $i += 2; continue }
    $i++; continue
  }
  if ($state -ne 'code' -and $state -ne 'line') {
    return $null
  }
  return $mask
}

# Reads a quoted literal that starts at $Index in the original source and returns @{ Value; End }
# (End is the index just past the closing quote), or $null when the value is not a plain literal.
function Read-LiteralValue {
  param([string]$Source, [int]$Index)
  while ($Index -lt $Source.Length -and [char]::IsWhiteSpace($Source[$Index])) { $Index++ }
  if ($Index -ge $Source.Length) { return $null }
  $quote = $Source[$Index]
  if ($quote -ne "'" -and $quote -ne '"' -and $quote -ne '`') { return $null }
  $end = $Source.IndexOf($quote, $Index + 1)
  if ($end -lt 0) { return $null }
  $value = $Source.Substring($Index + 1, $end - $Index - 1)
  if ($value.IndexOf('\') -ge 0 -or $value.IndexOf('$') -ge 0) { return $null }
  return @{ Value = $value; End = $end + 1 }
}

# Returns the literal value of a direct property of the options object, or denies.
function Get-OptionLiteral {
  param([string]$Script, [string]$KeyView, [string]$CodeView, [int]$Offset, [string]$Key, [int]$CallNumber)
  $keyMatches = [regex]::Matches($KeyView, "(?<![A-Za-z0-9_`$])(?:'$Key'|`"$Key`"|$Key)\s*:")
  if ($keyMatches.Count -eq 0) { return $null }
  if ($keyMatches.Count -gt 1) {
    Write-Decision -Decision 'deny' -Reason "Workflow agent call #$CallNumber sets $Key more than once; JavaScript keeps the last value, so the call cannot be verified."
  }
  $m = $keyMatches[0]
  $literal = Read-LiteralValue -Source $Script -Index ($Offset + $m.Index + $m.Length)
  if ($null -eq $literal) {
    Write-Decision -Decision 'deny' -Reason "Workflow agent call #$CallNumber sets $Key to something other than a plain quoted literal. Use a literal alias such as 'sonnet'."
  }
  $k = $literal.End - $Offset
  while ($k -lt $CodeView.Length -and [char]::IsWhiteSpace($CodeView[$k])) { $k++ }
  if ($k -lt $CodeView.Length -and $CodeView[$k] -ne ',' -and $CodeView[$k] -ne '}') {
    Write-Decision -Decision 'deny' -Reason "Workflow agent call #$CallNumber combines the $Key literal with an expression. Use a plain literal."
  }
  return $literal.Value
}

# Returns the plain-literal meta.name of a saved workflow script, or $null when the script has no
# `export const meta = { ... }` object whose depth-1 unquoted `name` key holds a plain quoted literal.
function Get-WorkflowMetaName {
  param([string]$Source)
  if ([string]::IsNullOrWhiteSpace($Source)) { return $null }
  $mask = Get-CodeMask -Source $Source
  if ($null -eq $mask) { return $null }
  $codeChars = New-Object char[] $Source.Length
  for ($i = 0; $i -lt $Source.Length; $i++) { $codeChars[$i] = if ($mask[$i] -eq 'c') { $Source[$i] } else { ' ' } }
  $code = -join $codeChars
  $metaMatch = [regex]::Match($code, '(?<![A-Za-z0-9_$.])export\s+const\s+meta\s*=\s*\{')
  if (-not $metaMatch.Success) { return $null }
  $start = $metaMatch.Index + $metaMatch.Length
  $depthOneChars = New-Object char[] ($code.Length - $start)
  $depth = 1
  $j = $start
  while ($j -lt $code.Length -and $depth -gt 0) {
    $c = $code[$j]
    $depthOneChars[$j - $start] = ' '
    if ($c -eq '{' -or $c -eq '[' -or $c -eq '(') { $depth++ }
    elseif ($c -eq '}' -or $c -eq ']' -or $c -eq ')') { $depth-- }
    elseif ($depth -eq 1) { $depthOneChars[$j - $start] = $c }
    $j++
  }
  if ($depth -ne 0) { return $null }
  $depthOneView = (-join $depthOneChars).Substring(0, $j - $start)
  $nameKeys = [regex]::Matches($depthOneView, '(?<![A-Za-z0-9_$])name\s*:')
  if ($nameKeys.Count -ne 1) { return $null }
  $literal = Read-LiteralValue -Source $Source -Index ($start + $nameKeys[0].Index + $nameKeys[0].Length)
  if ($null -eq $literal) { return $null }
  return $literal.Value
}

# Returns every saved workflow script whose meta.name equals $Name. Claude Code keys saved workflows by
# meta.name, not by file name, and skips a script whose meta it cannot parse.
function Find-WorkflowScriptByName {
  param([string]$Name, [string]$StartDirectory)

  if ($Name -notmatch '\A[A-Za-z0-9_.-]+\z' -or $Name -match '\.\.') { return @() }
  $directories = New-Object System.Collections.Generic.List[string]
  # Claude Code loads project workflows only from the .claude\workflows directories between the working
  # directory and the repository root (the first ancestor holding .git, a directory or a file), nearest
  # first; a script above the root is not one that runs, so the walk stops there.
  $dir = $StartDirectory
  while (-not [string]::IsNullOrWhiteSpace($dir)) {
    $directories.Add((Join-Path $dir '.claude\workflows'))
    if (Test-Path -LiteralPath (Join-Path $dir '.git')) { break }
    $parent = Split-Path -Path $dir -Parent
    if ([string]::IsNullOrWhiteSpace($parent) -or $parent -eq $dir) { break }
    $dir = $parent
  }
  # The personal location follows CLAUDE_CONFIG_DIR when it is set.
  $configDir = if ([string]::IsNullOrWhiteSpace($env:CLAUDE_CONFIG_DIR)) { Join-Path $env:USERPROFILE '.claude' } else { $env:CLAUDE_CONFIG_DIR }
  $directories.Add((Join-Path $configDir 'workflows'))
  $found = New-Object System.Collections.Generic.List[string]
  foreach ($directory in $directories) {
    if (-not (Test-Path -LiteralPath $directory -PathType Container)) { continue }
    foreach ($file in Get-ChildItem -LiteralPath $directory -Filter '*.js' -File) {
      if ((Get-WorkflowMetaName -Source (Get-Content -LiteralPath $file.FullName -Raw)) -ceq $Name) { $found.Add($file.FullName) }
    }
  }
  return $found.ToArray()
}

function Test-WorkflowScript {
  param([Parameter(Mandatory = $true)][string]$Script)

  $mask = Get-CodeMask -Source $Script
  if ($null -eq $mask) {
    Write-Decision -Decision 'deny' -Reason 'Workflow script could not be lexed to the end: an unterminated string, template literal, regex literal, or block comment, or a regex literal written directly after a closing parenthesis, which the policy cannot tell from division. Rewrite the script with plain literals.'
  }
  $codeChars = New-Object char[] $Script.Length
  $noCommentChars = New-Object char[] $Script.Length
  for ($i = 0; $i -lt $Script.Length; $i++) {
    $codeChars[$i] = if ($mask[$i] -eq 'c') { $Script[$i] } else { ' ' }
    $noCommentChars[$i] = if ($mask[$i] -eq 'm') { ' ' } else { $Script[$i] }
  }
  $code = -join $codeChars
  $noComment = -join $noCommentChars

  if ([regex]::IsMatch($code, '\\u[0-9A-Fa-f]{4}|\\u\{|\\x[0-9A-Fa-f]{2}')) {
    Write-Decision -Decision 'deny' -Reason 'Workflow script uses escape sequences outside string literals, which can hide an identifier from inspection.'
  }
  # A bare agent/workflow identifier must be a direct call. The only exemption is an object-literal
  # property key (`{ agent: ... }` or `, agent: ...`); a ternary such as `ok ? agent : other` is not one.
  foreach ($ref in [regex]::Matches($code, '(?<![A-Za-z0-9_$.])(agent|workflow)(?![A-Za-z0-9_$])(?!\s*\()')) {
    $isKey = [regex]::IsMatch($code.Substring(0, $ref.Index), '[{,]\s*\z') -and [regex]::IsMatch($code.Substring($ref.Index + $ref.Length), '\A\s*:')
    if (-not $isKey) {
      Write-Decision -Decision 'deny' -Reason 'Workflow script references agent or workflow without calling it directly (alias, ternary, .call, .apply, or optional call). Write every dispatch as a direct agent(prompt, { model }) call.'
    }
  }
  # Reading a field named agent off a result is fine; invoking through a member, reaching the global
  # object, computed access with a string key, or dynamic code can all alias the real function.
  if ([regex]::IsMatch($code, '\.\s*(agent|workflow)\s*(\(|\?\.|\.\s*(call|apply|bind)\b)')) {
    Write-Decision -Decision 'deny' -Reason 'Workflow script invokes agent or workflow through a member (for example globalThis.agent). Write every dispatch as a direct agent(prompt, { model }) call.'
  }
  if ([regex]::IsMatch($code, '(?<![A-Za-z0-9_$.])(globalThis|window|self|global)(?![A-Za-z0-9_$])|(?<![A-Za-z0-9_$.])this\s*\.\s*(agent|workflow)(?![A-Za-z0-9_$])')) {
    Write-Decision -Decision 'deny' -Reason 'Workflow script accesses the global object (globalThis, window, self, global, or this.agent), which can alias agent or workflow. Call agent(prompt, { model }) directly.'
  }
  if ([regex]::IsMatch($noComment, '\[\s*([''"`])(agent|workflow)\1\s*\]')) {
    Write-Decision -Decision 'deny' -Reason 'Workflow script accesses agent or workflow through a computed member with a string key. Call agent(prompt, { model }) directly.'
  }
  if ([regex]::IsMatch($code, '(?<![A-Za-z0-9_$.])(eval|Function)\s*\(|(?<![A-Za-z0-9_$.])new\s+Function(?![A-Za-z0-9_$])|(?<![A-Za-z0-9_$.])import\s*\(')) {
    Write-Decision -Decision 'deny' -Reason 'Workflow script uses dynamic code (eval, Function, or import()), which the dispatch policy cannot inspect.'
  }
  if ([regex]::IsMatch($code, '(?<![A-Za-z0-9_$.])workflow\s*\(')) {
    Write-Decision -Decision 'deny' -Reason 'Workflow scripts may not call workflow() for a nested workflow: the child script cannot be inspected for per-agent models. Inline the child stages instead.'
  }

  $callNumber = 0
  foreach ($match in [regex]::Matches($code, '(?<![A-Za-z0-9_$.])agent\s*\(')) {
    $open = $match.Index + $match.Length - 1
    $depth = 0
    $close = -1
    for ($j = $open; $j -lt $code.Length; $j++) {
      $c = $code[$j]
      if ($c -eq '(' -or $c -eq '[' -or $c -eq '{') { $depth++ }
      elseif ($c -eq ')' -or $c -eq ']' -or $c -eq '}') { $depth--; if ($depth -eq 0) { $close = $j; break } }
    }
    if ($close -lt 0) {
      Write-Decision -Decision 'deny' -Reason 'Workflow script has an agent call whose parentheses do not balance, so its model cannot be verified.'
    }
    if ([string]::IsNullOrWhiteSpace($noComment.Substring($open + 1, $close - $open - 1))) { continue }
    $callNumber++

    # Split the arguments at depth-zero commas; the API is agent(prompt, options).
    $argsCode = $code.Substring($open + 1, $close - $open - 1)
    $argStarts = New-Object System.Collections.Generic.List[int]
    $argEnds = New-Object System.Collections.Generic.List[int]
    $depth = 0
    $argStart = 0
    for ($j = 0; $j -lt $argsCode.Length; $j++) {
      $c = $argsCode[$j]
      if ($c -eq '(' -or $c -eq '[' -or $c -eq '{') { $depth++ }
      elseif ($c -eq ')' -or $c -eq ']' -or $c -eq '}') { $depth-- }
      elseif ($c -eq ',' -and $depth -eq 0) { $argStarts.Add($argStart); $argEnds.Add($j); $argStart = $j + 1 }
    }
    if (-not [string]::IsNullOrWhiteSpace($noComment.Substring($open + 1 + $argStart, $argsCode.Length - $argStart))) {
      $argStarts.Add($argStart); $argEnds.Add($argsCode.Length)
    }
    if ($argStarts.Count -gt 2) {
      Write-Decision -Decision 'deny' -Reason "Workflow agent call #$callNumber passes more than two arguments; the API is agent(prompt, options)."
    }
    if ($argStarts.Count -lt 2) {
      # agent(prompt) alone, or a lone object literal, passes no options and inherits the main-session model.
      Write-Decision -Decision 'deny' -Reason "Workflow agent call #$callNumber passes no options argument; the API is agent(prompt, options) and every call must set options.model to haiku, sonnet, or opus. A missing model inherits the main-session model."
    }
    $optsIndex = 1
    $segment = $argsCode.Substring($argStarts[$optsIndex], $argEnds[$optsIndex] - $argStarts[$optsIndex])
    $optsStart = -1
    for ($j = 0; $j -lt $segment.Length; $j++) { if (-not [char]::IsWhiteSpace($segment[$j])) { $optsStart = $j; break } }
    $optsEnd = -1
    for ($j = $segment.Length - 1; $j -ge 0; $j--) { if (-not [char]::IsWhiteSpace($segment[$j])) { $optsEnd = $j; break } }
    if ($optsStart -lt 0 -or $segment[$optsStart] -ne '{' -or $segment[$optsEnd] -ne '}') {
      Write-Decision -Decision 'deny' -Reason "Workflow agent call #$callNumber does not pass its options as an object literal, so its model cannot be verified."
    }
    $optsOffset = $open + 1 + $argStarts[$optsIndex] + $optsStart
    $optsLength = $optsEnd - $optsStart + 1

    # Views of the options object limited to its direct (depth-1) content: one keeps only code,
    # the other also keeps quoted property keys so 'model': and "model": are recognised.
    $codeView = New-Object char[] $optsLength
    $keyView = New-Object char[] $optsLength
    for ($j = 0; $j -lt $optsLength; $j++) { $codeView[$j] = ' '; $keyView[$j] = ' ' }
    $depth = 0
    $j = 0
    while ($j -lt $optsLength) {
      $abs = $optsOffset + $j
      $c = $Script[$abs]
      $isCode = $mask[$abs] -eq 'c'
      if ($isCode -and ($c -eq '(' -or $c -eq '[' -or $c -eq '{')) { $depth++; $j++; continue }
      if ($isCode -and ($c -eq ')' -or $c -eq ']' -or $c -eq '}')) { $depth--; $j++; continue }
      if ($depth -eq 1 -and $isCode) { $codeView[$j] = $c; $keyView[$j] = $c; $j++; continue }
      if ($depth -eq 1 -and $mask[$abs] -eq 's') {
        # Scan the whole string run once; keep it in the key view only when it is a property key.
        $k = $abs
        while ($k -lt $Script.Length -and $mask[$k] -eq 's') { $k++ }
        $runEnd = $k
        while ($k -lt $Script.Length -and [char]::IsWhiteSpace($Script[$k])) { $k++ }
        $isKey = ($k -lt $Script.Length -and $Script[$k] -eq ':' -and $mask[$k] -eq 'c')
        if ($isKey) {
          for ($r = $abs; $r -lt $runEnd -and ($r - $optsOffset) -lt $optsLength; $r++) { $keyView[$r - $optsOffset] = $Script[$r] }
        }
        $j = [Math]::Min($runEnd - $optsOffset, $optsLength)
        continue
      }
      $j++
    }
    $codeViewText = -join $codeView
    $keyViewText = -join $keyView
    if ($codeViewText.Contains('...')) {
      Write-Decision -Decision 'deny' -Reason "Workflow agent call #$callNumber spreads another object into its options, which can override model. Write the options inline."
    }

    $model = Get-OptionLiteral -Script $Script -KeyView $keyViewText -CodeView $codeViewText -Offset $optsOffset -Key 'model' -CallNumber $callNumber
    $agentType = Get-OptionLiteral -Script $Script -KeyView $keyViewText -CodeView $codeViewText -Offset $optsOffset -Key 'agentType' -CallNumber $callNumber

    if (($null -ne $model -and $model -match 'fable') -or ($null -ne $agentType -and $agentType -in $FableRoles)) {
      Write-Decision -Decision 'deny' -Reason "Workflow agent call #$callNumber uses Fable. Workflow scripts may not use fable or a Fable role; run a Fable critical role serially through the Agent tool after the workflow has consolidated evidence."
    }
    if ($null -ne $model -and $null -ne $agentType -and $RolePolicies.ContainsKey($agentType)) {
      $allowed = @($RolePolicies[$agentType].model)
      if (($model -replace '\[1m\]\z', '') -notin $allowed) {
        Write-Decision -Decision 'deny' -Reason "Workflow agent call #$callNumber pairs agentType '$agentType' with model '$model'; that role allows '$($allowed -join ' or ')'. A script-level model overrides the definition, so the pair must stay inside the role's allowed set."
      }
    }
    if ($null -ne $model -and $model -match $ModelAliasPattern) { continue }
    if ($null -ne $agentType -and $agentType -in $DefinedRoles) { continue }
    $modelText = if ($null -ne $model) { "'$model'" } else { 'nothing' }
    Write-Decision -Decision 'deny' -Reason "Workflow agent call #$callNumber names $modelText as model and no defined agentType (Explore, planner, implementer, qa, reviewer). Every agent call must set model to haiku, sonnet, or opus. A missing model inherits the main-session model."
  }
  if ($callNumber -eq 0) {
    Write-Decision -Decision 'deny' -Reason 'Workflow script contains no agent call the dispatch policy could parse. A workflow without direct agent(prompt, { model }) calls has nothing verifiable to run.'
  }
  return $callNumber
}

function Resolve-AgentMeta {
  param([string]$AgentId, [string]$TranscriptPath, [string]$SessionId)
  if ([string]::IsNullOrWhiteSpace($TranscriptPath) -or $SessionId -notmatch '\A[0-9A-Za-z-]+\z') { return $null }
  $sessionDir = Join-Path (Split-Path -Path $TranscriptPath -Parent) $SessionId
  if (-not (Test-Path -LiteralPath $sessionDir -PathType Container)) { return $null }
  $meta = Get-ChildItem -LiteralPath $sessionDir -Recurse -Filter "agent-$AgentId.meta.json" -File -ErrorAction SilentlyContinue | Select-Object -First 1
  if ($null -eq $meta) { return $null }
  return (Get-Content -LiteralPath $meta.FullName -Raw | ConvertFrom-Json)
}

# Counts the Fable workers already started in this session by reading every agent-*.meta.json under the
# session directory (Claude Code writes one per started subagent with its agentType and model). A denied
# dispatch never gets a meta file, so denials do not count. Returns $null when the session directory
# cannot be resolved, which the caller treats as "cannot verify" and denies.
function Get-FableStartCount {
  param([string]$TranscriptPath, [string]$SessionId)
  if ([string]::IsNullOrWhiteSpace($TranscriptPath) -or $SessionId -notmatch '\A[0-9A-Za-z-]+\z') { return $null }
  $sessionDir = Join-Path (Split-Path -Path $TranscriptPath -Parent) $SessionId
  if (-not (Test-Path -LiteralPath $sessionDir -PathType Container)) { return 0 }
  $count = 0
  foreach ($metaFile in Get-ChildItem -LiteralPath $sessionDir -Recurse -Filter 'agent-*.meta.json' -File -ErrorAction SilentlyContinue) {
    try { $meta = Get-Content -LiteralPath $metaFile.FullName -Raw | ConvertFrom-Json } catch { continue }
    if (([string]$meta.model) -match 'fable' -or ([string]$meta.agentType) -in $FableRoles) { $count++ }
  }
  return $count
}

# Claude Code writes the hook input as UTF-8. Windows PowerShell decodes [Console]::In with the console
# code page (GBK on this machine), where a multibyte sequence can swallow the following quote and
# corrupt the JSON, so read the raw bytes as UTF-8 explicitly and emit UTF-8 as well.
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$reader = New-Object System.IO.StreamReader([Console]::OpenStandardInput(), [System.Text.UTF8Encoding]::new($false))
$raw = $reader.ReadToEnd()
if ([string]::IsNullOrWhiteSpace($raw)) {
  Fail-Closed 'Agent dispatch policy received empty hook input.'
}

try {
  $call = $raw | ConvertFrom-Json
} catch {
  $dump = Join-Path $env:TEMP 'claude-dispatch-hook-parse-error.txt'
  try { [System.IO.File]::WriteAllText($dump, $raw) } catch { $dump = '(dump failed)' }
  Fail-Closed "Agent dispatch policy could not parse the hook input ($($_.Exception.Message)). Raw input saved to $dump."
}

if ($null -eq $call -or [string]::IsNullOrWhiteSpace([string]$call.tool_name)) {
  Fail-Closed 'Agent dispatch policy received hook input without tool_name.'
}

$workingDirectory = [string]$call.cwd
if ([string]::IsNullOrWhiteSpace($workingDirectory)) { $workingDirectory = (Get-Location).Path }

if ($call.tool_name -eq 'Workflow') {
  $script = $null
  if ($call.tool_input.script -is [string]) { $script = [string]$call.tool_input.script }
  $path = [string]$call.tool_input.scriptPath
  $name = [string]$call.tool_input.name
  # The Workflow input documentation says scriptPath takes precedence over script and name, while Claude
  # Code 2.1.296 runs the inline script when script and scriptPath are both present, so with more than one
  # source the policy cannot tell which script it would approve.
  $sources = @($script, $path, $name) | Where-Object { -not [string]::IsNullOrWhiteSpace($_) }
  if (@($sources).Count -gt 1) {
    Write-Decision -Decision 'deny' -Reason 'Workflow call passes more than one of script, scriptPath, and name, and the documented and observed precedence disagree, so the policy cannot tell which script would run. Pass exactly one of them.'
  }
  if ([string]::IsNullOrWhiteSpace($script)) {
    try {
      if ([string]::IsNullOrWhiteSpace($path) -and -not [string]::IsNullOrWhiteSpace($name)) {
        $matchesByName = @(Find-WorkflowScriptByName -Name $name -StartDirectory $workingDirectory)
        if ($matchesByName.Count -eq 0) {
          Write-Decision -Decision 'deny' -Reason "No saved workflow with meta.name '$name' was found under any .claude\workflows directory between the working directory and the repository root or under the personal workflows directory (CLAUDE_CONFIG_DIR, else ~\.claude), so it is a bundled or plugin workflow, or its meta.name is not a plain literal, and its agent models cannot be inspected. Pass an inline script with explicit models instead."
        }
        if ($matchesByName.Count -gt 1) {
          Write-Decision -Decision 'deny' -Reason "More than one saved workflow declares meta.name '$name' ($($matchesByName -join ', ')), so the policy cannot be sure which one runs. Rename or remove the duplicate, or pass the script inline."
        }
        $path = $matchesByName[0]
      }
      if (-not [string]::IsNullOrWhiteSpace($path) -and (Test-Path -LiteralPath $path -PathType Leaf)) {
        $script = Get-Content -LiteralPath $path -Raw
      }
    } catch {
      Fail-Closed "Agent dispatch policy could not read the workflow script: $($_.Exception.Message)"
    }
  }
  if ([string]::IsNullOrWhiteSpace($script)) {
    Write-Decision -Decision 'deny' -Reason 'Workflow script could not be read by the dispatch policy hook, so its agent models cannot be verified. Pass the script inline or a readable scriptPath.'
  }
  $calls = Test-WorkflowScript -Script $script
  Write-Decision -Decision 'allow' -Reason "Workflow with $calls agent call(s); every call names an approved model." -Context "Dispatch policy: this workflow declares $calls agent call(s), each with an explicit model. Before relying on its results, record the task level, cumulative starts, peak concurrency, and rerun policy in the ledger; a relaunch or resume counts every rerun agent as a new start."
}

if ($call.tool_name -eq 'SendMessage') {
  $target = [string]$call.tool_input.to
  if ($target -eq 'main') {
    exit 0
  }
  if ($target -match 'critical-|fable') {
    Write-Decision -Decision 'deny' -Reason "SendMessage to '$target' would resume a Fable role. Fable workers are never resumed; start a new explicitly approved task instead."
  }
  if ($target -match '^[0-9a-f]{12,}$') {
    try {
      $meta = Resolve-AgentMeta -AgentId $target -TranscriptPath ([string]$call.transcript_path) -SessionId ([string]$call.session_id)
    } catch {
      Fail-Closed "Agent dispatch policy could not read agent metadata: $($_.Exception.Message)"
    }
    if ($null -eq $meta) {
      Write-Decision -Decision 'deny' -Reason "SendMessage to agent ID '$target' cannot be resolved to a model from this session's agent metadata, so it may resume a Fable worker. Address the agent by its role name instead."
    }
    $metaModel = [string]$meta.model
    $metaType = [string]$meta.agentType
    if ($metaModel -match 'fable' -or $metaType -in $FableRoles -or $metaType -match 'critical-|fable') {
      Write-Decision -Decision 'deny' -Reason "SendMessage to agent ID '$target' would resume a Fable worker ($metaType, model $metaModel). Fable workers are never resumed."
    }
    Write-Decision -Decision 'ask' -Reason "SendMessage resumes agent '$target' ($metaType, model $metaModel) and counts as a new worker start." -Context "Dispatch policy: resuming agent '$target' ($metaType on $metaModel) is a new worker start. Count it in the task ledger and stop if the level's total is reached."
  }
  Write-Decision -Decision 'ask' -Reason "SendMessage to '$target' resumes that agent and counts as a new worker start." -Context "Dispatch policy: resuming '$target' is a new worker start. Count it in the task ledger and stop if the level's total is reached."
}

if ($call.tool_name -ne 'Agent') {
  exit 0
}

$agentType = [string]$call.tool_input.subagent_type
$model = [string]$call.tool_input.model
$modelBase = $model -replace '\[1m\]$', ''

if ([string]::IsNullOrWhiteSpace($agentType)) {
  Write-Decision -Decision 'deny' -Reason 'Every Agent dispatch must specify subagent_type.'
}

if ($agentType -eq 'fork') {
  Write-Decision -Decision 'deny' -Reason 'A fork ignores the model parameter and runs on the main-session model. Dispatch an explicit worker role with a model alias instead; if the full conversation context is truly required, the user must run the fork after removing this rule for the session.'
}

if ([string]::IsNullOrWhiteSpace($model)) {
  Write-Decision -Decision 'deny' -Reason "Agent '$agentType' must specify an explicit model. Model inheritance is prohibited."
}

# Per-session Fable cap. Every Fable start (reviewer-fable, critical-implementer, critical-reviewer, or any
# call naming the fable model) is counted against CLAUDE_FABLE_MAX_PER_SESSION (default 7, set by the
# maintainer on 2026-09-24 for the workbench thirteen-items program: five reviewer-fable full-diff reviews
# plus two critical-reviewer audits across B1-B6, so one marathon session can carry the whole plan). The
# count is read from the session's agent meta files, so it survives context compaction and cannot be
# talked down inside the conversation.
if ($modelBase -eq 'fable' -or $agentType -in $FableRoles) {
  # Since 2.1.292 the Agent tool takes a per-call effort that overrides the definition's. The budget weighs
  # reviewer-fable at its defined low effort and the critical roles at high, so an override would change a
  # Fable start's cost without changing its weight.
  $effortOverride = [string]$call.tool_input.effort
  if (-not [string]::IsNullOrWhiteSpace($effortOverride)) {
    Write-Decision -Decision 'deny' -Reason "Fable worker '$agentType' must run at its definition's effort, which its budget weight assumes; the call passes effort '$effortOverride'. Dispatch it without effort, or use an opus role at the effort you need."
  }
  # A name makes a running agent addressable by SendMessage, which would let a custom name slip past the
  # role-name check that keeps Fable workers from being resumed.
  if (-not [string]::IsNullOrWhiteSpace([string]$call.tool_input.name)) {
    Write-Decision -Decision 'deny' -Reason "Fable worker '$agentType' may not take a name: Fable workers are never resumed, and a name would make it addressable by SendMessage. Dispatch it without name."
  }
  $fableCap = 7
  if (-not [string]::IsNullOrWhiteSpace($env:CLAUDE_FABLE_MAX_PER_SESSION) -and $env:CLAUDE_FABLE_MAX_PER_SESSION -match '\A\d{1,3}\z') {
    $fableCap = [int]$env:CLAUDE_FABLE_MAX_PER_SESSION
  }
  try {
    $fableUsed = Get-FableStartCount -TranscriptPath ([string]$call.transcript_path) -SessionId ([string]$call.session_id)
  } catch {
    Fail-Closed "Agent dispatch policy could not count Fable starts: $($_.Exception.Message)"
  }
  if ($null -eq $fableUsed) {
    Write-Decision -Decision 'deny' -Reason "Fable dispatch '$agentType' cannot be counted: the session directory could not be resolved from transcript_path/session_id, so the per-session Fable cap cannot be enforced."
  }
  if ($fableUsed -ge $fableCap) {
    Write-Decision -Decision 'deny' -Reason "Fable cap reached: $fableUsed Fable worker(s) already started in this session and CLAUDE_FABLE_MAX_PER_SESSION is $fableCap. Use an opus role, or have the user raise the cap for this session."
  }
}

$policies = $RolePolicies

if ($policies.ContainsKey($agentType)) {
  $policy = $policies[$agentType]
  if ($modelBase -notin @($policy.model)) {
    Write-Decision -Decision 'deny' -Reason "Agent '$agentType' must use model '$($policy.model -join ' or ')', not '$model'."
  }
  exit 0
}

if ($modelBase -eq 'fable') {
  Write-Decision -Decision 'deny' -Reason "Fable is restricted to reviewer-fable, critical-implementer, and critical-reviewer; agent type '$agentType' is not approved."
}

if ($modelBase -notin @('haiku', 'sonnet', 'opus')) {
  Write-Decision -Decision 'deny' -Reason "Unknown agent type '$agentType' must use an explicit haiku, sonnet, or opus model alias."
}

if ($agentType -like 'codex:*') {
  exit 0
}

Write-Decision -Decision 'ask' -Reason "Agent type '$agentType' has no role definition, so its effort comes from the call's effort parameter or else the session's effort settings for its model." -Context "Dispatch policy: agent type '$agentType' has no role definition, so its effort comes from the call's effort parameter or else the session's effort settings for its model. Prefer a defined role (Explore, planner, implementer, qa, reviewer, reviewer-fable) that pins its own effort, and count this dispatch as a worker start."

// Backstop for Claude Code's built-in idle compaction. Written for 2.1.300, when the built-in
// feature needed fetched feature flags; since 2.1.314 it also runs with DISABLE_TELEMETRY set,
// usually fires first (0.9 of the cache window after the last request), and then this mod finds
// a small context and does nothing. The mod only acts where the built-in pass did not compact,
// and unlike it does not hold back when the usage limit is near.
// After a main-loop turn ends, wait 0.9 of the one-hour prompt cache lifetime; if no turn has
// started since and the context is large, compact while the cache is still warm, so the next
// message sends a summary instead of rebuilding the whole conversation cache.

// 54 minutes, the point the built-in feature fires at (0.9 of the one-hour TTL)
const FIRE_AFTER_MS = 54 * 60_000;
// A timer that runs later than this (the computer slept) finds the cache already gone
const LATE_MS = 60_000;
// The built-in feature's default threshold
const MIN_TOKENS = 200_000;

let timer = null;
let armedAt = 0;

export function register(on) {
  // Subagent and teammate turns carry e.agentId; only the main loop's cache matters here
  on('turn.start', async ($, e, next) => {
    if (e.agentId === undefined) disarm();
    return next(e);
  });

  on('turn.complete', async ($, e, next) => {
    if (e.agentId === undefined) await arm($);
    return next(e);
  });

  on('session.end', async ($, e, next) => {
    disarm();
    return next(e);
  });
}

function disarm() {
  if (timer !== null) timer.cancel();
  timer = null;
}

async function arm($) {
  disarm();
  armedAt = await $.clock.now();
  timer = $.clock.after(FIRE_AFTER_MS, () => fire($));
}

async function fire($) {
  timer = null;
  const idleMs = (await $.clock.now()) - armedAt;
  if (idleMs > FIRE_AFTER_MS + LATE_MS) return;
  // tokens is absent until the session's first response
  const tokens = (await $.session.usage()).context.tokens ?? 0;
  if (tokens < MIN_TOKENS) return;
  // Rejects while a turn runs and in headless (-p / SDK) sessions; the rejection goes to the debug log
  const result = await $.session.compact();
  if ('skip' in result) return;
  $.ui.log(
    `compacted ${Math.round(tokens / 1000)}K tokens after ${Math.round(idleMs / 60_000)} idle minutes, before the prompt cache expired`
  );
}