@nathapp/nax-agent 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `@nathapp/nax-agent` are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). While the version is `0.x`, a minor
+release may change the public API.
+
+## [0.1.0] - 2026-10-03
+
+First published version. Extracted from nax, where it was the native agent.
+
+### Added
+
+- The session contract, the native session adapter and `nativeComplete`, the tool set, permission
+  resolution, the OS sandbox, command-safety and the cost core, behind `@nathapp/nax-agent`.
+- Process-wide slots: `setAgentLogger`, `configureCredentials`, and `setAgentRuntime` with a Node
+  default (`nodeRuntime`).
+- Host ports: `runDeclaredCommand`, `ProtectedPathsPolicy`, `commandInterceptor`.
+- `@nathapp/nax-agent/internal`, nax-only and outside semver.
+- `api/nax-agent.api.txt`: the built public API, checked in CI.
+
+### Notes
+
+- Requires Node.js >= 22.19.0. No Bun APIs ship in the package.
+- `.` exports no `_`-prefixed name; test seams and reset hooks are on `./internal` only.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 William Khoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @nathapp/nax-agent
+
+nax's native coding agent as a package: the session contract, the native session adapter and its turn loop over `@nathapp/nax-ai`, the tool set, permission resolution, the OS sandbox, command-safety and cost accounting.
+
+> **Pre-1.0, not yet published.** `0.1.0` is the first planned version. Until `1.0` the API of `.` may change in any minor release. Pin an exact version.
+
+## Install
+
+```bash
+npm install @nathapp/nax-agent
+```
+
+Requires **Node.js >= 22.19.0**. The package is ESM only and ships no Bun code: it runs on Node, and on Bun, with the default runtime.
+
+## Entry points
+
+- **`@nathapp/nax-agent`** is the supported entry. Every export is named, and none starts with `_`. Its exact names are pinned in [`api/nax-agent.api.txt`](api/nax-agent.api.txt), which CI compares with the built declarations.
+- **`@nathapp/nax-agent/internal`** is **nax-only and outside semver.** nax bundles this package and reaches below the public entry for shared helpers, `NaxError`, deep modules and the `_*Deps` test seams. Names, shapes and behaviour there can change in any release, patch included, and a change there is not a breaking change. Do not import it from another project.
+
+## Process-wide slots
+
+The host installs these once, near startup. They are module-level, so they apply to everything in the process.
+
+| Slot | Install | When unset |
+|:-----|:--------|:-----------|
+| Logger | `setAgentLogger(logger)` (`null` clears) | Logging is silent: `getLogger()` is a no-op logger and `getSafeLogger()` is `null`. |
+| Credentials | `configureCredentials({ configDir, readAuthConfig })` | The first credential read throws `NaxError` with code `CREDENTIALS_NOT_CONFIGURED`. There is no default config directory. |
+| Runtime | `setAgentRuntime(runtime)` (`null` clears) | `getAgentRuntime()` returns `nodeRuntime`, built on `node:child_process` and `node:fs`. |
+
+`AgentRuntime` is the process and glob contract (`spawn`, `glob`, `globSync`). The Node default is complete; install your own only to change how the agent spawns processes or expands globs.
+
+## Ports the host supplies
+
+Three pieces of host knowledge are passed in as data or functions, because the package cannot know them. Their behaviour when you omit them differs, so check each one.
+
+- **`runDeclaredCommand`** runs a command your project declared (a test or lint command), never one the model wrote. If you do not supply it, the `RunCommand` tool answers `exit 1` with "no declared-command runner is configured for this session" and starts no process. It fails closed.
+- **`ProtectedPathsPolicy`** names the paths you own and want kept away from the agent: git pathspecs the Git tool excludes from its default view, gitignore patterns `GitCommit` refuses to stage, the project state directory, the credential directory and the trust-store file the sandbox protects. If you do not supply it, the Git tool excludes nothing from its default view, and `GitCommit` fails closed: it refuses every path and stages nothing until the policy supplies a non-empty `gitIgnorePatterns` (an empty list refuses the same way). Supply it whenever the agent works in a directory that holds files you own. Building a sandboxed session requires it.
+- **`commandInterceptor`** may rewrite a command before it runs (for example to prefix a wrapper binary). Rewrites are validated: an argv rewrite may only prefix the original argv with the provider's own binary, and a shell rewrite goes through the same narrowing. If you do not supply one, commands run unchanged. An interceptor that throws, or returns a rewrite that fails validation, is treated as a decline, and the original command runs.
+
+## Status and roadmap
+
+The embedder-facing session API is still being designed, so `0.x` may reshape `.` with a minor bump. See [`CHANGELOG.md`](CHANGELOG.md).
+
+Maintainers: see the [release procedure](https://github.com/nathapp-io/nax/blob/main/packages/nax-agent/RELEASING.md)
+for the manual 0.1.0 publish and OTP step, trusted-publisher setup and subsequent tagged releases.
+
+## License
+
+MIT

package/dist/coding-tools/coding-tool-bash.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Bash-specific grant resolution for `buildCodingToolSupport`.
+ *
+ * Extracted from coding-tool-support.ts, which sits at the 600-line source
+ * limit, so this stage's grant math -- and the explanatory comments that are
+ * load-bearing for reading the ADR-030 gating rule correctly -- have room to
+ * live without pushing the caller over the limit.
+ *
+ * Pure: no I/O, no `NaxError`. Decides nothing about the empty-root guard or
+ * the terminal `tools.length === 0` guard; both stay in coding-tool-support.ts,
+ * where the rest of the runtime is assembled.
+ */
+import type { BashApprovalMode } from "#src/config/bash-approval";
+import { type CodingToolName, type ToolGrant, type ToolPatternNarrowing } from "#src/tools/index";
+export interface BashSupportResolution {
+    /**
+     * The grants `compileToolPolicy` should compile -- narrowed, and with the
+     * ADR-030 synthetic `Bash(*)` grant appended under `raw` when applicable.
+     */
+    readonly effectiveGrants: readonly ToolGrant[];
+    /** Whether the op should receive a Bash tool at all (the declaration ceiling). */
+    readonly allowBash: boolean;
+    /**
+     * The patterns the Bash tool's description should name -- the EFFECTIVE
+     * grant (post-synthetic), not the pre-synthetic human grant, so a `raw`
+     * stage with no human `Bash(...)` rule still names what it can actually
+     * run instead of the stale "no command forms are granted" (ADR-030 / F3).
+     * `createBashTool` ignores this entirely under `raw` (it has its own
+     * static raw description), so the distinction only matters for
+     * `gated`/`escalate`, where it is identical to the pre-synthetic grant --
+     * `raw` is the only mode that ever synthesizes one.
+     */
+    readonly bashDescriptionPatterns: readonly string[];
+}
+/**
+ * Resolve the Bash-specific half of a stage's compiled grants.
+ *
+ * `grants` is the RAW (pre-narrow) grant list, matching what
+ * `buildCodingToolSupport` used to pass into `narrowGrants` inline.
+ */
+export declare function resolveBashSupport(args: {
+    declared: readonly CodingToolName[];
+    grants: readonly ToolGrant[];
+    toolPatterns?: ToolPatternNarrowing;
+    bashApproval: BashApprovalMode;
+}): BashSupportResolution;

package/dist/coding-tools/coding-tool-bash.js

@@ -0,0 +1,44 @@
+/**
+ * Bash-specific grant resolution for `buildCodingToolSupport`.
+ *
+ * Extracted from coding-tool-support.ts, which sits at the 600-line source
+ * limit, so this stage's grant math -- and the explanatory comments that are
+ * load-bearing for reading the ADR-030 gating rule correctly -- have room to
+ * live without pushing the caller over the limit.
+ *
+ * Pure: no I/O, no `NaxError`. Decides nothing about the empty-root guard or
+ * the terminal `tools.length === 0` guard; both stay in coding-tool-support.ts,
+ * where the rest of the runtime is assembled.
+ */
+import { BASH_TOOL_NAME, narrowGrants, } from "#src/tools/index";
+/**
+ * Resolve the Bash-specific half of a stage's compiled grants.
+ *
+ * `grants` is the RAW (pre-narrow) grant list, matching what
+ * `buildCodingToolSupport` used to pass into `narrowGrants` inline.
+ */
+export function resolveBashSupport(args) {
+    // Narrowed, not raw: `narrowGrants` is what the POLICY compiles, so reading
+    // the raw list here would name forms in the tool's description that the
+    // policy then refuses -- the wasted turn the `patterns` option exists to
+    // prevent, inverted.
+    const narrowedGrants = narrowGrants(args.grants, args.toolPatterns);
+    const bashGrant = narrowedGrants.findLast((grant) => grant.tool === BASH_TOOL_NAME);
+    const allowBash = args.declared.includes(BASH_TOOL_NAME);
+    // ADR-030: `raw` changes GATING, not GRANTING — the Bash tool still has to be
+    // granted or `callTool` never reaches the policy. The grant is synthetic
+    // (no human wrote a `Bash(...)` rule) and is deliberately conditioned on the
+    // op having DECLARED Bash. That condition is what keeps review ops and the
+    // verifier shell-free under every mode: they declare no Bash, so no mode can
+    // hand them one. Never grant unconditionally here.
+    const syntheticGrant = args.bashApproval === "raw" && allowBash && bashGrant === undefined
+        ? { tool: BASH_TOOL_NAME, patterns: ["*"] }
+        : undefined;
+    const effectiveGrants = syntheticGrant !== undefined ? [...narrowedGrants, syntheticGrant] : narrowedGrants;
+    const effectiveBashGrant = bashGrant ?? syntheticGrant;
+    return {
+        effectiveGrants,
+        allowBash,
+        bashDescriptionPatterns: effectiveBashGrant?.patterns ?? [],
+    };
+}

package/dist/coding-tools/coding-tool-extras.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The session-local tools an operation declares: RunCommand (its declared
+ * commands and, when `Exec` is declared, its argv branch) and Bash.
+ *
+ * Extracted from coding-tool-support.ts to keep that file under its 600-line
+ * source limit ahead of the P4 sandbox wiring. A pure move: every comment that
+ * explains a field below travelled with it.
+ */
+import type { BashApprovalMode } from "#src/config/bash-approval";
+import type { QualityCommandSpec } from "#src/internal/command-spec/index";
+import type { CommandLauncher } from "#src/sandbox/index";
+import { type CodingTool, type DeclaredCommandRunner, type ToolGrant } from "#src/tools/index";
+export interface DeclaredCommandToolsArgs {
+    readonly declaredCommands: ReadonlyMap<string, QualityCommandSpec>;
+    readonly allowExec: boolean;
+    readonly execGrant: ToolGrant | undefined;
+    readonly allowBash: boolean;
+    readonly bashDescriptionPatterns: readonly string[];
+    readonly bashApproval: BashApprovalMode;
+    /** A human can answer an escalated Bash command (ADR-030, amended for P4). */
+    readonly humanApproval?: boolean;
+    readonly root: string;
+    readonly repoRoot?: string;
+    readonly packageWorkdir?: string;
+    readonly commandCwd?: string;
+    readonly allowScripts?: boolean;
+    readonly packageName?: string;
+    readonly stripEnvVars?: readonly string[];
+    readonly shell?: string;
+    /** Port 7: runs declared commands; nax supplies `runQualityCommand`. */
+    readonly runDeclaredCommand?: DeclaredCommandRunner;
+    /** P4: how Bash and Exec-branch commands run; absent = direct spawn (tests). */
+    readonly launcher?: CommandLauncher;
+}
+export declare function buildDeclaredCommandTools(args: DeclaredCommandToolsArgs): CodingTool[];

package/dist/coding-tools/coding-tool-extras.js

@@ -0,0 +1,56 @@
+import { createBashTool, createRunCommandTool, } from "#src/tools/index";
+export function buildDeclaredCommandTools(args) {
+    return [
+        ...(args.declaredCommands.size > 0 || args.allowExec
+            ? [
+                createRunCommandTool(args.declaredCommands, {
+                    stripEnvVars: args.stripEnvVars,
+                    commandCwd: args.commandCwd ?? args.root,
+                    runDeclaredCommand: args.runDeclaredCommand,
+                    ...(args.allowExec
+                        ? {
+                            exec: {
+                                repoRoot: args.repoRoot ?? args.root,
+                                // Post-root-move: `args.root` is the repo root, so the
+                                // fallback only matters for single-package repos where
+                                // the two coincide (and for tests not threading
+                                // `packageWorkdir`). Production always threads it via
+                                // `commandCwd` plumbing in `resolveCodingToolSupport`
+                                // (Task 10), which makes `effectiveTarget`'s
+                                // `packageRelPath === ""` collapse impossible for a
+                                // package story.
+                                packageWorkdir: args.packageWorkdir ?? args.root,
+                                allowScripts: args.allowScripts ?? false,
+                                // The compiled grant, not BUILT_IN_EXEC_PATTERNS -- a
+                                // project's own Exec(...) expression replaces that
+                                // list rather than extending it (see the comment on
+                                // BUILT_IN_EXEC_PATTERNS in src/config/permissions.ts).
+                                // `allowExec` is true only when execGrant is defined,
+                                // so this array is never actually empty at this call
+                                // site; the fallback exists only for the type.
+                                patterns: args.execGrant?.patterns ?? [],
+                                ...(args.packageName !== undefined ? { packageName: args.packageName } : {}),
+                                ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
+                            },
+                        }
+                        : {}),
+                }),
+            ]
+            : []),
+        ...(args.allowBash
+            ? [
+                createBashTool({
+                    ...(args.shell !== undefined ? { shell: args.shell } : {}),
+                    ...(args.stripEnvVars !== undefined ? { stripEnvVars: args.stripEnvVars } : {}),
+                    // The EFFECTIVE grant, so the description names what THIS
+                    // stage may actually run, incl. the synthetic grant under
+                    // `raw` (ADR-030 / F3) -- ignored under `raw` regardless.
+                    patterns: args.bashDescriptionPatterns,
+                    bashApproval: args.bashApproval,
+                    ...(args.humanApproval === true ? { humanApproval: true } : {}),
+                    ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
+                }),
+            ]
+            : []),
+    ];
+}

package/dist/coding-tools/coding-tool-sandbox.d.ts

@@ -0,0 +1,74 @@
+import { homedir } from "node:os";
+import type { SandboxConfig } from "#src/config/schemas-sandbox";
+import { type CommandLauncher, defaultTempRoots, listCredentialFiles, listGitGuardFiles, listNaxEntries, probeSandboxOnce, resolveGitLayout, runTempRoots, sandboxBackendFor, strayCommonDirTripwire } from "#src/sandbox/index";
+import type { ProtectedPathsPolicy } from "#src/tools/index";
+export declare const _sessionSandboxDeps: {
+    backendFor: typeof sandboxBackendFor;
+    probe: typeof probeSandboxOnce;
+    gitLayout: typeof resolveGitLayout;
+    naxEntries: typeof listNaxEntries;
+    gitGuardFiles: typeof listGitGuardFiles;
+    commonDirTripwire: typeof strayCommonDirTripwire;
+    credentialFiles: typeof listCredentialFiles;
+    tempRoots: typeof defaultTempRoots;
+    homedir: typeof homedir;
+    platform: () => NodeJS.Platform;
+    /** US-002 — creates the session temp dir before the policy is built. */
+    mkdir: (path: string) => Promise<unknown>;
+    /** US-002 — the host temp dir, kept injectable so the policy choice is testable. */
+    tmpdir: () => string;
+    /** US-002 — the temp roots of one confined run, given its own root. */
+    runTempRoots: typeof runTempRoots;
+};
+export declare function resolveSessionSandbox(args: {
+    readonly config: SandboxConfig | undefined;
+    readonly root: string;
+    readonly outputDir?: string;
+    readonly needsLauncher: boolean;
+    readonly storyId?: string;
+    /** US-004 — per-session temp directory the launcher creates and exports as TMPDIR/TMP/TEMP. */
+    readonly tmpDir?: string;
+    /** US-002 — the run's own temp root, present whenever `tmpDir` is (dispatch-supplied). */
+    readonly runTmpRoot?: string;
+    /** Host-owned paths the policy denies (S1 spec port 6); nax passes `naxProtectedPaths()`. */
+    readonly protectedPaths: ProtectedPathsPolicy;
+}): Promise<CommandLauncher>;
+/** The compile-time policy refusal for `raw` (Task 8), or undefined. */
+export declare function rawRefusalFor(launcher: CommandLauncher | undefined): string | undefined;
+/**
+ * US-004: whether the session's sandbox confines temp writes to this run's own
+ * temp root.
+ *
+ * True exactly when the launcher is available AND says `sharedTmp: false` —
+ * the only state under which the command guard may skip the classifier for a
+ * temp-only command (`src/agents/coding-tool-support.ts` → `tempConfined` →
+ * `src/command-safety/guard.ts:185`). An available launcher without
+ * `sharedTmp`, an unavailable or disabled one, and no launcher at all all read
+ * as NOT confined.
+ *
+ * That is the RESOLVE-time answer, fixed when the launcher is built, and it is
+ * deliberately NOT the answer the policy narrows on. `SandboxPolicyInput.confined`
+ * ANDs it with whether the per-command session-dir `mkdir` succeeded
+ * (`src/sandbox/launcher.ts:194`), because the `export TMPDIR=…` prefix rides on
+ * that same mkdir. So a session whose dir fails to re-create reports `true` here
+ * while the policy for that ONE command is the unconflined one, `/tmp/claude`
+ * included — which means the guard's temp-only exemption can be claimed for a
+ * command that is not in fact confined. Deliberate, and documented on
+ * `SandboxPolicyInput.confined` (`src/sandbox/policy-builder.ts:41-64`); do not
+ * reconcile the two by making either follow the other.
+ */
+export declare function isTempConfined(launcher: CommandLauncher | undefined): boolean;
+/**
+ * US-002: the raw-screen options `compileToolPolicy` consumes, derived from the
+ * launcher's state.
+ *
+ * `rawBashRefusal` is exactly what `rawRefusalFor` returns (an unavailable
+ * launcher refuses every call). `sandboxWrapped: true` is added for an available
+ * launcher: the command really does run inside the OS sandbox, so the raw screen
+ * stops refusing a feature PRD the command only READS. A disabled launcher
+ * yields neither key.
+ */
+export declare function rawScreenOptionsFor(launcher: CommandLauncher | undefined): {
+    rawBashRefusal?: string;
+    sandboxWrapped?: true;
+};

package/dist/coding-tools/coding-tool-sandbox.js

@@ -0,0 +1,215 @@
+/**
+ * The async half of P4's session wiring (spec 5.2, review finding 7).
+ *
+ * resolveCodingToolSupport is async and awaits this; buildCodingToolSupport is
+ * synchronous and on the hot dispatch path, so it only receives the result as
+ * data. Nothing here may be called from the sync path.
+ */
+import { mkdir } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { errorMessage } from "#src/infra/errors";
+import { getSafeLogger, NaxError } from "#src/infra/index";
+import { approvalsPath } from "#src/permissions/index";
+import { buildSandboxPolicy, createCommandLauncher, DISABLED_SANDBOX_STATE, defaultTempRoots, listCredentialFiles, listGitGuardFiles, listNaxEntries, probeSandboxOnce, rawBashRefusalReason, resolveGitLayout, runTempRoots, sandboxBackendFor, strayCommonDirTripwire, warnSandboxUnavailableOnce, } from "#src/sandbox/index";
+export const _sessionSandboxDeps = {
+    backendFor: sandboxBackendFor,
+    probe: probeSandboxOnce,
+    gitLayout: resolveGitLayout,
+    naxEntries: listNaxEntries,
+    gitGuardFiles: listGitGuardFiles,
+    commonDirTripwire: strayCommonDirTripwire,
+    credentialFiles: listCredentialFiles,
+    tempRoots: defaultTempRoots,
+    homedir,
+    platform: () => process.platform,
+    /** US-002 — creates the session temp dir before the policy is built. */
+    mkdir: (path) => mkdir(path, { recursive: true }),
+    /** US-002 — the host temp dir, kept injectable so the policy choice is testable. */
+    tmpdir: () => tmpdir(),
+    /** US-002 — the temp roots of one confined run, given its own root. */
+    runTempRoots,
+};
+/**
+ * US-002: which temp roots a session's policy grants.
+ *
+ * Shared roots are today's behaviour and the fallback: the opt-out
+ * (`allowSharedTmp`), a session with no run root, and a failed directory
+ * creation all land there.
+ *
+ * Confinement needs both `runTmpRoot` and `tmpDir` — the session temp dir the
+ * launcher exports as TMPDIR is no more writable than `/tmp` is, so it has to
+ * be created here, BEFORE the policy that grants it. A creation failure fails
+ * OPEN to the shared roots: a session must never run with a TMPDIR its own
+ * sandbox cannot write.
+ */
+async function sessionTempRoots(args) {
+    const { runTmpRoot, tmpDir } = args;
+    const shared = () => ({ tempRoots: _sessionSandboxDeps.tempRoots(), confined: false });
+    if (args.config.filesystem.allowSharedTmp || runTmpRoot === undefined || tmpDir === undefined)
+        return shared();
+    try {
+        await _sessionSandboxDeps.mkdir(tmpDir);
+    }
+    catch (err) {
+        getSafeLogger()?.warn("sandbox", "could not create the session temp dir — granting the shared temp roots", {
+            storyId: args.storyId ?? "_dispatch",
+            tmpDir,
+            error: errorMessage(err),
+        });
+        return shared();
+    }
+    return {
+        tempRoots: _sessionSandboxDeps.runTempRoots({ runTmpRoot, tmpdir: _sessionSandboxDeps.tmpdir() }),
+        confined: true,
+    };
+}
+export async function resolveSessionSandbox(args) {
+    const config = args.config;
+    if (config === undefined || !config.enabled || !args.needsLauncher) {
+        return createCommandLauncher({
+            state: DISABLED_SANDBOX_STATE,
+            ...(args.tmpDir !== undefined ? { tmpDir: args.tmpDir } : {}),
+        });
+    }
+    const backend = _sessionSandboxDeps.backendFor(config);
+    const probe = await _sessionSandboxDeps.probe(backend, args.storyId);
+    if (!probe.available) {
+        warnSandboxUnavailableOnce(probe.reason, args.storyId);
+        return createCommandLauncher({
+            state: { kind: "unavailable", backend: backend.name, reason: probe.reason },
+            ...(args.tmpDir !== undefined ? { tmpDir: args.tmpDir } : {}),
+        });
+    }
+    const git = await _sessionSandboxDeps.gitLayout(args.root);
+    const credentialFiles = await _sessionSandboxDeps.credentialFiles(args.protectedPaths.credentialDir);
+    const approvalsFile = args.outputDir !== undefined ? approvalsPath(args.outputDir) : undefined;
+    // Before the policy: the confined roots include the session temp dir itself.
+    const { tempRoots, confined } = await sessionTempRoots({
+        config,
+        storyId: args.storyId,
+        runTmpRoot: args.runTmpRoot,
+        tmpDir: args.tmpDir,
+    });
+    const policyFor = async (root, tmpDirInForce) => buildSandboxPolicy({
+        root,
+        git,
+        // Per build, like the .nax entries: a worktree added mid-run gets its denies too.
+        gitGuardFiles: await _sessionSandboxDeps.gitGuardFiles(git),
+        naxEntries: await _sessionSandboxDeps.naxEntries(root, args.protectedPaths.projectStateDir),
+        credentialFiles,
+        ...(approvalsFile !== undefined ? { approvalsFile } : {}),
+        // US-006: a command inside the sandbox must not be able to rewrite the
+        // trust store that decides whether repository code runs.
+        trustStoreFile: args.protectedPaths.trustStoreFile,
+        home: _sessionSandboxDeps.homedir(),
+        tempRoots,
+        // #2301: the RESOLVED confinement, not `config.filesystem.allowSharedTmp`.
+        // A session confines only when that opt-out is off, a run root AND a
+        // session dir were both supplied, and the dir was actually created.
+        // `allowSharedTmp: false` is therefore no evidence of confinement — it also
+        // holds when the session dir could not be created and when no run root was
+        // supplied, and reading the flag would deny a darwin session that is
+        // running on the shared roots.
+        //
+        // Narrowed by whether THIS command will actually get the session's
+        // `TMPDIR`. `createCommandLauncher` recreates the session dir before every
+        // run and drops the `export TMPDIR=…` prefix when that creation fails
+        // (src/sandbox/launcher.ts), and then srt's own forced `TMPDIR`
+        // (`/tmp/claude`, sandbox-utils.js:630) is what the child gets — denying it
+        // would leave the session with a TMPDIR its own sandbox refuses to write,
+        // the one posture SPEC-tmp-confinement.md:132 rules out.
+        confined: confined && tmpDirInForce,
+        platform: _sessionSandboxDeps.platform(),
+        config,
+    });
+    // Review #17: literal() refuses a glob character in any policy path, and the
+    // probe builds its own policy, so a repo path like `re[x]po` passed the probe
+    // and then failed every command. Build the policy once here instead.
+    // The old residual (a glob-named feature dir created mid-run failing every
+    // command) is gone: listNaxEntries skips glob-named `.nax` entries (nax#2260).
+    const policyError = await literalPolicyError(policyFor, args.root, confined);
+    if (policyError !== undefined) {
+        warnSandboxUnavailableOnce(policyError, args.storyId);
+        return createCommandLauncher({ state: { kind: "unavailable", backend: backend.name, reason: policyError } });
+    }
+    const afterWrapped = await _sessionSandboxDeps.commonDirTripwire(git, args.storyId);
+    const network = config.network.allowedDomains ?? "open"; // absent = open (spec S2)
+    return createCommandLauncher({
+        // `sharedTmp` is present only when confined: absent means the shared temp
+        // roots are writable, which is what every pre-US-002 launcher says.
+        state: { kind: "available", backend: backend.name, network, ...(confined ? { sharedTmp: false } : {}) },
+        backend,
+        policyFor,
+        ...(afterWrapped !== undefined ? { afterWrapped } : {}),
+        ...(args.tmpDir !== undefined ? { tmpDir: args.tmpDir } : {}),
+    });
+}
+/** The compile-time policy refusal for `raw` (Task 8), or undefined. */
+export function rawRefusalFor(launcher) {
+    return launcher?.state.kind === "unavailable" ? rawBashRefusalReason(launcher.state.reason) : undefined;
+}
+/**
+ * US-004: whether the session's sandbox confines temp writes to this run's own
+ * temp root.
+ *
+ * True exactly when the launcher is available AND says `sharedTmp: false` —
+ * the only state under which the command guard may skip the classifier for a
+ * temp-only command (`src/agents/coding-tool-support.ts` → `tempConfined` →
+ * `src/command-safety/guard.ts:185`). An available launcher without
+ * `sharedTmp`, an unavailable or disabled one, and no launcher at all all read
+ * as NOT confined.
+ *
+ * That is the RESOLVE-time answer, fixed when the launcher is built, and it is
+ * deliberately NOT the answer the policy narrows on. `SandboxPolicyInput.confined`
+ * ANDs it with whether the per-command session-dir `mkdir` succeeded
+ * (`src/sandbox/launcher.ts:194`), because the `export TMPDIR=…` prefix rides on
+ * that same mkdir. So a session whose dir fails to re-create reports `true` here
+ * while the policy for that ONE command is the unconflined one, `/tmp/claude`
+ * included — which means the guard's temp-only exemption can be claimed for a
+ * command that is not in fact confined. Deliberate, and documented on
+ * `SandboxPolicyInput.confined` (`src/sandbox/policy-builder.ts:41-64`); do not
+ * reconcile the two by making either follow the other.
+ */
+export function isTempConfined(launcher) {
+    return launcher?.state.kind === "available" && launcher.state.sharedTmp === false;
+}
+/**
+ * US-002: the raw-screen options `compileToolPolicy` consumes, derived from the
+ * launcher's state.
+ *
+ * `rawBashRefusal` is exactly what `rawRefusalFor` returns (an unavailable
+ * launcher refuses every call). `sandboxWrapped: true` is added for an available
+ * launcher: the command really does run inside the OS sandbox, so the raw screen
+ * stops refusing a feature PRD the command only READS. A disabled launcher
+ * yields neither key.
+ */
+export function rawScreenOptionsFor(launcher) {
+    if (launcher?.state.kind === "available")
+        return { sandboxWrapped: true };
+    const rawBashRefusal = rawRefusalFor(launcher);
+    return rawBashRefusal !== undefined ? { rawBashRefusal } : {};
+}
+/**
+ * The compile-time policy refusal for `raw` (Task 8), or undefined.
+ *
+ * `resolvedConfinement` is the session's RESOLVE-time `confined`, not the
+ * per-launch `tmpDirInForce` this signature's second slot normally carries — a
+ * superset of it, since a launch can only narrow. That is deliberate: this probe
+ * exists to turn a glob refusal from `buildSandboxPolicy` into a session-level
+ * refusal, and the entries a narrower confinement differs by (#2301 — srt's
+ * `/tmp/claude` grant, present only when NOT confined) are fixed literals with no
+ * glob character. Passing the superset therefore exercises the strictest policy
+ * without risking a refusal a real launch would never hit.
+ */
+async function literalPolicyError(policyFor, root, resolvedConfinement) {
+    try {
+        await policyFor(root, resolvedConfinement);
+        return undefined;
+    }
+    catch (err) {
+        if (err instanceof NaxError && err.code === "SANDBOX_POLICY_NOT_LITERAL") {
+            return `[sandbox] a path in the sandbox policy contains a glob character: ${String(err.context?.path ?? "")}`;
+        }
+        throw err;
+    }
+}