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

package/dist/tools/policy-command-branch.d.ts

@@ -10,6 +10,7 @@
  * reaching `resolveWithin` back would close a cycle.
  */
 import type { BashApprovalMode } from "#src/config/bash-approval";
+import type { NaxDirIndex } from "./nax-dirs.ts";
 import type { OwnedPathsPolicy } from "./owned-paths.ts";
 import type { CompiledEntry } from "./policy-match.ts";
 import type { PolicyVerdict, ToolScope } from "./types.ts";
@@ -26,6 +27,8 @@ export interface BashCommandBranchArgs {
     /** S3-2: host-owned path rules; the `raw` screen hands it one candidate per live frame. */
     readonly ownedPaths: OwnedPathsPolicy;
     readonly resolvedRoot: string;
+    /** Per-policy cache of the `.nax` directories below the root, shared by every Bash call (#2493). */
+    readonly naxDirs?: NaxDirIndex;
     readonly denyBy: ReadonlyMap<string, CompiledEntry>;
     readonly askBy: ReadonlyMap<string, CompiledEntry>;
     readonly resolvePath: (candidate: string, cwd: string) => string | null;

package/dist/tools/policy-command-branch.js

@@ -12,7 +12,7 @@
 import { checkBashCommand } from "./policy-bash.js";
 import { screenRawBashCommand } from "./policy-bash-raw.js";
 export function commandBranch(args) {
-    const { tool, scope, input, grant, bashApproval, rawBashRefusal, sandboxWrapped, ownedPaths, resolvedRoot, denyBy, askBy, resolvePath, deny, askVerdict, } = args;
+    const { tool, scope, input, grant, bashApproval, rawBashRefusal, sandboxWrapped, ownedPaths, resolvedRoot, naxDirs, denyBy, askBy, resolvePath, deny, askVerdict, } = args;
     if (scope.commandField === undefined)
         return undefined;
     if (bashApproval === "raw") {
@@ -23,6 +23,7 @@ export function commandBranch(args) {
             command: input[scope.commandField],
             initialPath: resolvedRoot,
             root: resolvedRoot,
+            ...(naxDirs !== undefined ? { naxDirs } : {}),
             sandboxWrapped: sandboxWrapped === true,
             resolvePath,
             ownedPaths,
@@ -40,6 +41,7 @@ export function commandBranch(args) {
         ...(denyEntry !== undefined ? { denyEntry } : {}),
         ...(askEntry !== undefined ? { askEntry } : {}),
         initialPath: resolvedRoot,
+        ...(naxDirs !== undefined ? { naxDirs } : {}),
         resolvePath,
     });
     if (result.kind === "deny") {

package/dist/tools/policy.js

@@ -15,7 +15,9 @@
  */
 import { relative, resolve, sep } from "node:path";
 import { realOrRaw } from "#src/internal/realpath";
+import { claudeSettingsWriteRefusal } from "#src/sandbox/claude-settings";
 import { validateArgv } from "./exec-guard.js";
+import { createNaxDirIndex } from "./nax-dirs.js";
 import { EMPTY_OWNED_PATHS_POLICY } from "./owned-paths.js";
 import { commandBranch } from "./policy-command-branch.js";
 import { compileArgvPattern, compileRuleMap, globToRegExp, matchedArgvSource, matchedGlobSource, matchedRulePatterns, matchesAny, matchesArgvGrant, } from "./policy-match.js";
@@ -35,6 +37,8 @@ function isFieldlessScope(scope) {
 }
 export function compileToolPolicy(grants, root, options) {
     const resolvedRoot = realOrRaw(root);
+    // One downward `.nax` scan per compiled policy, shared by every Bash call it checks (#2493).
+    const naxDirs = createNaxDirIndex();
     const owned = options?.ownedPaths ?? EMPTY_OWNED_PATHS_POLICY;
     // nax#2115: the SAME transform `relativeTo` applies to every checked path, so
     // the guard compares like with like. A path outside the root yields a
@@ -88,6 +92,14 @@ export function compileToolPolicy(grants, root, options) {
      * denied and an ask on an ungranted call never becomes an approval prompt.
      */
     function applyPathRules(tool, rel, state) {
+        // US-006 (branch-review B1): the session-root Claude Code settings files are
+        // refused to the same mutating path tools the OS sandbox denies writes to.
+        // The port's `writeRefusal` cannot carry this one -- an embedder that injects
+        // nothing still gets the sandbox deny, so it must get the tool deny too --
+        // and both guards read the ONE list in `#src/sandbox/claude-settings`.
+        const settingsRefusal = claudeSettingsWriteRefusal(tool, rel, resolvedRoot);
+        if (settingsRefusal !== undefined)
+            return deny(`${tool} may not modify ${settingsRefusal}`);
         const ownedRefusal = owned.writeRefusal(tool, rel, { exemptRel: ownedWriteExemption, optIns: naxOptIns });
         if (ownedRefusal !== undefined)
             return deny(`${tool} may not modify ${ownedRefusal}`);
@@ -220,6 +232,7 @@ export function compileToolPolicy(grants, root, options) {
                 sandboxWrapped: options?.sandboxWrapped,
                 ownedPaths: owned,
                 resolvedRoot,
+                naxDirs,
                 denyBy,
                 askBy,
                 resolvePath: (candidate, cwd) => resolveWithin(resolvedRoot, resolve(cwd, candidate), owned),

package/dist/tools/provider-advertise.d.ts

@@ -40,6 +40,19 @@ export interface ResolvedProviderTools {
      * back apart (src/tools/provider-adapt.ts's header).
      */
     readonly entries: readonly ProviderGrantEntry[];
+    /**
+     * What each attached provider that still advertises a tool says about using
+     * it (#2517), in provider order — the raw texts, not the rendered section:
+     * rendering is a prompt concern (`provider-instructions.ts`), and a caller
+     * that reorders or drops entries must be able to (nax US-005 renders them).
+     *
+     * ABSENT when no provider contributed one, so "nobody spoke" and "everyone
+     * was silent" stay distinguishable rather than collapsing to `[]`.
+     */
+    readonly instructions?: readonly {
+        providerId: string;
+        text: string;
+    }[];
 }
 export declare function resolveProviderTools(providers: readonly ToolProvider[], stage: string, workdir: string, options?: {
     /**

package/dist/tools/provider-advertise.js

@@ -13,6 +13,28 @@ import { adaptProviderTool } from "./provider-adapt.js";
 import { expandProviderGrants } from "./provider-grants.js";
 import { sanitizeProviderTools } from "./provider-sanitize.js";
 import { providerAttachesTo } from "./provider-types.js";
+/**
+ * One provider's instructions, or `undefined` when it has none to give.
+ *
+ * A provider that throws costs one warn and nothing else: its tools stay
+ * advertised, because instructions are an aid and a broken aid must never
+ * withdraw a working capability. Never rejects.
+ */
+async function instructionsFor(provider, workdir) {
+    if (provider.instructions === undefined)
+        return undefined;
+    try {
+        const text = await provider.instructions(workdir);
+        return typeof text === "string" && text !== "" ? text : undefined;
+    }
+    catch (error) {
+        getSafeLogger()?.warn("mcp", `[provider] ${provider.id} instructions failed`, {
+            workdir,
+            reason: String(error),
+        });
+        return undefined;
+    }
+}
 export async function resolveProviderTools(providers, stage, workdir, options) {
     const tools = [];
     const entries = [];
@@ -20,6 +42,7 @@ export async function resolveProviderTools(providers, stage, workdir, options) {
     const skipped = [];
     const withheld = [];
     const providerIdByTool = new Map();
+    const instructions = [];
     for (const provider of providers) {
         if (!providerAttachesTo(provider, stage)) {
             skipped.push({ providerId: provider.id, reason: "stage-mismatch", stages: provider.stages });
@@ -40,12 +63,29 @@ export async function resolveProviderTools(providers, stage, workdir, options) {
                 localNames.push(tool.localName);
             }
             entries.push({ providerId: provider.id, localNames });
+            // Only a provider the model can actually use gets to speak: instructions
+            // for a capability `admits` withheld would describe tools that are not in
+            // the list, which is worse than saying nothing (#2517).
+            if (localNames.length > 0) {
+                const text = await instructionsFor(provider, workdir);
+                if (text !== undefined)
+                    instructions.push({ providerId: provider.id, text });
+            }
         }
         catch (error) {
             failures.push({ providerId: provider.id, reason: String(error) });
         }
     }
-    return { tools, grants: expandProviderGrants(entries), failures, skipped, withheld, providerIdByTool, entries };
+    return {
+        tools,
+        grants: expandProviderGrants(entries),
+        failures,
+        skipped,
+        withheld,
+        providerIdByTool,
+        entries,
+        ...(instructions.length > 0 ? { instructions } : {}),
+    };
 }
 /**
  * Bytes a tool list costs the prompt, paid on EVERY hop whether or not any

package/dist/tools/provider-instructions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The `## MCP servers` section (#2517): what each MCP server said about itself
+ * in its `initialize` result, rendered as one block of system prompt text.
+ *
+ * Those instructions come from an external process, exactly like a `discovered`
+ * provider tool's description, so they are the same prompt-injection surface and
+ * get the same first treatment: control characters are stripped, not trusted
+ * (`provider-sanitize.ts`). Line breaks and tabs are kept, because instructions
+ * are prose and a tab or a list break is formatting the server meant to send.
+ *
+ * They are then capped twice. Per server, so one verbose server cannot crowd its
+ * neighbours out of the section. In total, so the section's context cost stays
+ * bounded on every hop — the tax nax#1991's context-burn report is about. A cut
+ * per-server text says so with `…(truncated)`; a server that does not fit the
+ * total is dropped whole and the section says how many were (a half-rendered
+ * set of instructions is worse than one that admits it is incomplete).
+ */
+/** One server's instructions as the provider reported them. */
+type ProviderInstructionEntry = {
+    readonly providerId: string;
+    readonly text: string;
+};
+export declare const MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER = 2000;
+export declare const MCP_INSTRUCTIONS_MAX_CHARS_TOTAL = 6000;
+/**
+ * The section, or `undefined` when there is nothing to say — an empty section
+ * would spend prompt on a heading with no content under it.
+ *
+ * Per-server <= total, so the first server always fits and a non-empty input
+ * always renders at least one server.
+ */
+export declare function renderProviderInstructions(entries: readonly ProviderInstructionEntry[]): string | undefined;
+export {};

package/dist/tools/provider-instructions.js

@@ -0,0 +1,63 @@
+/**
+ * The `## MCP servers` section (#2517): what each MCP server said about itself
+ * in its `initialize` result, rendered as one block of system prompt text.
+ *
+ * Those instructions come from an external process, exactly like a `discovered`
+ * provider tool's description, so they are the same prompt-injection surface and
+ * get the same first treatment: control characters are stripped, not trusted
+ * (`provider-sanitize.ts`). Line breaks and tabs are kept, because instructions
+ * are prose and a tab or a list break is formatting the server meant to send.
+ *
+ * They are then capped twice. Per server, so one verbose server cannot crowd its
+ * neighbours out of the section. In total, so the section's context cost stays
+ * bounded on every hop — the tax nax#1991's context-burn report is about. A cut
+ * per-server text says so with `…(truncated)`; a server that does not fit the
+ * total is dropped whole and the section says how many were (a half-rendered
+ * set of instructions is worse than one that admits it is incomplete).
+ */
+export const MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER = 2000;
+export const MCP_INSTRUCTIONS_MAX_CHARS_TOTAL = 6000;
+const SECTION_HEADING = "## MCP servers";
+const TRUNCATION_MARKER = "…(truncated)";
+// C0 controls except tab (\u0009) and newline (\u000A), plus DEL. Carriage return
+// (\u000D) is NOT exempt: it is a line-break-ish byte that no MCP server needs in
+// prompt text, and keeping it would let a CRLF body smuggle a bare CR into the
+// system prompt.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control bytes is the point of this regex
+const CONTROL_CHARS = /[\u0000-\u0008\u000B-\u001F\u007F]/g;
+/**
+ * Caps text at `max` code POINTS, so a cut never splits a surrogate pair the
+ * way `String.prototype.slice` would. The marker is added on top of the cap:
+ * a cut text is `max` characters of content plus the note that it was cut.
+ */
+function capText(text, max) {
+    const points = [...text];
+    return points.length <= max ? text : `${points.slice(0, max).join("")}${TRUNCATION_MARKER}`;
+}
+function serverBlock(entry) {
+    const text = capText(entry.text.replace(CONTROL_CHARS, ""), MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER);
+    return `### ${entry.providerId}\n${text}`;
+}
+/**
+ * The section, or `undefined` when there is nothing to say — an empty section
+ * would spend prompt on a heading with no content under it.
+ *
+ * Per-server <= total, so the first server always fits and a non-empty input
+ * always renders at least one server.
+ */
+export function renderProviderInstructions(entries) {
+    if (entries.length === 0)
+        return undefined;
+    const blocks = [];
+    let total = 0;
+    for (const entry of entries) {
+        const block = serverBlock(entry);
+        if (total + block.length > MCP_INSTRUCTIONS_MAX_CHARS_TOTAL)
+            break;
+        total += block.length;
+        blocks.push(block);
+    }
+    const omitted = entries.length - blocks.length;
+    const tail = omitted === 0 ? "" : `\n\n(instructions omitted for ${omitted} more MCP server(s))`;
+    return [SECTION_HEADING, ...blocks].join("\n\n") + tail;
+}

package/dist/tools/provider-types.d.ts

@@ -31,6 +31,18 @@ export interface ToolProvider {
      * run executes stories in parallel worktrees.
      */
     tools(workdir: string): Promise<readonly ProviderTool[]>;
+    /**
+     * What the provider says about USING it (#2517), with the same
+     * `workdir` contract as `tools` — an MCP server's own `initialize`
+     * instructions, plus whatever the host configured. Optional: a provider with
+     * nothing to say contributes no section.
+     *
+     * Called only for a provider that attached to this stage AND still has at
+     * least one advertised tool after `admits`, so instructions never describe a
+     * capability the model cannot see, and an empty or throwing answer costs the
+     * caller nothing (`provider-advertise.ts`).
+     */
+    instructions?(workdir: string): Promise<string | undefined>;
 }
 /**
  * No `__`: that sequence is the namespace separator, and an id containing it

package/dist/tools/run-command.d.ts

@@ -104,4 +104,19 @@ export declare function substituteCommand(template: string, values: Record<strin
 export declare function substituteCommandSpec(spec: QualityCommandSpec, values: Record<string, string | readonly string[]>): QualityCommandSpec | {
     error: string;
 };
+/**
+ * US-006: the platform seam `execSandboxNote` reads to decide whether the
+ * description carries the macOS ps note.
+ *
+ * Kept out of `src/tools/index.ts` on purpose: `src/index.ts` takes named
+ * exports from that barrel, so a seam there would reach the package's public
+ * `.` entry, where `_` names are forbidden. It DOES reach `./internal`, because
+ * `src/internal.ts` star-exports this module — which is exactly where a
+ * `_*Deps` seam belongs (nax-only, outside semver), and why adding it here
+ * needed the one-line api/ snapshot update. Tests reach it through
+ * `#src/tools/run-command`.
+ */
+export declare const _runCommandToolDeps: {
+    platform: () => NodeJS.Platform;
+};
 export declare function createRunCommandTool(declared: ReadonlyMap<string, QualityCommandSpec>, opts?: RunCommandToolOptions): CodingTool;

package/dist/tools/run-command.js

@@ -194,10 +194,25 @@ function otherCommandsDeclaring(declared, key, currentCommand) {
     }
     return names;
 }
+/**
+ * US-006: the platform seam `execSandboxNote` reads to decide whether the
+ * description carries the macOS ps note.
+ *
+ * Kept out of `src/tools/index.ts` on purpose: `src/index.ts` takes named
+ * exports from that barrel, so a seam there would reach the package's public
+ * `.` entry, where `_` names are forbidden. It DOES reach `./internal`, because
+ * `src/internal.ts` star-exports this module — which is exactly where a
+ * `_*Deps` seam belongs (nax-only, outside semver), and why adding it here
+ * needed the one-line api/ snapshot update. Tests reach it through
+ * `#src/tools/run-command`.
+ */
+export const _runCommandToolDeps = {
+    platform: () => process.platform,
+};
 function execSandboxNote(launcher) {
     const state = launcher?.state;
     if (state?.kind === "available")
-        return ` An "argv" call runs ${sandboxSentence(state.network, state.sharedTmp !== false)}`;
+        return ` An "argv" call runs ${sandboxSentence(state.network, state.sharedTmp !== false, _runCommandToolDeps.platform())}`;
     if (state?.kind === "unavailable")
         return ` ${unsandboxedSentence(state.reason)}`;
     return "";

package/dist/tools/tool-audit.d.ts

@@ -202,7 +202,7 @@ export interface ToolSurfaceDraft {
 /** A draft stamped with the transport (and, on ACP, the narrowed profile). */
 export interface ToolSurfaceRecord extends ToolSurfaceDraft {
     readonly transport: "native" | "acp";
-    readonly profile?: "full" | "read";
+    readonly profile?: "full" | "review" | "read";
 }
 export declare function createToolAuditSink(opts: {
     dir: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.87.1",
+  "version": "0.88.0-canary.2",
   "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.87.1",
+    "@nathapp/nax-ai": "0.88.0-canary.2",
     "zod": "^4.3.6"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
     "provenance": true,
-    "tag": "latest"
+    "tag": "canary"
   }
 }