@nathapp/nax-agent 0.1.0

package/dist/tools/run-command.js

@@ -0,0 +1,398 @@
+/**
+ * Runs a command the PROJECT declared, never one the model wrote.
+ *
+ * This reaches a shell, deliberately: nax's quality runner
+ * (`src/quality/runner.ts`, supplied as `runDeclaredCommand`) executes every
+ * configured command through one to preserve their quoting semantics, and a
+ * declared command like "CI=1 bun test {{files}}" has no argv form -- CI=1 is a
+ * shell assignment, not a binary. Building a second execution path would mean
+ * the same command behaved differently depending on who invoked it.
+ *
+ * So the property here is narrower than the Git tool's, and is stated rather
+ * than implied: the model does not author the command string. It names a
+ * declared key and supplies placeholder values, and those values are the entire
+ * injection surface. They are quoted with shellQuoteArg -- the same helper
+ * command-resolver.ts already applies to {{package}}.
+ */
+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 { cutToByteCap, READ_CEILING } from "./truncate.js";
+const PLACEHOLDER = /\{\{([a-zA-Z]+)\}\}/g;
+function quoteAt(template, end) {
+    let quote;
+    let escaped = false;
+    for (let i = 0; i < end; i += 1) {
+        const char = template[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quote !== "single") {
+            escaped = true;
+            continue;
+        }
+        if (char === "'" && quote !== "double")
+            quote = quote === "single" ? undefined : "single";
+        if (char === '"' && quote !== "single")
+            quote = quote === "double" ? undefined : "double";
+    }
+    return quote;
+}
+function placeholderContextError(template) {
+    for (const match of template.matchAll(PLACEHOLDER)) {
+        const start = match.index ?? 0;
+        const key = match[1];
+        if (quoteAt(template, start) !== undefined) {
+            return `placeholder {{${key}}} may not appear inside shell quotes`;
+        }
+        const tokenStart = Math.max(template.lastIndexOf(" ", start), template.lastIndexOf("\t", start)) + 1;
+        const tokenEndMatch = /[ \t\r\n]/.exec(template.slice(start));
+        const tokenEnd = tokenEndMatch === null ? template.length : start + tokenEndMatch.index;
+        const token = template.slice(tokenStart, tokenEnd);
+        if (/[$`()]/.test(token)) {
+            return `placeholder {{${key}}} may not appear in a shell expansion`;
+        }
+    }
+    return undefined;
+}
+// A bare "no" is what produced the defect this exists to fix (#1924): denied
+// with no legal alternative named, the model repeated the identical rejected
+// call 18 times in one session because it was never told the placeholder
+// set. Matches git.ts's "valid for: ..." phrasing convention. A command with
+// no placeholders reads naturally rather than printing "(declared: )".
+function declaredPlaceholdersSuffix(declared) {
+    if (declared.size === 0)
+        return "this command declares no placeholders";
+    return `declared: ${[...declared].join(", ")}`;
+}
+/**
+ * An ARRAY value is quoted per element and joined; a string value is quoted
+ * whole. The distinction carries the element boundaries through substitution,
+ * which a pre-joined string cannot: the join would be re-split and a path
+ * under `/tmp/my dir/` would become two arguments (nax#1998).
+ */
+export function substituteCommand(template, values) {
+    const declared = new Set([...template.matchAll(PLACEHOLDER)].map((m) => m[1]));
+    for (const key of Object.keys(values)) {
+        if (!declared.has(key)) {
+            return { error: `value "${key}" is not a placeholder in this command (${declaredPlaceholdersSuffix(declared)})` };
+        }
+    }
+    for (const key of declared) {
+        if (values[key] === undefined) {
+            return { error: `placeholder {{${key}}} has no value (${declaredPlaceholdersSuffix(declared)})` };
+        }
+    }
+    const contextError = placeholderContextError(template);
+    if (contextError !== undefined)
+        return { error: contextError };
+    return template.replaceAll(PLACEHOLDER, (_m, key) => {
+        const value = values[key];
+        return Array.isArray(value) ? value.map(shellQuoteArg).join(" ") : shellQuoteArg(value);
+    });
+}
+/**
+ * Apply placeholder substitution across a spec. A list substitutes into every
+ * entry and fails as a whole if any entry fails, so a partially-substituted
+ * list can never reach the shell.
+ *
+ * Each entry only receives the subset of `values` it actually declares
+ * placeholders for -- list entries commonly have different placeholder needs
+ * (e.g. `["tsc --noEmit", "bun test {{files}}"]`), and `substituteCommand`
+ * rejects a value that isn't a placeholder in the template it's checking, by
+ * design (it's what stops a value silently going nowhere). Passing the full
+ * shared `values` object to every entry would make every entry without
+ * {{files}} fail that check.
+ *
+ * But per-entry filtering alone would let a value that no entry in the whole
+ * spec declares vanish silently (every entry's filtered set would just be
+ * empty, and every entry would substitute cleanly) -- so before filtering
+ * per entry, every key in `values` is checked against the UNION of
+ * placeholders declared across the whole spec, and rejected with the same
+ * "unrecognized value" contract `substituteCommand` gives the single-string
+ * case if it isn't declared anywhere.
+ */
+export function substituteCommandSpec(spec, values) {
+    if (typeof spec === "string")
+        return substituteCommand(spec, values);
+    const allDeclared = new Set();
+    for (const entry of spec) {
+        for (const match of entry.matchAll(PLACEHOLDER))
+            allDeclared.add(match[1]);
+    }
+    for (const key of Object.keys(values)) {
+        if (!allDeclared.has(key)) {
+            return {
+                error: `value "${key}" is not a placeholder in this command (${declaredPlaceholdersSuffix(allDeclared)})`,
+            };
+        }
+    }
+    const out = [];
+    for (const entry of spec) {
+        const declaredKeys = new Set([...entry.matchAll(PLACEHOLDER)].map((m) => m[1]));
+        const entryValues = {};
+        for (const [key, value] of Object.entries(values)) {
+            if (declaredKeys.has(key))
+                entryValues[key] = value;
+        }
+        const substituted = substituteCommand(entry, entryValues);
+        if (typeof substituted !== "string")
+            return substituted;
+        out.push(substituted);
+    }
+    return out;
+}
+// #1924, second half: the description-only fix, which is what prevents the
+// repeated-call loop rather than merely explaining it after the first
+// failure. Renders each declared command with the placeholders its OWN
+// template actually contains, so the model can pick values before it
+// guesses -- e.g. "test (no placeholders), testScoped ({{files}})".
+function placeholdersOf(spec) {
+    const templates = typeof spec === "string" ? [spec] : spec;
+    return new Set(templates.flatMap((template) => [...template.matchAll(PLACEHOLDER)].map((m) => m[1])));
+}
+function describeDeclaredCommand(name, spec) {
+    const placeholders = [...placeholdersOf(spec)];
+    if (placeholders.length === 0)
+        return `${name} (no placeholders)`;
+    return `${name} (${placeholders.map((p) => `{{${p}}}`).join(", ")})`;
+}
+function describeDeclaredCommands(declared) {
+    return [...declared.entries()].map(([name, template]) => describeDeclaredCommand(name, template)).join(", ");
+}
+// The live-run defect this exists to fix (run-2026-09-14T08-21-43-607Z): the
+// "values" input was cast straight to Record<string, unknown> with no shape
+// check, so a model sending a STRING got its characters iterated as if they
+// were object keys. An empty string produced no rejected keys at all, so the
+// unrelated "has no value" branch fired instead; "\t" produced the key "0",
+// so the response named a placeholder that was never in the input. 84 of 97
+// RunCommand calls in that run hit one of these two shapes, in a loop the
+// model could not escape because neither message ever said "values" itself
+// was the wrong type. Checked before "raw" is derived, so a malformed shape
+// can never reach Object.keys/Object.entries below.
+function isPlainValuesObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// #1924, third half (run-2026-09-14T05-55-54-734Z audit, Shape A): the
+// original error only ever named what the CHOSEN command declares, never
+// which OTHER declared command accepts the rejected key -- an agent that
+// wants scoped tests and picks "test" learns "no placeholders" and has to
+// guess a second time. Naming the real alternative ends the loop on the
+// first denial. Returns an empty array (no hint appended) when no other
+// command declares the key either, so a genuinely unrecognized value stays
+// exactly as informative as before -- never a false pointer.
+function otherCommandsDeclaring(declared, key, currentCommand) {
+    const names = [];
+    for (const [name, spec] of declared) {
+        if (name !== currentCommand && placeholdersOf(spec).has(key))
+            names.push(name);
+    }
+    return names;
+}
+function execSandboxNote(launcher) {
+    const state = launcher?.state;
+    if (state?.kind === "available")
+        return ` An "argv" call runs ${sandboxSentence(state.network, state.sharedTmp !== false)}`;
+    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() {
+    return { success: false, exitCode: 1, output: MISSING_RUNNER_OUTPUT };
+}
+/** One named default, so the refusal path lives in a single place. */
+function declaredCommandRunner(opts) {
+    return opts.runDeclaredCommand ?? refuseWithoutRunner;
+}
+export function createRunCommandTool(declared, opts = {}) {
+    const keys = [...declared.keys()];
+    const exec = opts.exec;
+    const hasExec = exec !== undefined;
+    const commandDescriptions = describeDeclaredCommands(declared);
+    const runDeclared = declaredCommandRunner(opts);
+    return {
+        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"] }),
+        },
+        // `{{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.
+        // `argvField` is set only when exec is available: it is what lets the
+        // 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.
+        scope: {
+            pathFields: [],
+            listPathFields: ["values.files"],
+            verbField: "command",
+            allowedVerbs: keys,
+            ...(hasExec ? { argvField: "argv" } : {}),
+        },
+        async run(input, ctx) {
+            const hasCommand = typeof input.command === "string" && input.command.length > 0;
+            const hasArgv = input.argv !== undefined;
+            if (hasCommand && hasArgv) {
+                return { content: "supply exactly one of command or argv, not both", isError: true };
+            }
+            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 key = typeof input.command === "string" ? input.command : "";
+            const template = declared.get(key);
+            if (template === undefined)
+                return { content: `unknown command "${key}"`, isError: true };
+            if (input.values !== undefined && !isPlainValuesObject(input.values)) {
+                return {
+                    content: `"values" must be an object mapping placeholder names to values, e.g. { files: "a.test.ts" } -- got ${describeValuesType(input.values)} instead`,
+                    isError: true,
+                };
+            }
+            const raw = (input.values ?? {});
+            // Shape A of the run-2026-09-14T05-55-54-734Z audit: check every
+            // rejected key against every OTHER declared command before falling
+            // through to substituteCommandSpec's generic error, so the response
+            // can name the command that actually accepts it. Only the first
+            // rejected key with a real alternative is reported -- consistent with
+            // substituteCommandSpec, which also stops at the first offending key.
+            const templateKeys = placeholdersOf(template);
+            for (const rejectedKey of Object.keys(raw)) {
+                if (templateKeys.has(rejectedKey))
+                    continue;
+                const alternates = otherCommandsDeclaring(declared, rejectedKey, key);
+                if (alternates.length === 0)
+                    continue;
+                return {
+                    content: `value "${rejectedKey}" is not a placeholder in this command (${declaredPlaceholdersSuffix(templateKeys)}) -- "${rejectedKey}" is a placeholder in: ${alternates.join(", ")}`,
+                    isError: true,
+                };
+            }
+            const values = {};
+            for (const [k, v] of Object.entries(raw)) {
+                values[k] = Array.isArray(v) && v.every((element) => typeof element === "string") ? v : String(v);
+            }
+            // `scope.listPathFields: ["values.files"]` means the policy split this
+            // value on whitespace and resolved EACH element into ctx.resolvedPaths --
+            // absolute, and approved against the grant. Substituting those instead of
+            // the raw string is what read.ts, write.ts, edit.ts and grep.ts already
+            // do, and it fixes a real defect: `bun test .nax/features/x/foo.test.ts`
+            // treats a bare dot-prefixed relative path as a test FILTER, not a path,
+            // and reports a confident false "no tests matched" (#1936). The absolute
+            // form runs.
+            //
+            // But a path field is a POLICY declaration, not a claim about what the
+            // agent actually passed. `{{files}}` is equally a test-NAME filter
+            // (`bun test run-command`), and resolveWithin accepts one happily,
+            // turning it into a nonexistent absolute path. So the resolved form is
+            // taken only for an element that is an existing FILE; everything else
+            // keeps the raw token it arrived as. "" splits to nothing, so it cannot
+            // absolutise to the root and run the entire suite.
+            //
+            // The result is an ARRAY, so each element survives substitution as its
+            // own argument -- which is what makes a multi-file scoped run possible
+            // at all, and what makes this path agree with scoped-selection.ts
+            // (nax#1998). One stat per element against a process spawn is free.
+            const rawFiles = raw.files;
+            const rawFilesValue = typeof rawFiles === "string"
+                ? rawFiles
+                : Array.isArray(rawFiles) && rawFiles.every((element) => typeof element === "string")
+                    ? rawFiles
+                    : undefined;
+            const elements = typeof rawFilesValue === "string"
+                ? pathListElements(rawFilesValue, ctx.root)
+                : Array.isArray(rawFilesValue)
+                    ? rawFilesValue
+                    : undefined;
+            if (elements !== undefined && rawFilesValue !== undefined) {
+                // The pairing is positional, and sound because `values.files` is this
+                // tool's only path field, so the policy appended exactly these
+                // elements in exactly this order (pinned by a test on `scope`).
+                //
+                // A length mismatch means the two layers disagreed -- a different root
+                // spelling, or a file created between the two stats. Falling back to
+                // the raw value is the fail-safe direction in BOTH directions: the
+                // shell then gets one argument, and one argument is always a subset of
+                // what the policy approved, however it split.
+                values.files =
+                    ctx.resolvedPaths.length === elements.length
+                        ? elements.map((element, i) => {
+                            const resolved = ctx.resolvedPaths[i];
+                            const isFile = resolved !== undefined && statSync(resolved, { throwIfNoEntry: false })?.isFile() === true;
+                            return isFile ? resolved : element;
+                        })
+                        : rawFilesValue;
+            }
+            const command = substituteCommandSpec(template, values);
+            if (typeof command !== "string" && !Array.isArray(command))
+                return { content: command.error, isError: true };
+            const result = await runDeclared({
+                commandName: key,
+                command,
+                // Post-PR2 `ctx.root` is the repo root (not the package dir), so an
+                // omitted `commandCwd` runs the declared command at the repo root —
+                // every production caller threads `commandCwd` via `buildCodingToolSupport`;
+                // this fallback only fires from tests that bypass the support seam.
+                workdir: opts.commandCwd ?? ctx.root,
+                stripEnvVars: [...(opts.stripEnvVars ?? [])],
+                // The agent's own iteration loop, not a harness gate: kept in the JSONL
+                // at debug, off the console. Its outcome reaches the agent through the
+                // returned content, and the harness reports its own gates separately.
+                origin: "agent-tool",
+            });
+            const body = `exit ${result.exitCode}\n${result.output}`;
+            // Tool-layer I/O bound, not the model-facing cap: `maxBytes` shapes what
+            // the model is told and belongs to the session's truncation policy, which
+            // spills the cut. Bounded here so a runaway command cannot be buffered
+            // without limit, and cut on a codepoint boundary so the returned body
+            // never carries a replacement character.
+            return { content: cutToByteCap(body, ctx.readCeiling ?? READ_CEILING), isError: !result.success };
+        },
+    };
+}

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

@@ -0,0 +1,146 @@
+/**
+ * `callTool`'s branch bodies, extracted from `runtime.ts` for the A13
+ * complexity drain (docs/plans/STATUS-complexity-drain.md).
+ *
+ * Each helper is one free function taking a single options object; the
+ * closure-bound collaborators (`logCall`, `runTool`, the session-wide
+ * `signal`) arrive BY REFERENCE and are read at call time, so the
+ * `_codingToolDeps` seam stays defined in `runtime.ts` exactly as the barrel
+ * (`src/tools/index.ts`) re-exports it. This file imports `runtime.ts`
+ * TYPE-ONLY — a runtime import would cycle back to the factory.
+ *
+ * One asymmetry is preserved on purpose: the denial-path breach warn below and the
+ * rejected-guard warn (US-004) call the module-level `getSafeLogger` import
+ * directly, while the ledger `log` in `runtime.ts` reads
+ * `_codingToolDeps.getLogger()`. Both behaved that way before the extraction;
+ * 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 AskResolver } from "#src/permissions/index";
+import type { SandboxRecord } from "../sandbox/index.ts";
+import type { CodingTool } from "./registry.ts";
+import type { CodingToolOutcome, ToolCallContext } from "./runtime.ts";
+import { type ToolPolicy } from "./types.ts";
+type PolicyVerdict = ReturnType<ToolPolicy["check"]>;
+/** The verdict shape the ask and deny branches see: the policy said no. */
+type DeniedVerdict = Extract<PolicyVerdict, {
+    allowed: false;
+}>;
+/** Per-call audit data a tool's result carries into the ledger. */
+export interface CallAudit {
+    executed?: readonly string[];
+    target?: "package" | "repoRoot";
+    /** Exec only: forwarded to the command shadow; never written to the ledger. */
+    cwd?: string;
+    approval?: {
+        decidedBy: string;
+        remembered: boolean;
+        latencyMs: number;
+    };
+    sandbox?: SandboxRecord;
+    exitCode?: number;
+}
+/** The per-call log wrapper `callTool` builds; settles the shadow tap too. */
+export type LogCallFn = (tool: string, outcome: CodingToolOutcome["kind"] | "denied:ask", resultBytes: number, input: Record<string, unknown>, context: ToolCallContext | undefined, breach?: boolean, reason?: string, routineErrors?: boolean, audit?: CallAudit, resultBytesPreTruncation?: number) => void;
+/** Executes a permitted call and records its outcome. */
+export type RunToolFn = (target: CodingTool, callInput: Record<string, unknown>, resolvedPaths: readonly string[], approval?: {
+    decidedBy: string;
+    remembered: boolean;
+    latencyMs: number;
+}) => Promise<CodingToolOutcome>;
+export interface PolicyIdentity {
+    readonly policyIdentity: string;
+    readonly argvField: string | undefined;
+    readonly hasArgv: boolean;
+}
+/**
+ * A call carrying the tool's declared argv field (RunCommand's `Exec`
+ * branch) is checked, and ledgered, under the `Exec` identity rather
+ * than the tool's own name. Left as `name`, an `Exec(...)` grant would
+ * never be consulted — the call would run under RunCommand's own grant
+ * (often a wildcard for its declared commands), making the allowlist
+ * decorative. The tool's registered name is unaffected; this changes
+ * only which identity the policy and ledger see for THIS call.
+ */
+export declare function resolvePolicyIdentity(name: string, tool: CodingTool, input: Record<string, unknown>): PolicyIdentity;
+/**
+ * P5: observe the command now (not awaited), settled from the caller's
+ * logCall below. Undefined whenever the runtime has no shadow configured.
+ */
+export declare function openCallShadowTap(p: {
+    shadow: CommandShadow | undefined;
+    identity: string;
+    tool: CodingTool;
+    input: Record<string, unknown>;
+    hasArgv: boolean;
+    argvField: string | undefined;
+    root: string;
+    stage: string | undefined;
+    storyId: string | undefined;
+    callId: string | undefined;
+    scopeId: string | undefined;
+    context: ToolCallContext | undefined;
+    verdict: PolicyVerdict;
+}): ReturnType<typeof openShadowTap> | undefined;
+/**
+ * US-004: the guard's flag-for-review route for an ALLOWED command.
+ *
+ * Returns the ask-shaped denial the flagged call routes through
+ * `resolveAskOutcome`, and undefined in every other case — no guard
+ * configured, an identity other than `Bash`/`Exec`, or an unflagged
+ * assessment — so the caller runs the tool exactly as it did before the guard
+ * existed. The guard is total by contract (US-003); a rejection, or a resolved
+ * decision the type does not actually hold, means that contract broke, so the
+ * call runs unguarded rather than being refused, and the failure is logged once
+ * per broken call.
+ */
+export declare function resolveGuardDenial(p: {
+    identity: string;
+    tool: CodingTool;
+    input: Record<string, unknown>;
+    argvField: string | undefined;
+    guard: CommandGuard | undefined;
+    root: string;
+    tempConfined: boolean;
+    resolvedPaths: readonly string[];
+}): Promise<DeniedVerdict | undefined>;
+/**
+ * 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
+ * context. The turn's abort signal is forwarded verbatim, and onWaiting is
+ * wired so the resolver can tell the turn loop a human prompt is pending.
+ */
+export declare function resolveAskOutcome(p: {
+    identity: string;
+    tool: CodingTool;
+    input: Record<string, unknown>;
+    context: ToolCallContext | undefined;
+    verdict: DeniedVerdict;
+    /** The runtime-level signal, falling back behind the per-call one. */
+    runtimeSignal: AbortSignal | undefined;
+    askResolver: AskResolver;
+    stage: string | undefined;
+    storyId: string | undefined;
+    root: string;
+    logCall: LogCallFn;
+    runTool: RunToolFn;
+}): Promise<CodingToolOutcome>;
+/**
+ * The deny branch: a final policy refusal, sharpened where possible with a
+ * redirect naming an advertised tool that serves the call's intent.
+ */
+export declare function resolveDenialOutcome(p: {
+    name: string;
+    identity: string;
+    tool: CodingTool;
+    input: Record<string, unknown>;
+    context: ToolCallContext | undefined;
+    verdict: DeniedVerdict;
+    argvField: string | undefined;
+    /** What `advertised()` actually returned; a redirect names only these. */
+    advertisedNames: ReadonlySet<string>;
+    declaredCommands: ReadonlySet<string> | undefined;
+    root: string;
+    logCall: LogCallFn;
+}): CodingToolOutcome;
+export {};