toolfunnel 0.7.0 → 0.8.0

package/src/extend/add-hook.md

@@ -1,152 +1,155 @@
-# How to add a hook (self-extension)
-
-This is the instruction served by `toolfunnel_howto({ topic: "add-hook" })`. It explains how to add a hook
-to the Hook Engine: the manifest entry shape, where the script goes, and how the enabled/disabled
-state is persisted separately in `hooks.state.json`. This is
-the authoring view.
-
-A hook is exactly two things:
-1. **A manifest entry** in `hooks/hooks.manifest.json` (its config: event, matcher, command, ...).
-2. **A script** under `hooks/scripts/` that the entry's `command` runs.
-
-Activation (on/off) is NOT in the manifest's source of truth at runtime - it lives in an overlay,
-`hooks/hooks.state.json` (see §4).
-
----
-
-## 1. The manifest entry shape
-
-`hooks.manifest.json` has `version`, `hooksDir`, and a `hooks` array. Each entry:
-
-```json
-{
-  "id": "pre-tool-use/deny-dangerous",
-  "event": "PreToolUse",
-  "matcher": "Bash|toolfunnel_run_tool",
-  "type": "command",
-  "command": "bash \"${HOOKS_DIR}/scripts/deny-dangerous.sh\"",
-  "script": "scripts/deny-dangerous.sh",
-  "timeout": 5,
-  "enabled": true,
-  "description": "Denies any tool call whose args contain a destructive pattern (rm -rf, etc)."
-}
-```
-
-| Field | Type | Meaning |
-|---|---|---|
-| `id` | string | Unique key, format `"<kebab-event>/<script-basename-without-ext>"` (e.g. `pre-tool-use/deny-dangerous`). The loader and `hooks.state.json` key on this. |
-| `event` | string | One of the six lifecycle events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `PreCompact`. |
-| `matcher` | string | Regex anchored full-match against `tool_name`. `""`, `undefined`, or `"*"` = always fire. Tool-less events (SessionStart, UserPromptSubmit, Stop, PreCompact) ignore it. Example: `"Bash|Write|Edit"`. |
-| `type` | string | `"command"` (the only type today). |
-| `command` | string | The command line the runner spawns. `${HOOKS_DIR}` expands to the absolute `hooks` path at load time. |
-| `script` | string | The script path relative to `hooksDir`, e.g. `scripts/deny-dangerous.sh`. Used by the manager's open/edit (`readScript`/`writeScript`). |
-| `timeout` | number | **Seconds** (the runner multiplies by 1000). The runner kills the child past this. |
-| `enabled` | boolean | The manifest's default/seed state. The live value is the overlay in `hooks.state.json` - see §4. |
-| `description` | string | What the hook does, for the manager UI. |
-
-One entry **per hook command** - a settings.json event with N hooks becomes N entries.
-
----
-
-## 2. Where the script goes
-
-```
-hooks/
-  hooks.manifest.json    # config entries (above)
-  hooks.state.json       # enabled/disabled overlay, keyed by hook id
-  scripts/               # your hook scripts live HERE
-    deny-dangerous.sh
-```
-
-(The loader itself - `hook-loader.js` - is engine code and is NOT user content; it lives in
-`src/core/`, not in `hooks/`.)
-
-`writeScript` (the manager's save path) refuses any path that resolves outside
-`hooks/scripts/` - defense-in-depth for the isolation rule. Author your script there only;
-never point a hook at a script in a live host hooks directory. Clone the behaviour in if you need it.
-
----
-
-## 3. What the script returns (the two protocols)
-
-The runner spawns the command, writes the event payload as JSON on stdin, then reads the result.
-The payload a tool event receives on stdin:
-
-```json
-{ "tool_name": "note_slow", "tool_input": { "arg": "value" } }
-```
-
-(`PreToolUse` → `tool_name` + `tool_input`; `PostToolUse` adds `tool_response`. Tool-less
-events carry their own fields - `prompt`, `source` - instead.)
-
-Two protocols:
-
-**A) Exit-code (simple):**
-- `exit 0` → success. On `SessionStart`/`UserPromptSubmit`, stdout becomes **injected context**;
-  on other events stdout is advisory.
-- `exit 2` → **blocking**. stderr is the reason - on a blocked tool call the client receives it
-  as the result text with `isError: true`.
-- any other code → non-blocking error (stderr captured, loop continues; never throws).
-
-**B) JSON (advanced)** - honored **only on exit 0**, when stdout parses as a JSON object:
-```json
-{
-  "continue": true,
-  "decision": "block",
-  "reason": "...",
-  "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
-    "permissionDecision": "allow" | "deny" | "ask",
-    "permissionDecisionReason": "...",
-    "additionalContext": "..."
-  }
-}
-```
-- **PreToolUse blocks via `hookSpecificOutput.permissionDecision: "deny"`** - NOT the top-level
-  `decision` field. `"allow"` passes; `"ask"` is non-blocking in the autonomous host.
-- **Top-level `decision: "block"`** is for the other blockable events (UserPromptSubmit, PostToolUse,
-  Stop, PreCompact). There is no `"approve"`.
-- `continue: false` stops the whole loop. `hookSpecificOutput.additionalContext` → injected text.
-
-This is the mechanism that makes a PreToolUse hook gate `toolfunnel_run_tool`: match its `tool_name`, and
-return `permissionDecision: "deny"` to block the call before the tool runs.
-
----
-
-## 4. Activation state lives in `hooks.state.json`
-
-The Hook Manager design splits **what exists** from **what's on**:
-
-- **The `scripts/` folder is the source of truth for what exists.** On startup the loader scans it
-  and reconciles with the manifest: newly-found scripts are added as entries (event/matcher inferred
-  or flagged "unconfigured"); manifest entries whose script is missing are flagged.
-- **The manifest carries config** (event, matcher, command, timeout, description, seed `enabled`).
-- **`hooks.state.json` is the activation overlay** - an object keyed by hook `id` recording the live
-  enabled/disabled value:
-
-```json
-{
-  "version": 1,
-  "enabled": {
-    "pre-tool-use/deny-dangerous": true,
-    "user-prompt-submit/inject-context": false
-  }
-}
-```
-
-Toggling a hook writes `hooks.state.json` **atomically** (temp + rename). It survives restarts and is
-kept separate from the auto-detected inventory, so re-scanning the folder never clobbers your toggles.
-At load, the overlay wins over the manifest's seed `enabled` for any id it lists.
-
----
-
-## 5. Steps to add a hook
-
-1. Write the script into `hooks/scripts/<name>.sh` (or a node script). Read the stdin JSON
-   payload; emit one of the two protocols above.
-2. Add the manifest entry: `id` = `"<kebab-event>/<name>"`, set `event`, `matcher`, `command`
-   (`bash "${HOOKS_DIR}/scripts/<name>.sh"`), `script`, `timeout` (seconds), `description`, and a
-   seed `enabled`.
-3. Set its live state in `hooks.state.json` via the loader's `setEnabled(id, bool)` (atomic write).
-4. Verify: the manager lists it under its event; a run-once test fires it with a sample payload and
-   shows the result. For a gate, confirm a matching `toolfunnel_run_tool` call is denied with your reason.
+# How to add a hook (self-extension)
+
+This is the instruction served by `toolfunnel_howto({ topic: "add-hook" })`. It explains how to add a hook
+to the Hook Engine: the manifest entry shape, where the script goes, and how the enabled/disabled
+state is persisted separately in `hooks.state.json`. This is
+the authoring view.
+
+A hook is exactly two things:
+1. **A manifest entry** in `hooks/hooks.manifest.json` (its config: event, matcher, command, ...).
+2. **A script** under `hooks/scripts/` that the entry's `command` runs.
+
+Activation (on/off) is NOT in the manifest's source of truth at runtime - it lives in an overlay,
+`hooks/hooks.state.json` (see §4).
+
+---
+
+## 1. The manifest entry shape
+
+`hooks.manifest.json` has `version`, `hooksDir`, and a `hooks` array. Each entry:
+
+```json
+{
+  "id": "pre-tool-use/deny-dangerous",
+  "event": "PreToolUse",
+  "matcher": "Bash|toolfunnel_run_tool",
+  "type": "command",
+  "command": "bash \"${HOOKS_DIR}/scripts/deny-dangerous.sh\"",
+  "script": "scripts/deny-dangerous.sh",
+  "timeout": 5,
+  "enabled": true,
+  "description": "Denies any tool call whose args contain a destructive pattern (rm -rf, etc)."
+}
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | Unique key, format `"<kebab-event>/<script-basename-without-ext>"` (e.g. `pre-tool-use/deny-dangerous`). The loader and `hooks.state.json` key on this. |
+| `event` | string | One of the six lifecycle events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `PreCompact`. |
+| `matcher` | string | Regex anchored full-match against `tool_name`. `""`, `undefined`, or `"*"` = always fire. Tool-less events (SessionStart, UserPromptSubmit, Stop, PreCompact) ignore it. Example: `"Bash|Write|Edit"`. |
+| `type` | string | `"command"` (the only type today). |
+| `command` | string | The command line the runner spawns. `${HOOKS_DIR}` expands to the absolute `hooks` path at load time. |
+| `script` | string | The script path relative to `hooksDir`, e.g. `scripts/deny-dangerous.sh`. Used by the manager's open/edit (`readScript`/`writeScript`). |
+| `timeout` | number | **Seconds** (the runner multiplies by 1000). The runner kills the child past this. |
+| `enabled` | boolean | The manifest's default/seed state. The live value is the overlay in `hooks.state.json` - see §4. |
+| `description` | string | What the hook does, for the manager UI. |
+
+One entry **per hook command** - a settings.json event with N hooks becomes N entries.
+
+---
+
+## 2. Where the script goes
+
+```
+hooks/
+  hooks.manifest.json    # config entries (above)
+  hooks.state.json       # enabled/disabled overlay, keyed by hook id
+  scripts/               # your hook scripts live HERE
+    deny-dangerous.sh
+```
+
+(The loader itself - `hook-loader.js` - is engine code and is NOT user content; it lives in
+`src/core/`, not in `hooks/`.)
+
+`writeScript` (the manager's save path) refuses any path that resolves outside
+`hooks/scripts/` - defense-in-depth for the isolation rule. Author your script there only;
+never point a hook at a script in a live host hooks directory. Clone the behaviour in if you need it.
+
+---
+
+## 3. What the script returns (the two protocols)
+
+The runner spawns the command, writes the event payload as JSON on stdin, then reads the result.
+The payload a tool event receives on stdin:
+
+```json
+{ "tool_name": "note_slow", "tool_input": { "arg": "value" } }
+```
+
+(`PreToolUse` → `tool_name` + `tool_input`; `PostToolUse` adds `tool_response`. Tool-less
+events carry their own fields - `prompt`, `source` - instead.)
+
+Two protocols:
+
+**A) Exit-code (simple):**
+- `exit 0` → success. On `SessionStart`/`UserPromptSubmit`, stdout becomes **injected context**;
+  on other events stdout is advisory.
+- `exit 2` → **blocking**. stderr is the reason - on a blocked tool call the client receives it
+  as the result text with `isError: true`.
+- any other code → non-blocking error (stderr captured, loop continues; never throws).
+
+**B) JSON (advanced)** - honored **only on exit 0**, when stdout is a JSON object carrying protocol
+keys - or ends with one on its own line after other output (a printed startup line is fine). A
+decision that cannot be read (truncated, followed by stray text) **denies**; a printed object that
+is not a decision (a diagnostic dump, a JSON log line) is ignored:
+```json
+{
+  "continue": true,
+  "decision": "block",
+  "reason": "...",
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow" | "deny" | "ask",
+    "permissionDecisionReason": "...",
+    "additionalContext": "..."
+  }
+}
+```
+- **PreToolUse blocks via `hookSpecificOutput.permissionDecision: "deny"`** - NOT the top-level
+  `decision` field. `"allow"` passes; `"ask"` is non-blocking in the autonomous host.
+- **Top-level `decision: "block"`** is for the other blockable events (UserPromptSubmit, PostToolUse,
+  Stop, PreCompact). There is no `"approve"`.
+- `continue: false` stops the whole loop. `hookSpecificOutput.additionalContext` → injected text.
+
+This is the mechanism that makes a PreToolUse hook gate `toolfunnel_run_tool`: match its `tool_name`, and
+return `permissionDecision: "deny"` to block the call before the tool runs.
+
+---
+
+## 4. Activation state lives in `hooks.state.json`
+
+The Hook Manager design splits **what exists** from **what's on**:
+
+- **The `scripts/` folder is the source of truth for what exists.** On startup the loader scans it
+  and reconciles with the manifest: newly-found scripts are added as entries (event/matcher inferred
+  or flagged "unconfigured"); manifest entries whose script is missing are flagged.
+- **The manifest carries config** (event, matcher, command, timeout, description, seed `enabled`).
+- **`hooks.state.json` is the activation overlay** - an object keyed by hook `id` recording the live
+  enabled/disabled value:
+
+```json
+{
+  "version": 1,
+  "enabled": {
+    "pre-tool-use/deny-dangerous": true,
+    "user-prompt-submit/inject-context": false
+  }
+}
+```
+
+Toggling a hook writes `hooks.state.json` **atomically** (temp + rename). It survives restarts and is
+kept separate from the auto-detected inventory, so re-scanning the folder never clobbers your toggles.
+At load, the overlay wins over the manifest's seed `enabled` for any id it lists.
+
+---
+
+## 5. Steps to add a hook
+
+1. Write the script into `hooks/scripts/<name>.sh` (or a node script). Read the stdin JSON
+   payload; emit one of the two protocols above.
+2. Add the manifest entry: `id` = `"<kebab-event>/<name>"`, set `event`, `matcher`, `command`
+   (`bash "${HOOKS_DIR}/scripts/<name>.sh"`), `script`, `timeout` (seconds), `description`, and a
+   seed `enabled`.
+3. Set its live state in `hooks.state.json` via the loader's `setEnabled(id, bool)` (atomic write).
+4. Verify: the manager lists it under its event; a run-once test fires it with a sample payload and
+   shows the result. For a gate, confirm a matching `toolfunnel_run_tool` call is denied with your reason.

package/src/extend/add-mcp.md

@@ -1,119 +1,119 @@
-# How to register an upstream MCP (self-extension)
-
-This is the instruction served by `toolfunnel_howto({ topic: "add-mcp" })`. It explains how to connect an
-**upstream MCP server** (a browser-automation MCP, a chat bridge, ...) to the aggregator and choose **which of its
-tools to expose downstream** to the CLI. All of this is configured in one persisted file:
-`mcp/expose.json`.
-
-The architecture: many upstream MCPs each expose many tools; the
-aggregator connects to them and the **MCP Manager picks which tools to surface** to the CLI as
-*curated-direct* tools - alongside the four lean meta-tools (`toolfunnel_list_tools`,
-`toolfunnel_tool_instructions`, `toolfunnel_run_tool`, `toolfunnel_howto`). The CLI sees a small surface; everything
-else stays reachable through the register.
-
-
----
-
-## 1. `expose.json` - the two blocks
-
-`expose.json` persists (a) the upstream MCP connections and (b) the curated-direct selection drawn
-from them:
-
-```json
-{
-  "version": 1,
-  "upstreams": [
-    {
-      "id": "chat",
-      "transport": "stdio",
-      "command": "node",
-      "args": ["vendor/chat-mcp/server.js"],
-      "env": { "CHAT_DB": "..." },
-      "enabled": true,
-      "description": "Chat bridge MCP - chats, messages, send."
-    },
-    {
-      "id": "browser",
-      "transport": "stdio",
-      "command": "npx",
-      "args": ["@example/browser-mcp"],
-      "enabled": false,
-      "description": "Browser automation MCP."
-    }
-  ],
-  "expose": [
-    {
-      "upstream": "chat",
-      "tool": "list_chats",
-      "as": "chat_list_chats",
-      "category": "chat",
-      "enabled": true
-    },
-    {
-      "upstream": "chat",
-      "tool": "send_message",
-      "as": "chat_send_message",
-      "category": "chat",
-      "enabled": true
-    }
-  ]
-}
-```
-
-### `upstreams[]` - one entry per upstream MCP
-
-| Field | Type | Meaning |
-|---|---|---|
-| `id` | string | Stable key for this upstream. Referenced by `expose[].upstream`. Unique. |
-| `transport` | string | How the aggregator connects. `"stdio"` (spawn `command`+`args`) is the baseline. |
-| `command` / `args` / `env` | string / string[] / object | The process the aggregator spawns for a `stdio` upstream. The isolation guard refuses to connect an upstream whose path-shaped **args** (including `--flag=value` values), **cwd**, or code-loading **env** vars (`NODE_OPTIONS`, `NODE_PATH`, and their equivalents) reach outside the config home. (The `command` itself, an executable, is not guarded. Opt-outs, each warned loudly by name: the currently-WRAPPED upstream is exempt; `allowOutsidePaths: true` on the entry exempts its paths; `allowCodeLoadingEnv: true` exempts the env class.) |
-| `enabled` | boolean | Whether the aggregator connects to this upstream at startup. |
-| `description` | string | Human-facing note for the MCP Manager UI. |
-
-### `expose[]` - which upstream tools become curated-direct
-
-| Field | Type | Meaning |
-|---|---|---|
-| `upstream` | string | Must match an `upstreams[].id`. |
-| `tool` | string | The upstream tool's own name (as the upstream's `tools/list` reports it). |
-| `as` | string | The downstream name the CLI sees (namespaced so two upstreams can't collide, e.g. `chat_send_message`). Optional - defaults to `<upstream>_<tool>`. |
-| `category` | string | Grouping label, same convention as register entries. |
-| `enabled` | boolean | Whether this tool is actually exposed downstream right now. |
-
-Only the tools listed in `expose[]` with `enabled: true` are surfaced to the CLI as curated-direct
-tools. Everything else on the upstream stays connected but hidden - reachable, if needed, by adding
-an `expose` entry (no upstream reconnect required to *list*, though see §3 on the CLI surface).
-
----
-
-## 2. Steps to register an upstream and expose a tool
-
-1. Add an entry to `upstreams[]` with a unique `id`, the `stdio` `command`/`args`, and
-   `enabled: true`. Keep the server's path-shaped args **inside the config home** (vendor the
-   server in if it isn't already) - the isolation guard refuses args that escape it.
-2. Let the aggregator connect and run the upstream's `tools/list` (the MCP Manager UI surfaces the
-   discovered tools).
-3. For each tool you want hot, add an `expose[]` entry: `{ upstream, tool, as, category, enabled:true }`.
-4. Leave the long tail unexposed - the model can still reach those via the register/meta-tools if you
-   later mirror them, but the *curated-direct* surface stays lean by design (the dial in §1 of the
-   architecture: directly-exposed = the HOT tools; the register meta-tools = the long tail).
-
----
-
-## 3. Curated-direct vs. the register (update cost)
-
-This matters because the two layers refresh differently:
-
-- **Curated-direct tools** (what `expose[]` produces) are negotiated with the CLI **at connect time**.
-  Changing the exposed set therefore needs a **reconnect**, or a `notifications/tools/list_changed`
-  message *if the CLI honours it* (VERIFY per host; restart is the safe baseline).
-- **Register tools** (the `toolfunnel_list_tools`/`run` path) are **always live** - the model re-reads the
-  register on every `toolfunnel_list_tools` call, so no reconnect is needed.
-
-Rule of thumb: expose a handful of HOT, high-reliability tools curated-direct; everything else lives
-in the register and is reached through the meta-tools.
-
-> Safety: a curated-direct upstream tool is still ultimately invoked by the model. When you wire
-> upstream execution through the host, route it through the same PreToolUse gate the register's `run`
-> uses (see `toolfunnel_howto({ topic: "add-hook" })`) so the safety invariant holds uniformly. The gate
-> firing on every execution path is a tested invariant, not an assumption.
+# How to register an upstream MCP (self-extension)
+
+This is the instruction served by `toolfunnel_howto({ topic: "add-mcp" })`. It explains how to connect an
+**upstream MCP server** (a browser-automation MCP, a chat bridge, ...) to the aggregator and choose **which of its
+tools to expose downstream** to the CLI. All of this is configured in one persisted file:
+`mcp/expose.json`.
+
+The architecture: many upstream MCPs each expose many tools; the
+aggregator connects to them and the **MCP Manager picks which tools to surface** to the CLI as
+*curated-direct* tools - alongside the four lean meta-tools (`toolfunnel_list_tools`,
+`toolfunnel_tool_instructions`, `toolfunnel_run_tool`, `toolfunnel_howto`). The CLI sees a small surface; everything
+else stays reachable through the register.
+
+
+---
+
+## 1. `expose.json` - the two blocks
+
+`expose.json` persists (a) the upstream MCP connections and (b) the curated-direct selection drawn
+from them:
+
+```json
+{
+  "version": 1,
+  "upstreams": [
+    {
+      "id": "chat",
+      "transport": "stdio",
+      "command": "node",
+      "args": ["vendor/chat-mcp/server.js"],
+      "env": { "CHAT_DB": "..." },
+      "enabled": true,
+      "description": "Chat bridge MCP - chats, messages, send."
+    },
+    {
+      "id": "browser",
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["@example/browser-mcp"],
+      "enabled": false,
+      "description": "Browser automation MCP."
+    }
+  ],
+  "expose": [
+    {
+      "upstream": "chat",
+      "tool": "list_chats",
+      "as": "chat_list_chats",
+      "category": "chat",
+      "enabled": true
+    },
+    {
+      "upstream": "chat",
+      "tool": "send_message",
+      "as": "chat_send_message",
+      "category": "chat",
+      "enabled": true
+    }
+  ]
+}
+```
+
+### `upstreams[]` - one entry per upstream MCP
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | Stable key for this upstream. Referenced by `expose[].upstream`. Unique. |
+| `transport` | string | How the aggregator connects. `"stdio"` (spawn `command`+`args`) is the baseline. |
+| `command` / `args` / `env` | string / string[] / object | The process the aggregator spawns for a `stdio` upstream. The isolation guard refuses to connect an upstream whose path-shaped **args** (including `--flag=value` values), **cwd**, or code-loading **env** vars (`NODE_OPTIONS`, `NODE_PATH`, and their equivalents) reach outside the config home. (The `command` itself, an executable, is not guarded. Opt-outs, each warned loudly by name: the currently-WRAPPED upstream is exempt; `allowOutsidePaths: true` on the entry exempts its paths; `allowCodeLoadingEnv: true` exempts the env class.) |
+| `enabled` | boolean | Whether the aggregator connects to this upstream at startup. |
+| `description` | string | Human-facing note for the MCP Manager UI. |
+
+### `expose[]` - which upstream tools become curated-direct
+
+| Field | Type | Meaning |
+|---|---|---|
+| `upstream` | string | Must match an `upstreams[].id`. |
+| `tool` | string | The upstream tool's own name (as the upstream's `tools/list` reports it). |
+| `as` | string | The downstream name the CLI sees (namespaced so two upstreams can't collide, e.g. `chat_send_message`). Optional - defaults to `<upstream>_<tool>`. |
+| `category` | string | Grouping label, same convention as register entries. |
+| `enabled` | boolean | Whether this tool is actually exposed downstream right now. |
+
+Only the tools listed in `expose[]` with `enabled: true` are surfaced to the CLI as curated-direct
+tools. Everything else on the upstream stays connected but hidden - reachable, if needed, by adding
+an `expose` entry (no upstream reconnect required to *list*, though see §3 on the CLI surface).
+
+---
+
+## 2. Steps to register an upstream and expose a tool
+
+1. Add an entry to `upstreams[]` with a unique `id`, the `stdio` `command`/`args`, and
+   `enabled: true`. Keep the server's path-shaped args **inside the config home** (vendor the
+   server in if it isn't already) - the isolation guard refuses args that escape it.
+2. Let the aggregator connect and run the upstream's `tools/list` (the MCP Manager UI surfaces the
+   discovered tools).
+3. For each tool you want hot, add an `expose[]` entry: `{ upstream, tool, as, category, enabled:true }`.
+4. Leave the long tail unexposed - the model can still reach those via the register/meta-tools if you
+   later mirror them, but the *curated-direct* surface stays lean by design (the dial in §1 of the
+   architecture: directly-exposed = the HOT tools; the register meta-tools = the long tail).
+
+---
+
+## 3. Curated-direct vs. the register (update cost)
+
+This matters because the two layers refresh differently:
+
+- **Curated-direct tools** (what `expose[]` produces) are negotiated with the CLI **at connect time**.
+  Changing the exposed set therefore needs a **reconnect**, or a `notifications/tools/list_changed`
+  message *if the CLI honours it* (VERIFY per host; restart is the safe baseline).
+- **Register tools** (the `toolfunnel_list_tools`/`run` path) are **always live** - the model re-reads the
+  register on every `toolfunnel_list_tools` call, so no reconnect is needed.
+
+Rule of thumb: expose a handful of HOT, high-reliability tools curated-direct; everything else lives
+in the register and is reached through the meta-tools.
+
+> Safety: a curated-direct upstream tool is still ultimately invoked by the model. When you wire
+> upstream execution through the host, route it through the same PreToolUse gate the register's `run`
+> uses (see `toolfunnel_howto({ topic: "add-hook" })`) so the safety invariant holds uniformly. The gate
+> firing on every execution path is a tested invariant, not an assumption.