flanders 0.8.0 → 0.10.0

package/README.md

@@ -11,6 +11,7 @@ Hi-diddly-ho, neighbor! I am a Node.js toolkit that helps avoid AI drifting. I w
 - [Configuration](#configuration)
 - [Usage](#usage)
 - [A worked example](#a-worked-example)
+- [Hard stop](#hard-stop)
 
 ## How it works
 
@@ -40,7 +41,7 @@ A few neighborly things to have on hand before you start:
 
 - **Node.js**.
 - **A git repository** — the `implement` command requires the project to be a git repository.
-- **A supported CLI AI coding tool** — currently Claude Code or Codex.
+- **A supported CLI AI coding tool** — currently Claude Code or Codex CLI.
 
 ## Installation
 
@@ -74,18 +75,20 @@ 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. 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.
 
+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. Just press Enter straight through to reproduce your saved configuration just as it was.
 
 ### Flags
@@ -99,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:
 
@@ -112,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.
@@ -131,7 +137,7 @@ Updated the lib and itching for the freshest skills, neighbor? Just run:
 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.
+`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
 
@@ -238,4 +244,14 @@ If you really want the font to be kept at that size, just save the spec, and no
 ```
 ```
 /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") {
@@ -81,11 +82,11 @@ class ClaudeAdapterIterator {
         this._capturedSessionId = null;
         this._queue = [];
         this._done = false;
-        this._error = null;
         this._waitResolve = null;
         this._abortListener = null;
         this._pendingTerminal = null;
         this._exitPromise = null;
+        this._retainedRateLimitInfo = null;
         this._start();
     }
     _start() {
@@ -122,13 +123,24 @@ class ClaudeAdapterIterator {
         });
         proc.on("error", (e) => {
             if (!this._done) {
+                const err = e instanceof Error ? e : new Error(String(e));
                 this._done = true;
-                this._error = e instanceof Error ? e : new Error(String(e));
+                this._queue.push({
+                    type: "error",
+                    retryable: false,
+                    message: err.code === "ENOENT"
+                        ? "claude binary not found"
+                        : err.message
+                });
                 this._wake();
             }
             exitResolve === null || exitResolve === void 0 ? void 0 : exitResolve();
         });
-        proc.on("exit", () => {
+        proc.on("exit", (code, signal) => {
+            if (this._done) {
+                exitResolve === null || exitResolve === void 0 ? void 0 : exitResolve();
+                return;
+            }
             if (stderrBuf) {
                 this._queue.push({
                     type: "output",
@@ -142,6 +154,20 @@ class ClaudeAdapterIterator {
                 this._queue.push(this._pendingTerminal);
                 this._pendingTerminal = null;
             }
+            else if (signal) {
+                this._queue.push({
+                    type: "error",
+                    retryable: true,
+                    message: `claude terminated by signal ${signal}`
+                });
+            }
+            else {
+                this._queue.push({
+                    type: "error",
+                    retryable: true,
+                    message: `claude exited unexpectedly (code ${code} signal ${signal})`
+                });
+            }
             if (!this._done) {
                 this._done = true;
             }
@@ -149,10 +175,10 @@ class ClaudeAdapterIterator {
             exitResolve === null || exitResolve === void 0 ? void 0 : exitResolve();
         });
         this._abortListener = () => {
+            this._done = true;
             if (this._proc) {
                 this._proc.kill("SIGINT");
             }
-            this._done = true;
             this._wake();
         };
         if (this._args.abortSignal.aborted) {
@@ -173,11 +199,16 @@ 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;
     }
     _handleLine(line) {
         var _a, _b, _c, _d, _e, _f;
+        if (this._done)
+            return;
         let parsed = null;
         try {
             parsed = JSON.parse(line);
@@ -197,6 +228,9 @@ class ClaudeAdapterIterator {
                 this._queue.push({ type: "session", id: parsed.session_id });
             }
         }
+        if (parsed.type === "rate_limit_event" && parsed.rate_limit_info) {
+            this._retainedRateLimitInfo = parsed.rate_limit_info;
+        }
         if (parsed.type === "assistant" && ((_a = parsed.message) === null || _a === void 0 ? void 0 : _a.content)) {
             for (const block of parsed.message.content) {
                 if (block.type === "tool_use" && typeof block.name === "string") {
@@ -259,12 +293,12 @@ class ClaudeAdapterIterator {
         this._wake();
     }
     _classifyError(parsed) {
-        var _a, _b;
+        var _a, _b, _c;
         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 = (_c = this._retainedRateLimitInfo) !== null && _c !== void 0 ? _c : parsed.rate_limit_info;
+        if (info || status === 429) {
             if (info) {
                 const target = info.isUsingOverage && typeof info.overageResetsAt === "number"
                     ? info.overageResetsAt
@@ -273,7 +307,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 };
@@ -309,9 +343,6 @@ class ClaudeAdapterIterator {
             if (this._queue.length > 0) {
                 return { value: this._queue.shift(), done: false };
             }
-            if (this._error) {
-                throw this._error;
-            }
             if (this._done && this._queue.length === 0) {
                 this._cleanup();
                 if (this._exitPromise) {

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;
@@ -97,13 +40,12 @@ class CodexAdapterIterator {
         this._exitPromise = null;
         this._sawTurnCompleted = false;
         this._receivedAnyEvent = false;
-        this._fallbackAttempted = false;
         this._usedResume = false;
-        this._start(false);
+        this._start();
     }
-    _start(useExecFallback) {
+    _start() {
         var _a, _b, _c;
-        const isResume = !useExecFallback && !!this._args.resumeSessionId;
+        const isResume = !!this._args.resumeSessionId;
         this._usedResume = isResume;
         const argv = this._buildArgv(isResume);
         const spawnOptions = { stdio: "pipe" };
@@ -148,23 +90,6 @@ class CodexAdapterIterator {
                 exitResolve === null || exitResolve === void 0 ? void 0 : exitResolve();
                 return;
             }
-            if (this._usedResume && !this._receivedAnyEvent && !this._fallbackAttempted) {
-                this._fallbackAttempted = true;
-                this._queue.push({
-                    type: "output",
-                    title: "Continuity lost",
-                    subtitle: "",
-                    details: "codex resume unavailable in installed CLI"
-                });
-                this._cleanup();
-                this._sawTurnCompleted = false;
-                this._receivedAnyEvent = false;
-                this._usedResume = false;
-                exitResolve === null || exitResolve === void 0 ? void 0 : exitResolve();
-                this._start(true);
-                this._wake();
-                return;
-            }
             if (this._sawTurnCompleted) {
                 this._queue.push({ type: "done" });
             }
@@ -175,6 +100,13 @@ class CodexAdapterIterator {
                     message: `codex terminated by signal ${signal}`
                 });
             }
+            else if (this._usedResume && !this._receivedAnyEvent) {
+                this._queue.push({
+                    type: "error",
+                    retryable: false,
+                    message: "codex exec resume unavailable in installed CLI"
+                });
+            }
             else {
                 this._queue.push({
                     type: "error",
@@ -187,10 +119,10 @@ class CodexAdapterIterator {
             exitResolve === null || exitResolve === void 0 ? void 0 : exitResolve();
         });
         this._abortListener = () => {
+            this._done = true;
             if (this._proc) {
                 this._proc.kill("SIGINT");
             }
-            this._done = true;
             this._wake();
         };
         if (this._args.abortSignal.aborted) {
@@ -203,7 +135,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 +153,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 +176,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 +187,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 +218,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;

package/lib/ai/toolErrorClassification.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRateLimitMessage = isRateLimitMessage;
+exports.isRetryableHttpStatus = isRetryableHttpStatus;
+exports.isRetryableTransport = isRetryableTransport;
+exports.synthesizeRateLimitEvent = synthesizeRateLimitEvent;
+exports.classifyToolFailure = classifyToolFailure;
+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 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;
+}
+function synthesizeRateLimitEvent(time, random) {
+    const r = EIGHT_MINUTES_MS + Math.round(random.random() * (TWELVE_MINUTES_MS - EIGHT_MINUTES_MS));
+    return { type: "rate_limit", waitUntilMs: time.now() + r };
+}
+function classifyToolFailure(message, time, random) {
+    if (isRateLimitMessage(message)) {
+        return synthesizeRateLimitEvent(time, random);
+    }
+    if (isRetryableHttpStatus(message) || isRetryableTransport(message)) {
+        return { type: "error", retryable: true, message };
+    }
+    return { type: "error", retryable: false, message };
+}

package/lib/cli.js

@@ -249,7 +249,9 @@ const ask = (() => {
         async askChoices(questions, output) {
             const out = output !== null && output !== void 0 ? output : outputContext;
             const total = questions.length;
-            const answers = new Array(total).fill(undefined);
+            const answers = questions.map(q => q.multiSelect && q.defaultIndexes !== undefined && q.defaultIndexes.length > 0
+                ? { picked: q.defaultIndexes.map(i => q.options[i]) }
+                : undefined);
             let idx = 0;
             while (idx < total) {
                 const q = questions[idx];
@@ -259,7 +261,7 @@ const ask = (() => {
                 hints.push(q.multiSelect
                     ? `[1-${q.options.length}, comma-separated; free-text OK]`
                     : `[1-${q.options.length}; free-text OK]`);
-                if (q.defaultIndex !== undefined) {
+                if (q.defaultIndex !== undefined || (q.multiSelect && existing !== undefined && existing.picked.length > 0)) {
                     hints.push("Enter for configured");
                 }
                 if (idx > 0) {
@@ -297,6 +299,10 @@ const ask = (() => {
                     idx++;
                     continue;
                 }
+                if (raw === "" && q.multiSelect && existing !== undefined && existing.picked.length > 0) {
+                    idx++;
+                    continue;
+                }
                 const parsed = parseAnswer(raw, q.options.length, q.multiSelect);
                 if (!parsed) {
                     out.writeError("Invalid input. Pick a valid option number, type free-form text, or use '-' / '+' to navigate.\n");