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

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

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

@@ -31,5 +31,47 @@ export interface DeclaredCommandToolsArgs {
     readonly runDeclaredCommand?: DeclaredCommandRunner;
     /** P4: how Bash and Exec-branch commands run; absent = direct spawn (tests). */
     readonly launcher?: CommandLauncher;
+    /**
+     * US-003/US-008: whether this session offers the per-call `unsandboxed`
+     * argument — on Bash (`createBashTool`) and on RunCommand's argv branch
+     * (`createRunCommandTool`'s `exec` option, US-008). Advertisement only:
+     * RunCommand's DECLARED-command branch has no argv to unwrap and refuses the
+     * flag by name.
+     */
+    readonly unsandboxedCommands?: boolean;
 }
+/**
+ * US-003: `unsandboxedCommands` as a spreadable field — present only when the
+ * session opted in, so "off" and "absent" stay one shape all the way down to
+ * `createBashTool` and to RunCommand's `exec` option (US-008).
+ *
+ * A helper rather than an inline `cond ? { field } : {}` spread because
+ * `buildDeclaredCommandTools` and `buildCodingToolSupport` both sit at their
+ * cognitive-complexity baseline and a ternary inside either one would raise it.
+ */
+export declare function unsandboxedToolOptions(args: {
+    readonly unsandboxedCommands?: boolean;
+}): {
+    readonly unsandboxedCommands?: true;
+};
+/**
+ * US-005: the same option as the RUNTIME's field — whether a `Bash`/`Exec`
+ * call may run outside the sandbox at all, plus the Bash approval mode that
+ * decides how an enabled request is routed.
+ *
+ * Absent when the session did not opt in, so "off" and "absent" stay one shape
+ * all the way to `createCodingToolRuntime` (absent means disabled). A helper
+ * for the same reason as `unsandboxedToolOptions`: `buildCodingToolSupport`
+ * sits at its cognitive-complexity baseline and a ternary inside it would
+ * raise it.
+ */
+export declare function unsandboxedRuntimeOption(args: {
+    readonly unsandboxedCommands?: boolean;
+    readonly bashApproval: BashApprovalMode;
+}): {
+    readonly unsandboxed?: {
+        readonly enabled: boolean;
+        readonly bashApproval: BashApprovalMode;
+    };
+};
 export declare function buildDeclaredCommandTools(args: DeclaredCommandToolsArgs): CodingTool[];

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

@@ -1,4 +1,30 @@
 import { createBashTool, createRunCommandTool, } from "#src/tools/index";
+/**
+ * US-003: `unsandboxedCommands` as a spreadable field — present only when the
+ * session opted in, so "off" and "absent" stay one shape all the way down to
+ * `createBashTool` and to RunCommand's `exec` option (US-008).
+ *
+ * A helper rather than an inline `cond ? { field } : {}` spread because
+ * `buildDeclaredCommandTools` and `buildCodingToolSupport` both sit at their
+ * cognitive-complexity baseline and a ternary inside either one would raise it.
+ */
+export function unsandboxedToolOptions(args) {
+    return args.unsandboxedCommands === true ? { unsandboxedCommands: true } : {};
+}
+/**
+ * US-005: the same option as the RUNTIME's field — whether a `Bash`/`Exec`
+ * call may run outside the sandbox at all, plus the Bash approval mode that
+ * decides how an enabled request is routed.
+ *
+ * Absent when the session did not opt in, so "off" and "absent" stay one shape
+ * all the way to `createCodingToolRuntime` (absent means disabled). A helper
+ * for the same reason as `unsandboxedToolOptions`: `buildCodingToolSupport`
+ * sits at its cognitive-complexity baseline and a ternary inside it would
+ * raise it.
+ */
+export function unsandboxedRuntimeOption(args) {
+    return args.unsandboxedCommands === true ? { unsandboxed: { enabled: true, bashApproval: args.bashApproval } } : {};
+}
 export function buildDeclaredCommandTools(args) {
     return [
         ...(args.declaredCommands.size > 0 || args.allowExec
@@ -31,6 +57,10 @@ export function buildDeclaredCommandTools(args) {
                                 patterns: args.execGrant?.patterns ?? [],
                                 ...(args.packageName !== undefined ? { packageName: args.packageName } : {}),
                                 ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
+                                // US-008: the same option Bash takes, forwarded to the argv
+                                // branch's advertisement through the same helper — one
+                                // shape for "off" and "absent" on both tools.
+                                ...unsandboxedToolOptions(args),
                             },
                         }
                         : {}),
@@ -49,6 +79,7 @@ export function buildDeclaredCommandTools(args) {
                     bashApproval: args.bashApproval,
                     ...(args.humanApproval === true ? { humanApproval: true } : {}),
                     ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
+                    ...unsandboxedToolOptions(args),
                 }),
             ]
             : []),

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

@@ -142,6 +142,12 @@ export declare function buildCodingToolSupport(args: {
     commandShadow?: CommandShadow;
     /** P4: resolved by resolveCodingToolSupport (async); data only here. */
     launcher?: CommandLauncher;
+    /**
+     * US-003: whether this session offers Bash's per-call `unsandboxed` argument
+     * (the session profile's `allowUnsandboxedCommands`). Advertisement only —
+     * the runtime's own reading of the field is a later story.
+     */
+    unsandboxedCommands?: boolean;
     /** US-001: forwarded into ToolRunContext so Bash/Exec can SIGKILL on cancel. */
     abortSignal?: AbortSignal;
     /**

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

@@ -11,7 +11,7 @@
 import { getSafeLogger, NaxError } from "#src/infra/index";
 import { advertisedSchemaBytes, BASH_TOOL_NAME, compileToolPolicy, createCodingToolRuntime, createNoOpToolAuditSink, createToolAuditSink, EXEC_TOOL_NAME, } from "#src/tools/index";
 import { resolveBashSupport } from "./coding-tool-bash.js";
-import { buildDeclaredCommandTools } from "./coding-tool-extras.js";
+import { buildDeclaredCommandTools, unsandboxedRuntimeOption, unsandboxedToolOptions } from "./coding-tool-extras.js";
 import { isTempConfined, rawScreenOptionsFor } from "./coding-tool-sandbox.js";
 export function buildCodingToolSupport(args) {
     if (args.declared.length === 0)
@@ -119,9 +119,15 @@ export function buildCodingToolSupport(args) {
                 ...(args.stripEnvVars !== undefined ? { stripEnvVars: args.stripEnvVars } : {}),
                 ...(args.shell !== undefined ? { shell: args.shell } : {}),
                 ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
+                ...unsandboxedToolOptions(args),
             }),
         ],
         ...(args.providerIdByTool !== undefined ? { providerIdByTool: args.providerIdByTool } : {}),
+        // US-005: the escape option reaches the RUNTIME too, not just the Bash
+        // 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 }),
     });
     const tools = runtime.advertised(advertised);
     // The fixed per-hop cost of advertising provider tools: their schemas enter

package/dist/config/catalog-overrides.d.ts

@@ -91,6 +91,11 @@ export interface CatalogModelOverride {
      * `protocol: "openai-completions"` (nax-ai `assertOverrideModelRouting`).
      */
     openRouterRouting?: OpenRouterRouting;
+    /**
+     * Thinking wire format for an `openai-completions` model (nax#2696).
+     * Mirrored from nax-ai's ThinkingFormat; omit to inherit the provider's format.
+     */
+    thinkingFormat?: "openai" | "qwen" | "qwen-chat-template" | "deepseek" | "zai";
 }
 /** Provider-scoped catalog overrides — maps 1:1 onto nax-ai's `ProviderOverride[]`. */
 export interface ProviderCatalogOverride {

package/dist/index.d.ts

@@ -24,13 +24,14 @@ export { AuthCancelledError, type AuthEvent, type AuthInteraction, type AuthLink
 export type { NativeSessionAdapterOptions } from "#src/native/session-adapter";
 export type { AfterResponsePatch, AfterResponsePayload, AfterToolPatch, AfterToolPayload, BeforeCompactionPatch, BeforeCompactionPayload, BeforeRequestPatch, BeforeRequestPayload, BeforeToolOutcome, BeforeToolPayload, BeforeTurnEndPatch, BeforeTurnEndPayload, BeforeTurnPatch, BeforeTurnPayload, CompleteCallOptions, ExternalHandlerOf, LoopEvent, LoopEventMap, LoopHandlerContext, LoopHandlerEntry, LoopHandlerSet, PatchOf, PayloadOf, TransformContextPatch, TransformContextPayload, } from "#src/native/session/loop-events/types";
 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 ApprovalAuditRow, type ApprovalEntry, type ApprovalMemoryDecision, type ApprovalMemoryRequest, approvalMemoryApplies, approvalMemoryKey, 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, SANDBOXED_ENV, 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 { createSessionStorage, defaultSessionsDir, processAlive, LIST_PAGE_SIZE, LOCK_HEARTBEAT_MS, LOCK_STALE_MS, SESSION_ID_PATTERN, SESSION_META_MODES, type SessionMeta, type SessionMetaMode, type SessionListEntry, type SessionListPage, type SessionLockHolder, type SessionLockHolderState, type SessionStorage, type SessionStorageDeps, } from "#src/session-store/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";
-export type { AgentSession, AgentSessionHostPorts, AgentSessionProfile, AnswerReply, AnswerStatus, ApprovalDecidedBy, CostSource, CreateAgentSessionOptions, EmbedderTool, EmbedderToolContext, EmbedderToolResult, SessionEvent, SessionEventBase, SessionEventBody, TurnEndStatus, } from "#src/session/agent-session-types";
+export type { AgentSession, AgentSessionHostPorts, AgentSessionProfile, AnswerReply, AnswerStatus, ApprovalDecidedBy, CostSource, CommandRunResult, CreateAgentSessionOptions, EmbedderTool, EmbedderToolContext, EmbedderToolResult, SessionEvent, SessionEventBase, SessionEventBody, TurnEndStatus, } from "#src/session/agent-session-types";
 export type { AgentAwaitingHumanEvent, AgentCallEndedEvent, AgentCallStartedEvent, AgentMessageUpdateEvent, AgentProcessUpdateEvent, AgentStreamEvent, AgentStreamEventBase, AgentThinkingUpdateEvent, AgentToolCallUpdateEvent, AgentUsageUpdateEvent, } from "#src/session/agent-stream-events";
 export { type AdapterInteraction, type AdapterInteractionResponse, type InteractionHandler, NO_OP_INTERACTION_HANDLER, } from "#src/session/interaction-handler";
 export { nativeBackend } from "#src/session/native-backend";

package/dist/index.js

@@ -19,9 +19,10 @@ export { NaxError } from "#src/infra/nax-error";
 export { createTerminalAuthInteraction, PLAIN_STYLE, PromptCancelledError, } from "#src/terminal-auth/index";
 export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, importPiCredentials, listProviderModels, listStoredProviders, loginProviderIds, MAX_RETAINED_TRANSCRIPTS, NATIVE_AGENT, NativeSessionAdapter, NativeSessionUnsupportedError, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, removeStoredProvider, resolveNativeId, runLogin, servedAuth, } from "#src/native/index";
 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 { approvalMemoryApplies, approvalMemoryKey, 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, SANDBOXED_ENV, 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 { createSessionStorage, defaultSessionsDir, processAlive, LIST_PAGE_SIZE, LOCK_HEARTBEAT_MS, LOCK_STALE_MS, SESSION_ID_PATTERN, SESSION_META_MODES, } from "#src/session-store/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";

package/dist/mcp/connect.js

@@ -6,7 +6,8 @@
  * once the process is gone. A failed connect is closed the same way.
  */
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { ErrorCode, ListToolsResultSchema, McpError, ToolSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
 import { McpCallError, McpConnectError } from "#src/mcp/errors";
 import { resultText } from "#src/mcp/result-text";
 import { waitForStdioExit } from "#src/mcp/stdio-close";
@@ -53,13 +54,35 @@ function toolInfo(raw) {
     if (!isRaw(raw) || typeof raw.name !== "string" || raw.name.length === 0)
         return undefined;
     const inputSchema = isRaw(raw.inputSchema) ? { ...raw.inputSchema } : {};
-    return { name: raw.name, description: typeof raw.description === "string" ? raw.description : "", inputSchema };
+    const readOnly = isRaw(raw.annotations) && raw.annotations.readOnlyHint === true;
+    return {
+        name: raw.name,
+        description: typeof raw.description === "string" ? raw.description : "",
+        inputSchema,
+        ...(readOnly ? { readOnly: true } : {}),
+    };
+}
+/**
+ * The SDK's own tools/list schema, except that a tool's `annotations` are not
+ * type-checked: the SDK would reject the WHOLE page over one server's
+ * `readOnlyHint: "yes"`, which would cost the connection every tool. `toolInfo`
+ * reads the hint strictly (`=== true`), so a malformed one just means "not
+ * read-only" and every other field is still validated.
+ */
+const LenientListToolsSchema = ListToolsResultSchema.extend({
+    tools: z.array(ToolSchema.extend({ annotations: z.record(z.string(), z.unknown()).optional() })),
+});
+async function listPage(client, cursor, signal, timeout) {
+    const page = await client.request({ method: "tools/list", ...(cursor !== undefined ? { params: { cursor } } : {}) }, LenientListToolsSchema, { signal, timeout });
+    // What Client.listTools does after its own request: the SDK reads these caches in callTool.
+    client["cacheToolMetadata"](page.tools);
+    return page;
 }
 async function listAll(client, signal, timeout) {
     const tools = [];
     let cursor;
     do {
-        const page = await client.listTools(cursor !== undefined ? { cursor } : undefined, { signal, timeout });
+        const page = await listPage(client, cursor, signal, timeout);
         for (const raw of page.tools ?? []) {
             const info = toolInfo(raw);
             if (info !== undefined)

package/dist/mcp/types.d.ts

@@ -15,6 +15,13 @@ export interface McpToolInfo {
     readonly name: string;
     readonly description: string;
     readonly inputSchema: JSONSchema;
+    /**
+     * Present (as `true`) only when the server annotated the tool
+     * `readOnlyHint: true`. Absent in every other case, so an unannotated tool
+     * keeps its `{ name, description, inputSchema }` shape. Trusted as the server
+     * states it; the lock pins input schemas, not this hint.
+     */
+    readonly readOnly?: true;
 }
 export interface McpCallResult {
     readonly text: string;

package/dist/native/models.js

@@ -117,6 +117,7 @@ export function toProviderOverrides(overrides) {
             // Omitted when the override declares none: nax-ai then falls back to the
             // template sibling's ceiling, which is the only honest value available.
             ...(model.maxTokens !== undefined ? { maxTokens: model.maxTokens } : {}),
+            ...(model.thinkingFormat !== undefined ? { thinkingFormat: model.thinkingFormat } : {}),
             supportsTools: model.supportsTools,
             thinkingLevels: model.thinkingLevels,
             // nax#2191: forwarded verbatim. nax-ai's `assertOverrideModelRouting`

package/dist/permissions/approval-memory.d.ts

@@ -0,0 +1,18 @@
+/** Shared session approval-memory policy, ported from the ACP server (nax#2553). */
+export interface ApprovalMemoryRequest {
+    readonly tool: string;
+    readonly command?: string;
+}
+export type ApprovalMemoryDecision = "allow" | "deny";
+/**
+ * Tool key, or execute tool plus command/subcommand. Unsafe, masked, wrapper and
+ * flag-second-word requests have no key. A key alone never authorizes a command:
+ * callers must also check approvalMemoryApplies against the remembered decision.
+ */
+export declare function approvalMemoryKey(request: ApprovalMemoryRequest): string | undefined;
+/**
+ * Whether a decision found under this request's key may answer without asking.
+ * Allows cover only simple commands with plain, non-flag words after the key;
+ * denies cover their matching key regardless. Does not validate key eligibility.
+ */
+export declare function approvalMemoryApplies(request: ApprovalMemoryRequest, decision: ApprovalMemoryDecision): boolean;

package/dist/permissions/approval-memory.js

@@ -0,0 +1,88 @@
+/** Keep aligned with the ACP display's execute tools, without depending on that transport. */
+const APPROVAL_EXECUTE_TOOLS = new Set(["Bash", "RunCommand", "Git", "GitCommit"]);
+/** Chaining, pipes, substitution, subshells, redirection and line breaks. */
+const SHELL_METACHARACTERS = /[;&|`$()<>\n\r]/;
+/** First words that run another command or arbitrary code. */
+const WRAPPERS = new Set([
+    "sh",
+    "bash",
+    "zsh",
+    "dash",
+    "ksh",
+    "fish",
+    "env",
+    "xargs",
+    "sudo",
+    "doas",
+    "su",
+    "command",
+    "builtin",
+    "eval",
+    "exec",
+    "source",
+    ".",
+    "nohup",
+    "time",
+    "timeout",
+    "nice",
+    "ionice",
+    "stdbuf",
+    "watch",
+    "find",
+    "node",
+    "bun",
+    "deno",
+    "npx",
+    "bunx",
+    "pnpx",
+    "python",
+    "python3",
+    "perl",
+    "ruby",
+    "php",
+    "uv",
+    "uvx",
+]);
+/** A plain command name or path: no quotes, escapes, globs or expansions the shell would rewrite. */
+const PLAIN_WORD = /^[A-Za-z0-9._/-]+$/;
+/** The masking prefix S3 puts in place of a secret in a shown command. */
+const MASK_MARKER = "[REDACTED";
+/**
+ * Tool key, or execute tool plus command/subcommand. Unsafe, masked, wrapper and
+ * flag-second-word requests have no key. A key alone never authorizes a command:
+ * callers must also check approvalMemoryApplies against the remembered decision.
+ */
+export function approvalMemoryKey(request) {
+    if (!APPROVAL_EXECUTE_TOOLS.has(request.tool))
+        return request.tool;
+    const command = request.command ?? "";
+    if (command.includes(MASK_MARKER))
+        return undefined;
+    const [first = "", second] = command.trim().split(/\s+/);
+    if (!PLAIN_WORD.test(first))
+        return undefined;
+    const name = first.slice(first.lastIndexOf("/") + 1).toLowerCase();
+    if (name === "" || WRAPPERS.has(name))
+        return undefined;
+    if (second === undefined)
+        return `${request.tool}:${first}`;
+    // A flag can change what the command does (`rm -f`, `git -C repo`): remembering the bare command would
+    // approve every later invocation of it, so a flag second word is never remembered (nax#2553).
+    if (second.startsWith("-"))
+        return undefined;
+    return PLAIN_WORD.test(second) ? `${request.tool}:${first} ${second}` : undefined;
+}
+/**
+ * Whether a decision found under this request's key may answer without asking.
+ * Allows cover only simple commands with plain, non-flag words after the key;
+ * denies cover their matching key regardless. Does not validate key eligibility.
+ */
+export function approvalMemoryApplies(request, decision) {
+    if (decision === "deny" || !APPROVAL_EXECUTE_TOOLS.has(request.tool))
+        return true;
+    const command = request.command ?? "";
+    if (SHELL_METACHARACTERS.test(command))
+        return false;
+    const rest = command.trim().split(/\s+/).slice(2);
+    return rest.every((word) => PLAIN_WORD.test(word) && !word.startsWith("-"));
+}

package/dist/permissions/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./approval-audit.ts";
+export { type ApprovalMemoryDecision, type ApprovalMemoryRequest, approvalMemoryApplies, approvalMemoryKey, } from "./approval-memory.ts";
 export * from "./approvals-link.ts";
 export * from "./approvals-store.ts";
 export * from "./approvals-taint.ts";

package/dist/permissions/index.js

@@ -1,4 +1,5 @@
 export * from "./approval-audit.js";
+export { approvalMemoryApplies, approvalMemoryKey, } from "./approval-memory.js";
 export * from "./approvals-link.js";
 export * from "./approvals-store.js";
 export * from "./approvals-taint.js";

package/dist/permissions/types.d.ts

@@ -36,6 +36,12 @@ export interface AskRequest {
      * hide shell syntax (review #9). The human link denies without prompting.
      */
     readonly unshowable?: true;
+    /**
+     * US-004: the call wants to run OUTSIDE the OS sandbox (the sandbox is never
+     * turned off for the whole session). A host that keys on it can offer a
+     * distinct decision; one that ignores it shows the ordinary approval prompt.
+     */
+    readonly unsandboxed?: true;
     /** The permitted root -- where the shell actually starts (src/tools/bash.ts:165). */
     readonly root?: string;
     /** The verdict's original reason, NOT rewritten as `matched ask rule "..."`. */

package/dist/sandbox/launcher.js

@@ -137,6 +137,9 @@ export function createCommandLauncher(opts) {
         state,
         async run(req) {
             const tmpDir = env.tmpDir !== undefined && (await ensureTmpDir(env.tmpDir)) ? env.tmpDir : undefined;
+            if (req.unwrapped === true) {
+                return runUnwrapped(req, { backend: "none", wrapped: false, reason: "requested" }, { ...env, tmpDir });
+            }
             if (state.kind === "disabled")
                 return runUnwrapped(req, { backend: "none", wrapped: false }, { ...env, tmpDir });
             if (state.kind === "unavailable") {

package/dist/sandbox/types.d.ts

@@ -112,6 +112,8 @@ export interface LaunchRequest {
     readonly stripEnvVars: readonly string[];
     /** The CALLER's own overlay (Exec's Yarn no-scripts env). Never the backend's. */
     readonly env?: Readonly<Record<string, string>>;
+    /** Explicitly run this command outside the sandbox without changing launcher state. */
+    readonly unwrapped?: true;
     /** Aborts the run: forwarded to runArgv, which SIGKILLs the process group. US-001. */
     readonly signal?: AbortSignal;
 }

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

@@ -0,0 +1,19 @@
+import type { ClaimedTurn, LiveTurn, TurnRunContext } from "./agent-session-turn.ts";
+import type { CommandRunResult, SessionEvent } from "./agent-session-types.ts";
+import type { OpenedBackend } from "./session-backend.ts";
+interface CommandHooks {
+    onStart(live: LiveTurn): void;
+    onSettle(): void;
+}
+export interface ClaimedCommand extends Pick<ClaimedTurn, "turnId" | "settled" | "cancel"> {
+    readonly result: Promise<CommandRunResult>;
+}
+/** Claim synchronously, but invoke callbacks only after the facade installs the claim. */
+export declare function claimCommand(options: {
+    ctx: TurnRunContext;
+    run: NonNullable<OpenedBackend["runCommand"]>;
+    command: string;
+    onEvent(event: SessionEvent): void;
+    hooks: CommandHooks;
+}): ClaimedCommand;
+export {};

package/dist/session/agent-session-command.js

@@ -0,0 +1,38 @@
+import { NaxError } from "#src/infra/nax-error";
+import { displayToolInput, toolResultPreview } from "#src/native/session/turn-event-emitter";
+import { _agentSessionDeps } from "./agent-session-deps.js";
+/** Claim synchronously, but invoke callbacks only after the facade installs the claim. */
+export function claimCommand(options) {
+    const { ctx, run, command, onEvent, hooks } = options;
+    const turnId = _agentSessionDeps.randomUUID();
+    const callId = _agentSessionDeps.randomUUID();
+    const controller = new AbortController();
+    const emit = (body) => onEvent({
+        sessionId: ctx.sessionId,
+        turnId,
+        at: new Date(_agentSessionDeps.now()).toISOString(),
+        metadata: ctx.metadata,
+        ...body,
+    });
+    const abort = (code, reason) => controller.abort(new NaxError(reason, code, { stage: "agent-session" }));
+    const result = Promise.resolve().then(async () => {
+        const timer = _agentSessionDeps.setTimeout(() => abort("AGENT_SESSION_TURN_TIMEOUT", "turn deadline"), ctx.turnTimeoutSeconds * 1000);
+        try {
+            hooks.onStart({ turnId, signal: controller.signal, emit });
+            emit({ type: "tool_call", name: "Bash", input: displayToolInput({ command }), callId });
+            const outcome = await run({ command, callId, signal: controller.signal });
+            emit({ type: "tool_result", callId, isError: outcome.isError, preview: toolResultPreview(outcome.content) });
+            return outcome;
+        }
+        finally {
+            _agentSessionDeps.clearTimeout(timer);
+            hooks.onSettle();
+        }
+    });
+    return {
+        turnId,
+        result,
+        settled: result.then(() => { }, () => { }),
+        cancel: (reason) => abort("AGENT_SESSION_CANCELLED", reason),
+    };
+}

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

@@ -117,6 +117,8 @@ export type SessionEventBody = {
     readonly command?: string;
     readonly reason: string;
     readonly expiresAt: string;
+    /** US-004: the call wants to run outside the OS sandbox. Absent on every ordinary ask. */
+    readonly unsandboxed?: true;
     /** `false`: decided already (by the profile); informational. Absent: a person's answer is awaited. */
     readonly answerable?: false;
 } | {
@@ -167,7 +169,14 @@ export type AnswerReply = {
     readonly text: string;
 };
 export type AnswerStatus = "accepted" | "expired" | "cancelled" | "unknown";
+export interface CommandRunResult {
+    /** The Bash tool's result text as the model would see it (capped by the tool runtime). */
+    readonly content: string;
+    readonly isError: boolean;
+}
 export interface AgentSession {
+    /** Run through the session's Bash tool without a model turn. The facade always provides this method. */
+    runCommand?(command: string, onEvent: (event: SessionEvent) => void): Promise<CommandRunResult>;
     readonly id: string;
     /** The backend that opened this session (`kind` and its capability summary). */
     readonly backend: BackendInfo;

package/dist/session/agent-session.js

@@ -1,3 +1,4 @@
+import { claimCommand } from "./agent-session-command.js";
 import { _agentSessionDeps } from "./agent-session-deps.js";
 import { AgentSessionError } from "./agent-session-errors.js";
 import { resolveAgentSessionOptions } from "./agent-session-options.js";
@@ -7,6 +8,17 @@ import { createPendingAskTable } from "./pending-asks.js";
 import { createSessionAskPort } from "./session-ask-port.js";
 /** The handler's turn signal between turns: never aborts. */
 const IDLE_SIGNAL = new AbortController().signal;
+/**
+ * The sandbox state as the embedder sees it: a frozen COPY, down to the
+ * `network` list an `available` state carries. Copying keeps the backend's own
+ * record out of the embedder's reach; freezing keeps the embedder from editing
+ * the record of what its commands ran under (US-001).
+ */
+function frozenSandbox(state) {
+    if (state.kind !== "available" || typeof state.network === "string")
+        return Object.freeze({ ...state });
+    return Object.freeze({ ...state, network: Object.freeze([...state.network]) });
+}
 class FacadeAgentSession {
     parts;
     active;
@@ -21,7 +33,13 @@ class FacadeAgentSession {
     }
     get backend() {
         const info = this.parts.opened.info;
-        return Object.freeze({ kind: info.kind, capabilities: Object.freeze({ ...info.capabilities }) });
+        // US-001: the sandbox state rides through the facade frozen, so an embedder
+        // cannot edit the record of what its commands ran under.
+        return Object.freeze({
+            kind: info.kind,
+            capabilities: Object.freeze({ ...info.capabilities }),
+            ...(info.sandbox !== undefined ? { sandbox: frozenSandbox(info.sandbox) } : {}),
+        });
     }
     get lastTurn() {
         return this.last;
@@ -49,6 +67,36 @@ class FacadeAgentSession {
         this.active = turn;
         return turn.iterable;
     }
+    async runCommand(command, onEvent) {
+        const code = this.closing !== undefined
+            ? "AGENT_SESSION_CLOSED"
+            : this.active !== undefined
+                ? "AGENT_SESSION_BUSY"
+                : this.parts.opened.runCommand === undefined
+                    ? "AGENT_SESSION_CAPABILITY_UNSUPPORTED"
+                    : undefined;
+        const run = this.parts.opened.runCommand;
+        if (code !== undefined || run === undefined) {
+            throw new AgentSessionError(`Session "${this.id}" cannot run a command`, code ?? "AGENT_SESSION_CAPABILITY_UNSUPPORTED", { sessionId: this.id });
+        }
+        const claim = claimCommand({
+            ctx: this.parts.ctx,
+            command,
+            onEvent,
+            run: (request) => run.call(this.parts.opened, request),
+            hooks: {
+                onStart: (live) => {
+                    this.parts.slot.turn = live;
+                },
+                onSettle: () => {
+                    this.parts.slot.turn = undefined;
+                    this.active = undefined;
+                },
+            },
+        });
+        this.active = claim;
+        return claim.result;
+    }
     answer(requestId, reply) {
         return this.parts.table.answer(requestId, reply);
     }

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

@@ -2,17 +2,30 @@ import type { BashApprovalMode } from "#src/config/bash-approval";
 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";
+import type { ToolProvider } from "#src/tools/provider-types";
 import type { AgentSessionHostPorts, AgentSessionProfile } from "./agent-session-types.ts";
 export interface NativeBackendOptions {
     readonly model: string;
+    /** Static or discovered tool providers attached to this session's profile and stage. */
+    readonly toolProviders?: readonly ToolProvider[];
     /** Repository instruction basename; defaults to AGENTS.md. */
     readonly instructionFileName?: string;
     readonly credentials?: CredentialSource;
     readonly catalogOverrides?: NativeCatalogOverrides;
     readonly loopHandlers?: LoopHandlerSet;
+    /** Copied into every turn's loop-handler context as `role` (for example "tui"). */
+    readonly loopHandlerRole?: string;
     readonly hostPorts?: AgentSessionHostPorts;
     readonly bashApproval?: BashApprovalMode;
     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[];
+    /**
+     * US-001: offer the Bash/Exec tools' `unsandboxed` argument, so a model can ask
+     * for one command to run outside the OS sandbox. Refused by the tool-less
+     * profiles, which have no shell to unwrap.
+     */
+    readonly allowUnsandboxedCommands?: boolean;
     /** Keep a resumed or continued conversation when the model differs (ACP server model switch, S5-3). */
     readonly carryHistoryAcrossModels?: boolean;
     /**
@@ -34,7 +47,10 @@ export interface ResolvedNativeOptions {
     readonly provider: string;
 }
 export declare function parseNativeBackendOptions(input: unknown): ResolvedNativeOptions;
-export declare function nativeProfileRules(profile: AgentSessionProfile, raw: NativeBackendOptions): {
+/** The profile's resolved knobs: the validator's answer, consumed as data. */
+export interface ResolvedProfileRules {
     readonly bashApproval: BashApprovalMode;
     readonly allowUnsandboxed: boolean;
-};
+    readonly allowUnsandboxedCommands: boolean;
+}
+export declare function nativeProfileRules(profile: AgentSessionProfile, raw: NativeBackendOptions): ResolvedProfileRules;