@nathapp/nax-agent 0.1.0

package/dist/permissions/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Permission-subsystem types (spec 2026-09-13 native-permission-subsystem).
+ *
+ * Rules reuse the ToolGrant shape — {tool, patterns} — with the EFFECT carried
+ * by which list a rule sits in (allow/deny/ask), never inside the rule itself.
+ * Precedence is deny > ask > allow (spec R6) and is enforced where rules are
+ * evaluated (src/tools/policy.ts), not where they are declared.
+ */
+import type { BashApprovalMode } from "#src/config/bash-approval";
+import type { ToolGrant } from "#src/tools/index";
+/** What a matched `ask` rule needs answered before the call may run. */
+export interface AskRequest {
+    readonly tool: string;
+    /** PipelineStage at the time of the call; a plain string here to keep this
+     * module free of value imports from src/config. */
+    readonly stage: string;
+    /** The rule expression that matched, verbatim from config. */
+    readonly rule: string;
+    /**
+     * The ask rule that matched, verbatim. Set ONLY when an ask rule matched;
+     * absent when the ask is an `escalate`-mode grant miss, where `rule` falls
+     * back to the denial reason. A remembered approval derives its `origin`
+     * from this (#2249).
+     */
+    readonly matchedRule?: string;
+    /** One human-readable line describing the attempted call. */
+    readonly summary: string;
+    /**
+     * The command string VERBATIM, never truncated. `summary` is capped at 200
+     * chars for logs; a human deciding whether to permit a command must see all
+     * of it, or they are approving a string they never read.
+     */
+    readonly command?: string;
+    /**
+     * Set when the call's arguments contain a secret whose masked form could
+     * hide shell syntax (review #9). The human link denies without prompting.
+     */
+    readonly unshowable?: true;
+    /** The permitted root -- where the shell actually starts (src/tools/bash.ts:165). */
+    readonly root?: string;
+    /** The verdict's original reason, NOT rewritten as `matched ask rule "..."`. */
+    readonly reason?: string;
+    readonly storyId?: string;
+    readonly featureName?: string;
+}
+export type { ToolGrant };
+export interface ResolvedPermissions {
+    /**
+     * ACP permission mode string — the only resolved value anything consumes
+     * (`agents/acp/adapter.ts`, `runtime/middleware/audit.ts`).
+     */
+    mode: "approve-all" | "approve-reads" | "default";
+    /**
+     * Declarative grants — data, never matchers. Compiled into an enforceable
+     * policy by src/tools/, which keeps glob and filesystem semantics out of the
+     * config layer while the decision stays here, in the gated SSOT.
+     */
+    toolGrants?: readonly ToolGrant[];
+    /**
+     * Deny rules for the stage (spec R6: deny > ask > allow). Same {tool, patterns}
+     * shape as `toolGrants`; compiled and enforced by src/tools/.
+     */
+    denyRules?: readonly ToolGrant[];
+    /** Ask rules for the stage; resolved by an AskResolver at call time (spec R1). */
+    askRules?: readonly ToolGrant[];
+    /**
+     * How far provider (MCP) tools reach for this stage (spec R7).
+     *
+     * `all` — every attached provider, as `unrestricted` has always had it.
+     * `rules` — only what the stage's `Mcp(...)` rules admit (`scoped`).
+     * `none` — no provider tools at all (`safe`, and the fail-closed arm).
+     *
+     * Decided here rather than by the consumer because `scoped` and `safe` both
+     * resolve to the same MODE, so no consumer can tell them apart — and this is
+     * a permission decision, which lives in this file by rule.
+     */
+    providerScope?: "all" | "rules" | "none";
+    /**
+     * How a model-authored bash command string is adjudicated for this stage
+     * (ADR-030). Always present: the global default is `raw`, and a per-stage
+     * `permissions.<stage>.bashApproval` overrides it. Compiled into the policy
+     * by src/tools/, like the rule lists above — the DECISION stays here.
+     */
+    bashApproval: BashApprovalMode;
+}

package/dist/permissions/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/index.d.ts

@@ -0,0 +1,3 @@
+export { nodeRuntime, nodeSpawn } from "./node-runtime.ts";
+export { getAgentRuntime, runtimeSpawn, setAgentRuntime } from "./slot.ts";
+export type { AgentGlobOptions, AgentRuntime, AgentSpawnOptions, AgentSpawnResult, AgentSpawnStdin } from "./types.ts";

package/dist/runtime/index.js

@@ -0,0 +1,2 @@
+export { nodeRuntime, nodeSpawn } from "./node-runtime.js";
+export { getAgentRuntime, runtimeSpawn, setAgentRuntime } from "./slot.js";

package/dist/runtime/node-glob.d.ts

@@ -0,0 +1,3 @@
+import type { AgentGlobOptions } from "./types.ts";
+export declare function nodeGlob(pattern: string, opts: AgentGlobOptions): AsyncIterable<string>;
+export declare function nodeGlobSync(pattern: string, opts: AgentGlobOptions): Iterable<string>;

package/dist/runtime/node-glob.js

@@ -0,0 +1,83 @@
+/** Node glob normalized to the agent contract and Bun's symlink traversal. */
+import { globSync, lstatSync, statSync } from "node:fs";
+import { glob } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+function scanOptions(pattern, opts) {
+    const cwd = resolve(opts.cwd);
+    if (!statSync(cwd).isDirectory()) {
+        throw Object.assign(new Error(`ENOTDIR: not a directory, glob '${cwd}'`), { code: "ENOTDIR", path: cwd });
+    }
+    const prefix = [];
+    for (const part of pattern.split("/")) {
+        if (/[*?[{]/.test(part.replace(/\\./g, "")))
+            break;
+        prefix.push(part.replace(/\\(.)/g, "$1"));
+    }
+    const literalPrefix = relative(cwd, resolve(cwd, ...prefix));
+    const symlinks = new Map();
+    const blockedSymlink = (path) => {
+        if (literalPrefix === path || literalPrefix.startsWith(`${path}${sep}`))
+            return false;
+        if (!symlinks.has(path))
+            symlinks.set(path, lstatSync(resolve(cwd, path), { throwIfNoEntry: false })?.isSymbolicLink() ?? false);
+        return symlinks.get(path) === true;
+    };
+    const exclude = (entry) => {
+        const path = relative(cwd, resolve(cwd, entry.parentPath, entry.name));
+        if (path.split(sep).some((segment) => segment.startsWith(".")))
+            return true;
+        // Node can optimize brace/class segments without reporting their symlink
+        // entries. Check lexical ancestors too, allowing only the literal prefix.
+        const parts = path.split(sep);
+        for (let end = 1; end <= parts.length; end++) {
+            if (blockedSymlink(parts.slice(0, end).join(sep)))
+                return true;
+        }
+        return false;
+    };
+    return { cwd, withFileTypes: true, exclude };
+}
+function filePath(entry, cwd, absolute, pattern) {
+    const full = resolve(cwd, entry.parentPath, entry.name);
+    if (!entry.isFile() &&
+        !(!/[*?[{]/.test(pattern.replace(/\\./g, "")) &&
+            entry.isSymbolicLink() &&
+            statSync(full, { throwIfNoEntry: false })?.isFile()))
+        return null;
+    const path = relative(cwd, full);
+    if (path.split(sep).some((segment) => segment.startsWith(".")))
+        return null;
+    const dotPrefix = pattern.match(/^(?:\.\/)+/)?.[0] ?? "";
+    return absolute ? resolve(full) : `${dotPrefix}${path}`;
+}
+function nodePattern(pattern) {
+    // Node treats backslash escapes differently; character classes express the
+    // same literal metacharacters without changing the Bun-facing contract.
+    return pattern.replace(/\\([[\]*?{}])/g, (_escape, char) => `[${char}]`);
+}
+export async function* nodeGlob(pattern, opts) {
+    const options = scanOptions(pattern, opts);
+    const seen = new Set();
+    for await (const entry of glob(nodePattern(pattern), options)) {
+        if (options.exclude(entry))
+            continue;
+        const path = filePath(entry, options.cwd, opts.absolute, pattern);
+        if (path !== null && !seen.has(path)) {
+            seen.add(path);
+            yield path;
+        }
+    }
+}
+export function* nodeGlobSync(pattern, opts) {
+    const options = scanOptions(pattern, opts);
+    const seen = new Set();
+    for (const entry of globSync(nodePattern(pattern), options)) {
+        if (options.exclude(entry))
+            continue;
+        const path = filePath(entry, options.cwd, opts.absolute, pattern);
+        if (path !== null && !seen.has(path)) {
+            seen.add(path);
+            yield path;
+        }
+    }
+}

package/dist/runtime/node-runtime.d.ts

@@ -0,0 +1,3 @@
+import type { AgentRuntime, AgentSpawnOptions, AgentSpawnResult } from "./types.ts";
+export declare function nodeSpawn(cmd: readonly string[], opts: AgentSpawnOptions): AgentSpawnResult;
+export declare const nodeRuntime: AgentRuntime;

package/dist/runtime/node-runtime.js

@@ -0,0 +1,126 @@
+/**
+ * The default runtime: node:child_process adapted to AgentSpawnResult, normalised
+ * to Bun.spawn's measured behaviour (the spawn cases in @nathapp/nax-test-kit).
+ *
+ * Known difference, kept on purpose: with `env` omitted the child inherits the
+ * live process.env, where Bun passes the environment the process started with.
+ */
+import { spawn as spawnChild } from "node:child_process";
+import { statSync } from "node:fs";
+import { constants as osConstants } from "node:os";
+import { resolve } from "node:path";
+import { Readable } from "node:stream";
+import { nodeGlob, nodeGlobSync } from "./node-glob.js";
+import { which } from "./which.js";
+/** The search path a child gets when `env` is given without PATH (libuv's and Bun's default). */
+const DEFAULT_PATH = "/usr/bin:/bin";
+const ERRNO = { ENOENT: -2, ENOTDIR: -20, EACCES: -13 };
+function spawnError(code, message, path) {
+    return Object.assign(new Error(message), { code, errno: ERRNO[code], syscall: "posix_spawn", path });
+}
+/** Bun fails a spawn synchronously; child_process reports it later, so check first. */
+function precheck(cmd, opts) {
+    const bin = cmd[0];
+    if (bin === undefined || bin === "")
+        throw new TypeError("spawn: empty argv");
+    if (opts.cwd !== undefined) {
+        let isDirectory;
+        try {
+            isDirectory = statSync(opts.cwd).isDirectory();
+        }
+        catch {
+            throw spawnError("ENOENT", `ENOENT: no such file or directory, posix_spawn '${bin}'`, bin);
+        }
+        if (!isDirectory)
+            throw spawnError("ENOTDIR", `ENOTDIR: not a directory, posix_spawn '${bin}'`, bin);
+    }
+    // A child with no cwd inherits ours; "." resolves to it.
+    const cwd = opts.cwd ?? ".";
+    if (bin.includes("/")) {
+        try {
+            statSync(resolve(cwd, bin));
+        }
+        catch {
+            throw spawnError("ENOENT", `ENOENT: no such file or directory, posix_spawn '${bin}'`, bin);
+        }
+        if (which(bin, undefined, cwd) === null) {
+            throw spawnError("EACCES", `EACCES: permission denied, posix_spawn '${bin}'`, bin);
+        }
+        return bin;
+    }
+    // The child searches its own PATH: env's when env is given (or the default), the parent's otherwise.
+    const pathEnv = opts.env !== undefined ? (opts.env.PATH ?? DEFAULT_PATH) : process.env.PATH;
+    if (which(bin, pathEnv, cwd) === null) {
+        throw Object.assign(new Error(`Executable not found in $PATH: "${bin}"`), { code: "ENOENT", errno: -2, path: bin });
+    }
+    return bin;
+}
+function emptyStream() {
+    return new ReadableStream({ start: (controller) => controller.close() });
+}
+function definedEnv(env) {
+    return Object.fromEntries(Object.entries(env).filter((entry) => entry[1] !== undefined));
+}
+/** 128 + n for a signal exit, as Bun reports it. */
+function exitStatus(code, signal) {
+    if (code !== null)
+        return code;
+    return 128 + (signal !== null ? (osConstants.signals[signal] ?? 0) : 0);
+}
+function toWeb(stream) {
+    return stream === null ? emptyStream() : Readable.toWeb(stream);
+}
+export function nodeSpawn(cmd, opts) {
+    const bin = precheck(cmd, opts);
+    const child = spawnChild(bin, cmd.slice(1), {
+        cwd: opts.cwd,
+        env: opts.env !== undefined ? definedEnv(opts.env) : process.env,
+        stdio: [opts.stdin ?? "ignore", "pipe", opts.stderr],
+        detached: opts.detached === true,
+    });
+    // A broken pipe on stdin is swallowed, as Bun does; an unhandled 'error' event would crash the process.
+    child.stdin?.on("error", () => { });
+    if (child.pid === undefined) {
+        // The OS refused the spawn after the precheck passed (e.g. a script whose
+        // interpreter is missing). Node reports it on a later 'error' event; Bun throws
+        // here. Throw, and never hand back a process without a pid: a caller's group
+        // kill of an invalid pid would reach other processes.
+        child.once("error", () => { });
+        throw spawnError("ENOENT", `ENOENT: no such file or directory, posix_spawn '${bin}'`, bin);
+    }
+    // 'exit', not 'close': a grandchild still holding a pipe must not delay it (Bun resolves at exit).
+    const exited = new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("exit", (code, signal) => resolve(exitStatus(code, signal)));
+    });
+    const stdin = opts.stdin === "pipe" && child.stdin !== null
+        ? {
+            write: (data) => {
+                if (child.stdin !== null && !child.stdin.destroyed)
+                    child.stdin.write(data);
+                return typeof data === "string" ? Buffer.byteLength(data) : data.byteLength;
+            },
+            end: () => {
+                child.stdin?.end();
+            },
+            flush: () => { },
+        }
+        : undefined;
+    return {
+        stdout: toWeb(child.stdout),
+        stderr: opts.stderr === "pipe" ? toWeb(child.stderr) : emptyStream(),
+        exited,
+        pid: child.pid,
+        stdin,
+        get exitCode() {
+            return child.exitCode;
+        },
+        get signalCode() {
+            return child.signalCode;
+        },
+        kill: (signal) => {
+            child.kill(signal);
+        },
+    };
+}
+export const nodeRuntime = { spawn: nodeSpawn, glob: nodeGlob, globSync: nodeGlobSync };

package/dist/runtime/slot.d.ts

@@ -0,0 +1,11 @@
+import type { AgentRuntime } from "./types.ts";
+/**
+ * Install (or, with `null`, clear) the process-wide runtime. nax installs its
+ * Bun runtime at startup; an embedder may install its own. Like the logger
+ * slot, it is module-level; S3 decides whether it becomes per-session.
+ */
+export declare function setAgentRuntime(runtime: AgentRuntime | null): void;
+/** The installed runtime, or the Node default. */
+export declare function getAgentRuntime(): AgentRuntime;
+/** Spawn through whatever runtime is installed at the moment of the call. */
+export declare const runtimeSpawn: AgentRuntime["spawn"];

package/dist/runtime/slot.js

@@ -0,0 +1,17 @@
+import { nodeRuntime } from "./node-runtime.js";
+let installed = null;
+/**
+ * Install (or, with `null`, clear) the process-wide runtime. nax installs its
+ * Bun runtime at startup; an embedder may install its own. Like the logger
+ * slot, it is module-level; S3 decides whether it becomes per-session.
+ */
+export function setAgentRuntime(runtime) {
+    installed = runtime;
+}
+/** The installed runtime, or the Node default. */
+export function getAgentRuntime() {
+    return installed ?? nodeRuntime;
+}
+/** Spawn through whatever runtime is installed at the moment of the call. */
+// nax-git-env-allow: pass-through to the installed runtime; git callers pass hardenedGitEnv themselves
+export const runtimeSpawn = (cmd, opts) => getAgentRuntime().spawn(cmd, opts);

package/dist/runtime/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The process-spawning contract nax-agent's tools run through (spec S2 §4.2).
+ * The shape records Bun.spawn's measured behaviour; the Node default
+ * (node-runtime.ts) normalises to it, and nax installs Bun.spawn itself.
+ *
+ * Distinct from nax's own `SpawnOptions`/`SpawnResult` (packages/nax/src/utils/
+ * bun-deps.ts), which describe nax's direct Bun.spawn wrapper.
+ */
+export interface AgentSpawnOptions {
+    cwd?: string;
+    stdin?: "pipe" | "inherit";
+    stdout: "pipe";
+    stderr: "pipe" | "inherit";
+    /** Replaces the environment; `undefined` values are dropped. Omitted: inherit. */
+    env?: Record<string, string | undefined>;
+    /** setsid: the child becomes its own process-group leader, so a group kill reaches its descendants (ORPHAN-1). */
+    detached?: boolean;
+}
+export interface AgentSpawnStdin {
+    /** Returns the number of bytes written. Never throws for a child that already exited. */
+    write(data: string | Uint8Array): number;
+    end(): void;
+    flush(): void;
+}
+export interface AgentSpawnResult {
+    readonly stdout: ReadableStream<Uint8Array>;
+    /** With `stderr: "inherit"` there is nothing to read; callers that inherit never read it. */
+    readonly stderr: ReadableStream<Uint8Array>;
+    /** The exit code, or 128 + the signal number for a signal exit. Resolves at exit, not when the pipes close. */
+    readonly exited: Promise<number>;
+    readonly pid: number;
+    readonly stdin?: AgentSpawnStdin;
+    /** `null` until exit, and after a signal exit. */
+    readonly exitCode: number | null;
+    readonly signalCode: string | null;
+    kill(signal?: number | NodeJS.Signals): void;
+}
+/**
+ * The slot's contract. `spawn` throws synchronously when the process cannot be
+ * started (missing binary, missing or non-directory cwd, not executable).
+ */
+export interface AgentGlobOptions {
+    cwd: string;
+    absolute: boolean;
+}
+export interface AgentRuntime {
+    spawn(cmd: readonly string[], opts: AgentSpawnOptions): AgentSpawnResult;
+    /** Files only, no hidden result-relative segments; cwd failures propagate. */
+    glob(pattern: string, opts: AgentGlobOptions): AsyncIterable<string>;
+    globSync(pattern: string, opts: AgentGlobOptions): Iterable<string>;
+}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/which.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The first executable regular file named `name` on `pathEnv` (POSIX; Windows is
+ * unsupported, as for nax). A name containing "/" is checked as a path. Relative
+ * paths and relative PATH entries resolve against `cwd`, as the spawned child sees them.
+ */
+export declare function which(name: string, pathEnv?: string | undefined, 
+/** Defaults to "." : relative to the current directory, which a child with no cwd inherits. */
+cwd?: string): string | null;

package/dist/runtime/which.js

@@ -0,0 +1,32 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, join, resolve } from "node:path";
+function isExecutableFile(path) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The first executable regular file named `name` on `pathEnv` (POSIX; Windows is
+ * unsupported, as for nax). A name containing "/" is checked as a path. Relative
+ * paths and relative PATH entries resolve against `cwd`, as the spawned child sees them.
+ */
+export function which(name, pathEnv = process.env.PATH, 
+/** Defaults to "." : relative to the current directory, which a child with no cwd inherits. */
+cwd = ".") {
+    if (name.includes("/"))
+        return isExecutableFile(resolve(cwd, name)) ? name : null;
+    for (const dir of (pathEnv ?? "").split(delimiter)) {
+        if (dir === "")
+            continue;
+        const candidate = join(resolve(cwd, dir), name);
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return null;
+}

package/dist/sandbox/argv-quote.d.ts

@@ -0,0 +1,11 @@
+/**
+ * POSIX single-quote quoting for RunCommand's Exec branch under the sandbox.
+ *
+ * srt wraps a command STRING that runs under `sh -c`, so a sandboxed Exec
+ * call becomes `sh -c '<argv, each element quoted>'`. Inside single quotes
+ * nothing is special, and an embedded quote is closed, escaped and reopened
+ * ('\''), so the mapping is injective and no metacharacter is ever
+ * interpreted. Lives here, not in run-command-exec.ts, whose whole-file guard
+ * forbids a shell-quoting import.
+ */
+export declare function quoteArgvForShell(argv: readonly string[]): string;

package/dist/sandbox/argv-quote.js

@@ -0,0 +1,13 @@
+/**
+ * POSIX single-quote quoting for RunCommand's Exec branch under the sandbox.
+ *
+ * srt wraps a command STRING that runs under `sh -c`, so a sandboxed Exec
+ * call becomes `sh -c '<argv, each element quoted>'`. Inside single quotes
+ * nothing is special, and an embedded quote is closed, escaped and reopened
+ * ('\''), so the mapping is injective and no metacharacter is ever
+ * interpreted. Lives here, not in run-command-exec.ts, whose whole-file guard
+ * forbids a shell-quoting import.
+ */
+export function quoteArgvForShell(argv) {
+    return argv.map((arg) => `'${arg.replaceAll("'", "'\\''")}'`).join(" ");
+}

package/dist/sandbox/defaults.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Built-in sandbox lists (spec 5.3). One auditable constant each; extend a
+ * project's set through `execution.sandbox.filesystem`, not by editing these.
+ */
+/** Package-manager caches, relative to $HOME. The bun cache is REQUIRED: bun stages temp files there (spec F3). */
+export declare const BUILTIN_CACHE_WRITE_ROOTS: readonly string[];
+/** macOS-only cache root, relative to $HOME. */
+export declare const MACOS_CACHE_WRITE_ROOT = "Library/Caches";
+/** srt forces TMPDIR to this inside the macOS sandbox and does not create it (spec F3). */
+export declare const SRT_MACOS_TMPDIR = "/tmp/claude";
+/**
+ * #2301 — the same directory as `SRT_MACOS_TMPDIR`, named through macOS's
+ * `/tmp` -> `/private/tmp` symlink. srt force-allows both spellings, and which of
+ * them survives nax's own `realOrRaw` depends on the host, so a deny names both.
+ */
+export declare const SRT_MACOS_TMPDIR_PRIVATE_SPELLING = "/private/tmp/claude";
+/**
+ * #2301 — both spellings of srt's forced TMPDIR, as a deny list.
+ *
+ * srt always includes `/tmp/claude` and `/private/tmp/claude` in
+ * `SANDBOX_OWN_WRITE_PATHS` and `getDefaultWritePaths` never drops them, so the
+ * only way to take the write back is an explicit `denyWrite` — srt renders its
+ * allow rules before its deny rules in a macOS profile, where the later deny wins.
+ */
+export declare const SRT_MACOS_TMPDIR_DENIES: readonly string[];
+/** Credential stores the agent's commands may not read, relative to $HOME. nax's own credential files are listed separately (they live under globalConfigDir()). */
+export declare const BUILTIN_CREDENTIAL_READ_DENIES: readonly string[];

package/dist/sandbox/defaults.js

@@ -0,0 +1,47 @@
+/**
+ * Built-in sandbox lists (spec 5.3). One auditable constant each; extend a
+ * project's set through `execution.sandbox.filesystem`, not by editing these.
+ */
+/** Package-manager caches, relative to $HOME. The bun cache is REQUIRED: bun stages temp files there (spec F3). */
+export const BUILTIN_CACHE_WRITE_ROOTS = [
+    ".bun/install/cache",
+    ".npm",
+    ".cache",
+    ".cargo/registry",
+    ".cargo/git",
+    "go/pkg/mod",
+    ".gradle/caches",
+    ".m2/repository",
+    ".pnpm-store",
+];
+/** macOS-only cache root, relative to $HOME. */
+export const MACOS_CACHE_WRITE_ROOT = "Library/Caches";
+/** srt forces TMPDIR to this inside the macOS sandbox and does not create it (spec F3). */
+export const SRT_MACOS_TMPDIR = "/tmp/claude";
+/**
+ * #2301 — the same directory as `SRT_MACOS_TMPDIR`, named through macOS's
+ * `/tmp` -> `/private/tmp` symlink. srt force-allows both spellings, and which of
+ * them survives nax's own `realOrRaw` depends on the host, so a deny names both.
+ */
+export const SRT_MACOS_TMPDIR_PRIVATE_SPELLING = "/private/tmp/claude";
+/**
+ * #2301 — both spellings of srt's forced TMPDIR, as a deny list.
+ *
+ * srt always includes `/tmp/claude` and `/private/tmp/claude` in
+ * `SANDBOX_OWN_WRITE_PATHS` and `getDefaultWritePaths` never drops them, so the
+ * only way to take the write back is an explicit `denyWrite` — srt renders its
+ * allow rules before its deny rules in a macOS profile, where the later deny wins.
+ */
+export const SRT_MACOS_TMPDIR_DENIES = [SRT_MACOS_TMPDIR, SRT_MACOS_TMPDIR_PRIVATE_SPELLING];
+/** Credential stores the agent's commands may not read, relative to $HOME. nax's own credential files are listed separately (they live under globalConfigDir()). */
+export const BUILTIN_CREDENTIAL_READ_DENIES = [
+    ".ssh",
+    ".aws",
+    ".config/gcloud",
+    ".docker/config.json",
+    ".netrc",
+    ".npmrc",
+    ".pypirc",
+    ".git-credentials",
+    ".config/gh",
+];

package/dist/sandbox/git-guards.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The I/O half of the sandbox's git guards (#2198): the git-read files that
+ * redirect where git finds its config and hooks, as they exist on disk now.
+ *
+ * A sandboxed command that repoints one of these at an agent-authored
+ * directory (its own `config` with core.hooksPath / core.fsmonitor) makes
+ * nax's next UNSANDBOXED git run agent code. The redirecting files are:
+ * `<common>/commondir`, and for every linked worktree `worktrees/<id>/`
+ * `{gitdir, commondir, config.worktree}` plus the worktree's `.git` pointer.
+ *
+ * Only files that EXIST are denied here: srt on Linux stubs an absent deny
+ * with an empty file (host-side too, while the command runs), and git dies
+ * reading an empty `commondir` / `gitdir` -- inside the sandbox and in any
+ * concurrent nax git. An absent `<common>/commondir` is therefore guarded by
+ * a tripwire instead (strayCommonDirTripwire). `config.worktree` is the
+ * exception: an empty one is valid config, so it is always denied.
+ *
+ * The tripwire is what protects a main checkout, whose git dir sits inside the
+ * root write root. In a linked worktree the common dir is not a write root at
+ * all (WORKTREE_COMMON_WRITE_DIRS, #2211), so the file cannot be created there
+ * and the tripwire is only a second line.
+ */
+import { readdir } from "node:fs/promises";
+import type { GitLayout } from "./policy-inputs.ts";
+export declare const WORKTREE_CONFIG_FILE = "config.worktree";
+/**
+ * What a linked worktree's git writes in the SHARED common dir (#2211): loose
+ * and packed objects, refs and their reflogs (`reftable/` holds both when
+ * `extensions.refStorage=reftable`, git >= 2.45), and git-lfs's object store.
+ * Only these are write roots, never the common dir itself, so the redirecting
+ * files at its top level (`commondir`, `config`, `hooks/`) and every sibling
+ * worktree's admin dir lie outside the sandbox's writes. `modules/` is left
+ * out on purpose: it holds submodule git dirs, each with its own config.
+ *
+ * Cost: a lock file at the common dir's top level cannot be created, so a
+ * sandboxed command cannot rewrite `packed-refs` (deleting a packed branch or
+ * tag) or take the `gc --auto` lock; commits, loose ref updates and fetches
+ * into loose objects are unaffected. (A reftable repo locks inside
+ * `reftable/`, so it keeps ref deletion too.)
+ */
+export declare const WORKTREE_COMMON_WRITE_DIRS: readonly string[];
+export declare const _gitGuardDeps: {
+    readdir: typeof readdir;
+    exists: (p: string) => Promise<boolean>;
+    readText: (p: string) => Promise<string>;
+    remove: (p: string) => Promise<void>;
+};
+/** The directory holding the shared config/hooks: the git dir itself for a main checkout. */
+export declare function commonDirOf(git: GitLayout): string | undefined;
+/**
+ * Every redirecting git file for the repo that `git` describes, for every
+ * worktree registered when the policy is built (literal paths: srt on Linux
+ * drops glob denies).
+ */
+export declare function listGitGuardFiles(git: GitLayout): Promise<string[]>;
+/**
+ * `<common>/commondir` never legitimately exists (git reads it only from a
+ * linked worktree's own git dir), and an absent one cannot be denied on Linux
+ * (see the header). So when it is absent at session start, one created by a
+ * sandboxed command is removed after that command, before nax's next git.
+ * Returns undefined when there is nothing to guard (no repo, or the file
+ * already exists -- listGitGuardFiles then denies it outright).
+ */
+export declare function strayCommonDirTripwire(git: GitLayout, storyId?: string): Promise<(() => Promise<void>) | undefined>;