@nathapp/nax-agent 0.1.0 → 0.2.0

package/dist/tools/grep.js

@@ -13,6 +13,7 @@
 import { drainBounded } from "#src/internal/bounded-io";
 import { runtimeSpawn } from "#src/runtime/index";
 import { which } from "#src/runtime/which";
+import { containsCredentialPath, credentialReadRefusal } from "./credential-read-deny.js";
 import { cutToByteCap, READ_CEILING } from "./truncate.js";
 const GREP_TIMEOUT_MS = 15_000;
 /** @internal */
@@ -30,6 +31,52 @@ export const _grepDeps = {
     which: (name) => which(name),
     spawn: runtimeSpawn,
 };
+/**
+ * The two independent caveats a search may carry, 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.
+ */
+function searchCaveat(mode, binary, pattern) {
+    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.");
+    }
+    return notes.join(" ");
+}
+/**
+ * The credential read-deny for a search rooted at `searchRoot` (S3 spec 6.3),
+ * or undefined. Two shapes: the search root itself is a credential path, and
+ * the subtler one where a subtree of `searchRoot` contains it — a root-level
+ * search on a workdir laid over the host's home would read the credential
+ * directory's contents via matches.
+ */
+function credentialSearchRefusal(ctx, searchRoot, shown) {
+    const inside = credentialReadRefusal(ctx.protectedPaths, searchRoot);
+    if (inside !== undefined)
+        return `path "${shown}" ${inside}`;
+    if (!containsCredentialPath(ctx.protectedPaths, searchRoot))
+        return undefined;
+    return ("this search would reach the host's credential directory or trust store, which the read tools are refused; " +
+        "narrow the search to a subdirectory that does not contain it");
+}
 export function buildGrepArgv(binary, pattern, path, patternType = "literal") {
     const target = path ?? ".";
     // `--` terminates flag parsing on both branches, in both modes: a pattern
@@ -87,6 +134,11 @@ export const grepTool = {
             return { content: "neither ripgrep nor grep is available on this machine", isError: true };
         }
         const [target] = ctx.resolvedPaths;
+        // S3 spec 6.3: the search must not reach the host's credential directory
+        // or trust store, whatever grant resolved the target.
+        const refusal = credentialSearchRefusal(ctx, target ?? ctx.root, typeof input.path === "string" ? input.path : ".");
+        if (refusal !== undefined)
+            return { content: refusal, isError: true };
         // 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
@@ -118,32 +170,9 @@ export const grepTool = {
         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(" ");
+        // Two independent caveats may apply -- the literal disclosure and the grep
+        // fallback's ERE dialect note. Their rules live in `searchCaveat` (above).
+        const caveat = searchCaveat(mode, binary, pattern);
         // Both binaries exit 1 for "no matches" — a normal outcome, not a failure.
         if (exitCode === 1 && stdout.trim() === "") {
             const base = `no matches for "${pattern}"`;

package/dist/tools/owned-paths.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The owned-paths port (S3 spec 6.5, arc decision D16): which paths the HOST
+ * owns the writes to, and how its refusals read. nax-agent holds no such
+ * knowledge itself; nax injects its policy through `buildCodingToolSupport`
+ * and `resolveSessionSandbox`, and an embedder that injects nothing gets
+ * `EMPTY_OWNED_PATHS_POLICY`: containment and the `.git/` refusal still apply,
+ * owned-path refusals do not.
+ */
+/** One working-directory frame of a raw Bash token, in frame order. */
+export interface OwnedBashCandidate {
+    /** The token resolved lexically against one working directory, symlinks resolved (`realOrRaw`). */
+    readonly lexical: string;
+    /** The typed-seam resolver's root-relative, `/`-joined path for that frame; null when it refused or the path is outside the root. */
+    readonly rel: string | null;
+}
+export interface OwnedPathsPolicy {
+    /** Refusal for a mutating path tool on a root-relative, `/`-joined path; undefined = not owned. */
+    writeRefusal(tool: string, rel: string, ctx: {
+        readonly exemptRel?: string;
+        readonly optIns: ReadonlySet<string>;
+    }): string | undefined;
+    /**
+     * Refusal for ANY tool, reads included, on a symlink-resolved absolute path;
+     * undefined = not refused. Non-undefined makes `resolveWithin` refuse the path,
+     * and the text completes `outOfRootReason`'s `path "x" <text>` sentence.
+     */
+    configRefusal(root: string, resolved: string): string | undefined;
+    /** Raw Bash screen: full refusal for `token` given its per-frame candidates; undefined = allowed. */
+    bashRefusal(tool: string, token: string, candidates: readonly OwnedBashCandidate[], ctx: {
+        readonly root: string;
+        readonly verb: "names" | "redirects into";
+        readonly sandboxWrapped: boolean;
+    }): string | undefined;
+    /** Top-level project-state entries the sandbox denies writes to, even when absent. */
+    readonly deniedEntries: readonly string[];
+    /** Root-level file names the sandbox denies writes to. */
+    readonly rootWriteDenies: readonly string[];
+    /** The one project-state entry agents may always write; never sandbox-denied. */
+    readonly scratchpadEntry?: string;
+    /** Project-state entries opened for writes by `allowWrite`. */
+    writeOptIns(root: string, allowWrite: readonly string[]): ReadonlySet<string>;
+}
+export declare const EMPTY_OWNED_PATHS_POLICY: OwnedPathsPolicy;

package/dist/tools/owned-paths.js

@@ -0,0 +1,17 @@
+/**
+ * The owned-paths port (S3 spec 6.5, arc decision D16): which paths the HOST
+ * owns the writes to, and how its refusals read. nax-agent holds no such
+ * knowledge itself; nax injects its policy through `buildCodingToolSupport`
+ * and `resolveSessionSandbox`, and an embedder that injects nothing gets
+ * `EMPTY_OWNED_PATHS_POLICY`: containment and the `.git/` refusal still apply,
+ * owned-path refusals do not.
+ */
+const NO_OPT_INS = new Set();
+export const EMPTY_OWNED_PATHS_POLICY = {
+    writeRefusal: () => undefined,
+    configRefusal: () => undefined,
+    bashRefusal: () => undefined,
+    deniedEntries: [],
+    rootWriteDenies: [],
+    writeOptIns: () => NO_OPT_INS,
+};

package/dist/tools/package-managers.d.ts

@@ -66,12 +66,15 @@
  * a widening `Exec(...)` grant by hand — defense-in-depth, not a live hole
  * under the shipped default.
  */
+import { type OwnedPathsPolicy } from "./owned-paths.ts";
 import type { NormalizeResult, WorkspaceContext } from "./package-managers-types.ts";
 export type { ExecTarget, NormalizeResult } from "./package-managers-types.ts";
 import type { ExecTarget } from "./package-managers-types.ts";
 export interface NormalizeInput extends WorkspaceContext {
     readonly argv: readonly string[];
     readonly target: ExecTarget;
+    /** Host-owned path rules (S3-2 port) handed to resolveWithin; absent: none (the empty policy). */
+    readonly ownedPaths?: OwnedPathsPolicy;
 }
 /**
  * Lowercases and strips a trailing executable suffix so `NPM`, `npm.cmd`

package/dist/tools/package-managers.js

@@ -68,6 +68,7 @@
  */
 import { resolve } from "node:path";
 import { normalizeFlagToken } from "./exec-guard.js";
+import { EMPTY_OWNED_PATHS_POLICY } from "./owned-paths.js";
 import { MANAGER_TABLE } from "./package-managers-table.js";
 import { resolveWithin } from "./policy.js";
 /** Package runners that execute an arbitrary, model-named package outside
@@ -295,7 +296,10 @@ function isPathShapedToken(token, manager) {
  * absolute, so it is `resolveWithin`'s own `isAbsolute` branch that runs the
  * actual containment check.
  */
-function findPositionalPathConflict(argv, entry, repoRoot, resolvedCwd) {
+function findPositionalPathConflict(argv, entry, repoRoot, resolvedCwd, ownedPaths) {
+    // Defaulted HERE, not at the call site: normalizeExec sits at its complexity
+    // limit and one more `??` there would breach the ratchet.
+    const owned = ownedPaths ?? EMPTY_OWNED_PATHS_POLICY;
     const manager = normalizeManagerBinary(argv[0]);
     const verbStart = firstNonFlagIndexAfterBinary(argv);
     if (verbStart === -1)
@@ -309,7 +313,7 @@ function findPositionalPathConflict(argv, entry, repoRoot, resolvedCwd) {
         if (!isPathShapedToken(token, manager))
             continue;
         const absolute = token.startsWith("/") ? token : resolve(resolvedCwd, token);
-        if (resolveWithin(repoRoot, absolute) === null) {
+        if (resolveWithin(repoRoot, absolute, owned) === null) {
             return `argv contains a path-shaped argument "${token}" that resolves outside the permitted root`;
         }
     }
@@ -381,7 +385,7 @@ export function normalizeExec(input) {
     const base = effectiveTarget === "package" ? entry.packageForm(argv, input) : entry.rootForm(argv, input);
     if ("error" in base)
         return base;
-    const positionalPathConflict = findPositionalPathConflict(argv, entry, input.repoRoot, base.cwd);
+    const positionalPathConflict = findPositionalPathConflict(argv, entry, input.repoRoot, base.cwd, input.ownedPaths);
     if (positionalPathConflict !== undefined) {
         return { error: positionalPathConflict };
     }

package/dist/tools/policy-bash-raw.d.ts

@@ -1,3 +1,4 @@
+import type { OwnedPathsPolicy } from "./owned-paths.ts";
 import type { BashCheck } from "./policy-bash.ts";
 export interface RawScreenArgs {
     readonly tool: string;
@@ -15,5 +16,7 @@ export interface RawScreenArgs {
      * write. Absent or false screens exactly as before.
      */
     readonly sandboxWrapped?: boolean;
+    /** S3-2: host-owned path rules; decides which tokens and redirects are refused and how. */
+    readonly ownedPaths: OwnedPathsPolicy;
 }
 export declare function screenRawBashCommand(args: RawScreenArgs): BashCheck;

package/dist/tools/policy-bash-raw.js

@@ -6,9 +6,12 @@
  * rather than refused. That inversion is the whole point of the mode.
  *
  * The one thing this screen still does is catch a naive mistake: if the lexer
- * CAN parse the command and a segment names or redirects into a path nax owns
- * (`.nax/config.json`, `.nax/mono/*\/config.json`, `.nax/features/**\/prd.json`,
- * the root queue-control files), the command is denied.
+ * CAN parse the command and a segment names or redirects into a path the
+ * host's owned-paths policy owns (for nax: `.nax/config.json`,
+ * `.nax/mono/*\/config.json`, `.nax/features/**\/prd.json`, the root
+ * queue-control files), the command is denied. Which paths those are, and how
+ * a refusal reads, is the `OwnedPathsPolicy` port's decision (S3-2); this
+ * screen only supplies the per-frame candidates.
  *
  * ADVISORY BY CONSTRUCTION. A command using substitution is not parsed and
  * therefore is not screened at all: `sh -c "$(echo rm) .nax/features/f/prd.json"`
@@ -50,7 +53,6 @@ import { relative, resolve, sep } from "node:path";
 import { realOrRaw } from "#src/internal/realpath";
 import { lexBashCommand } from "#src/permissions/index";
 import { cdTargetsFor, nextWorkingDirectories } from "./bash-cwd.js";
-import { isNaxConfigFile, naxOwnedBashRefusal, naxOwnedKind } from "./nax-owned-writes.js";
 /**
  * US-002: the start paths that mean "search the whole filesystem". An exact
  * token comparison, never a prefix one: `~/proj` and `~user` are scoped and
@@ -99,60 +101,40 @@ function deny(reason) {
     return { kind: "deny", reason, breach: false, escalatable: false };
 }
 /**
- * A protected path, named for the refusal message, or undefined.
+ * One `OwnedBashCandidate` per live frame, in frame order.
  *
- * Returns the KIND it matched alongside the token the agent used, so the caller
- * can print kind-specific refusal text (`naxOwnedBashRefusal`).
+ * The two passes are the policy's now (`OwnedPathsPolicy.bashRefusal`); this
+ * function only supplies the evidence, one candidate per frame.
  *
- * Checked against EVERY frame in `cwd`, mirroring the conservatism of gated
+ * Built against EVERY frame in `cwd`, mirroring the conservatism of gated
  * mode's own `resolveAll`: a `;`-joined `cd` can leave more than one frame
  * live at once (see `nextWorkingDirectories`), and a candidate that is safe
- * from one frame but hits a protected path from another must still deny.
+ * from one frame but hits an owned path from another must still be seen.
  *
- * Two passes, in order:
+ * Per frame, the candidate carries both halves of today's two-pass order:
  *
- * 1. LEXICAL nax-config check. The raw screen has no typed seam in front of
- *    it, and `args.resolvePath` (production: `resolveWithin`) returns null
- *    for `.nax/config.json` exactly because typed tools are SUPPOSED to refuse
- *    those writes. Falling through to that null would let the entire class
- *    of nax-config writes go unscreened. Resolve the candidate lexically
- *    against each frame -- `realOrRaw` walks to the nearest existing ancestor,
- *    so a not-yet-created file under a symlinked temp root still compares
- *    equal to `realOrRaw(root)` -- and refuse on `isNaxConfigFile` BEFORE the
- *    resolver is consulted.
+ * 1. `lexical`: the candidate resolved lexically against the frame --
+ *    `realOrRaw` walks to the nearest existing ancestor, so a not-yet-created
+ *    file under a symlinked temp root still compares equal to
+ *    `realOrRaw(root)`. The policy's lexical config check runs
+ *    on this, BEFORE the resolver is consulted -- the raw screen has no typed
+ *    seam in front of it, and `resolvePath` (production: `resolveWithin`)
+ *    returns null for `.nax/config.json` exactly because typed tools are
+ *    SUPPOSED to refuse those writes.
  *
- * 2. Typed-seam resolver pass (unchanged). `args.resolvePath` continues to be
- *    the gate for everything else: a `null` skips this frame, an out-of-root
- *    path skips this frame, and `isNaxOwnedWritePath` covers the queue file
- *    and feature PRD set.
- *
- * The two checks do not overlap: pass 1 covers nax config files; pass 2 covers
- * feature PRDs and the queue run-control files. `isNaxConfigFile` is checked
- * lexically here because the resolver cannot return it, and lexically in
- * `resolveWithin` for the same reason; `isNaxOwnedWritePath` is unchanged.
+ * 2. `rel`: the typed-seam resolver's root-relative spelling for the same
+ *    frame, null when it refused or the path is outside the root. The
+ *    policy's PRD/queue check runs on this.
  */
-function protectedHit(args, candidate, cwd) {
-    for (const directory of cwd) {
-        // Pass 1: lexical nax-config check. Independent of the resolver on
-        // purpose -- see the comment above. `realOrRaw` walks to the nearest
-        // existing ancestor so the comparison holds even when the file does not
-        // yet exist on disk (which is the common case: the screen catches the
-        // write BEFORE the file lands).
-        const lexical = realOrRaw(resolve(directory, candidate));
-        if (isNaxConfigFile(args.root, lexical))
-            return { kind: "config", hit: candidate };
-        // Pass 2: typed-seam resolver (unchanged).
+function ownedCandidates(args, candidate, cwd) {
+    return cwd.map((directory) => {
         const resolved = args.resolvePath(candidate, directory);
-        if (resolved === null)
-            continue;
-        const rel = relative(args.root, resolved).split(sep).join("/");
-        if (rel.startsWith(".."))
-            continue;
-        const kind = naxOwnedKind(rel);
-        if (kind !== undefined)
-            return { kind, hit: candidate };
-    }
-    return undefined;
+        const rel = resolved === null ? null : relative(args.root, resolved).split(sep).join("/");
+        return {
+            lexical: realOrRaw(resolve(directory, candidate)),
+            rel: rel === null || rel.startsWith("..") ? null : rel,
+        };
+    });
 }
 export function screenRawBashCommand(args) {
     const { command, tool } = args;
@@ -175,26 +157,31 @@ export function screenRawBashCommand(args) {
             return deny(`\`find ${findStart}\` searches the whole filesystem and runs into the 300s Bash timeout. ` +
                 `Search within the repository root instead: ${args.root}`);
         }
+        // US-002: sandbox-wrapped, a token that only NAMES a PRD is allowed -- the
+        // policy now applies that exemption (`bashRefusal` receives
+        // `sandboxWrapped` and skips the PRD read itself). A redirect WRITES, so
+        // the policy refuses it even sandbox-wrapped, with the read/write truth.
         for (const token of segment.tokens) {
             if (token.opaque)
                 continue;
-            const hit = protectedHit(args, token.text, cwd);
-            // US-002: sandbox-wrapped, a token that only NAMES a PRD is allowed --
-            // the sandbox is the boundary, so a read costs nothing. Config and queue
-            // are unchanged in both modes.
-            if (hit !== undefined && !(sandboxWrapped && hit.kind === "prd")) {
-                return deny(naxOwnedBashRefusal(tool, hit.kind, hit.hit, "names"));
-            }
+            const reason = args.ownedPaths.bashRefusal(tool, token.text, ownedCandidates(args, token.text, cwd), {
+                root: args.root,
+                verb: "names",
+                sandboxWrapped,
+            });
+            if (reason !== undefined)
+                return deny(reason);
         }
         for (const redirect of segment.redirects) {
             if (redirect.opaque)
                 continue;
-            const hit = protectedHit(args, redirect.target, cwd);
-            if (hit !== undefined) {
-                // A redirect WRITES, so even sandbox-wrapped it is refused -- with the
-                // read/write truth for a PRD (US-002), unchanged text elsewhere.
-                return deny(naxOwnedBashRefusal(tool, hit.kind, hit.hit, "redirects into", { sandboxWrapped }));
-            }
+            const reason = args.ownedPaths.bashRefusal(tool, redirect.target, ownedCandidates(args, redirect.target, cwd), {
+                root: args.root,
+                verb: "redirects into",
+                sandboxWrapped,
+            });
+            if (reason !== undefined)
+                return deny(reason);
         }
         // See the file header ("THE CRITICAL ASYMMETRY"). An unmodelled `cd` is
         // never itself a denial -- that inversion from gated mode is deliberate --

package/dist/tools/policy-command-branch.d.ts

@@ -10,6 +10,7 @@
  * reaching `resolveWithin` back would close a cycle.
  */
 import type { BashApprovalMode } from "#src/config/bash-approval";
+import type { OwnedPathsPolicy } from "./owned-paths.ts";
 import type { CompiledEntry } from "./policy-match.ts";
 import type { PolicyVerdict, ToolScope } from "./types.ts";
 export interface BashCommandBranchArgs {
@@ -22,6 +23,8 @@ export interface BashCommandBranchArgs {
     readonly rawBashRefusal?: string;
     /** US-002: true when the sandbox wraps the command, so `raw` no longer refuses a PRD it only reads. */
     readonly sandboxWrapped?: boolean;
+    /** S3-2: host-owned path rules; the `raw` screen hands it one candidate per live frame. */
+    readonly ownedPaths: OwnedPathsPolicy;
     readonly resolvedRoot: string;
     readonly denyBy: ReadonlyMap<string, CompiledEntry>;
     readonly askBy: ReadonlyMap<string, CompiledEntry>;

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

@@ -12,7 +12,7 @@
 import { checkBashCommand } from "./policy-bash.js";
 import { screenRawBashCommand } from "./policy-bash-raw.js";
 export function commandBranch(args) {
-    const { tool, scope, input, grant, bashApproval, rawBashRefusal, sandboxWrapped, resolvedRoot, denyBy, askBy, resolvePath, deny, askVerdict, } = args;
+    const { tool, scope, input, grant, bashApproval, rawBashRefusal, sandboxWrapped, ownedPaths, resolvedRoot, denyBy, askBy, resolvePath, deny, askVerdict, } = args;
     if (scope.commandField === undefined)
         return undefined;
     if (bashApproval === "raw") {
@@ -25,6 +25,7 @@ export function commandBranch(args) {
             root: resolvedRoot,
             sandboxWrapped: sandboxWrapped === true,
             resolvePath,
+            ownedPaths,
         });
         if (screened.kind === "deny")
             return deny(screened.reason, screened.breach, screened.escalatable);

package/dist/tools/policy-paths-branch.d.ts

@@ -21,6 +21,7 @@
  * from it (the collaborators it shares — deny, askVerdict, applyPathRules —
  * arrive by reference in `PathsBranchContext`, read at call time).
  */
+import type { OwnedPathsPolicy } from "./owned-paths.ts";
 import { type CompiledEntry } from "./policy-match.ts";
 import type { PolicyVerdict, ToolScope } from "./types.ts";
 /** Mutable scratch shared by `check()`'s branch helpers: first ask rule matched. */
@@ -38,11 +39,14 @@ export interface PathsBranchContext {
     readonly deny: (reason: string, breach?: boolean, escalatable?: boolean) => PolicyVerdict;
     readonly askVerdict: (resolvedPaths: readonly string[], rule: string) => PolicyVerdict;
     readonly applyPathRules: (tool: string, rel: string, state: RuleState) => PolicyVerdict | undefined;
+    /** The injected OwnedPathsPolicy (S3-2 port); the owned-config refusal reads through it. */
+    readonly ownedPaths: OwnedPathsPolicy;
 }
 /**
  * Absolute, symlink-resolved form of `candidate` if it lies inside `root`,
- * is not itself (and does not lie under) `.git/`, and is not one of nax's own
- * config files.
+ * is not itself (and does not lie under) `.git/`, and is not refused by the
+ * injected OwnedPathsPolicy's `configRefusal` (S3-2 port) -- for nax, one of
+ * nax's own config files.
  *
  * The single containment seam. Multi-root support (a future configurable
  * extension) changes this function and nothing else, which is why every tool
@@ -54,7 +58,9 @@ export interface PathsBranchContext {
  * so containment alone never bars it, and an unconditional ("*") grant --
  * what every non-Exec tool gets under the default `unrestricted` profile --
  * skips glob matching entirely, so nothing downstream of this function would
- * catch it either.
+ * catch it either. The owned-config refusal arrives through the port: nax
+ * injects `naxOwnedPathsPolicy`, an embedder that injects nothing gets
+ * `EMPTY_OWNED_PATHS_POLICY` and only containment plus `.git/` remain.
  *
  * Pre-single-frame, this seam carried one exception: an `execTouchedPaths` set
  * (Task 10) admitted a workspace install's repo-ROOT manifest/lockfile even
@@ -63,7 +69,7 @@ export interface PathsBranchContext {
  * manifest is in-root by construction and that carve-out was retired
  * (PR2/Task 13). There is no exception to this seam now.
  */
-export declare function resolveWithin(root: string, candidate: string): string | null;
+export declare function resolveWithin(root: string, candidate: string, owned: OwnedPathsPolicy): string | null;
 /**
  * Containment runs before any pattern matching and wins over everything.
  * Each resolved path is then evaluated deny -> ask -> allow. A verb-only
@@ -74,14 +80,14 @@ export declare function resolveWithin(root: string, candidate: string): string |
  * `confineTo` (tool-declared, see `ToolScope`) shifts the root passed to
  * `resolveWithin` from `<root>` to `<root>/<confineTo>`: containment stays
  * the one seam, and only its ROOT changes. `relativeTo` keeps rooting at
- * `resolvedRoot` so grant globs, deny rules and `naxOwnedWriteRefusal`
- * continue to see the canonical repo-root-relative spelling -- authors
+ * `resolvedRoot` so grant globs, deny rules and the injected policy's
+ * `writeRefusal` continue to see the canonical repo-root-relative spelling -- authors
  * write `.nax/scratchpad/**`, never `**`, regardless of `confineTo`.
  *
  * `confineTo` is bound to stay INSIDE `resolvedRoot`: an authoring typo of
  * `..` or `../shared` would otherwise widen the containment root past the
- * policy boundary and re-scope `resolveWithin`'s `.git/`-metadata and
- * `isNaxConfigFile` protections to a root that no longer aligns with the
+ * policy boundary and re-scope `resolveWithin`'s `.git/`-metadata and the
+ * port's `configRefusal` protections to a root that no longer aligns with the
  * segments those checks assume -- the repo's own `.nax/config.json` would
  stop being segment-matched against `.nax`. The boundary is the policy
  root's invariant, so an out-of-root confineTo refuses the call outright

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

@@ -23,7 +23,6 @@
  */
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isInside, realOrRaw } from "#src/internal/realpath";
-import { isNaxConfigFile } from "./nax-owned-writes.js";
 import { pathListElements } from "./path-list.js";
 import { pathFieldValue } from "./policy-input.js";
 import { matchesAny } from "./policy-match.js";
@@ -51,8 +50,9 @@ function entersGitMetadata(root, resolved) {
 }
 /**
  * Absolute, symlink-resolved form of `candidate` if it lies inside `root`,
- * is not itself (and does not lie under) `.git/`, and is not one of nax's own
- * config files.
+ * is not itself (and does not lie under) `.git/`, and is not refused by the
+ * injected OwnedPathsPolicy's `configRefusal` (S3-2 port) -- for nax, one of
+ * nax's own config files.
  *
  * The single containment seam. Multi-root support (a future configurable
  * extension) changes this function and nothing else, which is why every tool
@@ -64,7 +64,9 @@ function entersGitMetadata(root, resolved) {
  * so containment alone never bars it, and an unconditional ("*") grant --
  * what every non-Exec tool gets under the default `unrestricted` profile --
  * skips glob matching entirely, so nothing downstream of this function would
- * catch it either.
+ * catch it either. The owned-config refusal arrives through the port: nax
+ * injects `naxOwnedPathsPolicy`, an embedder that injects nothing gets
+ * `EMPTY_OWNED_PATHS_POLICY` and only containment plus `.git/` remain.
  *
  * Pre-single-frame, this seam carried one exception: an `execTouchedPaths` set
  * (Task 10) admitted a workspace install's repo-ROOT manifest/lockfile even
@@ -73,11 +75,11 @@ function entersGitMetadata(root, resolved) {
  * manifest is in-root by construction and that carve-out was retired
  * (PR2/Task 13). There is no exception to this seam now.
  */
-export function resolveWithin(root, candidate) {
+export function resolveWithin(root, candidate, owned) {
     const absolute = isAbsolute(candidate) ? candidate : resolve(root, candidate);
     if (isInside(root, absolute)) {
         const resolved = realOrRaw(absolute);
-        if (entersGitMetadata(root, resolved) || isNaxConfigFile(root, resolved))
+        if (entersGitMetadata(root, resolved) || owned.configRefusal(root, resolved) !== undefined)
             return null;
         return resolved;
     }
@@ -118,14 +120,13 @@ export function resolveWithin(root, candidate) {
  * message is where the agent first sees the absolute containment root -- and
  * naming a path the model itself handed in is the right disclosure.
  */
-function outOfRootReason(root, candidate) {
+function outOfRootReason(root, candidate, owned) {
     const absolute = isAbsolute(candidate) ? candidate : resolve(root, candidate);
-    if (isInside(root, absolute) && isNaxConfigFile(root, realOrRaw(absolute))) {
-        return ("is one of nax's own config files, which every tool is refused regardless of grant -- " +
-            "`quality.commands` and `acceptance.command` are run through a shell WITHOUT passing the " +
-            "permission gate because a human wrote them, so editing this file is a route to running " +
-            "an ungated command on the next run");
-    }
+    // The owned-config refusal (for nax: nax's own config files) comes from the
+    // injected port (S3-2), which supplies the full reason text.
+    const configReason = isInside(root, absolute) ? owned.configRefusal(root, realOrRaw(absolute)) : undefined;
+    if (configReason !== undefined)
+        return configReason;
     if (isInside(root, absolute) && entersGitMetadata(root, realOrRaw(absolute))) {
         return ("targets git metadata under .git/, which every tool is refused regardless of grant -- " +
             "writing there can corrupt the repository beyond git's own recovery, and reading its " +
@@ -168,9 +169,9 @@ function stripConfinePrefix(confinePrefix, value) {
  * fields, `restrictPaths` for array/ref fields — see the module comment).
  */
 function checkPathSegment(frame, candidate, enforceGlobs) {
-    const resolved = resolveWithin(frame.effectiveRoot, stripConfinePrefix(frame.confinePrefix, candidate.path));
+    const resolved = resolveWithin(frame.effectiveRoot, stripConfinePrefix(frame.confinePrefix, candidate.path), frame.ctx.ownedPaths);
     if (resolved === null) {
-        return frame.ctx.deny(`${candidate.denialSubject} ${outOfRootReason(frame.effectiveRoot, candidate.outOfRootTarget)}`, true);
+        return frame.ctx.deny(`${candidate.denialSubject} ${outOfRootReason(frame.effectiveRoot, candidate.outOfRootTarget, frame.ctx.ownedPaths)}`, true);
     }
     const rel = repoRelative(frame.ctx.resolvedRoot, resolved);
     const ruleDenial = frame.ctx.applyPathRules(frame.tool, rel, frame.state);
@@ -269,14 +270,14 @@ function runRefPathFields(frame) {
  * `confineTo` (tool-declared, see `ToolScope`) shifts the root passed to
  * `resolveWithin` from `<root>` to `<root>/<confineTo>`: containment stays
  * the one seam, and only its ROOT changes. `relativeTo` keeps rooting at
- * `resolvedRoot` so grant globs, deny rules and `naxOwnedWriteRefusal`
- * continue to see the canonical repo-root-relative spelling -- authors
+ * `resolvedRoot` so grant globs, deny rules and the injected policy's
+ * `writeRefusal` continue to see the canonical repo-root-relative spelling -- authors
  * write `.nax/scratchpad/**`, never `**`, regardless of `confineTo`.
  *
  * `confineTo` is bound to stay INSIDE `resolvedRoot`: an authoring typo of
  * `..` or `../shared` would otherwise widen the containment root past the
- * policy boundary and re-scope `resolveWithin`'s `.git/`-metadata and
- * `isNaxConfigFile` protections to a root that no longer aligns with the
+ * policy boundary and re-scope `resolveWithin`'s `.git/`-metadata and the
+ * port's `configRefusal` protections to a root that no longer aligns with the
  * segments those checks assume -- the repo's own `.nax/config.json` would
  stop being segment-matched against `.nax`. The boundary is the policy
  root's invariant, so an out-of-root confineTo refuses the call outright

package/dist/tools/policy.d.ts

@@ -14,6 +14,7 @@
  * exception to the boundary is needed.
  */
 import type { BashApprovalMode } from "#src/config/bash-approval";
+import { type OwnedPathsPolicy } from "./owned-paths.ts";
 import { resolveWithin } from "./policy-paths-branch.ts";
 import { type ToolGrant, type ToolPolicy } from "./types.ts";
 /** The single containment seam now lives beside the path branch that drives it. */
@@ -32,16 +33,18 @@ export interface ToolPolicyOptions {
      */
     readonly askRules?: readonly ToolGrant[];
     /**
-     * The ONE nax-owned path this session may write despite `naxOwnedWriteRefusal`
-     * (nax#2115): the ABSOLUTE `fileOutput` path the dispatching op declared. It is
-     * canonicalised into this policy's own root-relative frame below rather than by
-     * the caller, so alternate spellings of the same file cannot diverge from the
-     * string the guard compares. Only the feature-PRD refusal honours it; the nax
-     * CONFIG refusal is deliberately not exempted.
+     * The ONE nax-owned path this session may write despite the port's
+     * `writeRefusal` (nax#2115): the ABSOLUTE `fileOutput` path the dispatching op
+     * declared. It is canonicalised into this policy's own root-relative frame below
+     * rather than by the caller, so alternate spellings of the same file cannot
+     * diverge from the string the guard compares. Only the feature-PRD refusal
+     * honours it; the owned CONFIG refusal is deliberately not exempted.
      */
     readonly ownedWriteExemption?: string;
-    /** nax#2260: `execution.sandbox.filesystem.allowWrite`; a listed top-level `.nax/` entry becomes writable. */
+    /** nax#2260: `execution.sandbox.filesystem.allowWrite`; a listed top-level `.nax/` entry becomes writable through the port's `writeOptIns`. */
     readonly naxAllowWrite?: readonly string[];
+    /** S3-2: host-owned path rules (OwnedPathsPolicy port). Absent: none, the embedder default. */
+    readonly ownedPaths?: OwnedPathsPolicy;
     /**
      * How a bash command string is adjudicated (ADR-030). Absent means `gated` —
      * today's behaviour — so every caller that does not opt in is unchanged.