ai-foreman 1.7.24 → 1.7.26

package/README.md

@@ -116,7 +116,7 @@ Provider sessions are historical after import. Resume with `rafi build:resume <p
 | `-a, --agent <agent>` | `claude` / `codex` | single `rafi-config.yaml` target, otherwise `claude` | Builder agent. Explicit `--agent` always wins. |
 | `-m, --model <model>` | `gpt-5.5` / any supported agent model | agent default | Overrides the builder model. |
 | `--effort <level>` | Claude Code: `low` / `medium` / `high` / `xhigh`<br>Codex: `low` / `medium` / `high` / `xhigh` | agent default | Reasoning level. |
-| `--fast` | flag | off | Lower latency. For Codex, maps to `effort=low` when `--effort` is not set. |
+| `--fast` | flag | off | Use native fast mode when the selected model supports it. Otherwise continue at standard speed with the same model and reasoning settings. |
 | `-t, --tickets <path>` | `.md` / `.txt` / `.yaml` | auto-detects standard tracker files | Sends a task file to the builder during preflight planning. |
 | `-y, --yes` | flag | off | Skips preflight confirmation. |
 | `--no-qa` | flag | QA on | Disables per-ticket QA review. |
@@ -640,6 +640,7 @@ For Claude:
 - Bash is denied if it contains an always-escalate substring.
 - Bash is otherwise allowed only for configured prefixes.
 - Every chained segment must start with an `allowBash` prefix.
+- Supported project test forms include literal in-worktree `cd directory &&`, constrained `PYTHONPATH` or test environment assignments, existing project-local virtualenv Python/pytest executables, and `2>&1`. `uv run --offline --no-sync` may wrap an already allowed test command. Every pipeline executable must be allowed. Configure additional test commands under `permissions.allowBash` in `foreman.yaml`; PATH/loader overrides, substitutions, file redirection, and dependency acquisition remain separate decisions.
 - Unknown tools are denied.
 - Unknown Bash commands are denied.
 

package/dist/adapters/claude.d.ts

@@ -95,9 +95,22 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private terminalResult?;
     private streamEnded;
     private closed;
+    private closePromise?;
+    private launchScopeObserved;
+    private providerIdentityObserved;
+    private toolCwd?;
+    private readonly toolCwds;
+    private fastModePrepared?;
+    private fastModeEnabled;
+    private fastModeUnavailable;
+    private turnSawWork;
+    private prepareFastMode;
+    private disableFastModeNotice;
+    private disableFastMode;
     static create(opts: BuilderAdapterOptions): Promise<ClaudeAdapter>;
     private constructor();
     /** Background loop: consume the SDK message stream until it ends. */
+    private providerInputs;
     private pump;
     private handle;
     sendTurn(text: string, policy?: {
@@ -107,6 +120,7 @@ export declare class ClaudeAdapter implements BuilderAdapter {
         purpose?: ProviderTurnPurpose;
     }): Promise<TurnResult>;
     private sendTurnInternal;
+    private sendTurnAttempt;
     private captureStderr;
     private observationContext;
     private observeToolResults;
@@ -128,6 +142,7 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     observeEvents(listener: (event: BuilderEvent) => void): () => void;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
+    private closeInternal;
     private failSessionIdentity;
     private observeSession;
     private settlePending;

package/dist/adapters/claude.js

@@ -1,7 +1,7 @@
 import { ProviderPhaseBarrier } from "../providerPhase.js";
 import { OperationDeadline } from "../util/deadline.js";
 import { createHash, randomUUID } from "node:crypto";
-import { dirname, join } from "node:path";
+import { dirname, join, relative, isAbsolute } from "node:path";
 /** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
 export async function requireClaudeSDK() {
     try {
@@ -20,6 +20,8 @@ import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
 import { classifyClaudeSdkFailure, resolveExecutablePath, sanitizeDiagnostics, } from "../runtimeReadiness.js";
 import { createProviderSessionRef, validateProviderSessionScope, canonicalSessionPath } from "../sessionIdentity.js";
 import { SessionUnavailableError, sessionUnavailableResult } from "./sessionFailure.js";
+import { isFastModeUnavailable, reportFastModeUnavailable } from "./fastMode.js";
+import { handoffSystemInstructions } from "../handoffProtocol.js";
 const DEFAULT_PROVIDER_IDLE_TIMEOUT_MS = 30 * 60_000;
 /**
  * Pure function: build the `options` object passed to `query()`.
@@ -37,7 +39,9 @@ export function buildClaudeQueryOptions(opts) {
         resume: opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId,
         permissionMode: qaReadOnly ? "default" : "acceptEdits",
         effort: opts.effort,
-        extraArgs: opts.fast ? { fast: null } : undefined,
+        // Start at standard speed even when user/project settings enable fast mode.
+        // Enabling it before checking capabilities can silently switch the model.
+        settings: { fastMode: false },
         // Read-only roles still need the user's Claude authentication settings (for
         // example, an enterprise apiKeyHelper). Do not load repository-controlled
         // settings in those roles.
@@ -60,7 +64,7 @@ export function buildClaudeQueryOptions(opts) {
     const exactSkills = opts.preloadedSkillContent?.length
         ? ["# Preloaded Skills", "Use the following skills for this run.", ...opts.preloadedSkillContent.map((skill) => skill.content)].join("\n\n")
         : undefined;
-    const systemAppend = [opts.systemPromptAppend, opts.sessionRole === "builder" ? `Builder runtime contract: shell network ${opts.networkAccess === true ? "explicitly approved for this build" : "disabled"}; sandbox fallback disabled. If acquisition requires unavailable access, request input first or use a provenance-verified local bundle. A ticket answer does not grant runtime permissions.` : undefined, exactSkills].filter((part) => Boolean(part)).join("\n\n");
+    const systemAppend = [handoffSystemInstructions(opts.sessionRole, opts.systemPromptAppend), opts.sessionRole === "builder" ? `Builder runtime contract: shell network ${opts.networkAccess === true ? "explicitly approved for this build" : "disabled"}; sandbox fallback disabled. If acquisition requires unavailable access, request input first or use a provenance-verified local bundle. A ticket answer does not grant runtime permissions.` : undefined, exactSkills].filter((part) => Boolean(part)).join("\n\n");
     if (systemAppend) {
         base.systemPrompt = { type: "preset", preset: "claude_code", append: systemAppend };
     }
@@ -216,6 +220,58 @@ export class ClaudeAdapter {
     terminalResult;
     streamEnded = false;
     closed = false;
+    closePromise;
+    launchScopeObserved = false;
+    providerIdentityObserved = false;
+    toolCwd;
+    toolCwds = new Map();
+    fastModePrepared;
+    fastModeEnabled = false;
+    fastModeUnavailable = false;
+    turnSawWork = false;
+    async prepareFastMode() {
+        if (!this.opts.fast || this.fastModeUnavailable)
+            return;
+        this.fastModePrepared ??= (async () => {
+            // A missing capability is conservative: standard speed, same model.
+            let models;
+            try {
+                const init = await new OperationDeadline("Claude model capabilities", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.query.initializationResult());
+                models = init.models ?? [];
+            }
+            catch (error) {
+                if (!isFastModeUnavailable(String(error)))
+                    throw error;
+                this.disableFastModeNotice();
+                return;
+            }
+            const model = models.find(item => item.value === (this.opts.model ?? "default"));
+            if (model?.supportsFastMode !== true || typeof this.query.applyFlagSettings !== "function") {
+                this.disableFastModeNotice();
+                return;
+            }
+            try {
+                await new OperationDeadline("Claude fast mode", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.query.applyFlagSettings({ fastMode: true }));
+                this.fastModeEnabled = true;
+            }
+            catch (error) {
+                if (!isFastModeUnavailable(String(error)))
+                    throw error;
+                await this.disableFastMode();
+            }
+        })();
+        await this.fastModePrepared;
+    }
+    disableFastModeNotice() {
+        if (!this.fastModeUnavailable)
+            reportFastModeUnavailable(this.opts.model);
+        this.fastModeUnavailable = true;
+        this.fastModeEnabled = false;
+    }
+    async disableFastMode() {
+        await new OperationDeadline("Claude standard speed", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.query.applyFlagSettings({ fastMode: false }));
+        this.disableFastModeNotice();
+    }
     static async create(opts) {
         try {
             const runtimeExecutable = opts.runtimeExecutable ?? resolveExecutablePath("claude");
@@ -269,7 +325,7 @@ export class ClaudeAdapter {
             finish: (spanId, outcome) => opts.observer.store.finishSpan(spanId, { outcome }),
         } : undefined);
         this.query = query({
-            prompt: this.inbox,
+            prompt: this.providerInputs(),
             options: {
                 ...buildClaudeQueryOptions(opts),
                 abortController: this.abort,
@@ -277,6 +333,10 @@ export class ClaudeAdapter {
                     PreToolUse: [{ hooks: [async (input) => {
                                     if (input.hook_event_name !== "PreToolUse")
                                         return {};
+                                    this.toolCwd = input.cwd;
+                                    this.toolCwds.set(input.tool_use_id, input.cwd);
+                                    if (this.toolCwds.size > 1000)
+                                        this.toolCwds.delete(this.toolCwds.keys().next().value);
                                     const reason = this.phaseBarrier.denial(input.tool_name);
                                     return reason ? { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } } : {};
                                 }] }],
@@ -306,6 +366,7 @@ export class ClaudeAdapter {
                         const decision = await opts.permission({
                             toolName,
                             input,
+                            executionCwd: (requestOptions.toolUseID ? this.toolCwds.get(requestOptions.toolUseID) : undefined) ?? this.toolCwd ?? opts.cwd,
                             signal: requestOptions.signal,
                             title: requestOptions.title,
                             displayName: requestOptions.displayName,
@@ -334,6 +395,17 @@ export class ClaudeAdapter {
         this.pumpDone = this.pump();
     }
     /** Background loop: consume the SDK message stream until it ends. */
+    async *providerInputs() {
+        for await (const message of this.inbox) {
+            // A closed queue can still contain buffered input. Never let the SDK
+            // submit it after we recorded a proven pre-submit cancellation/failure.
+            if (this.closed || this.terminalResult || this.streamEnded)
+                return;
+            if (this.pending?.instruction === message.message.content)
+                this.pending.submitted = true;
+            yield message;
+        }
+    }
     async pump() {
         try {
             for await (const msg of this.query) {
@@ -394,10 +466,14 @@ export class ClaudeAdapter {
             for (const block of msg.message.content) {
                 this.eventQueue.push({ kind: "provider-item", provider: "claude", lifecycle: "completed", itemType: String(block.type ?? "unknown"), payload: structuredClone(block), payloadCompleteness: "complete", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
                 if (block.type === "text" && block.text) {
+                    if (msg.error && this.fastModeEnabled && isFastModeUnavailable(block.text) && !this.turnSawWork)
+                        continue;
+                    this.turnSawWork = true;
                     this.eventQueue.push({ kind: "text", text: block.text, byteCount: Buffer.byteLength(block.text), digest: createHash("sha256").update(block.text).digest("hex"), eventId: randomUUID(), observedAt: new Date().toISOString() });
                     this.opts.observer?.signal(true);
                 }
                 else if (block.type === "tool_use") {
+                    this.turnSawWork = true;
                     const callId = block.id;
                     this.toolCalls.set(callId, { name: block.name, input: block.input });
                     if (this.toolCalls.size > 1000)
@@ -530,7 +606,8 @@ export class ClaudeAdapter {
             result.outputTokens = mergedUsage.outputTokens;
             result.usage = { scope: "session-cumulative", inputTokens: mergedUsage.sample.inputTokens, outputTokens: mergedUsage.sample.outputTokens, totalTokens: mergedUsage.sample.totalTokens, costUsd: mergedUsage.sample.authoritativeCostUsd };
             this.cumulativeUsage = mergedUsage.sample;
-            this.eventQueue.push({ kind: "turn-complete", result, turnId: result.turnId });
+            if (!(result.isError && this.fastModeEnabled && !this.turnSawWork && isFastModeUnavailable(text)))
+                this.eventQueue.push({ kind: "turn-complete", result, turnId: result.turnId });
             this.settlePending(result, false);
             this.turnSignals = [];
             this.structuredError = undefined;
@@ -582,7 +659,17 @@ export class ClaudeAdapter {
             this.responseOnlyTurn = false;
         }
     }
-    sendTurnInternal(text) {
+    async sendTurnInternal(text) {
+        if (this.opts.fast)
+            await this.prepareFastMode();
+        const result = await this.sendTurnAttempt(text);
+        if (result.isError && this.fastModeEnabled && !this.turnSawWork && isFastModeUnavailable(result.rawResponse ?? result.text) && !this.streamEnded) {
+            await this.disableFastMode();
+            return this.sendTurnAttempt(text);
+        }
+        return result;
+    }
+    sendTurnAttempt(text) {
         if (this.closed)
             return Promise.reject(new Error("builder is closed"));
         if (this.terminalResult || this.streamEnded)
@@ -593,9 +680,10 @@ export class ClaudeAdapter {
         return new Promise((resolve, reject) => {
             this.eventQueue.push({ kind: "activity", state: "starting Claude turn", provider: "claude", model: this.opts.model });
             this.turnSignals = [];
+            this.turnSawWork = false;
             this.structuredError = undefined;
             this.apiErrorStatus = undefined;
-            const pending = this.pending = { resolve, reject, instruction: text, turnId: this.activeProviderTurnId ?? randomUUID() };
+            const pending = this.pending = { resolve, reject, instruction: text, submitted: false, turnId: this.activeProviderTurnId ?? randomUUID() };
             this.armPendingTurn(pending);
             this.inbox.push({
                 type: "user",
@@ -642,15 +730,16 @@ export class ClaudeAdapter {
             // continue the same turn. Preserve that state as unknown until a
             // correlated, explicit terminal result arrives.
             const resultReason = elapsedOnly ? "elapsed_placeholder"
-                : failed && /timed?\s*out|timeout/i.test(text) ? "timeout"
-                    : failed && /cancel(?:led|ed)/i.test(text) ? "cancelled"
-                        : failed && /permission denied/i.test(text) ? "permission_denied"
-                            : failed && /not found/i.test(text) ? "not_found"
-                                : failed && /\b(?:exit(?:ed)?|status)\s+[1-9]\d*\b/i.test(text) ? "nonzero_exit"
-                                    : failed && /\b(?:failed|error|exception)\b/i.test(text) ? "explicit_error"
-                                        : failed ? "unexplained_error"
-                                            : "completed";
-            const status = resultReason === "timeout" ? "timed_out" : resultReason === "cancelled" ? "cancelled" : ["permission_denied", "not_found", "nonzero_exit", "explicit_error"].includes(resultReason) ? "failed" : resultReason === "completed" ? "completed" : "unknown";
+                : failed && /Foreman policy: this action needs human approval\b[\s\S]*\band was NOT performed\./.test(text) ? "host_policy_denied"
+                    : failed && /timed?\s*out|timeout/i.test(text) ? "timeout"
+                        : failed && /cancel(?:led|ed)/i.test(text) ? "cancelled"
+                            : failed && /permission denied/i.test(text) ? "permission_denied"
+                                : failed && /not found/i.test(text) ? "not_found"
+                                    : failed && /\b(?:exit(?:ed)?|status)\s+[1-9]\d*\b/i.test(text) ? "nonzero_exit"
+                                        : failed && /\b(?:failed|error|exception)\b/i.test(text) ? "explicit_error"
+                                            : failed ? "unexplained_error"
+                                                : "completed";
+            const status = resultReason === "host_policy_denied" ? "denied" : resultReason === "timeout" ? "timed_out" : resultReason === "cancelled" ? "cancelled" : ["permission_denied", "not_found", "nonzero_exit", "explicit_error"].includes(resultReason) ? "failed" : resultReason === "completed" ? "completed" : "unknown";
             if (status !== "unknown") {
                 this.completedToolCalls.add(callId);
                 if (this.completedToolCalls.size > 1000)
@@ -699,7 +788,8 @@ export class ClaudeAdapter {
             });
             const prepare = async () => {
                 await this.query.initializationResult();
-                if (!this._sessionRef?.validatedAt && typeof this.query.supportedCommands === "function") {
+                await this.prepareFastMode();
+                if (!this.providerIdentityObserved && typeof this.query.supportedCommands === "function") {
                     const commands = await this.query.supportedCommands();
                     // Some SDK/CLI pairs expose init identity only after their first input.
                     // Require an advertised built-in local command; never substitute a
@@ -708,7 +798,10 @@ export class ClaudeAdapter {
                         this.opts.onLifecycleTrace?.({ phase: "local-context-initialization-start", at: new Date().toISOString() });
                         const result = await this.sendTurn("/context", { responseOnly: true });
                         this.opts.onLifecycleTrace?.({ phase: "local-context-initialization-complete", at: new Date().toISOString() });
-                        if (result.isError || result.failure || result.costUsd > 0)
+                        // SDK total_cost_usd includes earlier conversation cost on resume.
+                        // The advertised built-in command must report zero model turns;
+                        // historical cumulative cost does not make this a paid warm-up.
+                        if (result.isError || result.failure || result.numTurns !== 0 || (result.costUsd > 0 && result.usage?.scope !== "session-cumulative"))
                             throw new Error("Claude local context initialization did not complete without model work");
                     }
                 }
@@ -803,7 +896,7 @@ export class ClaudeAdapter {
         // The SDK can acknowledge initialization while its CLI is still waiting
         // for first input. Sending getContextUsage then deadlocks the control
         // queue, including a later local command. Establish identity first.
-        if (!this._sessionRef?.validatedAt && typeof this.query.supportedCommands === "function")
+        if (!this.providerIdentityObserved && typeof this.query.supportedCommands === "function")
             await this.prepareSession();
         await new OperationDeadline("Claude settings", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.query.applyFlagSettings({ autoCompactEnabled: true }));
         const baseline = await new OperationDeadline("Claude context usage", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.query.getContextUsage());
@@ -825,10 +918,10 @@ export class ClaudeAdapter {
             || !Number.isFinite(installed.autoCompactThreshold) || installed.autoCompactThreshold === undefined) {
             throw new Error("Claude did not expose an enabled native automatic-compaction threshold after configuration");
         }
-        // `applyFlagSettings` can legitimately clamp autoCompactWindow. The
-        // provider's reported trigger is authoritative; rejecting the entire run
-        // merely because a configured value is below that minimum made defaults
-        // unusable. Lifecycle code consumes this verified effective ceiling.
+        // A control acknowledgment may disagree with the SDK's subsequent report.
+        // Use that reported threshold as the available lifecycle telemetry rather
+        // than rejecting the build. This does not prove clamping or independently
+        // verify the native trigger's actual enforcement.
         const effectiveThresholdPercent = Math.max(1, Math.min(99, Math.floor(installed.autoCompactThreshold / installed.maxTokens * 100)));
         this.preparedAutoCompactionPolicy = {
             requestedThresholdPercent: threshold,
@@ -866,20 +959,32 @@ export class ClaudeAdapter {
             return { ok: false, error: "Claude SDK cannot change reasoning/fast controls on an existing transport" };
         if (settings.model === this.opts.model)
             return { ok: true };
+        if (this.opts.fast)
+            await this.prepareFastMode();
+        if (this.fastModeEnabled)
+            await new OperationDeadline("Claude standard speed", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.query.applyFlagSettings({ fastMode: false }));
+        this.fastModeEnabled = false;
         const result = await new OperationDeadline("Claude model settings", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.sendTurn(`/model ${settings.model ?? "default"}`), () => this.abort.abort());
         if (result.isError)
             return { ok: false, error: result.text, ...(result.failure ? { failure: result.failure } : {}) };
         this.opts.model = settings.model;
+        this.fastModePrepared = undefined;
+        this.fastModeUnavailable = false;
+        if (this.opts.fast)
+            await this.prepareFastMode();
         return { ok: true };
     }
     observeEvents(listener) { return this.eventQueue.observe(listener); }
     events() {
         return this.eventQueue;
     }
-    async close() {
+    close() { return this.closePromise ??= this.closeInternal(); }
+    async closeInternal() {
         if (this.closed)
             return;
         this.closed = true;
+        if (this.pending)
+            this.settlePending(this.streamFailureResult("Claude turn interrupted; submitted work requires recovery", false));
         this.questionTrace?.finish("closed");
         this.rejectSessionIdentity(new Error("Claude session closed during initialization"));
         this.abort.abort();
@@ -896,7 +1001,7 @@ export class ClaudeAdapter {
     failSessionIdentity(error) {
         this.rejectSessionIdentity(error);
         const result = sessionUnavailableResult(new SessionUnavailableError({
-            runtime: "claude", phase: this.pending ? "turn" : "preflight", dispatchState: this.pending ? "unknown" : "not-sent",
+            runtime: "claude", phase: this.pending ? "turn" : "preflight", dispatchState: this.pending?.submitted ? "unknown" : "not-sent",
             executable: this.opts.runtimeExecutable ?? "claude", cwd: this.opts.cwd, diagnostics: error.message,
             availability: { version: 1, status: "unavailable", checkedAt: new Date().toISOString(), reason: "attach-failed", detail: error.message, ...(this._sessionRef ? { sessionRef: this._sessionRef } : {}) },
         }));
@@ -912,11 +1017,26 @@ export class ClaudeAdapter {
             this.failSessionIdentity(error);
             throw error;
         }
-        if (observedCwd !== undefined && canonicalSessionPath(observedCwd) !== canonicalSessionPath(this.opts.cwd)) {
+        const launchCwd = canonicalSessionPath(this.opts.cwd);
+        const currentCwd = observedCwd === undefined ? undefined : canonicalSessionPath(observedCwd);
+        const withinLaunchScope = currentCwd === undefined ? false : (() => {
+            const path = relative(launchCwd, currentCwd);
+            return path === "" || (!isAbsolute(path) && path !== ".." && !path.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`));
+        })();
+        // Establish the launch scope before trusting mutable Bash cwd. Subsequent
+        // messages for the same identity may report a directory inside that scope;
+        // they must not replace the immutable cwd in the durable session reference.
+        const trustedResumeScope = Boolean(this.opts.resumeSessionRef?.validatedAt && canonicalSessionPath(this.opts.resumeSessionRef.cwd) === launchCwd);
+        if (currentCwd !== undefined && (this.launchScopeObserved || trustedResumeScope ? !withinLaunchScope : currentCwd !== launchCwd)) {
             const error = new Error(`Claude session cwd ${observedCwd} does not match ${this.opts.cwd}`);
             this.failSessionIdentity(error);
             throw error;
         }
+        if (currentCwd === launchCwd)
+            this.launchScopeObserved = true;
+        this.providerIdentityObserved = true;
+        if (currentCwd !== undefined)
+            this.toolCwd = currentCwd;
         this._sessionId = sessionId;
         if (this._sessionRef?.validatedAt) {
             this.resolveSessionIdentity(this._sessionRef);
@@ -1021,19 +1141,20 @@ export class ClaudeAdapter {
         return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_PROVIDER_IDLE_TIMEOUT_MS;
     }
     streamFailureResult(message, sessionUnavailable) {
+        const dispatchState = this.pending?.submitted === false ? "not-sent" : "unknown";
         if (sessionUnavailable) {
             const availability = {
                 version: 1, status: "unavailable", checkedAt: new Date().toISOString(), reason: "not-found",
                 detail: message, ...(this._sessionRef ? { sessionRef: this._sessionRef } : {}),
             };
             return sessionUnavailableResult(new SessionUnavailableError({
-                runtime: "claude", phase: "turn", dispatchState: "unknown", executable: this.opts.runtimeExecutable ?? "claude",
+                runtime: "claude", phase: "turn", dispatchState, executable: this.opts.runtimeExecutable ?? "claude",
                 cwd: this.opts.cwd, diagnostics: message, availability,
             }));
         }
         return {
             text: message, isError: true, numTurns: 0, costUsd: 0, costAuthoritative: false,
-            failure: { runtime: "claude", phase: this.opts.runtimePhase ?? "builder", category: "agent-stream", executable: this.opts.runtimeExecutable ?? "claude", cwd: this.opts.cwd, diagnostics: message, dispatchState: "unknown" },
+            failure: { runtime: "claude", phase: this.opts.runtimePhase ?? "builder", category: "agent-stream", executable: this.opts.runtimeExecutable ?? "claude", cwd: this.opts.cwd, diagnostics: message, dispatchState },
         };
     }
 }

package/dist/adapters/codex.d.ts

@@ -28,6 +28,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     private sessionAvailability?;
     private initialized;
     private closed;
+    private closePromise?;
     private activeText;
     private usage?;
     private usageRevision;
@@ -53,6 +54,13 @@ export declare class CodexAdapter implements BuilderAdapter {
     private readonly answeredApprovalRequests;
     private activeProviderTurnSpanId?;
     private readonly toolSpans;
+    private effectiveModel?;
+    private fastPreparedModel?;
+    private fastTier?;
+    private readonly fastUnavailableModels;
+    private turnSawTool;
+    private disableFastMode;
+    private prepareFastMode;
     constructor(opts: BuilderAdapterOptions);
     contractCapabilities(): {
         sameSessionAcceptance: boolean;
@@ -89,6 +97,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     observeEvents(listener: (event: BuilderEvent) => void): () => void;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
+    private closeInternal;
     private ensureThread;
     private ensureThreadInternal;
     private threadAttached;

package/dist/adapters/codex.js

@@ -9,6 +9,8 @@ import { BuilderEventQueue, withActivityPhase } from "../activity.js";
 import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
 import { canonicalSessionPath, createProviderSessionRef, validateProviderSessionScope } from "../sessionIdentity.js";
 import { SessionUnavailableError, sessionUnavailableResult } from "./sessionFailure.js";
+import { isFastModeUnavailable, reportFastModeUnavailable } from "./fastMode.js";
+import { handoffSystemInstructions } from "../handoffProtocol.js";
 /** Compatibility parser for recorded pre-app-server JSONL fixtures. */
 export function parseCodexLine(raw) {
     const type = raw.type;
@@ -42,6 +44,7 @@ export class CodexAdapter {
     sessionAvailability;
     initialized = false;
     closed = false;
+    closePromise;
     activeText = [];
     usage;
     usageRevision = 0;
@@ -67,6 +70,47 @@ export class CodexAdapter {
     answeredApprovalRequests = new Set();
     activeProviderTurnSpanId;
     toolSpans = new Map();
+    effectiveModel;
+    fastPreparedModel;
+    fastTier;
+    fastUnavailableModels = new Set();
+    turnSawTool = false;
+    disableFastMode() {
+        const model = this.opts.model ?? this.effectiveModel ?? "default";
+        if (!this.fastUnavailableModels.has(model))
+            reportFastModeUnavailable(model);
+        this.fastUnavailableModels.add(model);
+        this.fastTier = undefined;
+    }
+    async prepareFastMode() {
+        const model = this.opts.model ?? this.effectiveModel ?? "default";
+        if (!this.opts.fast || this.fastPreparedModel === model)
+            return;
+        this.fastPreparedModel = model;
+        this.fastTier = undefined;
+        if (this.fastUnavailableModels.has(model))
+            return;
+        try {
+            let cursor;
+            for (let page = 0; page < 20; page++) {
+                const result = await this.request("model/list", { includeHidden: true, ...(cursor ? { cursor } : {}) });
+                const entry = result.data?.find(item => item.model === model || item.id === model);
+                if (entry) {
+                    this.fastTier = entry.serviceTiers?.find(tier => tier.name?.toLowerCase() === "fast" || ["fast", "priority"].includes(tier.id))?.id;
+                    // Older app-server versions publish only the legacy speed list.
+                    if (entry.serviceTiers === undefined && entry.additionalSpeedTiers?.includes("fast"))
+                        this.fastTier = "fast";
+                    break;
+                }
+                if (!result.nextCursor || result.nextCursor === cursor)
+                    break;
+                cursor = result.nextCursor;
+            }
+        }
+        catch { /* Optional capability discovery never blocks a standard turn. */ }
+        if (!this.fastTier)
+            this.disableFastMode();
+    }
     constructor(opts) {
         this.opts = opts;
         this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
@@ -93,8 +137,6 @@ export class CodexAdapter {
             args.push("-m", this.opts.model);
         if (this.opts.effort)
             args.push("-c", `model_reasoning_effort=${this.opts.effort}`);
-        else if (this.opts.fast)
-            args.push("-c", "model_reasoning_effort=low");
         if (this._sessionId)
             args.push("resume", this._sessionId);
         args.push(instruction);
@@ -144,23 +186,38 @@ export class CodexAdapter {
         const providerInstruction = this.buildInstruction(instruction);
         try {
             await this.ensureThread();
+            if (this.opts.fast)
+                await this.prepareFastMode();
             const toolsBefore = this.observedToolCalls;
+            this.turnSawTool = false;
             this.activeText = [];
             this.lastTurnTokens = undefined;
             this.turnUsageBaseline = this.providerSessionUsage ? { ...this.providerSessionUsage } : undefined;
             const completion = this.waitFor("turn/completed", (params) => params.threadId === this._sessionId, this.providerIdleTimeoutMs(), true);
+            void completion.catch(() => { });
             turnStartDispatched = true;
-            const started = await this.request("turn/start", {
+            const startParams = {
                 threadId: this._sessionId,
                 input: [{ type: "text", text: providerInstruction, text_elements: [] }],
                 cwd: this.opts.cwd,
-                model: this.opts.model ?? null,
-                effort: this.opts.effort ?? (this.opts.fast ? "low" : null),
+                model: this.opts.model ?? this.effectiveModel ?? null,
+                effort: this.opts.effort ?? null,
+                ...(this.opts.fast ? { serviceTier: this.fastTier ?? "default" } : {}),
                 approvalPolicy: policy?.responseOnly || policy?.purpose && policy.purpose !== "implementation" ? "never" : this.effectiveApprovalPolicy(),
                 sandboxPolicy: policy?.responseOnly || policy?.purpose && policy.purpose !== "implementation" || this.opts.sandboxMode === "read-only" || this.opts.sessionRole === "qa"
                     ? { type: "readOnly", networkAccess: false }
                     : { type: "workspaceWrite", writableRoots: [this.opts.cwd], networkAccess: this.effectiveNetworkAccess() },
-            });
+            };
+            let started;
+            try {
+                started = await this.request("turn/start", startParams);
+            }
+            catch (error) {
+                if (!this.fastTier || !isFastModeUnavailable(String(error)) || this.turnSawTool || this.activeText.length)
+                    throw error;
+                this.disableFastMode();
+                started = await this.request("turn/start", { ...startParams, serviceTier: "default" });
+            }
             this.activeNativeTurnId = String(started.turn?.id ?? "") || undefined;
             const params = await new OperationDeadline("Codex active turn", this.opts.turnDeadlineMs ?? 3_600_000).run(() => completion);
             const turn = params.turn;
@@ -168,6 +225,10 @@ export class CodexAdapter {
             const failed = turn?.status === "failed" || responseOnlyViolation;
             const error = turn?.error;
             const text = this.activeText.join("\n");
+            if (failed && !responseOnlyViolation && this.fastTier && !this.turnSawTool && !text && isFastModeUnavailable(String(error?.message ?? ""))) {
+                this.disableFastMode();
+                return this.sendTurnInternal(instruction, policy);
+            }
             const result = {
                 text: failed ? normalizeRuntimeErrorText("codex", String(responseOnlyViolation ? "Response-only correction used tools; its result cannot authorize completion" : error?.message ?? text), null, "app-server turn") : text,
                 isError: failed, numTurns: 1, costUsd: 0, costAuthoritative: false,
@@ -381,6 +442,8 @@ export class CodexAdapter {
     }
     async sessionUsage() { return this.providerSessionUsage ? { ...this.providerSessionUsage } : undefined; }
     async switchSettings(settings) {
+        if (settings.model !== this.opts.model || settings.fast !== this.opts.fast)
+            this.fastPreparedModel = undefined;
         this.opts.model = settings.model;
         this.opts.effort = settings.effort;
         this.opts.fast = settings.fast;
@@ -417,7 +480,8 @@ export class CodexAdapter {
     }
     observeEvents(listener) { return this.eventQueue.observe(listener); }
     events() { return this.eventQueue; }
-    async close() {
+    close() { return this.closePromise ??= this.closeInternal(); }
+    async closeInternal() {
         if (this.closed)
             return;
         this.closed = true;
@@ -475,7 +539,7 @@ export class CodexAdapter {
                 model: this.opts.model ?? null, approvalPolicy: this.effectiveApprovalPolicy(),
                 config: { sandbox_workspace_write: { network_access: this.effectiveNetworkAccess() } },
                 sandbox: this.opts.sandboxMode === "read-only" || this.opts.sessionRole === "qa" ? "read-only" : "workspace-write",
-                developerInstructions: this.opts.systemPromptAppend ?? null,
+                developerInstructions: handoffSystemInstructions(this.opts.sessionRole, this.opts.systemPromptAppend) ?? null,
             });
         }
         catch (error) {
@@ -546,6 +610,7 @@ export class CodexAdapter {
         }
         this.sessionAvailability = { version: 1, status: "available", checkedAt: new Date().toISOString(), observedCwd: providerCwd ?? canonicalSessionPath(this.opts.cwd), sessionRef: this._sessionRef };
         this.threadAttached = true;
+        this.effectiveModel = typeof result.model === "string" ? result.model : this.opts.model;
         this.eventQueue.push({ kind: "session-transition", transition: method === "thread/resume" ? "resumed" : "started" });
     }
     threadAttached = false;
@@ -614,6 +679,7 @@ export class CodexAdapter {
             if (item)
                 this.eventQueue.push({ kind: "provider-item", provider: "codex", lifecycle: "started", itemType: String(item.type ?? "unknown"), payload: exactProviderItem(item), payloadCompleteness: "complete", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
             if (isCodexToolItem(item)) {
+                this.turnSawTool = true;
                 this.observedToolCalls += 1;
                 const callId = codexItemId(item) ?? randomUUID();
                 const name = codexToolName(item);
@@ -633,6 +699,7 @@ export class CodexAdapter {
             if (item)
                 this.eventQueue.push({ kind: "provider-item", provider: "codex", lifecycle: "completed", itemType: String(item.type ?? "unknown"), payload: exactProviderItem(item), payloadCompleteness: "complete", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
             if (isCodexToolItem(item)) {
+                this.turnSawTool = true;
                 const callId = codexItemId(item);
                 const spanId = callId ? this.toolSpans.get(callId) : undefined;
                 const status = typeof item?.status === "string" ? item.status : undefined;
@@ -710,6 +777,8 @@ export class CodexAdapter {
         else if (message.method === "error") {
             const error = params.error;
             const reason = String(error?.message ?? params.message ?? "Codex app-server error");
+            if (this.fastTier && isFastModeUnavailable(reason) && !this.activeText.length && !this.turnSawTool)
+                return;
             if (params.willRetry === true) {
                 const retryId = randomUUID();
                 this.eventQueue.push(this.opts.observer

package/dist/adapters/fastMode.d.ts

@@ -0,0 +1,4 @@
+/** Only explicit speed-option rejection permits a same-session retry. Auth,
+ * generic model failures, timeouts, and uncertain transport failures do not. */
+export declare function isFastModeUnavailable(detail: string): boolean;
+export declare function reportFastModeUnavailable(model?: string): void;