@nathapp/nax-agent 0.87.0 → 0.87.1

package/CHANGELOG.md

@@ -4,6 +4,10 @@ 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.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/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/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/index.d.ts

@@ -28,7 +28,7 @@ export type { CodingToolOutcome, CodingToolRuntime, ToolCallContext } from "./ru
 export { _codingToolDeps, _resetBuiltinsForTest, createCodingToolRuntime, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, registerBuiltinCodingTools, } from "./runtime.ts";
 export { SCRATCHPAD_DIR, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool } from "./scratchpad.ts";
 export { _spillDeps, applyModelTruncationPolicy, type ModelTruncationOptions, SPILL_DIR, type SpillRequest, spillRelativePath, writeSpill, } from "./spill.ts";
-export type { RegisteredSink, ToolAuditHeader, ToolAuditSink, ToolCallRecord } from "./tool-audit.ts";
+export type { RegisteredSink, ToolAuditHeader, ToolAuditSink, ToolCallRecord, ToolSurfaceDraft, ToolSurfaceRecord, } from "./tool-audit.ts";
 export { createNoOpToolAuditSink, createToolAuditSink, flushOpenToolAuditSinks, registerToolAuditSink, unregisterToolAuditSink, } from "./tool-audit.ts";
 export { cutBufferToByteCap, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, READ_CEILING, type TruncateForModelOptions, type TruncationDirection, type TruncationResult, truncateForModel, truncationDirectionFor, } from "./truncate.ts";
 export type { CodingToolName, PolicyVerdict, ToolGrant, ToolPolicy, ToolScope } from "./types.ts";

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

@@ -9,6 +9,24 @@ export interface ResolvedProviderTools {
         providerId: string;
         reason: string;
     }[];
+    /**
+     * Providers whose configured `stages` exclude this hop's stage, with the
+     * stages they were configured for (#2410 gap 2: a misconfigured `stages`
+     * must be visible, not silent). The scope-none arm contributes the
+     * whole-layer `provider-scope:none` row (permission profile `safe`, or a
+     * `rules` scope that resolved no providers).
+     */
+    readonly skipped: readonly {
+        providerId: string;
+        reason: "stage-mismatch" | "provider-scope:none";
+        stages: readonly string[];
+    }[];
+    /** Sanitised tools a scoped stage's `admits` rejected (#2410 gap 1). */
+    readonly withheld: readonly {
+        providerId: string;
+        localName: string;
+        reason: "not-admitted";
+    }[];
     /**
      * Advertised tool name -> owning provider id, carried explicitly so the
      * ledger never has to parse the `<id>__<local>` name apart (a naming

package/dist/tools/provider-advertise.js

@@ -2,9 +2,13 @@
  * Per-hop resolution of provider tools.
  *
  * A provider whose `tools()` rejects is DROPPED, not fatal: a broken provider
- * must never wedge a run. The failure is logged by the caller, which owns the
- * logger; this module stays pure so it can be tested without one.
+ * must never wedge a run. The failure reason is carried in `failures` and
+ * logged by the caller, which owns the logger. Stage mismatches and
+ * `admits`-rejected tools are carried in `skipped`/`withheld` (#2410) and the
+ * stage skip is logged once here at debug — the null-safe logger keeps the
+ * module testable without one.
  */
+import { getSafeLogger } from "#src/infra/index";
 import { adaptProviderTool } from "./provider-adapt.js";
 import { expandProviderGrants } from "./provider-grants.js";
 import { sanitizeProviderTools } from "./provider-sanitize.js";
@@ -13,16 +17,23 @@ export async function resolveProviderTools(providers, stage, workdir, options) {
     const tools = [];
     const entries = [];
     const failures = [];
+    const skipped = [];
+    const withheld = [];
     const providerIdByTool = new Map();
     for (const provider of providers) {
-        if (!providerAttachesTo(provider, stage))
+        if (!providerAttachesTo(provider, stage)) {
+            skipped.push({ providerId: provider.id, reason: "stage-mismatch", stages: provider.stages });
+            getSafeLogger()?.debug("mcp", `[provider] ${provider.id} not attached`, { stage, stages: provider.stages });
             continue;
+        }
         try {
             const sanitized = sanitizeProviderTools(provider.kind, await provider.tools(workdir));
             const localNames = [];
             for (const tool of sanitized) {
-                if (options?.admits !== undefined && !options.admits(provider.id, tool.localName))
+                if (options?.admits !== undefined && !options.admits(provider.id, tool.localName)) {
+                    withheld.push({ providerId: provider.id, localName: tool.localName, reason: "not-admitted" });
                     continue;
+                }
                 const adapted = adaptProviderTool(provider.id, tool);
                 tools.push(adapted);
                 providerIdByTool.set(adapted.name, provider.id);
@@ -34,7 +45,7 @@ export async function resolveProviderTools(providers, stage, workdir, options) {
             failures.push({ providerId: provider.id, reason: String(error) });
         }
     }
-    return { tools, grants: expandProviderGrants(entries), failures, providerIdByTool, entries };
+    return { tools, grants: expandProviderGrants(entries), failures, skipped, withheld, providerIdByTool, entries };
 }
 /**
  * Bytes a tool list costs the prompt, paid on EVERY hop whether or not any

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

@@ -164,8 +164,50 @@ export interface ToolAuditHeader {
     readonly storyId?: string;
     readonly sessionRole?: string;
 }
+/**
+ * Which MCP provider tools a session was OFFERED — the delivery-side twin of
+ * the per-call `calls` rows (#2410 gap 1). Present in the file body as
+ * `toolSurface` whenever a session's hop resolved provider tools, so
+ * "the model ignored the tool" can be told apart from "the tool was never
+ * advertised".
+ */
+export interface ToolSurfaceDraft {
+    /** The pipeline stage the session was resolved for. */
+    readonly stage: string;
+    /** The op's materialized declaration (what the profile/delivery decision saw). */
+    readonly declaredTools: readonly string[];
+    /** Provider tools actually offered: (providerId, local names) with content. */
+    readonly advertised: readonly {
+        providerId: string;
+        names: readonly string[];
+    }[];
+    /** Provider tools resolved but not offered, with why. */
+    readonly withheld: readonly {
+        providerId: string;
+        name?: string;
+        reason: string;
+    }[];
+    /** Providers skipped whole, with why. */
+    readonly skippedProviders: readonly {
+        id: string;
+        reason: string;
+        stages?: readonly string[];
+    }[];
+    /** Providers whose `tools()` rejected (same rows as `failures`). */
+    readonly failures: readonly {
+        providerId: string;
+        reason: string;
+    }[];
+}
+/** 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";
+}
 export declare function createToolAuditSink(opts: {
     dir: string;
     sessionName: string;
     header?: ToolAuditHeader;
+    /** The session's MCP tool surface (#2410): present ⇒ the file is written even with zero calls. */
+    toolSurface?: ToolSurfaceRecord;
 }): RegisteredSink;

package/dist/tools/tool-audit.js

@@ -129,7 +129,10 @@ export function createToolAuditSink(opts) {
     // may still run afterwards must not write a second, non-partial file.
     let partialFlushed = false;
     const write = async (partial) => {
-        if (calls.length === 0)
+        // Zero calls normally means "nothing to audit" — but a surface with no
+        // calls is exactly the never-called session #2410 exists to expose, so it
+        // must still produce its file.
+        if (calls.length === 0 && opts.toolSurface === undefined)
             return;
         await mkdir(opts.dir, { recursive: true });
         const body = JSON.stringify({
@@ -139,6 +142,7 @@ export function createToolAuditSink(opts) {
             // Additive and optional: absent on a normal flush, `true` only when the
             // shutdown path persisted a buffer its hop never closed.
             ...(partial ? { partial: true } : {}),
+            ...(opts.toolSurface !== undefined ? { toolSurface: opts.toolSurface } : {}),
             calls: redactRowStrings(calls),
         }, null, 2);
         const prefix = runId !== undefined ? `${runId}-` : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.87.0",
+  "version": "0.87.1",
   "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
   "license": "MIT",
   "author": "William Khoo",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.77",
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@nathapp/nax-ai": "0.87.0",
+    "@nathapp/nax-ai": "0.87.1",
     "zod": "^4.3.6"
   },
   "publishConfig": {