toolfunnel 0.3.0

package/src/core/tool-registry.js

@@ -0,0 +1,180 @@
+'use strict';
+
+/**
+ * tool-registry.js — backend-agnostic tool catalogue for the host loop.
+ *
+ * The host asks the registry for tool definitions to hand to a backend
+ * (see ARCHITECTURE.md: `backend.send({ system, messages, tools })`). When the
+ * model requests a tool by name, the host executes it here. The registry holds
+ * NO host imports so it runs headless under `node --test`.
+ *
+ * A tool is registered as: register(name, { description, inputSchema, run })
+ *   - description: human/model-facing string
+ *   - inputSchema: a JSON-schema-ish object describing the input (handed to the backend)
+ *   - run(input): the implementation; may be sync or async; its return value is the result
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+class ToolRegistry {
+  constructor() {
+    // name -> { description, inputSchema, run }
+    this._tools = new Map();
+  }
+
+  /**
+   * Register a tool under a unique name.
+   * Throws on a bad shape so misconfiguration is caught at wiring time, not at
+   * model-call time (the loop must never receive a half-formed tool).
+   *
+   * @param {string} name
+   * @param {{ description?: string, inputSchema?: object, run: (input:any)=>any }} def
+   * @returns {ToolRegistry} this (for chaining)
+   */
+  register(name, def) {
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new Error('ToolRegistry.register: name must be a non-empty string');
+    }
+    if (!def || typeof def !== 'object') {
+      throw new Error(`ToolRegistry.register("${name}"): definition object is required`);
+    }
+    if (typeof def.run !== 'function') {
+      throw new Error(`ToolRegistry.register("${name}"): "run" must be a function`);
+    }
+    if (this._tools.has(name)) {
+      throw new Error(`ToolRegistry.register("${name}"): tool already registered`);
+    }
+    this._tools.set(name, {
+      description: typeof def.description === 'string' ? def.description : '',
+      // Default to an open object schema so a tool without a declared schema
+      // still produces a valid definition for the backend.
+      inputSchema:
+        def.inputSchema && typeof def.inputSchema === 'object'
+          ? def.inputSchema
+          : { type: 'object', properties: {} },
+      run: def.run,
+    });
+    return this;
+  }
+
+  /** @param {string} name @returns {boolean} */
+  has(name) {
+    return this._tools.has(name);
+  }
+
+  /**
+   * Execute a registered tool by name. Always returns a Promise so the host
+   * loop can `await` uniformly regardless of whether `run` was sync or async.
+   * Throws a clear error if the tool is unknown (the host turns this into a
+   * tool result / PostToolUse feedback rather than crashing the loop).
+   *
+   * @param {string} name
+   * @param {any} input
+   * @returns {Promise<any>} the tool's result
+   */
+  async execute(name, input) {
+    const tool = this._tools.get(name);
+    if (!tool) {
+      const known = this.list().map((t) => t.name);
+      throw new Error(
+        `ToolRegistry.execute: unknown tool "${name}". ` +
+          `Registered tools: ${known.length ? known.join(', ') : '(none)'}`
+      );
+    }
+    // Await covers both sync return values and returned Promises.
+    return await tool.run(input);
+  }
+
+  /**
+   * Tool definitions array, shaped for handing to a backend:
+   * `[{ name, description, inputSchema }]`. The `run` function is deliberately
+   * omitted — the backend never needs (or should see) the implementation.
+   *
+   * @returns {Array<{ name: string, description: string, inputSchema: object }>}
+   */
+  list() {
+    const out = [];
+    for (const [name, tool] of this._tools) {
+      out.push({
+        name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      });
+    }
+    return out;
+  }
+}
+
+/**
+ * makeDemoRegistry — a ToolRegistry preloaded with two demo tools used by the
+ * host tests (host.test.js drives the lifecycle through these).
+ *
+ *   echo               — returns its input unchanged (trivial, deterministic).
+ *   readFileSandboxed  — reads a UTF-8 file, but ONLY within `sandboxRoot`,
+ *                        rejecting any path that escapes the sandbox. This is
+ *                        the same defense-in-depth posture the hook loader's
+ *                        writeScript guard uses (HOOK_ENGINE.md §8) — a tool the
+ *                        model can call must not become a filesystem escape.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.sandboxRoot=process.cwd()] absolute root for readFileSandboxed
+ * @returns {ToolRegistry}
+ */
+function makeDemoRegistry(opts) {
+  const sandboxRoot = path.resolve((opts && opts.sandboxRoot) || process.cwd());
+  const registry = new ToolRegistry();
+
+  registry.register('echo', {
+    description: 'Returns its input unchanged. Useful for testing the tool loop.',
+    inputSchema: {
+      type: 'object',
+      description: 'Any JSON value passed through as-is.',
+      properties: {},
+      additionalProperties: true,
+    },
+    run: (input) => input,
+  });
+
+  registry.register('readFileSandboxed', {
+    description:
+      'Reads a UTF-8 text file located within the sandbox root. ' +
+      'Rejects absolute paths and any relative path that escapes the sandbox.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Path to read, relative to the sandbox root.',
+        },
+      },
+      required: ['path'],
+    },
+    run: (input) => {
+      const requested = input && input.path;
+      if (typeof requested !== 'string' || requested.length === 0) {
+        throw new Error('readFileSandboxed: "path" (non-empty string) is required');
+      }
+      // Reject absolute paths outright; everything must be relative to the sandbox.
+      if (path.isAbsolute(requested)) {
+        throw new Error(
+          `readFileSandboxed: absolute paths are not allowed ("${requested}")`
+        );
+      }
+      // Resolve against the sandbox, then confirm the result is still inside it.
+      const resolved = path.resolve(sandboxRoot, requested);
+      const rel = path.relative(sandboxRoot, resolved);
+      // rel starting with ".." (or an absolute path on a different drive) means escape.
+      if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new Error(
+          `readFileSandboxed: path escapes sandbox root ("${requested}")`
+        );
+      }
+      return fs.readFileSync(resolved, 'utf8');
+    },
+  });
+
+  return registry;
+}
+
+module.exports = { ToolRegistry, makeDemoRegistry };

package/src/extend/add-hook.md

@@ -0,0 +1,142 @@
+# 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`. The full contract is HOOK_ENGINE.md — 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.
+Two protocols (HOOK_ENGINE.md §3):
+
+**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.
+- 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.

package/src/extend/add-mcp.md

@@ -0,0 +1,121 @@
+# 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 (see the architecture overview, §1): 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.
+
+> Phase note: the live aggregator (`src/mcp/aggregator.js`) is Phase 2. This doc defines the
+> `expose.json` shape so the config is authorable now and the aggregator reads exactly these fields
+> when it lands.
+
+---
+
+## 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. Paths must point **inside the project's vendor directory** (clone vendored servers in; never reference servers configured elsewhere on the host). |
+| `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`. Vendor the server **inside the project's vendor directory** if it isn't already.
+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 (see the architecture overview, §1):
+
+- **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.

package/src/extend/create-tool.md

@@ -0,0 +1,132 @@
+# How to add a tool (self-extension)
+
+This is the instruction served by `toolfunnel_howto({ topic: "create-tool" })`. It tells you — the
+model — how to add a new tool to the register so it becomes callable through `toolfunnel_run_tool`
+(and listable via `toolfunnel_list_tools` / `toolfunnel_tool_instructions`). No restart is needed: the register
+is read live every time the meta-tools are called.
+
+A tool is exactly two things:
+1. **A register entry** in `tools/tools.register.json` (structured metadata + how to invoke it).
+2. **A script** under `tools/scripts/` that the entry's `invoke` points at (only for
+   `invoke.type === "script"`; a `shell` tool needs no file).
+
+---
+
+## 1. The register entry shape
+
+`tools.register.json` is a JSON file with one top-level array of entries. Each entry:
+
+```json
+{
+  "id": "echo-upper",
+  "name": "Echo Upper",
+  "summary": "Uppercases the supplied text and echoes it back.",
+  "category": "demo",
+  "instructions": "Pass { text: string }. Returns the text uppercased. Use this only as a sanity check of the run path.",
+  "invoke": { "type": "script", "path": "scripts/echo-upper.sh" }
+}
+```
+
+Field-by-field — these names are fixed (registry.js reads exactly these):
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | Stable unique key, kebab-case. `toolfunnel_run_tool({ name })` and `registry.run(id, args)` look up by this. Never reuse an existing `id`. |
+| `name` | string | Human/model-facing display name. Shown in the manager UI. |
+| `summary` | string | One line. This is ALL that `toolfunnel_list_tools` returns for the tool — keep it tight and discriminating so the model can pick the right tool from the brief alone. |
+| `category` | string | Grouping label (e.g. `demo`, `memory`, `messaging`, `media`). Used by `toolfunnel_list_tools({ category })` to filter. |
+| `instructions` | string | Full usage doc returned by `toolfunnel_tool_instructions({ name })`. Describe the args object, what comes back, and any safety caveats. This is the long-tail payload — be complete here, terse in `summary`. |
+| `invoke` | object | How `run` executes the tool. See below. |
+
+### The `invoke` object — two forms
+
+```json
+{ "type": "script", "path": "scripts/echo-upper.sh" }
+```
+- `type: "script"` — run a file under `tools/scripts/`. `path` is **relative to `tools/`**
+  and MUST stay inside `tools/scripts/` (registry.js path-guards it, same defense-in-depth as the
+  hook loader's `writeScript`). The args object is delivered to the script (e.g. as a JSON blob on
+  stdin or argv per the registry's convention) and the script's stdout is the tool output.
+
+```json
+{ "type": "shell", "command": "node \"${TOOLS_DIR}/scripts/echo-upper.js\"" }
+```
+- `type: "shell"` — run a command line. `${TOOLS_DIR}` expands to the absolute `tools` path at run
+  time (mirrors `${HOOKS_DIR}` in the hook manifest). Prefer `script` for anything reusable; reserve
+  `shell` for thin one-liners.
+
+> Isolation rule: an `invoke` must only reference scripts/commands that live **inside the gateway's
+> own tree**. Never point `invoke` at a live tool that lives outside it (e.g. in a host's external
+> tool directory). If you want an external tool's behaviour, clone its script into
+> `tools/scripts/` first, then point at the clone.
+
+---
+
+## 2. Where the script goes
+
+```
+tools/
+  tools.register.json    # the entries (above)
+  scripts/               # your tool scripts live HERE and nowhere else
+    echo-upper.sh
+```
+
+(`registry.js` — the engine that loads/persists the register and runs list/instructions/run — is
+NOT user content. It lives in `src/tools/registry.js` and is not part of this tree.)
+
+The script reads its arguments (the `args` object passed to `run`) and writes its result to stdout.
+Exit non-zero with a message on stderr to signal failure — the registry surfaces that as the tool's
+error. Keep scripts pure and side-effect-honest: anything destructive is exactly what the PreToolUse
+gate exists to catch (next section).
+
+---
+
+## 3. How `run` works — and why it is gated
+
+`toolfunnel_run_tool({ name, args })` does **not** execute the script directly. It calls
+`registry.run(id, args)`, which routes the call through the gateway's **hook engine** before — and after —
+the tool actually runs:
+
+```
+toolfunnel_run_tool(name, args)
+        │
+        ▼
+  registry.run(id, args)
+        │
+        ├─► hookEngine.fire("PreToolUse", ctx, { tool_name, tool_input: args })
+        │        └─ if result.blocked  → STOP. Return { ok:false, error: <reason> }. Script never runs.
+        │
+        ├─► execute the invoke (script/shell) only if NOT blocked
+        │
+        └─► hookEngine.fire("PostToolUse", ctx, { tool_name, tool_input: args, tool_response })
+                 └─ feedback only; the tool already ran (cannot un-run it)
+```
+
+- **The PreToolUse gate is the whole safety case.** A hook denies a call by returning, on exit 0,
+  `{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny",
+  "permissionDecisionReason": "…" } }` — OR by `exit 2` with the reason on stderr. (PreToolUse uses
+  `permissionDecision`, NOT a top-level `decision` — see HOOK_ENGINE.md §3.) When that fires,
+  `run` returns an error result and the script is never spawned.
+- `permissionDecision: "allow"` passes; `"ask"` is non-blocking in the autonomous host (no
+  interactive prompt) — the reason is captured but the tool proceeds.
+- The result shape `run` returns matches the meta-tool contract: `{ ok, output, error? }`.
+
+So adding a tool grants real power, but every invocation is mediated by the same gate that protects
+every other tool. If your new tool is dangerous, the correct control is a PreToolUse hook that
+matches its `tool_name` (see `toolfunnel_howto({ topic: "add-hook" })`), not omitting the tool.
+
+---
+
+## 4. Steps to add a tool
+
+1. Pick a unique `id` (check `toolfunnel_list_tools` first so you don't collide).
+2. If `invoke.type === "script"`, write the script into `tools/scripts/<id>.sh` (or `.js`).
+3. Add the entry to the `tools.register.json` array (via `registry.js`'s add/edit path so the write
+   is atomic — never hand-edit and risk a torn file).
+4. Confirm with `toolfunnel_list_tools` (your `summary` appears) and `toolfunnel_tool_instructions({ name })`
+   (your `instructions` appear).
+5. Test with `toolfunnel_run_tool({ name, args })`. Verify the gate behaves: a benign call returns
+   `{ ok:true, output }`; if a matching PreToolUse hook should deny it, confirm it does.
+
+No reconnect is needed — the register is dynamic. (Only *curated-direct* tools negotiated at MCP
+connect need a reconnect; register tools reached via the meta-tools are always live.)

package/src/extend/howto.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * howto.js — the loader behind the `toolfunnel_howto` meta-tool (architecture notes §2 + §6).
+ *
+ * `toolfunnel_howto({ topic })` returns the self-extension instructions for one topic. This module
+ * resolves a topic to its authored markdown file (the topic -> file map below) and reads it.
+ *
+ *   howto(topic) -> string   // the markdown content for that topic
+ *
+ * Topics (the four documented in §2): create-tool | add-mcp | add-hook | package.
+ * Unknown topics THROW (the protocol layer turns that into a clean tool error, not a crash).
+ *
+ * Isolation: reads are confined to THIS directory (src/extend). The topic map is a fixed
+ * allow-list of basenames — there is no path interpolation from the caller, so a malicious
+ * `topic` cannot traverse out of src/extend. We additionally re-verify the resolved path is
+ * inside this directory (defense-in-depth, mirroring the hook loader's writeScript guard).
+ *
+ * CommonJS only. Node built-ins only. No transport, pure file read — unit-testable directly.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// The directory these instruction files live in (this module's own directory).
+const EXTEND_DIR = __dirname;
+
+/**
+ * Fixed topic -> filename map. The set of keys IS the list of valid topics; the values are
+ * plain basenames (no separators) so nothing the caller passes is ever joined into a path.
+ * @type {Readonly<Record<string,string>>}
+ */
+const TOPIC_FILES = Object.freeze({
+  'create-tool': 'create-tool.md',
+  'add-mcp': 'add-mcp.md',
+  'add-hook': 'add-hook.md',
+  package: 'package.md',
+});
+
+/**
+ * The valid topic names, for error messages and for callers that want to enumerate
+ * (e.g. the protocol layer validating args, or a UI listing the howto topics).
+ * @returns {string[]}
+ */
+function topics() {
+  return Object.keys(TOPIC_FILES);
+}
+
+/**
+ * Resolve a topic to the instruction markdown content.
+ *
+ * @param {string} topic one of: create-tool | add-mcp | add-hook | package
+ * @returns {string} the UTF-8 markdown content of the matching file
+ * @throws {Error} if `topic` is not a string, is unknown, or (defensively) resolves outside
+ *                 src/extend or the file is missing.
+ */
+function howto(topic) {
+  if (typeof topic !== 'string' || topic.length === 0) {
+    throw new Error(
+      `howto: topic must be a non-empty string. Known topics: ${topics().join(', ')}`
+    );
+  }
+
+  // Look up against the fixed allow-list — own property only (guards against "constructor",
+  // "__proto__", etc. resolving via the prototype chain).
+  if (!Object.prototype.hasOwnProperty.call(TOPIC_FILES, topic)) {
+    throw new Error(
+      `howto: unknown topic "${topic}". Known topics: ${topics().join(', ')}`
+    );
+  }
+
+  const fileName = TOPIC_FILES[topic];
+  const filePath = path.join(EXTEND_DIR, fileName);
+
+  // Defense-in-depth: confirm the resolved path is still inside EXTEND_DIR. With a fixed
+  // basename map this can never fail, but the guard documents and enforces the isolation rule.
+  const rel = path.relative(EXTEND_DIR, filePath);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`howto: refusing to read outside src/extend ("${fileName}")`);
+  }
+
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    // A known topic whose file is missing is a packaging error, not an unknown-topic error.
+    throw new Error(
+      `howto: instruction file for topic "${topic}" is missing or unreadable ` +
+        `(${filePath}): ${(err && err.message) || String(err)}`
+    );
+  }
+}
+
+module.exports = {
+  howto,
+  topics,
+  TOPIC_FILES,
+  EXTEND_DIR,
+};