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

package/dist/tools/ask-request.d.ts

@@ -25,6 +25,24 @@ export interface AskSummary {
  * what approval needs; the payload is what the audit sink already holds.
  */
 export declare function askSummary(tool: string, scope: ToolScope, input: Record<string, unknown>): AskSummary;
+/**
+ * The reason clause an unsandboxed approval carries (US-004).
+ *
+ * The reason is model-authored and travels to a human, so it is masked through
+ * `maskForPrompt` and cut to `MAX_ASK_SUMMARY_CHARS` — in that order, for the
+ * same reason `askSummary` masks before it cuts: cutting first can split a
+ * secret so that no pattern matches what is left. A reason whose masked form
+ * would hide shell syntax is WITHHELD rather than denying the ask (the command
+ * itself is already vetted by `askSummary`); the person still learns the call
+ * wants to run outside the sandbox, which is the fact the suffix exists for.
+ *
+ * A blank or whitespace-only reason takes the SAME fallback as an absent one:
+ * the model wrote nothing that could explain anything, and the approver must
+ * never be shown the dangling clause the prefix alone renders.
+ */
+export declare function unsandboxedReasonSuffix(input: {
+    readonly unsandboxedReason?: unknown;
+}): string;
 /**
  * The reason a `denied:ask` ledger row carries, chosen by WHO refused.
  *

package/dist/tools/ask-request.js

@@ -37,6 +37,36 @@ export function askSummary(tool, scope, input) {
         return { summary: `${tool} [arguments withheld: contains a secret]`, unshowable: true };
     return { summary: masked.masked.slice(0, MAX_ASK_SUMMARY_CHARS), unshowable: false };
 }
+/** The clause `unsandboxedReasonSuffix` renders, before the reason itself. */
+const UNSANDBOXED_PREFIX = " -- runs OUTSIDE the sandbox: ";
+/** What the suffix says when the model gave no usable reason. */
+const NO_REASON = "no reason given";
+/** What the suffix says instead of a reason that cannot be shown safely. */
+const REASON_WITHHELD = "reason withheld";
+/**
+ * The reason clause an unsandboxed approval carries (US-004).
+ *
+ * The reason is model-authored and travels to a human, so it is masked through
+ * `maskForPrompt` and cut to `MAX_ASK_SUMMARY_CHARS` — in that order, for the
+ * same reason `askSummary` masks before it cuts: cutting first can split a
+ * secret so that no pattern matches what is left. A reason whose masked form
+ * would hide shell syntax is WITHHELD rather than denying the ask (the command
+ * itself is already vetted by `askSummary`); the person still learns the call
+ * wants to run outside the sandbox, which is the fact the suffix exists for.
+ *
+ * A blank or whitespace-only reason takes the SAME fallback as an absent one:
+ * the model wrote nothing that could explain anything, and the approver must
+ * never be shown the dangling clause the prefix alone renders.
+ */
+export function unsandboxedReasonSuffix(input) {
+    const raw = input.unsandboxedReason;
+    if (typeof raw !== "string" || raw.trim() === "")
+        return `${UNSANDBOXED_PREFIX}${NO_REASON}`;
+    const masked = maskForPrompt(raw);
+    if (!masked.ok)
+        return `${UNSANDBOXED_PREFIX}${REASON_WITHHELD}`;
+    return `${UNSANDBOXED_PREFIX}${masked.masked.slice(0, MAX_ASK_SUMMARY_CHARS)}`;
+}
 /**
  * The reason a `denied:ask` ledger row carries, chosen by WHO refused.
  *

package/dist/tools/bash.d.ts

@@ -61,6 +61,15 @@ export interface BashToolOptions {
      * description, so the agent always knows whether it is sandboxed.
      */
     readonly launcher?: CommandLauncher;
+    /**
+     * US-003: whether this session offers the per-call `unsandboxed` argument
+     * (`NativeBackendOptions.allowUnsandboxedCommands`, threaded down through
+     * `buildSessionToolSupport`). It shapes the ADVERTISEMENT only -- the schema
+     * and one description sentence. `run` never reads it: the tool only honours
+     * the flag on the call, so a session that did not advertise the argument
+     * cannot be steered into running unwrapped by a stray input field.
+     */
+    readonly unsandboxedCommands?: boolean;
 }
 /**
  * Injectable spawn seam, mirroring `_argvExecDeps`, plus the platform seam

package/dist/tools/bash.js

@@ -179,7 +179,7 @@ function bashToolDescription(shell, opts) {
  * therefore never the string the policy judged, which is exactly why
  * `interceptShell` re-validates the provider's answer rather than trusting it.
  */
-async function launchIntercepted({ command, shell, opts, ctx, timeoutMs, }) {
+async function launchIntercepted({ command, shell, opts, ctx, timeoutMs, unwrapped, }) {
     // The run's interceptor arrives on the context (S1 spec port 7), immutable
     // for this call, so the launch below and `postProcess` see the same object.
     const interceptor = ctx.interceptor;
@@ -205,6 +205,9 @@ async function launchIntercepted({ command, shell, opts, ctx, timeoutMs, }) {
             spec: { kind: "shell", shell, command: intercepted.command },
             root: ctx.root,
             ...common,
+            // US-003: the key is present only for an exact `true` on the call, so
+            // every other request stays byte-identical to what US-002 shipped.
+            ...(unwrapped ? { unwrapped: true } : {}),
         })
         : { ...(await _bashToolDeps.runArgv({ argv: executed, ...common })), executed, sandbox: undefined };
     if (!intercepted.rewritten)
@@ -223,6 +226,51 @@ async function launchIntercepted({ command, shell, opts, ctx, timeoutMs, }) {
         return { launched, stdout: launched.stdout };
     }
 }
+/**
+ * US-003: the one sentence an opted-in session appends to its description, so
+ * the model knows the argument exists and what it is for. Absent from every
+ * description when the option is off, which keeps those byte-identical.
+ */
+const UNSANDBOXED_ARGUMENT_SENTENCE = 'Set "unsandboxed": true with an "unsandboxedReason" only when the command needs the network, a local socket or a device the sandbox blocks.';
+/**
+ * US-003: the description with the opt-in sentence appended.
+ *
+ * A separate function rather than a final ternary inside `bashToolDescription`
+ * so every existing variant keeps its own wording verbatim, and the separator
+ * is chosen here: most variants already end on a space, the sandbox-sentence
+ * ones do not, and a description must never end on two spaces or none.
+ */
+function withUnsandboxedSentence(description, opts) {
+    if (opts.unsandboxedCommands !== true)
+        return description;
+    const separator = description.endsWith(" ") ? "" : " ";
+    return `${description}${separator}${UNSANDBOXED_ARGUMENT_SENTENCE}`;
+}
+/**
+ * US-003: the input schema, plus the two argument fields when the session opted
+ * in. Built here rather than inline in `createBashTool` so the schema's shape
+ * has one owner, and the off-form is exactly the three properties it always was.
+ *
+ * Neither added field is `required`: the escape is per call, and a call without
+ * it runs exactly as it does today.
+ */
+function bashToolInputSchema(opts) {
+    return {
+        type: "object",
+        properties: {
+            command: { type: "string", description: 'The shell command to run, e.g. "bun test src/a.test.ts"' },
+            timeoutMs: {
+                type: "number",
+                description: `Deadline in milliseconds (default and maximum ${BASH_TIMEOUT_MS}).`,
+            },
+            description: { type: "string", description: "One short line on what this command is for." },
+            ...(opts.unsandboxedCommands === true
+                ? { unsandboxed: { type: "boolean" }, unsandboxedReason: { type: "string" } }
+                : {}),
+        },
+        required: ["command"],
+    };
+}
 export function createBashTool(opts = {}) {
     const shell = opts.shell ?? DEFAULT_BASH_SHELL;
     return {
@@ -231,23 +279,16 @@ export function createBashTool(opts = {}) {
         // not a fault worth an operator's attention — the same reason RunCommand
         // sets this.
         routineErrors: true,
-        description: bashToolDescription(shell, opts),
-        inputSchema: {
-            type: "object",
-            properties: {
-                command: { type: "string", description: 'The shell command to run, e.g. "bun test src/a.test.ts"' },
-                timeoutMs: {
-                    type: "number",
-                    description: `Deadline in milliseconds (default and maximum ${BASH_TIMEOUT_MS}).`,
-                },
-                description: { type: "string", description: "One short line on what this command is for." },
-            },
-            required: ["command"],
-        },
+        description: withUnsandboxedSentence(bashToolDescription(shell, opts), opts),
+        inputSchema: bashToolInputSchema(opts),
         // `commandField` is what routes this call to the Bash branch of the policy
         // (src/tools/policy-bash.ts). No pathFields: the paths are inside the
         // command string, where only that branch can see them.
-        scope: { pathFields: [], commandField: "command" },
+        //
+        // US-003: `unsandboxedField` is declared unconditionally, so the runtime can
+        // see the field whether or not this session advertises it -- the option
+        // shapes the schema, never the scope.
+        scope: { pathFields: [], commandField: "command", unsandboxedField: "unsandboxed" },
         async run(input, ctx) {
             const command = input.command;
             if (typeof command !== "string" || command.trim() === "") {
@@ -256,7 +297,11 @@ export function createBashTool(opts = {}) {
             const requested = typeof input.timeoutMs === "number" && Number.isFinite(input.timeoutMs) ? input.timeoutMs : BASH_TIMEOUT_MS;
             const timeoutMs = Math.min(Math.max(Math.trunc(requested), MIN_BASH_TIMEOUT_MS), BASH_TIMEOUT_MS);
             try {
-                const { launched, stdout } = await launchIntercepted({ command, shell, opts, ctx, timeoutMs });
+                // US-003: exact `true` only. The tool never consults `opts.unsandboxedCommands`
+                // here: whether the argument is ADVERTISED is the option's business, and what a
+                // given call asked for is the call's.
+                const unwrapped = input.unsandboxed === true;
+                const { launched, stdout } = await launchIntercepted({ command, shell, opts, ctx, timeoutMs, unwrapped });
                 // Same framing ladder as RunCommand (Exec) via the shared
                 // `formatExecBody`: an aborted call opens with the cancellation line
                 // and surfaces whatever partial output the readers captured before the

package/dist/tools/git.js

@@ -171,8 +171,15 @@ function buildGitRootArgv(input) {
     }
     return ["rev-parse", "--show-toplevel"];
 }
+/**
+ * `blame` rejects exclude pathspecs (exit 128). On `log` and `show` an exclude
+ * filters COMMITS, not just files: a commit that only touches `.nax/` is
+ * dropped, so `log HEAD -1` reported an older commit as HEAD and `show HEAD`
+ * printed nothing (#2693). Only `diff` and `status` list files.
+ */
+const GIT_EXCLUDE_EXEMPT_VERBS = ["blame", "log", "show"];
 function defaultGitExcludes(subcommand, excludes) {
-    return subcommand === "blame" ? [] : excludes;
+    return GIT_EXCLUDE_EXEMPT_VERBS.includes(subcommand) ? [] : excludes;
 }
 /**
  * `defaultExcludes`: pathspecs appended to an unscoped call (the host's own
@@ -292,8 +299,8 @@ export function buildGitArgv(input, defaultExcludes = []) {
         // on this DEFAULT branch: a caller that names a path under .nax/ gets it --
         // the tool is read-only, and silently returning nothing for an explicitly
         // requested path would be a worse failure than the one being fixed.
-        // `blame` is exempt because git rejects exclude pathspecs on it and exits
-        // 128; do not "unify" it back in.
+        // `blame`, `log` and `show` are exempt (GIT_EXCLUDE_EXEMPT_VERBS); do not
+        // "unify" them back in.
         argv.push(...defaultGitExcludes(subcommand, defaultExcludes));
         return argv;
     }

package/dist/tools/policy-match.d.ts

@@ -20,7 +20,7 @@ import type { ToolGrant } from "./types.ts";
  * -- but it made a *scoped* grant wider than its author wrote, which is the one
  * thing a scoped profile exists to prevent.
  */
-export declare function globToRegExp(pattern: string): RegExp;
+export declare function globToRegExp(pattern: string, ignoreCase?: boolean): RegExp;
 /** A compiled glob, keeping its source so verb names can be told from paths. */
 export interface CompiledPattern {
     readonly source: string;
@@ -55,7 +55,7 @@ export declare function matchedGlobSource(patterns: readonly CompiledPattern[],
  * is exactly bun, argv[1] starts with add", never "the space-joined argv
  * matches this glob".
  */
-export declare function compileArgvPattern(pattern: string): readonly CompiledPattern[];
+export declare function compileArgvPattern(pattern: string, ignoreCase?: boolean): readonly CompiledPattern[];
 /** A grant pattern's tokens are a PREFIX of argv — trailing argv tokens
  * (the package name, flags, ...) are the payload a prefix grant like
  * `bun add*` does not itself constrain. */

package/dist/tools/policy-match.js

@@ -19,7 +19,7 @@
  * -- but it made a *scoped* grant wider than its author wrote, which is the one
  * thing a scoped profile exists to prevent.
  */
-export function globToRegExp(pattern) {
+export function globToRegExp(pattern, ignoreCase = false) {
     let out = "";
     for (let i = 0; i < pattern.length; i += 1) {
         const char = pattern[i];
@@ -46,7 +46,7 @@ export function globToRegExp(pattern) {
         }
         out += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
     }
-    return new RegExp(`^${out}$`);
+    return new RegExp(`^${out}$`, ignoreCase ? "i" : "");
 }
 export function matchesAny(patterns, value) {
     return patterns.some((p) => p.re.test(value));
@@ -64,11 +64,11 @@ export function matchedGlobSource(patterns, value) {
  * is exactly bun, argv[1] starts with add", never "the space-joined argv
  * matches this glob".
  */
-export function compileArgvPattern(pattern) {
+export function compileArgvPattern(pattern, ignoreCase = false) {
     return pattern
         .split(/\s+/)
         .filter((token) => token.length > 0)
-        .map((token) => ({ source: token, re: globToRegExp(token) }));
+        .map((token) => ({ source: token, re: globToRegExp(token, ignoreCase) }));
 }
 /** A grant pattern's tokens are a PREFIX of argv — trailing argv tokens
  * (the package name, flags, ...) are the payload a prefix grant like
@@ -96,8 +96,11 @@ export function compileRuleMap(rules) {
         const nonWildcard = patterns.filter((p) => p !== "*");
         map.set(rule.tool, {
             unconditional: patterns.includes("*"),
-            matchers: nonWildcard.map((source) => ({ source, re: globToRegExp(source) })),
-            argvPatterns: nonWildcard.map((source) => compileArgvPattern(source)),
+            // Case-insensitive, unlike grants: on a case-insensitive filesystem `.ENV` and `.env` are one
+            // file, and a deny/ask rule must not be walked past by respelling it (nax#1972, as denyPaths).
+            // Over-matching only asks or refuses more, the direction these lists should fail in.
+            matchers: nonWildcard.map((source) => ({ source, re: globToRegExp(source, true) })),
+            argvPatterns: nonWildcard.map((source) => compileArgvPattern(source, true)),
             raw: patterns,
             rulePatterns: [...(existing?.rulePatterns ?? []), rule.patterns],
         });

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

@@ -46,7 +46,10 @@ function entersGitMetadata(root, resolved) {
     const rel = relative(realOrRaw(root), resolved);
     if (rel === "" || rel.startsWith(".."))
         return false;
-    return rel.split(sep).includes(".git");
+    // Case-folded: on a case-insensitive filesystem (macOS, Windows defaults) `.GIT/config` IS
+    // `.git/config`, and the canonical path keeps the caller's spelling. Over-refusing a genuinely
+    // distinct `.GIT` on a case-sensitive filesystem is the direction this ban should fail in.
+    return rel.split(sep).some((segment) => segment.toLowerCase() === ".git");
 }
 /**
  * Absolute, symlink-resolved form of `candidate` if it lies inside `root`,

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

@@ -53,6 +53,13 @@ export interface ResolvedProviderTools {
         providerId: string;
         text: string;
     }[];
+    /**
+     * Advertised (namespaced) names of tools from a `discovered` provider whose
+     * `readOnly` is not `true`, in advertise order: the ones an ask-profile
+     * session puts to the person before running. A `static` provider's tools
+     * never appear (their schemas are authored in this repo). ABSENT when empty.
+     */
+    readonly askTools?: readonly string[];
 }
 export declare function resolveProviderTools(providers: readonly ToolProvider[], stage: string, workdir: string, options?: {
     /**

package/dist/tools/provider-advertise.js

@@ -35,6 +35,14 @@ async function instructionsFor(provider, workdir) {
         return undefined;
     }
 }
+/** `{ [key]: list }` for a non-empty list, `{}` otherwise: the key is absent, never `[]`. */
+function whenNonEmpty(key, list) {
+    return list.length > 0 ? { [key]: list } : {};
+}
+/** A discovered tool its server did not mark read-only; a static provider's tools never ask. */
+function asksBeforeRunning(provider, tool) {
+    return provider.kind === "discovered" && tool.readOnly !== true;
+}
 export async function resolveProviderTools(providers, stage, workdir, options) {
     const tools = [];
     const entries = [];
@@ -43,6 +51,7 @@ export async function resolveProviderTools(providers, stage, workdir, options) {
     const withheld = [];
     const providerIdByTool = new Map();
     const instructions = [];
+    const askTools = [];
     for (const provider of providers) {
         if (!providerAttachesTo(provider, stage)) {
             skipped.push({ providerId: provider.id, reason: "stage-mismatch", stages: provider.stages });
@@ -60,6 +69,8 @@ export async function resolveProviderTools(providers, stage, workdir, options) {
                 const adapted = adaptProviderTool(provider.id, tool);
                 tools.push(adapted);
                 providerIdByTool.set(adapted.name, provider.id);
+                if (asksBeforeRunning(provider, tool))
+                    askTools.push(adapted.name);
                 localNames.push(tool.localName);
             }
             entries.push({ providerId: provider.id, localNames });
@@ -84,7 +95,8 @@ export async function resolveProviderTools(providers, stage, workdir, options) {
         withheld,
         providerIdByTool,
         entries,
-        ...(instructions.length > 0 ? { instructions } : {}),
+        ...whenNonEmpty("instructions", instructions),
+        ...whenNonEmpty("askTools", askTools),
     };
 }
 /**

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

@@ -18,6 +18,12 @@ export interface ProviderTool {
     readonly localName: string;
     readonly description: string;
     readonly inputSchema: JSONSchema;
+    /**
+     * The provider's own claim that the tool does not modify anything. Only a
+     * `discovered` provider sets it (an MCP server's `readOnlyHint`); it is
+     * trusted as stated and decides whether an ask-profile session asks first.
+     */
+    readonly readOnly?: boolean;
     run(input: Record<string, unknown>, ctx: ToolRunContext): Promise<ToolResult>;
 }
 export interface ToolProvider {

package/dist/tools/run-command-exec.js

@@ -71,6 +71,10 @@ async function launchExec(req) {
             stripEnvVars: req.stripEnvVars,
             ...(req.mergedEnv !== undefined ? { env: req.mergedEnv } : {}),
             ...(req.signal !== undefined ? { signal: req.signal } : {}),
+            // US-008: the key is present only for an exact `true` on the call, so
+            // every other request stays byte-identical to what US-002 shipped -- and
+            // the launcher, not this branch, decides what "unwrapped" means.
+            ...(req.unwrapped ? { unwrapped: true } : {}),
         });
     }
     return {
@@ -133,6 +137,14 @@ export async function runExecBranch(input, ctx, opts) {
             mergedEnv,
             stripEnvVars: opts.stripEnvVars ?? [],
             signal: ctx.signal,
+            // US-008: exact `true` only, read off the CALL. Whether the session
+            // offers the argument, and whether the request is permitted at all, was
+            // settled before `run` was reached (the runtime's `resolveUnsandboxedCall`
+            // and its ask), so re-reading `opts.exec.unsandboxedCommands` here would
+            // be a second authorization gate in the one place that cannot see the
+            // approval. A `"true"` string is not an escape request: it is the ordinary
+            // call it reads as.
+            unwrapped: input.unsandboxed === true,
         });
         // US-001: match Bash's framing so an aborted Exec is rendered as an
         // error with the cancellation banner (AC14 mirror) and an orphansKilled

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

@@ -0,0 +1,28 @@
+import type { CodingTool } from "./registry.ts";
+import type { RunCommandExecOptions } from "./run-command.ts";
+/**
+ * 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 `run-command.ts` — which is exactly where a
+ * `_*Deps` seam belongs (nax-only, outside semver), and why adding it needed
+ * the one-line api/ snapshot update. Tests reach it through
+ * `#src/tools/run-command`.
+ */
+export declare const _runCommandToolDeps: {
+    platform: () => NodeJS.Platform;
+};
+export declare function runCommandDescription(commandDescriptions: string, exec: RunCommandExecOptions | undefined): string;
+/**
+ * The tool's input schema. Each of the three conditional groups (declared
+ * fields, argv fields, the opt-in escape argument) has one owner here, so
+ * `createRunCommandTool` carries no schema branch of its own.
+ *
+ * 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.
+ */
+export declare function runCommandInputSchema(keys: readonly string[], exec: RunCommandExecOptions | undefined): CodingTool["inputSchema"];

package/dist/tools/run-command-surface.js

@@ -0,0 +1,109 @@
+import { sandboxSentence, unsandboxedSentence } from "../sandbox/index.js";
+import { describeExecAllowlist } from "./exec-allowlist-text.js";
+/**
+ * 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 `run-command.ts` — which is exactly where a
+ * `_*Deps` seam belongs (nax-only, outside semver), and why adding it 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 "";
+}
+/**
+ * US-008: the one sentence an opted-in session appends to an Exec-capable
+ * description. Worded for the argv branch ("the argv", not "the command") so it
+ * reads as the argv branch's own argument — the declared branch refuses the
+ * flag by name, and a shared sentence would promise a capability half the tool
+ * rejects.
+ */
+const UNSANDBOXED_ARGV_SENTENCE = 'Set "unsandboxed": true with an "unsandboxedReason" only when the argv needs the network, a local socket or a device the sandbox blocks.';
+/**
+ * US-008: the description with the opt-in sentence appended, or the description
+ * unchanged. A separate function for the same reason `withUnsandboxedSentence`
+ * is one in bash.ts: the separator is chosen here, so the off-form stays
+ * byte-identical to what shipped, and no caller has to end its own sentence
+ * with a space to keep the result readable.
+ */
+function withUnsandboxedArgvSentence(description, exec) {
+    if (exec.unsandboxedCommands !== true)
+        return description;
+    const separator = description.endsWith(" ") ? "" : " ";
+    return `${description}${separator}${UNSANDBOXED_ARGV_SENTENCE}`;
+}
+function execDescription(commandDescriptions, exec) {
+    return withUnsandboxedArgvSentence(`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)}`, exec);
+}
+export function runCommandDescription(commandDescriptions, exec) {
+    if (exec === undefined) {
+        return `Run one of this project's declared commands: ${commandDescriptions}. Supply values for its placeholders; you cannot write a command of your own.`;
+    }
+    return execDescription(commandDescriptions, exec);
+}
+/** The declared branch's two fields, always present. */
+function declaredInputProperties(keys) {
+    return {
+        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.',
+        },
+    };
+}
+/** The argv branch's two fields, present only when `exec` is available. */
+function argvInputProperties() {
+    return {
+        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.',
+        },
+    };
+}
+/**
+ * US-008: the escape argument's two fields, only when the session opted in.
+ * Neither is `required`: the escape is per call, and a call without it runs
+ * exactly as it does today.
+ */
+function unsandboxedArgvProperties(exec) {
+    if (exec.unsandboxedCommands !== true)
+        return {};
+    return { unsandboxed: { type: "boolean" }, unsandboxedReason: { type: "string" } };
+}
+/**
+ * The tool's input schema. Each of the three conditional groups (declared
+ * fields, argv fields, the opt-in escape argument) has one owner here, so
+ * `createRunCommandTool` carries no schema branch of its own.
+ *
+ * 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.
+ */
+export function runCommandInputSchema(keys, exec) {
+    return {
+        type: "object",
+        properties: {
+            ...declaredInputProperties(keys),
+            ...(exec === undefined ? {} : { ...argvInputProperties(), ...unsandboxedArgvProperties(exec) }),
+        },
+        ...(exec === undefined ? { required: ["command"] } : {}),
+    };
+}

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

@@ -1,6 +1,7 @@
 import type { QualityCommandSpec } from "#src/internal/command-spec/index";
-import { type CommandLauncher } from "../sandbox/index.ts";
+import type { CommandLauncher } from "../sandbox/index.ts";
 import type { CodingTool } from "./registry.ts";
+export { _runCommandToolDeps } from "./run-command-surface.ts";
 /**
  * Context for RunCommand's allowlisted, model-authored argv branch (`Exec`).
  *
@@ -27,6 +28,21 @@ export interface RunCommandExecOptions {
     readonly patterns: readonly string[];
     /** P4: how the argv runs. Absent = direct runArgv (unit tests). */
     readonly launcher?: CommandLauncher;
+    /**
+     * US-008: whether this session offers the per-call `unsandboxed` argument on
+     * the argv branch (`NativeBackendOptions.allowUnsandboxedCommands`, threaded
+     * down through `buildDeclaredCommandTools`). It shapes the ADVERTISEMENT only
+     * -- the two schema fields and one description sentence.
+     *
+     * `runExecBranch` never reads it: an `argv` call carrying `unsandboxed: true`
+     * runs unwrapped whenever the RUNTIME let the call through, which is where
+     * "is this permitted" is decided (US-005/US-006, `resolveUnsandboxedCall` in
+     * `src/tools/runtime-calltool.ts`). Making the option a second gate here
+     * would put the same decision in two places, and a session that simply did
+     * not advertise the field could then be steered into running unwrapped by a
+     * stray input key.
+     */
+    readonly unsandboxedCommands?: boolean;
 }
 /** What RunCommand hands the runner for one declared command. */
 export interface DeclaredCommandRequest {
@@ -104,19 +120,4 @@ export declare function substituteCommand(template: string, values: Record<strin
 export declare function substituteCommandSpec(spec: QualityCommandSpec, values: Record<string, string | readonly string[]>): QualityCommandSpec | {
     error: string;
 };
-/**
- * US-006: the platform seam `execSandboxNote` reads to decide whether the
- * description carries the macOS ps note.
- *
- * Kept out of `src/tools/index.ts` on purpose: `src/index.ts` takes named
- * exports from that barrel, so a seam there would reach the package's public
- * `.` entry, where `_` names are forbidden. It DOES reach `./internal`, because
- * `src/internal.ts` star-exports this module — which is exactly where a
- * `_*Deps` seam belongs (nax-only, outside semver), and why adding it here
- * needed the one-line api/ snapshot update. Tests reach it through
- * `#src/tools/run-command`.
- */
-export declare const _runCommandToolDeps: {
-    platform: () => NodeJS.Platform;
-};
 export declare function createRunCommandTool(declared: ReadonlyMap<string, QualityCommandSpec>, opts?: RunCommandToolOptions): CodingTool;