@nathapp/nax-agent 0.1.0 → 0.3.0

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.

package/dist/tools/policy.js

@@ -16,7 +16,7 @@
 import { relative, resolve, sep } from "node:path";
 import { realOrRaw } from "#src/internal/realpath";
 import { validateArgv } from "./exec-guard.js";
-import { naxOwnedWriteRefusal, naxWriteOptIns } from "./nax-owned-writes.js";
+import { EMPTY_OWNED_PATHS_POLICY } from "./owned-paths.js";
 import { commandBranch } from "./policy-command-branch.js";
 import { compileArgvPattern, compileRuleMap, globToRegExp, matchedArgvSource, matchedGlobSource, matchedRulePatterns, matchesAny, matchesArgvGrant, } from "./policy-match.js";
 import { pathsBranch, resolveWithin } from "./policy-paths-branch.js";
@@ -35,13 +35,14 @@ function isFieldlessScope(scope) {
 }
 export function compileToolPolicy(grants, root, options) {
     const resolvedRoot = realOrRaw(root);
+    const owned = options?.ownedPaths ?? EMPTY_OWNED_PATHS_POLICY;
     // nax#2115: the SAME transform `relativeTo` applies to every checked path, so
     // the guard compares like with like. A path outside the root yields a
     // ".."-prefixed rel that can never equal a checked path's, exempting nothing.
     const ownedWriteExemption = options?.ownedWriteExemption === undefined
         ? undefined
         : relative(resolvedRoot, realOrRaw(options.ownedWriteExemption)).split(sep).join("/");
-    const naxOptIns = naxWriteOptIns(root, options?.naxAllowWrite ?? []);
+    const naxOptIns = owned.writeOptIns(root, options?.naxAllowWrite ?? []);
     const denyBy = compileRuleMap(options?.denyRules);
     const askBy = compileRuleMap(options?.askRules);
     const bashApproval = options?.bashApproval ?? "gated";
@@ -87,9 +88,9 @@ export function compileToolPolicy(grants, root, options) {
      * denied and an ask on an ungranted call never becomes an approval prompt.
      */
     function applyPathRules(tool, rel, state) {
-        const naxOwned = naxOwnedWriteRefusal(tool, rel, ownedWriteExemption, naxOptIns);
-        if (naxOwned !== undefined)
-            return deny(`${tool} may not modify ${naxOwned}`);
+        const ownedRefusal = owned.writeRefusal(tool, rel, { exemptRel: ownedWriteExemption, optIns: naxOptIns });
+        if (ownedRefusal !== undefined)
+            return deny(`${tool} may not modify ${ownedRefusal}`);
         const denyEntry = denyBy.get(tool);
         const askEntry = askBy.get(tool);
         if (denyEntry !== undefined && (denyEntry.unconditional || matchesAny(denyEntry.matchers, rel))) {
@@ -187,7 +188,7 @@ export function compileToolPolicy(grants, root, options) {
      * the nested helpers below stay authoritative, and the sibling reads them at
      * call time — `pathsBranch` itself lives in `./policy-paths-branch`.
      */
-    const pathsBranchContext = { resolvedRoot, deny, askVerdict, applyPathRules };
+    const pathsBranchContext = { resolvedRoot, deny, askVerdict, applyPathRules, ownedPaths: owned };
     return {
         root: resolvedRoot,
         grantedTools() {
@@ -217,10 +218,11 @@ export function compileToolPolicy(grants, root, options) {
                 bashApproval,
                 rawBashRefusal: options?.rawBashRefusal,
                 sandboxWrapped: options?.sandboxWrapped,
+                ownedPaths: owned,
                 resolvedRoot,
                 denyBy,
                 askBy,
-                resolvePath: (candidate, cwd) => resolveWithin(resolvedRoot, resolve(cwd, candidate)),
+                resolvePath: (candidate, cwd) => resolveWithin(resolvedRoot, resolve(cwd, candidate), owned),
                 deny,
                 askVerdict,
             }) ??

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

@@ -9,12 +9,12 @@ export interface ProtectedPathsPolicy {
     readonly gitExcludePathspecs: readonly string[];
     /** Gitignore patterns GitCommit refuses to stage. */
     readonly gitIgnorePatterns: readonly string[];
-    /** Project-relative directory whose top-level entries the sandbox policy lists. */
-    readonly projectStateDir: string;
-    /** Directory whose `credentials*` files the sandbox denies. */
-    readonly credentialDir: string;
-    /** File the sandbox denies writes to: the trust store deciding whether repository code runs. */
-    readonly trustStoreFile: string;
+    /** Project-relative directory whose top-level entries the sandbox policy lists. Absent: the sandbox skips it (S3 spec 6.2). */
+    readonly projectStateDir?: string;
+    /** Directory whose `credentials*` files the sandbox denies. Absent: the sandbox skips it (S3 spec 6.2). */
+    readonly credentialDir?: string;
+    /** File the sandbox denies writes to: the trust store deciding whether repository code runs. Absent: the sandbox skips it (S3 spec 6.2). */
+    readonly trustStoreFile?: string;
 }
 /** The Git tool's default excludes; none when the session carries no policy. */
 export declare function gitExcludePathspecsOf(ctx: {

package/dist/tools/read.js

@@ -22,6 +22,7 @@
  * both.
  */
 import { readPrefix } from "#src/internal/bounded-io";
+import { credentialReadRefusal } from "./credential-read-deny.js";
 import { applyCapCut, limitStopFooter, shouldAppendLimitStopFooter } from "./read-continuation.js";
 import { MODEL_MAX_BYTES, MODEL_MAX_LINES, READ_CEILING, splitModelLines } from "./truncate.js";
 /** Range arguments models invent instead of offset/limit -- rejected by name, never silently dropped. */
@@ -41,6 +42,34 @@ function countLines(prefix) {
     const trimmed = prefix.endsWith("\n") ? prefix.slice(0, -1) : prefix;
     return trimmed.split("\n").length;
 }
+/**
+ * The range half of Read's input: the unsupported-alias rejection (#1923) plus
+ * offset/limit parsing. Extracted from `run` so the credential read-deny adds
+ * no complexity there.
+ */
+function parseRange(input) {
+    const usedAlias = UNSUPPORTED_RANGE_ALIASES.find((alias) => input[alias] !== undefined);
+    if (usedAlias !== undefined) {
+        return {
+            error: `"${usedAlias}" is not a supported Read argument -- use offset (1-based line number) and/or limit (line count) instead`,
+        };
+    }
+    let offset = 1;
+    if (input.offset !== undefined) {
+        const parsed = parsePositiveInt(input.offset, "offset");
+        if (typeof parsed === "string")
+            return { error: parsed };
+        offset = parsed;
+    }
+    let limit;
+    if (input.limit !== undefined) {
+        const parsed = parsePositiveInt(input.limit, "limit");
+        if (typeof parsed === "string")
+            return { error: parsed };
+        limit = parsed;
+    }
+    return { offset, limit };
+}
 export const readTool = {
     name: "Read",
     description: "Read a UTF-8 text file from the repository. Paths are relative to the repository root. " +
@@ -64,15 +93,18 @@ export const readTool = {
         const [target] = ctx.resolvedPaths;
         if (target === undefined)
             return { content: "no path supplied", isError: true };
-        const usedAlias = UNSUPPORTED_RANGE_ALIASES.find((alias) => input[alias] !== undefined);
-        if (usedAlias !== undefined) {
-            return {
-                content: `"${usedAlias}" is not a supported Read argument -- use offset (1-based line number) and/or limit (line count) instead`,
-                isError: true,
-            };
+        // S3 spec 6.3: a workdir may resolve onto the host's credential directory
+        // or trust store; the read tools refuse those regardless of grant.
+        const credential = credentialReadRefusal(ctx.protectedPaths, target);
+        if (credential !== undefined) {
+            return { content: `path "${String(input.path)}" ${credential}`, isError: true };
         }
         const hasOffset = input.offset !== undefined;
         const hasLimit = input.limit !== undefined;
+        const range = parseRange(input);
+        if ("error" in range)
+            return { content: range.error, isError: true };
+        const { offset, limit } = range;
         try {
             if (!hasOffset && !hasLimit) {
                 // Leading [N lines] header so an agent has a way to count the lines it
@@ -106,20 +138,6 @@ export const readTool = {
                 });
                 return { content: result.content };
             }
-            let offset = 1;
-            if (hasOffset) {
-                const parsed = parsePositiveInt(input.offset, "offset");
-                if (typeof parsed === "string")
-                    return { content: parsed, isError: true };
-                offset = parsed;
-            }
-            let limit;
-            if (hasLimit) {
-                const parsed = parsePositiveInt(input.limit, "limit");
-                if (typeof parsed === "string")
-                    return { content: parsed, isError: true };
-                limit = parsed;
-            }
             // Read up to maxFileBytes, not maxBytes: the requested range may start
             // past the display ceiling, and we still need to reach it to slice.
             const body = await readPrefix(target, ctx.maxFileBytes);

package/dist/tools/registry.d.ts

@@ -12,6 +12,7 @@
 import type { CommandInterceptor } from "#src/command-interceptor/index";
 import type { JSONSchema } from "#src/session/tool-descriptor";
 import type { SandboxRecord } from "../sandbox/index.ts";
+import type { OwnedPathsPolicy } from "./owned-paths.ts";
 import type { ProtectedPathsPolicy } from "./protected-paths.ts";
 import type { CodingToolName, ToolScope } from "./types.ts";
 export interface ToolResult {
@@ -96,6 +97,8 @@ export interface ToolRunContext {
     readonly interceptor?: CommandInterceptor;
     /** Host-owned paths (S1 spec port 6). Absent: the Git tools exclude and skip nothing extra. */
     readonly protectedPaths?: ProtectedPathsPolicy;
+    /** Host-owned path rules (S3-2 port). Absent: no owned-path refusals. */
+    readonly ownedPaths?: OwnedPathsPolicy;
 }
 export interface CodingTool {
     readonly name: string;

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

@@ -112,6 +112,7 @@ export async function runExecBranch(input, ctx, opts) {
         packageWorkdir: opts.exec.packageWorkdir,
         packageRelPath,
         allowScripts: opts.exec.allowScripts,
+        ownedPaths: ctx.ownedPaths,
         ...(opts.exec.packageName !== undefined ? { packageName: opts.exec.packageName } : {}),
     });
     if ("error" in normalized)