@nathapp/nax-agent 0.1.0 → 0.3.0

package/dist/session/session-tool-support.d.ts

@@ -0,0 +1,48 @@
+import { type CodingToolSupport } from "#src/coding-tools/coding-tool-support";
+import type { CommandInterceptor } from "#src/command-interceptor/index";
+import type { BashApprovalMode } from "#src/config/bash-approval";
+import type { AskResolver } from "#src/permissions/index";
+import type { CommandLauncher } from "#src/sandbox/index";
+import type { ProtectedPathsPolicy } from "#src/tools/protected-paths";
+import type { CodingToolName, ToolGrant } from "#src/tools/types";
+import type { AgentSessionProfile } from "./agent-session-types.ts";
+/** The pipeline stage the facade's tool calls and asks carry. */
+export declare const SESSION_STAGE = "session";
+export declare function declaredToolsFor(profile: AgentSessionProfile, protectedPaths: ProtectedPathsPolicy): readonly CodingToolName[];
+export declare function grantsFor(declared: readonly CodingToolName[]): readonly ToolGrant[];
+/**
+ * Ask rules evaluate after grants. Under "gated" every Bash command is put to
+ * the person. Under the "ask" profile every mutating path tool is too, and the
+ * profile forces "gated", so Bash always asks there.
+ */
+export declare function askRulesFor(declared: readonly CodingToolName[], bashApproval: BashApprovalMode, profile: AgentSessionProfile): readonly ToolGrant[];
+/**
+ * The embedder default (spec 6.2). A session with its own credentials source
+ * (memory or exec) has no credentials directory on disk; one that falls back
+ * to the configureCredentials slot protects that slot's directory.
+ */
+export declare function defaultProtectedPaths(ownCredentials: boolean): ProtectedPathsPolicy;
+export interface SessionLauncherArgs {
+    readonly profile: AgentSessionProfile;
+    readonly root: string;
+    readonly protectedPaths: ProtectedPathsPolicy;
+    readonly bashApproval: BashApprovalMode;
+    readonly allowUnsandboxed: boolean;
+}
+/** The sandbox floor (spec 6.3): "ask" and "full" need a usable sandbox unless gated + allowUnsandboxed. */
+export declare function resolveSessionLauncher(args: SessionLauncherArgs): Promise<CommandLauncher | undefined>;
+export interface SessionToolSupportArgs {
+    readonly profile: AgentSessionProfile;
+    readonly root: string;
+    readonly sessionName: string;
+    readonly protectedPaths: ProtectedPathsPolicy;
+    readonly bashApproval: BashApprovalMode;
+    readonly launcher: CommandLauncher | undefined;
+    readonly askResolver: AskResolver;
+    readonly interceptor: CommandInterceptor | undefined;
+}
+export interface SessionToolSupport {
+    readonly support: CodingToolSupport;
+    readonly grants: readonly ToolGrant[];
+}
+export declare function buildSessionToolSupport(args: SessionToolSupportArgs): SessionToolSupport;

package/dist/session/session-tool-support.js

@@ -0,0 +1,104 @@
+/**
+ * Profile -> coding tools (spec 4.5, 6.2, 6.3). A profile is a capability
+ * statement; this module turns it into the declared tools and grants that
+ * buildCodingToolSupport takes, picks the embedder default protected-paths
+ * policy, and enforces the sandbox floor for "full".
+ */
+import { resolveSessionSandbox } from "#src/coding-tools/coding-tool-sandbox";
+import { buildCodingToolSupport } from "#src/coding-tools/coding-tool-support";
+import { UNIVERSAL_CODING_TOOLS } from "#src/coding-tools/universal-coding-tools";
+import { DEFAULT_SANDBOX_CONFIG } from "#src/config/schemas-sandbox";
+import { credentialsConfig } from "#src/infra/credentials-config";
+import { EMPTY_OWNED_PATHS_POLICY } from "#src/tools/owned-paths";
+import { AgentSessionError } from "./agent-session-errors.js";
+/** The pipeline stage the facade's tool calls and asks carry. */
+export const SESSION_STAGE = "session";
+const READ_TOOLS = ["Read", "Glob", "Grep", "Git"];
+const WRITE_TOOLS = ["Write", "Edit", "Delete", "Bash"];
+const ASK_PROFILE_TOOLS = ["Write", "Edit", "Delete", "GitCommit"];
+export function declaredToolsFor(profile, protectedPaths) {
+    if (profile === "none")
+        return [...UNIVERSAL_CODING_TOOLS];
+    if (profile === "read")
+        return [...UNIVERSAL_CODING_TOOLS, ...READ_TOOLS];
+    // GitCommit refuses every path without ignore patterns, so it is offered only with them.
+    const commit = protectedPaths.gitIgnorePatterns.length > 0 ? ["GitCommit"] : [];
+    return [...UNIVERSAL_CODING_TOOLS, ...READ_TOOLS, ...WRITE_TOOLS, ...commit];
+}
+export function grantsFor(declared) {
+    return declared.map((tool) => ({ tool, patterns: ["*"] }));
+}
+/**
+ * Ask rules evaluate after grants. Under "gated" every Bash command is put to
+ * the person. Under the "ask" profile every mutating path tool is too, and the
+ * profile forces "gated", so Bash always asks there.
+ */
+export function askRulesFor(declared, bashApproval, profile) {
+    const bash = bashApproval === "gated" && declared.includes("Bash") ? ["Bash"] : [];
+    const mutating = profile === "ask" ? ASK_PROFILE_TOOLS.filter((tool) => declared.includes(tool)) : [];
+    return [...mutating, ...bash].map((tool) => ({ tool, patterns: ["*"] }));
+}
+/** The configured credentials directory; undefined when configureCredentials was never called. */
+function configuredCredentialDir() {
+    try {
+        return credentialsConfig().configDir();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The embedder default (spec 6.2). A session with its own credentials source
+ * (memory or exec) has no credentials directory on disk; one that falls back
+ * to the configureCredentials slot protects that slot's directory.
+ */
+export function defaultProtectedPaths(ownCredentials) {
+    const base = { gitExcludePathspecs: [], gitIgnorePatterns: [] };
+    const credentialDir = ownCredentials ? undefined : configuredCredentialDir();
+    return credentialDir === undefined ? base : { ...base, credentialDir };
+}
+/** The sandbox floor (spec 6.3): "ask" and "full" need a usable sandbox unless gated + allowUnsandboxed. */
+export async function resolveSessionLauncher(args) {
+    if (args.profile !== "full" && args.profile !== "ask")
+        return undefined;
+    const launcher = await resolveSessionSandbox({
+        config: DEFAULT_SANDBOX_CONFIG,
+        root: args.root,
+        needsLauncher: true,
+        protectedPaths: args.protectedPaths,
+        ownedPaths: EMPTY_OWNED_PATHS_POLICY,
+    });
+    if (launcher.state.kind === "available")
+        return launcher;
+    if (args.bashApproval === "gated" && args.allowUnsandboxed)
+        return undefined;
+    const reason = launcher.state.kind === "unavailable" ? launcher.state.reason : "the sandbox is disabled";
+    throw new AgentSessionError(`Profile "${args.profile}" needs a usable sandbox (${reason}). Pass bashApproval "gated" with allowUnsandboxed: true to run without one.`, "AGENT_SESSION_SANDBOX_UNAVAILABLE", { reason });
+}
+export function buildSessionToolSupport(args) {
+    const declared = declaredToolsFor(args.profile, args.protectedPaths);
+    const grants = grantsFor(declared);
+    const askRules = askRulesFor(declared, args.bashApproval, args.profile);
+    const support = buildCodingToolSupport({
+        root: args.root,
+        commandCwd: args.root,
+        pipelineStage: SESSION_STAGE,
+        sessionName: args.sessionName,
+        declared,
+        grants,
+        bashApproval: args.bashApproval,
+        protectedPaths: args.protectedPaths,
+        ownedPaths: EMPTY_OWNED_PATHS_POLICY,
+        askResolver: args.askResolver,
+        ...(askRules.length > 0 ? { askRules } : {}),
+        ...(args.interceptor !== undefined ? { interceptor: args.interceptor } : {}),
+        ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
+    });
+    // Unreachable while the scratchpad trio is always declared and granted; kept for the type.
+    if (support === undefined) {
+        throw new AgentSessionError("No coding tools resolved for the session", "AGENT_SESSION_INVALID_OPTIONS", {
+            profile: args.profile,
+        });
+    }
+    return { support, grants };
+}

package/dist/session/session-types.d.ts

@@ -26,8 +26,8 @@ import type { ToolDescriptor } from "./tool-descriptor.ts";
 export interface AuthStamp {
     /** Keyed credential digest (see `fingerprint.ts`). Not comparable across machines. */
     fingerprint: string;
-    /** Where the credential was read from. */
-    source: "file" | "exec";
+    /** Where the credential was read from: the `file` store, an `exec` helper, or an in-process `memory` store. */
+    source: "file" | "exec" | "memory";
     /** Account label the source reported, when it reports one. */
     account?: string;
 }
@@ -143,6 +143,28 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
      * boundary transcript resumption must respect (nax#1877). ACP ignores it.
      */
     transcriptOwner?: string;
+    /**
+     * Native: where the session's history lives (S3 spec 5.5). Mutually exclusive
+     * with `transcriptDir`, which is shorthand for the file store; exactly one of
+     * the two must be set. nax sets `transcriptDir`. ACP ignores it.
+     */
+    transcriptStore?: import("#src/native/session/transcript-types").TranscriptStore;
+    /**
+     * Native: leave the live transcript in place on close (S3 spec 5.5). By
+     * default a clean close deletes it and a failed close moves it aside; the
+     * facade sets this so the session stays resumable. nax leaves it unset.
+     * Limitation: the file store's prune on a failed close (cap 50, oldest first)
+     * counts every transcript in its directory, live ones included, so a
+     * retained session should not share a file-store directory with sessions
+     * that close failed.
+     */
+    retainOnClose?: boolean;
+    /**
+     * Native: the session's system prompt, sent as the request's top-level
+     * `system` on every round trip (not on the compaction summary). The S3
+     * facade sets it from `instructions`; nax leaves it unset. ACP ignores it.
+     */
+    systemPrompt?: string;
     /**
      * Native: resolved compaction settings. A resolved primitive, never NaxConfig —
      * src/agents/native/ must not read config (check:adapter-no-config-import).
@@ -208,6 +230,13 @@ export interface SendTurnOpts {
      * precisely so tool calls made during the turn can carry it.
      */
     turnId?: string;
+    /**
+     * S3-3: per-turn event sink (deltas, stream_reset, tool calls and results,
+     * per-round usage, compaction). Native honours it; ACP ignores it until S4.
+     * Called synchronously; a throw or rejection is contained by the backend.
+     * nax sets none.
+     */
+    onTurnEvent?: import("./turn-event.ts").TurnEventSink;
 }
 /**
  * A single mid-turn interactive Q&A exchange between the agent and a human
@@ -231,6 +260,8 @@ export interface TurnResult {
     estimatedCostUsd: number;
     /** Exact cost reported by wire protocol (when available). */
     exactCostUsd?: number;
+    /** Absent means computed. */
+    costSource?: import("./agent-session-types.ts").CostSource;
     /** Number of session.prompt() calls made. */
     internalRoundTrips: number;
     /**

package/dist/session/turn-event.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Per-turn events a backend pushes to `SendTurnOpts.onTurnEvent` (S3 spec
+ * 5.3, 5.4). Backend-neutral: the S3 facade adds `sessionId`, `turnId`, `at`
+ * and `metadata` and turns these into its `SessionEvent`s. nax sets no sink.
+ *
+ * - Deltas are provisional. `after_response` handlers may patch the recorded
+ *   text, so the transcript and `TurnResult.output` are authoritative.
+ * - `stream_reset` voids the deltas of `round` so far: the round's request is
+ *   being re-issued (a retry), and `attempt` is the new attempt's 1-based number.
+ * - `usage` is one per round-trip model call and marks the round's end.
+ * - `stream_reset` voids everything since the failed attempt began, including
+ *   any retry backoff; the deltas after it are the new attempt's.
+ * - `usage` excludes the compaction summary call, so a turn's totals come from
+ *   `TurnResult` (`tokenUsage`, `estimatedCostUsd`), not from summing events.
+ * - `tool_call.input` and `tool_result.preview` are redacted BEST-EFFORT (the
+ *   logger's redactor: secret-named keys, known token shapes, KEY=value text)
+ *   and byte-capped. A secret file's text can still appear; treat previews and
+ *   inputs as sensitive. Text and thinking deltas are not redacted.
+ * - Every `tool_call` is followed by exactly one `tool_result`, also when the
+ *   turn throws. A refusal is a non-error result carrying the refusal text.
+ *   Calls the loop answers without running (spin stop, cancel) and `ask_human`
+ *   emit no tool events; they appear only in the transcript.
+ */
+export type TurnEvent = {
+    readonly type: "text_delta";
+    readonly round: number;
+    readonly text: string;
+} | {
+    readonly type: "thinking_delta";
+    readonly round: number;
+    readonly text: string;
+} | {
+    readonly type: "stream_reset";
+    readonly round: number;
+    readonly attempt: number;
+} | {
+    readonly type: "tool_call";
+    readonly callId: string;
+    readonly name: string;
+    readonly input: unknown;
+} | {
+    readonly type: "tool_result";
+    readonly callId: string;
+    readonly isError: boolean;
+    readonly preview: string;
+} | {
+    readonly type: "usage";
+    readonly round: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /** Absent when the call reported no cache data -- never coerced to 0. */
+    readonly cacheRead?: number;
+    /** Absent when the call reported no cache data -- never coerced to 0. */
+    readonly cacheWrite?: number;
+    readonly costUsd: number;
+    /**
+     * Absent means computed from the catalog (the native backend). `unpriced`
+     * rows carry `costUsd: 0` and must not be summed as a real cost.
+     */
+    readonly costSource?: import("./agent-session-types.ts").CostSource;
+} | {
+    readonly type: "compaction";
+    readonly reason: "proactive" | "overflow";
+};
+/** The per-turn sink. Called synchronously; a throw or a rejected promise is contained by the backend. */
+export type TurnEventSink = (event: TurnEvent) => void;

package/dist/session/turn-event.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/ask-request.js

@@ -6,7 +6,7 @@
  * `maskForPrompt` before they leave the process; a secret that cannot be
  * shown safely withholds the arguments entirely (`unshowable`, review #9).
  */
-import { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_TIMEOUT_REASON, ASK_UNSHOWABLE_REASON, maskForPrompt, } from "#src/permissions/index";
+import { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNSHOWABLE_REASON, maskForPrompt, } from "#src/permissions/index";
 /** Ceiling for the one-line call description an AskResolver receives. */
 export const MAX_ASK_SUMMARY_CHARS = 200;
 /**
@@ -53,5 +53,7 @@ export function askDenyReason(decidedBy) {
         return ASK_CANCELLED_REASON;
     if (decidedBy === "unshowable")
         return ASK_UNSHOWABLE_REASON;
+    if (decidedBy === "profile")
+        return ASK_PROFILE_REASON;
     return ASK_NO_CHANNEL_REASON;
 }

package/dist/tools/bash-cwd.d.ts

@@ -8,9 +8,9 @@
  * `<root>/child/secret`), so both screens must track it identically to avoid
  * being fooled by it. This module is the ONE definition of "what does a `cd`
  * segment resolve to, and how do separators fold that into the running set
- * of candidate working directories" -- mirroring `isNaxOwnedWritePath` in
- * `nax-owned-writes.ts`, which is the same one-definition-two-callers shape
- * for a different seam.
+ * of candidate working directories" -- mirroring the `OwnedPathsPolicy` port's
+ * `writeRefusal` (`tools/owned-paths.ts`), which is the same
+ * one-definition-two-callers shape for a different seam.
  *
  * What this module does NOT decide: what happens when a `cd` cannot be
  * modelled (an option-shaped target, an opaque one, one that fails to

package/dist/tools/credential-read-deny.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Read-deny for the host's credential directory and trust-store file in the
+ * read tools (S3 spec 6.3). Before S3-2 only the sandbox enforced these, and
+ * only for Bash; Read, Glob and Grep enforced root containment alone, so a
+ * workdir containing the credential directory exposed it.
+ *
+ * Paths are compared in canonical form: `realpathSync.native` for a path that
+ * exists returns the on-disk casing on a case-insensitive filesystem, where
+ * `realOrRaw` (JS `realpathSync`) keeps the caller's casing and would let
+ * `.NAX/credentials.json` past a `.nax` prefix check. A path that does not
+ * exist cannot be read, so its lexical form is enough.
+ */
+import type { ProtectedPathsPolicy } from "./protected-paths.ts";
+/**
+ * A predicate over resolved paths, with the credential roots canonicalised
+ * once: Glob tests every hit, and a native realpath per root per hit is waste.
+ */
+export declare function credentialPathTest(protectedPaths: ProtectedPathsPolicy | undefined): (resolved: string) => boolean;
+/** Why `resolved` may not be read, or undefined when it may. */
+export declare function credentialReadRefusal(protectedPaths: ProtectedPathsPolicy | undefined, resolved: string): string | undefined;
+/** True when searching `dir` would reach the credential directory or the trust store. */
+export declare function containsCredentialPath(protectedPaths: ProtectedPathsPolicy | undefined, dir: string): boolean;

package/dist/tools/credential-read-deny.js

@@ -0,0 +1,56 @@
+/**
+ * Read-deny for the host's credential directory and trust-store file in the
+ * read tools (S3 spec 6.3). Before S3-2 only the sandbox enforced these, and
+ * only for Bash; Read, Glob and Grep enforced root containment alone, so a
+ * workdir containing the credential directory exposed it.
+ *
+ * Paths are compared in canonical form: `realpathSync.native` for a path that
+ * exists returns the on-disk casing on a case-insensitive filesystem, where
+ * `realOrRaw` (JS `realpathSync`) keeps the caller's casing and would let
+ * `.NAX/credentials.json` past a `.nax` prefix check. A path that does not
+ * exist cannot be read, so its lexical form is enough.
+ */
+import { realpathSync } from "node:fs";
+import { sep } from "node:path";
+import { realOrRaw } from "#src/internal/realpath";
+function canonical(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return realOrRaw(p);
+    }
+}
+function isWithin(base, target) {
+    return target === base || target.startsWith(`${base}${sep}`);
+}
+function credentialRoots(protectedPaths) {
+    if (protectedPaths === undefined)
+        return [];
+    return [protectedPaths.credentialDir, protectedPaths.trustStoreFile]
+        .filter((p) => p !== undefined)
+        .map(canonical);
+}
+const CREDENTIAL_REFUSAL = "is a host credential or trust-store path, which the read tools are refused regardless of grant";
+/**
+ * A predicate over resolved paths, with the credential roots canonicalised
+ * once: Glob tests every hit, and a native realpath per root per hit is waste.
+ */
+export function credentialPathTest(protectedPaths) {
+    const roots = credentialRoots(protectedPaths);
+    if (roots.length === 0)
+        return () => false;
+    return (resolved) => {
+        const target = canonical(resolved);
+        return roots.some((base) => isWithin(base, target));
+    };
+}
+/** Why `resolved` may not be read, or undefined when it may. */
+export function credentialReadRefusal(protectedPaths, resolved) {
+    return credentialPathTest(protectedPaths)(resolved) ? CREDENTIAL_REFUSAL : undefined;
+}
+/** True when searching `dir` would reach the credential directory or the trust store. */
+export function containsCredentialPath(protectedPaths, dir) {
+    const base = canonical(dir);
+    return credentialRoots(protectedPaths).some((cred) => isWithin(base, cred));
+}

package/dist/tools/glob.js

@@ -14,8 +14,10 @@
  * `<dir>/ <b1> <b2> ...`, unescaping each quoted basename, and joining each
  * basename to its directory reconstructs the matched set exactly.
  */
-import { sep } from "node:path";
+import { join, sep } from "node:path";
 import { getAgentRuntime } from "#src/runtime/index";
+import { credentialPathTest } from "./credential-read-deny.js";
+import { EMPTY_OWNED_PATHS_POLICY } from "./owned-paths.js";
 import { resolveWithin } from "./policy.js";
 const MAX_MATCHES = 500;
 /**
@@ -127,6 +129,9 @@ export const globTool = {
         if (climbsOut(pattern))
             return { content: "no matches" };
         const matches = [];
+        // S3 spec 6.3: credential roots are canonicalised once; a native realpath
+        // per hit would be waste when a listing covers the credential directory.
+        const isCredential = credentialPathTest(ctx.protectedPaths);
         try {
             // `absolute: false` is the repo-wide idiom (test-scanner.ts:318,
             // fragments/store.ts:53, manifest-purge.ts:64) and yields root-relative
@@ -136,7 +141,9 @@ export const globTool = {
             // a throwing iterator and exercise the catch branch without planting a
             // malformed pattern on disk.
             for await (const hit of _globDeps.scan(pattern, { cwd: ctx.root, absolute: false })) {
-                if (resolveWithin(ctx.root, hit) === null)
+                if (resolveWithin(ctx.root, hit, ctx.ownedPaths ?? EMPTY_OWNED_PATHS_POLICY) === null)
+                    continue;
+                if (isCredential(join(ctx.root, hit)))
                     continue;
                 matches.push(hit.split(sep).join("/"));
                 if (matches.length >= MAX_MATCHES)

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`