@nathapp/nax-agent 0.91.7-canary.2 → 0.91.7-canary.4

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to `@nathapp/nax-agent` are recorded here. The format follow
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). While the version is `0.x`, a minor
 release may change the public API.
 
+## [0.91.7-canary.4] - 2026-10-27
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
+## [0.91.7-canary.3] - 2026-10-27
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
 ## [0.91.7-canary.2] - 2026-10-26
 
 - No changes in this package. Released in lockstep with the other nax packages.

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

@@ -67,11 +67,13 @@ export declare function unsandboxedToolOptions(args: {
  */
 export declare function unsandboxedRuntimeOption(args: {
     readonly unsandboxedCommands?: boolean;
+    readonly askOnUnsandboxed?: boolean;
     readonly bashApproval: BashApprovalMode;
 }): {
     readonly unsandboxed?: {
         readonly enabled: boolean;
         readonly bashApproval: BashApprovalMode;
+        readonly alwaysAsk?: boolean;
     };
 };
 export declare function buildDeclaredCommandTools(args: DeclaredCommandToolsArgs): CodingTool[];

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

@@ -23,7 +23,15 @@ export function unsandboxedToolOptions(args) {
  * raise it.
  */
 export function unsandboxedRuntimeOption(args) {
-    return args.unsandboxedCommands === true ? { unsandboxed: { enabled: true, bashApproval: args.bashApproval } } : {};
+    if (args.unsandboxedCommands !== true)
+        return {};
+    return {
+        unsandboxed: {
+            enabled: true,
+            bashApproval: args.bashApproval,
+            ...(args.askOnUnsandboxed === true ? { alwaysAsk: true } : {}),
+        },
+    };
 }
 export function buildDeclaredCommandTools(args) {
     return [

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

@@ -148,6 +148,7 @@ export declare function buildCodingToolSupport(args: {
      * the runtime's own reading of the field is a later story.
      */
     unsandboxedCommands?: boolean;
+    askOnUnsandboxed?: boolean;
     /** US-001: forwarded into ToolRunContext so Bash/Exec can SIGKILL on cancel. */
     abortSignal?: AbortSignal;
     /**

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

@@ -127,7 +127,11 @@ export function buildCodingToolSupport(args) {
         // schema — with the locally resolved mode, so a caller that left
         // `bashApproval` unset cannot enable an escape under a mode it did not
         // choose.
-        ...unsandboxedRuntimeOption({ unsandboxedCommands: args.unsandboxedCommands, bashApproval }),
+        ...unsandboxedRuntimeOption({
+            unsandboxedCommands: args.unsandboxedCommands,
+            askOnUnsandboxed: args.askOnUnsandboxed,
+            bashApproval,
+        }),
     });
     const tools = runtime.advertised(advertised);
     // The fixed per-hop cost of advertising provider tools: their schemas enter

package/dist/runtime/node-runtime.js

@@ -67,6 +67,11 @@ function exitStatus(code, signal) {
         return code;
     return 128 + (signal !== null ? (osConstants.signals[signal] ?? 0) : 0);
 }
+/**
+ * `Readable.toWeb` is declared against `node:stream/web`'s `ReadableStream`, while
+ * `AgentSpawnResult` carries the global one. They are the same class at runtime and differ
+ * only in how their `getReader` overloads are written, so the bridge has to go via `unknown`.
+ */
 function toWeb(stream) {
     return stream === null ? emptyStream() : Readable.toWeb(stream);
 }

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

@@ -4,6 +4,7 @@
  * @nathapp/nax-agent-acp backend (S4) reuses these types unchanged.
  */
 import type { CommandInterceptor } from "#src/command-interceptor/index";
+import type { CommandShadow } from "#src/command-safety/types";
 import type { TokenUsage } from "#src/cost/standard-types";
 import type { TranscriptStore } from "#src/native/session/transcript-types";
 import type { ProtectedPathsPolicy } from "#src/tools/protected-paths";
@@ -43,6 +44,7 @@ export interface AgentSessionHostPorts {
     /** Paths the sandbox and the read tools deny. Default: the configured credentials directory, if any. */
     readonly protectedPaths?: ProtectedPathsPolicy;
     readonly commandInterceptor?: CommandInterceptor;
+    readonly commandShadow?: CommandShadow;
 }
 export interface CreateAgentSessionOptions {
     /** The driver: `nativeBackend({ model })`, or an ACP backend. Native-only options live on the backend. */

package/dist/session/native-backend-options.d.ts

@@ -1,4 +1,12 @@
+/**
+ * nativeBackend's options (S4 spec 5.2): the native half of the facade's
+ * createAgentSession options, validated here rather than by the facade. zod
+ * checks the shape; the caller's own object is kept as `raw` (zod returns
+ * copies, which would break identity for handlers the caller owns).
+ */
+import { z } from "zod";
 import type { BashApprovalMode } from "#src/config/bash-approval";
+import { SandboxConfigSchema } from "#src/config/schemas-sandbox";
 import type { NativeCatalogOverrides } from "#src/native/client";
 import type { CredentialSource } from "#src/native/credentials/session-source";
 import type { LoopHandlerSet } from "#src/native/session/loop-events/types";
@@ -17,6 +25,17 @@ export interface NativeBackendOptions {
     readonly loopHandlerRole?: string;
     readonly hostPorts?: AgentSessionHostPorts;
     readonly bashApproval?: BashApprovalMode;
+    /** Ask before a per-call sandbox escape, including under raw; requires allowUnsandboxedCommands. */
+    readonly askOnUnsandboxed?: boolean;
+    /** Gate Bash when the sandbox is disabled or unavailable at session open. */
+    readonly askWhenSandboxDown?: boolean;
+    /** Keep provider-designated mutating tool asks outside the ask profile too. */
+    readonly askDiscoveredTools?: boolean;
+    /** Rule overlays appended to the profile's own permission rules. */
+    readonly askRules?: readonly string[];
+    readonly denyRules?: readonly string[];
+    /** Partial sandbox input, validated here and default-filled at posture resolution. */
+    readonly sandbox?: z.input<typeof SandboxConfigSchema>;
     readonly allowUnsandboxed?: boolean;
     /** Narrow the declared tools to these names (built-in names, `<provider>__<tool>`, or `<provider>__*`); scratchpad tools are always kept. */
     readonly allowedTools?: readonly string[];

package/dist/session/native-backend-options.js

@@ -5,6 +5,7 @@
  * copies, which would break identity for handlers the caller owns).
  */
 import { z } from "zod";
+import { SandboxConfigSchema } from "#src/config/schemas-sandbox";
 import { parseNativeModel } from "#src/native/models";
 import { compactionSettingsSchema } from "#src/native/session/compaction-settings";
 import { isInstructionFileName } from "#src/native/session/instruction-file-name";
@@ -41,10 +42,19 @@ const OptionsSchema = z.strictObject({
         protectedPaths: z
             .custom((value) => isRecord(value) && isStringArray(value.gitExcludePathspecs) && isStringArray(value.gitIgnorePatterns), "must be a protected-paths policy with gitExcludePathspecs and gitIgnorePatterns string arrays")
             .optional(),
+        commandShadow: z
+            .custom(hasMethods(["observe", "settle", "drain"]), "must implement observe, settle and drain")
+            .optional(),
         commandInterceptor: z.custom(hasMethods(["intercept"]), "must implement intercept").optional(),
     })
         .optional(),
     bashApproval: z.enum(["raw", "gated", "escalate"]).optional(),
+    askOnUnsandboxed: z.boolean().optional(),
+    askWhenSandboxDown: z.boolean().optional(),
+    askDiscoveredTools: z.boolean().optional(),
+    askRules: z.array(z.string().min(1)).optional(),
+    denyRules: z.array(z.string().min(1)).optional(),
+    sandbox: SandboxConfigSchema.optional(),
     allowUnsandboxed: z.boolean().optional(),
     allowedTools: z.array(z.string().min(1)).optional(),
     allowUnsandboxedCommands: z.boolean().optional(),

package/dist/session/native-backend.js

@@ -14,6 +14,7 @@ import { NativeSessionAdapter } from "#src/native/session-adapter";
 import { resolveProviderTools } from "#src/tools/provider-advertise";
 import { AgentSessionError } from "./agent-session-errors.js";
 import { nativeProfileRules, parseNativeBackendOptions, } from "./native-backend-options.js";
+import { effectiveBashApproval, nativePostureRules } from "./native-posture-rules.js";
 import { createSessionAskLink, createSessionAskResolver } from "./session-ask-link.js";
 import { createSessionInteractionHandler, embedderToolDescriptor } from "./session-interaction.js";
 import { buildSessionToolSupport, defaultProtectedPaths, providerAdmits, resolveSessionLauncher, SESSION_STAGE, } from "./session-tool-support.js";
@@ -41,7 +42,8 @@ async function openNative(resolved, ctx) {
     const raw = resolved.raw;
     if (ctx.resume !== undefined && raw.carryHistoryAcrossModels !== true)
         checkResumeModel(ctx.resume.doc, ctx.sessionId, raw.model);
-    const { bashApproval, allowUnsandboxed, allowUnsandboxedCommands } = nativeProfileRules(ctx.profile, raw);
+    const { bashApproval: profileMode, allowUnsandboxed, allowUnsandboxedCommands, } = nativeProfileRules(ctx.profile, raw);
+    const posture = nativePostureRules(ctx.profile, raw);
     const protectedPaths = {
         ...defaultProtectedPaths(raw.credentials !== undefined),
         ...raw.hostPorts?.protectedPaths,
@@ -50,9 +52,11 @@ async function openNative(resolved, ctx) {
         profile: ctx.profile,
         root: ctx.workdir,
         protectedPaths,
-        bashApproval,
+        bashApproval: profileMode,
         allowUnsandboxed,
+        config: posture.sandbox,
     });
+    const bashApproval = effectiveBashApproval(profileMode, posture.askWhenSandboxDown, sandbox.kind);
     const providerTools = ctx.profile === "none" || raw.toolProviders === undefined
         ? undefined
         : await resolveProviderTools(raw.toolProviders, SESSION_STAGE, ctx.workdir, raw.allowedTools !== undefined ? { admits: providerAdmits(raw.allowedTools) } : undefined);
@@ -76,6 +80,11 @@ async function openNative(resolved, ctx) {
         launcher,
         askResolver: createSessionAskResolver(createSessionAskLink({ port: ctx.asks, currentCallId: () => callId })),
         interceptor: raw.hostPorts?.commandInterceptor,
+        askRules: posture.askRules,
+        denyRules: posture.denyRules,
+        askOnUnsandboxed: posture.askOnUnsandboxed,
+        askDiscoveredTools: posture.askDiscoveredTools,
+        commandShadow: raw.hostPorts?.commandShadow,
         // US-003: the profile's validated opt-in, so an interactive "full" session
         // can offer Bash's per-call escape without turning the sandbox off.
         ...(allowUnsandboxedCommands ? { unsandboxedCommands: true } : {}),
@@ -83,6 +92,7 @@ async function openNative(resolved, ctx) {
     const interactionHandler = createSessionInteractionHandler({
         sessionId: ctx.sessionId,
         runtime: support.runtime,
+        unavailableTools: new Set((support.declaredTools ?? []).filter((name) => !support.tools.some((tool) => tool.name === name))),
         embedderTools: new Map(ctx.tools.map((tool) => [tool.name, tool])),
         asks: ctx.asks,
         turnSignal: ctx.turnSignal,

package/dist/session/native-posture-rules.d.ts

@@ -0,0 +1,18 @@
+/** Optional native-session overlays, separate from the existing profile defaults. */
+import type { BashApprovalMode } from "#src/config/bash-approval";
+import { type SandboxConfig } from "#src/config/schemas-sandbox";
+import type { SandboxState } from "#src/sandbox/index";
+import type { ToolGrant } from "#src/tools/types";
+import type { AgentSessionProfile } from "./agent-session-types.ts";
+import type { NativeBackendOptions } from "./native-backend-options.ts";
+export interface ResolvedPostureRules {
+    readonly askRules: readonly ToolGrant[];
+    readonly denyRules: readonly ToolGrant[];
+    readonly sandbox: SandboxConfig;
+    readonly askOnUnsandboxed: boolean;
+    readonly askWhenSandboxDown: boolean;
+    readonly askDiscoveredTools: boolean;
+}
+export declare function nativePostureRules(profile: AgentSessionProfile, raw: NativeBackendOptions): ResolvedPostureRules;
+/** Snapshot the sandbox posture at open; a running session never silently changes modes. */
+export declare function effectiveBashApproval(profileMode: BashApprovalMode, askWhenSandboxDown: boolean, sandboxKind: SandboxState["kind"]): BashApprovalMode;

package/dist/session/native-posture-rules.js

@@ -0,0 +1,33 @@
+import { DEFAULT_SANDBOX_CONFIG, SandboxConfigSchema } from "#src/config/schemas-sandbox";
+import { parseRuleList } from "#src/permissions/grammar";
+import { AgentSessionError } from "./agent-session-errors.js";
+export function nativePostureRules(profile, raw) {
+    const toolOnlyOptions = [
+        "askRules",
+        "denyRules",
+        "askOnUnsandboxed",
+        "askWhenSandboxDown",
+        "askDiscoveredTools",
+    ];
+    for (const name of toolOnlyOptions) {
+        if ((profile === "none" || profile === "read") && raw[name] !== undefined) {
+            const path = `backend.${name}`;
+            throw new AgentSessionError(`Invalid agent session options: ${path} applies to profiles "ask", "full" and "review" only`, "AGENT_SESSION_INVALID_OPTIONS", { path });
+        }
+    }
+    if (raw.askOnUnsandboxed === true && raw.allowUnsandboxedCommands !== true) {
+        throw new AgentSessionError("Invalid agent session options: backend.askOnUnsandboxed requires backend.allowUnsandboxedCommands: true", "AGENT_SESSION_INVALID_OPTIONS", { path: "backend.askOnUnsandboxed" });
+    }
+    return {
+        askOnUnsandboxed: raw.askOnUnsandboxed === true,
+        askWhenSandboxDown: raw.askWhenSandboxDown === true,
+        askDiscoveredTools: raw.askDiscoveredTools === true,
+        askRules: parseRuleList(raw.askRules ?? []),
+        denyRules: parseRuleList(raw.denyRules ?? []),
+        sandbox: raw.sandbox === undefined ? DEFAULT_SANDBOX_CONFIG : SandboxConfigSchema.parse(raw.sandbox),
+    };
+}
+/** Snapshot the sandbox posture at open; a running session never silently changes modes. */
+export function effectiveBashApproval(profileMode, askWhenSandboxDown, sandboxKind) {
+    return askWhenSandboxDown && sandboxKind !== "available" ? "gated" : profileMode;
+}

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

@@ -9,6 +9,8 @@ export interface SessionInteractionDeps {
     readonly sessionId: string;
     readonly runtime: CodingToolRuntime;
     readonly embedderTools: ReadonlyMap<string, EmbedderTool>;
+    /** Declared coding tools withheld by the runtime's advertisement policy. Never execute these calls. */
+    readonly unavailableTools?: ReadonlySet<string>;
     readonly asks: SessionAskPort;
     /** The running turn's signal (a never-aborting one between turns). */
     readonly turnSignal: () => AbortSignal;

package/dist/session/session-interaction.js

@@ -168,8 +168,15 @@ export function createSessionInteractionHandler(deps) {
         async onInteraction(request) {
             if (request.kind === "question")
                 return answerQuestion(deps, request.text);
-            if (request.kind === "context-tool")
+            if (request.kind === "context-tool") {
+                // A model may still call a denied tool it remembers from earlier turns.
+                // Keep it hidden, but distinguish a policy refusal from an unknown name.
+                if (deps.unavailableTools?.has(request.name)) {
+                    const reason = `Tool "${request.name}" is not available under the session policy`;
+                    return { answer: `Denied: ${reason}`, denied: { reason, breach: false } };
+                }
                 throw toolError(`Unknown tool "${request.name}"`, request.name);
+            }
             const tool = deps.embedderTools.get(request.name);
             return tool !== undefined ? runEmbedderTool(deps, tool, request) : runCodingTool(deps, request);
         },

package/dist/session/session-tool-support.d.ts

@@ -1,6 +1,8 @@
 import { type CodingToolSupport } from "#src/coding-tools/coding-tool-support";
 import type { CommandInterceptor } from "#src/command-interceptor/index";
+import type { CommandShadow } from "#src/command-safety/types";
 import type { BashApprovalMode } from "#src/config/bash-approval";
+import { type SandboxConfig } from "#src/config/schemas-sandbox";
 import type { AskResolver } from "#src/permissions/index";
 import type { CommandLauncher, SandboxState } from "#src/sandbox/index";
 import type { ProtectedPathsPolicy } from "#src/tools/protected-paths";
@@ -35,6 +37,7 @@ export interface SessionLauncherArgs {
      */
     readonly bashApproval: BashApprovalMode;
     readonly allowUnsandboxed: boolean;
+    readonly config?: SandboxConfig;
 }
 /** What the floor decided: the launcher to run under (if any), and the state to report. */
 export interface ResolvedSessionLauncher {
@@ -58,6 +61,11 @@ export interface SessionToolSupportArgs {
     readonly launcher: CommandLauncher | undefined;
     readonly askResolver: AskResolver;
     readonly interceptor: CommandInterceptor | undefined;
+    readonly askRules?: readonly ToolGrant[];
+    readonly denyRules?: readonly ToolGrant[];
+    readonly askOnUnsandboxed?: boolean;
+    readonly askDiscoveredTools?: boolean;
+    readonly commandShadow?: CommandShadow;
     /**
      * US-003: offer Bash's per-call `unsandboxed` argument for this session
      * (from `nativeProfileRules(...).allowUnsandboxedCommands`). Optional and

package/dist/session/session-tool-support.js

@@ -73,7 +73,7 @@ export async function resolveSessionLauncher(args) {
         return { launcher: undefined, sandbox: { kind: "disabled" } };
     }
     const launcher = await resolveSessionSandbox({
-        config: DEFAULT_SANDBOX_CONFIG,
+        config: args.config ?? DEFAULT_SANDBOX_CONFIG,
         root: args.root,
         needsLauncher: true,
         protectedPaths: args.protectedPaths,
@@ -101,6 +101,14 @@ function narrowBuiltIns(profileTools, allowedTools) {
     const allowed = new Set(allowedTools);
     return profileTools.filter((tool) => UNIVERSAL_CODING_TOOLS.includes(tool) || allowed.has(tool));
 }
+/** Optional overlays share one forwarding point for future posture knobs. */
+function postureToolOptions(args) {
+    return {
+        ...(args.denyRules !== undefined ? { denyRules: args.denyRules } : {}),
+        ...(args.askOnUnsandboxed !== undefined ? { askOnUnsandboxed: args.askOnUnsandboxed } : {}),
+        ...(args.commandShadow !== undefined ? { commandShadow: args.commandShadow } : {}),
+    };
+}
 export function buildSessionToolSupport(args) {
     const profileTools = narrowBuiltIns(declaredToolsFor(args.profile, args.protectedPaths), args.allowedTools);
     // CodingToolName enumerates built-ins, but the runtime also accepts provider names.
@@ -108,13 +116,14 @@ export function buildSessionToolSupport(args) {
         ...new Set([...profileTools, ...(args.providerTools?.tools.map((tool) => tool.name) ?? [])]),
     ];
     const grants = [...grantsFor(profileTools), ...(args.providerTools?.grants ?? [])];
-    // Only the "ask" profile puts a discovered, non-read-only tool to the person; "full" never asks.
+    // Provider asks remain opt-in outside "ask"; configured rules follow them.
     const askRules = [
         ...askRulesFor(profileTools, args.bashApproval, args.profile),
-        ...(args.profile === "ask" ? (args.providerTools?.askTools ?? []) : []).map((tool) => ({
+        ...(args.profile === "ask" || args.askDiscoveredTools ? (args.providerTools?.askTools ?? []) : []).map((tool) => ({
             tool: tool,
             patterns: ["*"],
         })),
+        ...(args.askRules ?? []),
     ];
     const providerInstructions = renderProviderInstructions(args.providerTools?.instructions ?? []);
     const support = buildCodingToolSupport({
@@ -139,6 +148,7 @@ export function buildSessionToolSupport(args) {
         ...(args.interceptor !== undefined ? { interceptor: args.interceptor } : {}),
         ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
         ...unsandboxedToolOptions(args),
+        ...postureToolOptions(args),
     });
     // Unreachable while the scratchpad trio is always declared and granted; kept for the type.
     if (support === undefined) {

package/dist/session-store/session-lock.js

@@ -161,7 +161,10 @@ export function acquireSessionLock(path, deps, isAlive) {
             rmSync(temp, { force: true });
         }
     }, LOCK_HEARTBEAT_MS);
-    timer.unref();
+    // Bun returns a number and Node a Timeout; only the latter can be unref'd, and only it
+    // needs to be (a number handle never holds the loop open on its own).
+    if (typeof timer !== "number")
+        timer.unref();
     return async () => {
         try {
             // The heartbeat stays live while release waits out contention.

package/dist/tools/runtime-calltool.d.ts

@@ -117,6 +117,7 @@ export declare function resolveUnsandboxedCall(p: {
     option: {
         readonly enabled: boolean;
         readonly bashApproval: BashApprovalMode;
+        readonly alwaysAsk?: boolean;
     } | undefined;
 }): UnsandboxedCall | undefined;
 /**

package/dist/tools/runtime-calltool.js

@@ -81,7 +81,7 @@ export function resolveUnsandboxedCall(p) {
     return {
         kind: "unsandboxed",
         suffix: unsandboxedReasonSuffix(p.input),
-        asksOnAllow: p.option.bashApproval !== "raw",
+        asksOnAllow: p.option.alwaysAsk === true || p.option.bashApproval !== "raw",
     };
 }
 /** The reason a converted allow carries (spec US-006), before the suffix. */

package/dist/tools/runtime.d.ts

@@ -159,5 +159,6 @@ export declare function createCodingToolRuntime(opts: {
     unsandboxed?: {
         readonly enabled: boolean;
         readonly bashApproval: BashApprovalMode;
+        readonly alwaysAsk?: boolean;
     };
 }): CodingToolRuntime;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.91.7-canary.2",
+  "version": "0.91.7-canary.4",
   "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.91.7-canary.2",
+    "@nathapp/nax-ai": "0.91.7-canary.4",
     "zod": "^4.3.6"
   },
   "publishConfig": {