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

package/dist/tools/run-command.js

@@ -17,11 +17,14 @@
 import { statSync } from "node:fs";
 import { describeValuesType } from "#src/internal/describe-value-type";
 import { shellQuoteArg } from "#src/internal/shell-quote";
-import { sandboxSentence, unsandboxedSentence } from "../sandbox/index.js";
-import { describeExecAllowlist } from "./exec-allowlist-text.js";
 import { pathListElements } from "./path-list.js";
 import { runExecBranch } from "./run-command-exec.js";
+import { runCommandDescription, runCommandInputSchema } from "./run-command-surface.js";
 import { cutToByteCap, READ_CEILING } from "./truncate.js";
+// Re-exported so the seam keeps its `#src/tools/run-command` specifier (tests)
+// and its `./internal` API-snapshot name after US-008 moved it next to the
+// description it feeds. Same object instance either way: one import graph.
+export { _runCommandToolDeps } from "./run-command-surface.js";
 const PLACEHOLDER = /\{\{([a-zA-Z]+)\}\}/g;
 function quoteAt(template, end) {
     let quote;
@@ -194,29 +197,6 @@ 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, _runCommandToolDeps.platform())}`;
-    if (state?.kind === "unavailable")
-        return ` ${unsandboxedSentence(state.reason)}`;
-    return "";
-}
 const MISSING_RUNNER_OUTPUT = "no declared-command runner is configured for this session";
 /** The runner a tool built without one uses: refuses, spawns nothing. */
 async function refuseWithoutRunner() {
@@ -226,6 +206,36 @@ async function refuseWithoutRunner() {
 function declaredCommandRunner(opts) {
     return opts.runDeclaredCommand ?? refuseWithoutRunner;
 }
+/**
+ * The refusal for a field that applies only to an `argv` call, or undefined when
+ * the call carries none.
+ *
+ * Every refusal lives in ONE function because `run` sits at its
+ * cognitive-complexity baseline (`scripts/baselines/complexity-baseline.json`:
+ * the gate only ever lowers, and another `if` in `run` fails
+ * `bun run check:complexity`), which is why the message strings moved out too.
+ *
+ * #2066 is the reason `target` is refused rather than ignored: 48 of 136
+ * declared-command calls in one audited run carried a `target` that was silently
+ * discarded, and the transcript shows the model reasoning about it while trying
+ * to fix a failure. `unsandboxed` gets the same treatment for the same reason,
+ * plus a harder one: silently dropping an escape request would run the command
+ * SANDBOXED while the caller believes it escaped, which is a wrong answer rather
+ * than a missing one. `unsandboxedReason` is refused for the #2066 reason alone:
+ * on its own no escape was requested, so nothing unsafe happens -- but a silent
+ * drop teaches the model nothing, and it re-sends the same call.
+ */
+function argvOnlyFieldRefusal(input) {
+    if (input.unsandboxed === true)
+        return '"unsandboxed" applies only to "argv" calls';
+    if (input.unsandboxedReason !== undefined) {
+        return '"unsandboxedReason" applies only to "argv" calls, alongside "unsandboxed": true. Remove "unsandboxedReason".';
+    }
+    if (input.target === undefined)
+        return undefined;
+    const key = typeof input.command === "string" ? input.command : "";
+    return `"target" applies only to "argv" calls; a declared command runs in the directory its configuration declares. Remove "target" and call "${key}" on its own.`;
+}
 export function createRunCommandTool(declared, opts = {}) {
     const keys = [...declared.keys()];
     const exec = opts.exec;
@@ -236,37 +246,8 @@ export function createRunCommandTool(declared, opts = {}) {
         name: "RunCommand",
         // A non-zero exit here is the agent's red/green loop, not a fault.
         routineErrors: true,
-        description: exec !== undefined
-            ? `Two ways to run something. (1) Run one of this project's declared commands: ${commandDescriptions} — supply "command" and, optionally, "values" for its placeholders. (2) Run an allowlisted external command via "argv" (an array, e.g. ["bun","add","left-pad"]) — no shell, so no quoting and no shell metacharacters; ${describeExecAllowlist(exec.patterns)}. Supply exactly one of "command" or "argv".${execSandboxNote(exec.launcher)}`
-            : `Run one of this project's declared commands: ${commandDescriptions}. Supply values for its placeholders; you cannot write a command of your own.`,
-        inputSchema: {
-            type: "object",
-            properties: {
-                command: { type: "string", enum: keys, description: "Which declared command to run" },
-                values: {
-                    type: "object",
-                    description: 'Values for the command\'s placeholders, e.g. { files: "a.test.ts" }. A path placeholder takes several paths separated by spaces, e.g. { files: "a.test.ts b.test.ts" }, or as an array of paths, e.g. { files: ["test/a.test.ts", "test/b.test.ts"] } -- one call, not one per file.',
-                },
-                ...(hasExec
-                    ? {
-                        argv: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: 'Argv for an allowlisted external command, e.g. ["bun","add","left-pad"]. No shell: each element is one literal argument. Supply exactly one of "command" or "argv".',
-                        },
-                        target: {
-                            type: "string",
-                            enum: ["repoRoot", "package"],
-                            description: 'Working directory for "argv": this package (default) or the repo root.',
-                        },
-                    }
-                    : {}),
-            },
-            // With exec available, neither field is unconditionally required —
-            // run() enforces "exactly one of command or argv" at call time, which
-            // a static JSON Schema `required` list cannot express as an either/or.
-            ...(hasExec ? {} : { required: ["command"] }),
-        },
+        description: runCommandDescription(commandDescriptions, exec),
+        inputSchema: runCommandInputSchema(keys, exec),
         // `{{files}}` is the declared scoped-test path parameter. Keeping it in
         // the policy's containment seam prevents a quoted-but-otherwise harmless
         // absolute filename from making the configured command act outside root.
@@ -274,12 +255,19 @@ export function createRunCommandTool(declared, opts = {}) {
         // policy recognize an argv call and check it under the `Exec` identity
         // (see src/tools/runtime.ts and src/tools/policy.ts) rather than under
         // RunCommand's own grant.
+        //
+        // US-008: `unsandboxedField` is likewise set whenever exec is available,
+        // unconditionally -- the runtime reads the field to route an escaping argv
+        // call (Bash's rule, US-003), while whether the argument is OFFERED is
+        // `exec.unsandboxedCommands`' business. A declared-command call carries no
+        // Exec identity, so the runtime leaves that flag to `run` below, which
+        // refuses it by name.
         scope: {
             pathFields: [],
             listPathFields: ["values.files"],
             verbField: "command",
             allowedVerbs: keys,
-            ...(hasExec ? { argvField: "argv" } : {}),
+            ...(hasExec ? { argvField: "argv", unsandboxedField: "unsandboxed" } : {}),
         },
         async run(input, ctx) {
             const hasCommand = typeof input.command === "string" && input.command.length > 0;
@@ -289,17 +277,9 @@ export function createRunCommandTool(declared, opts = {}) {
             }
             if (hasArgv)
                 return runExecBranch(input, ctx, opts);
-            // #2066: `target` is read only on the argv branch (run-command-exec.ts).
-            // 48 of 136 declared-command calls in one audited run carried a `target`
-            // that was silently discarded, and the transcript shows the model
-            // reasoning about it while trying to fix a failure. Silently ignoring it
-            // is the one option that teaches nothing.
-            if (input.target !== undefined) {
-                return {
-                    content: `"target" applies only to "argv" calls; a declared command runs in the directory its configuration declares. Remove "target" and call "${typeof input.command === "string" ? input.command : ""}" on its own.`,
-                    isError: true,
-                };
-            }
+            const misplaced = argvOnlyFieldRefusal(input);
+            if (misplaced !== undefined)
+                return { content: misplaced, isError: true };
             const key = typeof input.command === "string" ? input.command : "";
             const template = declared.get(key);
             if (template === undefined)

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

@@ -16,6 +16,7 @@
  * the seam stub in the mirror suites has never covered either warn.
  */
 import { type CommandGuard, type CommandShadow, openShadowTap } from "#src/command-safety/index";
+import type { BashApprovalMode } from "#src/config/bash-approval";
 import { type AskResolver } from "#src/permissions/index";
 import type { SandboxRecord } from "../sandbox/index.ts";
 import type { CodingTool } from "./registry.ts";
@@ -63,6 +64,96 @@ export interface PolicyIdentity {
  * only which identity the policy and ledger see for THIS call.
  */
 export declare function resolvePolicyIdentity(name: string, tool: CodingTool, input: Record<string, unknown>): PolicyIdentity;
+/**
+ * What `resolveUnsandboxedCall` answers for a call that really asked to run
+ * outside the sandbox: `error` is the refusal, `unsandboxed` the permission.
+ */
+export type UnsandboxedCall = {
+    readonly kind: "error";
+    readonly content: string;
+} | {
+    readonly kind: "unsandboxed";
+    /** The clause appended to any ask this call raises: WHY it wants out. */
+    readonly suffix: string;
+    /**
+     * US-006: true when an ALLOWED verdict must still become an ask. False
+     * under `raw`, which never asks by definition (ADR-030) — the mode's
+     * whole point is that a command the policy let through runs.
+     */
+    readonly asksOnAllow: boolean;
+};
+/**
+ * US-005: the sandbox-escape gate, run once per call BEFORE the policy.
+ *
+ * Whether an escape is PERMITTED is the runtime's decision, not the tool's:
+ * the tool only knows what the call asked for, and it runs exactly as it
+ * always did once this gate lets it through. Three conditions narrow the field
+ * to the calls that really are escape requests — the tool declares an
+ * `unsandboxedField`, the policy identity is one the flag is defined for, and
+ * the value is exactly `true` (a `"true"` string is not an escape: an opted-in
+ * session's schema rejects it at the transport, and every other session reads
+ * it as the ordinary call it is).
+ *
+ * - `error` — this session was not opened with `unsandboxed.enabled`, so the
+ *   call never reaches the policy, an ask or a spawn. Deciding it here rather
+ *   than in the tool is what makes "disabled" mean disabled.
+ * - `unsandboxed` — the escape is allowed. `suffix` is the clause an ask this
+ *   call raises must carry, so the person approving it is told the command
+ *   runs outside the sandbox; `asksOnAllow` says whether an ALLOW still has to
+ *   be raised as one (US-006). The policy itself is evaluated unchanged: the
+ *   flag is not a policy input, so the verdict is the one the call would get
+ *   without it.
+ *
+ * The mode is read from the runtime's option rather than the compiled policy:
+ * `bashApproval` decides how an ENABLED request is ROUTED, which is the
+ * runtime's business, while the policy line answers only "is this command
+ * form granted". An `Exec` (argv) call is routed by the same mode — it is the
+ * other model-authored identity, and no separate Exec approval mode exists.
+ */
+export declare function resolveUnsandboxedCall(p: {
+    identity: string;
+    tool: CodingTool;
+    input: Record<string, unknown>;
+    option: {
+        readonly enabled: boolean;
+        readonly bashApproval: BashApprovalMode;
+    } | undefined;
+}): UnsandboxedCall | undefined;
+/**
+ * US-006: the ask a permitted escape request raises where the policy only
+ * allowed it.
+ *
+ * An allow says "this command form is granted", nothing about the sandbox:
+ * under `gated` that same grant runs the command WRAPPED, and under `escalate`
+ * only a grant MISS asks. So an escape request the policy merely allowed would
+ * otherwise run unwrapped with nobody told, which is the whole thing the
+ * approval exists to prevent. `raw` is exempt (`asksOnAllow`), and a verdict
+ * that already asks or denies is left to the ordinary paths.
+ *
+ * The rule is SYNTHETIC — `Unsandboxed(<identity>)` is expressible in no
+ * config — so it goes on `rule` only; `matchedRule` stays unset (see
+ * `SYNTHETIC_UNSANDBOXED_RULE`). `resolvedPaths` is carried over so an
+ * approved call admits exactly what the policy resolved.
+ */
+export declare function convertUnsandboxedAllow(p: {
+    identity: string;
+    unsandboxed: UnsandboxedCall | undefined;
+    verdict: PolicyVerdict;
+}): DeniedVerdict | undefined;
+/**
+ * The verdict this call raises an ask with, or undefined when it raises none.
+ *
+ * One place decides both the ask the policy itself produced (US-005) and the
+ * one an ALLOWED escape request is converted into (US-006), so `callTool`
+ * keeps a single ask branch and the conversion cannot drift from the ordinary
+ * route. A denial that is final — `outcome` absent or "denied" — is NOT an
+ * ask and comes back undefined, leaving `resolveDenialOutcome` to answer it.
+ */
+export declare function resolveAskVerdict(p: {
+    identity: string;
+    verdict: PolicyVerdict;
+    unsandboxed: UnsandboxedCall | undefined;
+}): DeniedVerdict | undefined;
 /**
  * P5: observe the command now (not awaited), settled from the caller's
  * logCall below. Undefined whenever the runtime has no shadow configured.
@@ -124,6 +215,15 @@ export declare function resolveAskOutcome(p: {
     root: string;
     logCall: LogCallFn;
     runTool: RunToolFn;
+    /**
+     * US-004: set when this ask is an unsandboxed run. `suffix` is
+     * `unsandboxedReasonSuffix(...)`, appended to the request's `reason` so the
+     * person sees WHY the call wants to leave the sandbox; the flag itself is
+     * what a host keys on.
+     */
+    unsandboxed?: {
+        readonly suffix: string;
+    };
 }): Promise<CodingToolOutcome>;
 /**
  * The deny branch: a final policy refusal, sharpened where possible with a

package/dist/tools/runtime-calltool.js

@@ -20,7 +20,7 @@ import { openShadowTap } from "#src/command-safety/index";
 import { errorMessage } from "#src/infra/errors";
 import { getSafeLogger } from "#src/infra/index";
 import { ASK_CANCELLED_REASON } from "#src/permissions/index";
-import { askDenyReason, askSummary } from "./ask-request.js";
+import { askDenyReason, askSummary, unsandboxedReasonSuffix } from "./ask-request.js";
 import { redirectForArgv, redirectForCommand, redirectForVerb } from "./denial-redirect.js";
 import { BASH_TOOL_NAME, EXEC_TOOL_NAME } from "./types.js";
 /**
@@ -38,6 +38,98 @@ export function resolvePolicyIdentity(name, tool, input) {
     const policyIdentity = hasArgv ? EXEC_TOOL_NAME : name;
     return { policyIdentity, argvField, hasArgv };
 }
+/** The content of the refusal a disabled escape request gets (spec US-005). */
+const UNSANDBOXED_NOT_ENABLED = "unsandboxed commands are not enabled for this session (allowUnsandboxedCommands)";
+/**
+ * US-005: the sandbox-escape gate, run once per call BEFORE the policy.
+ *
+ * Whether an escape is PERMITTED is the runtime's decision, not the tool's:
+ * the tool only knows what the call asked for, and it runs exactly as it
+ * always did once this gate lets it through. Three conditions narrow the field
+ * to the calls that really are escape requests — the tool declares an
+ * `unsandboxedField`, the policy identity is one the flag is defined for, and
+ * the value is exactly `true` (a `"true"` string is not an escape: an opted-in
+ * session's schema rejects it at the transport, and every other session reads
+ * it as the ordinary call it is).
+ *
+ * - `error` — this session was not opened with `unsandboxed.enabled`, so the
+ *   call never reaches the policy, an ask or a spawn. Deciding it here rather
+ *   than in the tool is what makes "disabled" mean disabled.
+ * - `unsandboxed` — the escape is allowed. `suffix` is the clause an ask this
+ *   call raises must carry, so the person approving it is told the command
+ *   runs outside the sandbox; `asksOnAllow` says whether an ALLOW still has to
+ *   be raised as one (US-006). The policy itself is evaluated unchanged: the
+ *   flag is not a policy input, so the verdict is the one the call would get
+ *   without it.
+ *
+ * The mode is read from the runtime's option rather than the compiled policy:
+ * `bashApproval` decides how an ENABLED request is ROUTED, which is the
+ * runtime's business, while the policy line answers only "is this command
+ * form granted". An `Exec` (argv) call is routed by the same mode — it is the
+ * other model-authored identity, and no separate Exec approval mode exists.
+ */
+export function resolveUnsandboxedCall(p) {
+    const field = p.tool.scope.unsandboxedField;
+    if (field === undefined)
+        return undefined;
+    if (p.identity !== BASH_TOOL_NAME && p.identity !== EXEC_TOOL_NAME)
+        return undefined;
+    if (p.input[field] !== true)
+        return undefined;
+    if (p.option?.enabled !== true)
+        return { kind: "error", content: UNSANDBOXED_NOT_ENABLED };
+    return {
+        kind: "unsandboxed",
+        suffix: unsandboxedReasonSuffix(p.input),
+        asksOnAllow: p.option.bashApproval !== "raw",
+    };
+}
+/** The reason a converted allow carries (spec US-006), before the suffix. */
+const UNSANDBOXED_ASK_REASON = "unsandboxed run requested";
+/**
+ * US-006: the ask a permitted escape request raises where the policy only
+ * allowed it.
+ *
+ * An allow says "this command form is granted", nothing about the sandbox:
+ * under `gated` that same grant runs the command WRAPPED, and under `escalate`
+ * only a grant MISS asks. So an escape request the policy merely allowed would
+ * otherwise run unwrapped with nobody told, which is the whole thing the
+ * approval exists to prevent. `raw` is exempt (`asksOnAllow`), and a verdict
+ * that already asks or denies is left to the ordinary paths.
+ *
+ * The rule is SYNTHETIC — `Unsandboxed(<identity>)` is expressible in no
+ * config — so it goes on `rule` only; `matchedRule` stays unset (see
+ * `SYNTHETIC_UNSANDBOXED_RULE`). `resolvedPaths` is carried over so an
+ * approved call admits exactly what the policy resolved.
+ */
+export function convertUnsandboxedAllow(p) {
+    if (p.unsandboxed?.kind !== "unsandboxed" || !p.unsandboxed.asksOnAllow)
+        return undefined;
+    if (!p.verdict.allowed)
+        return undefined;
+    return {
+        allowed: false,
+        outcome: "ask",
+        breach: false,
+        rule: `Unsandboxed(${p.identity})`,
+        reason: UNSANDBOXED_ASK_REASON,
+        resolvedPaths: p.verdict.resolvedPaths,
+    };
+}
+/**
+ * The verdict this call raises an ask with, or undefined when it raises none.
+ *
+ * One place decides both the ask the policy itself produced (US-005) and the
+ * one an ALLOWED escape request is converted into (US-006), so `callTool`
+ * keeps a single ask branch and the conversion cannot drift from the ordinary
+ * route. A denial that is final — `outcome` absent or "denied" — is NOT an
+ * ask and comes back undefined, leaving `resolveDenialOutcome` to answer it.
+ */
+export function resolveAskVerdict(p) {
+    if (p.verdict.allowed)
+        return convertUnsandboxedAllow(p);
+    return p.verdict.outcome === "ask" ? p.verdict : undefined;
+}
 /**
  * P5: observe the command now (not awaited), settled from the caller's
  * logCall below. Undefined whenever the runtime has no shadow configured.
@@ -127,6 +219,20 @@ export async function resolveGuardDenial(p) {
         return undefined;
     }
 }
+/**
+ * US-004: `Unsandboxed(<identity>)` is the SYNTHETIC rule US-006's
+ * converted-allow verdict carries — not an ask rule anyone configured. It is
+ * kept on `rule` (the request has to name what it is) but never becomes
+ * `matchedRule`, because a remembered approval derives its `origin` from that
+ * field and would then remember a rule that exists in no config.
+ */
+const SYNTHETIC_UNSANDBOXED_RULE = /^Unsandboxed\(.*\)$/;
+/** The configured ask rule behind a verdict, or undefined when there is none. */
+function matchedRuleOf(verdict) {
+    if (verdict.rule === undefined)
+        return undefined;
+    return SYNTHETIC_UNSANDBOXED_RULE.test(verdict.rule) ? undefined : verdict.rule;
+}
 /**
  * The ask branch: a call the policy gates matched an ask rule, so an
  * AskResolver decides. US-003: build the AskControl from the per-call
@@ -141,21 +247,24 @@ export async function resolveAskOutcome(p) {
         ...(context?.onWaiting !== undefined ? { onWaiting: context.onWaiting } : {}),
     };
     const ask = askSummary(p.identity, tool.scope, input);
+    const askReason = p.unsandboxed === undefined ? verdict.reason : `${verdict.reason}${p.unsandboxed.suffix}`;
+    const matchedRule = matchedRuleOf(verdict);
     let askVerdict;
     try {
         askVerdict = await p.askResolver.resolve({
             tool: p.identity,
             stage: p.stage ?? "unknown",
             rule: verdict.rule ?? verdict.reason,
-            ...(verdict.rule !== undefined ? { matchedRule: verdict.rule } : {}),
+            ...(matchedRule !== undefined ? { matchedRule } : {}),
             summary: ask.summary,
             ...(ask.unshowable ? { unshowable: true } : {}),
             ...(typeof input[tool.scope.commandField ?? ""] === "string"
                 ? { command: input[tool.scope.commandField] }
                 : {}),
             root: p.root,
-            reason: verdict.reason,
+            reason: askReason,
             ...(p.storyId !== undefined ? { storyId: p.storyId } : {}),
+            ...(p.unsandboxed !== undefined ? { unsandboxed: true } : {}),
         }, askControl);
     }
     catch (err) {

package/dist/tools/runtime.d.ts

@@ -10,6 +10,7 @@
  */
 import type { CommandInterceptor } from "#src/command-interceptor/index";
 import type { CommandShadow } from "#src/command-safety/index";
+import type { BashApprovalMode } from "#src/config/bash-approval";
 import { getSafeLogger } from "#src/infra/index";
 import { type AskResolver } from "#src/permissions/index";
 import type { OwnedPathsPolicy } from "./owned-paths.ts";
@@ -149,4 +150,14 @@ export declare function createCodingToolRuntime(opts: {
     protectedPaths?: ProtectedPathsPolicy;
     /** S3-2 port: placed on every ToolRunContext this runtime builds. */
     ownedPaths?: OwnedPathsPolicy;
+    /**
+     * US-005: whether this session may run one call OUTSIDE the OS sandbox, and
+     * the Bash mode that routes an enabled request. ABSENT means disabled: a
+     * `Bash`/`Exec` call carrying `unsandboxed: true` is then refused before the
+     * policy evaluates it.
+     */
+    unsandboxed?: {
+        readonly enabled: boolean;
+        readonly bashApproval: BashApprovalMode;
+    };
 }): CodingToolRuntime;

package/dist/tools/runtime.js

@@ -21,7 +21,7 @@ import { enforceInstructionAccess } from "./instruction-access.js";
 import { readTool } from "./read.js";
 import { getCodingTool, registerBuiltinTool } from "./registry.js";
 import { requestCapabilityTool } from "./request-capability.js";
-import { openCallShadowTap, resolveAskOutcome, resolveDenialOutcome, resolveGuardDenial, resolvePolicyIdentity, } from "./runtime-calltool.js";
+import { openCallShadowTap, resolveAskOutcome, resolveAskVerdict, resolveDenialOutcome, resolveGuardDenial, resolvePolicyIdentity, resolveUnsandboxedCall, } from "./runtime-calltool.js";
 import { scratchpadListTool, scratchpadReadTool, scratchpadWriteTool } from "./scratchpad.js";
 import { applyModelTruncationPolicy } from "./spill.js";
 import { createNoOpToolAuditSink } from "./tool-audit.js";
@@ -199,9 +199,35 @@ export function createCodingToolRuntime(opts) {
                 return { kind: "denied", reason, breach: false };
             }
             const { policyIdentity, argvField, hasArgv } = resolvePolicyIdentity(name, tool, input);
+            // Settled by `logCall`, which is declared FIRST so the refusal that
+            // precedes the policy can ledger through the same wrapper. Undefined
+            // until the shadow opens: nothing observed, nothing to settle.
+            let tap;
+            // Every ledger outcome of this call settles the tap exactly once, with
+            // `denied:ask` and `decidedBy` intact -- which CodingToolOutcome.kind
+            // alone would lose (spec 4.2). The audit is a named parameter, not a
+            // rest-array index: `log`'s positional shape can then change without
+            // silently shifting what the tap settles with.
+            const logCall = (tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation) => {
+                log(tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation);
+                tap?.settle(outcome, audit?.approval?.decidedBy, audit?.executed === undefined
+                    ? undefined
+                    : {
+                        executed: audit.executed,
+                        ...(audit.cwd !== undefined ? { cwd: audit.cwd } : {}),
+                    });
+            };
+            // US-005: a `Bash`/`Exec` escape request is answered before the policy,
+            // the ask chain and any spawn — refused when this session never enabled
+            // it, and otherwise marked so the ask below carries the reason suffix.
+            const unsandboxed = resolveUnsandboxedCall({ identity: policyIdentity, tool, input, option: opts.unsandboxed });
+            if (unsandboxed?.kind === "error") {
+                logCall(policyIdentity, "error", unsandboxed.content.length, input, context, false, unsandboxed.content);
+                return unsandboxed;
+            }
             const verdict = opts.policy.check(policyIdentity, tool.scope, input);
             // P5: observe the command now (not awaited), settle from logCall below.
-            const tap = openCallShadowTap({
+            tap = openCallShadowTap({
                 shadow: opts.commandShadow,
                 identity: policyIdentity,
                 tool,
@@ -216,20 +242,6 @@ export function createCodingToolRuntime(opts) {
                 context,
                 verdict,
             });
-            // Every ledger outcome of this call settles the tap exactly once, with
-            // `denied:ask` and `decidedBy` intact -- which CodingToolOutcome.kind
-            // alone would lose (spec 4.2). The audit is a named parameter, not a
-            // rest-array index: `log`'s positional shape can then change without
-            // silently shifting what the tap settles with.
-            const logCall = (tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation) => {
-                log(tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation);
-                tap?.settle(outcome, audit?.approval?.decidedBy, audit?.executed === undefined
-                    ? undefined
-                    : {
-                        executed: audit.executed,
-                        ...(audit.cwd !== undefined ? { cwd: audit.cwd } : {}),
-                    });
-            };
             /**
              * Executes a permitted call and records its outcome. Shared by the
              * ordinary allow path and an ask verdict an AskResolver approved, so an
@@ -283,13 +295,17 @@ export function createCodingToolRuntime(opts) {
                     return { kind: "error", content };
                 }
             }
-            if (!verdict.allowed && verdict.outcome === "ask") {
+            // US-005/US-006: the ONE ask route. A verdict the policy raised as an
+            // ask goes there as it always did; an ALLOWED escape request is
+            // converted into one unless the mode already let it run (`raw`).
+            const askVerdict = resolveAskVerdict({ identity: policyIdentity, verdict, unsandboxed });
+            if (askVerdict !== undefined) {
                 return resolveAskOutcome({
                     identity: policyIdentity,
                     tool,
                     input,
                     context,
-                    verdict,
+                    verdict: askVerdict,
                     runtimeSignal: signal,
                     askResolver,
                     stage: opts.pipelineStage,
@@ -297,6 +313,8 @@ export function createCodingToolRuntime(opts) {
                     root: opts.policy.root,
                     logCall,
                     runTool,
+                    // US-004/US-005: the ask says the command runs outside the sandbox.
+                    ...(unsandboxed?.kind === "unsandboxed" ? { unsandboxed: { suffix: unsandboxed.suffix } } : {}),
                 });
             }
             if (!verdict.allowed) {

package/dist/tools/types.d.ts

@@ -110,6 +110,14 @@ export interface ToolScope {
      * tool declaring it must be granted explicitly, since no profile grants one.
      */
     readonly commandField?: string;
+    /**
+     * US-003: the input field by which a call asks to run OUTSIDE the OS sandbox
+     * (`Bash`'s `unsandboxed`). Declared unconditionally, so the runtime can read
+     * the field whether or not the session advertises it; whether the argument is
+     * OFFERED (schema + description) is the session's `unsandboxedCommands`
+     * option, and whether a call is PERMITTED is the runtime's decision.
+     */
+    readonly unsandboxedField?: string;
 }
 /**
  * `breach` separates "you may not write there" from "that path is not in this

package/package.json

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