@nathapp/nax-agent 0.87.0 → 0.88.0-canary.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.88.0-canary.1] - 2026-10-13
+
+- Bash guard for nax run state (#2490): `git update-index --skip-worktree` / `--assume-unchanged` (and the `--no-` forms) on a `.nax` path, `git stash` / `push` / `pop` / `apply` in a repo that holds a `.nax/` directory (unless the pathspec excludes `.nax`), and `git checkout` / `restore` of a `.nax` path are now refused in every segment of a compound command, in gated and raw mode, also behind `git -C`/`-c`, env assignments, `env`/`command`/`nice`/`timeout`/`xargs` wrappers and `bash -c`/`eval`, plus a coarse text backstop for wrappers it cannot enumerate. `RULE_SET_VERSION` is now 4 (git global options, `-c alias.*` and more wrappers are resolved when locating the subcommand).
+- Bash guard gaps closed (#2493): whole-tree reverts (`git reset --hard`, `git checkout .`, `git restore [--source=REV] .`, `:/`, `*`, the root, exclusion-only pathspecs) are refused unless a full `.nax` exclusion follows `--`; the `.nax` presence check also finds a `.nax/` up to three levels below the root (cached per compiled policy); `\git`, `GIT_WORK_TREE` / `GIT_DIR` / `GIT_CONFIG_*` assignments, `git config alias.X <verb>`, `!` aliases and aliases that begin with global options, unknown git global options (fail closed to the text backstop; `--attr-source` is now a known separate-value global), `python|node|perl|ruby -c|-e` code and verbs built by shell expansion are all read; `git checkout feature/.nax` (a branch name) is no longer a false positive. `RULE_SET_VERSION` is now 6 (`locateGit` reads `\git`, re-skips globals after an alias expansion, follows alias chains of any length and never expands an alias over a git builtin).
+- Bash guard, final pass (#2493): a shell name or `-c` cluster anywhere in a segment triggers the quoted-string scan again (`if sh -c "..."`, `find -exec sh -c`, `su -c`, `setsid bash -c` were let through by round 2); `git clean` counts as a dry run only for an `n` before any `e` in a short cluster (`-fdenx` is `-e nx`, a real clean); `--literal-pathspecs` / `GIT_LITERAL_PATHSPECS` with an exclusion pathspec on checkout, restore, stash or clean is refused (it turns every exclusion into a literal path). The command guard stops here; detect-and-repair of nax run state is tracked in #2497.
+- Bash guard, review round 2 (#2493): the covering exclusion must be the top-anchored `/**` form (real git: a glob without the `/**` matches only the `.nax` directory entry, not the files in it, and a relative glob is taken from the working directory); a `:(...)` pathspec with an `attr:` element, or whose magic is not exactly `exclude`, is no exclusion; `checkout-index`, `read-tree` and `clean` operands that name `.nax` are refused; long options are matched by any prefix git accepts (`--k`, `--f`, `--a`); the gated screen accepts the exact covering pathspec instead of rejecting its quoted `*`; the quoted-string scan covers only shells, interpreters and exec-style wrappers (`grep "git stash"`, `gh ... --body "..."`, `printf`, `sed` are no longer refused); `git clean -n` / `--dry-run` is allowed. Not covered, documented: git subcommands that execute a string (`rebase -x`, `submodule foreach`, `bisect run`, `difftool -x`, `fetch --upload-pack=`), executing environment variables (`GIT_EXTERNAL_DIFF`, `GIT_PAGER`, `GIT_EDITOR`, `GIT_SSH_COMMAND`), executing config keys beyond the listed ones (`remote.*.uploadpack`, `uploadpack.packObjectsHook`, `core.alternateRefsCommand`, `merge.*.driver`, `core.gitProxy`, `protocol.ext.allow` with `ext::` URLs), `deno eval` in raw mode, and commands built by string arithmetic in an interpreter.
+- Bash guard, review round 1 (#2493): alias chains have no depth limit (a cycle is refused); backslash-built words (`g\it`, `st\ash`) are read; `restore --staged` is index-only only when every flag is known (`--wor`, `-SW` count as worktree); more interpreters and any quoted string next to a guarded verb are scanned; git config keys that execute commands (`core.fsmonitor`, `core.hooksPath`, `diff.external`, `include.path`, ...) are refused through `-c`, `--config-env` and `git config`; an alias over a git builtin is not expanded; the covering exclusion is now `':(top,exclude,glob)**/.nax/**'` (the literal `:!.nax` only counts while the root `.nax` is the only one); `checkout -f`, `switch -f`, `reset --keep|--merge`, `clean`, `checkout-index -a -f` and `read-tree -u --reset` are refused while a `.nax/` exists; an expansion head needs a `git` token in the segment. A `.nax/` below the root, for example a test fixture within three levels, makes `git stash` refused for the whole repository. The nested scan caches a found `.nax` but re-scans an empty result after one second.
+- Native errors: a `quota` kind from `@nathapp/nax-ai` (usage-limit and token-plan 429s) now maps to
+  `fail-quota` instead of a transient rate limit.
+
+## [0.87.1] - 2026-10-12
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
 ## [0.87.0] - 2026-10-11
 
 - No changes in this package. Released in lockstep with the other nax packages.

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

@@ -14,12 +14,24 @@ import type { BashApprovalMode } from "#src/config/bash-approval";
 import type { QualityCommandSpec } from "#src/internal/command-spec/index";
 import type { AskResolver } from "#src/permissions/index";
 import type { CommandLauncher } from "#src/sandbox/index";
-import { type CodingTool, type CodingToolName, type CodingToolRuntime, type DeclaredCommandRunner, type ProtectedPathsPolicy, type ToolAuditSink, type ToolGrant, type ToolPatternNarrowing } from "#src/tools/index";
+import { type CodingTool, type CodingToolName, type CodingToolRuntime, type DeclaredCommandRunner, type ProtectedPathsPolicy, type ToolAuditSink, type ToolGrant, type ToolPatternNarrowing, type ToolSurfaceDraft, type ToolSurfaceRecord } from "#src/tools/index";
 import type { OwnedPathsPolicy } from "#src/tools/owned-paths";
 export interface CodingToolSupport {
     readonly runtime: CodingToolRuntime;
     readonly tools: readonly CodingTool[];
     readonly auditSink: ToolAuditSink;
+    /** The materialized declaration this support resolved from (nax#2444 D2) — set on every resolve. */
+    readonly declaredTools?: readonly CodingToolName[];
+    /** The session's MCP tool surface (nax#2410 D4), stamped into the audit file at flush. */
+    readonly toolSurface?: ToolSurfaceRecord;
+    /**
+     * The policy-filtered provider-tool delivery for an ACP session (nax#2444 D4),
+     * attached by the nax resolver; the ACP adapter adapts `tools` to EmbedderTools.
+     */
+    readonly acpDelivery?: {
+        readonly tools: readonly CodingTool[];
+        readonly surface: ToolSurfaceDraft;
+    };
 }
 export declare function buildCodingToolSupport(args: {
     root?: string;
@@ -76,6 +88,8 @@ export declare function buildCodingToolSupport(args: {
     /** `quality.shell` — the shell the Bash tool spawns. Defaults to /bin/sh. */
     shell?: string;
     auditDir?: string;
+    /** Stamped into the audit file at flush (nax#2410 D4); absent ⇒ no surface block. */
+    toolSurface?: ToolSurfaceRecord;
     sessionName?: string;
     header?: import("../tools/tool-audit.ts").ToolAuditHeader;
     callId?: string;

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

@@ -71,13 +71,7 @@ export function buildCodingToolSupport(args) {
     // P4/S5: under `raw`, an UNAVAILABLE launcher refuses every Bash call.
     // US-002: an AVAILABLE one marks the screen sandbox-wrapped, so a PRD it only reads is allowed.
     const rawScreenOptions = rawScreenOptionsFor(args.launcher);
-    const sink = args.auditDir !== undefined
-        ? createToolAuditSink({
-            dir: args.auditDir,
-            sessionName: args.sessionName ?? "unattached",
-            ...(args.header ? { header: args.header } : {}),
-        })
-        : createNoOpToolAuditSink();
+    const sink = supportSink(args);
     const runtime = createCodingToolRuntime({
         policy: compileToolPolicy(effectiveGrants, args.root, {
             bashApproval,
@@ -144,7 +138,24 @@ export function buildCodingToolSupport(args) {
     }
     if (tools.length === 0)
         return undefined;
-    return { runtime, tools, auditSink: sink };
+    return {
+        runtime,
+        tools,
+        auditSink: sink,
+        declaredTools: args.declared,
+        ...(args.toolSurface !== undefined ? { toolSurface: args.toolSurface } : {}),
+    };
+}
+/** The audit sink a support resolution records through; no dir ⇒ a non-recording sink. */
+function supportSink(args) {
+    if (args.auditDir === undefined)
+        return createNoOpToolAuditSink();
+    return createToolAuditSink({
+        dir: args.auditDir,
+        sessionName: args.sessionName ?? "unattached",
+        ...(args.header !== undefined ? { header: args.header } : {}),
+        ...(args.toolSurface !== undefined ? { toolSurface: args.toolSurface } : {}),
+    });
 }
 /**
  * Ledger session name.

package/dist/command-safety/rule-scorer.d.ts

@@ -1,5 +1,5 @@
 import { type RuleResult } from "./types.ts";
-export declare const RULE_SET_VERSION = 3;
+export declare const RULE_SET_VERSION = 6;
 /** Context the scorer may use; every field is optional and absent means v1 behaviour. */
 export interface RuleContext {
     /** The project root the command runs against (the Bash call's cwd). */

package/dist/command-safety/rule-scorer.js

@@ -27,14 +27,24 @@
  * hit. The existing eleven regex families stay; the new patterns live in a
  * per-segment pass.
  *
+ * v5: `locateGit` (shared with the nax-state guard, #2493) reads a
+ * backslash-prefixed `\git`, runs the global-option skip again over an
+ * expanded alias, and follows alias chains, so a discard behind any of those
+ * is now located by the v3 per-segment pass.
+ *
+ * v6: `locateGit` never expands an alias that shadows a git builtin (git ignores it) and follows alias
+ * chains of any length (a cycle is reported, not looped on), so `git -c alias.checkout=status checkout -f`
+ * is the discard it really is.
+ *
  * Frozen before the red-team corpus was written. Any pattern or behaviour
  * change bumps RULE_SET_VERSION.
  */
 import { posix } from "node:path";
 import { errorMessage } from "#src/infra/errors";
 import { lexBashCommand } from "#src/permissions/index";
+import { locateGit } from "#src/tools/git-flags/locate";
 import { QUESTION_IDS } from "./types.js";
-export const RULE_SET_VERSION = 3;
+export const RULE_SET_VERSION = 6;
 const RULES = {
     deletes_data: [
         /\brm\s+(?:\S+\s+)*?(?:-[a-zA-Z]*[rRf][a-zA-Z]*|--recursive|--force)\b/,
@@ -140,118 +150,6 @@ const FORCE_FLAGS = new Set(["-f", "--force", "--discard-changes"]);
 const STAGED_FLAGS = new Set(["--staged", "-S"]);
 /** True when `word` is a worktree-restore flag — its own pattern handles these. */
 const WORKTREE_FLAGS = new Set(["--worktree", "-W"]);
-/** `git`'s global options that take no value — pass-through, then look for
- *  the subcommand. */
-const GIT_BOOLEAN_GLOBALS = new Set([
-    "--no-pager",
-    "--no-replace-objects",
-    "--bare",
-    "--literal-pathspecs",
-    "--glob-pathspecs",
-    "--noglob-pathspecs",
-    "--icase-pathspecs",
-]);
-/** `git`'s global options that take a separate value (the next token). */
-const GIT_VALUE_GLOBALS = new Set(["-c", "-C"]);
-/** `git`'s global long options that embed their value (`--key=value`). */
-const GIT_KEY_VALUE_GLOBALS = new Set([
-    "--git-dir=",
-    "--exec-path=",
-    "--work-tree=",
-    "--namespace=",
-    "--super-prefix=",
-]);
-/** `sudo` options whose values occupy the next shell word. */
-const SUDO_VALUE_OPTIONS = new Set([
-    "-u",
-    "-g",
-    "-h",
-    "-D",
-    "-C",
-    "-p",
-    "-r",
-    "-t",
-    "-U",
-    "--user",
-    "--group",
-    "--host",
-    "--chdir",
-    "--close-from",
-    "--prompt",
-    "--role",
-    "--type",
-    "--other-user",
-]);
-/** Skip a sudo/doas prefix, including options with a separate value. */
-function afterPrivilegeWrapper(words) {
-    if (words[0] !== "sudo" && words[0] !== "doas")
-        return 0;
-    let i = 1;
-    while (words[i]?.startsWith("-")) {
-        const option = words[i++];
-        if (option === "--")
-            break;
-        if (option !== undefined && SUDO_VALUE_OPTIONS.has(option))
-            i += 1;
-    }
-    return i;
-}
-/** Skip an env prefix and its assignments and options. */
-function afterEnvWrapper(words, start) {
-    if (words[start] !== "env")
-        return start;
-    let i = start + 1;
-    while (i < words.length) {
-        const word = words[i];
-        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word) || word === "-i" || word === "--ignore-environment") {
-            i += 1;
-        }
-        else if (word === "-u" || word === "--unset") {
-            i += 2;
-        }
-        else
-            break;
-    }
-    return i;
-}
-/** Find `git` in the executable position after supported shell wrappers. */
-function gitExecutableIndex(words) {
-    let i = afterEnvWrapper(words, afterPrivilegeWrapper(words));
-    if (words[i] === "command" || words[i] === "exec")
-        i += 1;
-    return words[i] === "git" ? i : undefined;
-}
-/** Locate executable `git` in `words` and advance past its global options. Returns the
-   subcommand and the index of the first argument (or `undefined` when `git`
-   isn't there or has no subcommand). Handles `sudo git`, `env VAR=x git`,
-   `git --no-pager checkout`, etc. */
-function locateGit(words) {
-    const gitIdx = gitExecutableIndex(words);
-    if (gitIdx === undefined)
-        return undefined;
-    let i = gitIdx + 1;
-    while (i < words.length) {
-        const w = words[i];
-        if (GIT_BOOLEAN_GLOBALS.has(w)) {
-            i += 1;
-            continue;
-        }
-        if (GIT_VALUE_GLOBALS.has(w)) {
-            // The value is a separate token; skip it.
-            i += 2;
-            continue;
-        }
-        if ([...GIT_KEY_VALUE_GLOBALS].some((prefix) => w.startsWith(prefix))) {
-            i += 1;
-            continue;
-        }
-        break;
-    }
-    const subcommand = words[i];
-    if (subcommand === undefined)
-        return undefined;
-    return { subcommand, args: words.slice(i + 1) };
-}
 /** True when `token` is a short-flag bundle that includes `f` (so `-f`,
  *  `-fq`, `-fb`, `-fqH`, ...). Stops at `--` so a long flag like
  *  `--force-something` is not misread as a bundle. */

package/dist/index.d.ts

@@ -42,5 +42,5 @@ export { attachTurnSpend, type FailedTurnSpend, readTurnSpend } from "#src/sessi
 export type { JSONSchema, ToolDescriptor, } from "#src/session/tool-descriptor";
 export { createTurnDeadline, type TurnDeadline, } from "#src/session/turn-deadline";
 export type { TurnEvent, TurnEventSink } from "#src/session/turn-event";
-export { adaptProviderTool, advertisedSchemaBytes, applyModelTruncationPolicy, BASH_TIMEOUT_MS, BASH_TOOL_NAME, buildCommitArgvs, buildGitArgv, buildGrepArgv, type CodingTool, type CodingToolName, type CodingToolOutcome, type CodingToolRuntime, classifyExec, compileToolPolicy, createBashTool, createCodingToolRuntime, createNoOpToolAuditSink, createRunCommandTool, createToolAuditSink, cutBufferToByteCap, DEFAULT_BASH_SHELL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_MAX_COUNT, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, type DeclaredCommandRequest, type DeclaredCommandResult, type DeclaredCommandRunner, deleteTool, EXEC_TOOL_NAME, type ExecTarget, editTool, expandMcpRuleGrants, expandProviderGrants, flushOpenToolAuditSinks, GIT_ESCAPE_FLAGS, GIT_READ_VERBS, getCodingTool, gitCommitTool, gitExcludePathspecsOf, gitIgnorePatternsOf, gitTool, globTool, grepTool, isKnownManager, listCodingTools, MAX_PROVIDER_DESCRIPTION_BYTES, MAX_PROVIDER_SCHEMA_BYTES, MCP_RULE_TOOL, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, type ModelTruncationOptions, mcpRuleAdmits, type NormalizeInput, type NormalizeResult, namespacedToolName, narrowGrants, normalizeExec, normalizeManagerBinary, type PolicyVerdict, PROVIDER_ID_RE, type ProtectedPathsPolicy, type ProviderGrantEntry, type ProviderKind, type ProviderTool, partitionMcpRules, partitionNaxOwnedPaths, providerAttachesTo, READ_CEILING, RESERVED_TOOL_NAMES, type ReadFileSliceOptions, type ReadFileSliceResult, type RegisteredSink, type ResolvedProviderTools, readFileSlice, readTool, registerBuiltinCodingTools, registerBuiltinTool, registerCodingTool, registerToolAuditSink, requestCapabilityTool, resolveProviderTools, resolveWithin, SCRATCHPAD_DIR, SPILL_DIR, type SpillRequest, sanitizeProviderTools, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool, spillRelativePath, substituteCommand, substituteCommandSpec, type ToolAuditHeader, type ToolAuditSink, type ToolCallContext, type ToolCallRecord, type ToolGrant, type ToolPatternNarrowing, type ToolPolicy, type ToolPolicyOptions, type ToolProvider, type ToolResult, type ToolRunContext, type ToolScope, type TruncateForModelOptions, type TruncationDirection, type TruncationResult, truncateForModel, truncationDirectionFor, unregisterToolAuditSink, validateProviderId, writeSpill, writeTool, } from "#src/tools/index";
+export { adaptProviderTool, advertisedSchemaBytes, applyModelTruncationPolicy, BASH_TIMEOUT_MS, BASH_TOOL_NAME, buildCommitArgvs, buildGitArgv, buildGrepArgv, type CodingTool, type CodingToolName, type CodingToolOutcome, type CodingToolRuntime, classifyExec, compileToolPolicy, createBashTool, createCodingToolRuntime, createNoOpToolAuditSink, createRunCommandTool, createToolAuditSink, cutBufferToByteCap, DEFAULT_BASH_SHELL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_MAX_COUNT, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, type DeclaredCommandRequest, type DeclaredCommandResult, type DeclaredCommandRunner, deleteTool, EXEC_TOOL_NAME, type ExecTarget, editTool, expandMcpRuleGrants, expandProviderGrants, flushOpenToolAuditSinks, GIT_ESCAPE_FLAGS, GIT_READ_VERBS, getCodingTool, gitCommitTool, gitExcludePathspecsOf, gitIgnorePatternsOf, gitTool, globTool, grepTool, isKnownManager, listCodingTools, MAX_PROVIDER_DESCRIPTION_BYTES, MAX_PROVIDER_SCHEMA_BYTES, MCP_RULE_TOOL, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, type ModelTruncationOptions, mcpRuleAdmits, type NormalizeInput, type NormalizeResult, namespacedToolName, narrowGrants, normalizeExec, normalizeManagerBinary, type PolicyVerdict, PROVIDER_ID_RE, type ProtectedPathsPolicy, type ProviderGrantEntry, type ProviderKind, type ProviderTool, partitionMcpRules, partitionNaxOwnedPaths, providerAttachesTo, READ_CEILING, RESERVED_TOOL_NAMES, type ReadFileSliceOptions, type ReadFileSliceResult, type RegisteredSink, type ResolvedProviderTools, readFileSlice, readTool, registerBuiltinCodingTools, registerBuiltinTool, registerCodingTool, registerToolAuditSink, requestCapabilityTool, resolveProviderTools, resolveWithin, SCRATCHPAD_DIR, SPILL_DIR, type SpillRequest, sanitizeProviderTools, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool, spillRelativePath, substituteCommand, substituteCommandSpec, type ToolAuditHeader, type ToolAuditSink, type ToolCallContext, type ToolCallRecord, type ToolGrant, type ToolPatternNarrowing, type ToolPolicy, type ToolPolicyOptions, type ToolProvider, type ToolResult, type ToolRunContext, type ToolScope, type ToolSurfaceDraft, type ToolSurfaceRecord, type TruncateForModelOptions, type TruncationDirection, type TruncationResult, truncateForModel, truncationDirectionFor, unregisterToolAuditSink, validateProviderId, writeSpill, writeTool, } from "#src/tools/index";
 export { EMPTY_OWNED_PATHS_POLICY, type OwnedBashCandidate, type OwnedPathsPolicy, } from "#src/tools/owned-paths";

package/dist/internal.d.ts

@@ -69,6 +69,7 @@ export { _repositoryInstructionDeps } from "#src/native/session/repository-instr
 export * from "#src/native/session/session";
 export * as sessionModule from "#src/native/session/session";
 export * from "#src/native/session/tool-mapping";
+export { _transcriptArchiveDeps } from "#src/native/session/transcript-archive";
 export * from "#src/native/session/transcript-identity";
 export * from "#src/native/session/transcript-store";
 export * as transcriptStoreModule from "#src/native/session/transcript-store";

package/dist/internal.js

@@ -69,6 +69,7 @@ export { _repositoryInstructionDeps } from "#src/native/session/repository-instr
 export * from "#src/native/session/session";
 export * as sessionModule from "#src/native/session/session";
 export * from "#src/native/session/tool-mapping";
+export { _transcriptArchiveDeps } from "#src/native/session/transcript-archive";
 export * from "#src/native/session/transcript-identity";
 export * from "#src/native/session/transcript-store";
 export * as transcriptStoreModule from "#src/native/session/transcript-store";

package/dist/native/errors.js

@@ -17,6 +17,13 @@ const FAILURES = Object.freeze({
         outcome: "fail-rate-limit",
         retriable: true,
     },
+    // The account or plan is exhausted: waiting does not help, so not retriable.
+    quota: {
+        message: "nax-ai account or plan quota exhausted",
+        category: "availability",
+        outcome: "fail-quota",
+        retriable: false,
+    },
     auth: {
         message: "nax-ai authentication failed",
         category: "availability",

package/dist/native/session/session.d.ts

@@ -11,6 +11,7 @@ import type { AgentStreamEvent } from "#src/session/agent-stream-events";
 import type { OpenSessionOpts, SessionHandle } from "#src/session/session-types";
 import type { ResolvedCompaction } from "./compaction.ts";
 import type { RepositoryInstructions } from "./repository-instructions.ts";
+import { type TranscriptArchive } from "./transcript-archive.ts";
 import type { TranscriptStore } from "./transcript-types.ts";
 import type { TurnRetryConfig } from "./turn-retry.ts";
 /** The runtime hooks handed to openSession. */
@@ -22,6 +23,8 @@ export interface NativeSessionStreamHooks {
 export interface SessionTranscript {
     readonly store: TranscriptStore;
     readonly retainOnClose: boolean;
+    /** When set, close writes a redacted copy here before deleting or retaining the live document (nax#2453). */
+    readonly transcriptArchive?: TranscriptArchive;
 }
 /**
  * The per-owner state behind the native session lifecycle.

package/dist/native/session/session.js

@@ -13,6 +13,7 @@ import { nativeSessionId } from "../session-affinity.js";
 import { instructionFileNameFor } from "./instruction-file-name.js";
 import { openRepositoryInstructions } from "./instruction-session.js";
 import { instructionTranscriptStore } from "./instruction-transcript.js";
+import { archiveTranscript } from "./transcript-archive.js";
 import { createFileTranscriptStore } from "./transcript-store.js";
 export function createNativeSessionState() {
     return {
@@ -106,6 +107,7 @@ export async function openNativeSession(state, name, opts) {
     state.transcripts.set(name, {
         store,
         retainOnClose: opts.retainOnClose === true,
+        transcriptArchive: opts.transcriptArchive,
     });
     state.timeouts.set(name, opts.timeoutSeconds);
     state.scratchpadRoots.set(name, opts.workdir);
@@ -123,6 +125,7 @@ export async function openNativeSession(state, name, opts) {
     state.transcripts.set(name, {
         store: instructionTranscriptStore(store, instructions),
         retainOnClose: opts.retainOnClose === true,
+        transcriptArchive: opts.transcriptArchive,
     });
     // `resume` is SessionManager's "this name already has a descriptor in this
     // process" signal, and it had no consumer on this transport (nax#1877) — a
@@ -199,6 +202,10 @@ export async function closeNativeSession(state, handle, failed) {
     const treatAsFailed = failed ?? state.failed.has(handle.id);
     try {
         if (transcript !== undefined && !transcript.retainOnClose) {
+            // Archive first (nax#2453): best-effort, never throws, so the branch below is unchanged.
+            if (transcript.transcriptArchive !== undefined) {
+                await archiveTranscript(transcript.store, handle.id, transcript.transcriptArchive);
+            }
             // Retain for a human, out of reach of the next session of this name.
             if (treatAsFailed)
                 await transcript.store.retainFailed(handle.id);

package/dist/native/session/transcript-archive.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Audit archive for native session transcripts (nax#2453).
+ *
+ * `closeNativeSession` deletes a clean session's transcript and renames a failed
+ * one, so a passing session, which is where most tokens go, left no turn-level
+ * record. When the caller opts in, this writes a redacted copy into an archive
+ * directory first. The archive file name contains `.transcript.` and ends in
+ * `.json`, so `pruneRetainedTranscripts` already counts it; it never sits in the
+ * live `sessions/` directory, so it can never be loaded as a resumption source
+ * (nax#1877).
+ */
+import type { TranscriptStore } from "./transcript-types.ts";
+/** Injectable clock for the archive stamp, so tests order archives without sleeping. */
+export declare const _transcriptArchiveDeps: {
+    now: () => Date;
+};
+/** Where, and how many, archived transcripts are kept (the `OpenSessionOpts.transcriptArchive` shape). */
+export interface TranscriptArchive {
+    readonly dir: string;
+    readonly maxRetained: number;
+}
+/**
+ * Write a redacted copy of the session's transcript into `archive.dir`, then
+ * prune the directory to `archive.maxRetained`. Nothing to archive (no saved
+ * document) is a quiet return. Every error is logged and swallowed: the archive
+ * is supplementary and must never change how a session closes.
+ */
+export declare function archiveTranscript(store: TranscriptStore, sessionId: string, archive: TranscriptArchive): Promise<void>;

package/dist/native/session/transcript-archive.js

@@ -0,0 +1,43 @@
+/**
+ * Audit archive for native session transcripts (nax#2453).
+ *
+ * `closeNativeSession` deletes a clean session's transcript and renames a failed
+ * one, so a passing session, which is where most tokens go, left no turn-level
+ * record. When the caller opts in, this writes a redacted copy into an archive
+ * directory first. The archive file name contains `.transcript.` and ends in
+ * `.json`, so `pruneRetainedTranscripts` already counts it; it never sits in the
+ * live `sessions/` directory, so it can never be loaded as a resumption source
+ * (nax#1877).
+ */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { getLogger } from "#src/infra/index";
+import { writeFileAtomic } from "#src/internal/atomic-write";
+import { redactSecrets } from "#src/internal/redact";
+import { pruneRetainedTranscripts } from "./transcript-store.js";
+/** Injectable clock for the archive stamp, so tests order archives without sleeping. */
+export const _transcriptArchiveDeps = { now: () => new Date() };
+/**
+ * Write a redacted copy of the session's transcript into `archive.dir`, then
+ * prune the directory to `archive.maxRetained`. Nothing to archive (no saved
+ * document) is a quiet return. Every error is logged and swallowed: the archive
+ * is supplementary and must never change how a session closes.
+ */
+export async function archiveTranscript(store, sessionId, archive) {
+    try {
+        const doc = await store.load(sessionId);
+        if (doc === null)
+            return;
+        const stamp = _transcriptArchiveDeps.now().toISOString().replace(/[:.]/g, "-");
+        await mkdir(archive.dir, { recursive: true });
+        await writeFileAtomic(join(archive.dir, `${sessionId}.transcript.${stamp}.json`), JSON.stringify(redactSecrets(doc), null, 2));
+        await pruneRetainedTranscripts(archive.dir, archive.maxRetained);
+    }
+    catch (err) {
+        getLogger().warn("native-session", "Transcript archive failed; close continues unchanged", {
+            sessionId,
+            dir: archive.dir,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}

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

@@ -146,6 +146,17 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
         readonly dir: string;
         readonly header: import("#src/tools/tool-audit").ToolAuditHeader;
     };
+    /**
+     * ACP delivery (nax#2444, D3): provider tools already policy-filtered at the
+     * hop (deny/ask-ruled tools withheld), adapted by the ACP backend only when
+     * its registry entry declares a pre-approval channel. Native ignores it —
+     * provider tools ride `codingTools` on the turn.
+     */
+    providerTools?: readonly import("#src/tools/registry").CodingTool[];
+    /** ACP: the op's materialized declaration, which narrows the session profile (nax#2444, D2). */
+    declaredTools?: readonly string[];
+    /** ACP: the transport-less surface draft; the adapter stamps transport + profile (nax#2410, D4). */
+    toolSurface?: import("#src/tools/tool-audit").ToolSurfaceDraft;
     /**
      * Native: identity that owns this session's transcript — the op invocation's
      * `scopeId ?? callId`. Stable across the retries and hops of one invocation,
@@ -169,6 +180,14 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
      * that close failed.
      */
     retainOnClose?: boolean;
+    /**
+     * Native: when set, closeNativeSession writes a redacted copy of the transcript
+     * here before deleting or retaining it. ACP ignores it.
+     */
+    transcriptArchive?: {
+        readonly dir: string;
+        readonly maxRetained: number;
+    };
     /**
      * Native: the session's system prompt, sent as the request's top-level
      * `system` on every round trip (not on the compaction summary). The S3

package/dist/tools/denial-redirect.d.ts

@@ -19,16 +19,31 @@
  * `grep -n x y` did not. 20 of 34 denials in the two runs after #1971 carried
  * no redirect (nax#1999). A single table cannot drift against itself.
  */
-export declare function redirectForArgv(argv: readonly string[], available: ReadonlySet<string>, declaredCommands: ReadonlySet<string>): string | undefined;
+export declare const NAX_OWNED_RUN_STATE_EXPLANATION = "`.nax/` is nax's own run state, written by the harness during this run. It is not part of your diff and must not be reverted.";
 /**
- * Name the tool that serves the intent behind a denied Bash COMMAND.
+ * The sentence explaining a revert of nax's own run state, or undefined.
+ *
+ * Deliberately NOT an `Intent`: `render()` wraps every hit as "this session
+ * already has `X`", which is false here -- no tool reverts `.nax/`, and the
+ * module's header forbids naming one it does not hold. So this predicate is
+ * checked BEFORE `intentFor` in both entry points and returns its own sentence.
  *
- * Reads the first segment only: that is what the model reached for, and a
- * later segment's intent is not what to teach when the call is refused. The
- * split is deliberately its own crude one rather than the lexer's
- * (`lexBashCommand`): a command REFUSED for an unanalysable construct must
- * still get a redirect, and the lexer returns nothing to read in that case.
+ * Verb scope is `checkout` and `restore` only; `git stash` has no operands to
+ * gate on and is handled by `nax-state-guard.ts` instead. The gate is a `.nax`
+ * path SEGMENT (split on `/`), never a substring, so `src/nax-helpers.ts` and
+ * `docs/.naxignore` stay unanswered. `--` is a separator, not an operand, and a
+ * `timeout N` wrapper is stripped the same way `intentFor` strips it.
+ */
+export declare function naxOwnedRunStateExplanation(tokens: readonly string[]): string | undefined;
+/** A `timeout N ...` prefix wraps the real command; look past it. */
+export declare function withoutTimeoutPrefix(tokens: readonly string[]): readonly string[];
+export declare function redirectForArgv(argv: readonly string[], available: ReadonlySet<string>, declaredCommands: ReadonlySet<string>): string | undefined;
+/**
+ * The crude segment split shared by the redirect and the raw screen's fallback
+ * for a command the lexer refused. Deliberately not the lexer: it must still
+ * produce segments when the lexer returns nothing to read.
  */
+export declare function crudeCommandSegments(command: string): string[][];
 export declare function redirectForCommand(command: string, available: ReadonlySet<string>, declaredCommands: ReadonlySet<string>): string | undefined;
 /**
  * Name the tool that serves the intent behind a denied VERB call.

package/dist/tools/denial-redirect.js

@@ -32,7 +32,7 @@ const GIT_COMMIT_VERBS = new Set(["add", "commit"]);
  * intent, so the refusal teaches instead of naming one (nax#2007).
  */
 const GIT_REVERT_VERBS = new Set(["checkout", "restore"]);
-const NAX_OWNED_RUN_STATE_EXPLANATION = "`.nax/` is nax's own run state, written by the harness during this run. It is not part of your diff and must not be reverted.";
+export const NAX_OWNED_RUN_STATE_EXPLANATION = "`.nax/` is nax's own run state, written by the harness during this run. It is not part of your diff and must not be reverted.";
 /**
  * The sentence explaining a revert of nax's own run state, or undefined.
  *
@@ -41,13 +41,13 @@ const NAX_OWNED_RUN_STATE_EXPLANATION = "`.nax/` is nax's own run state, written
  * module's header forbids naming one it does not hold. So this predicate is
  * checked BEFORE `intentFor` in both entry points and returns its own sentence.
  *
- * Verb scope is `checkout` and `restore` only; `git stash` is the agent's own
- * WIP, not nax's state, and has no operands to gate on. The gate is a `.nax`
+ * Verb scope is `checkout` and `restore` only; `git stash` has no operands to
+ * gate on and is handled by `nax-state-guard.ts` instead. The gate is a `.nax`
  * path SEGMENT (split on `/`), never a substring, so `src/nax-helpers.ts` and
  * `docs/.naxignore` stay unanswered. `--` is a separator, not an operand, and a
  * `timeout N` wrapper is stripped the same way `intentFor` strips it.
  */
-function naxOwnedRunStateExplanation(tokens) {
+export function naxOwnedRunStateExplanation(tokens) {
     const av = withoutTimeoutPrefix(tokens);
     const hasGitPrefix = av[0] === "git";
     const verb = hasGitPrefix ? av[1] : av[0];
@@ -142,7 +142,7 @@ function isSingleFileDelete(tokens, from) {
     return tokens.length === from + 1 && !tokens[from]?.startsWith("-");
 }
 /** A `timeout N ...` prefix wraps the real command; look past it. */
-function withoutTimeoutPrefix(tokens) {
+export function withoutTimeoutPrefix(tokens) {
     return tokens[0] === "timeout" ? tokens.slice(2) : tokens;
 }
 /**
@@ -211,23 +211,39 @@ export function redirectForArgv(argv, available, declaredCommands) {
 /**
  * Name the tool that serves the intent behind a denied Bash COMMAND.
  *
- * Reads the first segment only: that is what the model reached for, and a
- * later segment's intent is not what to teach when the call is refused. The
+ * The intent redirect reads the first segment only: that is what the model
+ * reached for, and a later segment's intent is not what to teach when the call
+ * is refused. The
  * split is deliberately its own crude one rather than the lexer's
  * (`lexBashCommand`): a command REFUSED for an unanalysable construct must
  * still get a redirect, and the lexer returns nothing to read in that case.
  */
-export function redirectForCommand(command, available, declaredCommands) {
-    const [first = ""] = command.split(/&&|\|\||;|\||\n/);
-    const tokens = first
+function tokenize(segment) {
+    return segment
         .trim()
         .split(/\s+/)
         .filter((token) => token.length > 0);
+}
+/**
+ * The crude segment split shared by the redirect and the raw screen's fallback
+ * for a command the lexer refused. Deliberately not the lexer: it must still
+ * produce segments when the lexer returns nothing to read.
+ */
+export function crudeCommandSegments(command) {
+    return command.split(/&&|\|\||;|\||\n/).map(tokenize);
+}
+export function redirectForCommand(command, available, declaredCommands) {
+    const segments = crudeCommandSegments(command);
+    // A revert of nax's run state is explained wherever it sits in a compound
+    // command (#2490); only the intent redirect below is first-segment-only.
+    for (const segment of segments) {
+        const ownedRunState = naxOwnedRunStateExplanation(segment);
+        if (ownedRunState !== undefined)
+            return ownedRunState;
+    }
+    const tokens = segments[0] ?? [];
     if (tokens.length === 0)
         return undefined;
-    const ownedRunState = naxOwnedRunStateExplanation(tokens);
-    if (ownedRunState !== undefined)
-        return ownedRunState;
     const hit = intentFor(tokens);
     if (hit === undefined)
         return taskRunnerFallback(tokens, available, declaredCommands);

package/dist/tools/git-flags/locate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Locating `git` and its subcommand inside a command line.
+ *
+ * A leaf module with NO imports, like `./index.ts`, so both `command-safety`
+ * and `tools` can use it without a cycle. Shared by the command-safety scorer
+ * and the Bash guard for nax's run state (#2490), so a wrapper or global
+ * option that hides `git` from one cannot hide it from the other.
+ */
+/**
+ * Index of the word that actually names the command, after leading `VAR=x`
+ * assignments and the wrappers that pass through to it (`sudo`, `env`,
+ * `command`, `exec`, `nice`, `timeout`, `xargs`).
+ */
+export declare function commandHeadIndex(words: readonly string[]): number;
+/** Find `git` in the executable position after supported wrappers. */
+export declare function gitExecutableIndex(words: readonly string[]): number | undefined;
+export interface LocatedGit {
+    readonly subcommand: string;
+    readonly args: readonly string[];
+    /**
+     * Values of `-C`, `--work-tree` and `--git-dir` (both `--key value` and
+     * `--key=value`) and of leading `GIT_WORK_TREE=` / `GIT_DIR=` assignments, in order.
+     */
+    readonly dirs: readonly string[];
+    /** True when an alias is defined through `--config-env=alias.*`: its value lives in the environment and cannot be read. */
+    readonly unresolvedAlias: boolean;
+    /** True when a global option this reader does not know sat before the subcommand: the subcommand found may be that option's value. */
+    readonly uncertain: boolean;
+    /** The shell text a `!` alias runs (its value without the `!`, then the call's remaining arguments), or undefined. */
+    readonly shellAlias: string | undefined;
+    /** Lower-cased keys set by `-c key=value` and `--config-env=key=VAR`, in order. */
+    readonly configKeys: readonly string[];
+    /** True when a leading assignment sets a `GIT_CONFIG*` variable (config, including aliases, injected through the environment). */
+    readonly configEnv: boolean;
+    /** True under `--literal-pathspecs` or a non-empty, non-`0` `GIT_LITERAL_PATHSPECS`: every `:(...)` / `:!` exclusion is a literal path. */
+    readonly literalPathspecs: boolean;
+}
+/**
+ * Locate executable `git` in `words` and advance past its global options.
+ * Returns the subcommand (alias-expanded), its arguments, and the directories
+ * the global options point git at, or `undefined` when `git` isn't there or has
+ * no subcommand. Handles `sudo git`, `env VAR=x git`, a backslash-prefixed
+ * `git`, `git --no-pager checkout`, and an UNKNOWN `-x` / `--xxx` global
+ * (skipped as one word and flagged `uncertain`, so a new git option cannot
+ * hide the subcommand silently).
+ */
+export declare function locateGit(words: readonly string[]): LocatedGit | undefined;