@nathapp/nax-agent 0.1.0

package/dist/tools/grep.js

@@ -0,0 +1,162 @@
+/**
+ * Search file contents, preferring ripgrep and falling back to grep.
+ *
+ * Both branches spawn a subprocess, so this tool is NOT evidence that the
+ * default tool set is in-process — it is not. What makes it safe is the same
+ * property that makes Git safe: a fixed binary, an argv nax constructs
+ * entirely, and no shell, so the model supplies data and never a command.
+ *
+ * The two binaries take different flags, so the argv builder is per-binary
+ * rather than shared, and the fallback is tested explicitly: a machine without
+ * ripgrep must produce the same matches, not a silent empty result.
+ */
+import { drainBounded } from "#src/internal/bounded-io";
+import { runtimeSpawn } from "#src/runtime/index";
+import { which } from "#src/runtime/which";
+import { cutToByteCap, READ_CEILING } from "./truncate.js";
+const GREP_TIMEOUT_MS = 15_000;
+/** @internal */
+const REGEX_METACHARACTERS = /[.*+?^${}()|[\]\\]/;
+/**
+ * Returns true when the pattern contains at least one regex metacharacter.
+ * Used to disclose to callers that their search was performed literally.
+ * @internal
+ */
+function containsRegexMetacharacter(pattern) {
+    return REGEX_METACHARACTERS.test(pattern);
+}
+/** @internal Injectable for tests — exercises the fallback without uninstalling ripgrep. */
+export const _grepDeps = {
+    which: (name) => which(name),
+    spawn: runtimeSpawn,
+};
+export function buildGrepArgv(binary, pattern, path, patternType = "literal") {
+    const target = path ?? ".";
+    // `--` terminates flag parsing on both branches, in both modes: a pattern
+    // beginning with "-" is then data, not an option. Neither binary is ever
+    // handed a shell string.
+    if (binary === "rg") {
+        // rg's own default IS regex (its "fixed-strings" flag is what disables
+        // it), so the regex branch simply omits the flag rather than adding one.
+        const flags = patternType === "literal"
+            ? ["--fixed-strings", "--line-number", "--no-heading", "--color", "never"]
+            : ["--line-number", "--no-heading", "--color", "never"];
+        return ["rg", ...flags, "--", pattern, target];
+    }
+    // grep has no "regex" default to fall back to: -F is fixed-strings, and the
+    // nearest equivalent to rg's regex syntax is -E (POSIX ERE, e.g. `a+`, `a|b`
+    // with no backslash), not grep's default BRE.
+    const modeFlag = patternType === "literal" ? "-F" : "-E";
+    return ["grep", "-r", "-n", modeFlag, "--", pattern, target];
+}
+export const grepTool = {
+    name: "Grep",
+    description: "Search repository file contents for a literal string or a regular expression. Returns 'path:line:text' rows relative to the repository root when no subdirectory target is supplied, absolute when one is (rg prints the target as given). Defaults to a literal (fixed-string) search; set pattern_type to \"regex\" to interpret the pattern as a regular expression (ripgrep syntax, e.g. `foo|bar`, `\\d+`; on a machine without ripgrep the pattern falls back to POSIX ERE, which the result discloses).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            pattern: {
+                type: "string",
+                description: 'String to search for. Interpreted literally unless pattern_type is "regex", in which case it is a regular expression.',
+            },
+            path: { type: "string", description: "Optional subdirectory, relative to the repository root" },
+            pattern_type: {
+                type: "string",
+                enum: ["literal", "regex"],
+                default: "literal",
+                description: '"literal" (default) matches pattern as a fixed string; "regex" interprets it as a regex.',
+            },
+        },
+        required: ["pattern"],
+    },
+    // The optional `path` is path-bearing and is gated exactly like Read's: the
+    // policy resolves it through resolveWithin, denying escapes as breaches.
+    // `pattern` is not a path and needs no path gating.
+    scope: { pathFields: ["path"] },
+    async run(input, ctx) {
+        const pattern = input.pattern;
+        if (typeof pattern !== "string")
+            return { content: "pattern must be a string", isError: true };
+        const patternType = input.pattern_type;
+        if (patternType !== undefined && patternType !== "literal" && patternType !== "regex") {
+            return { content: 'pattern_type must be "literal" or "regex"', isError: true };
+        }
+        const mode = patternType === "regex" ? "regex" : "literal";
+        const binary = _grepDeps.which("rg") ? "rg" : _grepDeps.which("grep") ? "grep" : null;
+        if (binary === null) {
+            return { content: "neither ripgrep nor grep is available on this machine", isError: true };
+        }
+        const [target] = ctx.resolvedPaths;
+        // The I/O ceiling, not the model-facing cap: `maxBytes` shapes what the
+        // model is told and belongs to the session's truncation policy, while this
+        // bound only keeps a search whose result is enormous from being buffered
+        // without limit. Bounding both the drain and the returned body at the same
+        // value is what lets a result in (maxBytes, readCeiling) reach that policy
+        // whole, and it is why the ceiling is a tool-layer constant.
+        const ioCeiling = ctx.readCeiling ?? READ_CEILING;
+        // nax-git-env-allow: not git: rg/grep search argv
+        const proc = _grepDeps.spawn(buildGrepArgv(binary, pattern, target, mode), {
+            cwd: ctx.root,
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+        const timer = setTimeout(() => {
+            try {
+                proc.kill("SIGKILL");
+            }
+            catch {
+                // already exited
+            }
+        }, GREP_TIMEOUT_MS);
+        // Drain concurrently: a large result set fills the pipe buffer and would
+        // otherwise block the process before it can exit. Bounded, because the
+        // result is truncated to the same ceiling anyway -- a search matching a
+        // generated file could otherwise buffer far more than is ever returned,
+        // limited only by how much the binary emits before the timeout fires.
+        const stdoutText = drainBounded(proc.stdout, ioCeiling).catch(() => "");
+        const stderrText = drainBounded(proc.stderr, ioCeiling).catch(() => "");
+        const exitCode = await proc.exited;
+        clearTimeout(timer);
+        const stdout = await stdoutText;
+        // Two independent caveats, either of which means the search the caller
+        // asked for is not quite the search that ran.
+        //
+        // 1. The literal disclosure fires whenever the search was literal AND the
+        //    pattern contained a metacharacter a regex would have treated
+        //    specially -- regardless of whether it matched. #1876 only covered the
+        //    zero-match case; a literal match on a pattern like "foo.bar" is the
+        //    WORSE case (#1922): the caller has positive evidence and no cue that
+        //    "." was never a wildcard, so a real regex match was never attempted.
+        //
+        // 2. The dialect note fires when regex mode ran through the grep fallback.
+        //    ripgrep's Rust regex and POSIX ERE are NOT the same language: `\d`,
+        //    `\w` and `\b` are unsupported in ERE, and whether they degrade to a
+        //    literal or to something else differs BY PLATFORM (GNU grep treats
+        //    `\d` as `d`; the BSD grep on macOS matches a digit). Silently
+        //    returning a different answer depending on which binary the machine
+        //    happens to have is exactly the failure this file's header forbids of
+        //    the fallback, so the divergence is disclosed rather than hidden.
+        const notes = [];
+        if (mode === "literal" && containsRegexMetacharacter(pattern)) {
+            notes.push("The search was performed literally and regex metacharacters were not interpreted.");
+        }
+        if (mode === "regex" && binary === "grep") {
+            notes.push("ripgrep is not installed here, so the pattern was matched with POSIX ERE via grep: escapes such as \\d, \\w and \\b are NOT supported — use [0-9], [A-Za-z0-9_] and similar instead.");
+        }
+        const caveat = notes.join(" ");
+        // Both binaries exit 1 for "no matches" — a normal outcome, not a failure.
+        if (exitCode === 1 && stdout.trim() === "") {
+            const base = `no matches for "${pattern}"`;
+            return { content: caveat === "" ? base : `${base}. ${caveat}` };
+        }
+        if (exitCode !== 0 && stdout.trim() === "") {
+            return { content: (await stderrText).trim() || `${binary} exited ${exitCode}`, isError: true };
+        }
+        // The caveat leads rather than trails, and the tool's own bound is applied
+        // to the whole body: appended after the cap it both overran the ceiling and
+        // was the first thing lost on a result large enough to need the cue most.
+        const matches = stdout.trimEnd();
+        const body = caveat === "" ? matches : `${caveat}\n\n${matches}`;
+        return { content: cutToByteCap(body, ioCeiling) };
+    },
+};

package/dist/tools/index.d.ts

@@ -0,0 +1,36 @@
+export { _bashToolDeps, BASH_TIMEOUT_MS, createBashTool, DEFAULT_BASH_SHELL } from "./bash.ts";
+export { deleteTool } from "./delete.ts";
+export { _editDeps, editTool } from "./edit.ts";
+export { buildGitArgv, DEFAULT_LOG_FORMAT, DEFAULT_LOG_MAX_COUNT, GIT_ESCAPE_FLAGS, GIT_READ_VERBS, gitTool, } from "./git.ts";
+export { buildCommitArgvs, gitCommitTool, partitionNaxOwnedPaths } from "./git-commit.ts";
+export { _globDeps, globTool } from "./glob.ts";
+export { _grepDeps, buildGrepArgv, grepTool } from "./grep.ts";
+export { narrowGrants, type ToolPatternNarrowing } from "./narrow-grants.ts";
+export type { ExecTarget, NormalizeInput, NormalizeResult } from "./package-managers.ts";
+export { classifyExec, isKnownManager, normalizeExec, normalizeManagerBinary } from "./package-managers.ts";
+export type { ToolPolicyOptions } from "./policy.ts";
+export { compileToolPolicy, resolveWithin } from "./policy.ts";
+export type { ProtectedPathsPolicy } from "./protected-paths.ts";
+export { gitExcludePathspecsOf, gitIgnorePatternsOf } from "./protected-paths.ts";
+export * from "./provider-adapt.ts";
+export * from "./provider-advertise.ts";
+export * from "./provider-grants.ts";
+export * from "./provider-sanitize.ts";
+export * from "./provider-types.ts";
+export { readTool } from "./read.ts";
+export { type ReadFileSliceOptions, type ReadFileSliceResult, readFileSlice } from "./read-file.ts";
+export type { CodingTool, ToolResult, ToolRunContext } from "./registry.ts";
+export { _resetRegistryForTest, getCodingTool, listCodingTools, RESERVED_TOOL_NAMES, registerBuiltinTool, registerCodingTool, } from "./registry.ts";
+export { requestCapabilityTool } from "./request-capability.ts";
+export type { DeclaredCommandRequest, DeclaredCommandResult, DeclaredCommandRunner } from "./run-command.ts";
+export { createRunCommandTool, substituteCommand, substituteCommandSpec } from "./run-command.ts";
+export type { CodingToolOutcome, CodingToolRuntime, ToolCallContext } from "./runtime.ts";
+export { _codingToolDeps, _resetBuiltinsForTest, createCodingToolRuntime, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, registerBuiltinCodingTools, } from "./runtime.ts";
+export { SCRATCHPAD_DIR, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool } from "./scratchpad.ts";
+export { _spillDeps, applyModelTruncationPolicy, type ModelTruncationOptions, SPILL_DIR, type SpillRequest, spillRelativePath, writeSpill, } from "./spill.ts";
+export type { RegisteredSink, ToolAuditSink, ToolCallRecord } from "./tool-audit.ts";
+export { createNoOpToolAuditSink, createToolAuditSink, flushOpenToolAuditSinks, registerToolAuditSink, unregisterToolAuditSink, } from "./tool-audit.ts";
+export { cutBufferToByteCap, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, READ_CEILING, type TruncateForModelOptions, type TruncationDirection, type TruncationResult, truncateForModel, truncationDirectionFor, } from "./truncate.ts";
+export type { CodingToolName, PolicyVerdict, ToolGrant, ToolPolicy, ToolScope } from "./types.ts";
+export { BASH_TOOL_NAME, EXEC_TOOL_NAME } from "./types.ts";
+export { writeTool } from "./write.ts";

package/dist/tools/index.js

@@ -0,0 +1,28 @@
+export { _bashToolDeps, BASH_TIMEOUT_MS, createBashTool, DEFAULT_BASH_SHELL } from "./bash.js";
+export { deleteTool } from "./delete.js";
+export { _editDeps, editTool } from "./edit.js";
+export { buildGitArgv, DEFAULT_LOG_FORMAT, DEFAULT_LOG_MAX_COUNT, GIT_ESCAPE_FLAGS, GIT_READ_VERBS, gitTool, } from "./git.js";
+export { buildCommitArgvs, gitCommitTool, partitionNaxOwnedPaths } from "./git-commit.js";
+export { _globDeps, globTool } from "./glob.js";
+export { _grepDeps, buildGrepArgv, grepTool } from "./grep.js";
+export { narrowGrants } from "./narrow-grants.js";
+export { classifyExec, isKnownManager, normalizeExec, normalizeManagerBinary } from "./package-managers.js";
+export { compileToolPolicy, resolveWithin } from "./policy.js";
+export { gitExcludePathspecsOf, gitIgnorePatternsOf } from "./protected-paths.js";
+export * from "./provider-adapt.js";
+export * from "./provider-advertise.js";
+export * from "./provider-grants.js";
+export * from "./provider-sanitize.js";
+export * from "./provider-types.js";
+export { readTool } from "./read.js";
+export { readFileSlice } from "./read-file.js";
+export { _resetRegistryForTest, getCodingTool, listCodingTools, RESERVED_TOOL_NAMES, registerBuiltinTool, registerCodingTool, } from "./registry.js";
+export { requestCapabilityTool } from "./request-capability.js";
+export { createRunCommandTool, substituteCommand, substituteCommandSpec } from "./run-command.js";
+export { _codingToolDeps, _resetBuiltinsForTest, createCodingToolRuntime, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, registerBuiltinCodingTools, } from "./runtime.js";
+export { SCRATCHPAD_DIR, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool } from "./scratchpad.js";
+export { _spillDeps, applyModelTruncationPolicy, SPILL_DIR, spillRelativePath, writeSpill, } from "./spill.js";
+export { createNoOpToolAuditSink, createToolAuditSink, flushOpenToolAuditSinks, registerToolAuditSink, unregisterToolAuditSink, } from "./tool-audit.js";
+export { cutBufferToByteCap, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, READ_CEILING, truncateForModel, truncationDirectionFor, } from "./truncate.js";
+export { BASH_TOOL_NAME, EXEC_TOOL_NAME } from "./types.js";
+export { writeTool } from "./write.js";

package/dist/tools/narrow-grants.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Narrowing a grant an operation inherits.
+ *
+ * `CodingToolRuntime.advertised()` intersects tool NAMES against the policy's
+ * grants, so an op declaring `Write` under the `unrestricted` profile received
+ * that profile's `["*"]` — there was no way to say "this role may write, but
+ * only this one file" (nax#2013).
+ *
+ * Narrowing only. `resolvePermissions` remains the single permission authority
+ * (CLAUDE.md, Permission Resolution): a tool the profile did not grant has no
+ * grant here to narrow, so nothing in this module can widen access.
+ *
+ * Glob-set intersection is undecidable in general, so the rule is structural
+ * rather than semantic — see each branch below.
+ */
+import type { CodingToolName, ToolGrant } from "./types.ts";
+/** Per-tool path globs an operation asks to be held to. */
+export type ToolPatternNarrowing = Partial<Record<CodingToolName, readonly string[]>>;
+export declare function narrowGrants(grants: readonly ToolGrant[], narrowing: ToolPatternNarrowing | undefined): readonly ToolGrant[];

package/dist/tools/narrow-grants.js

@@ -0,0 +1,54 @@
+/**
+ * Narrowing a grant an operation inherits.
+ *
+ * `CodingToolRuntime.advertised()` intersects tool NAMES against the policy's
+ * grants, so an op declaring `Write` under the `unrestricted` profile received
+ * that profile's `["*"]` — there was no way to say "this role may write, but
+ * only this one file" (nax#2013).
+ *
+ * Narrowing only. `resolvePermissions` remains the single permission authority
+ * (CLAUDE.md, Permission Resolution): a tool the profile did not grant has no
+ * grant here to narrow, so nothing in this module can widen access.
+ *
+ * Glob-set intersection is undecidable in general, so the rule is structural
+ * rather than semantic — see each branch below.
+ */
+import { getSafeLogger } from "#src/infra/index";
+const UNCONDITIONAL = "*";
+export function narrowGrants(grants, narrowing) {
+    if (narrowing === undefined || Object.keys(narrowing).length === 0)
+        return grants;
+    // Indexed through a Map rather than `narrowing[grant.tool]`: `ToolGrant.tool`
+    // is a plain string (third parties register their own names) while the
+    // op-facing type is keyed on CodingToolName so a typo in an op is a compile
+    // error. Object.entries bridges the two without a cast.
+    const wanted = new Map(Object.entries(narrowing).filter((entry) => entry[1] !== undefined));
+    const out = [];
+    for (const grant of grants) {
+        const requested = wanted.get(grant.tool);
+        if (requested === undefined || requested.length === 0) {
+            out.push(grant);
+            continue;
+        }
+        // An unconditional grant is wider than any concrete list, so the op's
+        // patterns are unambiguously a narrowing of it.
+        if (grant.patterns.includes(UNCONDITIONAL)) {
+            out.push({ tool: grant.tool, patterns: [...requested] });
+            continue;
+        }
+        // A scoped grant already names specific globs. Comparing two globs for
+        // containment is undecidable, so admit only the ones the grant's author
+        // wrote verbatim — which is what a scoped profile intending this writes.
+        const admitted = requested.filter((pattern) => grant.patterns.includes(pattern));
+        if (admitted.length === 0) {
+            getSafeLogger()?.warn("tools", "[policy] op narrowing excluded by the scoped grant — tool withheld", {
+                tool: grant.tool,
+                requested: [...requested],
+                granted: [...grant.patterns],
+            });
+            continue;
+        }
+        out.push({ tool: grant.tool, patterns: admitted });
+    }
+    return out;
+}

package/dist/tools/nax-owned-writes.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Which paths nax refuses to let an agent touch, and to which tools.
+ *
+ * A separate file rather than an addition to src/tools/policy.ts, for the same
+ * reason src/tools/deny-paths.ts is one: that file carries the containment
+ * seam and sits at the project's file-size ratchet, while this is a narrower
+ * concern -- it has nothing to do with resolving or containing a path, only
+ * with refusing one containment would otherwise allow.
+ *
+ * Segment-exact, never a prefix or substring match: `.naxignore`,
+ * `docs/nax/config.json` and `.nax/mono/api/notes.md` are ordinary paths a
+ * tool must still reach.
+ */
+/**
+ * The one top-level `.nax/` entry agents may write freely: the scratchpad.
+ * Must equal the last segment of SCRATCHPAD_DIR (pinned by a test; importing
+ * it here would close a scratchpad -> policy -> nax-owned-writes cycle).
+ */
+export declare const NAX_SCRATCHPAD_ENTRY = "scratchpad";
+/**
+ * Entries nax loads as human-authored input. The sandbox denies these even
+ * when absent, so an agent cannot create one: a new `.nax/rules/x.md` would be
+ * injected into every later session's prompt, and `hooks.json` / `plugins/`
+ * run unsandboxed on the next `nax run`. `templates/` and `prompts/` are where
+ * `prompts.overrides` points. nax creates none of them mid-run (CLI only).
+ */
+export declare const NAX_ALWAYS_DENIED_ENTRIES: readonly string[];
+/**
+ * Top-level `.nax/` entries a human opened for agent writes by listing them in
+ * `execution.sandbox.filesystem.allowWrite` (nax#2260). Only an exact entry
+ * counts -- `.nax/rules`, never `.nax/rules/a.md` -- and never the scratchpad
+ * (always open) or a NAX_NEVER_OPT_IN entry. Relative entries resolve against
+ * `root`, as the sandbox's own write roots do.
+ */
+export declare function naxWriteOptIns(root: string, allowWrite: readonly string[]): ReadonlySet<string>;
+/**
+ * Is `resolved` one of nax's own CONFIG files, relative to `root`?
+ *
+ * `.nax/config.json`, and `.nax/mono/<package>/config.json` in a monorepo.
+ *
+ * Why these at all: `quality.commands` and `acceptance.command` are run by key
+ * through a shell and never pass the permission gate -- they are trusted
+ * because a HUMAN wrote them. That trust rests entirely on a model being
+ * unable to write them. An agent holding `Write` under the default
+ * `unrestricted` profile could otherwise add a quality command and receive an
+ * ungated shell on the next run, routing around every `Bash(...)` rule, the
+ * lexer's construct refusals and containment itself.
+ *
+ * Refused to EVERY tool, reads included -- this is the pre-existing behaviour
+ * and it is deliberate.
+ */
+export declare function isNaxConfigFile(root: string, resolved: string): boolean;
+/**
+ * The path-bearing tools that MUTATE. Read, Grep, Glob and Git are read-only
+ * and are deliberately absent: an agent legitimately reads its own PRD, and
+ * refusing that would break ordinary work to close one hole.
+ *
+ * Bash and Exec are absent because they carry no path fields -- a shell
+ * redirect into `.nax/` is gated by the human-authored `Bash(...)` rules and
+ * the lexer, which is a different seam from this one.
+ */
+export declare const NAX_OWNED_WRITE_TOOLS: ReadonlySet<string>;
+/**
+ * nax's run-control files at the root: the command channel an agent could
+ * otherwise use to PAUSE, ABORT or SKIP stories without writing any code.
+ *
+ * `.queue.txt.processing` is the atomic-rename target the queue handler reads
+ * from (src/execution/queue-handler.ts), so guarding only `.queue.txt` would
+ * leave the same hole one rename downstream.
+ */
+export declare const QUEUE_CONTROL_FILES: ReadonlySet<string>;
+/**
+ * The kinds of nax-owned path the raw Bash screen refuses by name.
+ * `"config"` is produced by the lexical `isNaxConfigFile` pass, never by
+ * `naxOwnedKind` -- see that function.
+ */
+export type NaxOwnedKind = "prd" | "queue" | "config";
+/**
+ * Is this path one nax owns the writes to, independent of WHICH tool is asking?
+ *
+ * `naxOwnedWriteRefusal` answers the same question for the four file-writing
+ * tools and returns prose. This predicate is the tool-agnostic half, extracted
+ * so the `raw` bash screen (ADR-030) can consult exactly the same path set
+ * without being in `NAX_OWNED_WRITE_TOOLS`. One definition, two callers.
+ *
+ * @param rel - Path relative to the permitted root, `/`-joined.
+ */
+export declare function isNaxOwnedWritePath(rel: string): boolean;
+/**
+ * Which kind of nax-owned write path `rel` is, or undefined when it is not one.
+ *
+ * `/`-joined and root-relative, like `isNaxOwnedWritePath`. Never returns
+ * `"config"` -- nax config files are recognised by the lexical
+ * `isNaxConfigFile` pass, which callers (`protectedHit` in policy-bash-raw.ts)
+ * run FIRST. Keeping the two apart is what lets the raw screen name the kind it
+ * matched without duplicating the config rule here.
+ */
+export declare function naxOwnedKind(rel: string): "prd" | "queue" | undefined;
+/**
+ * Refusal text for a Bash command that names (verb "names") or redirects into
+ * (verb "redirects into") a nax-owned file.
+ *
+ * Kind-specific on purpose. The previous screen returned one modification-only
+ * sentence for every kind, which read as "you cannot WRITE this" -- so an agent
+ * that only wanted to READ a PRD retried a command it will never be allowed to
+ * run. Each branch now says what the file IS and what the agent can do instead.
+ *
+ * The text never spells `.nax/features/` literally: `src/tools/` is covered by
+ * the `check:feature-dir-ssot` gate, so the PRD branch names the token the agent
+ * used (`hit`) rather than the tree layout.
+ *
+ * US-002: `opts.sandboxWrapped` (an available launcher) swaps only the PRD
+ * sentence -- reading through Bash is then allowed, writing still is not.
+ * `config` and `queue` are unchanged in both modes.
+ */
+export declare function naxOwnedBashRefusal(tool: string, kind: NaxOwnedKind, hit: string, verb: "names" | "redirects into", opts?: {
+    sandboxWrapped?: boolean;
+}): string;
+/**
+ * Why `tool` may not touch `rel`, or `undefined` when it may.
+ *
+ * `rel` MUST be the canonical, posix-separated, root-relative spelling the
+ * policy itself derived -- never the caller's own. Matching the caller's
+ * spelling means this guard and the policy that approved the call are reading
+ * different strings, and every alternate spelling ("./x", "a/../x") walks past
+ * the guard. Same rule, and the same reason, as `matchesDenyPaths`.
+ *
+ * The PRD defines the acceptance criteria the story is judged against. An
+ * agent that can rewrite it can pass any review without writing any code,
+ * which defeats the review layer without touching a config file.
+ *
+ * The queue file is the other half of the same concern: it is the run-control
+ * channel, and a write there can pause, abort or skip stories outright.
+ */
+export declare function naxOwnedWriteRefusal(tool: string, rel: string, exemptRel?: string, optIns?: ReadonlySet<string>): string | undefined;