@robmclarty/volley 0.10.1 → 0.11.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { accessSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { cac } from "cac";
 import { serve_acp, to_session_updates, workspace_tools } from "fascicle/acp";
@@ -101,6 +101,187 @@ function step_countdown(max_steps, check) {
 	};
 }
 //#endregion
+//#region src/builder/prepare_step.ts
+/** One hook that runs `hooks` in order, each on the request the one before it
+* made, and reports no change when none of them made one. */
+function compose_prepare_steps(hooks) {
+	return async ({ step_index, messages }) => {
+		let request = messages;
+		let changed = false;
+		for (const hook of hooks) {
+			const prepared = await hook({
+				step_index,
+				messages: request
+			});
+			if (prepared?.messages !== void 0) {
+				request = prepared.messages;
+				changed = true;
+			}
+		}
+		return changed ? { messages: request } : void 0;
+	};
+}
+//#endregion
+//#region src/builder/trim.ts
+/**
+* Trimming a long tool-loop session's history (#7). Every turn resends the
+* whole session, every earlier `read_file` result included, even for files the
+* builder has rewritten since, so a long local session's requests grow
+* linearly and each turn's latency grows with them: volley-41806476's input
+* went from 2.6k to 57k tokens over 50 steps, and its turns from 3 s to as
+* much as 120 s.
+*
+* Above a size the operator sets (`--builder-trim-history`), each turn's
+* request replaces the older tool results with one-line stubs: a read of a
+* file a later call wrote, edited, or read whole says so, and any other result
+* names its call and size. The last `TRIM_KEEP_TURNS` turns, every assistant
+* and user message, every failed call's result, and anything short stay as
+* they are. It goes in through fascicle's `prepare_step`, which reshapes only
+* what one turn sends, so the transcript stays as the model wrote it.
+*
+* A local runtime reuses the KV cache for the prefix a request shares with
+* the last one, and rewriting an earlier message breaks that prefix, so the
+* window is prefilled again. So the trim moves in coarse steps: it stubs
+* everything before a turn boundary, boundaries fall every
+* `TRIM_STRIDE_TURNS` turns, and the boundary moves on only when the trimmed
+* request has grown past the size again. Between moves each request starts
+* with the same bytes as the last, since a stub depends only on what came
+* before its boundary and never on the step. The trim keeps no state:
+* `trim_cutoff` works the boundary out again from the transcript each turn.
+*/
+/** A rough token count per character: the hook sees no token counts, so a
+* request's size is estimated from its text. */
+const CHARS_PER_TOKEN = 4;
+/** What a message costs beyond its text: its role and framing. */
+const MESSAGE_OVERHEAD_TOKENS = 8;
+/** The calls that change a file, whose success makes an earlier read of it
+* stale. Both volley's tools and fascicle's ACP tools use these names and a
+* `path` input. */
+const FILE_WRITERS = /* @__PURE__ */ new Set(["write_file", "edit_file"]);
+const COMMAND_TOOLS = /* @__PURE__ */ new Set(["bash", "run_command"]);
+function message_chars(message) {
+	if (typeof message.content === "string") return message.content.length;
+	let chars = 0;
+	for (const part of message.content) if (part.type === "text" || part.type === "reasoning") chars += part.text.length;
+	else if (part.type === "tool_call") chars += part.name.length + (JSON.stringify(part.input) ?? "").length;
+	return chars;
+}
+/** A request's size in tokens, estimated from its characters. */
+function estimate_tokens(messages) {
+	let tokens = 0;
+	for (const message of messages) tokens += Math.ceil(message_chars(message) / CHARS_PER_TOKEN) + MESSAGE_OVERHEAD_TOKENS;
+	return tokens;
+}
+function call_input(input) {
+	if (typeof input !== "object" || input === null) return {
+		path: null,
+		whole: true
+	};
+	const fields = input;
+	return {
+		path: typeof fields["path"] === "string" ? posix.normalize(fields["path"]) : null,
+		whole: fields["offset"] === void 0 && fields["limit"] === void 0
+	};
+}
+/** Each tool call's input, by call id, from the assistant messages in
+* `messages`. */
+function call_inputs(messages) {
+	const inputs = /* @__PURE__ */ new Map();
+	for (const message of messages) {
+		if (message.role !== "assistant" || typeof message.content === "string") continue;
+		for (const part of message.content) if (part.type === "tool_call") inputs.set(part.id, call_input(part.input));
+	}
+	return inputs;
+}
+/** Whether this result is one whose call changed its file or read it whole. */
+function supersession_of(message, input) {
+	if (input === void 0 || input.path === null || message.is_error === true) return null;
+	if (FILE_WRITERS.has(message.name)) return message.content.startsWith("error:") ? null : {
+		tool: message.name,
+		changed: true
+	};
+	if (message.name === "read_file" && input.whole) return {
+		tool: "read_file",
+		changed: false
+	};
+	return null;
+}
+function exit_code_of(content) {
+	try {
+		const parsed = JSON.parse(content);
+		if (typeof parsed === "object" && parsed !== null) {
+			const code = parsed["exit_code"];
+			if (typeof code === "number") return code;
+		}
+	} catch {}
+	return null;
+}
+function stub(message, input, later) {
+	const size = `${String(message.content.length)} chars`;
+	if (later !== void 0 && input !== void 0 && input.path !== null) return later.changed ? `[volley] read_file ${input.path} (${size}) elided: a later ${later.tool} changed this file. Read it again for its current content.` : `[volley] read_file ${input.path} (${size}) elided: it was read again later in this session.`;
+	const exit_code = COMMAND_TOOLS.has(message.name) ? exit_code_of(message.content) : null;
+	const detail = exit_code === null ? size : `${size}, exit ${String(exit_code)}`;
+	return `[volley] ${message.name} output (${detail}) elided from an earlier turn. Run it again if you need it.`;
+}
+/**
+* The request with every tool result before `cutoff` that is long enough to
+* matter and didn't fail replaced by a stub. Every message keeps its place,
+* role, id, and name. A stub reads only what comes before `cutoff`, so the
+* same transcript prefix always gives the same bytes.
+*/
+function trim_view(messages, cutoff) {
+	const window = messages.slice(0, cutoff);
+	const inputs = call_inputs(window);
+	const next_on_path = /* @__PURE__ */ new Map();
+	const later_for = /* @__PURE__ */ new Map();
+	for (let i = window.length - 1; i >= 0; i -= 1) {
+		const message = window[i];
+		if (message?.role !== "tool") continue;
+		const input = inputs.get(message.tool_call_id);
+		const path = input?.path ?? null;
+		if (path === null) continue;
+		if (message.name === "read_file") {
+			const later = next_on_path.get(path);
+			if (later !== void 0) later_for.set(i, later);
+		}
+		const supersedes = supersession_of(message, input);
+		if (supersedes !== null) next_on_path.set(path, supersedes);
+	}
+	return messages.map((message, i) => {
+		if (i >= cutoff || message.role !== "tool" || message.is_error === true) return message;
+		if (message.content.length <= 200) return message;
+		return {
+			...message,
+			content: stub(message, inputs.get(message.tool_call_id), later_for.get(i))
+		};
+	});
+}
+/**
+* Where to cut this turn's request, as a message index, or null to send it
+* whole. Boundaries are the starts of turns `TRIM_STRIDE_TURNS`,
+* `2 * TRIM_STRIDE_TURNS`, and so on, short of the last `TRIM_KEEP_TURNS`.
+* The cut moves to the next boundary only while the request, trimmed at the
+* last one, is still over `threshold`. A trimmed request only grows as the
+* session goes on, so a boundary once taken is kept.
+*/
+function trim_cutoff(messages, threshold) {
+	const turn_starts = messages.flatMap((message, i) => message.role === "assistant" ? [i] : []);
+	let cutoff = null;
+	for (let turn = 8; turn <= turn_starts.length - 6; turn += 8) {
+		if (estimate_tokens(cutoff === null ? messages : trim_view(messages, cutoff)) <= threshold) break;
+		cutoff = turn_starts[turn] ?? null;
+	}
+	return cutoff;
+}
+/** The `prepare_step` hook that trims a request estimated above `threshold`
+* tokens. */
+function step_trim(threshold) {
+	return ({ messages }) => {
+		const cutoff = trim_cutoff(messages, threshold);
+		return cutoff === null ? void 0 : { messages: trim_view(messages, cutoff) };
+	};
+}
+//#endregion
 //#region src/types.ts
 function config_error(message) {
 	return Object.assign(new Error(message), { kind: "config_error" });
@@ -310,6 +491,7 @@ function create_volley_engine(options) {
 		default_cwd: options.workspace,
 		setting_sources: ["project", "local"],
 		auth_mode,
+		omit_env: SEAT_CREDENTIAL_VARS,
 		...binary !== void 0 && binary.length > 0 ? { binary } : {},
 		...auth_mode === "api_key" && env[ANTHROPIC_KEY_VAR] !== void 0 ? { api_key: env[ANTHROPIC_KEY_VAR] } : {}
 	} };
@@ -1168,6 +1350,60 @@ function rejected_check(runner) {
 	};
 }
 //#endregion
+//#region src/claude_cli_permissions.ts
+/** Whether a seat this run drives runs on the Claude CLI. A critique has no
+* builder, whatever its provider resolved to. */
+function uses_claude_cli(config) {
+	return config.mode !== "critique" && config.builder_provider === "claude_cli" || config.critic_provider === "claude_cli";
+}
+const BUILDER_ALLOWED_TOOLS = [
+	"Read(/**)",
+	"Edit(/**)",
+	"Bash",
+	"WebFetch"
+];
+const CRITIC_ALLOWED_TOOLS = ["Read(/**)"];
+const CRITIC_DISALLOWED_TOOLS = "Write,Edit,MultiEdit,NotebookEdit,Bash";
+const PERMISSION_BLOCKS = { permissions: {
+	blockWritesOutsideWorkingDirectories: true,
+	blockReadsOutsideWorkingDirectories: true
+} };
+/** The CLI flags that turn on `PERMISSION_BLOCKS`. */
+function settings_args() {
+	return ["--settings", JSON.stringify(PERMISSION_BLOCKS)];
+}
+const MIN_CLAUDE_WRITE_BLOCK = [
+	2,
+	1,
+	314
+];
+const MIN_CLAUDE_READ_BLOCK = [
+	2,
+	1,
+	257
+];
+/** The version `claude --version` printed (`2.1.316 (Claude Code)`), or null
+* when it printed something else. */
+function parse_claude_version(stdout) {
+	const match = /^\s*(\d+)\.(\d+)\.(\d+)\b/.exec(stdout);
+	if (match === null) return null;
+	return [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	];
+}
+function version_below(version, min) {
+	const [major, minor, patch] = version;
+	const [min_major, min_minor, min_patch] = min;
+	if (major !== min_major) return major < min_major;
+	if (minor !== min_minor) return minor < min_minor;
+	return patch < min_patch;
+}
+function format_version(version) {
+	return version.join(".");
+}
+//#endregion
 //#region src/cost.ts
 /**
 * Cost and usage accumulation. All pricing knowledge lives in
@@ -1223,14 +1459,77 @@ function phase_record(result, model, duration_ms = result.timing?.duration_ms ??
 		...rate !== void 0 ? { throughput: rate } : {}
 	};
 }
+const NS_PER_MS = 1e6;
+function ns_field(payload, name) {
+	const value = payload[name];
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+/** A turn's prefill and decode times: Ollama's own durations when it reported
+* them (in ns), else the time to the first streamed chunk, else none. */
+function step_split(step) {
+	const reported = step.provider_reported?.["ollama"];
+	if (typeof reported === "object" && reported !== null) {
+		const ollama = reported;
+		const evaluated = ns_field(ollama, "eval_duration");
+		const prompt = ns_field(ollama, "prompt_eval_duration");
+		if (evaluated !== void 0 && prompt !== void 0) return {
+			prefill_ms: Math.round(prompt / NS_PER_MS),
+			decode_ms: Math.round(evaluated / NS_PER_MS),
+			timing_basis: "ollama_reported"
+		};
+		const total = ns_field(ollama, "total_duration");
+		const load = ns_field(ollama, "load_duration");
+		if (evaluated !== void 0 && total !== void 0 && load !== void 0 && total >= load + evaluated) return {
+			prefill_ms: Math.round((total - load - evaluated) / NS_PER_MS),
+			decode_ms: Math.round(evaluated / NS_PER_MS),
+			timing_basis: "ollama_derived"
+		};
+	}
+	const timing = step.timing;
+	if (timing?.first_chunk_ms !== void 0 && timing.whole_tool_call !== true) return {
+		prefill_ms: timing.first_chunk_ms,
+		decode_ms: Math.max(0, timing.duration_ms - timing.first_chunk_ms),
+		timing_basis: "first_chunk"
+	};
+	return { timing_basis: "none" };
+}
+/** How much a tool call's result put into the transcript: its output as the
+* loop serializes it, or the error text it fed back. */
+function output_chars(call) {
+	if (call.output === void 0) return call.error?.message.length ?? 0;
+	return typeof call.output === "string" ? call.output.length : (JSON.stringify(call.output) ?? "").length;
+}
+/** Each turn of a session as the archive records it, or undefined when the
+* result has none. */
+function step_records(result) {
+	if (result.steps.length === 0) return void 0;
+	return result.steps.map((step) => ({
+		index: step.index,
+		input_tokens: step.usage.input_tokens,
+		output_tokens: step.usage.output_tokens,
+		duration_ms: step.timing?.duration_ms ?? 0,
+		...step_split(step),
+		finish_reason: step.finish_reason,
+		...step.truncated === true ? { truncated: true } : {},
+		tool_calls: step.tool_calls.map((call) => ({
+			name: call.name,
+			output_chars: output_chars(call)
+		}))
+	}));
+}
 /** Fold one phase's result into the loop state. Unknown cost records `null`
-* for the phase and warns once per run — a run never fails over pricing. */
+* for the phase and warns once per run — a run never fails over pricing. The
+* builder's record also carries its session's turns. */
 function accumulate(state, role, result, model, duration_ms) {
 	const record = phase_record(result, model, duration_ms);
+	const steps = role === "builder" ? step_records(result) : void 0;
 	const cost = record.cost_usd ?? 0;
 	return {
 		...state,
-		[role]: record,
+		[role]: steps !== void 0 ? {
+			...record,
+			steps
+		} : record,
 		total_usage: add_usage(state.total_usage, result.usage),
 		total_cost_usd: state.total_cost_usd + cost,
 		iteration_cost_usd: state.iteration_cost_usd + cost,
@@ -1478,6 +1777,7 @@ function write_resolved_config(config, env = process.env) {
 		builder_max_steps: config.builder_max_steps,
 		builder_max_tool_calls: config.builder_max_tool_calls,
 		builder_max_output_tokens: config.builder_max_output_tokens,
+		builder_trim_history: config.builder_trim_history,
 		critic_model: config.critic_model,
 		critic_provider: config.critic_provider,
 		critic_url: config.critic_url,
@@ -1951,16 +2251,6 @@ async function with_worktree(options, body) {
 * complete agentic session in the workspace — Claude Code under `claude_cli`,
 * or a model driving volley's tools on any other provider, local or hosted.
 */
-const BUILDER_ALLOWED_TOOLS = [
-	"Read",
-	"Write",
-	"Edit",
-	"MultiEdit",
-	"Bash",
-	"Grep",
-	"Glob",
-	"WebFetch"
-];
 function compose_builder_system() {
 	return [
 		"You are the builder inside the volley harness: an autonomous agent",
@@ -2022,6 +2312,14 @@ function check_hint(config) {
 	if (config.check_resolved === "command") return `the check (\`${config.check}\`)`;
 	return "the project's tests";
 }
+/** The builder's `prepare_step`: the countdown, after the history trim when
+* `--builder-trim-history` turns it on, so the countdown's note still goes
+* last. */
+function builder_prepare_step(config) {
+	const countdown = step_countdown(config.builder_max_steps, check_hint(config));
+	if (config.builder_trim_history === null) return countdown;
+	return compose_prepare_steps([step_trim(config.builder_trim_history), countdown]);
+}
 /** Per-provider tool wiring for the builder, mirroring `critic_tool_options`.
 * The `claude_cli` builder is confined at the CLI permission layer (allowlist +
 * permission mode) and brings its own built-in tools — this arm is unchanged
@@ -2029,7 +2327,8 @@ function check_hint(config) {
 * builder, local or `openrouter`, brings none, so volley supplies its whole
 * workspace tool surface (or the set the caller injected in its place, with
 * the handler that answers its approvals), the per-call loop knobs, the step
-* countdown (`./builder/countdown.ts`), the output cap when one is set, and
+* countdown (`./builder/countdown.ts`) and the history trim when it's on
+* (`./builder/trim.ts`), the output cap when one is set, and
 * **no** schema (it produces a workspace, not a verdict); per-call values win
 * over engine defaults. */
 function builder_tool_options(deps) {
@@ -2037,7 +2336,11 @@ function builder_tool_options(deps) {
 	const bash_executor = deps.bash_executor ?? null;
 	if (config.builder_provider === "claude_cli") return { provider_options: { claude_cli: {
 		allowed_tools: [...BUILDER_ALLOWED_TOOLS],
-		extra_args: ["--permission-mode", config.builder_permission_mode]
+		extra_args: [
+			"--permission-mode",
+			config.builder_permission_mode,
+			...settings_args()
+		]
 	} } };
 	return {
 		tools: deps.tools === void 0 ? builder_tools(build_root(config.workspace, config.worktree), bash_executor !== null ? { bash_executor } : {}) : [...deps.tools],
@@ -2046,7 +2349,7 @@ function builder_tool_options(deps) {
 		tool_error_policy: "feed_back",
 		tool_call_repair_attempts: BUILDER_TOOL_CALL_REPAIR_ATTEMPTS,
 		max_tool_calls_per_step: config.builder_max_tool_calls,
-		prepare_step: step_countdown(config.builder_max_steps, check_hint(config)),
+		prepare_step: builder_prepare_step(config),
 		...config.builder_max_output_tokens !== null ? {
 			max_tokens: config.builder_max_output_tokens,
 			truncated_turn_policy: "continue"
@@ -2573,12 +2876,6 @@ function compose_critic_prompt(input) {
 * structured verdict. The
 * harness — not the critic — writes the run's `feedback.md` and `verdict`.
 */
-const CRITIC_ALLOWED_TOOLS = [
-	"Read",
-	"Grep",
-	"Glob"
-];
-const CRITIC_DISALLOWED_TOOLS = "Write,Edit,MultiEdit,NotebookEdit,Bash";
 /** A critic that holds tools isn't constrain-decoded, so nothing stops it
 * answering null for the feedback or the unmet list, as GLM did on approving.
 * Both fields allow null and read it as empty, so that answer is a verdict
@@ -2591,7 +2888,8 @@ const verdict_schema = z.object({
 	unmet_criteria: z.array(z.string()).nullable().transform((unmet) => unmet ?? []).describe("The specific acceptance criteria judged unmet, verbatim. Empty when approved.")
 });
 /** Read-only tool wiring per provider. The claude_cli critic is confined at
-* the CLI permission layer (allowlist + explicit disallow); every other critic,
+* the CLI permission layer (allowlist + explicit disallow, and the settings
+* blocks that keep its reads in the build root); every other critic,
 * local or `openrouter`, gets volley's own workspace-scoped read-only tools (or
 * the set the caller injected in their place) and no write path at all.
 *
@@ -2613,7 +2911,11 @@ const verdict_schema = z.object({
 function critic_tool_options(config, tools) {
 	if (config.critic_provider === "claude_cli") return { provider_options: { claude_cli: {
 		allowed_tools: [...CRITIC_ALLOWED_TOOLS],
-		extra_args: ["--disallowedTools", CRITIC_DISALLOWED_TOOLS]
+		extra_args: [
+			"--disallowedTools",
+			CRITIC_DISALLOWED_TOOLS,
+			...settings_args()
+		]
 	} } };
 	return {
 		tools: tools === void 0 ? read_only_tools(build_root(config.workspace, config.worktree)) : [...tools],
@@ -2979,7 +3281,8 @@ function phase_summary(record) {
 		...record.retry_cause_kind !== void 0 ? { retry_cause_kind: record.retry_cause_kind } : {},
 		...record.critic_degraded === true ? { critic_degraded: true } : {},
 		...record.degrade_cause !== void 0 ? { degrade_cause: record.degrade_cause } : {},
-		...record.throughput !== void 0 ? { throughput: record.throughput } : {}
+		...record.throughput !== void 0 ? { throughput: record.throughput } : {},
+		...record.steps !== void 0 ? { steps: record.steps } : {}
 	};
 }
 /** Archive one completed iteration: verdict files, check artifacts, and the
@@ -3236,6 +3539,7 @@ function load_resume_state(workspace, run_id, state_dir = null, options = {}) {
 		...recorded["builder_max_steps"] === void 0 ? {} : { builder_max_steps: Number(recorded["builder_max_steps"]) },
 		...recorded["builder_max_tool_calls"] === void 0 ? {} : { builder_max_tool_calls: Number(recorded["builder_max_tool_calls"]) },
 		...typeof recorded["builder_max_output_tokens"] === "number" ? { builder_max_output_tokens: recorded["builder_max_output_tokens"] } : {},
+		...typeof recorded["builder_trim_history"] === "number" ? { builder_trim_history: recorded["builder_trim_history"] } : {},
 		critic_model: String(recorded["critic_model"]),
 		critic_provider: recorded["critic_provider"] ?? "claude_cli",
 		...typeof recorded["critic_url"] === "string" ? { critic_url: recorded["critic_url"] } : {},
@@ -4165,6 +4469,7 @@ const CRITIQUE_REFUSED = [
 	["builder_max_steps", "--builder-max-steps"],
 	["builder_max_tool_calls", "--builder-max-tool-calls"],
 	["builder_max_output_tokens", "--builder-max-output-tokens"],
+	["builder_trim_history", "--builder-trim-history"],
 	["builder_permission_mode", "--builder-permission-mode"],
 	["allow_unsandboxed_builder", "--allow-unsandboxed-builder"],
 	["sandbox_image", "--sandbox-image"],
@@ -4204,6 +4509,12 @@ function builder_max_output_tokens_count(provider) {
 		fallback: CAPPED_BY_DEFAULT.includes(provider) ? DEFAULT_BUILDER_MAX_OUTPUT_TOKENS : null
 	};
 }
+/** The history trim's size: off unless something sets it. */
+const BUILDER_TRIM_HISTORY = {
+	flag: "--builder-trim-history",
+	env_var: "VOLLEY_BUILDER_TRIM_HISTORY",
+	fallback: null
+};
 /** A builder count's flag or config value wins over its env var, which wins
 * over the default, and either must be a positive integer. Local builder
 * only; ignored by the `claude_cli` arm. */
@@ -4338,6 +4649,7 @@ function resolve_config(raw, options = {}) {
 	const builder_max_steps = resolve_builder_count(raw.builder_max_steps, builder_env, BUILDER_MAX_STEPS);
 	const builder_max_tool_calls = resolve_builder_count(raw.builder_max_tool_calls, builder_env, BUILDER_MAX_TOOL_CALLS);
 	const builder_max_output_tokens = resolve_builder_count(raw.builder_max_output_tokens, builder_env, builder_max_output_tokens_count(builder_provider));
+	const builder_trim_history = resolve_builder_count(raw.builder_trim_history, builder_env, BUILDER_TRIM_HISTORY);
 	const critic_provider = raw.critic_provider ?? DEFAULT_CRITIC_PROVIDER;
 	if (!CRITIC_PROVIDERS.includes(critic_provider)) throw config_error(`--critic-provider must be one of ${CRITIC_PROVIDERS.join(", ")}; got: ${String(raw.critic_provider)}`);
 	const builder_url = resolve_seat_url("builder", raw.builder_url, builder_provider);
@@ -4376,6 +4688,7 @@ function resolve_config(raw, options = {}) {
 		builder_max_steps,
 		builder_max_tool_calls,
 		builder_max_output_tokens,
+		builder_trim_history,
 		allow_unsandboxed_builder,
 		critic_model: raw.critic_model ?? DEFAULT_CRITIC_MODEL,
 		critic_provider,
@@ -5471,6 +5784,10 @@ function render_matrix_table(rows) {
 * never requires Docker or a model server — so they never contribute an exit 5
 * on that path.
 *
+* A `claude_cli` seat gets one read of `claude --version`, which only ever
+* warns: below the version that enforces the settings blocks keeping the seat's
+* file tools in the build root, the dry run says what goes unenforced.
+*
 * A *local critic* additionally gets the critic-seat canary: one tiny $0
 * generate through the real critic tool wiring, run
 * whatever the builder provider is. A degradable failure warns and predicts
@@ -5492,6 +5809,7 @@ const REQUIRED_TOOLCHAIN = [
 /** A short cap on the endpoint probe so a wrong/unreachable host fails fast
 * rather than hanging the preflight before the loop even starts. */
 const ENDPOINT_PROBE_TIMEOUT_MS = 3e3;
+const CLAUDE_VERSION_TIMEOUT_MS = 1e4;
 /** Builders that drive their model through volley's own tool loop, local or
 * hosted, so the containment preflight applies. `claude_cli` never does. */
 function is_tool_loop_builder(provider) {
@@ -5580,6 +5898,33 @@ function worktree_creatable(workspace) {
 		detail: repo
 	};
 }
+/** What `claude --version` printed, from the binary the run will spawn, or
+* null when it didn't run. */
+function claude_version(env) {
+	const binary = env["VOLLEY_CLAUDE_BIN"];
+	const result = spawnSync(binary !== void 0 && binary.length > 0 ? binary : "claude", ["--version"], {
+		env: command_env(process.env),
+		encoding: "utf8",
+		timeout: CLAUDE_VERSION_TIMEOUT_MS
+	});
+	if (result.error !== void 0 || result.status !== 0) return null;
+	return result.stdout;
+}
+/** Name the Claude Code version a `claude_cli` seat runs on, and warn when it
+* is too old to enforce the blocks that keep the seat's file tools in the
+* build root. Never fails the dry run. */
+function report_claude_cli(config, renderer, env, probe) {
+	if (!uses_claude_cli(config)) return;
+	const printed = probe(env);
+	const version = printed === null ? null : parse_claude_version(printed);
+	if (version === null) {
+		renderer.warn("claude: could not read the Claude Code version (`claude --version`), so whether it keeps a claude_cli seat's file tools in the build root is unknown");
+		return;
+	}
+	renderer.info(`claude: ${format_version(version)}`);
+	if (version_below(version, MIN_CLAUDE_WRITE_BLOCK)) renderer.warn(`claude: Claude Code ${format_version(version)} ignores the block on writes outside the build root (needs ${format_version(MIN_CLAUDE_WRITE_BLOCK)}). Edit(/**) still keeps a builder's edits there under acceptEdits, but not under bypassPermissions.`);
+	if (version_below(version, MIN_CLAUDE_READ_BLOCK)) renderer.warn(`claude: Claude Code ${format_version(version)} ignores the block on reads outside the build root (needs ${format_version(MIN_CLAUDE_READ_BLOCK)}).`);
+}
 /** Reachability probe: any HTTP response (even a 404) proves the TCP connect
 * landed; a thrown error (connection refused, DNS failure, timeout) means the
 * endpoint is unreachable. */
@@ -5669,6 +6014,7 @@ async function preflight(config, renderer, env, probes = {}) {
 		renderer.info(`builder max steps: ${config.builder_max_steps}`);
 		renderer.info(`builder tool calls per turn: ${config.builder_max_tool_calls}`);
 		renderer.info(`builder output tokens per turn: ${config.builder_max_output_tokens ?? "the provider's limit"}`);
+		renderer.info(`builder history trim: ${config.builder_trim_history === null ? "off" : `above ${String(config.builder_trim_history)} estimated tokens`}`);
 	}
 	if (tool_loop_builder) {
 		const contained = detect_containment(env);
@@ -5679,6 +6025,7 @@ async function preflight(config, renderer, env, probes = {}) {
 	renderer.info(seat_line("critic", config.critic_model, config.critic_provider, config.critic_url, env));
 	report_worktree_fate(config, renderer);
 	report_gate_posture(config, renderer);
+	report_claude_cli(config, renderer, env, probes.claude_version ?? claude_version);
 	if (config.check_resolved === "checkride") {
 		if (!(probes.checkride_doctor ?? run_checkride_doctor)(config.workspace)) {
 			renderer.error("checkride doctor failed; fix the workspace check pipeline before running");
@@ -5776,8 +6123,19 @@ function make_renderer(config, run_id = config.run_id) {
 		}, "trajectory.jsonl")
 	});
 }
-function warn_api_key_meter(renderer) {
-	if (process.env["ANTHROPIC_API_KEY"] !== void 0) renderer.warn("ANTHROPIC_API_KEY is set: the claude CLI will bill this run against the API key, not a subscription. Know which meter you are on.");
+/** Only `VOLLEY_AUTH_MODE=api_key` hands the claude CLI a key: under `auto`
+* and `oauth` it gets none and stays on its own login, whatever is set. */
+function warn_api_key_meter(config, renderer, env = process.env) {
+	if (uses_claude_cli(config) && env["VOLLEY_AUTH_MODE"] === "api_key") renderer.warn("VOLLEY_AUTH_MODE=api_key: the claude CLI bills this run to ANTHROPIC_API_KEY at API rates, not to a subscription. Know which meter you are on.");
+}
+/** What to try when a `claude_cli` seat on the subscription login can't
+* authenticate, which is how every such seat fails once `claude -p` runs bare by
+* default (volley#9). Null for any other error. */
+function claude_login_hint(err, env = process.env) {
+	const auth_failure = [err, err?.cause].some((e) => error_kind(e) === "provider_auth_error" && e.provider === "claude_cli");
+	const auth_mode = env["VOLLEY_AUTH_MODE"] ?? "auto";
+	if (!auth_failure || auth_mode === "api_key") return null;
+	return `a claude_cli seat on the subscription login (VOLLEY_AUTH_MODE=${auth_mode}) could not authenticate. If \`claude auth login\` does not fix it, a Claude Code release that runs \`claude -p\` bare by default would explain it (volley#9): set VOLLEY_AUTH_MODE=api_key with ANTHROPIC_API_KEY to run on the API key meanwhile.`;
 }
 /** One loud warning when a tool-loop builder is about to run *uncontained* on
 * the host via the opt-out. Config resolution has already refused this
@@ -5800,7 +6158,7 @@ function with_critic_options(command, required = false) {
 function with_seat_options(command, required = false) {
 	const model_note = required ? " (required)" : "";
 	const provider_note = required ? "required" : "default: claude_cli";
-	return with_critic_options(command.option("--builder-model <model>", `Builder model${model_note}`).option("--builder-provider <name>", `claude_cli | ollama | lmstudio | openrouter (${provider_note})`).option("--builder-url <url>", "Builder's model server base URL, ollama, lmstudio, or openrouter only (default: VOLLEY_OLLAMA_URL / VOLLEY_LMSTUDIO_URL / VOLLEY_OPENROUTER_URL)").option("--builder-max-steps <n>", "Tool-loop builder step cap per iteration, any provider but claude_cli (default: 50)").option("--builder-max-tool-calls <n>", "Tool calls a tool-loop builder may make per turn, reads aside, any provider but claude_cli (default: 1)").option("--builder-max-output-tokens <n>", "Output tokens a tool-loop builder may generate per turn, reasoning included, any provider but claude_cli (default: 16384 on ollama and lmstudio, the provider's on openrouter)").option("--allow-unsandboxed-builder", "Permit a builder other than claude_cli to run without a sandbox (real host bash + write)"), required);
+	return with_critic_options(command.option("--builder-model <model>", `Builder model${model_note}`).option("--builder-provider <name>", `claude_cli | ollama | lmstudio | openrouter (${provider_note})`).option("--builder-url <url>", "Builder's model server base URL, ollama, lmstudio, or openrouter only (default: VOLLEY_OLLAMA_URL / VOLLEY_LMSTUDIO_URL / VOLLEY_OPENROUTER_URL)").option("--builder-max-steps <n>", "Tool-loop builder step cap per iteration, any provider but claude_cli (default: 50)").option("--builder-max-tool-calls <n>", "Tool calls a tool-loop builder may make per turn, reads aside, any provider but claude_cli (default: 1)").option("--builder-max-output-tokens <n>", "Output tokens a tool-loop builder may generate per turn, reasoning included, any provider but claude_cli (default: 16384 on ollama and lmstudio, the provider's on openrouter)").option("--builder-trim-history <tokens>", "Experimental: above this estimated request size, a tool-loop builder's turns send older tool results as one-line stubs, any provider but claude_cli (default: off)").option("--allow-unsandboxed-builder", "Permit a builder other than claude_cli to run without a sandbox (real host bash + write)"), required);
 }
 /** What a critique declares only so that it can refuse each by name, with
 * exit 5: cac would answer an undeclared one with a bare "Unknown option".
@@ -5812,6 +6170,7 @@ const CRITIQUE_REFUSED_OPTIONS = [
 	"--builder-max-steps <n>",
 	"--builder-max-tool-calls <n>",
 	"--builder-max-output-tokens <n>",
+	"--builder-trim-history <tokens>",
 	"--builder-permission-mode <mode>",
 	"--allow-unsandboxed-builder",
 	"--sandbox-image <tag>",
@@ -5836,6 +6195,7 @@ function merge_flags(base, flags) {
 		...flags.builderMaxSteps !== void 0 ? { builder_max_steps: Number(flags.builderMaxSteps) } : {},
 		...flags.builderMaxToolCalls !== void 0 ? { builder_max_tool_calls: Number(flags.builderMaxToolCalls) } : {},
 		...flags.builderMaxOutputTokens !== void 0 ? { builder_max_output_tokens: Number(flags.builderMaxOutputTokens) } : {},
+		...flags.builderTrimHistory !== void 0 ? { builder_trim_history: Number(flags.builderTrimHistory) } : {},
 		...flags.allowUnsandboxedBuilder === true ? { allow_unsandboxed_builder: true } : {},
 		...flags.criticModel !== void 0 ? { critic_model: flags.criticModel } : {},
 		...flags.criticProvider !== void 0 ? { critic_provider: flags.criticProvider } : {},
@@ -5884,6 +6244,8 @@ function report_error(err) {
 		const cause = err.cause;
 		if (cause instanceof Error && cause.message !== message) process.stderr.write(`  cause: ${cause.message}\n`);
 	}
+	const hint = claude_login_hint(err);
+	if (hint !== null) process.stderr.write(`  hint: ${hint}\n`);
 	return exit_code_for_error(err);
 }
 async function main(argv) {
@@ -5894,7 +6256,7 @@ async function main(argv) {
 		const run_id = not_a_bare_number("--run-id", flags.runId);
 		const config = resolve_config(merged, run_id !== void 0 ? { run_id } : {});
 		const renderer = make_renderer(config);
-		warn_api_key_meter(renderer);
+		warn_api_key_meter(config, renderer);
 		warn_unsandboxed_builder(config, renderer);
 		if (merged.dry_run === true) {
 			exit_code = await preflight(config, renderer, process.env);
@@ -5913,7 +6275,7 @@ async function main(argv) {
 		});
 		if (resume.iterations_completed >= config.max_iterations) throw config_error(`run already completed ${String(resume.iterations_completed)} of ${String(config.max_iterations)} iterations`);
 		const renderer = make_renderer(config);
-		warn_api_key_meter(renderer);
+		warn_api_key_meter(config, renderer);
 		warn_unsandboxed_builder(config, renderer);
 		if (resume.config_signed === false) warn_trusted_config(config, renderer);
 		renderer.info(`resuming run ${run_id} at iteration ${String(resume.iterations_completed + 1)}`);
@@ -5932,7 +6294,7 @@ async function main(argv) {
 			...run_id !== void 0 ? { run_id } : {}
 		});
 		const renderer = make_renderer(config);
-		warn_api_key_meter(renderer);
+		warn_api_key_meter(config, renderer);
 		if (merged.dry_run === true) {
 			const sha = resolve_baseline(config.workspace, baseline);
 			renderer.info(`baseline: ${sha ?? "none (not a git repository, or no commit yet)"}`);
@@ -5961,7 +6323,7 @@ async function main(argv) {
 			discard_worktree: true
 		});
 		const renderer = make_renderer(base_config, "<run id>");
-		warn_api_key_meter(renderer);
+		warn_api_key_meter(base_config, renderer);
 		warn_unsandboxed_builder(base_config, renderer);
 		const outcome = await run_matrix({
 			base: merged,
@@ -5993,6 +6355,6 @@ if (import.meta.main) {
 	process.exitCode = code;
 }
 //#endregion
-export { package_version, warn_unsandboxed_builder };
+export { claude_login_hint, package_version, warn_api_key_meter, warn_unsandboxed_builder };
 
 //# sourceMappingURL=cli.js.map