@nathapp/nax-agent 0.1.0

package/dist/tools/policy.js

@@ -0,0 +1,232 @@
+/**
+ * Compile declarative grants into a policy, and answer one call at a time.
+ *
+ * nax-permission-mode-allow: applies grants resolved by resolvePermissions;
+ * decides no permission of its own.
+ *
+ * Containment runs BEFORE pattern matching and is not expressible in config:
+ * the root is a boundary no PROFILE can widen. `unrestricted` means "any
+ * tool, any path within the root", never "any path on the machine".
+ *
+ * The `execTouchedPaths` carve-out (Task 10) was retired in the single-frame
+ * root move (PR2/Task 13): the containment root became the repo root, so a
+ * workspace install's root manifest is in-root by construction and no
+ * exception to the boundary is needed.
+ */
+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 { 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";
+import { EXEC_TOOL_NAME } from "./types.js";
+import { argvShellHint } from "./verb-denial-argv-hint.js";
+/** The single containment seam now lives beside the path branch that drives it. */
+export { resolveWithin };
+function isFieldlessScope(scope) {
+    return (scope.argvField === undefined &&
+        scope.commandField === undefined &&
+        scope.verbField === undefined &&
+        scope.pathFields.length === 0 &&
+        (scope.listPathFields?.length ?? 0) === 0 &&
+        (scope.arrayPathFields?.length ?? 0) === 0 &&
+        (scope.refPathFields?.length ?? 0) === 0);
+}
+export function compileToolPolicy(grants, root, options) {
+    const resolvedRoot = realOrRaw(root);
+    // 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 denyBy = compileRuleMap(options?.denyRules);
+    const askBy = compileRuleMap(options?.askRules);
+    const bashApproval = options?.bashApproval ?? "gated";
+    const compiled = new Map();
+    for (const grant of grants) {
+        const unconditional = grant.patterns.includes("*");
+        const nonWildcard = grant.patterns.filter((p) => p !== "*");
+        compiled.set(grant.tool, {
+            unconditional,
+            matchers: nonWildcard.map((source) => ({ source, re: globToRegExp(source) })),
+            argvPatterns: nonWildcard.map((source) => compileArgvPattern(source)),
+            raw: grant.patterns,
+        });
+    }
+    function deny(reason, breach = false, escalatable = false) {
+        return { allowed: false, reason, breach, escalatable, outcome: "denied" };
+    }
+    /**
+     * `allowed: false` on purpose: any consumer that only reads `allowed` fails
+     * closed. `outcome: "ask"` is the sole signal that an AskResolver may approve
+     * this call, and `resolvedPaths` is what an approval would admit.
+     */
+    function askVerdict(resolvedPaths, rule) {
+        return {
+            allowed: false,
+            reason: `matched ask rule "${rule}" — requires approval before it may run`,
+            breach: false,
+            outcome: "ask",
+            resolvedPaths,
+            rule,
+        };
+    }
+    /** `Tool` for an unconditional entry, else `Tool(pattern, ...)`. */
+    function ruleExpr(tool, entry, source) {
+        const patterns = source === undefined ? entry.raw : matchedRulePatterns(entry, source);
+        return patterns.includes("*") ? tool : `${tool}(${patterns.join(", ")})`;
+    }
+    /**
+     * Deny (spec R6) outranks ask, and both are evaluated per resolved path.
+     * Returns a denial verdict when a deny glob matches; otherwise records the
+     * matching ask source on `state` and returns undefined. Ask never grants on
+     * its own: the caller's allow checks still run, so an ungranted path stays
+     * 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 denyEntry = denyBy.get(tool);
+        const askEntry = askBy.get(tool);
+        if (denyEntry !== undefined && (denyEntry.unconditional || matchesAny(denyEntry.matchers, rel))) {
+            return deny(`${tool} path "${rel}" is denied for this stage`);
+        }
+        if (askEntry !== undefined && (askEntry.unconditional || matchesAny(askEntry.matchers, rel))) {
+            state.ask = ruleExpr(tool, askEntry, askEntry.unconditional ? "*" : matchedGlobSource(askEntry.matchers, rel));
+        }
+        return undefined;
+    }
+    /**
+     * RunCommand's `Exec` branch, checked entirely here and never falling through
+     * to verbField/pathFields: there is no "command" field on this shape for
+     * verbField to read. `validateArgv` runs FIRST -- before this grant's patterns
+     * are even consulted -- so a malformed token can never be admitted by a `*`
+     * grant that would otherwise wave anything through unchecked. Returns
+     * undefined when this is not an argv call, so the caller tries the next branch.
+     */
+    function argvBranch(tool, scope, input, grant) {
+        if (scope.argvField === undefined)
+            return undefined;
+        const rawArgv = input[scope.argvField];
+        if (rawArgv === undefined)
+            return undefined;
+        const invalid = validateArgv(rawArgv);
+        if (invalid !== undefined)
+            return deny(invalid);
+        const argv = rawArgv;
+        const denyEntry = denyBy.get(tool);
+        if (denyEntry !== undefined && (denyEntry.unconditional || matchesArgvGrant(denyEntry.argvPatterns, argv))) {
+            return deny(`${tool} is denied for argv "${argv.join(" ")}" for this stage`);
+        }
+        if (!grant.unconditional && !matchesArgvGrant(grant.argvPatterns, argv)) {
+            // Name the granted forms, not just the refusal. A bare "no" is what
+            // produced the defect this branch exists to fix: denied with no legal
+            // alternative named, the model deleted the requirement instead of
+            // installing it. An unconditional grant never enters this branch (see
+            // the guard above), so `raw` cannot contain the bare "*" element --
+            // entries *containing* "*" (`bun add*`) are exactly what we want to name.
+            const granted = grant.raw.join(", ");
+            const alternatives = granted === "" ? "no argv forms are granted for this stage" : `granted forms: ${granted}`;
+            return deny(`${tool} is not granted for argv "${argv.join(" ")}" -- ${alternatives}`);
+        }
+        const askEntry = askBy.get(tool);
+        if (askEntry !== undefined && (askEntry.unconditional || matchesArgvGrant(askEntry.argvPatterns, argv))) {
+            return askVerdict([], ruleExpr(tool, askEntry, askEntry.unconditional ? "*" : matchedArgvSource(askEntry, argv)));
+        }
+        return { allowed: true, resolvedPaths: [] };
+    }
+    /**
+     * Verb gating: the tool's own allowedVerbs bound what config can grant, so a
+     * "*" grant can never reach a mutating subcommand. A deny/ask rule names a
+     * verb directly here -- unlike the allow path (`pathMatchers`), these are not
+     * filtered through `allowedVerbs`, so a deny for a verb the tool does not even
+     * allow still reads as the rule's denial, not a generic "not a permitted
+     * subcommand". Returns undefined once the gate passes (or is absent), so the
+     * caller can check paths next.
+     */
+    function verbBranch(tool, scope, input, grant, state) {
+        if (scope.verbField === undefined)
+            return undefined;
+        const verb = input[scope.verbField];
+        if (typeof verb !== "string")
+            return deny(`"${scope.verbField}" must be a string`);
+        const denyEntry = denyBy.get(tool);
+        if (denyEntry !== undefined && (denyEntry.unconditional || denyEntry.raw.includes(verb))) {
+            return deny(`${tool} is denied the "${verb}" subcommand for this stage`);
+        }
+        // Name what the stage can actually use, not merely what the tool allows
+        // (nax#1971). `allowedVerbs` alone would advertise a verb a narrower grant
+        // refuses one line below -- sending the model straight back into a denial,
+        // which is the defect #1937 exists to fix.
+        const usableVerbs = scope.allowedVerbs === undefined
+            ? []
+            : grant.unconditional
+                ? [...scope.allowedVerbs]
+                : scope.allowedVerbs.filter((v) => grant.raw.includes(v));
+        const permitted = usableVerbs.length === 0 ? "no subcommands are permitted for this stage" : `permitted: ${usableVerbs.join(", ")}`;
+        // See verb-denial-argv-hint.ts (run-2026-09-14T05-55-54-734Z, Shape B).
+        const argvHint = argvShellHint(scope.verbField, scope.argvField, compiled.get(EXEC_TOOL_NAME)?.raw ?? []);
+        if (scope.allowedVerbs !== undefined && !scope.allowedVerbs.includes(verb)) {
+            return deny(`"${verb}" is not a permitted ${tool} subcommand -- ${permitted}${argvHint}`);
+        }
+        if (!grant.unconditional && !grant.raw.includes(verb)) {
+            return deny(`${tool} is not granted the "${verb}" subcommand for this stage -- ${permitted}`);
+        }
+        const askEntry = askBy.get(tool);
+        if (askEntry !== undefined && (askEntry.unconditional || askEntry.raw.includes(verb))) {
+            state.ask = ruleExpr(tool, askEntry, askEntry.unconditional ? "*" : verb);
+        }
+        return undefined;
+    }
+    /**
+     * The path branch's collaborators, by reference (see `PathsBranchContext`):
+     * 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 };
+    return {
+        root: resolvedRoot,
+        grantedTools() {
+            // A tool with an UNCONDITIONAL deny never reaches a caller; a scoped
+            // (pattern) deny leaves it advertised, because some calls still pass.
+            return [...compiled.keys()].filter((t) => denyBy.get(t)?.unconditional !== true);
+        },
+        check(tool, scope, input) {
+            const grant = compiled.get(tool);
+            if (grant === undefined)
+                return deny(`tool "${tool}" is not permitted for this stage`);
+            // Unconditional deny is final and outranks every other gate.
+            const denyEntry = denyBy.get(tool);
+            if (denyEntry?.unconditional === true) {
+                return deny(`tool "${tool}" is denied for this stage by rule ${ruleExpr(tool, denyEntry)}`);
+            }
+            const askEntry = askBy.get(tool);
+            if (askEntry?.unconditional === true && isFieldlessScope(scope)) {
+                return askVerdict([], ruleExpr(tool, askEntry));
+            }
+            const state = {};
+            return (commandBranch({
+                tool,
+                scope,
+                input,
+                grant,
+                bashApproval,
+                rawBashRefusal: options?.rawBashRefusal,
+                sandboxWrapped: options?.sandboxWrapped,
+                resolvedRoot,
+                denyBy,
+                askBy,
+                resolvePath: (candidate, cwd) => resolveWithin(resolvedRoot, resolve(cwd, candidate)),
+                deny,
+                askVerdict,
+            }) ??
+                argvBranch(tool, scope, input, grant) ??
+                verbBranch(tool, scope, input, grant, state) ??
+                pathsBranch({ ctx: pathsBranchContext, tool, scope, input, grant, state }));
+        },
+    };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Paths the HOST owns, which the coding tools and the sandbox must keep the
+ * agent away from (S1 spec section 4.2, port 6). Data only: nax builds it
+ * from its own path definitions (`naxProtectedPaths`) once per dispatch; an
+ * embedder supplies its own.
+ */
+export interface ProtectedPathsPolicy {
+    /** Long-form pathspecs the Git tool appends to its default (no-path) view (nax#2007). */
+    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;
+}
+/** The Git tool's default excludes; none when the session carries no policy. */
+export declare function gitExcludePathspecsOf(ctx: {
+    readonly protectedPaths?: ProtectedPathsPolicy;
+}): readonly string[];
+/** GitCommit's ignore patterns; none when the session carries no policy. */
+export declare function gitIgnorePatternsOf(ctx: {
+    readonly protectedPaths?: ProtectedPathsPolicy;
+}): readonly string[];

package/dist/tools/protected-paths.js

@@ -0,0 +1,8 @@
+/** The Git tool's default excludes; none when the session carries no policy. */
+export function gitExcludePathspecsOf(ctx) {
+    return ctx.protectedPaths?.gitExcludePathspecs ?? [];
+}
+/** GitCommit's ignore patterns; none when the session carries no policy. */
+export function gitIgnorePatternsOf(ctx) {
+    return ctx.protectedPaths?.gitIgnorePatterns ?? [];
+}

package/dist/tools/provider-adapt.d.ts

@@ -0,0 +1,4 @@
+import type { ProviderTool } from "./provider-types.ts";
+import type { CodingTool } from "./registry.ts";
+export declare function namespacedToolName(providerId: string, localName: string): string;
+export declare function adaptProviderTool(providerId: string, tool: ProviderTool): CodingTool;

package/dist/tools/provider-adapt.js

@@ -0,0 +1,32 @@
+/**
+ * Namespacing and adaptation of provider tools into plain CodingTools.
+ *
+ * The namespaced name is NEVER parsed back apart. That is what lets a local
+ * name contain `__` without escaping, and it is why the ledger carries an
+ * explicit `provider` field rather than expecting a consumer to string-split.
+ */
+import { NaxError } from "#src/infra/index";
+import { validateProviderId } from "./provider-types.js";
+import { RESERVED_TOOL_NAMES } from "./registry.js";
+export function namespacedToolName(providerId, localName) {
+    validateProviderId(providerId);
+    if (localName.length === 0) {
+        throw new NaxError(`provider ${providerId} advertised a tool with an empty name`, "PROVIDER_TOOL_NAME_EMPTY");
+    }
+    const name = `${providerId}__${localName}`;
+    if (RESERVED_TOOL_NAMES.includes(name)) {
+        throw new NaxError(`provider tool ${name} collides with a built-in`, "PROVIDER_TOOL_NAME_RESERVED");
+    }
+    return name;
+}
+export function adaptProviderTool(providerId, tool) {
+    return {
+        name: namespacedToolName(providerId, tool.localName),
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        // No path fields and no verb field: the grant lookup is the whole gate,
+        // which is the honest expression for a tool whose arguments are not paths.
+        scope: { pathFields: [] },
+        run: (input, ctx) => tool.run(input, ctx),
+    };
+}

package/dist/tools/provider-advertise.d.ts

@@ -0,0 +1,39 @@
+import { type ProviderGrantEntry } from "./provider-grants.ts";
+import { type ToolProvider } from "./provider-types.ts";
+import type { CodingTool } from "./registry.ts";
+import type { ToolGrant } from "./types.ts";
+export interface ResolvedProviderTools {
+    readonly tools: readonly CodingTool[];
+    readonly grants: readonly ToolGrant[];
+    readonly failures: readonly {
+        providerId: string;
+        reason: string;
+    }[];
+    /**
+     * Advertised tool name -> owning provider id, carried explicitly so the
+     * ledger never has to parse the `<id>__<local>` name apart (a naming
+     * convention change would otherwise break telemetry silently).
+     */
+    readonly providerIdByTool: ReadonlyMap<string, string>;
+    /**
+     * (providerId, localNames) pairs for the tools that survived sanitisation,
+     * the lock and `allowedTools`. Exposed because `Mcp(server:tool)` rules must
+     * be matched against the LOCAL name, and `<id>__<local>` is never parsed
+     * back apart (src/tools/provider-adapt.ts's header).
+     */
+    readonly entries: readonly ProviderGrantEntry[];
+}
+export declare function resolveProviderTools(providers: readonly ToolProvider[], stage: string, workdir: string, options?: {
+    /**
+     * Narrows which discovered tools are advertised at all. Applied HERE, not
+     * after the fact: a tool a scoped stage did not admit must never be
+     * adapted, advertised or granted (spec US-006).
+     */
+    readonly admits?: (providerId: string, localName: string) => boolean;
+}): Promise<ResolvedProviderTools>;
+/**
+ * Bytes a tool list costs the prompt, paid on EVERY hop whether or not any
+ * tool is called. This is the per-hop tax that appears in no ledger today and
+ * which nax#1991's context-burn report needs.
+ */
+export declare function advertisedSchemaBytes(tools: readonly CodingTool[]): number;

package/dist/tools/provider-advertise.js

@@ -0,0 +1,50 @@
+/**
+ * Per-hop resolution of provider tools.
+ *
+ * A provider whose `tools()` rejects is DROPPED, not fatal: a broken provider
+ * must never wedge a run. The failure is logged by the caller, which owns the
+ * logger; this module stays pure so it can be tested without one.
+ */
+import { adaptProviderTool } from "./provider-adapt.js";
+import { expandProviderGrants } from "./provider-grants.js";
+import { sanitizeProviderTools } from "./provider-sanitize.js";
+import { providerAttachesTo } from "./provider-types.js";
+export async function resolveProviderTools(providers, stage, workdir, options) {
+    const tools = [];
+    const entries = [];
+    const failures = [];
+    const providerIdByTool = new Map();
+    for (const provider of providers) {
+        if (!providerAttachesTo(provider, stage))
+            continue;
+        try {
+            const sanitized = sanitizeProviderTools(provider.kind, await provider.tools(workdir));
+            const localNames = [];
+            for (const tool of sanitized) {
+                if (options?.admits !== undefined && !options.admits(provider.id, tool.localName))
+                    continue;
+                const adapted = adaptProviderTool(provider.id, tool);
+                tools.push(adapted);
+                providerIdByTool.set(adapted.name, provider.id);
+                localNames.push(tool.localName);
+            }
+            entries.push({ providerId: provider.id, localNames });
+        }
+        catch (error) {
+            failures.push({ providerId: provider.id, reason: String(error) });
+        }
+    }
+    return { tools, grants: expandProviderGrants(entries), failures, providerIdByTool, entries };
+}
+/**
+ * Bytes a tool list costs the prompt, paid on EVERY hop whether or not any
+ * tool is called. This is the per-hop tax that appears in no ledger today and
+ * which nax#1991's context-burn report needs.
+ */
+export function advertisedSchemaBytes(tools) {
+    let total = 0;
+    for (const tool of tools) {
+        total += Buffer.byteLength(tool.description, "utf8") + Buffer.byteLength(JSON.stringify(tool.inputSchema), "utf8");
+    }
+    return total;
+}

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

@@ -0,0 +1,36 @@
+import type { ToolGrant } from "./types.ts";
+export interface ProviderGrantEntry {
+    readonly providerId: string;
+    readonly localNames: readonly string[];
+}
+export declare function expandProviderGrants(entries: readonly ProviderGrantEntry[]): readonly ToolGrant[];
+/**
+ * The pseudo-tool name `Mcp(...)` parses to. SURFACE SYNTAX ONLY: it must be
+ * partitioned out and expanded before compilation (see this file's header).
+ */
+export declare const MCP_RULE_TOOL = "Mcp";
+/**
+ * Split `Mcp(...)` rules out of a parsed rule list.
+ *
+ * Patterns MERGE across entries rather than overwriting, unlike the allow
+ * compiler's per-tool last-write-wins: two `Mcp(...)` expressions in one list
+ * are two servers a human named, and dropping the earlier one would silently
+ * withdraw a grant that is written in the config.
+ */
+export declare function partitionMcpRules(grants: readonly ToolGrant[]): {
+    readonly grants: readonly ToolGrant[];
+    readonly mcpPatterns: readonly string[];
+};
+/** Does an `Mcp` pattern list admit `<providerId>__<localName>`?
+ * `*` = every server; `server` = every tool of that server; `server:tool` =
+ * one tool; `server:*` = every tool of that server, written explicitly. */
+export declare function mcpRuleAdmits(patterns: readonly string[], providerId: string, localName: string): boolean;
+/**
+ * Expand `Mcp` patterns against the tools a provider actually advertised.
+ *
+ * Keyed on the post-lock, post-`allowedTools` list the caller passes in, so a
+ * rule can only ever narrow what the provider layer already admitted — and the
+ * result is concrete `<id>__<tool>` grants, which is the only shape
+ * `compileToolPolicy` can key on.
+ */
+export declare function expandMcpRuleGrants(patterns: readonly string[], entries: readonly ProviderGrantEntry[]): readonly ToolGrant[];

package/dist/tools/provider-grants.js

@@ -0,0 +1,72 @@
+/**
+ * Expansion of provider grants into the only shape the policy can use.
+ *
+ * `compileToolPolicy` keys grants by exact tool name, and `advertised()` tests
+ * `granted.has(<namespaced name>)`. Any grant-expression sugar a consuming
+ * feature defines — `Mcp(server)`, `Mcp(server:tool)` — is SURFACE SYNTAX FOR
+ * HUMANS and must be expanded here before compilation. A grant that survives in
+ * parsed form compiles to the key `"Mcp"`, matches no advertised name, and
+ * denies every call while every parser unit test still passes.
+ */
+import { namespacedToolName } from "./provider-adapt.js";
+export function expandProviderGrants(entries) {
+    const grants = [];
+    for (const entry of entries) {
+        for (const localName of entry.localNames) {
+            grants.push({ tool: namespacedToolName(entry.providerId, localName), patterns: ["*"] });
+        }
+    }
+    return grants;
+}
+/**
+ * The pseudo-tool name `Mcp(...)` parses to. SURFACE SYNTAX ONLY: it must be
+ * partitioned out and expanded before compilation (see this file's header).
+ */
+export const MCP_RULE_TOOL = "Mcp";
+/**
+ * Split `Mcp(...)` rules out of a parsed rule list.
+ *
+ * Patterns MERGE across entries rather than overwriting, unlike the allow
+ * compiler's per-tool last-write-wins: two `Mcp(...)` expressions in one list
+ * are two servers a human named, and dropping the earlier one would silently
+ * withdraw a grant that is written in the config.
+ */
+export function partitionMcpRules(grants) {
+    const kept = [];
+    const mcpPatterns = [];
+    for (const grant of grants) {
+        if (grant.tool === MCP_RULE_TOOL)
+            mcpPatterns.push(...grant.patterns);
+        else
+            kept.push(grant);
+    }
+    return { grants: kept, mcpPatterns };
+}
+/** Does an `Mcp` pattern list admit `<providerId>__<localName>`?
+ * `*` = every server; `server` = every tool of that server; `server:tool` =
+ * one tool; `server:*` = every tool of that server, written explicitly. */
+export function mcpRuleAdmits(patterns, providerId, localName) {
+    return patterns.some((pattern) => {
+        if (pattern === "*")
+            return true;
+        const colon = pattern.indexOf(":");
+        if (colon === -1)
+            return pattern === providerId;
+        return pattern.slice(0, colon) === providerId && ["*", localName].includes(pattern.slice(colon + 1));
+    });
+}
+/**
+ * Expand `Mcp` patterns against the tools a provider actually advertised.
+ *
+ * Keyed on the post-lock, post-`allowedTools` list the caller passes in, so a
+ * rule can only ever narrow what the provider layer already admitted — and the
+ * result is concrete `<id>__<tool>` grants, which is the only shape
+ * `compileToolPolicy` can key on.
+ */
+export function expandMcpRuleGrants(patterns, entries) {
+    const admitted = entries.map((entry) => ({
+        providerId: entry.providerId,
+        localNames: entry.localNames.filter((localName) => mcpRuleAdmits(patterns, entry.providerId, localName)),
+    }));
+    return expandProviderGrants(admitted.filter((entry) => entry.localNames.length > 0));
+}

package/dist/tools/provider-sanitize.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bounds on what a `discovered` provider may put into the model's tool list.
+ *
+ * A discovered tool's description and schema come from an external process and
+ * go straight into the prompt, which makes the description a prompt-injection
+ * surface and the schema a per-hop context tax paid whether or not the tool is
+ * ever called. A `static` provider's schema is authored in this repo, so
+ * sanitising it would be theatre — hence the kind check rather than a blanket
+ * pass.
+ *
+ * Truncate rather than drop: an over-long description degrades into a shorter
+ * one, where dropping would remove a working tool over a cosmetic problem. A
+ * malformed or oversized SCHEMA is different — it cannot be safely truncated,
+ * so that one tool is skipped and its siblings survive.
+ */
+import type { ProviderKind, ProviderTool } from "./provider-types.ts";
+export declare const MAX_PROVIDER_DESCRIPTION_BYTES = 2000;
+export declare const MAX_PROVIDER_SCHEMA_BYTES = 20000;
+export declare function sanitizeProviderTools(kind: ProviderKind, tools: readonly ProviderTool[]): readonly ProviderTool[];

package/dist/tools/provider-sanitize.js

@@ -0,0 +1,53 @@
+export const MAX_PROVIDER_DESCRIPTION_BYTES = 2_000;
+export const MAX_PROVIDER_SCHEMA_BYTES = 20_000;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control bytes is the point of this function
+const CONTROL_CHARS = /[\u0000-\u001F\u007F]/g;
+function strip(value) {
+    return value.replace(CONTROL_CHARS, "");
+}
+/**
+ * Truncate to a byte ceiling without splitting a code point.
+ *
+ * `String.prototype.slice` counts UTF-16 code units, so a multi-byte code point
+ * straddling the boundary is cut in half and becomes a replacement character.
+ * Iterating code points and stopping at the ceiling keeps the result valid.
+ */
+function truncateToBytes(value, maxBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
+        return value;
+    let out = "";
+    let bytes = 0;
+    for (const char of value) {
+        const charBytes = Buffer.byteLength(char, "utf8");
+        if (bytes + charBytes > maxBytes)
+            break;
+        out += char;
+        bytes += charBytes;
+    }
+    return out;
+}
+export function sanitizeProviderTools(kind, tools) {
+    if (kind === "static")
+        return tools;
+    const out = [];
+    let schemaBytes = 0;
+    for (const tool of tools) {
+        const schema = tool.inputSchema;
+        if (typeof schema !== "object" || schema === null || Array.isArray(schema))
+            continue;
+        // US-005 caps the TOTAL schema bytes one provider may put into the prompt,
+        // not just each schema: many small tools still add up to an unbounded hop
+        // tax. A single oversized schema fails the same test with a zero running
+        // total, which preserves the per-tool skip this file already had.
+        const toolBytes = Buffer.byteLength(JSON.stringify(schema), "utf8");
+        if (schemaBytes + toolBytes > MAX_PROVIDER_SCHEMA_BYTES)
+            continue;
+        schemaBytes += toolBytes;
+        out.push({
+            ...tool,
+            localName: strip(tool.localName),
+            description: truncateToBytes(strip(tool.description), MAX_PROVIDER_DESCRIPTION_BYTES),
+        });
+    }
+    return out;
+}

package/dist/tools/provider-types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Vocabulary for tools supplied by a provider rather than compiled into
+ * `CodingToolName`.
+ *
+ * Providers split by ONE axis that matters: who authored the tool's schema.
+ * A `static` provider's schema is written in this repo and reviewed in this
+ * repo's PRs, making it exactly as trustworthy as Read's. A `discovered`
+ * provider's schema arrives from an external process at runtime, which makes
+ * its description a prompt-injection surface and its schema an unbounded
+ * context cost. Sanitisation and pinning attach to the KIND, so a trusted
+ * provider never inherits ceremony it does not need.
+ */
+import type { JSONSchema } from "#src/session/tool-descriptor";
+import type { ToolResult, ToolRunContext } from "./registry.ts";
+export type ProviderKind = "static" | "discovered";
+export interface ProviderTool {
+    /** Unqualified, as the provider knows it. Namespaced by `provider-adapt`. */
+    readonly localName: string;
+    readonly description: string;
+    readonly inputSchema: JSONSchema;
+    run(input: Record<string, unknown>, ctx: ToolRunContext): Promise<ToolResult>;
+}
+export interface ToolProvider {
+    readonly id: string;
+    readonly kind: ProviderKind;
+    /** Stage names this provider attaches to, or "*" for every stage. */
+    readonly stages: readonly string[];
+    /**
+     * `workdir` is the HOP'S PERMITTED ROOT, never the runtime's workdir. A
+     * provider may legitimately expose different tools per working root, and a
+     * run executes stories in parallel worktrees.
+     */
+    tools(workdir: string): Promise<readonly ProviderTool[]>;
+}
+/**
+ * No `__`: that sequence is the namespace separator, and an id containing it
+ * would make `<id>__<local>` ambiguous to a human reading a ledger row.
+ */
+export declare const PROVIDER_ID_RE: RegExp;
+export declare function validateProviderId(id: string): void;
+export declare function providerAttachesTo(provider: Pick<ToolProvider, "stages">, stage: string): boolean;

package/dist/tools/provider-types.js

@@ -0,0 +1,26 @@
+/**
+ * Vocabulary for tools supplied by a provider rather than compiled into
+ * `CodingToolName`.
+ *
+ * Providers split by ONE axis that matters: who authored the tool's schema.
+ * A `static` provider's schema is written in this repo and reviewed in this
+ * repo's PRs, making it exactly as trustworthy as Read's. A `discovered`
+ * provider's schema arrives from an external process at runtime, which makes
+ * its description a prompt-injection surface and its schema an unbounded
+ * context cost. Sanitisation and pinning attach to the KIND, so a trusted
+ * provider never inherits ceremony it does not need.
+ */
+import { NaxError } from "#src/infra/index";
+/**
+ * No `__`: that sequence is the namespace separator, and an id containing it
+ * would make `<id>__<local>` ambiguous to a human reading a ledger row.
+ */
+export const PROVIDER_ID_RE = /^[a-z0-9][a-z0-9_-]*$/;
+export function validateProviderId(id) {
+    if (!PROVIDER_ID_RE.test(id) || id.includes("__")) {
+        throw new NaxError(`provider id ${JSON.stringify(id)} must match ${PROVIDER_ID_RE}`, "PROVIDER_ID_INVALID");
+    }
+}
+export function providerAttachesTo(provider, stage) {
+    return provider.stages.some((s) => s === "*" || s === stage);
+}