@nathapp/nax-agent 0.87.1 → 0.88.0-canary.2

package/dist/native/session/turn-complete-step.js

@@ -20,6 +20,8 @@
  */
 import { getSafeLogger } from "#src/infra/index";
 import { applyHistoryPatch } from "./loop-events/cache-boundary.js";
+import { takePartialSpend } from "./partial-spend.js";
+import { usageBeat } from "./turn-accumulator.js";
 import { runOverflowCompaction } from "./turn-compaction-step.js";
 import { realSleep, retryTransportFault } from "./turn-retry.js";
 /**
@@ -89,8 +91,26 @@ export async function completeWithRecovery(args) {
         honoured = wire.honoured;
         return deps.complete(wire.messages, tools, options, turnEvents.deltaSink(roundTrip));
     };
+    // A failed round trip was still billed for what it streamed. Folding it in
+    // here, per attempt, is what makes a retry count both attempts and an
+    // aborted or timed-out one count what it cost; `takePartialSpend` consumes
+    // the entry, and the retry loop rethrows the error it was given without
+    // re-entering this wrapper, so nothing counts twice.
+    const countedRequest = async (msgs) => {
+        try {
+            return await request(msgs);
+        }
+        catch (err) {
+            const spend = takePartialSpend(err);
+            if (spend !== undefined) {
+                usage.add(spend.usage, spend.costUsd, spend.rates);
+                deps.onActivity?.(usageBeat(spend.usage, spend.costUsd));
+            }
+            throw err;
+        }
+    };
     try {
-        res = await request(messages);
+        res = await countedRequest(messages);
     }
     catch (err) {
         // Written as one guarded `if` (not a separate `canRetry` boolean) so
@@ -109,7 +129,7 @@ export async function completeWithRecovery(args) {
             if (deps.transportRetry === undefined)
                 throw err;
             res = await retryTransportFault(err, {
-                attempt: () => request(messages),
+                attempt: () => countedRequest(messages),
                 config: deps.transportRetry,
                 deadline: deps.deadline,
                 signal,
@@ -161,7 +181,7 @@ export async function completeWithRecovery(args) {
             turnEvents.emit({ type: "compaction", reason: "overflow" });
             // Retried once. A second overflow propagates: compacting further would be
             // guessing, and the failure now carries a correct diagnosis.
-            res = await request(messages);
+            res = await countedRequest(messages);
         }
     }
     return { res, messages, compacted, honoured, boundary: compacted };

package/dist/native/session-adapter.js

@@ -15,6 +15,7 @@ import { _adapterDeps, authFields, isProtocolStreamError } from "./adapter-deps.
 import { _clientDeps, getNativeClient } from "./client.js";
 import { createSessionCredentialStore } from "./credentials/session-source.js";
 import { toAdapterFailure } from "./errors.js";
+import { billedOnFailure } from "./failed-round-trip-spend.js";
 import { buildRateCard, NATIVE_AGENT, parseNativeModel, resolveContextWindow, toThinkingLevel } from "./models.js";
 import { createInstructionInteraction } from "./session/instruction-interaction.js";
 import { closeNativeSession, createNativeSessionState, markNativeTurnOutcome, openNativeSession, systemFieldFor, } from "./session/session.js";
@@ -305,7 +306,7 @@ export class NativeSessionAdapter {
                     const requestThinking = requestOptions?.thinking === false ? undefined : thinking;
                     try {
                         instructionInteraction.acknowledge();
-                        const res = await streamComplete(client, resolved, {
+                        const res = await billedOnFailure(rates, () => streamComplete(client, resolved, {
                             messages,
                             ...(tools.length > 0 ? { tools } : {}),
                             sessionId,
@@ -324,7 +325,7 @@ export class NativeSessionAdapter {
                             // to reuse the entry, so a cache write there costs more than it
                             // saves.
                             cacheRetention: "short",
-                        }, onDelta);
+                        }, onDelta));
                         const usage = res.usage;
                         // Single `priceCall` invocation: `costUsd` and `resolvedRates`
                         // come from the same call so they cannot diverge — the

package/dist/permissions/bash-lex.js

@@ -128,23 +128,55 @@ function lexDoubleQuote(state, i) {
     const end = doubleQuoteEnd(state.command, i + 1);
     if (end === -1)
         return { kind: "refuse", construct: "an unbalanced double quote" };
+    // The checks read the text with line continuations joined, as sh does: `"$\<NL>(id)"` runs `id`.
+    // Joining over-matches only after an escaped backslash, which errs toward refusing.
     const inner = state.command.slice(i + 1, end);
-    if (inner.includes("$("))
+    const joined = inner.replaceAll("\\\n", "");
+    if (joined.includes("$("))
         return { kind: "refuse", construct: "a command substitution `$(...)`" };
-    if (inner.includes("`"))
+    if (joined.includes("`"))
         return { kind: "refuse", construct: "a backtick command substitution" };
-    if (inner.includes("$"))
+    if (joined.includes("$"))
         state.opaque = true;
-    state.word += inner;
+    state.word += doubleQuotedWord(inner);
     state.started = true;
     return { kind: "advance", by: end + 1 - i };
 }
+/** The characters a backslash escapes inside double quotes; before any other, it is literal. */
+const DQ_ESCAPABLE = new Set(["$", "`", '"', "\\"]);
+/**
+ * The word sh reads from double-quoted text (nax#2551): `\<newline>` is removed, `\$ \` \" \\`
+ * keep only the escaped character, and any other backslash stays. A scan, not a replace: in
+ * `\\<newline>` the first backslash escapes the second, so the newline stays.
+ */
+function doubleQuotedWord(inner) {
+    let out = "";
+    for (let i = 0; i < inner.length; i++) {
+        const c = inner[i];
+        const next = inner[i + 1] ?? "";
+        if (c !== "\\" || next === "") {
+            out += c;
+        }
+        else if (next === "\n") {
+            i++;
+        }
+        else {
+            out += DQ_ESCAPABLE.has(next) ? next : c + next;
+            i++;
+        }
+    }
+    return out;
+}
 function lexEscape(state, i) {
     if (state.command[i] !== "\\")
         return undefined;
     const next = state.command[i + 1];
     if (next === undefined)
         return { kind: "refuse", construct: "a trailing backslash" };
+    // nax#2551: a line continuation contributes nothing — `r\<NL>m` is the word `rm` to sh, so it
+    // must be to the policy too. It starts no word, so between words it adds no empty token.
+    if (next === "\n")
+        return { kind: "advance", by: 2 };
     state.word += next;
     state.started = true;
     return { kind: "advance", by: 2 };

package/dist/sandbox/claude-settings.d.ts

@@ -0,0 +1,46 @@
+/**
+ * US-006: the two session-root Claude Code settings files.
+ *
+ * Claude Code loads `allow` rules, hooks and MCP servers from these files at
+ * the session ROOT, so a write into one weakens every later session started in
+ * that workdir — a privilege escalation that survives the run that made it.
+ *
+ * One canonical list, because two independent guards consume it and they must
+ * never diverge:
+ *
+ *   - the OS sandbox denies writes to these paths (`buildSandboxPolicy`), which
+ *     covers a sandboxed command (Bash, RunCommand) and the ACP edit path;
+ *   - the native tool policy refuses the same writes (`claudeSettingsWriteRefusal`
+ *     through `compileToolPolicy`), which is the ONLY guard on the native
+ *     `Write` / `Edit` / `Delete` tools — they run through Node's fs APIs with no
+ *     sandbox around them (branch review B1).
+ *
+ * `.claude` itself is deliberately NOT listed: a project keeps skills, commands
+ * and agents under it, so this is a file deny, never a directory one (on Linux
+ * srt turns a directory deny into a bind mount over all of them). The sandbox
+ * resolves each entry through the same `literal()`/`realOrRaw` path as every
+ * other entry, so the deny holds whether or not the file — or `.claude/` itself
+ * — exists yet.
+ *
+ * Only the session root's own files are listed. A monorepo package's
+ * `packages/<pkg>/.claude/settings.json` is out of scope (spec, "Out of Scope").
+ */
+export declare const CLAUDE_SETTINGS_FILES: readonly string[];
+/**
+ * Why `tool` may not modify the root-relative path `rel`, or undefined.
+ *
+ * `rel` must be the policy's OWN canonical spelling (root-relative, `/`-joined,
+ * symlink-resolved), never the caller's arguments: matching the caller's
+ * spelling would let `./.claude/settings.json` or `.claude/../.claude/x` walk
+ * past this guard while reaching the same file.
+ *
+ * Because `rel` is symlink-resolved, each settings entry is resolved the same
+ * way before it is compared (branch review B2): a `.claude/settings.json` that
+ * is a symlink, or a `.claude/` that is one, arrives here as its target, and a
+ * literal-only match would let the write through. Resolved per call, not at
+ * policy compile time, so a symlink created mid-session is still seen.
+ *
+ * Segment-exact on the full path — a sibling such as `settings.json.bak`, or any
+ * other file under `.claude/`, is an ordinary path a tool must still reach.
+ */
+export declare function claudeSettingsWriteRefusal(tool: string, rel: string, resolvedRoot: string): string | undefined;

package/dist/sandbox/claude-settings.js

@@ -0,0 +1,76 @@
+import { join, relative, sep } from "node:path";
+import { realOrRaw } from "#src/internal/realpath";
+/**
+ * US-006: the two session-root Claude Code settings files.
+ *
+ * Claude Code loads `allow` rules, hooks and MCP servers from these files at
+ * the session ROOT, so a write into one weakens every later session started in
+ * that workdir — a privilege escalation that survives the run that made it.
+ *
+ * One canonical list, because two independent guards consume it and they must
+ * never diverge:
+ *
+ *   - the OS sandbox denies writes to these paths (`buildSandboxPolicy`), which
+ *     covers a sandboxed command (Bash, RunCommand) and the ACP edit path;
+ *   - the native tool policy refuses the same writes (`claudeSettingsWriteRefusal`
+ *     through `compileToolPolicy`), which is the ONLY guard on the native
+ *     `Write` / `Edit` / `Delete` tools — they run through Node's fs APIs with no
+ *     sandbox around them (branch review B1).
+ *
+ * `.claude` itself is deliberately NOT listed: a project keeps skills, commands
+ * and agents under it, so this is a file deny, never a directory one (on Linux
+ * srt turns a directory deny into a bind mount over all of them). The sandbox
+ * resolves each entry through the same `literal()`/`realOrRaw` path as every
+ * other entry, so the deny holds whether or not the file — or `.claude/` itself
+ * — exists yet.
+ *
+ * Only the session root's own files are listed. A monorepo package's
+ * `packages/<pkg>/.claude/settings.json` is out of scope (spec, "Out of Scope").
+ */
+export const CLAUDE_SETTINGS_FILES = [".claude/settings.json", ".claude/settings.local.json"];
+/**
+ * The path-mutating tools this deny covers: the three that resolve a path
+ * through `compileToolPolicy` and then write it with Node's fs APIs.
+ *
+ * `GitCommit` is deliberately absent — committing a settings file does not
+ * change it, and the deny is about the file's CONTENT. Read-only tools are
+ * absent for the other reason: a session must be able to read the settings it
+ * is bound by, or a refusal becomes indistinguishable from a broken environment.
+ */
+const CLAUDE_SETTINGS_WRITE_TOOLS = new Set(["Write", "Edit", "Delete"]);
+/**
+ * Why `tool` may not modify the root-relative path `rel`, or undefined.
+ *
+ * `rel` must be the policy's OWN canonical spelling (root-relative, `/`-joined,
+ * symlink-resolved), never the caller's arguments: matching the caller's
+ * spelling would let `./.claude/settings.json` or `.claude/../.claude/x` walk
+ * past this guard while reaching the same file.
+ *
+ * Because `rel` is symlink-resolved, each settings entry is resolved the same
+ * way before it is compared (branch review B2): a `.claude/settings.json` that
+ * is a symlink, or a `.claude/` that is one, arrives here as its target, and a
+ * literal-only match would let the write through. Resolved per call, not at
+ * policy compile time, so a symlink created mid-session is still seen.
+ *
+ * Segment-exact on the full path — a sibling such as `settings.json.bak`, or any
+ * other file under `.claude/`, is an ordinary path a tool must still reach.
+ */
+export function claudeSettingsWriteRefusal(tool, rel, resolvedRoot) {
+    if (!CLAUDE_SETTINGS_WRITE_TOOLS.has(tool))
+        return undefined;
+    const entry = CLAUDE_SETTINGS_FILES.find((e) => e === rel || resolvedSettingsRel(resolvedRoot, e) === rel);
+    if (entry === undefined)
+        return undefined;
+    const subject = entry === rel
+        ? `"${rel}" is a Claude Code settings file`
+        : `"${rel}" is the target of the Claude Code settings file "${entry}"`;
+    return (`${subject}: Claude loads allow rules, hooks and MCP servers from it for every ` +
+        "session started in this workdir, so a change here outlives this run and is not made from inside it. " +
+        "The sandbox refuses writes to it as well; a human changes it by hand, outside the run.");
+}
+/** `entry`'s symlink-resolved spelling, relative to the already-resolved root, `/`-joined. */
+function resolvedSettingsRel(resolvedRoot, entry) {
+    return relative(resolvedRoot, realOrRaw(join(resolvedRoot, entry)))
+        .split(sep)
+        .join("/");
+}

package/dist/sandbox/index.d.ts

@@ -6,6 +6,7 @@ export { buildSandboxPolicy, type SandboxPolicyInput } from "./policy-builder.ts
 export { _policyInputDeps, defaultTempRoots, type GitLayout, listCredentialFiles, listNaxEntries, resolveGitLayout, runTempRoots, } from "./policy-inputs.ts";
 export { _probeDeps, probeSandbox } from "./probe.ts";
 export { _resetSandboxRegistryForTests, _sandboxRegistryDeps, probeSandboxOnce, resetSandboxBackend, sandboxBackendFor, warnSandboxUnavailableOnce, } from "./registry.ts";
+export { sessionSandboxFrom } from "./session-sandbox.ts";
 export { _sessionTmpDeps, runTmpRoot, sessionTmpDir, sessionTmpDirUnder } from "./session-tmp.ts";
 export { _srtBackendDeps, createSrtBackend } from "./srt-backend.ts";
-export type { CommandLauncher, LaunchRequest, LaunchResult, LaunchSpec, ProbeResult, SandboxBackend, SandboxBackendName, SandboxNetworkPolicy, SandboxPolicy, SandboxRecord, SandboxState, SandboxWrapRequest, } from "./types.ts";
+export type { CommandLauncher, LaunchRequest, LaunchResult, LaunchSpec, ProbeResult, SandboxBackend, SandboxBackendName, SandboxNetworkPolicy, SandboxPolicy, SandboxRecord, SandboxState, SandboxWrapRequest, SessionSandbox, } from "./types.ts";

package/dist/sandbox/index.js

@@ -6,5 +6,6 @@ export { buildSandboxPolicy } from "./policy-builder.js";
 export { _policyInputDeps, defaultTempRoots, listCredentialFiles, listNaxEntries, resolveGitLayout, runTempRoots, } from "./policy-inputs.js";
 export { _probeDeps, probeSandbox } from "./probe.js";
 export { _resetSandboxRegistryForTests, _sandboxRegistryDeps, probeSandboxOnce, resetSandboxBackend, sandboxBackendFor, warnSandboxUnavailableOnce, } from "./registry.js";
+export { sessionSandboxFrom } from "./session-sandbox.js";
 export { _sessionTmpDeps, runTmpRoot, sessionTmpDir, sessionTmpDirUnder } from "./session-tmp.js";
 export { _srtBackendDeps, createSrtBackend } from "./srt-backend.js";

package/dist/sandbox/launcher.js

@@ -156,5 +156,9 @@ export function createCommandLauncher(opts) {
                 await opts.afterWrapped?.();
             }
         },
+        // nax#2500: `false` keeps /tmp/claude writable; Claude's own srt forces that TMPDIR.
+        ...(opts.policyFor !== undefined
+            ? { policyAt: (root) => opts.policyFor(root, false) }
+            : {}),
     };
 }

package/dist/sandbox/messages.d.ts

@@ -4,7 +4,7 @@
  * always know whether it is sandboxed and what it may write (spec S5).
  */
 export declare const LIKELY_SANDBOX_DENIAL: RegExp;
-export declare function sandboxSentence(network: "open" | readonly string[], sharedTmp?: boolean): string;
+export declare function sandboxSentence(network: "open" | readonly string[], sharedTmp?: boolean, platform?: NodeJS.Platform): string;
 export declare function unsandboxedSentence(reason: string): string;
 export declare function rawBashRefusalReason(reason: string): string;
 /**

package/dist/sandbox/messages.js

@@ -18,12 +18,24 @@ function describeNetwork(network) {
  * write; a shared-temp session keeps the wording it had before.
  */
 const tempRootsPhrase = (sharedTmp) => sharedTmp ? "the system temp directories" : "this run's temp directory ($TMPDIR)";
-export function sandboxSentence(network, sharedTmp = true) {
-    return (`inside an OS sandbox: writes are allowed only under the repository root, ${tempRootsPhrase(sharedTmp)} and ` +
+/**
+ * US-006: on macOS srt refuses every setuid program, `/bin/ps` among them, and
+ * kills a non-setuid copy with SIGKILL. A test that shells out to ps therefore
+ * fails for a reason that has nothing to do with the test, and an agent reading
+ * only "Operation not permitted" has no way to tell the two apart. Appended on
+ * darwin alone: on Linux ps runs, where the sentence would excuse a real
+ * failure. It is deliberately in `sandboxSentence` rather than at each call
+ * site so every description that advertises a WORKING sandbox carries it.
+ */
+const DARWIN_SETUID_REFUSAL_SENTENCE = 'On macOS the sandbox also refuses ps and other setuid programs ("Operation not permitted"), so a test that ' +
+    "shells out to ps fails here for that reason alone.";
+export function sandboxSentence(network, sharedTmp = true, platform) {
+    const sentence = `inside an OS sandbox: writes are allowed only under the repository root, ${tempRootsPhrase(sharedTmp)} and ` +
         "package-manager caches -- and nothing under .nax/ except .nax/scratchpad/, since .nax/ is nax's own state " +
         "(change a feature's acceptance test with the Edit tool); credential files (~/.ssh, ~/.aws, ~/.npmrc, nax credentials and similar) are unreadable; " +
         `${describeNetwork(network)}. A write anywhere else fails with "Operation not permitted" or "Read-only file system" ` +
-        "-- that is the sandbox, not a bug in your command.");
+        "-- that is the sandbox, not a bug in your command.";
+    return platform === "darwin" ? `${sentence} ${DARWIN_SETUID_REFUSAL_SENTENCE}` : sentence;
 }
 export function unsandboxedSentence(reason) {
     return `Commands are NOT sandboxed on this machine (${reason}).`;

package/dist/sandbox/policy-builder.js

@@ -10,6 +10,7 @@ import { isAbsolute, join, resolve } from "node:path";
 import { NaxError } from "#src/infra/index";
 import { realOrRaw } from "#src/internal/realpath";
 import { SANDBOX_GLOB_CHARS } from "../config/schemas-sandbox.js";
+import { CLAUDE_SETTINGS_FILES } from "./claude-settings.js";
 import { BUILTIN_CACHE_WRITE_ROOTS, BUILTIN_CREDENTIAL_READ_DENIES, MACOS_CACHE_WRITE_ROOT, SRT_MACOS_TMPDIR, SRT_MACOS_TMPDIR_DENIES, } from "./defaults.js";
 import { WORKTREE_COMMON_WRITE_DIRS, WORKTREE_CONFIG_FILE } from "./git-guards.js";
 function expandHome(p, home) {
@@ -35,7 +36,13 @@ function gitDenies(root, git) {
     const common = git.kind === "worktree" ? git.commonDir : git.gitDir;
     // config.worktree is read when extensions.worktreeConfig is on; an absent one
     // is safe to deny (srt stubs it empty, and empty is valid config) (#2198).
-    const shared = [join(common, "hooks"), join(common, "config"), join(common, WORKTREE_CONFIG_FILE)];
+    // info/ holds exclude and sparse-checkout: an agent-written ignore rule hides files from review guards (#2552).
+    const shared = [
+        join(common, "hooks"),
+        join(common, "config"),
+        join(common, "info"),
+        join(common, WORKTREE_CONFIG_FILE),
+    ];
     if (git.kind === "main")
         return shared;
     // A worktree's `.git` is a pointer FILE, and gitdir/commondir point back;
@@ -47,6 +54,8 @@ function gitDenies(root, git) {
         join(git.gitDir, "gitdir"),
         join(git.gitDir, "commondir"),
         join(git.gitDir, WORKTREE_CONFIG_FILE),
+        // A linked worktree keeps its own info/ (sparse-checkout) beside the shared one (#2552).
+        join(git.gitDir, "info"),
     ];
 }
 /**
@@ -141,6 +150,10 @@ export function buildSandboxPolicy(input) {
         ...input.gitGuardFiles,
         ...(input.approvalsFile !== undefined ? [input.approvalsFile] : []),
         ...(input.trustStoreFile !== undefined ? [input.trustStoreFile] : []),
+        // US-006: the two session-root Claude settings files. One canonical list
+        // with the native tool policy that refuses the same paths (B1) -- see
+        // ./claude-settings.ts for why each is denied and why `.claude` is not.
+        ...CLAUDE_SETTINGS_FILES.map((rel) => join(root, rel)),
         ...(darwin && confined ? SRT_MACOS_TMPDIR_DENIES : []),
     ]);
     const denyRead = literal([
@@ -149,5 +162,17 @@ export function buildSandboxPolicy(input) {
         ...config.filesystem.denyRead.map((p) => resolve(root, expandHome(p, home))),
     ]);
     const allowed = config.network.allowedDomains;
-    return { writeRoots, denyWrite, denyRead, network: allowed === undefined ? {} : { allowedDomains: [...allowed] } };
+    // US-002: the flag is carried only when the config asks for it, so an absent
+    // -- or explicitly false -- config leaves `network` without the key. The type
+    // only admits `true` (see SandboxNetworkPolicy), and srt treats absent as off.
+    const loopback = config.network.allowLocalBinding === true;
+    return {
+        writeRoots,
+        denyWrite,
+        denyRead,
+        network: {
+            ...(allowed === undefined ? {} : { allowedDomains: [...allowed] }),
+            ...(loopback ? { allowLocalBinding: true } : {}),
+        },
+    };
 }

package/dist/sandbox/session-sandbox.d.ts

@@ -0,0 +1,3 @@
+/** nax#2500: a launcher's sandbox as plain data for a backend that runs its own shell. */
+import type { CommandLauncher, SessionSandbox } from "./types.ts";
+export declare function sessionSandboxFrom(launcher: CommandLauncher | undefined, root: string): Promise<SessionSandbox | undefined>;

package/dist/sandbox/session-sandbox.js

@@ -0,0 +1,9 @@
+export async function sessionSandboxFrom(launcher, root) {
+    if (launcher === undefined || launcher.state.kind === "disabled")
+        return undefined;
+    if (launcher.state.kind === "unavailable")
+        return { kind: "unavailable", reason: launcher.state.reason };
+    if (launcher.policyAt === undefined)
+        return { kind: "unavailable", reason: "the launcher exposes no policy" };
+    return { kind: "policy", policy: await launcher.policyAt(root) };
+}

package/dist/sandbox/srt-backend.d.ts

@@ -12,8 +12,17 @@ import { mkdir } from "node:fs/promises";
 import type { SandboxConfig } from "../config/schemas-sandbox.ts";
 import type { SandboxBackend } from "./types.ts";
 type SrtModule = typeof import("@anthropic-ai/sandbox-runtime");
+/**
+ * The slice of the srt module this backend calls. Narrowed on purpose: this seam
+ * is what a test replaces, and a double for the whole module needs an
+ * `as unknown as` cast, which test/ forbids (check-test-as-unknown-as). The real
+ * `typeof import(...)` satisfies this structurally, so nothing is lost.
+ */
+type SrtModuleSlice = {
+    SandboxManager: Pick<SrtModule["SandboxManager"], "initialize" | "isSupportedPlatform" | "wrapWithSandboxArgv" | "annotateStderrWithSandboxFailures" | "cleanupAfterCommand" | "reset">;
+};
 export declare const _srtBackendDeps: {
-    load: () => Promise<SrtModule>;
+    load: () => Promise<SrtModuleSlice>;
     platform: () => NodeJS.Platform;
     mkdir: typeof mkdir;
 };

package/dist/sandbox/srt-backend.js

@@ -22,11 +22,18 @@ export const _srtBackendDeps = {
  * `network`, so the object must exist. This is the one cast in the module; the
  * live suite pins the behaviour (open => no proxy variables in the argv), so
  * an srt bump that changes it fails a test rather than silently restricting.
+ *
+ * US-002 (#2538): `allowLocalBinding` rides along. srt reads it once per process
+ * from THIS object (`getAllowLocalBinding`, sandbox-manager.js:1171), never from
+ * a per-command `customConfig`, so it is emitted only here. Only `true` is
+ * emitted: srt's default is off, so absent and `false` are equivalent, and the
+ * policy type (`SandboxNetworkPolicy`) cannot express an explicit `false`.
  */
-function srtNetwork(allowedDomains) {
+function srtNetwork(allowedDomains, allowLocalBinding) {
+    const localBinding = allowLocalBinding === true ? { allowLocalBinding: true } : {};
     if (allowedDomains !== undefined)
-        return { allowedDomains: [...allowedDomains], deniedDomains: [] };
-    const open = { deniedDomains: [] };
+        return { allowedDomains: [...allowedDomains], deniedDomains: [], ...localBinding };
+    const open = { deniedDomains: [], ...localBinding };
     return open;
 }
 function customConfig(policy) {
@@ -36,6 +43,9 @@ function customConfig(policy) {
             allowWrite: [...policy.writeRoots],
             denyWrite: [...policy.denyWrite],
         },
+        // US-002: `allowLocalBinding` is deliberately NOT here. srt applies it
+        // process-wide, from the `initialize` config, so a copy on the per-command
+        // config would promise a per-command effect it does not have.
         ...(policy.network.allowedDomains !== undefined ? { network: srtNetwork(policy.network.allowedDomains) } : {}),
     };
 }
@@ -49,7 +59,7 @@ export function createSrtBackend(network) {
             if (_srtBackendDeps.platform() === "darwin")
                 await _srtBackendDeps.mkdir(SRT_MACOS_TMPDIR, { recursive: true });
             await mod.SandboxManager.initialize({
-                network: srtNetwork(network.allowedDomains),
+                network: srtNetwork(network.allowedDomains, network.allowLocalBinding),
                 filesystem: { denyRead: [], allowWrite: [], denyWrite: [] },
             });
             loaded = mod;

package/dist/sandbox/types.d.ts

@@ -10,6 +10,15 @@ export type SandboxBackendName = "srt";
 export interface SandboxNetworkPolicy {
     /** Absent = unrestricted. */
     readonly allowedDomains?: readonly string[];
+    /**
+     * US-002: srt may let a command bind to -- and reach -- loopback ports, so a
+     * DB-backed test run sees a local server that is up (#2538).
+     *
+     * `true` only. srt's own default is off, so absent and `false` are the same
+     * thing to it, and a policy that cannot express "off" cannot contradict the
+     * config it was built from.
+     */
+    readonly allowLocalBinding?: true;
 }
 export interface SandboxPolicy {
     readonly writeRoots: readonly string[];
@@ -17,6 +26,18 @@ export interface SandboxPolicy {
     readonly denyRead: readonly string[];
     readonly network: SandboxNetworkPolicy;
 }
+/**
+ * nax#2500: the sandbox an embedder hands a backend that runs its own shell
+ * (ACP Claude). Absent = sandbox disabled by config. `unavailable` = enabled but
+ * unusable on this host; the backend must refuse rather than run unsandboxed.
+ */
+export type SessionSandbox = {
+    readonly kind: "policy";
+    readonly policy: SandboxPolicy;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
 export type ProbeResult = {
     readonly available: true;
 } | {
@@ -99,4 +120,6 @@ export interface LaunchResult extends ArgvExecResult {
 export interface CommandLauncher {
     readonly state: SandboxState;
     run(req: LaunchRequest): Promise<LaunchResult>;
+    /** nax#2500: the policy this launcher would apply at `root`, without the session TMPDIR. Present when available. */
+    policyAt?(root: string): Promise<SandboxPolicy>;
 }

package/dist/session/agent-session-options.js

@@ -36,7 +36,7 @@ const OptionsSchema = z.strictObject({
         .string()
         .regex(SESSION_ID, "must be 1-128 letters, digits, '.', '_' or '-', starting with a letter or digit")
         .optional(),
-    profile: z.enum(["none", "read", "ask", "full"]),
+    profile: z.enum(["none", "read", "review", "ask", "full"]),
     workdir: z
         .string()
         .refine((dir) => isAbsolute(dir), "must be an absolute path")

package/dist/session/agent-session-types.d.ts

@@ -13,7 +13,7 @@ import type { JSONSchema } from "./tool-descriptor.ts";
  * What the session's agent may touch. Capability statements, not tool lists
  * (spec 4.5). `ask`: every mutating action is approved through `answer()`.
  */
-export type AgentSessionProfile = "none" | "read" | "ask" | "full";
+export type AgentSessionProfile = "none" | "read" | "review" | "ask" | "full";
 export interface EmbedderToolContext {
     readonly sessionId: string;
     /** The provider's tool-call id: the same id as the `tool_call` / `tool_result` events. */

package/dist/session/native-backend-options.js

@@ -69,12 +69,14 @@ export function parseNativeBackendOptions(input) {
     return { raw: options, provider: providerOf(options.model) };
 }
 export function nativeProfileRules(profile, raw) {
-    const tools = profile === "full" || profile === "ask";
+    const tools = profile === "full" || profile === "ask" || profile === "review";
     if (!tools && raw.bashApproval !== undefined) {
-        throw invalid('bashApproval applies to profiles "ask" and "full" only', { path: "backend.bashApproval" });
+        throw invalid('bashApproval applies to profiles "ask", "full" and "review" only', { path: "backend.bashApproval" });
     }
     if (!tools && raw.allowUnsandboxed !== undefined) {
-        throw invalid('allowUnsandboxed applies to profiles "ask" and "full" only', { path: "backend.allowUnsandboxed" });
+        throw invalid('allowUnsandboxed applies to profiles "ask", "full" and "review" only', {
+            path: "backend.allowUnsandboxed",
+        });
     }
     const bashApproval = raw.bashApproval ?? "gated";
     if (profile === "ask" && bashApproval !== "gated") {

package/dist/session/session-backend.d.ts

@@ -64,6 +64,15 @@ export interface BackendOpenContext {
     readonly metadata: Readonly<Record<string, string>>;
     /** Aborted when the session starts closing. */
     readonly openSignal: AbortSignal;
+    /** nax#2500: present only for profiles review/full when the embedder supplied one. */
+    readonly sandbox?: import("#src/sandbox/types").SessionSandbox;
+    /**
+     * The rendered `## MCP servers` section for this open (#2517). The ACP
+     * backend (nax-agent-acp) offers it to its tool host, so the agent's own MCP
+     * client receives it in `initialize`; the native backend leaves it alone —
+     * native reaches the same text through `OpenSessionOpts.providerInstructions`.
+     */
+    readonly providerInstructions?: string;
 }
 export interface OpenedBackend {
     readonly adapter: AgentSessionAdapter;

package/dist/session/session-tool-support.d.ts

@@ -29,7 +29,7 @@ export interface SessionLauncherArgs {
     readonly bashApproval: BashApprovalMode;
     readonly allowUnsandboxed: boolean;
 }
-/** The sandbox floor (spec 6.3): "ask" and "full" need a usable sandbox unless gated + allowUnsandboxed. */
+/** The sandbox floor (spec 6.3): "ask", "full" and "review" need a usable sandbox unless gated + allowUnsandboxed. */
 export declare function resolveSessionLauncher(args: SessionLauncherArgs): Promise<CommandLauncher | undefined>;
 export interface SessionToolSupportArgs {
     readonly profile: AgentSessionProfile;

package/dist/session/session-tool-support.js

@@ -21,6 +21,8 @@ export function declaredToolsFor(profile, protectedPaths) {
         return [...UNIVERSAL_CODING_TOOLS];
     if (profile === "read")
         return [...UNIVERSAL_CODING_TOOLS, ...READ_TOOLS];
+    if (profile === "review")
+        return [...UNIVERSAL_CODING_TOOLS, ...READ_TOOLS, "Bash"];
     // GitCommit refuses every path without ignore patterns, so it is offered only with them.
     const commit = protectedPaths.gitIgnorePatterns.length > 0 ? ["GitCommit"] : [];
     return [...UNIVERSAL_CODING_TOOLS, ...READ_TOOLS, ...WRITE_TOOLS, ...commit];
@@ -57,9 +59,9 @@ export function defaultProtectedPaths(ownCredentials) {
     const credentialDir = ownCredentials ? undefined : configuredCredentialDir();
     return credentialDir === undefined ? base : { ...base, credentialDir };
 }
-/** The sandbox floor (spec 6.3): "ask" and "full" need a usable sandbox unless gated + allowUnsandboxed. */
+/** The sandbox floor (spec 6.3): "ask", "full" and "review" need a usable sandbox unless gated + allowUnsandboxed. */
 export async function resolveSessionLauncher(args) {
-    if (args.profile !== "full" && args.profile !== "ask")
+    if (args.profile !== "full" && args.profile !== "ask" && args.profile !== "review")
         return undefined;
     const launcher = await resolveSessionSandbox({
         config: DEFAULT_SANDBOX_CONFIG,

package/dist/session/session-types.d.ts

@@ -155,6 +155,8 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
     providerTools?: readonly import("#src/tools/registry").CodingTool[];
     /** ACP: the op's materialized declaration, which narrows the session profile (nax#2444, D2). */
     declaredTools?: readonly string[];
+    /** nax#2500: the dispatch sandbox for ACP backends that run their own shell (claude). Native ignores it. */
+    sandbox?: import("#src/sandbox/types").SessionSandbox;
     /** ACP: the transport-less surface draft; the adapter stamps transport + profile (nax#2410, D4). */
     toolSurface?: import("#src/tools/tool-audit").ToolSurfaceDraft;
     /**
@@ -194,6 +196,14 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
      * facade sets it from `instructions`; nax leaves it unset. ACP ignores it.
      */
     systemPrompt?: string;
+    /**
+     * Native: the rendered `## MCP servers` section, appended to `systemPrompt`
+     * after a blank line (#2517) — one `system` field, so the instructions reach
+     * the model exactly where `systemPrompt` already goes and no second state
+     * map is needed. Set together with `systemPrompt` by nax
+     * (`openSessionExtras`); either may be set alone. ACP ignores it.
+     */
+    providerInstructions?: string;
     /** Native: repository-relative instruction scopes, independent of the file-tool root. */
     instructionDirectories?: readonly string[];
     /** Native: instruction Markdown basename; defaults to AGENTS.md and its legacy fallback chain. */