@gaunt-sloth/core 2.0.0-alpha.9 → 2.0.0-beta.1

package/dist/core/approvals/promptHeader.d.ts

@@ -0,0 +1,28 @@
+import type { PendingToolInterrupt } from '#src/core/types.js';
+/**
+ * The opening sentence of the approval prompt for one gated call, **without** any surface's own
+ * punctuation or styling.
+ *
+ * Three arms, one per subject kind:
+ *
+ * - `shell` — *The agent wants to run a shell command via `<tool>`*, unchanged, so the case that was
+ *   already clear stays clear.
+ * - `mcpTool` — *The agent wants to call `<name>` on the MCP server `<server>`, via `<tool>`*.
+ *   **Naming the server is a deliberate addition rather than a side effect**: the subject already
+ *   carries it, and which server a call reaches is the one load-bearing fact the old prompt hid.
+ * - `tool` — *The agent wants to use the `<tool>` tool*.
+ *
+ * **An MCP call whose server would print as a blank falls to the `tool` arm.** The `mcpTool`
+ * sentence would otherwise read "on the MCP server , via …" — nothing where the decisive word goes.
+ * The `tool` arm names the full registered name instead, which still carries the visible `mcp__`
+ * namespace, and invents no prose claiming a server nothing could attribute.
+ *
+ * **A pending call with no subject also falls to the `tool` arm**, which is true of any gated call
+ * and false of none. The runner attaches a subject to every interrupt it hands the approval
+ * callback (asserted in `packages/core/spec/approvalPromptHeader.spec.ts`), so this is a floor
+ * rather than a path: a surface handed a hand-built interrupt gets the vague sentence, never a
+ * wrong one.
+ *
+ * @param pending The gated call — its registered name, and the subject the gate decided on.
+ */
+export declare function approvalPromptHeader(pending: Pick<PendingToolInterrupt, 'name' | 'subject'>): string;

package/dist/core/approvals/promptHeader.js

@@ -0,0 +1,62 @@
+import { UNRESOLVED_MCP_SERVER } from '#src/core/approvals/mcpSubjects.js';
+import { neutralizeToOneLine } from '#src/core/shell/framing.js';
+/**
+ * An identifier as it may be interpolated into the prompt's **own** chrome line.
+ *
+ * A registered tool name is not always ours: an MCP server supplies the names in its tool listing,
+ * and the `mcpTool` arm additionally prints the server-supplied short name. This line sits at
+ * column 0 among the dialog's own rows, so a name carrying a newline would lay down a row that
+ * looks exactly like chrome and a carriage return would walk the cursor back over it — the
+ * [[TUI-C26]] forgery, reached through the one string that was never framed. `neutralizeToOneLine`
+ * is core's existing answer for text that must survive as a single safe line; an ordinary name
+ * passes through it byte for byte, so nothing legitimate changes shape.
+ */
+const identifier = (value) => neutralizeToOneLine(value);
+/**
+ * The opening sentence of the approval prompt for one gated call, **without** any surface's own
+ * punctuation or styling.
+ *
+ * Three arms, one per subject kind:
+ *
+ * - `shell` — *The agent wants to run a shell command via `<tool>`*, unchanged, so the case that was
+ *   already clear stays clear.
+ * - `mcpTool` — *The agent wants to call `<name>` on the MCP server `<server>`, via `<tool>`*.
+ *   **Naming the server is a deliberate addition rather than a side effect**: the subject already
+ *   carries it, and which server a call reaches is the one load-bearing fact the old prompt hid.
+ * - `tool` — *The agent wants to use the `<tool>` tool*.
+ *
+ * **An MCP call whose server would print as a blank falls to the `tool` arm.** The `mcpTool`
+ * sentence would otherwise read "on the MCP server , via …" — nothing where the decisive word goes.
+ * The `tool` arm names the full registered name instead, which still carries the visible `mcp__`
+ * namespace, and invents no prose claiming a server nothing could attribute.
+ *
+ * **A pending call with no subject also falls to the `tool` arm**, which is true of any gated call
+ * and false of none. The runner attaches a subject to every interrupt it hands the approval
+ * callback (asserted in `packages/core/spec/approvalPromptHeader.spec.ts`), so this is a floor
+ * rather than a path: a surface handed a hand-built interrupt gets the vague sentence, never a
+ * wrong one.
+ *
+ * @param pending The gated call — its registered name, and the subject the gate decided on.
+ */
+export function approvalPromptHeader(pending) {
+    const tool = identifier(pending.name);
+    const subject = pending.subject;
+    if (subject?.kind === 'shell') {
+        return `The agent wants to run a shell command via ${tool}`;
+    }
+    if (subject?.kind === 'mcpTool') {
+        const server = identifier(subject.server);
+        // **The guard is on the RENDERED server, not the raw one.** `UNRESOLVED_MCP_SERVER` is the
+        // empty string — the one identity a user cannot spell in config — but it is not the only value
+        // that reaches the screen as a blank: `neutralizeToOneLine` ends in a trim, so a server key of
+        // whitespace alone, which `z.string().min(1)` admits, is empty by the time it would be printed.
+        // Comparing the value before neutralisation lets exactly that key render the sentence with a
+        // hole in it, which is the output this fallback exists to prevent.
+        if (server !== UNRESOLVED_MCP_SERVER) {
+            const name = identifier(subject.name);
+            return `The agent wants to call ${name} on the MCP server ${server}, via ${tool}`;
+        }
+    }
+    return `The agent wants to use the ${tool} tool`;
+}
+//# sourceMappingURL=promptHeader.js.map

package/dist/core/approvals/promptHeader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptHeader.js","sourceRoot":"","sources":["../../../src/core/approvals/promptHeader.ts"],"names":[],"mappings":"AAyCA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGjE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAuD;IAEvD,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,OAAO,GAAgC,OAAO,CAAC,OAAO,CAAC;IAC7D,IAAI,OAAO,EAAE,IAAI,KAAK,OAAO,EAAE,CAAC;QAC9B,OAAO,8CAA8C,IAAI,EAAE,CAAC;IAC9D,CAAC;IACD,IAAI,OAAO,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC1C,2FAA2F;QAC3F,+FAA+F;QAC/F,+FAA+F;QAC/F,gGAAgG;QAChG,6FAA6F;QAC7F,mEAAmE;QACnE,IAAI,MAAM,KAAK,qBAAqB,EAAE,CAAC;YACrC,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACtC,OAAO,2BAA2B,IAAI,sBAAsB,MAAM,SAAS,IAAI,EAAE,CAAC;QACpF,CAAC;IACH,CAAC;IACD,OAAO,8BAA8B,IAAI,OAAO,CAAC;AACnD,CAAC"}

package/dist/core/approvals/toolAnnotationSources.d.ts

@@ -0,0 +1,105 @@
+import type { DeclaredToolAnnotations } from '#src/core/approvals/annotations.js';
+/**
+ * A built-in's authored hint set. **All four hints are stated**, never a subset: an omitted hint
+ * silently takes the fail-closed default, so a partial row would read as a considered judgment
+ * while actually being a gap. Requiring the whole set makes a forgotten hint a compile error.
+ */
+export type AuthoredToolAnnotations = Required<DeclaredToolAnnotations>;
+/**
+ * §4.7 — what each of our own tools does, in the MCP `ToolAnnotations` vocabulary. Read **verbatim**
+ * through the trusted provenance (§4.7.1: we author these), so every value here has to be *true*
+ * rather than convenient.
+ *
+ * Keyed by the registered tool NAME, not by owner — gsloth's own `GthFileSystemToolkit` and
+ * `gth_*` tools, plus the conventional `ls`/`glob`/`grep` a graph builder or MCP server may
+ * register — because the conventions overlap on `read_file`/`write_file`/`edit_file` and one flat
+ * table by name serves them all, exactly as `BUILT_IN_TOOL_ACCESS` does.
+ *
+ * The judgments that carry security weight:
+ *
+ * - **A local read is `readOnlyHint: true`, `openWorldHint: false`.** It mutates nothing and reaches
+ *   nothing off this machine.
+ * - **`gth_web_fetch` is `readOnlyHint: true` AND `openWorldHint: true`** — §4.7.3. It mutates
+ *   nothing locally *and* reaches the network, and the two facts are independent. Reading it as a
+ *   local read is precisely what §4.7.3 forbids: §4.6 floors a shell fetch before any model call,
+ *   and "the same fetch reached through a tool instead of through `curl` must not be ungated", or
+ *   the preflight is a rule about spelling rather than about fetching.
+ * - **Anything that writes, moves or deletes is not `readOnlyHint: true`**, and is
+ *   `destructiveHint: true` wherever the call can destroy something that was already there —
+ *   which `create_directory` cannot and `write_file`, `edit_file`, `move_file` and the two deletes
+ *   can.
+ * - `idempotentHint` says whether repeating the identical call changes anything further. It has no
+ *   built-in consumer (§4.7.2) and is recorded so the vocabulary round-trips and a user's own
+ *   `hint` entry can reference it. MCP defines it, like `destructiveHint`, as meaningful only when
+ *   `readOnlyHint` is false, so on a read row it is **moot and stated `true`**: a tool that changes
+ *   nothing cannot change anything further on a second call, and a read row claiming otherwise
+ *   would contradict itself.
+ */
+export declare const BUILT_IN_TOOL_ANNOTATIONS: Readonly<Record<string, AuthoredToolAnnotations>>;
+/**
+ * §4.7.1 — the `builtIn` half of a `DeclaredToolAnnotationLookup`: what WE say one of our own tools
+ * does.
+ *
+ * **Keyed off {@link BUILT_IN_TOOL_ANNOTATIONS}, our own authored table, and never off the bound
+ * tool list.** The bound list is the merged set the graph is given, and it contains every MCP
+ * server's tools; a `builtIn` lookup implemented over it would read a third-party declaration
+ * through the trusted-verbatim path — the same "a gate any server can opt itself out of" hole as
+ * routing an MCP call to a `tool` subject, arriving by a different door. §4.7.1 puts it more
+ * strongly still: what decides trust is *who authored the annotation*, so even a tool running
+ * in-process whose annotations we did not write does not take this path.
+ *
+ * Returns a fresh object, so the table cannot be mutated through the lookup; `undefined` for
+ * anything not in it, which is fail-closed.
+ */
+export declare function builtInToolAnnotations(toolName: string): DeclaredToolAnnotations | undefined;
+/** The slice of a registered tool this module reads. Keeps it free of any langchain type. */
+export interface AnnotationDeclaringTool {
+    name?: string;
+    /** `unknown` on purpose: it is whatever the adapter attached, and it is network-derived. */
+    metadata?: unknown;
+}
+/**
+ * Read the four MCP hints a tool DECLARES, off the `metadata.annotations` the MCP adapter carries
+ * over verbatim from the server's `tools/list` response.
+ *
+ * Own-property reads of the four known hint names only, so nothing else in a server's payload can
+ * arrive as a hint. Values are passed through **unchanged**, including non-booleans: the one place
+ * that decides a string `"true"` is not a `true` is the trust computation
+ * (`createEffectiveToolAnnotationSource`), and duplicating that judgment here would give it two
+ * homes that can disagree.
+ *
+ * `undefined` when the payload declares none of the four — a server that says nothing about itself
+ * is the ordinary case and must land on fail-closed, not on an empty "it declared nothing" object.
+ */
+export declare function declaredToolAnnotationsFrom(metadata: unknown): DeclaredToolAnnotations | undefined;
+/**
+ * §4.7.1 — collect what the connected MCP servers declared, keyed by the **registered tool name**
+ * (`mcp__<server>__<tool>`).
+ *
+ * Keying by the registered name rather than by a parsed `(server, tool)` pair is what makes the
+ * lookup immune to the `__`-in-a-server-key hazard: the reader rebuilds the same string with
+ * `mcpToolRegisteredName` from a server key it has already resolved against the configured set, so
+ * nothing is ever split apart and re-joined differently.
+ *
+ * Only MCP-namespaced names are collected. Our own tools' annotations come from
+ * {@link BUILT_IN_TOOL_ANNOTATIONS} and must not be reachable through the per-hint-trusted MCP
+ * path, and a custom tool's own metadata is not ours to believe either (§4.7.1).
+ */
+export declare function collectDeclaredMcpToolAnnotations(tools: readonly AnnotationDeclaringTool[]): ReadonlyMap<string, DeclaredToolAnnotations>;
+/**
+ * §4.7.1/§4.7.5 — the `mcp` half of a `DeclaredToolAnnotationLookup`, over what
+ * {@link collectDeclaredMcpToolAnnotations} recorded.
+ *
+ * **{@link UNRESOLVED_MCP_SERVER} is refused outright**, and that guard is structural rather than
+ * belt-and-braces. A call whose server could not be resolved has no identity to look a declaration
+ * up by; without the guard the lookup would fall back to *string arithmetic* on the sentinel and
+ * find a declaration in whatever entry happened to reconstruct to the same registered name.
+ * "Happened not to collide" is not a security property. Refusing the sentinel makes an
+ * unidentifiable call fail-closed for a reason that does not depend on the shape of anyone's tool
+ * names — and, because trust for an unnamed server would otherwise fall through to
+ * `approvals.mcp.defaults`, this is also what stops a permissive `defaults` from reaching it.
+ *
+ * There is one lookup rather than one per call site so the guard cannot be present in the runner
+ * and absent in the next consumer.
+ */
+export declare function mcpDeclaredAnnotationLookup(declared: ReadonlyMap<string, DeclaredToolAnnotations> | undefined): (server: string, toolName: string) => DeclaredToolAnnotations | undefined;

package/dist/core/approvals/toolAnnotationSources.js

@@ -0,0 +1,277 @@
+/**
+ * @module core/approvals/toolAnnotationSources
+ *
+ * EXT-70 §4.7 — **where a declared annotation actually comes from**: our own authored hint sets for
+ * our own tools, and a server's `tools/list` declaration for an MCP tool. The trust that is then
+ * applied to them lives in `core/approvals/annotations.ts` and only there; this module supplies the
+ * raw claims and nothing else.
+ *
+ * ## One annotation-driven classifier, and no exempt list
+ *
+ * §4.7 is explicit that the vocabulary — `readOnlyHint`, `destructiveHint`, `idempotentHint`,
+ * `openWorldHint` — is shared by built-in, MCP and custom tools, with *"no bespoke exempt list"*.
+ * {@link BUILT_IN_TOOL_ANNOTATIONS} is therefore a statement of **what each tool does**, not a list
+ * of tools that get special treatment: nothing reads a name out of it to decide an outcome, and
+ * every consumer reads the four booleans. A table of names that skip the gate would be the thing
+ * this section removes.
+ *
+ * ## Absent means fail-closed, never "trusted, declaring nothing"
+ *
+ * A tool this module cannot answer for yields `undefined`, which
+ * `createEffectiveToolAnnotationSource` resolves to the MCP fail-closed defaults — a destructive,
+ * non-idempotent, open-world writer. That is why tools whose honest annotation set simply *is* the
+ * fail-closed default are deliberately absent below rather than spelled out: `run_shell_command`,
+ * the fixed dev-command tools, A2A agent tools and user-authored custom tools all reach arbitrary
+ * code or the network, and writing rows that restate the default would add entries no behaviour
+ * could distinguish from their absence.
+ */
+import { TOOL_ANNOTATION_HINTS } from '#src/config/shell-policy.js';
+import { isMcpNamespacedToolName, mcpToolRegisteredName, UNRESOLVED_MCP_SERVER, } from '#src/core/approvals/mcpSubjects.js';
+/** Build one authored set. Named arguments, because a row of four bare booleans is unreviewable. */
+function authored(annotations) {
+    return Object.freeze(annotations);
+}
+/**
+ * Reads a file, a directory or file contents inside the working folder. Mutates nothing, so
+ * `destructiveHint` is moot and false; reaches nothing off this machine; and reading twice reads
+ * the same thing.
+ */
+const LOCAL_READ = authored({
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+});
+/**
+ * Leaves the working folder in a state its **arguments alone** determine — overwriting or removing
+ * whatever happened to be at the path — so it destroys, and repeating the identical call lands the
+ * same end state. Covers writing a whole file and deleting a file or a directory: what they have in
+ * common is that neither reads what is there first, and both discard it.
+ */
+const LOCAL_ABSOLUTE_CHANGE = authored({
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+});
+/**
+ * Changes something in the working folder in a way that depends on what is there now: it destroys
+ * what it replaced, and repeating it either fails or lands a second, different time.
+ */
+const LOCAL_RELATIVE_CHANGE = authored({
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+});
+/**
+ * Adds something to the working folder that was not there, destroying nothing, and settles into the
+ * same state when repeated.
+ */
+const LOCAL_ADDITIVE_CHANGE = authored({
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+});
+/**
+ * Writes state that belongs to **this session** — the agent's own plan, a surface rendered for the
+ * user — rather than to the working folder. Replacing such state destroys nothing outside the
+ * session, and re-sending the same state leaves the same state.
+ *
+ * Deliberately a separate constant from {@link LOCAL_ADDITIVE_CHANGE} despite carrying the same
+ * four values: the two describe different things, so a future correction to one must not silently
+ * move the other's tools.
+ */
+const SESSION_STATE_CHANGE = authored({
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+});
+/**
+ * §4.7 — what each of our own tools does, in the MCP `ToolAnnotations` vocabulary. Read **verbatim**
+ * through the trusted provenance (§4.7.1: we author these), so every value here has to be *true*
+ * rather than convenient.
+ *
+ * Keyed by the registered tool NAME, not by owner — gsloth's own `GthFileSystemToolkit` and
+ * `gth_*` tools, plus the conventional `ls`/`glob`/`grep` a graph builder or MCP server may
+ * register — because the conventions overlap on `read_file`/`write_file`/`edit_file` and one flat
+ * table by name serves them all, exactly as `BUILT_IN_TOOL_ACCESS` does.
+ *
+ * The judgments that carry security weight:
+ *
+ * - **A local read is `readOnlyHint: true`, `openWorldHint: false`.** It mutates nothing and reaches
+ *   nothing off this machine.
+ * - **`gth_web_fetch` is `readOnlyHint: true` AND `openWorldHint: true`** — §4.7.3. It mutates
+ *   nothing locally *and* reaches the network, and the two facts are independent. Reading it as a
+ *   local read is precisely what §4.7.3 forbids: §4.6 floors a shell fetch before any model call,
+ *   and "the same fetch reached through a tool instead of through `curl` must not be ungated", or
+ *   the preflight is a rule about spelling rather than about fetching.
+ * - **Anything that writes, moves or deletes is not `readOnlyHint: true`**, and is
+ *   `destructiveHint: true` wherever the call can destroy something that was already there —
+ *   which `create_directory` cannot and `write_file`, `edit_file`, `move_file` and the two deletes
+ *   can.
+ * - `idempotentHint` says whether repeating the identical call changes anything further. It has no
+ *   built-in consumer (§4.7.2) and is recorded so the vocabulary round-trips and a user's own
+ *   `hint` entry can reference it. MCP defines it, like `destructiveHint`, as meaningful only when
+ *   `readOnlyHint` is false, so on a read row it is **moot and stated `true`**: a tool that changes
+ *   nothing cannot change anything further on a second call, and a read row claiming otherwise
+ *   would contradict itself.
+ */
+export const BUILT_IN_TOOL_ANNOTATIONS = Object.freeze({
+    // ---- Local reads (gsloth's GthFileSystemToolkit and gth_* tools, lean backend). -----------
+    read_file: LOCAL_READ,
+    read_multiple_files: LOCAL_READ,
+    gth_read_binary: LOCAL_READ,
+    list_directory: LOCAL_READ,
+    list_directory_with_sizes: LOCAL_READ,
+    directory_tree: LOCAL_READ,
+    search_files: LOCAL_READ,
+    get_file_info: LOCAL_READ,
+    // Reports which directories the file tools may touch. Reads configuration, changes nothing.
+    list_allowed_directories: LOCAL_READ,
+    gth_grep: LOCAL_READ,
+    // ---- Conventional local-read names a graph builder or MCP server may register. -----------
+    ls: LOCAL_READ,
+    glob: LOCAL_READ,
+    grep: LOCAL_READ,
+    // ---- Local writes. -----------------------------------------------------------------------
+    // Writes the whole file, so it destroys whatever was there; the same bytes twice leave the
+    // same file.
+    write_file: LOCAL_ABSOLUTE_CHANGE,
+    // A targeted edit destroys the text it replaces, and re-applying it either fails or lands a
+    // second time.
+    edit_file: LOCAL_RELATIVE_CHANGE,
+    // Creating a directory adds and removes nothing; the second call leaves the same tree.
+    create_directory: LOCAL_ADDITIVE_CHANGE,
+    // A move removes the source, and the second call no longer has one.
+    move_file: LOCAL_RELATIVE_CHANGE,
+    // Deletion destroys by definition; the second call finds nothing left to change.
+    delete_file: LOCAL_ABSOLUTE_CHANGE,
+    delete_directory: LOCAL_ABSOLUTE_CHANGE,
+    // ---- The open-world read (§4.7.3): read-only locally, and on the network. -----------------
+    gth_web_fetch: authored({
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }),
+    // ---- Tools that touch only this session's own surfaces. ----------------------------------
+    // Prints one line for the user and changes no state anywhere, so it is a read. `idempotentHint`
+    // is then MOOT for exactly the reason `destructiveHint` is — MCP defines both as meaningful
+    // only when `readOnlyHint` is false — and a moot hint states the value consistent with the
+    // read: a tool that changes nothing cannot change anything *further* when called again.
+    // Stating `false` here would have this row contradict itself.
+    gth_status_update: authored({
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }),
+    // Replaces the agent's own plan state: a write, destroying nothing outside the session, and
+    // re-sending the same checklist leaves the same checklist.
+    gth_checklist: SESSION_STATE_CHANGE,
+    // Renders a UI surface on the client — it changes what the user sees rather than nothing at
+    // all, and re-rendering the same surface is the same surface.
+    show_a2ui_surface: SESSION_STATE_CHANGE,
+});
+/**
+ * §4.7.1 — the `builtIn` half of a `DeclaredToolAnnotationLookup`: what WE say one of our own tools
+ * does.
+ *
+ * **Keyed off {@link BUILT_IN_TOOL_ANNOTATIONS}, our own authored table, and never off the bound
+ * tool list.** The bound list is the merged set the graph is given, and it contains every MCP
+ * server's tools; a `builtIn` lookup implemented over it would read a third-party declaration
+ * through the trusted-verbatim path — the same "a gate any server can opt itself out of" hole as
+ * routing an MCP call to a `tool` subject, arriving by a different door. §4.7.1 puts it more
+ * strongly still: what decides trust is *who authored the annotation*, so even a tool running
+ * in-process whose annotations we did not write does not take this path.
+ *
+ * Returns a fresh object, so the table cannot be mutated through the lookup; `undefined` for
+ * anything not in it, which is fail-closed.
+ */
+export function builtInToolAnnotations(toolName) {
+    if (!Object.hasOwn(BUILT_IN_TOOL_ANNOTATIONS, toolName))
+        return undefined;
+    return { ...BUILT_IN_TOOL_ANNOTATIONS[toolName] };
+}
+/**
+ * Read the four MCP hints a tool DECLARES, off the `metadata.annotations` the MCP adapter carries
+ * over verbatim from the server's `tools/list` response.
+ *
+ * Own-property reads of the four known hint names only, so nothing else in a server's payload can
+ * arrive as a hint. Values are passed through **unchanged**, including non-booleans: the one place
+ * that decides a string `"true"` is not a `true` is the trust computation
+ * (`createEffectiveToolAnnotationSource`), and duplicating that judgment here would give it two
+ * homes that can disagree.
+ *
+ * `undefined` when the payload declares none of the four — a server that says nothing about itself
+ * is the ordinary case and must land on fail-closed, not on an empty "it declared nothing" object.
+ */
+export function declaredToolAnnotationsFrom(metadata) {
+    if (!metadata || typeof metadata !== 'object')
+        return undefined;
+    const annotations = metadata.annotations;
+    if (!annotations || typeof annotations !== 'object')
+        return undefined;
+    const declared = annotations;
+    const result = {};
+    let stated = false;
+    for (const hint of TOOL_ANNOTATION_HINTS) {
+        if (!Object.hasOwn(declared, hint))
+            continue;
+        result[hint] = declared[hint];
+        stated = true;
+    }
+    return stated ? result : undefined;
+}
+/**
+ * §4.7.1 — collect what the connected MCP servers declared, keyed by the **registered tool name**
+ * (`mcp__<server>__<tool>`).
+ *
+ * Keying by the registered name rather than by a parsed `(server, tool)` pair is what makes the
+ * lookup immune to the `__`-in-a-server-key hazard: the reader rebuilds the same string with
+ * `mcpToolRegisteredName` from a server key it has already resolved against the configured set, so
+ * nothing is ever split apart and re-joined differently.
+ *
+ * Only MCP-namespaced names are collected. Our own tools' annotations come from
+ * {@link BUILT_IN_TOOL_ANNOTATIONS} and must not be reachable through the per-hint-trusted MCP
+ * path, and a custom tool's own metadata is not ours to believe either (§4.7.1).
+ */
+export function collectDeclaredMcpToolAnnotations(tools) {
+    const collected = new Map();
+    for (const tool of tools) {
+        const name = tool?.name;
+        if (typeof name !== 'string' || !isMcpNamespacedToolName(name))
+            continue;
+        const declared = declaredToolAnnotationsFrom(tool.metadata);
+        if (declared)
+            collected.set(name, declared);
+    }
+    return collected;
+}
+/**
+ * §4.7.1/§4.7.5 — the `mcp` half of a `DeclaredToolAnnotationLookup`, over what
+ * {@link collectDeclaredMcpToolAnnotations} recorded.
+ *
+ * **{@link UNRESOLVED_MCP_SERVER} is refused outright**, and that guard is structural rather than
+ * belt-and-braces. A call whose server could not be resolved has no identity to look a declaration
+ * up by; without the guard the lookup would fall back to *string arithmetic* on the sentinel and
+ * find a declaration in whatever entry happened to reconstruct to the same registered name.
+ * "Happened not to collide" is not a security property. Refusing the sentinel makes an
+ * unidentifiable call fail-closed for a reason that does not depend on the shape of anyone's tool
+ * names — and, because trust for an unnamed server would otherwise fall through to
+ * `approvals.mcp.defaults`, this is also what stops a permissive `defaults` from reaching it.
+ *
+ * There is one lookup rather than one per call site so the guard cannot be present in the runner
+ * and absent in the next consumer.
+ */
+export function mcpDeclaredAnnotationLookup(declared) {
+    return (server, toolName) => {
+        if (server === UNRESOLVED_MCP_SERVER)
+            return undefined;
+        return declared?.get(mcpToolRegisteredName(server, toolName));
+    };
+}
+//# sourceMappingURL=toolAnnotationSources.js.map

package/dist/core/approvals/toolAnnotationSources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolAnnotationSources.js","sourceRoot":"","sources":["../../../src/core/approvals/toolAnnotationSources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,oCAAoC,CAAC;AAS5C,oGAAoG;AACpG,SAAS,QAAQ,CAAC,WAAoC;IACpD,OAAO,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,GAAG,QAAQ,CAAC;IAC1B,YAAY,EAAE,IAAI;IAClB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,KAAK;CACrB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IACrC,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,IAAI;IACrB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,KAAK;CACrB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IACrC,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,IAAI;IACrB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,KAAK;CACrB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IACrC,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,KAAK;CACrB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IACpC,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,KAAK;CACrB,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,yBAAyB,GACpC,MAAM,CAAC,MAAM,CAAC;IACZ,8FAA8F;IAC9F,SAAS,EAAE,UAAU;IACrB,mBAAmB,EAAE,UAAU;IAC/B,eAAe,EAAE,UAAU;IAC3B,cAAc,EAAE,UAAU;IAC1B,yBAAyB,EAAE,UAAU;IACrC,cAAc,EAAE,UAAU;IAC1B,YAAY,EAAE,UAAU;IACxB,aAAa,EAAE,UAAU;IACzB,4FAA4F;IAC5F,wBAAwB,EAAE,UAAU;IACpC,QAAQ,EAAE,UAAU;IACpB,6FAA6F;IAC7F,EAAE,EAAE,UAAU;IACd,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,UAAU;IAEhB,6FAA6F;IAC7F,2FAA2F;IAC3F,aAAa;IACb,UAAU,EAAE,qBAAqB;IACjC,4FAA4F;IAC5F,eAAe;IACf,SAAS,EAAE,qBAAqB;IAChC,uFAAuF;IACvF,gBAAgB,EAAE,qBAAqB;IACvC,oEAAoE;IACpE,SAAS,EAAE,qBAAqB;IAChC,iFAAiF;IACjF,WAAW,EAAE,qBAAqB;IAClC,gBAAgB,EAAE,qBAAqB;IAEvC,8FAA8F;IAC9F,aAAa,EAAE,QAAQ,CAAC;QACtB,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,IAAI;KACpB,CAAC;IAEF,6FAA6F;IAC7F,gGAAgG;IAChG,4FAA4F;IAC5F,2FAA2F;IAC3F,wFAAwF;IACxF,8DAA8D;IAC9D,iBAAiB,EAAE,QAAQ,CAAC;QAC1B,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACrB,CAAC;IACF,4FAA4F;IAC5F,2DAA2D;IAC3D,aAAa,EAAE,oBAAoB;IACnC,4FAA4F;IAC5F,8DAA8D;IAC9D,iBAAiB,EAAE,oBAAoB;CACxC,CAAC,CAAC;AAEL;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,yBAAyB,EAAE,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1E,OAAO,EAAE,GAAG,yBAAyB,CAAC,QAAQ,CAAC,EAAE,CAAC;AACpD,CAAC;AASD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,2BAA2B,CACzC,QAAiB;IAEjB,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChE,MAAM,WAAW,GAAI,QAAsC,CAAC,WAAW,CAAC;IACxE,IAAI,CAAC,WAAW,IAAI,OAAO,WAAW,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACtE,MAAM,QAAQ,GAAG,WAAsC,CAAC;IACxD,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,KAAK,MAAM,IAAI,IAAI,qBAAqB,EAAE,CAAC;QACzC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC;YAAE,SAAS;QAC7C,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,MAAM,CAAC,CAAC,CAAE,MAAkC,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iCAAiC,CAC/C,KAAyC;IAEzC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAmC,CAAC;IAC7D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;QACxB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC;YAAE,SAAS;QACzE,MAAM,QAAQ,GAAG,2BAA2B,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5D,IAAI,QAAQ;YAAE,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,2BAA2B,CACzC,QAAkE;IAElE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE;QAC1B,IAAI,MAAM,KAAK,qBAAqB;YAAE,OAAO,SAAS,CAAC;QACvD,OAAO,QAAQ,EAAE,GAAG,CAAC,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChE,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/approvals/toolHost.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @module core/approvals/toolHost
+ *
+ * EXT-70 (spec §4.7.4) — **the host a tool call reaches**, read off the call's own arguments.
+ *
+ * §4.7.4's bound on a sticky tool grant needs one thing the tool name does not carry: *which
+ * counterparty this call talks to*. A grant that recorded only the tool would be every host,
+ * forever — the hole §4.6 spent a whole preflight closing, reached through a tool instead of
+ * `curl`. A host is not "the full argument signature"; it is the one argument both
+ * security-relevant and stable enough across calls for the grant to stay useful.
+ *
+ * ## Why this is not a second implementation of §4.6's scanner
+ *
+ * `core/shell/openWorld.ts` answers a different question over a different input: *"does this shell
+ * word name a counterparty at all"*, over a tokenized command line, returning a boolean plus the
+ * literals it found for a human-readable reason. This answers *"which host, exactly"* over a
+ * **structured tool argument**, because the answer here is stored in a config entry and later
+ * compared for equality — so it must be a single normalized string or nothing.
+ *
+ * Structured arguments admit the precise instrument the shell path cannot use: `URL` parsing. A
+ * value either parses as a URL with a host or it does not, with no tokenization, no quoting and no
+ * heuristics about operand position.
+ *
+ * ## The COUNT is the answer, which is why nothing here returns a single host
+ *
+ * A grant's `host` is one exact string, so only a call naming **exactly one** host has a host to
+ * record — but the decision needs the count and not just that one host, because the two ways of
+ * having no single host are opposite outcomes: a call naming **no** host gets a tool-only grant
+ * (§6's *always approve `mcp__jira__create_issue`*, where no host is involved), while a call naming
+ * **several** gets no grant at all, since the menu may not display one bound and store another.
+ * A convenience that collapsed both to "no host" would hand a caller the one distinction this
+ * module exists to preserve, already discarded — so {@link toolCallHosts} is the whole surface, and
+ * a caller that wants *the* host reads `hosts.length === 1 ? hosts[0] : …` at the point where it
+ * also decides what the other two cases mean.
+ *
+ * A value this module fails to recognize as a host costs a re-prompt or a broader grant than the
+ * call deserved, never a narrower one that silently fails to match.
+ */
+/**
+ * Every distinct host named anywhere in a tool call's arguments, in the order first seen.
+ *
+ * Own enumerable properties only, so nothing inherited can contribute a host, and arrays are walked
+ * as their elements. This is what the approvals decision reads, because it needs the COUNT: a call
+ * naming no host and a call naming several are the same absent host and not the same grant.
+ */
+export declare function toolCallHosts(args: unknown): string[];

package/dist/core/approvals/toolHost.js

@@ -0,0 +1,108 @@
+/**
+ * @module core/approvals/toolHost
+ *
+ * EXT-70 (spec §4.7.4) — **the host a tool call reaches**, read off the call's own arguments.
+ *
+ * §4.7.4's bound on a sticky tool grant needs one thing the tool name does not carry: *which
+ * counterparty this call talks to*. A grant that recorded only the tool would be every host,
+ * forever — the hole §4.6 spent a whole preflight closing, reached through a tool instead of
+ * `curl`. A host is not "the full argument signature"; it is the one argument both
+ * security-relevant and stable enough across calls for the grant to stay useful.
+ *
+ * ## Why this is not a second implementation of §4.6's scanner
+ *
+ * `core/shell/openWorld.ts` answers a different question over a different input: *"does this shell
+ * word name a counterparty at all"*, over a tokenized command line, returning a boolean plus the
+ * literals it found for a human-readable reason. This answers *"which host, exactly"* over a
+ * **structured tool argument**, because the answer here is stored in a config entry and later
+ * compared for equality — so it must be a single normalized string or nothing.
+ *
+ * Structured arguments admit the precise instrument the shell path cannot use: `URL` parsing. A
+ * value either parses as a URL with a host or it does not, with no tokenization, no quoting and no
+ * heuristics about operand position.
+ *
+ * ## The COUNT is the answer, which is why nothing here returns a single host
+ *
+ * A grant's `host` is one exact string, so only a call naming **exactly one** host has a host to
+ * record — but the decision needs the count and not just that one host, because the two ways of
+ * having no single host are opposite outcomes: a call naming **no** host gets a tool-only grant
+ * (§6's *always approve `mcp__jira__create_issue`*, where no host is involved), while a call naming
+ * **several** gets no grant at all, since the menu may not display one bound and store another.
+ * A convenience that collapsed both to "no host" would hand a caller the one distinction this
+ * module exists to preserve, already discarded — so {@link toolCallHosts} is the whole surface, and
+ * a caller that wants *the* host reads `hosts.length === 1 ? hosts[0] : …` at the point where it
+ * also decides what the other two cases mean.
+ *
+ * A value this module fails to recognize as a host costs a re-prompt or a broader grant than the
+ * call deserved, never a narrower one that silently fails to match.
+ */
+/**
+ * How deep into a nested argument object a host may hide. Tool arguments are shallow by
+ * construction (a JSON Schema the model fills in), so this is a budget rather than a limit anyone
+ * should expect to reach.
+ */
+const MAX_DEPTH = 4;
+/** How many values are examined in total, so a pathological argument object cannot spin. */
+const MAX_VALUES = 256;
+/**
+ * Values longer than this are not candidate URLs. A URL that reaches this length is not something a
+ * grant should be keyed on, and the cap bounds the work regardless of what a model emitted.
+ */
+const MAX_VALUE_LENGTH = 4096;
+/**
+ * The host a single string names, or `undefined`.
+ *
+ * **A non-empty `hostname` is the whole test**, and it is what makes the schemes that name no
+ * counterparty drop out without a list to maintain: `file:///etc/passwd`, `data:text/plain,x` and
+ * `mailto:someone@example.com` all parse, and all have an empty hostname. Lower-cased because host
+ * names are case-insensitive and the stored value is compared for equality; the port is
+ * deliberately left out, since §3.1's example is a bare host and a grant that dissolved when a
+ * server moved port would be a grant on the wrong thing.
+ */
+function hostOf(value) {
+    if (value.length === 0 || value.length > MAX_VALUE_LENGTH)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return undefined;
+    }
+    return parsed.hostname.length > 0 ? parsed.hostname.toLowerCase() : undefined;
+}
+/**
+ * Every distinct host named anywhere in a tool call's arguments, in the order first seen.
+ *
+ * Own enumerable properties only, so nothing inherited can contribute a host, and arrays are walked
+ * as their elements. This is what the approvals decision reads, because it needs the COUNT: a call
+ * naming no host and a call naming several are the same absent host and not the same grant.
+ */
+export function toolCallHosts(args) {
+    const hosts = [];
+    let budget = MAX_VALUES;
+    const walk = (value, depth) => {
+        if (budget <= 0 || depth > MAX_DEPTH)
+            return;
+        budget -= 1;
+        if (typeof value === 'string') {
+            const host = hostOf(value);
+            if (host !== undefined && !hosts.includes(host))
+                hosts.push(host);
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                walk(item, depth + 1);
+            return;
+        }
+        if (value && typeof value === 'object') {
+            for (const key of Object.keys(value)) {
+                walk(value[key], depth + 1);
+            }
+        }
+    };
+    walk(args, 0);
+    return hosts;
+}
+//# sourceMappingURL=toolHost.js.map

package/dist/core/approvals/toolHost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolHost.js","sourceRoot":"","sources":["../../../src/core/approvals/toolHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;GAIG;AACH,MAAM,SAAS,GAAG,CAAC,CAAC;AAEpB,4FAA4F;AAC5F,MAAM,UAAU,GAAG,GAAG,CAAC;AAEvB;;;GAGG;AACH,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B;;;;;;;;;GASG;AACH,SAAS,MAAM,CAAC,KAAa;IAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,gBAAgB;QAAE,OAAO,SAAS,CAAC;IAC5E,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,MAAM,GAAG,UAAU,CAAC;IAExB,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,KAAa,EAAQ,EAAE;QACnD,IAAI,MAAM,IAAI,CAAC,IAAI,KAAK,GAAG,SAAS;YAAE,OAAO;QAC7C,MAAM,IAAI,CAAC,CAAC;QACZ,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3B,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClE,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,KAAK,MAAM,IAAI,IAAI,KAAK;gBAAE,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAChD,OAAO;QACT,CAAC;QACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,EAAE,CAAC;gBAChE,IAAI,CAAE,KAAiC,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACd,OAAO,KAAK,CAAC;AACf,CAAC"}