fascicle 0.17.7 → 0.17.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,24 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.17.8 — 2026-11-02
4
+
5
+ ### Added
6
+
7
+ - **A `claude_cli` provider can run under Claude Code's own sandbox.** The `bwrap` and `greywall` wrappers never enforced `network_allowlist`, so nothing held a call's commands to a list of hosts. `sandbox: { kind: 'claude_code' }` passes a policy to the CLI as `--settings`, and the CLI enforces it at the OS level, with Seatbelt on macOS and bubblewrap on Linux, while the login keeps working. Bash reaches only the domains in `network_allowlist`, and a host off the list is refused rather than asked about. It writes only inside the working directory, the temp directory, and `additional_write_paths`, it reads outside the working directory only from `additional_read_paths`, and it can't retry a blocked command outside the sandbox. The file tools refuse paths outside the working directories in every permission mode, and `deny_read_paths` keeps Bash and the file tools off credential files. Hooks are off, only the MCP servers named with `--mcp-config` start, and a repo's own settings can't loosen any of it. Before its first sandboxed call the adapter checks for Claude Code 2.1.314 or later, since an older CLI drops the settings that it doesn't know without saying so, and a CLI whose sandbox can't start fails with `sandbox_unavailable`. See [cli.md](./docs/cli.md#sandboxing).
8
+
9
+ ### Changed
10
+
11
+ - **The `bwrap` and `greywall` sandboxes are deprecated, and the docs stop saying that they enforce the allowlist.** A non-empty `network_allowlist` under `bwrap` shares the host network and hands the hosts to a variable that nothing reads, and `greywall` ignores the `network.allowHosts` that it's given, but `cli.md` and `SECURITY.md` said that the list confined the subprocess. Both kinds behave as they did. `kind: 'claude_code'` takes the same `network_allowlist` and `additional_write_paths`, so moving over changes one word, and the old kinds go in a later minor release.
12
+
13
+ ### Fixed
14
+
15
+ - **An `oauth` call no longer inherits the variable that runs Claude Code bare.** `CLAUDE_CODE_SIMPLE=1` runs the CLI in bare mode, the same as `--bare`, and bare mode never reads the CLI's login. Under `auth_mode: 'oauth'` the CLI inherits all of `process.env`, so a host that was started inside a bare session handed the variable on, and the call couldn't authenticate. `oauth` scrubs it now, along with `ANTHROPIC_API_KEY`. See [cli.md](./docs/cli.md#auth-modes).
16
+
17
+ ### Internal
18
+
19
+ - **`claude_cli`'s argv is pinned whole under each auth mode.** Claude Code plans to make `-p` bare by default, and bare mode never reads the login, so `auto` and `oauth` calls will need a flag that opts back out. The tests held the argv one flag at a time, which would have let that flag, or any other, change without a test noticing. They hold all of it now, at the argv builder and at the spawn.
20
+ - **A live test probes the `claude_code` sandbox on the real CLI.** The mocked suite shows which settings go out, and only the CLI can show that it enforces them. `claude_cli_sandbox.test.ts` runs the real `claude` on the subscription from a temp directory outside the repo and checks each confinement by its effect: a file that mustn't appear, a canary that mustn't come back, an exit code, an HTTP code. Each Bash probe reaches outside through a symlink in the working directory, so the OS sandbox is the only thing in its way. It passed on Claude Code 2.1.316, and it's gated on `LIVE_TESTS=1` and `LIVE_CLAUDE_CLI=1`.
21
+
3
22
  ## v0.17.7 — 2026-11-01
4
23
 
5
24
  ### Added
package/dist/AGENTS.md CHANGED
@@ -3,7 +3,7 @@
3
3
  This file is for a coding agent (Claude Code, Codex, Cursor, or another) that's
4
4
  working in a project which uses the published `fascicle` package. A person who
5
5
  is learning Fascicle will usually import it from their `CLAUDE.md`, as
6
- [lesson 0](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/learn/00-set-up.md) shows. Every shape, rule, and error message below
6
+ [lesson 0](https://github.com/robmclarty/fascicle/blob/v0.17.8/docs/learn/00-set-up.md) shows. Every shape, rule, and error message below
7
7
  was checked against `fascicle` 0.16.3, and against 0.15.0 where the two differ,
8
8
  except what's marked 0.17.0 and later, which was checked against 0.17.0. A rule
9
9
  that a later release changes says what changed.
@@ -398,11 +398,11 @@ describe('the calculator', () => {
398
398
 
399
399
  ## Where to Look Next
400
400
 
401
- - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/blueprint.md) for the layout of a growing app.
402
- - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/leaf-arm-spine.md) for choosing a primitive at each
401
+ - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.17.8/docs/blueprint.md) for the layout of a growing app.
402
+ - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.17.8/docs/leaf-arm-spine.md) for choosing a primitive at each
403
403
  layer.
404
- - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/composition.md) for one line on every composer.
405
- - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/cookbook.md) for worked patterns, including tool loops with
404
+ - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.17.8/docs/composition.md) for one line on every composer.
405
+ - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.17.8/docs/cookbook.md) for worked patterns, including tool loops with
406
406
  `define_tool`.
407
- - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/testing.md) for the stand-in engines.
408
- - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/troubleshooting.md) for errors and their causes.
407
+ - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.17.8/docs/testing.md) for the stand-in engines.
408
+ - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.17.8/docs/troubleshooting.md) for errors and their causes.
package/dist/acp.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { c as Step, h as TrajectoryLogger, m as TrajectoryEvent } from "./types-CPqLZOEr.js";
2
- import { M as Tool, N as ToolApprovalHandler } from "./types-xYjCEd6i.js";
2
+ import { M as Tool, N as ToolApprovalHandler } from "./types-C6PB2aP0.js";
3
3
  import { AgentApp, ClientCapabilities, ContentBlock, SessionUpdate } from "@agentclientprotocol/sdk";
4
4
  //#region src/acp/types.d.ts
5
5
  /**
package/dist/agents.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { c as Step } from "./types-CPqLZOEr.js";
2
2
  import { r as ToolSchema } from "./types-BK0UW28o.js";
3
- import { l as EffortLevel, u as Engine } from "./types-xYjCEd6i.js";
3
+ import { l as EffortLevel, u as Engine } from "./types-C6PB2aP0.js";
4
4
  //#region src/agents/define_agent.d.ts
5
5
  type AgentBuiltPrompt = string | {
6
6
  readonly user: string;
@@ -3121,6 +3121,23 @@ const CLI_AUTH_ERROR_PATTERNS = Object.freeze([
3121
3121
  * names and its `refresh_command` carries.
3122
3122
  */
3123
3123
  const CLI_REFRESH_COMMAND = "claude auth login";
3124
+ /**
3125
+ * The variable that runs the CLI in bare mode, the same as passing `--bare`.
3126
+ * Bare mode never reads the CLI's login, so an `oauth` call scrubs it.
3127
+ */
3128
+ const CLI_BARE_MODE_ENV = "CLAUDE_CODE_SIMPLE";
3129
+ /**
3130
+ * The oldest Claude Code that honors every key the `claude_code` sandbox
3131
+ * renders, as `[major, minor, patch]`. 2.1.314 added
3132
+ * `blockWritesOutsideWorkingDirectories`, the newest of them, and an older
3133
+ * CLI drops a key it doesn't know without a word, which would leave the
3134
+ * file tools unconfined.
3135
+ */
3136
+ const CLAUDE_CODE_SANDBOX_MIN_VERSION = Object.freeze([
3137
+ 2,
3138
+ 1,
3139
+ 314
3140
+ ]);
3124
3141
  const DEFAULT_SETTING_SOURCES = Object.freeze(["project", "local"]);
3125
3142
  //#endregion
3126
3143
  //#region src/engine/providers/claude_cli/auth.ts
@@ -3191,13 +3208,15 @@ function seed_base_env(config, auth_mode) {
3191
3208
  }
3192
3209
  /**
3193
3210
  * Apply the auth-mode scrub last, after base and caller env are merged, so
3194
- * nothing can re-introduce `ANTHROPIC_API_KEY` under `'oauth'`. `'api_key'`
3211
+ * nothing can re-introduce `ANTHROPIC_API_KEY` under `'oauth'`, or the
3212
+ * bare-mode variable that would stop the CLI reading its login. `'api_key'`
3195
3213
  * forces the configured key (empty string when absent); `'auto'` forwards a
3196
3214
  * non-empty configured key and otherwise leaves the inherited env untouched.
3197
3215
  */
3198
3216
  function apply_auth_key(env, config, auth_mode) {
3199
3217
  if (auth_mode === "oauth") {
3200
3218
  delete env["ANTHROPIC_API_KEY"];
3219
+ delete env[CLI_BARE_MODE_ENV];
3201
3220
  return;
3202
3221
  }
3203
3222
  if (auth_mode === "api_key") {
@@ -3220,8 +3239,9 @@ function apply_auth_key(env, config, auth_mode) {
3220
3239
  * session-specific vars to reach the already-logged-in OAuth session.
3221
3240
  * `omit_env` drops its names after the caller overrides are merged in, so a
3222
3241
  * call can't hand back a variable the provider keeps out. The auth-mode
3223
- * scrub runs last, so nothing can re-introduce `ANTHROPIC_API_KEY` under
3224
- * `'oauth'`, and a configured `api_key` still reaches the CLI.
3242
+ * scrub runs last, so nothing can re-introduce `ANTHROPIC_API_KEY` or
3243
+ * `CLAUDE_CODE_SIMPLE` under `'oauth'`, and a configured `api_key` still
3244
+ * reaches the CLI.
3225
3245
  */
3226
3246
  function build_env(config, caller_env, auth_mode) {
3227
3247
  const env = seed_base_env(config, auth_mode);
@@ -3244,6 +3264,111 @@ function stderr_is_auth_failure(stderr) {
3244
3264
  return false;
3245
3265
  }
3246
3266
  //#endregion
3267
+ //#region src/engine/providers/claude_cli/settings.ts
3268
+ /**
3269
+ * Claude Code's own sandbox for the claude_cli adapter.
3270
+ *
3271
+ * A `claude_code` sandbox needs no wrapper around the binary. The CLI
3272
+ * enforces it from the JSON that `build_cli_argv` passes inline with
3273
+ * `--settings`, and this module renders that JSON and checks the policy
3274
+ * before any run.
3275
+ *
3276
+ * The sandbox confines Bash and nothing else: Claude's file tools, hooks,
3277
+ * and MCP servers run in the unsandboxed CLI process. So the policy pairs
3278
+ * the sandbox with the permission keys that keep the file tools inside the
3279
+ * working directories, and turns hooks off.
3280
+ */
3281
+ /**
3282
+ * Drop the trailing slashes from a path that's longer than its prefix, so
3283
+ * `~/.ssh/` and `~/.ssh` render the same rules.
3284
+ */
3285
+ function trim_path(path) {
3286
+ return path.length > 2 ? path.replace(/\/+$/, "") : path;
3287
+ }
3288
+ /**
3289
+ * The permission rules that keep the file tools off one denied path and
3290
+ * everything under it. A permission rule spells an absolute path with a
3291
+ * leading `//`, where the sandbox's own lists take a single `/`.
3292
+ */
3293
+ function read_deny_rules(path) {
3294
+ const rule_path = path.startsWith("~/") ? path : `/${path}`;
3295
+ return [`Read(${rule_path})`, `Read(${rule_path}/**)`];
3296
+ }
3297
+ /**
3298
+ * Throw `engine_config_error` when a `claude_code` sandbox names a path that
3299
+ * isn't absolute or under `~/`.
3300
+ *
3301
+ * Claude Code resolves a relative path against a different directory in
3302
+ * each of its lists, and against none that's documented when the settings
3303
+ * arrive inline, so the policy takes only paths that read the same
3304
+ * everywhere. Runs at adapter construction, before anything spawns.
3305
+ */
3306
+ function validate_sandbox_config(config) {
3307
+ const sandbox = config.sandbox;
3308
+ if (sandbox?.kind !== "claude_code") return;
3309
+ const relative = [
3310
+ ...sandbox.additional_write_paths ?? [],
3311
+ ...sandbox.additional_read_paths ?? [],
3312
+ ...sandbox.deny_read_paths ?? []
3313
+ ].filter((p) => !p.startsWith("/") && !p.startsWith("~/"));
3314
+ if (relative.length > 0) throw new engine_config_error(`providers.claude_cli.sandbox has relative paths (${relative.join(", ")}): make each one absolute or start it with ~/, since Claude Code resolves a relative path differently in each list`, "claude_cli");
3315
+ }
3316
+ /**
3317
+ * Throw `engine_config_error` when a call's `extra_args` carries its own
3318
+ * `--settings` under a `claude_code` sandbox.
3319
+ *
3320
+ * The sandbox travels as `--settings`, and a second one would replace or
3321
+ * merge with it in ways the CLI doesn't document, so the call is refused
3322
+ * instead of running with a policy nobody wrote.
3323
+ */
3324
+ function validate_sandbox_extra_args(sandbox, extra_args) {
3325
+ if (sandbox?.kind !== "claude_code") return;
3326
+ if ((extra_args ?? []).some((arg) => arg === "--settings" || arg.startsWith("--settings="))) throw new engine_config_error("extra_args can't carry --settings under a claude_code sandbox, because the sandbox is passed as --settings: drop it from extra_args, or leave the sandbox off this provider", "claude_cli");
3327
+ }
3328
+ /**
3329
+ * Render a `claude_code` sandbox as the JSON that the CLI takes inline with
3330
+ * `--settings`.
3331
+ *
3332
+ * - `failIfUnavailable` makes the CLI exit at startup when its sandbox
3333
+ * can't start, instead of running Bash unconfined.
3334
+ * - `allowUnsandboxedCommands: false` arriving through `--settings` makes
3335
+ * the sandbox admin-required, so a repo's own settings can't loosen it.
3336
+ * - `autoAllowBashIfSandboxed: false` leaves the call's allowlist deciding
3337
+ * whether Bash runs at all, rather than the sandbox approving it.
3338
+ * - `strictAllowlist` refuses a host off the list rather than asking for it.
3339
+ * - The two `permissions` blocks hold the file tools inside the working
3340
+ * directories in every permission mode, and the Read deny rules keep them
3341
+ * off the denied paths too.
3342
+ * - `disableAllHooks` turns hooks off, because they run outside the sandbox
3343
+ * and `-p` runs a project's hooks without asking.
3344
+ */
3345
+ function render_sandbox_settings(sandbox) {
3346
+ const deny_paths = (sandbox.deny_read_paths ?? []).map(trim_path);
3347
+ return JSON.stringify({
3348
+ sandbox: {
3349
+ enabled: true,
3350
+ failIfUnavailable: true,
3351
+ allowUnsandboxedCommands: false,
3352
+ autoAllowBashIfSandboxed: false,
3353
+ network: {
3354
+ allowedDomains: [...sandbox.network_allowlist ?? []],
3355
+ strictAllowlist: true
3356
+ },
3357
+ filesystem: {
3358
+ allowWrite: (sandbox.additional_write_paths ?? []).map(trim_path),
3359
+ allowRead: (sandbox.additional_read_paths ?? []).map(trim_path),
3360
+ denyRead: deny_paths
3361
+ }
3362
+ },
3363
+ permissions: {
3364
+ blockReadsOutsideWorkingDirectories: true,
3365
+ blockWritesOutsideWorkingDirectories: true,
3366
+ deny: deny_paths.flatMap(read_deny_rules)
3367
+ },
3368
+ disableAllHooks: true
3369
+ });
3370
+ }
3371
+ //#endregion
3247
3372
  //#region src/engine/providers/claude_cli/argv.ts
3248
3373
  /**
3249
3374
  * Assemble the full argv array for one `claude` CLI invocation.
@@ -3262,6 +3387,7 @@ function build_cli_argv(input) {
3262
3387
  args.push("--verbose");
3263
3388
  const setting_sources = input.provider_config.setting_sources ?? DEFAULT_SETTING_SOURCES;
3264
3389
  args.push("--setting-sources", setting_sources.join(","));
3390
+ args.push(...sandbox_args(input.provider_config));
3265
3391
  for (const tool of input.merged_allowed_tools) args.push("--allowedTools", tool);
3266
3392
  if (typeof input.call_opts.session_id === "string" && input.call_opts.session_id.length > 0) args.push("--resume", input.call_opts.session_id);
3267
3393
  if (input.call_opts.agents !== void 0) args.push("--agents", JSON.stringify(input.call_opts.agents));
@@ -3274,6 +3400,21 @@ function build_cli_argv(input) {
3274
3400
  return Object.freeze(args);
3275
3401
  }
3276
3402
  /**
3403
+ * The flags that a `claude_code` sandbox adds: its policy as `--settings`,
3404
+ * and `--strict-mcp-config`, since MCP servers run outside the sandbox and
3405
+ * the strict flag starts only the ones a caller names with `--mcp-config`,
3406
+ * never a repo's `.mcp.json`. Any other sandbox adds none.
3407
+ */
3408
+ function sandbox_args(config) {
3409
+ const sandbox = config.sandbox;
3410
+ if (sandbox?.kind !== "claude_code") return [];
3411
+ return [
3412
+ "--settings",
3413
+ render_sandbox_settings(sandbox),
3414
+ "--strict-mcp-config"
3415
+ ];
3416
+ }
3417
+ /**
3277
3418
  * Join the caller's `system` prompt and the `append_system_prompt` call
3278
3419
  * option into the single string passed to `--append-system-prompt`.
3279
3420
  *
@@ -3307,13 +3448,17 @@ function merge_allowed_tools(call_allowlist, tool_names) {
3307
3448
  /**
3308
3449
  * Sandbox wrapper for the claude_cli adapter.
3309
3450
  *
3310
- * Builds the `{ spawn_cmd, prefix_args }` pair for bwrap and greywall. When
3311
- * no sandbox is configured, returns `{ spawn_cmd: binary, prefix_args: [] }`;
3312
- * the caller then concatenates prefix_args before the CLI argv.
3451
+ * Builds the `{ spawn_cmd, prefix_args }` pair for the deprecated bwrap and
3452
+ * greywall wrappers. With no sandbox, or a `claude_code` one, which the CLI
3453
+ * enforces itself from `--settings` (see `settings.ts`), it returns
3454
+ * `{ spawn_cmd: binary, prefix_args: [] }`; the caller then concatenates
3455
+ * prefix_args before the CLI argv.
3313
3456
  *
3314
- * Both wrappers allow the binary to execute while restricting network reach
3315
- * to the allowlist and write access to additional paths on top of the
3316
- * sandbox's default-read-only filesystem.
3457
+ * Both wrappers let the binary run with write access to additional paths on
3458
+ * top of the sandbox's default-read-only filesystem. Neither enforces
3459
+ * `network_allowlist`: bwrap shares the host network whenever the list is
3460
+ * non-empty, and greywall leaves host filtering to greyproxy, which nothing
3461
+ * here configures.
3317
3462
  *
3318
3463
  * greywall 0.3+ removed the `--allow-host` and `--rw` flags; policy now
3319
3464
  * lives in a JSON settings file passed via `--settings <path>`. Schema is
@@ -3333,10 +3478,10 @@ function merge_allowed_tools(call_allowlist, tool_names) {
3333
3478
  * Pick the sandbox wrapper (if any) and build its wrapping argv.
3334
3479
  *
3335
3480
  * Returns the unwrapped binary with no prefix args when `sandbox` is
3336
- * undefined.
3481
+ * undefined or a `claude_code` sandbox, which wraps nothing.
3337
3482
  */
3338
3483
  function build_sandbox_plan(binary, sandbox) {
3339
- if (sandbox === void 0) return {
3484
+ if (sandbox === void 0 || sandbox.kind === "claude_code") return {
3340
3485
  spawn_cmd: binary,
3341
3486
  prefix_args: []
3342
3487
  };
@@ -3698,6 +3843,81 @@ async function* build_stdout_lines(child, on_data) {
3698
3843
  }
3699
3844
  }
3700
3845
  //#endregion
3846
+ //#region src/engine/providers/claude_cli/version.ts
3847
+ /**
3848
+ * Claude Code version gate for the `claude_code` sandbox.
3849
+ *
3850
+ * The sandbox's settings keys arrived over several Claude Code releases, and
3851
+ * the CLI drops a settings key it doesn't know without failing, so a run on
3852
+ * an older CLI would go ahead with part of its policy missing. The gate asks
3853
+ * the binary for its version before the first sandboxed call on each `PATH`,
3854
+ * and refuses a CLI older than `CLAUDE_CODE_SANDBOX_MIN_VERSION`.
3855
+ */
3856
+ /**
3857
+ * Read the `major.minor.patch` that `claude --version` prints first, as in
3858
+ * `2.1.316 (Claude Code)`. Returns `undefined` for anything else.
3859
+ */
3860
+ function parse_cli_version(text) {
3861
+ const match = /^\s*(\d+)\.(\d+)\.(\d+)/.exec(text);
3862
+ if (match === null) return void 0;
3863
+ return [
3864
+ Number(match[1]),
3865
+ Number(match[2]),
3866
+ Number(match[3])
3867
+ ];
3868
+ }
3869
+ /**
3870
+ * Whether `found` is the release `floor` names or a later one, comparing
3871
+ * major, then minor, then patch.
3872
+ */
3873
+ function version_at_least(found, floor) {
3874
+ const [major, minor, patch] = found;
3875
+ const [floor_major, floor_minor, floor_patch] = floor;
3876
+ if (major !== floor_major) return major > floor_major;
3877
+ if (minor !== floor_minor) return minor > floor_minor;
3878
+ return patch >= floor_patch;
3879
+ }
3880
+ /**
3881
+ * Run `<cmd> --version` once and throw `sandbox_unavailable` unless it
3882
+ * reports at least the floor.
3883
+ *
3884
+ * Output that doesn't lead with a version, or a nonzero exit, fails the same
3885
+ * way, since the gate can't vouch for a CLI it can't read.
3886
+ */
3887
+ async function check_cli_version(spawn_runtime, init, env, abort) {
3888
+ const session = await spawn_runtime.spawn_cli({
3889
+ ...init,
3890
+ argv: ["--version"],
3891
+ env,
3892
+ stdin: "",
3893
+ abort
3894
+ });
3895
+ const lines = [];
3896
+ for await (const line of session.stdout_lines) lines.push(line);
3897
+ const outcome = await session.wait_close();
3898
+ const output = lines.join("\n").trim();
3899
+ const found = outcome.code === 0 ? parse_cli_version(output) : void 0;
3900
+ const floor = CLAUDE_CODE_SANDBOX_MIN_VERSION.join(".");
3901
+ if (found === void 0) throw new claude_cli_error("sandbox_unavailable", `couldn't read a Claude Code version from '${init.cmd} --version' (exit ${String(outcome.code)}, output '${output.slice(0, 120)}'): the claude_code sandbox needs Claude Code ${floor} or later, so point providers.claude_cli.binary at a claude that prints one`, { stderr_snippet: outcome.stderr.slice(0, 512) });
3902
+ if (!version_at_least(found, CLAUDE_CODE_SANDBOX_MIN_VERSION)) throw new claude_cli_error("sandbox_unavailable", `Claude Code ${found.join(".")} is older than ${floor}, the first release that honors every setting the claude_code sandbox needs: run claude update, or point providers.claude_cli.binary at a newer claude`);
3903
+ }
3904
+ /**
3905
+ * Build the per-adapter gate. `ensure` checks the CLI the first time it sees
3906
+ * a call's `PATH`, because a bare binary name resolves against that `PATH`
3907
+ * and a call can pass its own, so a pass for one `PATH` says nothing about
3908
+ * the binary that another finds. It remembers only passes, so a CLI that's
3909
+ * updated after a failure passes on the next call.
3910
+ */
3911
+ function create_cli_version_gate(spawn_runtime, init) {
3912
+ const passed = /* @__PURE__ */ new Set();
3913
+ return { ensure: async (env, abort) => {
3914
+ const path = env["PATH"] ?? "";
3915
+ if (passed.has(path)) return;
3916
+ await check_cli_version(spawn_runtime, init, env, abort);
3917
+ passed.add(path);
3918
+ } };
3919
+ }
3920
+ //#endregion
3701
3921
  //#region src/engine/providers/claude_cli/stream_parse.ts
3702
3922
  /** A non-null, non-array object: the shape every CLI event and sub-object takes. */
3703
3923
  function is_record(value) {
@@ -5026,6 +5246,7 @@ const SUPPORTED = /* @__PURE__ */ new Set([
5026
5246
  ]);
5027
5247
  const PROVIDER_NAME = "claude_cli";
5028
5248
  const BWRAP_EXEC_MISSING = /^bwrap: execvp (.+): No such file or directory$/m;
5249
+ const CLI_SANDBOX_START_FAILED = /sandbox\.failIfUnavailable/;
5029
5250
  const CLAUDE_CLI_EFFORT_VALUES = {
5030
5251
  low: "low",
5031
5252
  medium: "medium",
@@ -5105,23 +5326,35 @@ function compile_schema(schema) {
5105
5326
  return JSON.stringify(to_json_schema(schema, { strip_meta: true }));
5106
5327
  }
5107
5328
  /**
5329
+ * Classify a close whose stderr or error result says that a sandbox kept
5330
+ * the run from going ahead, whether Claude Code's own or a wrapper. Returns
5331
+ * `undefined` when neither does.
5332
+ *
5333
+ * The bwrap check has to come before the wrapper check: bwrap's own
5334
+ * "execvp <binary>: No such file or directory" names bwrap and says the file
5335
+ * is missing, so the wrapper check would blame bwrap for the claude binary.
5336
+ */
5337
+ function classify_sandbox_failure(stderr, reported, snippet, detail) {
5338
+ if (CLI_SANDBOX_START_FAILED.test(stderr) || CLI_SANDBOX_START_FAILED.test(reported)) return new claude_cli_error("sandbox_unavailable", `Claude Code's sandbox couldn't start, so the claude_code sandbox stopped the run: on Linux and WSL2 it needs bubblewrap and socat, and native Windows has no sandbox (${detail})`, { stderr_snippet: snippet });
5339
+ const sandboxed_binary = BWRAP_EXEC_MISSING.exec(stderr)?.[1];
5340
+ if (sandboxed_binary !== void 0) return new claude_cli_error("binary_not_found", `bwrap ran but found no claude binary at '${sandboxed_binary}' inside its sandbox, which binds only /usr, /bin, /lib, /lib64, and additional_write_paths: ${snippet}`, { stderr_snippet: snippet });
5341
+ if (/bwrap|greywall|sandbox/i.test(stderr) && /not found|no such file|enoent/i.test(stderr)) return new claude_cli_error("sandbox_unavailable", `sandbox binary unavailable: ${snippet}`, { stderr_snippet: snippet });
5342
+ }
5343
+ /**
5108
5344
  * Turn a closed CLI subprocess's exit code, signal, stderr, and what its
5109
5345
  * stream reported into an `Error`.
5110
5346
  *
5111
- * Checks for an auth failure first, then for a claude binary that bwrap
5112
- * started but couldn't find inside its sandbox, then for a missing sandbox
5113
- * binary, then falls back to a generic exit-code error. The stderr snippet
5114
- * attached to each error is truncated to 512 bytes.
5347
+ * Checks for an auth failure first, then for a sandbox that stopped the run
5348
+ * (Claude Code's own failing to start, a claude binary that bwrap couldn't
5349
+ * find inside its sandbox, or a missing wrapper), then falls back to a
5350
+ * generic exit-code error. The stderr snippet attached to each error is
5351
+ * truncated to 512 bytes.
5115
5352
  *
5116
5353
  * A logged-out CLI says so on stdout and leaves stderr empty: it writes an
5117
5354
  * assistant message with the `authentication_failed` error code and an error
5118
5355
  * result that reads "Not logged in · Please run /login". So the auth check
5119
5356
  * reads the stream's error code as well as stderr, and when stderr is empty,
5120
5357
  * an error result's text stands in for it in the message.
5121
- *
5122
- * The bwrap check has to come before the sandbox check: bwrap's own
5123
- * "execvp <binary>: No such file or directory" names bwrap and says the file
5124
- * is missing, so the sandbox check would blame bwrap for the claude binary.
5125
5358
  */
5126
5359
  function classify_close_error(code, signal, stderr, parsed) {
5127
5360
  const snippet = stderr.slice(0, 512);
@@ -5131,9 +5364,8 @@ function classify_close_error(code, signal, stderr, parsed) {
5131
5364
  const reason = detail.length > 0 ? `${detail}: ` : "";
5132
5365
  return new provider_auth_error(PROVIDER_NAME, `claude CLI reported an auth failure: ${reason}run ${CLI_REFRESH_COMMAND}`, { refresh_command: CLI_REFRESH_COMMAND });
5133
5366
  }
5134
- const sandboxed_binary = BWRAP_EXEC_MISSING.exec(stderr)?.[1];
5135
- if (sandboxed_binary !== void 0) return new claude_cli_error("binary_not_found", `bwrap ran but found no claude binary at '${sandboxed_binary}' inside its sandbox, which binds only /usr, /bin, /lib, /lib64, and additional_write_paths: ${snippet}`, { stderr_snippet: snippet });
5136
- if (/bwrap|greywall|sandbox/i.test(stderr) && /not found|no such file|enoent/i.test(stderr)) return new claude_cli_error("sandbox_unavailable", `sandbox binary unavailable: ${snippet}`, { stderr_snippet: snippet });
5367
+ const sandbox_failure = classify_sandbox_failure(stderr, reported, snippet, detail);
5368
+ if (sandbox_failure !== void 0) return sandbox_failure;
5137
5369
  const status = typeof code === "number" ? code : void 0;
5138
5370
  const signal_part = signal !== null ? ` (signal ${signal})` : "";
5139
5371
  const message = `claude CLI exited with code ${String(code)}${signal_part}: ${detail}`;
@@ -5161,6 +5393,7 @@ async function run_cli(spawn_runtime, args) {
5161
5393
  ...args.compiled_schema !== void 0 ? { compiled_schema: args.compiled_schema } : {}
5162
5394
  });
5163
5395
  const full_argv = [...args.prefix_args, ...argv];
5396
+ const sandbox = args.provider_config.sandbox;
5164
5397
  const session = await spawn_runtime.spawn_cli({
5165
5398
  cmd: args.spawn_cmd,
5166
5399
  argv: full_argv,
@@ -5170,7 +5403,7 @@ async function run_cli(spawn_runtime, args) {
5170
5403
  stall_timeout_ms: args.stall_timeout_ms,
5171
5404
  ...args.cwd !== void 0 ? { cwd: args.cwd } : {},
5172
5405
  ...args.abort !== void 0 ? { abort: args.abort } : {},
5173
- ...args.provider_config.sandbox !== void 0 ? { spawn_failure_reason: "sandbox_unavailable" } : {}
5406
+ ...sandbox !== void 0 && sandbox.kind !== "claude_code" ? { spawn_failure_reason: "sandbox_unavailable" } : {}
5174
5407
  });
5175
5408
  const state = create_parser_state();
5176
5409
  const chunks = [];
@@ -5439,6 +5672,7 @@ function close_spans_on_error(trajectory, spans, err) {
5439
5672
  function create_claude_cli_adapter(init) {
5440
5673
  const config = init;
5441
5674
  validate_auth_config(config);
5675
+ validate_sandbox_config(config);
5442
5676
  const spawn_runtime = create_spawn_runtime();
5443
5677
  let disposed = false;
5444
5678
  const in_flight = /* @__PURE__ */ new Set();
@@ -5446,6 +5680,11 @@ function create_claude_cli_adapter(init) {
5446
5680
  const resolved_auth_mode = config.auth_mode ?? "auto";
5447
5681
  const resolved_startup_timeout = config.startup_timeout_ms ?? 12e4;
5448
5682
  const resolved_stall_timeout = config.stall_timeout_ms ?? 3e5;
5683
+ const sandbox_cli_gate = config.sandbox?.kind === "claude_code" ? create_cli_version_gate(spawn_runtime, {
5684
+ cmd: resolved_binary,
5685
+ startup_timeout_ms: resolved_startup_timeout,
5686
+ stall_timeout_ms: resolved_stall_timeout
5687
+ }) : void 0;
5449
5688
  return {
5450
5689
  kind: "external",
5451
5690
  name: PROVIDER_NAME,
@@ -5459,6 +5698,7 @@ function create_claude_cli_adapter(init) {
5459
5698
  const tools_list = opts.tools ?? [];
5460
5699
  const tool_bridge = call_opts.tool_bridge ?? "allowlist_only";
5461
5700
  validate_request(opts.prompt, tools_list, tool_bridge);
5701
+ validate_sandbox_extra_args(config.sandbox, call_opts.extra_args);
5462
5702
  const merged_allowed_tools = merge_allowed_tools(call_opts.allowed_tools, tools_list.map((t) => t.name));
5463
5703
  record_allowlist_only_drop(tools_list, tool_bridge, trajectory);
5464
5704
  const merged_system = merge_system(opts.system ?? extract_system_text(opts.prompt), call_opts.append_system_prompt);
@@ -5487,6 +5727,7 @@ function create_claude_cli_adapter(init) {
5487
5727
  trajectory
5488
5728
  };
5489
5729
  try {
5730
+ await sandbox_cli_gate?.ensure(env, controller.signal);
5490
5731
  const first_outcome = await run_cli(spawn_runtime, base_args);
5491
5732
  const { parsed, parsed_content } = await resolve_content(spawn_runtime, base_args, opts, first_outcome.parsed);
5492
5733
  const result = assemble_result$1(parsed, resolved, opts.schema, parsed_content);
@@ -8603,4 +8844,4 @@ function create_engine(config) {
8603
8844
  //#endregion
8604
8845
  export { to_json_schema as n, create_engine as t };
8605
8846
 
8606
- //# sourceMappingURL=engine-B5iQ3if9.js.map
8847
+ //# sourceMappingURL=engine-D7ANZ8eq.js.map