toolfunnel 0.5.0 → 0.6.0

package/docs/KNOWN_BUGS.md

@@ -1,33 +1,99 @@
-# Known issues & roadmap
-
-ToolFunnel has no known correctness bugs at this release. This file tracks the upcoming
-compatibility work and any limitations worth knowing about.
-
-## Coming in 0.6.0 — the 2026-07-28 MCP specification
-
-The 2026-07-28 MCP revision is a **breaking** change to the protocol: it removes the `initialize`
-handshake, protocol-level sessions, and the standalone GET/SSE endpoint, and adds new required
-behaviours — per-request protocol metadata, `Mcp-Method` / `Mcp-Name` request headers, a
-`server/discover` endpoint, a `subscriptions/listen` change-notification stream, and
-`resultType` / `ttlMs` / `cacheScope` result fields.
-
-ToolFunnel 0.5.0 speaks the current `2024-11-05` protocol and works with every MCP client shipping
-today. **0.6.0** will add **dual-era** support — answering both the current handshake-based clients
-*and* the 2026-07-28 modern clients — built against the finalised spec after 28 July.
-
-Planned for 0.6.0:
-
-- **Dual-era transport** (current + 2026-07-28) so old and new clients both keep working.
-- `server/discover`, the new request-header validation, and the `subscriptions/listen` stream.
-- An **opt-in, per-upstream legacy-protocol shim**: keep an ageing MCP server working past the
-  cutover by pinning the protocol version ToolFunnel speaks *to that upstream* — off by default,
-  it names the exact version it drops to and warns at startup and on every call.
-
-## Current limitations
-
-- The OAuth 2.1 resource-server and Streamable-HTTP support are recent and less battle-tested than
-  the core — test your setup before relying on them in a networked deployment.
-- No Prometheus / OpenTelemetry metrics — a toggleable JSONL audit log and in-memory `/health`
-  call counters only.
-
-Found a bug, or want to help with the 0.6.0 work? Issues and PRs are welcome.
+# Known issues & roadmap
+
+This file tracks the state of the 0.6.0 dual-era work, the deliberately-deferred items, and any
+limitations worth knowing about.
+
+## 0.6.0 - the 2026-07-28 MCP specification
+
+The 2026-07-28 MCP revision is a **breaking** change to the protocol: it removes the `initialize`
+handshake, protocol-level sessions, and the standalone GET/SSE endpoint, and adds new required
+behaviours - per-request protocol metadata, `Mcp-Method` / `Mcp-Name` request headers, a
+`server/discover` endpoint, a `subscriptions/listen` change-notification stream, and
+`resultType` / `ttlMs` / `cacheScope` result fields.
+
+Implemented in 0.6.0 (built against the RC spec; a reconciliation pass against the finalised
+spec lands after 28 July):
+
+- **Dual-era transport** (2024-11-05 + 2026-07-28) - old and new clients both work.
+- `server/discover`, request-header validation, and the `subscriptions/listen` stream.
+- A **dual-era client**: ToolFunnel speaks modern to modern upstream servers (stdio).
+- An **opt-in, per-upstream legacy-protocol shim** (`legacyPin`) - off by default, names the exact
+  version it drops to, warns at startup and on every call, and is enforced (skips the era probe).
+- **Passthrough wrap** (`toolfunnel wrap <upstreamId>`): one command turns the gateway into a
+  transparent, both-era wrapper for one upstream MCP - verbatim identity, tool definitions,
+  results, errors, notifications, and per-URI resource subscriptions (forwarded, and replayed
+  across silent upstream reconnects), with every call still passing the PreToolUse gate.
+- **Elicitation bridging**: a wrapped legacy server's mid-call questions are translated into the
+  modern `input_required` + retry pattern and back - multi-round, single-use tokens, TTL'd -
+  tested end-to-end against real published elicitation servers.
+- **Cancel translation** (stdio): a client's cancel reaches the upstream in the upstream's own
+  request-id space, for forwarded methods and wrapped tool calls alike.
+- **Identity settings + wrap mirroring**: `toolfunnel.json` gains `clientName`/`clientVersion`
+  (the identity upstreams see); under a wrap on stdio the real downstream client's identity is
+  mirrored upstream automatically.
+- **UI**: a Settings tab (identity + ports), a per-upstream legacy-pin toggle, and the wrap
+  security notice surfaced on the UI wrap path (parity with the CLI).
+- **Agent-facing docs**: `toolfunnel_howto` gains `wrap` and `configure` topics, so a plain agent
+  can learn the wrap and the whole no-code config map from inside the protocol.
+- **Method-class timeouts**: tool calls (`tools/call`, `prompts/get`, `resources/read`) wait
+  120 s by default - configurable per upstream via `"timeoutMs"` - and a progress report from
+  the tool re-arms the window, so a slow-but-alive tool never dies to the clock. The 10 s
+  handshake/list window stays fixed as the dead-upstream detector.
+- **Async shell execution**: `shell`-invoke register tools no longer block the event loop
+  (was `spawnSync` since 0.5.0) - concurrent HTTP clients keep being served during a long
+  shell tool.
+- **Config-home visibility**: every start prints the resolved config home to stderr, with a
+  relocation hint when it defaulted to the package root - running from a git clone no longer
+  writes config into the repo silently.
+- **Bounded listen streams**: the HTTP transport caps concurrent `subscriptions/listen`
+  streams (64) and refuses new ones past the cap with a clear error; existing streams are
+  never evicted.
+
+## Deliberately deferred (documented dispositions, target: the 28-July reconciliation pass)
+
+- **Legacy version family**: ToolFunnel currently speaks the oldest legacy dialect (`2024-11-05`)
+  to legacy upstreams and clamps a wrapped handshake to what the upstream negotiated. A client and
+  upstream that both speak a newer legacy revision (e.g. `2025-06-18`) are negotiated down.
+  Fidelity of the *fields* is unaffected (verified against real servers - nothing version-gated is
+  dropped), but the advertised version string is older than either end requires. DECIDED
+  (2026-07-17): best-version negotiation in BOTH directions - newest each peer speaks, modern
+  first, legacy fallback. Lands with the reconciliation pass, sequenced after the elicitation
+  bridge (a newer legacy offer invites server-initiated requests the client must handle first).
+- **Modern-upstream subscriptions**: the client does not yet open a `subscriptions/listen` stream
+  to modern upstreams, so their change-notifications are not received; the listen ack honestly
+  refuses `resourceSubscriptions` when no legacy subscribe-capable upstream is in scope.
+- **Elicitation bridge scope**: a wrapped upstream's mid-call `elicitation/create` bridges to
+  modern clients as MRTR (`input_required` + retry - built and wire-tested). A LEGACY client
+  gets an automatic decline instead (relaying backwards requests to legacy clients is future
+  work), and `sampling/createMessage` / `roots/list` from upstreams are answered -32601 for now.
+  An elicitation can only be bound to a call when exactly ONE wrapped call is in flight for that
+  upstream (always true on stdio); ambiguous concurrent HTTP calls decline rather than guess.
+- Header validation reports `-32020` where `-32022` would be more specific in one path.
+- Two-store wrap state read (expose.json + tools.state.json) has a benign TOCTOU window.
+- A meta-less `server/discover` is answered rather than refused (permissive-by-design).
+- The wrap's identity-mirror reconnect re-runs the full era negotiation - worst case ~3 s extra
+  on the first handshake against an upstream that ignores `server/discover`. Reusing the
+  already-known era on reconnect is a deferred optimisation.
+- HTTP cancel translation: the sessionless modern era gives a POST no connection identity, so a
+  client `notifications/cancelled` over HTTP is dropped rather than risk cancelling another
+  client's call. stdio (one client per pipe) translates and forwards cancels for both forwarded
+  methods and wrapped tools/call; the remaining best-effort windows are sub-millisecond (a cancel
+  racing the instant a forward is issued) plus the PreToolUse gate-evaluation phase of a tool
+  call (registered at upstream-issue time, post-gate).
+- `io.modelcontextprotocol/logLevel` (the modern per-request log level) is stripped with the rest
+  of the protocol `_meta` keys on wrapped forwards and not re-injected for modern upstreams -
+  part of the modern-upstream work above.
+- Discover on a DISABLED upstream works (inspect its tools before enabling - an explicit
+  allowance on the discover path only; the disabled upstream never reaches the tool surface).
+
+## Current limitations
+
+- The OAuth 2.1 resource-server and Streamable-HTTP support are recent and less battle-tested than
+  the core - test your setup before relying on them in a networked deployment.
+- No Prometheus / OpenTelemetry metrics - a toggleable JSONL audit log and in-memory `/health`
+  call counters only.
+- One gateway instance per process: the bridge/cancel state is process-global, so embedding two
+  gateway instances in one Node process is not a supported configuration (running two processes
+  is fine, and is the normal deployment).
+
+Found a bug, or want to help with the 0.6.0 work? Issues and PRs are welcome.

package/docs/design.md

@@ -0,0 +1,70 @@
+# Design decisions
+
+Short notes on the decisions that shape ToolFunnel, so you can judge the reasoning without
+reading the source. Each one is also documented at the place in the code where it bites.
+
+## 1. Zero runtime dependencies
+
+ToolFunnel sits in a privileged position: it executes tools and enforces policy. Every
+transitive dependency in that position is something you have to trust or audit. So the gateway
+uses Node built-ins only; "dependencies" in package.json is empty and stays empty. The one
+exception is deliberate and opt-in: OAuth token validation uses jose, installed only when you
+run `toolfunnel install-oauth`, version-pinned, because hand-rolled JWT crypto is how security
+holes are born. Dev tooling for the test suite (jose, the MCP SDK for interop tests) never
+ships.
+
+## 2. No SDK
+
+The gateway hand-rolls JSON-RPC over stdio and HTTP rather than building on the official MCP
+SDK. Two reasons. First, the zero-dependency stance above. Second, ToolFunnel has to speak two
+protocol eras at once, on both sides, which the SDK does not do; owning the wire layer is what
+makes the dual-era serving and the wrap possible at all.
+
+## 3. The gate fails closed
+
+Every server-side execution path goes through one function, gatedRun, and that function treats
+every failure as a deny: a hook that blocks, a hook engine that crashes, a malformed engine
+result, all of them mean the tool does not run. Denies carry a flag distinguishing operator
+policy ("your hook said no") from wiring failure ("the gate itself broke"), so a broken gate
+can never be mistaken for an approving one. The invariant has its own test.
+
+## 4. The isolation boundary
+
+Upstream server definitions can name any executable but their path-shaped arguments must stay
+inside the config home. The command is the interpreter you chose; the args are what it can
+reach, so the args are what the guard checks. Wrapping suspends the guard for the wrapped
+server only, because a wrap is an explicit statement that this one server is your entire
+surface, and it warns you when that happens.
+
+## 5. Two eras, served per request
+
+The 2026-07-28 revision removes the handshake that defines the older protocol, so "which era"
+is a property of each request, and that is how the gateway treats it: era detection per
+request, no mode switch, no configuration. Legacy answers stay byte-identical to what a
+pre-0.6.0 client saw; the gateway's own modern decoration only ever appears on modern
+requests. (A wrapped modern upstream's results are relayed verbatim, whatever era the
+caller speaks - stripping a server's own fields would be data loss and a wrapper tell.)
+
+## 6. Config lives in one folder
+
+Everything mutable (tools, upstreams, hooks, identity, logs) lives in the config home,
+relocatable with `--config-dir` or `TOOLFUNNEL_HOME`, seeded once, never overwritten by
+updates. One folder to back up, one folder to package, one folder to hand a colleague. The
+gateway prints the resolved home at every start so there is never any doubt about where state
+lives.
+
+## 7. Single operator by design
+
+Each ToolFunnel instance serves one operator. That is a decision, not an oversight: one
+instance per user gives process isolation, crash containment, per-user wrap state, and a
+security boundary you can reason about in one sentence. Multi-user deployment composes *in
+front of* the gateway rather than inside it - an authenticating proxy at the OAuth boundary
+(ToolFunnel is already an OAuth 2.1 resource server) routing each authenticated user to their
+own instance, with the per-request `_meta` lane carrying user context through to upstreams
+that want it. Nothing in the core couples the operator to a token subject, so that door stays
+open without the core ever growing user-shaped complexity.
+
+A Team edition built on this pattern - per-user identity, audit trails, quotas, per-user
+policy - is on the roadmap if there is interest. If your team wants that sooner, or you need a
+bespoke gateway built on ToolFunnel for your own requirements, open an issue on this
+repository titled `enquiry` - tailored builds are available.

package/docs/packaging.md

@@ -1,115 +1,115 @@
-# Packaging: ship what you built
-
-ToolFunnel's config is a folder. That single fact is the whole packaging story: everything you
-build in a gateway — your tools and their scripts, which of them are promoted hot or hidden, the
-upstream MCPs you attached and the tools you chose to expose from them, the policy hooks that gate
-every call, and the identity the server introduces itself with — lives in one directory tree, the
-**config home**. Ship the tree and you have shipped the product.
-
-## The config home
-
-By default the home is the package/clone root — a git clone works exactly as it always did. Point
-the gateway elsewhere and the config lives there instead:
-
-```
-toolfunnel --config-dir D:\my-setup     # flag (wins)
-TOOLFUNNEL_HOME=D:\my-setup toolfunnel  # env var
-```
-
-An empty home is **seeded** on first use from the shipped defaults (the register + management
-scripts, an empty `mcp/expose.json`, the default hooks manifest) and is **never overwritten**
-afterwards — which is the point: with the home outside the package, `npm update toolfunnel`
-can never eat your tools.
-
-```
-<home>/
-  toolfunnel.json         # identity (serverName/serverVersion), port defaults, `requires`
-  tools/
-    tools.register.json   # your tool entries (incl. their inputSchema)
-    tools.state.json      # the hot/hidden/enabled curation — part of the product
-    scripts/              # the tool scripts
-  mcp/expose.json         # upstream references + curated exposure
-  hooks/                  # the policy gate: manifest + hook scripts
-```
-
-## `tf_pack` — one call to a deployment artifact
-
-The `tf_pack` management tool snapshots the LIVE setup into `<home>/dist/<name>/` — always a
-separate location, never the live tree. `auth/` (environment-specific) and `logs/` never ship.
-
-**`{ format: "home" }`** → a portable config home. Zip it, commit it to a repo, or run it as-is:
-
-```
-toolfunnel --config-dir path/to/the-pack
-```
-
-**`{ format: "npm", name: "my-mcp", version: "1.0.0" }`** → a publishable npm package:
-
-```
-dist/my-mcp/
-  package.json      # name, bin, files, dependencies: { "toolfunnel": "^0.4.0" }
-  bin/my-mcp.js     # 2 lines: pin --config-dir at ../home, delegate to toolfunnel
-  home/             # the bundled config home (identity rewritten to my-mcp@1.0.0)
-  README.md         # a stub to make your own
-```
-
-Review it, then `cd dist/my-mcp && npm publish`. Your users run `npx my-mcp` and get **your**
-server: your name in the MCP `initialize` handshake, your tools with your schemas, your curation,
-and — the part nobody else can say — **your gate**. The hooks travel inside the pack and enforce
-your policy on the recipient's machine regardless of which MCP client calls it.
-
-### Depend, never copy
-
-The generated package **depends on** `toolfunnel` (caret range) rather than vendoring it. Your own
-runtime dependencies go in **your** `package.json` exactly as with any npm package — npm installs
-the whole tree on `npx my-mcp`; toolfunnel itself adds zero. Why depending matters:
-
-- security and bug fixes reach every wrapped MCP through a normal `npm update` — no stale forks
-  carrying old bugs;
-- your package stays a few KB of config instead of a copied engine;
-- (and honestly) every install of your MCP counts as a toolfunnel download, which keeps the thing
-  you depend on alive.
-
-Your users can move the bundled home out of `node_modules` (so *their* edits survive *your*
-updates) via the `<NAME>_HOME` env var the generated launcher supports.
-
-## Declaring runtimes: `requires`
-
-Your tools may need runtimes the gateway doesn't (python, git, ffmpeg…). Declare them in the
-home's `toolfunnel.json` and they travel with every pack:
-
-```json
-{
-  "serverName": "my-mcp",
-  "requires": [
-    { "command": "python", "min": "3.10", "why": "the pdf-extract tools" },
-    { "command": "git" }
-  ]
-}
-```
-
-The gateway probes them once at startup and prints one clear stderr line per problem — found
-version vs needed, plus your `why`. Advisory by design: a missing runtime breaks only the tools
-that need it, so the server still starts and everything else keeps working.
-
-## Composite packs
-
-A pack is not just your own scripts. Because `mcp/expose.json` lives in the home, a pack carries
-**upstream references too**: "attach `@example/weather-mcp` (pin the version) and expose exactly
-these four tools under these names." The upstream itself travels as a *reference* — `npx` fetches
-it on the recipient's machine — while your **curation** and your **gate** travel as config. One
-pack = your tools + other people's servers, curated, renamed, and policed, as a single artifact.
-
-## Audit honesty
-
-Packs spawn commands — that is what they are for. Before you run anyone's pack (including one of
-ours), read **three files** — every command it can run is declared in plain JSON:
-
-- `tools/tools.register.json` — the tool invokes (scripts and shell commands);
-- `mcp/expose.json` — the upstream server commands it will spawn;
-- `toolfunnel.json` — the `requires` probes. Note these run **at gateway startup** (each declared
-  program is executed once with its version flag), which is why a `requires` command must be a
-  bare program name — the gateway rejects paths, spaces, and shell characters outright.
-
-Ship your own packs expecting the same scrutiny, and say so in your README (the `tf_pack` stub
-already does).
+# Packaging: ship what you built
+
+ToolFunnel's config is a folder. That single fact is the whole packaging story: everything you
+build in a gateway - your tools and their scripts, which of them are promoted hot or hidden, the
+upstream MCPs you attached and the tools you chose to expose from them, the policy hooks that gate
+every call, and the identity the server introduces itself with - lives in one directory tree, the
+**config home**. Ship the tree and you have shipped the product.
+
+## The config home
+
+By default the home is the package/clone root - a git clone works exactly as it always did. Point
+the gateway elsewhere and the config lives there instead:
+
+```
+toolfunnel --config-dir D:\my-setup     # flag (wins)
+TOOLFUNNEL_HOME=D:\my-setup toolfunnel  # env var
+```
+
+An empty home is **seeded** on first use from the shipped defaults (the register + management
+scripts, an empty `mcp/expose.json`, the default hooks manifest) and is **never overwritten**
+afterwards - which is the point: with the home outside the package, `npm update toolfunnel`
+can never eat your tools.
+
+```
+<home>/
+  toolfunnel.json         # identity (serverName/serverVersion), port defaults, `requires`
+  tools/
+    tools.register.json   # your tool entries (incl. their inputSchema)
+    tools.state.json      # the hot/hidden/enabled curation - part of the product
+    scripts/              # the tool scripts
+  mcp/expose.json         # upstream references + curated exposure
+  hooks/                  # the policy gate: manifest + hook scripts
+```
+
+## `tf_pack` - one call to a deployment artifact
+
+The `tf_pack` management tool snapshots the LIVE setup into `<home>/dist/<name>/` - always a
+separate location, never the live tree. `auth/` (environment-specific) and `logs/` never ship.
+
+**`{ format: "home" }`** → a portable config home. Zip it, commit it to a repo, or run it as-is:
+
+```
+toolfunnel --config-dir path/to/the-pack
+```
+
+**`{ format: "npm", name: "my-mcp", version: "1.0.0" }`** → a publishable npm package:
+
+```
+dist/my-mcp/
+  package.json      # name, bin, files, dependencies: { "toolfunnel": "^<current version>" }
+  bin/my-mcp.js     # 2 lines: pin --config-dir at ../home, delegate to toolfunnel
+  home/             # the bundled config home (identity rewritten to my-mcp@1.0.0)
+  README.md         # a stub to make your own
+```
+
+Review it, then `cd dist/my-mcp && npm publish`. Your users run `npx my-mcp` and get **your**
+server: your name in the MCP `initialize` handshake, your tools with your schemas, your curation,
+and - the part nobody else can say - **your gate**. The hooks travel inside the pack and enforce
+your policy on the recipient's machine regardless of which MCP client calls it.
+
+### Depend, never copy
+
+The generated package **depends on** `toolfunnel` (caret range) rather than vendoring it. Your own
+runtime dependencies go in **your** `package.json` exactly as with any npm package - npm installs
+the whole tree on `npx my-mcp`; toolfunnel itself adds zero. Why depending matters:
+
+- security and bug fixes reach every wrapped MCP through a normal `npm update` (the pack pins the caret range of the version that built it, so patch releases flow automatically) - no stale forks
+  carrying old bugs;
+- your package stays a few KB of config instead of a copied engine;
+- (and honestly) every install of your MCP counts as a toolfunnel download, which keeps the thing
+  you depend on alive.
+
+Your users can move the bundled home out of `node_modules` (so *their* edits survive *your*
+updates) via the `<NAME>_HOME` env var the generated launcher supports.
+
+## Declaring runtimes: `requires`
+
+Your tools may need runtimes the gateway doesn't (python, git, ffmpeg...). Declare them in the
+home's `toolfunnel.json` and they travel with every pack:
+
+```json
+{
+  "serverName": "my-mcp",
+  "requires": [
+    { "command": "python", "min": "3.10", "why": "the pdf-extract tools" },
+    { "command": "git" }
+  ]
+}
+```
+
+The gateway probes them once at startup and prints one clear stderr line per problem - found
+version vs needed, plus your `why`. Advisory by design: a missing runtime breaks only the tools
+that need it, so the server still starts and everything else keeps working.
+
+## Composite packs
+
+A pack is not just your own scripts. Because `mcp/expose.json` lives in the home, a pack carries
+**upstream references too**: "attach `@example/weather-mcp` (pin the version) and expose exactly
+these four tools under these names." The upstream itself travels as a *reference* - `npx` fetches
+it on the recipient's machine - while your **curation** and your **gate** travel as config. One
+pack = your tools + other people's servers, curated, renamed, and policed, as a single artifact.
+
+## Audit honesty
+
+Packs spawn commands - that is what they are for. Before you run anyone's pack (including one of
+ours), read **three files** - every command it can run is declared in plain JSON:
+
+- `tools/tools.register.json` - the tool invokes (scripts and shell commands);
+- `mcp/expose.json` - the upstream server commands it will spawn;
+- `toolfunnel.json` - the `requires` probes. Note these run **at gateway startup** (each declared
+  program is executed once with its version flag), which is why a `requires` command must be a
+  bare program name - the gateway rejects paths, spaces, and shell characters outright.
+
+Ship your own packs expecting the same scrutiny, and say so in your README (the `tf_pack` stub
+already does).

package/hooks/hooks.manifest.json

@@ -1,27 +1,27 @@
-{
-  "version": 1,
-  "hooks": [
-    {
-      "id": "pre-tool-use/example-deny-dangerous",
-      "event": "PreToolUse",
-      "matcher": "*",
-      "type": "command",
-      "command": "node \"${HOOKS_DIR}/scripts/example-deny-dangerous.js\"",
-      "script": "scripts/example-deny-dangerous.js",
-      "timeout": 10,
-      "enabled": false,
-      "description": "EXAMPLE (disabled by default). A PreToolUse policy gate: denies any tool call whose arguments contain an obviously-destructive shell pattern (rm -rf, mkfs, drive format, fork bomb). A non-zero exit fails closed and blocks the call before it runs. Enable it in the UI Hooks tab (or set enabled:true here) to see the gate bite; edit scripts/example-deny-dangerous.js to encode your own policy."
-    },
-    {
-      "id": "post-tool-use/example-audit",
-      "event": "PostToolUse",
-      "matcher": "*",
-      "type": "command",
-      "command": "node \"${HOOKS_DIR}/scripts/example-audit.js\"",
-      "script": "scripts/example-audit.js",
-      "timeout": 10,
-      "enabled": false,
-      "description": "EXAMPLE (disabled by default). A PostToolUse observer: runs AFTER a tool executes (advisory — it cannot un-run the call) and receives the tool result on stdin. The stub exits 0 (clean pass); replace its body to forward results to your own audit sink, metrics, or SIEM. Enable it in the UI Hooks tab (or set enabled:true here)."
-    }
-  ]
-}
+{
+  "version": 1,
+  "hooks": [
+    {
+      "id": "pre-tool-use/example-deny-dangerous",
+      "event": "PreToolUse",
+      "matcher": "*",
+      "type": "command",
+      "command": "node \"${HOOKS_DIR}/scripts/example-deny-dangerous.js\"",
+      "script": "scripts/example-deny-dangerous.js",
+      "timeout": 10,
+      "enabled": false,
+      "description": "EXAMPLE (disabled by default). A PreToolUse policy gate: denies any tool call whose arguments contain an obviously-destructive shell pattern (rm -rf, mkfs, drive format, fork bomb). A non-zero exit fails closed and blocks the call before it runs. Enable it in the UI Hooks tab (or set enabled:true here) to see the gate bite; edit scripts/example-deny-dangerous.js to encode your own policy."
+    },
+    {
+      "id": "post-tool-use/example-audit",
+      "event": "PostToolUse",
+      "matcher": "*",
+      "type": "command",
+      "command": "node \"${HOOKS_DIR}/scripts/example-audit.js\"",
+      "script": "scripts/example-audit.js",
+      "timeout": 10,
+      "enabled": false,
+      "description": "EXAMPLE (disabled by default). A PostToolUse observer: runs AFTER a tool executes (advisory - it cannot un-run the call) and receives the tool result on stdin. The stub exits 0 (clean pass); replace its body to forward results to your own audit sink, metrics, or SIEM. Enable it in the UI Hooks tab (or set enabled:true here)."
+    }
+  ]
+}

package/hooks/scripts/example-audit.js

@@ -1,21 +1,21 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * EXAMPLE PostToolUse observer — DISABLED by default.
- *
- * PostToolUse is ADVISORY: it runs AFTER a tool has executed and CANNOT un-run it — it observes the
- * outcome. The lifecycle event (including the tool result) arrives as JSON on stdin. This stub just
- * exits 0 (a clean pass). Replace the body to forward results to your own audit sink, metrics, an
- * external SIEM, etc. Exit 0 = observed; a non-zero exit on PostToolUse is a non-blocking error.
- *
- * Zero dependencies — Node built-ins only.
- */
-
-let raw = '';
-process.stdin.on('data', (c) => { raw += c; });
-process.stdin.on('end', () => {
-  // let ev = JSON.parse(raw || '{}');  // { tool_name, tool_input, tool_response, ... }
-  // ... forward ev to your audit sink here ...
-  process.exit(0);
-});
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * EXAMPLE PostToolUse observer - DISABLED by default.
+ *
+ * PostToolUse is ADVISORY: it runs AFTER a tool has executed and CANNOT un-run it - it observes the
+ * outcome. The lifecycle event (including the tool result) arrives as JSON on stdin. This stub just
+ * exits 0 (a clean pass). Replace the body to forward results to your own audit sink, metrics, an
+ * external SIEM, etc. Exit 0 = observed; a non-zero exit on PostToolUse is a non-blocking error.
+ *
+ * Zero dependencies - Node built-ins only.
+ */
+
+let raw = '';
+process.stdin.on('data', (c) => { raw += c; });
+process.stdin.on('end', () => {
+  // let ev = JSON.parse(raw || '{}');  // { tool_name, tool_input, tool_response, ... }
+  // ... forward ev to your audit sink here ...
+  process.exit(0);
+});

package/hooks/scripts/example-deny-dangerous.js

@@ -1,31 +1,31 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * EXAMPLE PreToolUse gate — DISABLED by default (enable it in hooks/hooks.manifest.json, or via the
- * UI Hooks tab / the per-tool "Pre" toggle on the Tools tab).
- *
- * This is the shape of a real policy gate: it runs INSIDE the gateway, BEFORE a tool executes, and a
- * non-zero exit DENIES the call (the gate fails closed). The lifecycle event arrives as JSON on
- * stdin; here we block any call whose arguments contain an obviously-destructive shell pattern.
- *
- * Block protocol (the simple one): write the reason to stderr and `process.exit(2)`. (A richer JSON
- * protocol is also supported — see docs/hooks-and-gating.md.) Exit 0 = allow.
- *
- * Zero dependencies — Node built-ins only.
- */
-
-let raw = '';
-process.stdin.on('data', (c) => { raw += c; });
-process.stdin.on('end', () => {
-  let ev = {};
-  try { ev = JSON.parse(raw || '{}'); } catch (_e) { /* malformed payload → allow (don't block on a parse error) */ }
-  const args = JSON.stringify((ev && ev.tool_input) || {});
-  // A small illustrative denylist: recursive-force delete, mkfs, drive format, fork bomb.
-  const DANGER = /\brm\s+-[a-z]*r[a-z]*f|\bmkfs\b|\bformat\s+[a-z]:|:\(\)\s*\{\s*:/i;
-  if (DANGER.test(args)) {
-    process.stderr.write('example-deny-dangerous: blocked — the arguments contain a destructive pattern.\n');
-    process.exit(2); // DENY — the gateway refuses to run the tool
-  }
-  process.exit(0); // allow
-});
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * EXAMPLE PreToolUse gate - DISABLED by default (enable it in hooks/hooks.manifest.json, or via the
+ * UI Hooks tab / the per-tool "Pre" toggle on the Tools tab).
+ *
+ * This is the shape of a real policy gate: it runs INSIDE the gateway, BEFORE a tool executes, and a
+ * non-zero exit DENIES the call (the gate fails closed). The lifecycle event arrives as JSON on
+ * stdin; here we block any call whose arguments contain an obviously-destructive shell pattern.
+ *
+ * Block protocol (the simple one): write the reason to stderr and `process.exit(2)`. (A richer JSON
+ * protocol is also supported - see docs/hooks-and-gating.md.) Exit 0 = allow.
+ *
+ * Zero dependencies - Node built-ins only.
+ */
+
+let raw = '';
+process.stdin.on('data', (c) => { raw += c; });
+process.stdin.on('end', () => {
+  let ev = {};
+  try { ev = JSON.parse(raw || '{}'); } catch (_e) { /* malformed payload -> allow (don't block on a parse error) */ }
+  const args = JSON.stringify((ev && ev.tool_input) || {});
+  // A small illustrative denylist: recursive-force delete, mkfs, drive format, fork bomb.
+  const DANGER = /\brm\s+-[a-z]*r[a-z]*f|\bmkfs\b|\bformat\s+[a-z]:|:\(\)\s*\{\s*:/i;
+  if (DANGER.test(args)) {
+    process.stderr.write('example-deny-dangerous: blocked - the arguments contain a destructive pattern.\n');
+    process.exit(2); // DENY - the gateway refuses to run the tool
+  }
+  process.exit(0); // allow
+});