flanders 0.7.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
-# Flanders
+# Motivation
 
-Hi-diddly-ho, neighbor! Flanders is a Node.js toolkit that helps you author contracts, derive work plans from them, and implement those plans through a mix of plain code and AI orchestration. It reaches you through two surfaces — a CLI invoked as `npx flanders <command>`, and three AI-tool skills invoked from inside an AI-coding-tool session.
+Hi-diddly-ho, neighbor! I am a Node.js toolkit that helps avoid AI drifting. I was sick of the AI not reading the `CLAUDE.md`, avoiding rules and forgetting what I told it 3 prompts ago. You know that I, Ned Flanders, will never break a rule, so it was natural for me to spawn here at some point. I will help you define a specification, the public contracts and private rules, and then I will orchestrate the AI for you to implement and review anything without breaking the specification. I have no problem hitting the AI with a stick when it drifts.
 
 ## Contents
 
@@ -11,44 +11,53 @@ Hi-diddly-ho, neighbor! Flanders is a Node.js toolkit that helps you author cont
 - [Configuration](#configuration)
 - [Usage](#usage)
 - [A worked example](#a-worked-example)
+- [Hard stop](#hard-stop)
 
 ## How it works
 
-Flanders speaks to you through two surfaces. The **CLI** — invoked as `npx flanders <command>` — carries three commands: `install`, which sets Flanders up in your project or your home directory; `update`, which refreshes the already-installed skills in place; and `implement [plan]`, which builds a plan from start to finish. The three **AI-tool skills** — `/flanders-spec`, `/flanders-plan`, and `/flanders-work` — are invoked from right inside an AI-coding-tool session.
+With Flanders you first define a specification that will be stored in a `.spec` folder alongside where the specification applies. Then Flanders will help you to create a plan divided into tasks, and via CLI you then implement the plan.
 
-Underneath, Flanders keeps a tidy little spec corpus alongside your code, and everything flows from it:
-
-- **`.spec/contracts`** holds the public obligations a scope exposes — the promises its surface makes to the outside world.
-- **`.spec/rules`** holds the internal conventions its code follows — the house rules it keeps for itself.
-- **`.spec/flanders`** holds behavior rules — the obligations that govern how Flanders' own commands and skills behave while they work in your project.
+Flanders will implement one task at a time, and then will launch, in parallel, as many validators as you have configured. If something differs from the specification, they will notify the worker to review the problem and fix it.
 
-Ordered work plans then live under **`plans/`**: each plan is a sequence of tasks derived from the contracts and rules, ready to be built one at a time.
+I'm not gonna lie, it is token hungry, but that's what you get when you want to reduce specification drifting. The AI has to iterate and validate multiple times what it is doing to avoid the typical "Ah, you are right! You already told me that". Still, Flanders has rate limit detection and retries, so you can let an implementation run overnight while you sleep, without worrying about the limits.
 
 The whole neighborly cycle runs **spec → plan → implement**:
 
-1. Capture obligations and conventions as contracts, rules, and behavior rules in the spec corpus (with `/flanders-spec`).
+1. Capture obligations and conventions as contracts and rules in the spec corpus (with `/flanders-spec`).
 2. Derive an ordered work plan from them under `plans/` (with `/flanders-plan`).
-3. Implement the plan task by task, gating each result through build, test, and adversarial review (with `npx flanders implement`).
+3. Implement the plan task by task, gating each result through build, test, and adversarial review (with `flanders implement`).
 
 For a small, self-contained change that doesn't need a whole plan, there's a friendly shortcut: **`/flanders-work`** implements the request directly and gates it through the same build, test, and adversarial review, all in one invocation.
 
+Underneath, Flanders keeps a tidy little spec corpus alongside your code, and everything flows from it:
+
+- **`.spec/contracts`** holds the public obligations a scope exposes — the promises its surface makes to the outside world.
+- **`.spec/rules`** holds the internal conventions its code follows — the house rules it keeps for itself.
+- **`.spec/flanders`** holds behavior rules — the obligations that govern how Flanders' own commands and skills behave while they work in your project.
+
 ## Requirements
 
 A few neighborly things to have on hand before you start:
 
-- **Node.js** — the CLI is run with `npx`.
+- **Node.js**.
 - **A git repository** — the `implement` command requires the project to be a git repository.
-- **A supported AI coding tool** — currently Claude Code or Codex CLI.
+- **A supported CLI AI coding tool** — currently Claude Code or Codex CLI.
 
 ## Installation
 
 Setting Flanders up is a breeze, neighbor — just run:
 
 ```sh
-npx flanders install
+npm install flanders -g
+```
+
+and then:
+
+```sh
+flanders install
 ```
 
-This is how Flanders first sets up on disk: it is the only command that writes the persistent `.flanders/` configuration that `implement` reads, and the way you publish the skills to a fresh scope. Once the skills are in place, `npx flanders update` refreshes them where they already live (see [Updating](#updating)).
+This is how Flanders first sets up on disk: it is the only command that writes the persistent `.flanders/` configuration that `implement` reads, and the way you publish the skills to a fresh scope.
 
 ### Scope
 
@@ -57,8 +66,6 @@ Flanders installs at one of two scopes, chosen with a pair of mutually exclusive
 - `--project` — the scope is the current working directory. Skills go into the project's AI-tool skill folders, and the `.flanders/` configuration is written at the project root.
 - `--global` — the scope is your home directory. Skills go into the user-level AI-tool skill folders, and the `.flanders/` configuration is written at your home directory.
 
-Passing both at once is a usage error. When you supply neither, the command kindly prompts you to pick one.
-
 ### What it writes
 
 For each AI tool you select for skills, `install` writes one skill artifact per Flanders skill (`/flanders-spec`, `/flanders-plan`, and `/flanders-work`) into that tool's skill folder for the chosen scope:
@@ -68,21 +75,21 @@ For each AI tool you select for skills, `install` writes one skill artifact per
 | Claude Code | `.claude/skills/` | `~/.claude/skills/` |
 | Codex CLI | `.codex/prompts/` | `~/.codex/prompts/` |
 
-Select `both` and the artifacts are written for both tools, each into its own folder. Alongside the skills, the command writes the `.flanders/` configuration at the chosen scope (see [Configuration](#configuration)).
+Select both tools and the artifacts are written for each, into its own folder. Alongside the skills, the command writes the `.flanders/` configuration at the chosen scope (see [Configuration](#configuration)).
 
 ### Interactive prompts
 
 Run it without flags and Flanders walks you through the setup, asking in this order:
 
-1. **Skills tool** — `claude`, `codex`, or `both`.
+1. **Skills tool** — one or more of `claude` and `codex`.
 2. **Scope** — `--project` or `--global`, each option labelled with the concrete destination path(s) for the skills tool you picked.
 3. **Worker tool, model, and effort** — the AI the `implement` command's worker uses.
-4. **Reviewer configuration** — an ordered list of one or more adversarial reviewers, each with its own tool, model, and effort.
-5. **Weighted-review configuration** — when two or more reviewers are configured, the minimum number of reviewers that must run to a verdict, and which reviewers are optional.
+4. **Reviewer configuration** — an ordered list of one or more adversarial reviewers, each with its own tool, model, and effort. You can have any number of reviewers, for example Claude Opus, Claude Sonnet and Codex. You can even duplicate them if you think that one pass is not enough to detect a problem.
+5. **Weighted-review configuration** — when two or more reviewers are configured, the minimum number of reviewers that must run to a verdict, and which reviewers are optional. Optional reviewers will not halt the implementation when they reach a rate limit.
 
-Any question whose answer you supply by flag is not prompted again.
+After the effort question, both the worker and each reviewer are also asked whether to enable Claude Code's fast mode — but only when that role's tool is Claude Code and its chosen model supports fast mode. The question defaults to off, since fast mode bills at a higher rate, and your answer is persisted per role in the `.flanders/` configuration.
 
-And if a `.flanders/` configuration already lives at the scope you choose, neighbor, `install` reads it the moment you pick that scope and pre-selects your stored answers as the question defaults — the worker's tool, model, and effort; the reviewer list, including how many reviewers there are and, for each one, its tool, model, effort, and whether it's optional; and the minimum number of reviewers that must run. Press Enter straight through and, but for one edge case, you reproduce your saved configuration just as it was. That edge case is a stored Codex model the probe no longer offers: with it no longer on the menu, that one question is shown with no pre-selected default and you answer it afresh. The skills tool and the scope aren't kept in that file, so they're always asked fresh too, and any flag you pass still wins over a pre-selected default. When no configuration lives at that scope yet — or the file can't be read — Flanders gently falls back to its fresh-install defaults and pre-selects nothing.
+And if a `.flanders/` configuration already lives at the scope you choose, neighbor, `install` reads it the moment you pick that scope and pre-selects your stored answers as the question defaults. Just press Enter straight through to reproduce your saved configuration just as it was.
 
 ### Flags
 
@@ -95,10 +102,11 @@ Every question has an equivalent command-line flag, so the whole setup can run w
 
 **Skills and worker**
 
-- `--skills-tool=<claude|codex|both>` — which AI tool(s) the skills are installed for.
+- `--skills-tool=<claude|codex|claude,codex>` — which AI tool(s) the skills are installed for, as a comma-separated list of one or more of `claude` and `codex`.
 - `--worker-tool=<claude|codex>` — which AI tool the `implement` worker uses.
 - `--worker-model=<value>` — model the worker tool invokes; an empty value means "use the tool's default configured model".
 - `--worker-effort=<value>` — reasoning effort the worker tool invokes; an empty value means "use the tool's default configured effort".
+- `--worker-fast` — a presence flag that enables Claude Code's fast mode for the worker; off by default, and valid only for a worker whose tool is `claude` and whose model supports fast mode.
 
 **Reviewers** — an ordered list, where reviewer 1 uses the unindexed names and reviewer `N` (2 or greater) carries the index:
 
@@ -108,6 +116,8 @@ Every question has an equivalent command-line flag, so the whole setup can run w
 
 The reviewer indices must form a contiguous run starting at reviewer 1. Supplying any reviewer flag fixes the reviewer list to those indices and skips the "configure another reviewer?" prompt.
 
+A presence flag, `--reviewer-fast` / `--reviewer-N-fast`, enables Claude Code's fast mode for that reviewer; off by default, and valid only for a reviewer whose tool is `claude` and whose model supports fast mode. It annotates a reviewer within the established list rather than establishing or extending it, so — unlike the tool, model, and effort flags above — it neither fixes the list nor skips the "configure another reviewer?" prompt.
+
 **Weighted review** — only meaningful with two or more reviewers:
 
 - `--reviewer-optional` / `--reviewer-N-optional` — a presence flag that marks that reviewer optional; a reviewer with no such flag is required.
@@ -121,17 +131,13 @@ Existing files at the destination — both skill artifacts and `.flanders/` conf
 
 ## Updating
 
-Already set up and itching for the freshest skills, neighbor? Just run:
+Updated the lib and itching for the freshest skills, neighbor? Just run:
 
 ```sh
-npx flanders update
+flanders update
 ```
 
-`update` takes no flags. It scans the four skill destinations `install` writes to — Claude Code and Codex CLI, each at project and global scope — and wherever it finds at least one Flanders skill artifact already in place, it rewrites the full `/flanders-spec`, `/flanders-plan`, and `/flanders-work` trio there with the current version. A destination where no Flanders skill artifact is present is left untouched, so `update` refreshes the installations you already have and never creates one where you had none.
-
-It is entirely hands-off: `update` asks you nothing, and it never reads or writes your `.flanders/` configuration — the worker and reviewer answers a previous `install` saved carry over exactly as they were. Existing skill files are overwritten silently, the same way `install` overwrites them. On success it prints every file it wrote, one path per line.
-
-If no Flanders skills are installed at any scope or tool, `update` has nothing to refresh: it exits with an error that points you to `npx flanders install` to set one up first.
+`update` takes no flags. It scans the four skill destinations `install` writes to — Claude Code's `.claude/skills/` and `~/.claude/skills/`, and Codex CLI's `.codex/prompts/` and `~/.codex/prompts/` — and wherever it finds at least one Flanders skill artifact already in place, it rewrites the full `/flanders-spec`, `/flanders-plan`, and `/flanders-work` trio there with the current version. A destination where no Flanders skill artifact is present is left untouched, so `update` refreshes the installations you already have and never creates one where you had none.
 
 ## Configuration
 
@@ -140,16 +146,6 @@ The `install` command tucks your answers into a `.flanders/` folder so the comma
 - **Project scope** — `.flanders/` at the project root.
 - **Global scope** — `~/.flanders/` in your home directory.
 
-It persists exactly the answers downstream commands need at run time:
-
-- The **worker** the `implement` command uses: its tool (`claude` or `codex`), its model, and its reasoning effort.
-- The **ordered list of adversarial reviewers**, in the order you configured them. Each reviewer carries its own tool (`claude` or `codex`), model, and effort, plus whether it is optional.
-- The **minimum number of reviewers** that must run to a verdict in each review round.
-
-For any model or effort you leave unset — the worker's or a reviewer's — Flanders doesn't record a concrete value; instead it persists the explicit marker `default configured model` or `default configured effort`, which tells the tool to fall back to its own default at run time.
-
-The skills-tool answer is used by `install` itself to decide which folders to write into, so it isn't persisted here.
-
 ### Which configuration wins
 
 When a command reads the configuration, a project-scope `.flanders/` always takes precedence over a global one — and it's all or nothing, with no field-by-field merge between the two. So a project `.flanders/` is used in full when it's present; otherwise the global `~/.flanders/` is used.
@@ -158,20 +154,10 @@ When a command reads the configuration, a project-scope `.flanders/` always take
 
 With Flanders installed, here's how to put it to work — running plans from the CLI and shaping them with the three skills.
 
-### Implementing a plan
-
-```sh
-npx flanders implement [plan]
-```
-
-`implement` takes a plan from your `plans/` folder and carries it through from start to finish. Leave `[plan]` off and Flanders runs the single plan in `plans/` for you automatically; when there's more than one, it lists them and asks you to re-run naming the one to implement. From there it works through each open task with the worker AI, gating every result through build, test, and adversarial review before marking that task complete in the plan — and it commits once per accepted task, so each step lands as its own neat little commit. The whole run is non-interactive: once started, it never stops to ask you anything, and it caps each task at five attempts before halting. The project must be a git repository: `implement` needs git and has no flag to turn it off.
-
 ### The three skills
 
-The skills become available after a successful `npx flanders install` run, and each is invoked from inside your AI-coding-tool session. Each one shapes a different part of the spec → plan → implement cycle:
-
 - **`/flanders-spec`** — turns a free-form request into your contracts, rules, and behavior rules, written into the `.spec/contracts`, `.spec/rules`, and `.spec/flanders` folders.
-- **`/flanders-plan`** — derives a single, ordered, contract-aware work plan under `plans/` from your request.
+- **`/flanders-plan`** — derives a single, ordered, specification-aware work plan from your request.
 - **`/flanders-work`** — implements a small, self-contained request directly and gates it through build, test, and a single adversarial review, all in one invocation — no plan file and no commit.
 
 Each skill takes the same optional `<data>` argument:
@@ -186,14 +172,24 @@ Each skill takes the same optional `<data>` argument:
 - Give it a path to an existing file, and the skill reads that file as the input.
 - Give it any other text, and the skill uses that text verbatim.
 
+### Implementing a plan
+
+```sh
+flanders implement [plan]
+```
+
+`implement` takes a plan from your `plans/` folder and carries it through from start to finish. Leave `[plan]` off and Flanders runs the single plan in `plans/` for you automatically. From there it works through each open task with the worker AI, gating every result through build, test, and adversarial review before marking that task complete in the plan — and it commits once per accepted task, so each step lands as its own neat little commit. The whole run is non-interactive: once started, it never stops to ask you anything, and it caps each task at five attempts before halting. The project must be a git repository: `implement` needs git and has no flag to turn it off.
+
+When the plan implementation is finished, you can squash all the plan commits. They are ordered by task for easier identification.
+
 ### A typical workflow
 
 Here's the neighborly path from a blank slate to shipped code:
 
-1. **`npx flanders install`** — set Flanders up and deliver the skills.
+1. **`flanders install`** — set Flanders up and deliver the skills.
 2. **`/flanders-spec`** — capture your obligations and conventions as contracts, rules, and behavior rules.
 3. **`/flanders-plan`** — derive an ordered work plan from them under `plans/`.
-4. **`npx flanders implement`** — build the plan task by task, each result gated through build, test, and review.
+4. **`flanders implement`** — build the plan task by task, each result gated through build, test, and review.
 
 And when a change is small enough that a whole plan would be overkill, **`/flanders-work`** is your shortcut — it carries that one request from request to reviewed finish without a plan or a commit.
 
@@ -203,43 +199,59 @@ Let's build a tiny web calculator that only multiplies and subtracts, neighbor
 
 1. **Set Flanders up** in your project and deliver the skills:
 
-   ```sh
-   npx flanders install
-   ```
+```sh
+flanders install
+```
 
 2. **Capture the spec** with `/flanders-spec`. You describe what you want; the skill sorts each obligation into the right folder — public behavior into `.spec/contracts`, internal conventions into `.spec/rules`:
 
-   ```
-   /flanders-spec A web calculator with exactly two operations — multiply and
-   subtract — over two number inputs, showing the result. The operation buttons
-   are teal, the result panel is white, and the page background is slate. Build
-   the UI with React bundled by Vite, and use no other UI framework.
-   ```
+```
+/flanders-spec A web calculator with exactly two operations — multiply and subtract — over two number inputs, showing the result. The operation buttons are teal, the result panel is white, and the page background is slate. Build the UI with React bundled by Vite, and use no other UI framework.
+```
 
-   From that one request it writes, for example:
+From that one request it writes, for example:
 
-   - a **functionality contract** under `.spec/contracts/` — the calculator offers exactly two operations, multiply and subtract, over two numeric inputs, and shows the result;
-   - a **colors contract** under `.spec/contracts/` — the operation buttons are teal, the result panel white, and the background slate;
-   - a **frameworks rule** under `.spec/rules/` — the UI is built with React bundled by Vite, and no other UI framework is introduced.
+- a **functionality contract** under `.spec/contracts/` — the calculator offers exactly two operations, multiply and subtract, over two numeric inputs, and shows the result;
+- a **colors contract** under `.spec/contracts/` — the operation buttons are teal, the result panel white, and the background slate;
+- a **frameworks rule** under `.spec/rules/` — the UI is built with React bundled by Vite, and no other UI framework is introduced.
 
-   The skill shows you the planned layout first and writes the files once you approve.
+The skill shows you the planned layout first and writes the files once you approve.
 
-3. **Derive the plan** with `/flanders-plan` — one ordered, contract-aware plan under `plans/`, each task linked back to the contracts and rules it satisfies:
+3. **Derive the plan** with `/flanders-plan` — one ordered, specification-aware plan under `plans/`, each task linked back to the contracts and rules it satisfies:
 
-   ```
-   /flanders-plan
-   ```
+```
+/flanders-plan
+```
 
 4. **Build it** with `implement` — Flanders works each task with the worker AI, gates every result through build, test, and adversarial review, and lands one commit per accepted task:
 
-   ```sh
-   npx flanders implement
-   ```
+```sh
+flanders implement
+```
 
-   When it finishes, the contracts are honored by code: a calculator that multiplies and subtracts and nothing else, in teal, white, and slate, built on the framework your rule pinned.
+When it finishes, the contracts are honored by code: a calculator that multiplies and subtracts and nothing else, in teal, white, and slate, built on the framework your rule pinned.
 
 5. **Tweak it later** with the shortcut — a small change that doesn't need a whole plan:
 
-   ```
-   /flanders-work make the result panel use a larger font
-   ```
+```
+/flanders-work make the result panel use a larger font
+```
+
+If you really want the font to be kept at that size, just save the spec, and no future work will ever break that specification:
+
+```
+/flanders-spec make the result panel use a larger font
+```
+```
+/flanders-work
+```
+
+## Hard stop
+
+Even the most neighborly run can run out of road. When Flanders can't get a single task past the build, test, and review gates within its five attempts, it doesn't keep flailing away — it calls a **hard stop**: the whole `implement` run ends right there and exits with a non-zero status.
+
+It won't leave you guessing, though. Flanders prints an error that names the task that got stuck — its line number in the plan and its title — and points you at that run's temporary folder. Every other time Flanders exits it tidies that folder away, but on a hard stop it leaves it right where it is, on purpose, so you can have a look.
+
+Inside you'll find the sessions from every attempt on the task: the worker's output, the build and test output, each reviewer's output, and the `error.log` that briefed the final iteration. It's the whole story of what was tried and where each go-round fell short.
+
+And here's the neighborly part — you don't have to untangle it all yourself. Hand that folder to your AI coding tool and just ask it to review the folder and tell you why the run failed. It'll read back through the sessions and walk you through what went wrong, so you can mend the spec, the plan, or the task and send Flanders off to try again.

package/lib/ai/AiRunner.d.ts

@@ -1,5 +1,5 @@
 import type { TimeContext } from "../contexts";
-import type { ToolAdapter, ToolAdapterUsageCallback, ToolEventOutput } from "./ToolAdapter";
+import type { ToolAdapter, ToolAdapterUsageCallback, ToolTokenUsage, ToolEventOutput } from "./ToolAdapter";
 export type RunCallbacks = Readonly<{
     onOutput(event: ToolEventOutput): void;
     onSessionId(id: string): void;
@@ -12,7 +12,9 @@ export type RunArgs = Readonly<{
     prompt: string;
     model: string;
     effort: string;
+    fast: boolean;
     resumeSessionId?: string;
+    priorSessionUsage?: ToolTokenUsage;
     abortSignal: AbortSignal;
     callbacks: RunCallbacks;
     time: TimeContext;

package/lib/ai/AiRunner.js

@@ -7,7 +7,7 @@ const INITIAL_TRANSIENT_WAIT_MS = 1000;
 const TRANSIENT_WAIT_CAP_MS = 60000;
 async function run(args) {
     var _a, _b;
-    const { adapter, prompt, model, effort, abortSignal, callbacks, time } = args;
+    const { adapter, prompt, model, effort, fast, abortSignal, callbacks, time } = args;
     if (abortSignal.aborted) {
         throw abortError();
     }
@@ -15,7 +15,7 @@ async function run(args) {
     let transientAttempt = 0;
     let firstInvocation = true;
     for (;;) {
-        const base = { prompt, model, effort, abortSignal, onUsage: callbacks.onUsage };
+        const base = { prompt, model, effort, fast, abortSignal, onUsage: callbacks.onUsage, priorSessionUsage: args.priorSessionUsage };
         let invokeArgs;
         if (firstInvocation) {
             if (args.resumeSessionId) {

package/lib/ai/AiSession.d.ts

@@ -1,5 +1,5 @@
 import type { OutputContext, TimeContext } from "../contexts";
-import type { ToolAdapter } from "./ToolAdapter";
+import type { ToolAdapter, ToolTokenUsage } from "./ToolAdapter";
 export type AiSessionResult = Readonly<{
     text: string;
     sessionId: string | null;
@@ -11,7 +11,9 @@ export type AiSessionOptions = Readonly<{
     prompt: string;
     model: string;
     effort: string;
+    fast: boolean;
     resumeSessionId?: string | null;
+    priorSessionUsage?: ToolTokenUsage;
     onLongWaitStart?(kind: "rate-limit", endTimeMs: number): void;
     onLongWaitEnd?(): void;
 }>;

package/lib/ai/AiSession.js

@@ -71,7 +71,9 @@ class AiSession {
                     prompt: this._options.prompt,
                     model: this._options.model,
                     effort: this._options.effort,
+                    fast: this._options.fast,
                     ...(this._options.resumeSessionId != null ? { resumeSessionId: this._options.resumeSessionId } : null),
+                    ...(this._options.priorSessionUsage != null ? { priorSessionUsage: this._options.priorSessionUsage } : null),
                     abortSignal: controller.signal,
                     callbacks: {
                         onOutput,

package/lib/ai/ClaudeAdapter.d.ts

@@ -1,8 +1,9 @@
-import type { ScriptContext, TimeContext } from "../contexts";
+import type { ScriptContext, TimeContext, RandomContext } from "../contexts";
 import type { ToolAdapter, ToolAdapterInvokeArgs, ToolEvent } from "./ToolAdapter";
 export type ClaudeAdapterContexts = Readonly<{
     claude: ScriptContext;
     time: TimeContext;
+    random: RandomContext;
 }>;
 export declare function formatToolInput(input: Readonly<Record<string, unknown>> | undefined): string;
 export declare class ClaudeAdapter implements ToolAdapter {

package/lib/ai/ClaudeAdapter.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClaudeAdapter = void 0;
 exports.formatToolInput = formatToolInput;
+const toolErrorClassification_1 = require("./toolErrorClassification");
 const TOOL_INPUT_INLINE_MAX = 120;
 function formatToolInput(input) {
     if (!input || typeof input !== "object") {
@@ -173,6 +174,9 @@ class ClaudeAdapterIterator {
         if (this._args.effort) {
             argv.push("--effort", this._args.effort);
         }
+        if (this._args.fast) {
+            argv.push("--settings", JSON.stringify({ fastMode: true }));
+        }
         argv.push("--input-format", "stream-json", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--print", "--dangerously-skip-permissions");
         return argv;
     }
@@ -263,8 +267,8 @@ class ClaudeAdapterIterator {
         const status = parsed.api_error_status;
         const subtype = parsed.subtype;
         const message = (_b = (_a = parsed.error) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : "unknown error";
-        if (status === 429) {
-            const info = parsed.rate_limit_info;
+        const info = parsed.rate_limit_info;
+        if (info || status === 429) {
             if (info) {
                 const target = info.isUsingOverage && typeof info.overageResetsAt === "number"
                     ? info.overageResetsAt
@@ -273,7 +277,7 @@ class ClaudeAdapterIterator {
                     return { type: "rate_limit", waitUntilMs: target * 1000 };
                 }
             }
-            return { type: "error", retryable: true, message };
+            return (0, toolErrorClassification_1.synthesizeRateLimitEvent)(this._contexts.time, this._contexts.random);
         }
         if (typeof status === "number" && status >= 500) {
             return { type: "error", retryable: true, message };

package/lib/ai/CodexAdapter.js

@@ -2,39 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodexAdapter = void 0;
 exports.formatCodexCommand = formatCodexCommand;
+const toolErrorClassification_1 = require("./toolErrorClassification");
 const COMMAND_INLINE_MAX = 120;
-const RATE_LIMIT_SUBSTRINGS = [
-    "out of credits",
-    "refill",
-    "usage limit",
-    "rate limit",
-    "rate-limit",
-    "rate_limit",
-    "quota",
-    "too many requests"
-];
-const RATE_LIMIT_429_RE = /\b429\b/;
-const EIGHT_MINUTES_MS = 8 * 60000;
-const TWELVE_MINUTES_MS = 12 * 60000;
-const FIVE_XX_RE = /\b5\d{2}\b/;
-const STATUS_408_RE = /\b408\b/;
-const STATUS_425_RE = /\b425\b/;
-const TRANSPORT_SUBSTRINGS = [
-    "timeout",
-    "timed out",
-    "connection reset",
-    "connection refused",
-    "socket hang up",
-    "temporarily unavailable",
-    "service unavailable",
-    "gateway",
-    "network",
-    "econnreset",
-    "econnrefused",
-    "enotfound",
-    "etimedout",
-    "eai_again"
-];
 function formatCodexCommand(command) {
     if (!command)
         return "";
@@ -44,32 +13,6 @@ function formatCodexCommand(command) {
     }
     return firstLine;
 }
-function isRateLimitMessage(message) {
-    const lower = message.trim().toLowerCase();
-    for (const sub of RATE_LIMIT_SUBSTRINGS) {
-        if (lower.includes(sub))
-            return true;
-    }
-    return RATE_LIMIT_429_RE.test(message.trim());
-}
-function isRetryableHttpStatus(message) {
-    const trimmed = message.trim();
-    if (FIVE_XX_RE.test(trimmed))
-        return true;
-    if (STATUS_408_RE.test(trimmed))
-        return true;
-    if (STATUS_425_RE.test(trimmed))
-        return true;
-    return false;
-}
-function isRetryableTransport(message) {
-    const lower = message.trim().toLowerCase();
-    for (const sub of TRANSPORT_SUBSTRINGS) {
-        if (lower.includes(sub))
-            return true;
-    }
-    return false;
-}
 class CodexAdapter {
     constructor(_contexts) {
         this._contexts = _contexts;
@@ -154,7 +97,7 @@ class CodexAdapterIterator {
                     type: "output",
                     title: "Continuity lost",
                     subtitle: "",
-                    details: "codex resume unavailable in installed CLI"
+                    details: "codex exec resume unavailable in installed CLI"
                 });
                 this._cleanup();
                 this._sawTurnCompleted = false;
@@ -203,7 +146,7 @@ class CodexAdapterIterator {
     _buildArgv(isResume) {
         const argv = [];
         if (isResume) {
-            argv.push("resume", this._args.resumeSessionId);
+            argv.push("exec", "resume", this._args.resumeSessionId);
         }
         else {
             argv.push("exec");
@@ -221,7 +164,7 @@ class CodexAdapterIterator {
         return argv;
     }
     _handleLine(line) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         if (this._done)
             return;
         let parsed = null;
@@ -244,9 +187,10 @@ class CodexAdapterIterator {
         else if (parsed.type === "turn.completed") {
             this._sawTurnCompleted = true;
             if (parsed.usage && this._args.onUsage) {
+                const base = this._usedResume ? this._args.priorSessionUsage : undefined;
                 this._args.onUsage({
-                    inputTokens: (_a = parsed.usage.input_tokens) !== null && _a !== void 0 ? _a : 0,
-                    outputTokens: (_b = parsed.usage.output_tokens) !== null && _b !== void 0 ? _b : 0
+                    inputTokens: ((_a = parsed.usage.input_tokens) !== null && _a !== void 0 ? _a : 0) - ((_b = base === null || base === void 0 ? void 0 : base.inputTokens) !== null && _b !== void 0 ? _b : 0),
+                    outputTokens: ((_c = parsed.usage.output_tokens) !== null && _c !== void 0 ? _c : 0) - ((_d = base === null || base === void 0 ? void 0 : base.outputTokens) !== null && _d !== void 0 ? _d : 0)
                 });
             }
         }
@@ -254,7 +198,7 @@ class CodexAdapterIterator {
             this._handleFailure(typeof parsed.message === "string" ? parsed.message : "unknown error");
         }
         else if (parsed.type === "turn.failed") {
-            this._handleFailure(typeof ((_c = parsed.error) === null || _c === void 0 ? void 0 : _c.message) === "string" ? parsed.error.message : "unknown error");
+            this._handleFailure(typeof ((_e = parsed.error) === null || _e === void 0 ? void 0 : _e.message) === "string" ? parsed.error.message : "unknown error");
         }
         this._wake();
     }
@@ -285,22 +229,7 @@ class CodexAdapterIterator {
         }
     }
     _handleFailure(message) {
-        if (isRateLimitMessage(message)) {
-            const r = EIGHT_MINUTES_MS + Math.round(this._contexts.random.random() * (TWELVE_MINUTES_MS - EIGHT_MINUTES_MS));
-            this._queue.push({
-                type: "rate_limit",
-                waitUntilMs: this._contexts.time.now() + r
-            });
-        }
-        else if (isRetryableHttpStatus(message)) {
-            this._queue.push({ type: "error", retryable: true, message });
-        }
-        else if (isRetryableTransport(message)) {
-            this._queue.push({ type: "error", retryable: true, message });
-        }
-        else {
-            this._queue.push({ type: "error", retryable: false, message });
-        }
+        this._queue.push((0, toolErrorClassification_1.classifyToolFailure)(message, this._contexts.time, this._contexts.random));
         this._done = true;
     }
     _wake() {

package/lib/ai/ToolAdapter.d.ts

@@ -1,3 +1,4 @@
+import type { TOOL_NAMES } from "../toolNames";
 export type ToolEventOutput = Readonly<{
     type: "output";
     title: string;
@@ -21,16 +22,19 @@ export type ToolEventDone = Readonly<{
     type: "done";
 }>;
 export type ToolEvent = ToolEventOutput | ToolEventSession | ToolEventError | ToolEventRateLimit | ToolEventDone;
-export type ToolAdapterUsageCallback = (usage: Readonly<{
+export type ToolTokenUsage = Readonly<{
     inputTokens: number;
     outputTokens: number;
-}>) => void;
+}>;
+export type ToolAdapterUsageCallback = (usage: ToolTokenUsage) => void;
 type ToolAdapterInvokeArgsBase = Readonly<{
     prompt: string;
     model: string;
     effort: string;
+    fast: boolean;
     abortSignal: AbortSignal;
     onUsage?: ToolAdapterUsageCallback;
+    priorSessionUsage?: ToolTokenUsage;
 }>;
 export type ToolAdapterInvokeArgsFresh = ToolAdapterInvokeArgsBase & Readonly<{
     resumeSessionId?: undefined;
@@ -42,5 +46,5 @@ export type ToolAdapterInvokeArgs = ToolAdapterInvokeArgsFresh | ToolAdapterInvo
 export interface ToolAdapter {
     invoke(args: ToolAdapterInvokeArgs): AsyncIterable<ToolEvent>;
 }
-export type ToolName = "claude" | "codex";
+export type ToolName = (typeof TOOL_NAMES)[number];
 export {};

package/lib/ai/toolErrorClassification.d.ts

@@ -0,0 +1,7 @@
+import type { RandomContext, TimeContext } from "../contexts";
+import type { ToolEventError, ToolEventRateLimit } from "./ToolAdapter";
+export declare function isRateLimitMessage(message: string): boolean;
+export declare function isRetryableHttpStatus(message: string): boolean;
+export declare function isRetryableTransport(message: string): boolean;
+export declare function synthesizeRateLimitEvent(time: TimeContext, random: RandomContext): ToolEventRateLimit;
+export declare function classifyToolFailure(message: string, time: TimeContext, random: RandomContext): ToolEventRateLimit | ToolEventError;