cclaw-cli 0.26.0 → 0.28.0

package/dist/eval/agents/with-tools.js

@@ -1,11 +1,11 @@
 /**
- * Tier B with-tools agent.
+ * Multi-turn with-tools agent (agent mode, reused by workflow mode).
  *
  * Multi-turn loop with OpenAI-style function-calling over a set of
  * sandbox-confined tools. The AUT is given:
  *
- *  - System prompt = stage SKILL.md (same contract as Tier A so the
- *    single-shot baseline is comparable).
+ *  - System prompt = stage SKILL.md (same contract as the single-shot path
+ *    so the baseline is comparable).
  *  - User prompt = task description + a short "tools available" hint
  *    that names the sandbox root and the four built-in tools.
  *  - Tools = `read_file`, `write_file`, `glob`, `grep` (see
@@ -29,7 +29,7 @@
  * Artifact resolution: the final assistant content is the artifact. If
  * the model used `write_file` to stage the artifact at
  * `artifact.md` (or `artifact/<stage>.md`), we prefer that file — it
- * mirrors the Tier C workflow where writes are the deliverable. The
+ * mirrors workflow mode where writes are the deliverable. The
  * fallback is the terminal assistant message so prompts that don't
  * call write_file still produce something judgable.
  */
@@ -42,7 +42,7 @@ import { loadStageSkill } from "./single-shot.js";
 export class MaxTurnsExceededError extends Error {
     turns;
     constructor(turns) {
-        super(`Tier B agent exceeded the ${turns}-turn budget without a terminal stop.`);
+        super(`Agent loop exceeded the ${turns}-turn budget without a terminal stop.`);
         this.name = "MaxTurnsExceededError";
         this.turns = turns;
     }
@@ -62,10 +62,12 @@ export async function runWithTools(input) {
     const toolMap = toolsByName(tools);
     const toolsBody = toolsForRequest(tools);
     const sandboxFactory = input.createSandboxFn ?? createSandbox;
-    const sandbox = await sandboxFactory({
-        projectRoot,
-        ...(caseEntry.contextFiles ? { contextFiles: caseEntry.contextFiles } : {})
-    });
+    const externalSandbox = input.externalSandbox;
+    const sandbox = externalSandbox ??
+        (await sandboxFactory({
+            projectRoot,
+            ...(caseEntry.contextFiles ? { contextFiles: caseEntry.contextFiles } : {})
+        }));
     const toolUse = {
         turns: 0,
         calls: 0,
@@ -76,7 +78,7 @@ export async function runWithTools(input) {
     const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
     let lastModel = config.model;
     let totalAttempts = 0;
-    const userPrompt = buildUserPrompt(caseEntry, sandbox, tools);
+    const userPrompt = buildUserPrompt(caseEntry, sandbox, tools, input.promptPreamble);
     const messages = [
         { role: "system", content: systemPrompt },
         { role: "user", content: userPrompt }
@@ -150,7 +152,8 @@ export async function runWithTools(input) {
         throw new MaxTurnsExceededError(maxTurns);
     }
     finally {
-        await sandbox.dispose();
+        if (!externalSandbox)
+            await sandbox.dispose();
     }
 }
 function finalize(artifact, usage, model, attempts, started, toolUse, systemPrompt, userPrompt, config) {
@@ -196,16 +199,18 @@ function clampPositive(value, fallback) {
         return fallback;
     return Math.floor(value);
 }
-function buildUserPrompt(caseEntry, sandbox, tools) {
+function buildUserPrompt(caseEntry, sandbox, tools, preamble) {
     const toolList = tools.map((t) => `- ${t.descriptor.name}: ${t.descriptor.description}`);
     const files = caseEntry.contextFiles ?? [];
     const contextLines = files.length > 0
         ? files.map((f) => `- ${f}`).join("\n")
         : "(no files seeded)";
-    const lines = [
-        `Stage: ${caseEntry.stage}`,
-        `Case id: ${caseEntry.id}`,
-        ``,
+    const lines = [];
+    if (preamble && preamble.trim().length > 0) {
+        lines.push(preamble.trim(), ``);
+    }
+    lines.push(`Stage: ${caseEntry.stage}`, `Case id: ${caseEntry.id}`, ``);
+    const rest = [
         `Sandbox root: ${sandbox.root}`,
         `You may call the following tools to read or modify files inside the sandbox.`,
         `All paths are relative to the sandbox root.`,
@@ -225,6 +230,7 @@ function buildUserPrompt(caseEntry, sandbox, tools) {
         `You may optionally write the artifact to \`artifact.md\` in the sandbox; ` +
             `if you do, the last written \`artifact.md\` is preferred over the chat reply.`
     ];
+    lines.push(...rest);
     return lines.join("\n");
 }
 async function resolveArtifact(sandbox, fallback) {

package/dist/eval/agents/workflow.d.ts

@@ -0,0 +1,31 @@
+import type { EvalLlmClient } from "../llm-client.js";
+import { createSandbox } from "../sandbox.js";
+import type { SandboxTool } from "../tools/index.js";
+import type { ResolvedEvalConfig, WorkflowCase, WorkflowStageName, WorkflowStageResult } from "../types.js";
+export interface WorkflowInput {
+    workflow: WorkflowCase;
+    config: Pick<ResolvedEvalConfig, "model" | "agentTemperature" | "timeoutMs" | "tokenPricing" | "toolMaxTurns" | "toolMaxArgumentsBytes" | "toolMaxResultBytes" | "workflowMaxTotalTurns">;
+    projectRoot: string;
+    client: EvalLlmClient;
+    tools?: SandboxTool[];
+    /** Override for the SKILL.md loader (test hook). */
+    loadSkill?: (stage: WorkflowStageName) => Promise<string>;
+    /** Override for the sandbox factory (test hook). */
+    createSandboxFn?: typeof createSandbox;
+    /**
+     * Optional per-stage lifecycle hooks. The runner uses these to emit
+     * progress events to stderr so workflow-mode runs surface real-time
+     * status rather than going silent for minutes.
+     */
+    onStageStart?: (stage: WorkflowStageName) => void;
+    onStageEnd?: (stage: WorkflowStageName, result: WorkflowStageResult) => void;
+}
+export interface WorkflowOutput {
+    caseId: string;
+    stages: WorkflowStageResult[];
+    /** Map from stage name to produced artifact (also persisted in sandbox). */
+    artifacts: Map<WorkflowStageName, string>;
+    totalUsageUsd: number;
+    totalDurationMs: number;
+}
+export declare function runWorkflow(input: WorkflowInput): Promise<WorkflowOutput>;

package/dist/eval/agents/workflow.js

@@ -0,0 +1,135 @@
+/**
+ * Workflow-mode agent.
+ *
+ * Runs the with-tools loop once per stage in a workflow case,
+ * sharing a single sandbox across stages so every new stage can read
+ * the earlier artifacts the model produced. The shape of the run is:
+ *
+ *   1. Create one sandbox seeded with `contextFiles`.
+ *   2. For each stage in `workflow.stages`:
+ *      a. Delete any leftover `artifact.md` so the resolver doesn't
+ *         accidentally pick the previous stage's output.
+ *      b. Invoke `runWithTools({ externalSandbox: sandbox, promptPreamble })`.
+ *         The preamble tells the model which stage it is on and lists the
+ *         `stages/*.md` files available for reading.
+ *      c. Persist the returned artifact to `stages/<stage>.md` inside the
+ *         sandbox (deterministic, regardless of whether the model wrote
+ *         `artifact.md` itself).
+ *      d. Record `WorkflowStageResult` with usage, duration, and tool use.
+ *   3. Dispose the sandbox in a `finally` so temp directories never leak.
+ *
+ * Errors bubble up from `runWithTools`:
+ *   - `MaxTurnsExceededError` stops the workflow at the current stage.
+ *   - `DailyCostCapExceededError` (surfaced by the cost-guard wrapper in
+ *     the runner) aborts immediately.
+ *   - Generic `EvalLlmError` subclasses propagate as-is so the runner can
+ *     record a workflow-level verifier failure.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createSandbox } from "../sandbox.js";
+import { loadStageSkill } from "./single-shot.js";
+import { runWithTools } from "./with-tools.js";
+const STAGES_SUBDIR = "stages";
+const ARTIFACT_CANDIDATES = ["artifact.md", "artifact.txt", "ARTIFACT.md"];
+export async function runWorkflow(input) {
+    const { workflow, config, projectRoot, client } = input;
+    const sandboxFactory = input.createSandboxFn ?? createSandbox;
+    const sandbox = await sandboxFactory({
+        projectRoot,
+        ...(workflow.contextFiles ? { contextFiles: workflow.contextFiles } : {})
+    });
+    const stageResults = [];
+    const artifacts = new Map();
+    let totalUsageUsd = 0;
+    let totalDurationMs = 0;
+    try {
+        await fs.mkdir(await sandbox.resolve(STAGES_SUBDIR, { allowMissing: true }), { recursive: true });
+        for (const step of workflow.stages) {
+            input.onStageStart?.(step.name);
+            await clearArtifactFile(sandbox);
+            const priorStages = stageResults.map((r) => r.stage);
+            const preamble = buildStagePreamble(workflow, step.name, priorStages);
+            const caseEntry = {
+                id: `${workflow.id}/${step.name}`,
+                stage: step.name,
+                inputPrompt: step.inputPrompt,
+                ...(workflow.contextFiles ? { contextFiles: workflow.contextFiles } : {})
+            };
+            const result = await runWithTools({
+                caseEntry,
+                config,
+                projectRoot,
+                client,
+                ...(input.tools ? { tools: input.tools } : {}),
+                ...(input.loadSkill
+                    ? { loadSkill: input.loadSkill }
+                    : {
+                        loadSkill: (stage) => loadStageSkill(projectRoot, stage)
+                    }),
+                externalSandbox: sandbox,
+                promptPreamble: preamble
+            });
+            await persistStageArtifact(sandbox, step.name, result.artifact);
+            artifacts.set(step.name, result.artifact);
+            const stageResult = {
+                stage: step.name,
+                artifact: result.artifact,
+                durationMs: result.durationMs,
+                usageUsd: result.usageUsd,
+                toolUse: result.toolUse,
+                attempts: result.attempts,
+                model: result.model,
+                promptTokens: result.usage.promptTokens,
+                completionTokens: result.usage.completionTokens
+            };
+            stageResults.push(stageResult);
+            input.onStageEnd?.(step.name, stageResult);
+            totalUsageUsd += result.usageUsd;
+            totalDurationMs += result.durationMs;
+        }
+        return {
+            caseId: workflow.id,
+            stages: stageResults,
+            artifacts,
+            totalUsageUsd: Number(totalUsageUsd.toFixed(6)),
+            totalDurationMs
+        };
+    }
+    finally {
+        await sandbox.dispose();
+    }
+}
+async function clearArtifactFile(sandbox) {
+    for (const candidate of ARTIFACT_CANDIDATES) {
+        try {
+            const abs = await sandbox.resolve(candidate);
+            await fs.rm(abs, { force: true });
+        }
+        catch {
+            // candidate did not exist — resolve threw SandboxEscapeError for
+            // missing realpath; safe to ignore.
+        }
+    }
+}
+async function persistStageArtifact(sandbox, stage, artifact) {
+    const rel = `${STAGES_SUBDIR}/${stage}.md`;
+    const abs = await sandbox.resolve(rel, { allowMissing: true });
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, artifact.endsWith("\n") ? artifact : `${artifact}\n`, "utf8");
+}
+function buildStagePreamble(workflow, current, priorStages) {
+    const lines = [];
+    lines.push(`You are running stage "${current}" of the workflow "${workflow.id}".`);
+    if (workflow.description) {
+        lines.push(`Case description: ${workflow.description}`);
+    }
+    if (priorStages.length === 0) {
+        lines.push(`This is the first stage. Any context_files have been seeded into the sandbox root.`);
+    }
+    else {
+        lines.push(`Earlier stage artifacts are available via read_file:`, ...priorStages.map((name) => `  - ${STAGES_SUBDIR}/${name}.md`), `Read the prior artifacts before drafting your output so decisions and ` +
+            `ids carry through.`);
+    }
+    return lines.join("\n");
+}

package/dist/eval/baseline.d.ts

@@ -1,6 +1,30 @@
 import type { FlowStage } from "../types.js";
 import type { BaselineDelta, BaselineSnapshot, EvalReport } from "./types.js";
 export declare const BASELINE_SCHEMA_VERSION = 1;
+/**
+ * Thrown when a signed baseline's on-disk digest does not match the
+ * canonical encoding of its `{ schemaVersion, stage, cases }` block.
+ * Callers should treat this as a hard failure: the baseline was either
+ * hand-edited or corrupted and cannot be trusted for regression gating.
+ */
+export declare class BaselineSignatureError extends Error {
+    readonly file: string;
+    readonly expected: string;
+    readonly actual: string;
+    constructor(opts: {
+        file: string;
+        expected: string;
+        actual: string;
+    });
+}
+/**
+ * Produce a deterministic sha256 digest over the signable portion of a
+ * baseline. We intentionally exclude `generatedAt` and `cclawVersion`
+ * from the digest so that rebuilding the same baseline from identical
+ * case results on a new CLI version doesn't invalidate the signature —
+ * only changes to the observed pass/ok/score payloads do.
+ */
+export declare function computeBaselineDigest(snapshot: Pick<BaselineSnapshot, "schemaVersion" | "stage" | "cases">): string;
 export declare function loadBaseline(projectRoot: string, stage: FlowStage): Promise<BaselineSnapshot | null>;
 export declare function loadBaselinesByStage(projectRoot: string, stages: readonly FlowStage[]): Promise<Map<FlowStage, BaselineSnapshot>>;
 export declare function buildBaselineForStage(stage: FlowStage, report: EvalReport): BaselineSnapshot;

package/dist/eval/baseline.js

@@ -14,15 +14,67 @@
  * Writes are gated behind an explicit `--update-baseline --confirm` pair at
  * the CLI layer so accidental resets do not slip into PRs.
  */
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { EVALS_ROOT, CCLAW_VERSION } from "../constants.js";
 import { exists } from "../fs-utils.js";
 import { FLOW_STAGES } from "../types.js";
 export const BASELINE_SCHEMA_VERSION = 1;
+/**
+ * Thrown when a signed baseline's on-disk digest does not match the
+ * canonical encoding of its `{ schemaVersion, stage, cases }` block.
+ * Callers should treat this as a hard failure: the baseline was either
+ * hand-edited or corrupted and cannot be trusted for regression gating.
+ */
+export class BaselineSignatureError extends Error {
+    file;
+    expected;
+    actual;
+    constructor(opts) {
+        super(`Baseline signature mismatch at ${opts.file}: expected ${opts.expected}, got ${opts.actual}. ` +
+            `The file was modified outside of \`cclaw eval --update-baseline\`. ` +
+            `Re-run with --update-baseline --confirm to re-sign a known-good snapshot.`);
+        this.name = "BaselineSignatureError";
+        this.file = opts.file;
+        this.expected = opts.expected;
+        this.actual = opts.actual;
+    }
+}
 function baselinePath(projectRoot, stage) {
     return path.join(projectRoot, EVALS_ROOT, "baselines", `${stage}.json`);
 }
+/**
+ * Produce a deterministic sha256 digest over the signable portion of a
+ * baseline. We intentionally exclude `generatedAt` and `cclawVersion`
+ * from the digest so that rebuilding the same baseline from identical
+ * case results on a new CLI version doesn't invalidate the signature —
+ * only changes to the observed pass/ok/score payloads do.
+ */
+export function computeBaselineDigest(snapshot) {
+    const canonical = canonicalJson({
+        schemaVersion: snapshot.schemaVersion,
+        stage: snapshot.stage,
+        cases: snapshot.cases
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/**
+ * JSON.stringify with object keys sorted recursively so the digest is
+ * stable across filesystem / serializer variations.
+ */
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => canonicalJson(v)).join(",")}]`;
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(record[k])}`);
+    return `{${parts.join(",")}}`;
+}
 export async function loadBaseline(projectRoot, stage) {
     const filePath = baselinePath(projectRoot, stage);
     if (!(await exists(filePath)))
@@ -38,6 +90,20 @@ export async function loadBaseline(projectRoot, stage) {
     if (!isBaseline(parsed, stage)) {
         throw new Error(`Invalid baseline at ${filePath}: shape mismatch (expected schemaVersion=${BASELINE_SCHEMA_VERSION}, stage=${stage})`);
     }
+    const signature = parsed.signature;
+    if (signature) {
+        if (signature.algorithm !== "sha256") {
+            throw new Error(`Invalid baseline at ${filePath}: unsupported signature algorithm "${signature.algorithm}".`);
+        }
+        const actual = computeBaselineDigest(parsed);
+        if (actual !== signature.digest) {
+            throw new BaselineSignatureError({
+                file: filePath,
+                expected: signature.digest,
+                actual
+            });
+        }
+    }
     return parsed;
 }
 function isBaseline(value, stage) {
@@ -80,13 +146,20 @@ export function buildBaselineForStage(stage, report) {
     for (const c of stageCases) {
         cases[c.caseId] = entryFromResult(c);
     }
-    return {
+    const now = new Date().toISOString();
+    const unsigned = {
         schemaVersion: BASELINE_SCHEMA_VERSION,
         stage,
-        generatedAt: new Date().toISOString(),
+        generatedAt: now,
         cclawVersion: CCLAW_VERSION,
         cases
     };
+    unsigned.signature = {
+        algorithm: "sha256",
+        digest: computeBaselineDigest(unsigned),
+        signedAt: now
+    };
+    return unsigned;
 }
 export async function writeBaselinesFromReport(projectRoot, report) {
     const written = [];

package/dist/eval/config-loader.js

@@ -3,7 +3,8 @@ import path from "node:path";
 import { parse } from "yaml";
 import { EVALS_CONFIG_PATH } from "../constants.js";
 import { exists } from "../fs-utils.js";
-import { EVAL_TIERS } from "./types.js";
+import { EVAL_MODES } from "./types.js";
+import { parseModeInput } from "./mode.js";
 /**
  * Default eval config. Optimized for the z.ai OpenAI-compatible coding endpoint
  * with GLM 5.1 per the roadmap locked decisions (D-EVAL-01..05). Any field can
@@ -14,7 +15,7 @@ export const DEFAULT_EVAL_CONFIG = {
     provider: "zai",
     baseUrl: "https://api.z.ai/api/coding/paas/v4",
     model: "glm-5.1",
-    defaultTier: "A",
+    defaultMode: "fixture",
     regression: {
         failIfDeltaBelow: -0.15,
         failIfCriticalBelow: 3.0
@@ -25,7 +26,6 @@ export const DEFAULT_EVAL_CONFIG = {
     judgeTemperature: 0,
     agentTemperature: 0.2
 };
-const EVAL_TIER_SET = new Set(EVAL_TIERS);
 const NUMERIC_ENVS = new Set([
     "CCLAW_EVAL_DAILY_USD_CAP",
     "CCLAW_EVAL_TIMEOUT_MS",
@@ -35,11 +35,12 @@ const NUMERIC_ENVS = new Set([
     "CCLAW_EVAL_AGENT_TEMPERATURE",
     "CCLAW_EVAL_TOOL_MAX_TURNS",
     "CCLAW_EVAL_TOOL_MAX_ARG_BYTES",
-    "CCLAW_EVAL_TOOL_MAX_RESULT_BYTES"
+    "CCLAW_EVAL_TOOL_MAX_RESULT_BYTES",
+    "CCLAW_EVAL_WORKFLOW_MAX_TOTAL_TURNS"
 ]);
 function evalConfigError(configFilePath, reason) {
     return new Error(`Invalid cclaw eval config at ${configFilePath}: ${reason}\n` +
-        `Supported tiers: ${EVAL_TIERS.join(", ")}\n` +
+        `Supported modes: ${EVAL_MODES.join(", ")} (legacy tier values A|B|C also accepted).\n` +
         `See docs/evals.md for the full schema. After fixing, run: cclaw eval --dry-run`);
 }
 function isRecord(value) {
@@ -52,12 +53,11 @@ function parseNumericEnv(name, raw) {
     }
     return value;
 }
-function parseTierEnv(raw) {
-    const trimmed = raw.trim().toUpperCase();
-    if (!EVAL_TIER_SET.has(trimmed)) {
-        throw new Error(`Environment variable CCLAW_EVAL_TIER must be one of ${EVAL_TIERS.join("/")}, got: ${raw}`);
-    }
-    return trimmed;
+function parseModeEnv(raw, envName) {
+    return parseModeInput(envName === "CCLAW_EVAL_TIER" ? raw.toUpperCase() : raw, {
+        source: "env",
+        raw: `${envName}=${raw}`
+    });
 }
 function validateFileConfig(raw, configFilePath) {
     if (raw === undefined || raw === null)
@@ -78,11 +78,33 @@ function validateFileConfig(raw, configFilePath) {
     assignString("baseUrl", raw.baseUrl);
     assignString("model", raw.model);
     assignString("judgeModel", raw.judgeModel);
-    if (raw.defaultTier !== undefined) {
-        if (typeof raw.defaultTier !== "string" || !EVAL_TIER_SET.has(raw.defaultTier)) {
-            throw evalConfigError(configFilePath, `"defaultTier" must be one of: ${EVAL_TIERS.join(", ")}`);
+    if (raw.defaultMode !== undefined) {
+        if (typeof raw.defaultMode !== "string") {
+            throw evalConfigError(configFilePath, `"defaultMode" must be one of: ${EVAL_MODES.join(", ")}`);
+        }
+        try {
+            out.defaultMode = parseModeInput(raw.defaultMode, {
+                source: "config",
+                raw: `defaultMode: ${raw.defaultMode}`
+            });
+        }
+        catch (err) {
+            throw evalConfigError(configFilePath, err instanceof Error ? err.message : String(err));
+        }
+    }
+    else if (raw.defaultTier !== undefined) {
+        if (typeof raw.defaultTier !== "string") {
+            throw evalConfigError(configFilePath, `"defaultTier" must be a string (legacy; prefer "defaultMode")`);
+        }
+        try {
+            out.defaultMode = parseModeInput(raw.defaultTier, {
+                source: "config",
+                raw: `defaultTier: ${raw.defaultTier}`
+            });
+        }
+        catch (err) {
+            throw evalConfigError(configFilePath, err instanceof Error ? err.message : String(err));
         }
-        out.defaultTier = raw.defaultTier;
     }
     if (raw.dailyUsdCap !== undefined) {
         if (typeof raw.dailyUsdCap !== "number" || raw.dailyUsdCap < 0) {
@@ -166,6 +188,7 @@ function validateFileConfig(raw, configFilePath) {
     assignPositiveInt("toolMaxTurns", raw.toolMaxTurns, "toolMaxTurns");
     assignPositiveInt("toolMaxArgumentsBytes", raw.toolMaxArgumentsBytes, "toolMaxArgumentsBytes");
     assignPositiveInt("toolMaxResultBytes", raw.toolMaxResultBytes, "toolMaxResultBytes");
+    assignPositiveInt("workflowMaxTotalTurns", raw.workflowMaxTotalTurns, "workflowMaxTotalTurns");
     if (raw.regression !== undefined) {
         if (!isRecord(raw.regression)) {
             throw evalConfigError(configFilePath, `"regression" must be a mapping`);
@@ -192,6 +215,7 @@ function validateFileConfig(raw, configFilePath) {
         "baseUrl",
         "model",
         "judgeModel",
+        "defaultMode",
         "defaultTier",
         "dailyUsdCap",
         "timeoutMs",
@@ -203,7 +227,8 @@ function validateFileConfig(raw, configFilePath) {
         "tokenPricing",
         "toolMaxTurns",
         "toolMaxArgumentsBytes",
-        "toolMaxResultBytes"
+        "toolMaxResultBytes",
+        "workflowMaxTotalTurns"
     ]);
     const unknown = Object.keys(raw).filter((key) => !knownKeys.has(key));
     if (unknown.length > 0) {
@@ -263,11 +288,18 @@ function applyEnvOverrides(base, env) {
         patched.provider = provider;
         overridden = true;
     }
-    const tier = read("CCLAW_EVAL_TIER");
-    if (tier) {
-        patched.defaultTier = parseTierEnv(tier);
+    const modeEnv = read("CCLAW_EVAL_MODE");
+    if (modeEnv) {
+        patched.defaultMode = parseModeEnv(modeEnv, "CCLAW_EVAL_MODE");
         overridden = true;
     }
+    else {
+        const legacyTier = read("CCLAW_EVAL_TIER");
+        if (legacyTier) {
+            patched.defaultMode = parseModeEnv(legacyTier, "CCLAW_EVAL_TIER");
+            overridden = true;
+        }
+    }
     const cap = read("CCLAW_EVAL_DAILY_USD_CAP");
     if (cap) {
         patched.dailyUsdCap = parseNumericEnv("CCLAW_EVAL_DAILY_USD_CAP", cap);
@@ -326,6 +358,7 @@ function applyEnvOverrides(base, env) {
         void label;
     };
     readPositiveInt("CCLAW_EVAL_TOOL_MAX_TURNS", "toolMaxTurns", "toolMaxTurns");
+    readPositiveInt("CCLAW_EVAL_WORKFLOW_MAX_TOTAL_TURNS", "workflowMaxTotalTurns", "workflowMaxTotalTurns");
     readPositiveInt("CCLAW_EVAL_TOOL_MAX_ARG_BYTES", "toolMaxArgumentsBytes", "toolMaxArgumentsBytes");
     readPositiveInt("CCLAW_EVAL_TOOL_MAX_RESULT_BYTES", "toolMaxResultBytes", "toolMaxResultBytes");
     const apiKey = read("CCLAW_EVAL_API_KEY");

package/dist/eval/cost-guard.d.ts

@@ -35,6 +35,22 @@ export declare class DailyCostCapExceededError extends Error {
         currentUsd: number;
     });
 }
+/**
+ * Per-run cost cap — enforced in-memory, no ledger file. Complements the
+ * daily cap so a single long workflow run can't blow the whole day's
+ * budget even if the daily cap is generous. Opt-in via
+ * `--max-cost-usd=<n>` on the CLI or `CCLAW_EVAL_MAX_COST_USD`.
+ */
+export declare class RunCostCapExceededError extends Error {
+    readonly capUsd: number;
+    readonly projectedUsd: number;
+    readonly currentUsd: number;
+    constructor(opts: {
+        capUsd: number;
+        projectedUsd: number;
+        currentUsd: number;
+    });
+}
 declare function utcDate(now?: Date): string;
 declare function pricingFor(model: string, config: Pick<ResolvedEvalConfig, "tokenPricing">): TokenPricing;
 /**
@@ -67,6 +83,12 @@ export interface CreateCostGuardOptions {
     now?: () => Date;
     /** Override the default filesystem root for the ledger. */
     ledgerPath?: string;
+    /**
+     * Per-run (in-memory) USD cap. Independent from the persisted daily
+     * cap so a single `cclaw eval` invocation can be budgeted without
+     * touching the shared nightly ledger. Undefined = unlimited.
+     */
+    runCapUsd?: number;
 }
 export declare function createCostGuard(projectRoot: string, config: Pick<ResolvedEvalConfig, "dailyUsdCap" | "tokenPricing">, options?: CreateCostGuardOptions): CostGuard;
 /** Exposed for tests. */

package/dist/eval/cost-guard.js

@@ -52,6 +52,28 @@ export class DailyCostCapExceededError extends Error {
         this.currentUsd = opts.currentUsd;
     }
 }
+/**
+ * Per-run cost cap — enforced in-memory, no ledger file. Complements the
+ * daily cap so a single long workflow run can't blow the whole day's
+ * budget even if the daily cap is generous. Opt-in via
+ * `--max-cost-usd=<n>` on the CLI or `CCLAW_EVAL_MAX_COST_USD`.
+ */
+export class RunCostCapExceededError extends Error {
+    capUsd;
+    projectedUsd;
+    currentUsd;
+    constructor(opts) {
+        super(`Run cost cap would be exceeded: ` +
+            `current=$${opts.currentUsd.toFixed(4)}, ` +
+            `projected=$${opts.projectedUsd.toFixed(4)}, ` +
+            `cap=$${opts.capUsd.toFixed(4)}. ` +
+            `Raise --max-cost-usd or drop it to run uncapped.`);
+        this.name = "RunCostCapExceededError";
+        this.capUsd = opts.capUsd;
+        this.projectedUsd = opts.projectedUsd;
+        this.currentUsd = opts.currentUsd;
+    }
+}
 function utcDate(now = new Date()) {
     return now.toISOString().slice(0, 10);
 }
@@ -109,11 +131,25 @@ export function createCostGuard(projectRoot, config, options = {}) {
     const now = options.now ?? (() => new Date());
     const currentDate = () => utcDate(now());
     const file = () => options.ledgerPath ?? ledgerPath(projectRoot, currentDate());
+    const runCap = options.runCapUsd;
+    let runTotalUsd = 0;
     return {
         async commit(model, usage) {
             const usd = computeUsageUsd(model, usage, config);
-            if (config.dailyUsdCap === undefined)
+            if (runCap !== undefined) {
+                const projected = Number((runTotalUsd + usd).toFixed(6));
+                if (projected > runCap) {
+                    throw new RunCostCapExceededError({
+                        capUsd: runCap,
+                        projectedUsd: projected,
+                        currentUsd: runTotalUsd
+                    });
+                }
+            }
+            if (config.dailyUsdCap === undefined) {
+                runTotalUsd = Number((runTotalUsd + usd).toFixed(6));
                 return usd;
+            }
             const date = currentDate();
             const target = file();
             const ledger = await readLedger(target, date);
@@ -133,6 +169,7 @@ export function createCostGuard(projectRoot, config, options = {}) {
             byModel.usd = Number((byModel.usd + usd).toFixed(6));
             ledger.byModel[model] = byModel;
             await writeLedger(target, ledger);
+            runTotalUsd = Number((runTotalUsd + usd).toFixed(6));
             return usd;
         },
         async snapshot() {