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

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.2] - 2026-10-15
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
+## [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.

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

@@ -32,6 +32,16 @@ export interface CodingToolSupport {
         readonly tools: readonly CodingTool[];
         readonly surface: ToolSurfaceDraft;
     };
+    /** nax#2500: the dispatch launcher's sandbox as data, attached by the nax resolver for ACP opens. */
+    readonly acpSandbox?: import("#src/sandbox/types").SessionSandbox;
+    /**
+     * The rendered `## MCP servers` section (nax#2517), built by the nax resolver
+     * with `renderProviderInstructions` from this hop's resolved provider
+     * instructions. The session open folds it into the session's `system` field
+     * (native) or hands it to the ACP tool host. ABSENT when no attached provider
+     * contributed instructions, so "no section" and "an empty one" stay distinct.
+     */
+    readonly providerInstructions?: string;
 }
 export declare function buildCodingToolSupport(args: {
     root?: string;
@@ -134,6 +144,12 @@ export declare function buildCodingToolSupport(args: {
     launcher?: CommandLauncher;
     /** US-001: forwarded into ToolRunContext so Bash/Exec can SIGKILL on cancel. */
     abortSignal?: AbortSignal;
+    /**
+     * The rendered `## MCP servers` section for this hop (nax#2517), produced by
+     * the resolver from `ResolvedProviderTools.instructions`; returned on the
+     * support unchanged.
+     */
+    providerInstructions?: string;
 }): CodingToolSupport | undefined;
 /**
  * Ledger session name.

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

@@ -144,8 +144,20 @@ export function buildCodingToolSupport(args) {
         auditSink: sink,
         declaredTools: args.declared,
         ...(args.toolSurface !== undefined ? { toolSurface: args.toolSurface } : {}),
+        ...providerInstructionsField(args),
     };
 }
+/**
+ * The support's optional `providerInstructions` (#2517) as a spreadable field —
+ * ABSENT when unset, so `"providerInstructions" in support` answers "is there
+ * an MCP section?". A helper rather than an inline conditional because
+ * `buildCodingToolSupport` sits at its complexity baseline.
+ */
+function providerInstructionsField(args) {
+    if (args.providerInstructions === undefined)
+        return {};
+    return { providerInstructions: args.providerInstructions };
+}
 /** The audit sink a support resolution records through; no dir ⇒ a non-recording sink. */
 function supportSink(args) {
     if (args.auditDir === undefined)

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/config/schemas-sandbox.d.ts

@@ -24,6 +24,7 @@ export declare const SandboxConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     network: z.ZodPrefault<z.ZodObject<{
         allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;

package/dist/config/schemas-sandbox.js

@@ -38,6 +38,15 @@ export const SandboxConfigSchema = z.object({
         .object({
         /** absent = unrestricted (spec S2); [] = no network; a list = allow-list. */
         allowedDomains: z.array(z.string()).optional(),
+        /**
+         * US-002 (#2538): let a sandboxed command reach loopback ports.
+         *
+         * Off when absent, and it only changes anything alongside an
+         * `allowedDomains` list: with an open network srt's macOS profile already
+         * allows all traffic. srt reads it once per process, from the config given
+         * to `SandboxManager.initialize`.
+         */
+        allowLocalBinding: z.boolean().optional(),
     })
         .prefault({}),
 });

package/dist/index.d.ts

@@ -26,7 +26,7 @@ export type { AfterResponsePatch, AfterResponsePayload, AfterToolPatch, AfterToo
 export { displayToolInput, TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES, toolResultPreview, } from "#src/native/session/turn-event-emitter";
 export { type ApprovalAuditRow, type ApprovalEntry, type ApprovalsFile, type ApprovalsFileRead, type ApprovalsFileState, type ApprovalsTaint, ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, type AskControl, type AskDecidedBy, type AskDecision, type AskLink, type AskLinkOutcome, type AskRequest, type AskResolver, type AskVerdict, appendApproval, appendApprovalAudit, approvalId, approvalsPath, type BashLexResult, type BashRedirect, type BashSegment, type BashSegmentSeparator, type BashToken, type ClearTaintOutcome, chainAskLinks, clearApprovalsTaint, createApprovalsLink, findApproval, findSecretSpans, headlessAskResolver, isForgeCapable, lexBashCommand, type MaskResult, maskForPrompt, type PrepareApprovalsStoreOptions, parseRuleList, parseToolExpression, prepareApprovalsStore, type RemovalDecision, type RemovalResult, type ResolvedPermissions, readApprovals, readApprovalsFile, readApprovalsFileDetailed, redactForRow, redactRowStrings, removeApprovals, type SecretSpan, taintApprovals, writeApprovalsFile, } from "#src/permissions/index";
 export { type AgentGlobOptions, type AgentRuntime, type AgentSpawnOptions, type AgentSpawnResult, type AgentSpawnStdin, getAgentRuntime, nodeRuntime, setAgentRuntime, } from "#src/runtime/index";
-export { buildSandboxPolicy, type CommandLauncher, type CommandLauncherOptions, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, type GitLayout, type LaunchRequest, type LaunchResult, type LaunchSpec, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, type ProbeResult, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, type SandboxBackend, type SandboxBackendName, type SandboxNetworkPolicy, type SandboxPolicy, type SandboxPolicyInput, type SandboxRecord, type SandboxState, type SandboxWrapRequest, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";
+export { buildSandboxPolicy, type CommandLauncher, type CommandLauncherOptions, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, type GitLayout, type LaunchRequest, type LaunchResult, type LaunchSpec, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, type ProbeResult, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, type SandboxBackend, type SandboxBackendName, type SandboxNetworkPolicy, type SandboxPolicy, type SandboxPolicyInput, type SandboxRecord, type SandboxState, type SandboxWrapRequest, type SessionSandbox, sessionSandboxFrom, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";
 export type { AdapterFailure } from "#src/session/adapter-failure";
 export { createAgentSession, resumeAgentSession } from "#src/session/agent-session";
 export { AgentSessionError, type AgentSessionErrorCode } from "#src/session/agent-session-errors";
@@ -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 ToolSurfaceDraft, type ToolSurfaceRecord, 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_INSTRUCTIONS_MAX_CHARS_PER_SERVER, MCP_INSTRUCTIONS_MAX_CHARS_TOTAL, 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, renderProviderInstructions, 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/index.js

@@ -21,7 +21,7 @@ export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOut
 export { displayToolInput, TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES, toolResultPreview, } from "#src/native/session/turn-event-emitter";
 export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, appendApproval, appendApprovalAudit, approvalId, approvalsPath, chainAskLinks, clearApprovalsTaint, createApprovalsLink, findApproval, findSecretSpans, headlessAskResolver, isForgeCapable, lexBashCommand, maskForPrompt, parseRuleList, parseToolExpression, prepareApprovalsStore, readApprovals, readApprovalsFile, readApprovalsFileDetailed, redactForRow, redactRowStrings, removeApprovals, taintApprovals, writeApprovalsFile, } from "#src/permissions/index";
 export { getAgentRuntime, nodeRuntime, setAgentRuntime, } from "#src/runtime/index";
-export { buildSandboxPolicy, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";
+export { buildSandboxPolicy, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, sessionSandboxFrom, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";
 export { createAgentSession, resumeAgentSession } from "#src/session/agent-session";
 export { AgentSessionError } from "#src/session/agent-session-errors";
 export { NO_OP_INTERACTION_HANDLER, } from "#src/session/interaction-handler";
@@ -29,5 +29,5 @@ export { nativeBackend } from "#src/session/native-backend";
 export { SessionTurnError, } from "#src/session/session-types";
 export { attachTurnSpend, readTurnSpend } from "#src/session/turn-spend";
 export { createTurnDeadline, } from "#src/session/turn-deadline";
-export { adaptProviderTool, advertisedSchemaBytes, applyModelTruncationPolicy, BASH_TIMEOUT_MS, BASH_TOOL_NAME, buildCommitArgvs, buildGitArgv, buildGrepArgv, 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, deleteTool, EXEC_TOOL_NAME, 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, mcpRuleAdmits, namespacedToolName, narrowGrants, normalizeExec, normalizeManagerBinary, PROVIDER_ID_RE, partitionMcpRules, partitionNaxOwnedPaths, providerAttachesTo, READ_CEILING, RESERVED_TOOL_NAMES, readFileSlice, readTool, registerBuiltinCodingTools, registerBuiltinTool, registerCodingTool, registerToolAuditSink, requestCapabilityTool, resolveProviderTools, resolveWithin, SCRATCHPAD_DIR, SPILL_DIR, sanitizeProviderTools, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool, spillRelativePath, substituteCommand, substituteCommandSpec, truncateForModel, truncationDirectionFor, unregisterToolAuditSink, validateProviderId, writeSpill, writeTool, } from "#src/tools/index";
+export { adaptProviderTool, advertisedSchemaBytes, applyModelTruncationPolicy, BASH_TIMEOUT_MS, BASH_TOOL_NAME, buildCommitArgvs, buildGitArgv, buildGrepArgv, 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, deleteTool, EXEC_TOOL_NAME, 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_INSTRUCTIONS_MAX_CHARS_PER_SERVER, MCP_INSTRUCTIONS_MAX_CHARS_TOTAL, MCP_RULE_TOOL, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, mcpRuleAdmits, namespacedToolName, narrowGrants, normalizeExec, normalizeManagerBinary, PROVIDER_ID_RE, partitionMcpRules, partitionNaxOwnedPaths, providerAttachesTo, READ_CEILING, RESERVED_TOOL_NAMES, readFileSlice, readTool, registerBuiltinCodingTools, registerBuiltinTool, registerCodingTool, registerToolAuditSink, renderProviderInstructions, requestCapabilityTool, resolveProviderTools, resolveWithin, SCRATCHPAD_DIR, SPILL_DIR, sanitizeProviderTools, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool, spillRelativePath, substituteCommand, substituteCommandSpec, truncateForModel, truncationDirectionFor, unregisterToolAuditSink, validateProviderId, writeSpill, writeTool, } from "#src/tools/index";
 export { EMPTY_OWNED_PATHS_POLICY, } from "#src/tools/owned-paths";

package/dist/internal/process-kill.d.ts

@@ -12,7 +12,9 @@
  * 2. Falls back to killing the single process if group kill fails
  *
  * @param pid - Process ID (positive, not negative)
- * @param signal - Signal to send (SIGTERM, SIGKILL, etc.)
+ * @param signal - Signal to send (SIGTERM, SIGKILL, etc.); `0` probes whether the group still has a member
+ * @param opts - `singleProcessFallback: false` skips step 2. Pass it once the group leader is known to have
+ *   exited: the bare pid may have been reused by an unrelated process by then.
  * @returns true if kill was sent successfully, false if process already exited
  *
  * @example
@@ -24,4 +26,6 @@
  * }
  * ```
  */
-export declare function killProcessGroup(pid: number, signal: NodeJS.Signals | number): boolean;
+export declare function killProcessGroup(pid: number, signal: NodeJS.Signals | number, opts?: {
+    readonly singleProcessFallback?: boolean;
+}): boolean;

package/dist/internal/process-kill.js

@@ -12,7 +12,9 @@
  * 2. Falls back to killing the single process if group kill fails
  *
  * @param pid - Process ID (positive, not negative)
- * @param signal - Signal to send (SIGTERM, SIGKILL, etc.)
+ * @param signal - Signal to send (SIGTERM, SIGKILL, etc.); `0` probes whether the group still has a member
+ * @param opts - `singleProcessFallback: false` skips step 2. Pass it once the group leader is known to have
+ *   exited: the bare pid may have been reused by an unrelated process by then.
  * @returns true if kill was sent successfully, false if process already exited
  *
  * @example
@@ -24,7 +26,7 @@
  * }
  * ```
  */
-export function killProcessGroup(pid, signal) {
+export function killProcessGroup(pid, signal, opts = {}) {
     // A pid that is not a real child reaches other processes: 0 is our own group,
     // 1 (as -1) is every process we may signal, and a negative pid is init or a
     // foreign group. A spawn that failed has no pid, so refuse rather than signal.
@@ -39,6 +41,8 @@ export function killProcessGroup(pid, signal) {
         const err = error;
         // ESRCH = no such process — process group doesn't exist, try single process
         if (err.code === "ESRCH") {
+            if (opts.singleProcessFallback === false)
+                return false;
             try {
                 process.kill(pid, signal);
                 return true;

package/dist/internal.d.ts

@@ -93,6 +93,7 @@ export * from "#src/tools/git-commit";
 export * from "#src/tools/grep";
 export * from "#src/tools/index";
 export { _instructionAccessDeps } from "#src/tools/instruction-access";
+export { _naxStateGuardDeps } from "#src/tools/nax-stash-restore";
 export * from "#src/tools/owned-paths";
 export * from "#src/tools/package-managers";
 export * from "#src/tools/policy";

package/dist/internal.js

@@ -93,6 +93,7 @@ export * from "#src/tools/git-commit";
 export * from "#src/tools/grep";
 export * from "#src/tools/index";
 export { _instructionAccessDeps } from "#src/tools/instruction-access";
+export { _naxStateGuardDeps } from "#src/tools/nax-stash-restore";
 // S3-2: the port (nax supplies the policy behind it from its own module).
 export * from "#src/tools/owned-paths";
 export * from "#src/tools/package-managers";

package/dist/mcp/connect.js

@@ -83,6 +83,15 @@ function createHandle(config) {
         throw new McpConnectError(`MCP connect failed: ${messageOf(error)}`);
     }
 }
+/**
+ * The server's `initialize` instructions (#2517), or `undefined` for anything
+ * that is not a non-empty string: an empty one would render an empty prompt
+ * section, and a `getInstructions()` that returns nothing is the same silence.
+ */
+function serverInstructions(client) {
+    const text = client.getInstructions();
+    return typeof text === "string" && text !== "" ? text : undefined;
+}
 export async function connectMcp(config, opts) {
     const handle = createHandle(config);
     const client = new Client({ name: opts.clientInfo.name, version: opts.clientInfo.version });
@@ -95,7 +104,11 @@ export async function connectMcp(config, opts) {
             throw new McpConnectError("MCP connect failed: aborted");
         await client.connect(handle.transport, { signal, timeout: opts.timeoutMs });
         const tools = await listAll(client, signal, opts.timeoutMs);
-        return liveConnection(config, client, handle, tools, { graceMs, life });
+        return liveConnection(config, client, handle, tools, {
+            graceMs,
+            life,
+            instructions: serverInstructions(client),
+        });
     }
     catch (error) {
         await closeTransport(client, handle, graceMs, life);
@@ -127,6 +140,7 @@ function liveConnection(config, client, handle, tools, state) {
             return handle.pid();
         },
         tools,
+        ...(state.instructions !== undefined ? { instructions: state.instructions } : {}),
         call(name, input, opts) {
             if (closing !== undefined || life.exited)
                 return Promise.reject(new McpCallError(`MCP call ${name} failed: the connection is closed`));

package/dist/mcp/types.d.ts

@@ -31,6 +31,12 @@ export interface McpConnection {
     /** The stdio child process pid; null for HTTP. Read before close() — the SDK may clear it after. */
     readonly pid: number | null;
     readonly tools: readonly McpToolInfo[];
+    /**
+     * The server's own `initialize` instructions — how to use it, in its words
+     * (#2517). Absent when it sent none (or an empty string): an MCP server that
+     * says nothing must not produce an empty prompt section.
+     */
+    readonly instructions?: string;
     /** Server-side tool errors are `isError` results; transport failures throw McpCallError. */
     call(name: string, input: unknown, opts: McpCallOptions): Promise<McpCallResult>;
     /** stdio only: called once when the process exits without close() having been called. */

package/dist/native/auth.d.ts

@@ -29,8 +29,8 @@ export declare const _authDeps: {
     ambientAuthAvailable: typeof ambientAuthAvailable;
     providerIds: () => Promise<string[]>;
     /**
-     * Injectable timer pair — lets tests drive `anyAmbientCredential`'s
-     * expiry branch off a virtual clock instead of waiting the full 2s
+     * Injectable timer pair — lets tests drive ambient credential probes'
+     * expiry branches off a virtual clock instead of waiting the full 2s
      * production timeout. Mirrors `_heartbeatDeps` / `_idleWatchdogDeps`.
      *
      * @internal

package/dist/native/auth.js

@@ -41,8 +41,8 @@ export const _authDeps = {
     ambientAuthAvailable,
     providerIds: async () => (await defaultProviders()).map((provider) => provider.id),
     /**
-     * Injectable timer pair — lets tests drive `anyAmbientCredential`'s
-     * expiry branch off a virtual clock instead of waiting the full 2s
+     * Injectable timer pair — lets tests drive ambient credential probes'
+     * expiry branches off a virtual clock instead of waiting the full 2s
      * production timeout. Mirrors `_heartbeatDeps` / `_idleWatchdogDeps`.
      *
      * @internal
@@ -301,14 +301,14 @@ export async function providersWithoutCredentials(providerIds) {
     })).then((missing) => missing.filter((id) => id !== undefined));
     let timer;
     const expiry = new Promise((resolve) => {
-        timer = setTimeout(() => resolve([]), AMBIENT_PROBE_TIMEOUT_MS);
+        timer = _authDeps.setTimeout(() => resolve([]), AMBIENT_PROBE_TIMEOUT_MS);
     });
     try {
         return await Promise.race([sweep, expiry]);
     }
     finally {
         if (timer !== undefined)
-            clearTimeout(timer);
+            _authDeps.clearTimeout(timer);
     }
 }
 /**

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/failed-round-trip-spend.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Prices the tokens a failed or aborted round trip was billed for and attaches
+ * them to the thrown error (`session/partial-spend.ts`), where the turn loop's
+ * `completeWithRecovery` folds them into the turn's accumulated usage.
+ *
+ * nax-ai's `collectStream` hands the partial usage over on the error
+ * (`partialUsageOf`); only the adapter holds the rate card, so pricing happens
+ * here, once, with the same `priceCall` the success path uses.
+ */
+import type { Pricing } from "#src/cost/standard-types";
+/**
+ * Runs one round trip; if it throws, prices whatever it was billed first and
+ * attaches that to the error, which is rethrown untouched. A wrapper (rather
+ * than a catch at the call site) keeps `sendTurn` under the complexity ratchet.
+ */
+export declare function billedOnFailure<T>(rates: Pricing, roundTrip: () => Promise<T>): Promise<T>;

package/dist/native/failed-round-trip-spend.js

@@ -0,0 +1,33 @@
+/**
+ * Prices the tokens a failed or aborted round trip was billed for and attaches
+ * them to the thrown error (`session/partial-spend.ts`), where the turn loop's
+ * `completeWithRecovery` folds them into the turn's accumulated usage.
+ *
+ * nax-ai's `collectStream` hands the partial usage over on the error
+ * (`partialUsageOf`); only the adapter holds the rate card, so pricing happens
+ * here, once, with the same `priceCall` the success path uses.
+ */
+import { partialUsageOf } from "@nathapp/nax-ai";
+import { priceCall } from "#src/cost/core/index";
+import { attachPartialSpend } from "./session/partial-spend.js";
+function recordFailedRoundTripSpend(err, rates) {
+    const usage = partialUsageOf(err);
+    if (usage === undefined)
+        return;
+    const { costUsd, resolvedRates } = priceCall(usage, rates);
+    attachPartialSpend(err, { usage, costUsd, rates: resolvedRates });
+}
+/**
+ * Runs one round trip; if it throws, prices whatever it was billed first and
+ * attaches that to the error, which is rethrown untouched. A wrapper (rather
+ * than a catch at the call site) keeps `sendTurn` under the complexity ratchet.
+ */
+export async function billedOnFailure(rates, roundTrip) {
+    try {
+        return await roundTrip();
+    }
+    catch (err) {
+        recordFailedRoundTripSpend(err, rates);
+        throw err;
+    }
+}

package/dist/native/session/partial-spend.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Spend billed by a round trip that then failed.
+ *
+ * A failed or aborted request still bills the tokens it streamed (nax-ai's
+ * `partialUsageOf`). The adapter's `complete` closure is the only place that
+ * can price them, but it can only throw, so the priced spend rides on the
+ * thrown error's identity (a WeakMap, like `turn-spend.ts`) and the turn loop's
+ * `completeWithRecovery` folds it into the turn accumulator. `take` removes the
+ * entry, so an error reaching the fold twice cannot count twice.
+ */
+import type { PricingRates, TokenUsage } from "#src/cost/standard-types";
+export interface PartialSpend {
+    readonly usage: TokenUsage;
+    readonly costUsd: number;
+    readonly rates?: PricingRates;
+}
+/** Attaches the priced partial spend of a failed round trip to the error it threw. */
+export declare function attachPartialSpend(err: unknown, spend: PartialSpend): void;
+/** Removes and returns the partial spend attached to `err`, if any. */
+export declare function takePartialSpend(err: unknown): PartialSpend | undefined;

package/dist/native/session/partial-spend.js

@@ -0,0 +1,14 @@
+const partialByError = new WeakMap();
+/** Attaches the priced partial spend of a failed round trip to the error it threw. */
+export function attachPartialSpend(err, spend) {
+    if (typeof err === "object" && err !== null)
+        partialByError.set(err, spend);
+}
+/** Removes and returns the partial spend attached to `err`, if any. */
+export function takePartialSpend(err) {
+    if (typeof err !== "object" || err === null)
+        return undefined;
+    const spend = partialByError.get(err);
+    partialByError.delete(err);
+    return spend;
+}

package/dist/native/session/session.js

@@ -83,12 +83,19 @@ function openTranscriptStore(name, opts) {
 /**
  * Records, or clears, the session's system prompt at open. A helper so that
  * openNativeSession gains no branch.
+ *
+ * `providerInstructions` (the rendered `## MCP servers` section, #2517) is
+ * folded in HERE rather than kept in a map of its own: the model sees one
+ * `system` string, and every consumer of `state.systemPrompts`
+ * (`systemFieldFor`, the adapter's context-budget setup) keeps working
+ * unchanged.
  */
-function recordSystemPrompt(state, name, systemPrompt) {
-    if (systemPrompt === undefined)
+function recordSystemPrompt(state, name, prompts) {
+    const parts = [prompts.systemPrompt, prompts.providerInstructions].filter((part) => part !== undefined && part !== "");
+    if (parts.length === 0)
         state.systemPrompts.delete(name);
     else
-        state.systemPrompts.set(name, systemPrompt);
+        state.systemPrompts.set(name, parts.join("\n\n"));
 }
 /** The request field for the session's system prompt: `{ system }`, or `{}` when it has none. */
 export function systemFieldFor(state, sessionName) {
@@ -119,7 +126,7 @@ export async function openNativeSession(state, name, opts) {
         state.carryHistoryAcrossModels.add(name);
     else
         state.carryHistoryAcrossModels.delete(name);
-    recordSystemPrompt(state, name, opts.systemPrompt);
+    recordSystemPrompt(state, name, opts);
     const instructions = await openRepositoryInstructions(name, opts, store);
     state.repositoryInstructions.set(name, instructions);
     state.transcripts.set(name, {