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

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to `@nathapp/nax-agent` are recorded here. The format follow
 [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.89.0] - 2026-10-17
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
+## [0.88.0] - 2026-10-16
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
 ## [0.88.0-canary.2] - 2026-10-15
 
 - No changes in this package. Released in lockstep with the other nax packages.

package/README.md

@@ -34,9 +34,9 @@ The host installs these once, near startup. They are module-level, so they apply
 
 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.
+- **`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. `createAgentSession` does not accept a runner yet: `hostPorts.runDeclaredCommand` throws `AGENT_SESSION_INVALID_OPTIONS`, so a session's `RunCommand` always refuses.
+- **`ProtectedPathsPolicy`** (`hostPorts.protectedPaths` on the facade) 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`** (`hostPorts.commandInterceptor` on the facade) 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.
 
 ## Repository instructions
 
@@ -62,7 +62,7 @@ const lookupOrder: EmbedderTool = {
 };
 
 const session = await createAgentSession({
-  backend: nativeBackend({ model: "anthropic/claude-sonnet-5-5" }),
+  backend: nativeBackend({ model: "openai/gpt-5.4-mini" }),
   profile: "ask",
   workdir: "/abs/project",
   tools: [lookupOrder],
@@ -82,8 +82,9 @@ Profiles set what a session may do:
 | Profile | Side effects |
 |:--------|:-------------|
 | `none` | no side effects; |
-| `read` | read-only; |
-| `ask` | every Write, Edit, Delete, GitCommit and Bash is put to `answer()`; |
+| `read` | read-only tools (Read, Glob, Grep, Git); |
+| `review` | the read tools plus Bash; `bashApproval` and the sandbox floor apply; |
+| `ask` | Write, Edit, Delete and GitCommit are put to `answer()`; Bash follows `bashApproval`; |
 | `full` | no prompts; `bashApproval` and the sandbox floor apply. |
 
 `createAgentSession` takes a `SessionBackend`. `nativeBackend(opts)` takes `instructionFileName` (default `AGENTS.md`), `model`, `credentials`, `catalogOverrides`, `loopHandlers`, `hostPorts`, `bashApproval`, `allowUnsandboxed` and `compaction`. The ACP backend ships in `@nathapp/nax-agent-acp`.
@@ -97,7 +98,7 @@ Profiles set what a session may do:
 - **Approvals and questions.** Answer them with `session.answer(requestId, { decision: "allow" | "deny" })` or `{ text }`. An unanswered one is denied after `approvalTimeoutMs` (default 600000, range 30000..3600000). `answer` returns `"accepted"`, `"expired"`, `"cancelled"` or `"unknown"`.
 - **Credentials.** A session's `credentials` (`memory` or `exec`) and `catalogOverrides` give it its own client. Without them it uses the process-wide `configureCredentials` slot.
 - **History and restarts.** The store holds one document per session, saved at the end of every turn. `close()` keeps it. After a restart, `resumeAgentSession(sessionId, options)` reopens it with the same options you created it with; pass `instructions` and `tools` again, since they are not stored. If the process died mid-turn, `session.lastTurn` is `{ turnId, status: "interrupted" }`, and that turn's message is not in history. A resume with a different model throws `AGENT_SESSION_MODEL_MISMATCH`; a different reasoning effort (`[high]`) is the same model. Resuming with a different backend kind throws `AGENT_SESSION_BACKEND_MISMATCH`; a stored document with no `backend` field is native. Do not open one session id twice at once: the store has no lock.
-- **Errors.** Every error is an `AgentSessionError` with a code `AGENT_SESSION_*`: `INVALID_OPTIONS`, `EXISTS`, `BUSY`, `CLOSED`, `INVALID_ANSWER`, `NOT_FOUND`, `SCHEMA_UNSUPPORTED`, `MODEL_MISMATCH`, `SANDBOX_UNAVAILABLE`, `TOOL_NAME_RESERVED`, `BACKEND_UNAVAILABLE`, `AUTH_REQUIRED`, `CAPABILITY_UNSUPPORTED` or `BACKEND_MISMATCH`. A stored document that cannot be read is a `NaxError` with `TRANSCRIPT_CORRUPT`.
+- **Errors.** Every error is an `AgentSessionError` with a code `AGENT_SESSION_*`: `INVALID_OPTIONS`, `EXISTS`, `BUSY`, `CLOSED`, `INVALID_ANSWER`, `NOT_FOUND`, `SCHEMA_UNSUPPORTED`, `MODEL_MISMATCH`, `SANDBOX_UNAVAILABLE`, `TOOL_NAME_RESERVED`, `BACKEND_UNAVAILABLE`, `AUTH_REQUIRED`, `RATE_LIMITED`, `CAPABILITY_UNSUPPORTED` or `BACKEND_MISMATCH`. A stored document that cannot be read is a `NaxError` with `TRANSCRIPT_CORRUPT`.
 
 ## MCP connections (`@nathapp/nax-agent/mcp`)
 
@@ -127,10 +128,10 @@ await connection.close();                           // waits for the process; SI
 
 ## Status and roadmap
 
-`0.x` may reshape `.` with a minor bump. `@nathapp/nax-agent-acp` provides an ACP backend for the same API (0.3.0). See [`CHANGELOG.md`](CHANGELOG.md).
+`0.x` may reshape `.` with a minor bump. `@nathapp/nax-agent-acp` provides an ACP backend for the same API. Both packages share one version. 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.
+Maintainers: releases are lockstep and tag-driven; see the [repo-root release procedure](https://github.com/nathapp-io/nax/blob/main/RELEASING.md).
+The package's [`RELEASING.md`](RELEASING.md) keeps its acceptance records.
 
 ## License
 

package/dist/mcp/connect.js

@@ -102,6 +102,18 @@ export async function connectMcp(config, opts) {
     try {
         if (signal.aborted)
             throw new McpConnectError("MCP connect failed: aborted");
+        if (config.kind === "stdio" && opts.onSpawn !== undefined) {
+            const start = handle.transport.start;
+            let notified = false;
+            handle.transport.start = async function () {
+                await start.call(this);
+                const pid = handle.pid();
+                if (pid !== null && !notified) {
+                    notified = true;
+                    opts.onSpawn?.(pid);
+                }
+            };
+        }
         await client.connect(handle.transport, { signal, timeout: opts.timeoutMs });
         const tools = await listAll(client, signal, opts.timeoutMs);
         return liveConnection(config, client, handle, tools, {

package/dist/mcp/types.d.ts

@@ -51,6 +51,8 @@ export interface ConnectMcpOptions {
         readonly name: string;
         readonly version: string;
     };
+    /** stdio only: called once after spawn, before the initialize request is sent. */
+    readonly onSpawn?: (pid: number) => void;
     /** stdio: how long close() waits for the process before SIGKILL. Default 3000. */
     readonly closeGraceMs?: number;
 }

package/dist/native/session/turn-retry.d.ts

@@ -80,9 +80,9 @@ export declare function turnRetryFitsBudget(delayMs: number, remainingMs: number
  * nax-ai's retry.ts `abortableSleep` so a pending backoff cannot outlive the
  * caller's own cancellation and go on to start a request nobody wants.
  */
-export declare function abortableSleep(ms: number, sleep: (ms: number) => Promise<void>, signal?: AbortSignal): Promise<void>;
+export declare function abortableSleep(ms: number, sleep: (ms: number, signal?: AbortSignal) => Promise<void>, signal?: AbortSignal): Promise<void>;
 /** The real timer. Named and exported so the only production wiring of it is one reference. */
-export declare function realSleep(ms: number): Promise<void>;
+export declare function realSleep(ms: number, signal?: AbortSignal): Promise<void>;
 export interface TurnRetryDeps<T> {
     /** Re-issues the round trip. Called once per retry, never for the triggering attempt. */
     readonly attempt: () => Promise<T>;
@@ -99,7 +99,7 @@ export interface TurnRetryDeps<T> {
      * and leaving it optional let a test omit it and silently wait out a real
      * multi-second backoff. Required makes that a compile error instead.
      */
-    readonly sleep: (ms: number) => Promise<void>;
+    readonly sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
     /** Injectable jitter source, for deterministic tests. Defaults to Math.random. */
     readonly random?: () => number;
     /** Fired once per retry, before the backoff delay, with a 1-based retry number. */

package/dist/native/session/turn-retry.js

@@ -104,7 +104,7 @@ export function turnRetryFitsBudget(delayMs, remainingMs) {
     return remainingMs === undefined || delayMs <= remainingMs;
 }
 function abortError(signal) {
-    return signal.reason ?? new DOMException("Aborted", "AbortError");
+    return signal?.reason ?? new DOMException("Aborted", "AbortError");
 }
 /**
  * A sleep that resolves early, and rejects, when `signal` fires — mirrors
@@ -113,21 +113,40 @@ function abortError(signal) {
  */
 export function abortableSleep(ms, sleep, signal) {
     if (signal === undefined)
-        return sleep(ms);
+        return sleep(ms, signal);
     if (signal.aborted)
         return Promise.reject(abortError(signal));
     return new Promise((resolve, reject) => {
         const onAbort = () => reject(abortError(signal));
         signal.addEventListener("abort", onAbort, { once: true });
-        sleep(ms).then(() => {
+        // Keep the race for injected sleeps that do not honour cancellation.
+        Promise.resolve()
+            .then(() => sleep(ms, signal))
+            .then(() => {
             signal.removeEventListener("abort", onAbort);
             resolve();
-        }, reject);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
     });
 }
 /** The real timer. Named and exported so the only production wiring of it is one reference. */
-export function realSleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+export function realSleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(abortError(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError(signal));
+        };
+        // Cancellable timer: abort must release the pending backoff immediately.
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
 }
 /**
  * Retries `attempt` while the thrown error is a transport/overloaded fault,

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

@@ -97,7 +97,7 @@ export interface TurnDeps {
      * actually wait (forbidden-patterns-tests.md). Absent uses a real timer —
      * a real session always wants to actually wait.
      */
-    sleep?: (ms: number) => Promise<void>;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     /**
      * Live repetition-breaker instance (nax#2013, session-lifetime since #2047). Absent disables the breaker.
      */

package/dist/tools/bash-canonical.d.ts

@@ -0,0 +1,10 @@
+/** Deny/ask-only views of Bash commands. Never use these views to grant or check paths. */
+import { type BashSegment } from "#src/permissions/index";
+export type CanonicalResult = {
+    readonly kind: "ok";
+    readonly segments: readonly BashSegment[];
+} | {
+    readonly kind: "refused";
+    readonly reason: string;
+};
+export declare function canonicalSegments(segment: BashSegment): CanonicalResult;

package/dist/tools/bash-canonical.js

@@ -0,0 +1,207 @@
+/** Deny/ask-only views of Bash commands. Never use these views to grant or check paths. */
+import { lexBashCommand } from "#src/permissions/index";
+// Deliberately separate from commandHeadIndex: this policy must refuse unknown
+// wrapper options rather than guess whether the next word names the executable.
+const WRAPPERS = {
+    env: { flags: ["-i", "--ignore-environment"], values: ["-u", "--unset"] },
+    command: { flags: ["-p"], values: [] },
+    exec: { flags: ["-c", "-l"], values: ["-a"] },
+    time: { flags: ["-p"], values: [] },
+    nohup: { flags: [], values: [] },
+    nice: { flags: [], values: ["-n", "--adjustment"] },
+    timeout: {
+        flags: ["--foreground", "--preserve-status", "-v", "--verbose"],
+        values: ["-k", "--kill-after", "-s", "--signal"],
+    },
+    stdbuf: { flags: [], values: ["-i", "-o", "-e", "--input", "--output", "--error"] },
+    xargs: {
+        flags: ["-0", "--null", "-r", "--no-run-if-empty", "-t", "--verbose", "-p", "--interactive", "-x", "--exit"],
+        values: [
+            "-I",
+            "-n",
+            "-P",
+            "-d",
+            "-E",
+            "-L",
+            "-s",
+            "-a",
+            "--replace",
+            "--max-args",
+            "--max-procs",
+            "--delimiter",
+            "--eof",
+            "--max-lines",
+            "--max-chars",
+            "--arg-file",
+        ],
+    },
+    busybox: { flags: [], values: [] },
+    sudo: {
+        flags: [
+            "-A",
+            "-b",
+            "-E",
+            "-H",
+            "-K",
+            "-k",
+            "-n",
+            "-S",
+            "--askpass",
+            "--background",
+            "--preserve-env",
+            "--set-home",
+            "--non-interactive",
+            "--stdin",
+        ],
+        values: [
+            "-u",
+            "-g",
+            "-h",
+            "-D",
+            "-C",
+            "-p",
+            "-r",
+            "-t",
+            "-U",
+            "--user",
+            "--group",
+            "--host",
+            "--chdir",
+            "--close-from",
+            "--prompt",
+            "--role",
+            "--type",
+            "--other-user",
+        ],
+    },
+    doas: { flags: ["-n", "-s", "-L"], values: ["-u", "-C"] },
+};
+const GIT_OPTIONS = {
+    flags: ["--no-pager", "-p", "--paginate", "--bare", "--literal-pathspecs", "--no-replace-objects"],
+    values: ["-C", "-c", "--git-dir", "--work-tree", "--namespace"],
+};
+const KEYWORDS = new Set(["if", "then", "else", "elif", "do", "while", "until", "{"]);
+const CLOSERS = new Set(["fi", "done", "}"]);
+const SHELLS = new Set(["sh", "bash", "dash", "zsh", "ksh"]);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+function refused(reason) {
+    return { kind: "refused", reason: `Bash canonical analysis refused: ${reason}` };
+}
+/** Number of tokens an option consumes; undefined means it is unknown. */
+function optionWidth(word, options) {
+    if (options.flags.includes(word))
+        return 1;
+    if (options.values.includes(word))
+        return 2;
+    if (options.values.some((flag) => flag.startsWith("--") ? word.startsWith(`${flag}=`) : word.startsWith(flag) && word.length > flag.length))
+        return 1;
+    // Short boolean options may be clustered (sudo -nE, for example).
+    if (/^-[A-Za-z0-9]+$/.test(word) && [...word.slice(1)].every((letter) => options.flags.includes(`-${letter}`)))
+        return 1;
+    return undefined;
+}
+function afterOptions(tokens, start, options) {
+    let i = start;
+    while (tokens[i]?.text.startsWith("-")) {
+        const token = tokens[i];
+        if (token.opaque)
+            return "opaque wrapper option";
+        if (token.text === "--")
+            return i + 1;
+        const width = optionWidth(token.text, options);
+        if (width === undefined)
+            return `unknown option ${token.text}`;
+        if (width === 2 && tokens[i + 1] === undefined)
+            return `missing value for ${token.text}`;
+        i += width;
+    }
+    return i;
+}
+/** Locate only the shell's command-string operand, never a script's arguments. */
+function shellPayload(tokens) {
+    for (let i = 1; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        const word = token.text;
+        if ((!word.startsWith("-") && !word.startsWith("+")) || word === "--")
+            return undefined;
+        if (token.opaque)
+            return "opaque shell option";
+        if (word === "-o" || word === "+o" || word === "-O" || word === "--rcfile" || word === "--init-file") {
+            i += 1;
+            continue;
+        }
+        if (/^-[A-Za-z]*c[A-Za-z]*$/.test(word))
+            return tokens[i + 1] ?? "missing shell command string";
+    }
+    return undefined;
+}
+function stripPrefixes(input) {
+    let tokens = input;
+    for (;;) {
+        const head = tokens[0];
+        if (head === undefined)
+            return [];
+        if (head.opaque)
+            return "opaque command head";
+        if (KEYWORDS.has(head.text) || ASSIGNMENT.test(head.text)) {
+            tokens = tokens.slice(1);
+            continue;
+        }
+        const wrapper = Object.hasOwn(WRAPPERS, head.text) ? WRAPPERS[head.text] : undefined;
+        if (wrapper === undefined)
+            break;
+        const next = afterOptions(tokens, 1, wrapper);
+        if (typeof next === "string")
+            return `${head.text}: ${next}`;
+        const command = head.text === "timeout" ? next + 1 : next;
+        if (head.text === "timeout" && tokens[next] === undefined)
+            return "missing timeout duration";
+        tokens = tokens.slice(command);
+    }
+    return tokens;
+}
+function expandShell(payload, depth) {
+    if (depth >= 3)
+        return refused("shell command strings nest deeper than 3 levels");
+    if (payload.opaque)
+        return refused("opaque shell command string");
+    const lexed = lexBashCommand(payload.text);
+    if (lexed.kind === "refused")
+        return refused(`shell command string contains ${lexed.construct}`);
+    const segments = [];
+    for (const nested of lexed.segments) {
+        const result = canonicalise(nested, depth + 1);
+        if (result.kind === "refused")
+            return result;
+        segments.push(...result.segments);
+    }
+    return { kind: "ok", segments };
+}
+function canonicalise(segment, depth) {
+    const stripped = stripPrefixes(segment.tokens);
+    if (typeof stripped === "string")
+        return refused(stripped);
+    let tokens = stripped;
+    if (tokens.length === 0)
+        return { kind: "ok", segments: [] };
+    if (tokens.length === 1 && CLOSERS.has(tokens[0]?.text ?? ""))
+        return { kind: "ok", segments: [] };
+    if (tokens[0]?.text === "git") {
+        const next = afterOptions(tokens, 1, GIT_OPTIONS);
+        if (typeof next === "string")
+            return refused(`git: ${next}`);
+        tokens = [tokens[0], ...tokens.slice(next)];
+    }
+    const head = tokens[0]?.text.split("/").pop() ?? "";
+    if (SHELLS.has(head)) {
+        const payload = shellPayload(tokens);
+        if (typeof payload === "string")
+            return refused(payload);
+        if (payload !== undefined)
+            return expandShell(payload, depth);
+    }
+    return { kind: "ok", segments: [{ ...segment, tokens }] };
+}
+export function canonicalSegments(segment) {
+    return canonicalise(segment, 0);
+}

package/dist/tools/nax-revert.d.ts

@@ -26,9 +26,21 @@ export declare function operandTouchesNax(operand: string, ctx: NaxGuardContext)
  * under `top`), so they count only while that is the single `.nax` there is.
  */
 export declare function isFullNaxExclusion(spec: string, ctx: NaxGuardContext): boolean;
+interface Operands {
+    /** Non-option words before `--`. */
+    readonly before: readonly string[];
+    /** Words after `--`. */
+    readonly after: readonly string[];
+    readonly hasSeparator: boolean;
+    readonly flags: readonly string[];
+}
+export declare function splitOperands(verb: string, args: readonly string[]): Operands;
+/** True when `spec` selects a directory that holds one of the `.nax` directories (or all of them, from the top). */
+export declare function coversNax(spec: string, ctx: NaxGuardContext, nax: readonly string[]): boolean;
 /** The refusal for `git checkout` / `git restore` with these arguments, or undefined. */
 export declare function revertRefusal(verb: string, args: readonly string[], ctx: NaxGuardContext): string | undefined;
 /** `git reset --hard` / `--keep` / `--merge` (any abbreviation git accepts) while a `.nax/` exists. */
 export declare function resetRefusal(args: readonly string[], ctx: NaxGuardContext): string | undefined;
 /** `switch -f`, `clean`, `checkout-index -a -f`, `read-tree -u --reset`: other ways to wipe the tree. */
 export declare function discardRefusal(verb: string, args: readonly string[], ctx: NaxGuardContext): string | undefined;
+export {};

package/dist/tools/nax-revert.js

@@ -93,7 +93,7 @@ const VALUE_FLAGS = {
     restore: new Set(["-s", "--source", "--pathspec-from-file"]),
     clean: new Set(["-e", "--exclude"]),
 };
-function splitOperands(verb, args) {
+export function splitOperands(verb, args) {
     const valueFlags = VALUE_FLAGS[verb] ?? new Set();
     const before = [];
     const after = [];
@@ -130,7 +130,7 @@ function pathOperands(verb, ops, ctx) {
     return [...ops.after, ...ops.before.filter((word) => isUnmarkedCheckoutPath(word, ctx))];
 }
 /** True when `spec` selects a directory that holds one of the `.nax` directories (or all of them, from the top). */
-function coversNax(spec, ctx, nax) {
+export function coversNax(spec, ctx, nax) {
     if (isExclusionSpec(spec))
         return false;
     const magic = /^:(?:\(([^)]*)\)|\/)?(.*)$/s.exec(spec);

package/dist/tools/nax-stash-restore.d.ts

@@ -3,5 +3,7 @@ export declare const _naxStateGuardDeps: {
     /** stdout on success, undefined on a spawn error, timeout or non-zero exit. */
     git(cwd: string, args: readonly string[]): string | undefined;
 };
+/** Literal existing files or directories only; never symlinks, magic or globs. */
+export declare function pathIsClean(spec: string, ctx: NaxGuardContext): boolean;
 /** Stash mutations that can be proved not to capture or replay nax state. */
 export declare function stashIsExempt(args: readonly string[], ctx: NaxGuardContext): boolean;

package/dist/tools/nax-stash-restore.js

@@ -60,7 +60,7 @@ function restoreIsExempt(args, ctx) {
     return ctx.frames.every((frame) => worktreeListingIsClean(frame, request.ref) && (!request.index || indexSnapshotIsClean(frame, request.ref)));
 }
 /** Literal existing files or directories only; never symlinks, magic or globs. */
-function pathIsClean(spec, ctx) {
+export function pathIsClean(spec, ctx) {
     if (spec.startsWith(":") || /[*?[]/.test(spec) || operandTouchesNax(spec, ctx))
         return false;
     return ctx.frames.every((frame) => {
@@ -82,10 +82,23 @@ function pathIsClean(spec, ctx) {
 export function stashIsExempt(args, ctx) {
     if (args[0] === "pop" || args[0] === "apply")
         return restoreIsExempt(args.slice(1), ctx);
+    if (args[0] !== "push")
+        return false;
     const separator = args.indexOf("--");
-    if (args[0] !== "push" || separator === -1)
+    const options = args.slice(1, separator === -1 ? args.length : separator);
+    if (options.some((word) => word === "--pathspec-from-file" || word.startsWith("--pathspec-from-file="))) {
         return false;
-    const specs = args.slice(separator + 1);
+    }
+    const specs = [];
+    for (let i = 0; i < options.length; i += 1) {
+        const word = options[i];
+        if (word === "-m" || word === "--message")
+            i += 1;
+        else if (!word.startsWith("-"))
+            specs.push(word);
+    }
+    if (separator !== -1)
+        specs.push(...args.slice(separator + 1));
     if (specs.some((spec) => isFullNaxExclusion(spec, ctx)))
         return true;
     return specs.length > 0 && specs.every((spec) => pathIsClean(spec, ctx));

package/dist/tools/nax-state-guard.js

@@ -119,6 +119,7 @@ import { hasNaxDirNear } from "./nax-dirs.js";
 import { buildsVerbByExpansion, CONFIG_ENV_REFUSAL, configAliasRefusal, EXEC_CONFIG_REFUSAL, EXPANSION_REFUSAL, flattenCode, interpreterCode, isExecConfigKey, mentionsGuardedVerb, } from "./nax-evasion.js";
 import { COVERING_EXCLUSION, discardRefusal, operandTouchesNax, resetRefusal, revertRefusal } from "./nax-revert.js";
 import { stashIsExempt } from "./nax-stash-restore.js";
+import { verbGapsRefusal } from "./nax-verb-gaps.js";
 export { createNaxDirIndex } from "./nax-dirs.js";
 /** Stash subcommands that neither capture nor replay the working tree. */
 const STASH_SAFE_SUBCOMMANDS = new Set(["list", "show", "create", "store", "drop", "clear"]);
@@ -189,6 +190,9 @@ const DISCARD_VERBS = new Set(["switch", "clean", "checkout-index", "read-tree"]
 /** Verbs whose exclusion pathspecs `--literal-pathspecs` turns into literal paths. */
 const EXCLUDING_VERBS = new Set(["checkout", "restore", "stash", "clean"]);
 function verbRefusal(git, segment, where) {
+    const gaps = verbGapsRefusal(git.subcommand, git.args, where);
+    if (gaps !== undefined)
+        return gaps;
     if (git.literalPathspecs && EXCLUDING_VERBS.has(git.subcommand) && git.args.some((a) => a.startsWith(":"))) {
         if (hasNaxDirNear(where))
             return LITERAL_PATHSPECS_REFUSAL;

package/dist/tools/nax-verb-gaps.d.ts

@@ -0,0 +1,3 @@
+import { type NaxGuardContext } from "./nax-dirs.ts";
+/** No new refusal applies when no run-state directory is near the invocation. */
+export declare function verbGapsRefusal(verb: string, args: readonly string[], ctx: NaxGuardContext): string | undefined;

package/dist/tools/nax-verb-gaps.js

@@ -0,0 +1,32 @@
+/** Additional destructive git forms, evaluated with locateGit's effective frames. */
+import { NAX_OWNED_RUN_STATE_EXPLANATION } from "./denial-redirect.js";
+import { findNaxDirs } from "./nax-dirs.js";
+import { coversNax, isExclusionSpec, operandTouchesNax, splitOperands } from "./nax-revert.js";
+const PATH_VERBS = new Set(["checkout", "restore", "rm", "reset"]);
+const AUTOSTASH_VERBS = new Set(["rebase", "pull", "merge"]);
+/** No new refusal applies when no run-state directory is near the invocation. */
+export function verbGapsRefusal(verb, args, ctx) {
+    if (!PATH_VERBS.has(verb) && !AUTOSTASH_VERBS.has(verb) && verb !== "sparse-checkout")
+        return undefined;
+    const nax = findNaxDirs(ctx);
+    if (nax.length === 0)
+        return undefined;
+    if (AUTOSTASH_VERBS.has(verb)) {
+        const flags = splitOperands(verb, args).flags;
+        return flags.includes("--autostash") ? NAX_OWNED_RUN_STATE_EXPLANATION : undefined;
+    }
+    if (verb === "sparse-checkout") {
+        return args[0] === "list" ? undefined : NAX_OWNED_RUN_STATE_EXPLANATION;
+    }
+    const ops = splitOperands(verb, args);
+    const specs = [...ops.before, ...ops.after].filter((spec) => !isExclusionSpec(spec));
+    if (specs.some((spec) => /[*?[]/.test(spec))) {
+        return `${NAX_OWNED_RUN_STATE_EXPLANATION} Glob pathspecs may also select files under \`.nax/\`; name literal paths instead.`;
+    }
+    if (verb === "rm" || verb === "reset") {
+        if (specs.some((spec) => operandTouchesNax(spec, ctx) || coversNax(spec, ctx, nax))) {
+            return NAX_OWNED_RUN_STATE_EXPLANATION;
+        }
+    }
+    return undefined;
+}

package/dist/tools/policy-bash.js

@@ -26,6 +26,7 @@
  * owner of the root boundary and the `.git/` refusal therefore remains `policy.ts`.
  */
 import { lexBashCommand } from "#src/permissions/index";
+import { canonicalSegments } from "./bash-canonical.js";
 import { cdTargetsFor, nextWorkingDirectories } from "./bash-cwd.js";
 import { deniedFlag } from "./exec-guard.js";
 import { isCoveringExclusion } from "./nax-revert.js";
@@ -216,6 +217,34 @@ function lexicalDenial(lexed) {
     return deny(`command contains ${lexed.construct}, which cannot be analysed and is therefore refused -- ` +
         "rewrite it without that construct, or use a structured tool", false, true);
 }
+function matchingDenial(args, segments) {
+    const entry = args.denyEntry;
+    if (entry === undefined)
+        return undefined;
+    for (const segment of segments) {
+        if (segment.tokens[0]?.text === "eval")
+            return deny("Bash canonical analysis refused: eval cannot be analysed");
+        if (matchesSegment(entry, segment)) {
+            return deny(`${args.tool} segment "${render(segment)}" is denied for this stage by rule ${ruleExpr(args.tool, entry, segment)}`);
+        }
+    }
+    return undefined;
+}
+function ruleSegments(segments, refuseUnreadable) {
+    const views = [];
+    for (const segment of segments) {
+        views.push(segment);
+        const canonical = canonicalSegments(segment);
+        if (canonical.kind === "refused") {
+            if (refuseUnreadable)
+                return canonical;
+        }
+        else {
+            views.push(...canonical.segments);
+        }
+    }
+    return { kind: "ok", segments: views };
+}
 export function checkBashCommand(args) {
     const { command, tool } = args;
     const invalid = invalidCommandDenial(command);
@@ -230,11 +259,15 @@ export function checkBashCommand(args) {
     // empty when the refusal preceded any completed word, leaving the checks a
     // no-op and the escalatable lexical refusal intact (Category A).
     const segments = lexed.kind === "ok" ? lexed.segments : lexed.prefix;
-    for (const segment of segments) {
-        if (args.denyEntry !== undefined && matchesSegment(args.denyEntry, segment)) {
-            return deny(`${tool} segment "${render(segment)}" is denied for this stage by rule ${ruleExpr(tool, args.denyEntry, segment)}`);
-        }
-    }
+    // Only deny/ask see these additional views. Payloads, cwd and grants below
+    // continue to evaluate the original tokens (canonicalization cannot grant).
+    const views = ruleSegments(segments, args.denyEntry !== undefined);
+    if (views.kind === "refused")
+        return deny(views.reason);
+    const matchingSegments = views.segments;
+    const denied = matchingDenial(args, matchingSegments);
+    if (denied !== undefined)
+        return denied;
     let cwd = [args.initialPath];
     for (const segment of segments) {
         const result = checkPayload(args, segment, cwd);
@@ -252,7 +285,7 @@ export function checkBashCommand(args) {
         const alternatives = granted === "" ? "no command forms are granted for this stage" : `granted forms: ${granted}`;
         return deny(`${tool} is not granted "${render(segment)}" -- ${alternatives}`, false, true);
     }
-    for (const segment of segments) {
+    for (const segment of matchingSegments) {
         if (args.askEntry !== undefined && matchesSegment(args.askEntry, segment)) {
             return { kind: "ask", rule: ruleExpr(tool, args.askEntry, segment) };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.88.0-canary.2",
+  "version": "0.89.0",
   "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
   "license": "MIT",
   "author": "William Khoo",
@@ -47,13 +47,13 @@
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.77",
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@nathapp/nax-ai": "0.88.0-canary.2",
+    "@nathapp/nax-ai": "0.89.0",
     "zod": "^4.3.6"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
     "provenance": true,
-    "tag": "canary"
+    "tag": "latest"
   }
 }