toolfunnel 0.6.0 → 0.7.0

package/README.md

@@ -2,6 +2,8 @@
 
 ![ToolFunnel](assets/logo.png)
 
+[![CI](https://github.com/Rendeverance/toolfunnel/actions/workflows/ci.yml/badge.svg)](https://github.com/Rendeverance/toolfunnel/actions/workflows/ci.yml)
+
 > A zero-dependency MCP and Local tool gateway: host your own tools in any language, forward and curate tools from other MCP servers, expose them leanly to cut agent token cost, gate every call through your own policy hooks before it runs, create your own MCP servers easily with zero code - and **wrap any MCP server so it speaks both protocol eras, invisibly**.
 
 **Zero code, zero dependencies: your own MCP server in 60 seconds** - from three ordinary scripts to a named, packaged, policy-gated MCP server (everything on screen is real output; see [demo/](demo/)):
@@ -16,11 +18,11 @@ Toolfunnel is designed to solve multiple issues in one package :)
 
 The Model Context Protocol (MCP) lets an AI agent call tools from many servers. But every connected server dumps **all** of its tool schemas into the model's context on every turn. Connect a handful of rich MCP servers and you've spent thousands of tokens describing tools the agent won't use this turn - slower, costlier, noisier.
 
-Similarly, working with AI I found myself generating many many tools, some of which I wanted to use with different AI workflows, some I didnt, and I didnt want to keep setting them up, I also didnt wish to keep many different setups for different workflows. Therefore ToolFunnel was born so that all of my multi-use tools and common MCP servers can be in one place, with any workflow, and I can easily select which I want to use with whatever workflow and even change or add tools during a session with simple toggles in the UI. I also wanted to wire up and test MCPs *live*, in the running session, without resetting the CLI or restarting anything - and have their tools show up in the tools list straight away; ToolFunnel does exactly that.
+Similarly, working with AI I found myself generating many many tools, some of which I wanted to use with different AI workflows, some I didn't, and I didn't want to keep setting them up, I also didn't wish to keep many different setups for different workflows. Therefore ToolFunnel was born so that all of my multi-use tools and common MCP servers can be in one place, with any workflow, and I can easily select which I want to use with whatever workflow and even change or add tools during a session with simple toggles in the UI. I also wanted to wire up and test MCPs *live*, in the running session, without resetting the CLI or restarting anything - and have their tools show up in the tools list straight away; ToolFunnel does exactly that.
 
 Often also, there's also no consistent way to **govern** what an agent may run: hooks and policies live in the *host* (a specific CLI or otherwise), so they don't travel when you switch clients - with ToolFunnel, this is easy because your hooks travel with the tools - it can become your one swiss-army knife for many different workflows.
 
-Additionally, I wanted an easy and consistent way to package my own tools and create new MCP servers from other tools, whatever language they were written in. FastMCP could do that, but not everything is written in python. I also  didnt want to audit huge numbers of dependencies - a personal choice, yes - so I wanted something that could be audited quickly and easily.
+Additionally, I wanted an easy and consistent way to package my own tools and create new MCP servers from other tools, whatever language they were written in. FastMCP could do that, but not everything is written in python. I also didn't want to audit huge numbers of dependencies - a personal choice, yes - so I wanted something that could be audited quickly and easily.
 
 Finally, when the MCP changes were announced as breaking changes, it became apparent this would eventually break a lot of MCP servers and/or clients out there, many of which might not be actively maintained. Not only that but changing MCP protocol generations takes time and might take considerable effort depending on the complexity of the server - therefore I added a quick, simple single command tool that allows ToolFunnel to wrap an MCP and easily translate between new and legacy protocols - quick, low effort, maximum gain.
 
@@ -38,18 +40,20 @@ ToolFunnel is one small MCP server that sits between your agent and everything e
 6. **Audit when you want it** - a toggleable JSONL log (default off) records tool runs, every gate allow/deny decision, and every upstream connect / disconnect / reconnect.
 7. **Live & self-healing** - attach/curate/toggle on a running gateway with no restart; if an attached MCP's process dies, the gateway detects it and reconnects in the background with backoff.
 8. **Build your own MCP server, no code, no SDK** - assemble scripts and curated upstream tools, switch the meta-tools off, and ToolFunnel *is* your MCP server; `tf_pack` ships it as a `npx`-installable npm package.
-9. **Wrap any MCP server** - one command turns ToolFunnel into a transparent, dual-era wrapper for a single MCP server: modern clients can use legacy servers, legacy clients can use modern servers, and neither side can tell ToolFunnel is there. *(The headline of 0.6.0 - see below.)*
+9. **Wrap any MCP server** - one command turns ToolFunnel into a transparent, dual-era wrapper for a single MCP server: modern clients can use legacy servers, legacy clients can use modern servers, and neither side can tell ToolFunnel is there. *(The headline of the dual-era work - see below.)*
 
 ## Under the hood
 
 Three claims in this README carry the most weight, and each one has a proof you can run:
 
-- **The gate fails closed.** A PreToolUse deny means the tool's execute path is never entered. The test suite proves it directly: a tool plants a side-effect file, the gate denies the call, and the test asserts the file never appears.
+- **A deny is absolute - and an unreadable decision is a deny.** A PreToolUse deny means the tool's execute path is never entered. The test suite proves it directly: a tool plants a side-effect file, the gate denies the call, and the test asserts the file never appears. A hook whose decision cannot be *read* - output past the cap, unparseable JSON - is also denied, because an unreadable answer must never read as permission. The deliberate exception: a hook script that crashes, is missing, or hangs past its timeout is a non-blocking error and the call proceeds (Claude Code hook parity - one broken hook file must not take every tool offline). So write denies as `exit 2`, never as a bare non-zero. `test/gate-semantics.test.js` pins every case.
 - **The wrap is tested at the wire, against servers we didn't write.** Elicitation bridging, cancel translation into the upstream's own request ids, identity mirroring and subscription replay all run over real pipes in the suite, including integration tests against the official MCP SDK client and a real npx-launched third-party server.
-- **The suite runs on 3 operating systems.** CI covers Linux, macOS and Windows across Node 18, 20 and 22 (35 test files). `npm test` runs the same suite locally.
+- **The suite runs on 3 operating systems.** CI covers Linux, macOS and Windows across Node 18, 20 and 22 (63 test files). `npm test` runs the same suite locally.
 
 The reasoning behind the bigger design decisions (why no SDK, why fail-closed, why zero dependencies, where the isolation boundary sits) is in [docs/design.md](docs/design.md).
 
+**Current release: 0.7.0** - the reconciliation pass against the finalised 2026-07-28 specification plus a defect-hunt hardening pass: best-version protocol negotiation for connecting clients, stricter HTTP header enforcement, verbatim upstream error relay, hook-matcher migration on rename, both elicitation modes, and a refcounted subscription lifecycle. Every item landed with a failing test first and the wire surface byte-diffed before and after. The full list of what changed is in the [release notes](https://github.com/Rendeverance/toolfunnel/releases); what is still open is in [docs/KNOWN_BUGS.md](docs/KNOWN_BUGS.md); the security model is in [SECURITY.md](SECURITY.md).
+
 ## Wrap any MCP server - one command, both protocol eras, invisible
 
 The 2026-07-28 MCP revision is a **breaking** protocol change: it removes the `initialize` handshake and sessions that every earlier server and client is built on. When clients upgrade, unmaintained legacy servers stop working with them; older clients can't talk to new-style servers at all. A lot of good tools are going to get stranded on the wrong side of that line.
@@ -119,7 +123,7 @@ Hooks speak the Claude-Code hook protocol (event JSON on stdin, exit `2` to bloc
 
 Hosting tools and proxying other MCP servers is a crowded space - but for my own use case, which is why I rolled my own solution, I wanted something different.
 
-A quick feature comparison as of June 2026:
+A quick feature comparison as of Aug 2nd 2026:
 
 | Capability | ToolFunnel | FastMCP | mcpproxy-go | MetaMCP | mcp-anything |
 |---|:--:|:--:|:--:|:--:|:--:|
@@ -132,7 +136,7 @@ A quick feature comparison as of June 2026:
 | Zero runtime dependencies\* | ✓ (Node, no SDK) | ✗ (framework) | ✓ (Go) | ✗ (Docker) | ✓ (Go) |
 | Runtime dependencies (installed / bundled) | **0\*** | many | 40+ (bundled) | many | bundled (Go) |
 | Config web UI | ✓ | ✗ | ✓ | ✓ | ✗ |
-| Dual-era protocol (2026-07-28 + legacy), client & server side | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Dual-era protocol (2026-07-28 + legacy), client & server side | ✓ | ✗<br>✓(beta) | ✗ | ✗ | ✗ |
 | Transparent single-server wrap (invisible, era-bridging) | ✓ | ✗ | ✗ | ✗ | ✗ |
 
 Beyond the dependency count, four capability choices set ToolFunnel apart from a pure proxy like mcpproxy-go:

package/SECURITY.md

@@ -0,0 +1,84 @@
+# Security Policy
+
+ToolFunnel sits between MCP clients and MCP servers - it gates, filters, and forwards
+tool calls. That makes its security surface worth taking seriously, and reports are
+genuinely welcome.
+
+## Reporting a vulnerability
+
+**Please use GitHub's private vulnerability reporting:** go to the
+[Security tab](https://github.com/Rendeverance/toolfunnel/security) → **Report a
+vulnerability**. That opens a private thread with the maintainer - nothing is public
+until a fix is out.
+
+Please **do not** open a public issue for a security-sensitive report. If you're unsure
+whether something is security-relevant, please err on the side of the private route.
+
+## What counts
+
+Anything that lets a client or upstream server do what the configuration says it
+shouldn't. For example:
+
+- Bypassing the tool gate / hidden-tool filtering (`tf_tool_set`, expose config)
+- Auth bypass in the HTTP transport or OAuth resource-server validation
+- Token or credential leakage (in logs, error messages, or forwarded traffic)
+- Escaping the PreToolUse deny-hook
+- Injection via tool names, schemas, or forwarded arguments
+
+Bugs that crash ToolFunnel but don't cross a trust boundary are ordinary bugs -
+public issues are fine for those.
+
+## What to expect
+
+This is a single-maintainer project. Reports get a response on a best-effort basis -
+normally within a few days. Confirmed vulnerabilities are fixed as a priority, and
+you'll be credited in the release notes unless you'd rather not be.
+
+## Supported versions
+
+Only the latest published release (`npm install toolfunnel`) is supported with
+security fixes.
+
+## Trust model
+
+**The config home is the trust boundary.** Anyone who can write the config home
+(`tools/`, `mcp/`, `hooks/`, `auth/`, `toolfunnel.json`) can define register tools, hooks,
+and upstream commands that execute with the gateway process's privileges. Protect it with
+filesystem permissions like you would a crontab or a shell profile.
+
+Everything else follows from that line:
+
+- **Upstream MCP servers are operator-chosen code.** Attaching or wrapping a server means
+  trusting it with whatever its command can reach. In funnel mode the gateway *refuses*
+  upstream arguments, working directories, and code-loading environment variables that
+  reference paths outside the config home. The per-upstream opt-outs are explicit, and each
+  is wider than a single check: `allowOutsidePaths` lifts the outside-path refusal for
+  everything path-shaped that upstream carries - its arguments (including the value after
+  `=` in a `--flag=value` form), the working directory its bare arguments resolve against,
+  and its path-list environment variables; `allowCodeLoadingEnv` permits the code-loading
+  environment class (`NODE_OPTIONS`, `NODE_PATH`, and their equivalents for other runtimes)
+  on its own. Wrap mode permits outside paths with a security notice, because serving your
+  real files is usually the point of a wrapped server. The guard is a tripwire for configs that quietly reach
+  outside an auditable config home - not a sandbox against an untrusted pack author:
+  installing a pack is installing software.
+- **The network surface binds loopback by default** (HTTP, SSE, and the web UI), validates
+  the `Origin` header against loopback origins, and enforces the protocol-version
+  and parameter-mirroring header rules of the 2026-07-28 revision. Exposing the port beyond
+  localhost is an operator decision; put OAuth 2.1 (opt-in) or your own reverse proxy in
+  front of it if you do.
+- **Zero runtime dependencies** - the supply-chain audit surface is this repository's own
+  code (OAuth, if enabled, adds exactly one audited library: `jose`).
+- **An unreadable gate decision is a deny.** A hook that floods its output past the cap, whose
+  decision JSON cannot be parsed, or whose decision slot carries a value outside the exact
+  protocol vocabulary (a miscased `"DENY"`, a synonym like `"denied"`, the right word in the
+  wrong slot, a wrong type) blocks the call it was gating rather than waving it through. A hook
+  matcher that does not compile is the same class: it is refused at authoring, and one already
+  in the manifest denies every tool-bearing call of its event until fixed. A `null` in a
+  protocol slot is NOT an attempt - it reads as "no value", exactly like an absent key, and
+  falls through. The deliberate exception: a hook script that CRASHES, is MISSING, or HANGS
+  past its timeout is a non-blocking error and the call proceeds - Claude Code hook parity, so
+  a script-execution failure cannot take every tool offline. An authored-config defect (the
+  matcher, the decision vocabulary) gets no such grace: the author wrote a gate the runner
+  cannot read, and it denies until corrected. Denies are `exit 2`; a gate that cannot reach a
+  decision should exit 2 explicitly rather than error out. Pinned by
+  `test/gate-semantics.test.js` and `test/matcher-compile.test.js`.

package/bin/toolfunnel.js

@@ -11,6 +11,7 @@
  *   toolfunnel --ui                 Start the OPTIONAL config web UI on 127.0.0.1:9777
  *   toolfunnel --ui --port <n>      Bind a specific UI port (0 = OS-assigned)
  *   toolfunnel install-oauth        Install the OPTIONAL OAuth 2.1 dependency (jose) on demand
+ *   toolfunnel --version            Print the version
  *   toolfunnel --help               Show this help
  *
  * Zero runtime dependencies. The stdio path runs the server's main(); the HTTP
@@ -21,9 +22,37 @@
 
 const args = process.argv.slice(2);
 
+/**
+ * Read a flag's value, accepting BOTH `--flag value` and `--flag=value` (0.7.0). Only the
+ * space-separated form was handled, so `--config-dir=/my/home` was silently ignored and the config
+ * home fell back to the package root - exactly the class of quiet misconfiguration the resolved-home
+ * stderr line and the positional parsing below exist to prevent. The `=` form is what most people
+ * type first, and getting it wrong wrote config somewhere they were not looking.
+ */
 function flagValue(name, fallback) {
-  const i = args.indexOf(name);
-  return i !== -1 && i + 1 < args.length ? args[i + 1] : fallback;
+  // ONE left-to-right scan, LAST occurrence wins whichever form it uses. Scanning the = form
+  // across all args before the space form made precedence depend on spelling, not position
+  // (`--port 9 --port=8` and `--port=8 --port 9` both answered 8). A present-but-EMPTY `=`
+  // value (`--config-dir=`) is an error, not a silent fallback - downstream it is
+  // indistinguishable from "not given", which for --config-dir meant config quietly written to
+  // the package root, the exact misconfiguration this parser exists to prevent.
+  const eq = name + '=';
+  let value = fallback;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (typeof a !== 'string') continue;
+    if (a.startsWith(eq)) {
+      const v = a.slice(eq.length);
+      if (v.length === 0) {
+        process.stderr.write(`toolfunnel: ${name}= requires a value (write ${name}=<value> or ${name} <value>)\n`);
+        process.exit(2);
+      }
+      value = v;
+    } else if (a === name && i + 1 < args.length) {
+      value = args[i + 1];
+    }
+  }
+  return value;
 }
 
 // POSITIONAL arguments - the subcommand and its target - recognised regardless of where global
@@ -35,11 +64,18 @@ const VALUE_FLAGS = new Set(['--config-dir', '--port', '--host', '--as']);
 const positionals = [];
 for (let i = 0; i < args.length; i++) {
   const a = args[i];
+  // `--flag value` consumes the next token; `--flag=value` is self-contained and is skipped by the
+  // generic leading-dash rule below, so it must NOT also eat the following token.
   if (VALUE_FLAGS.has(a)) { i++; continue; }
   if (typeof a === 'string' && a.length && a[0] === '-') continue;
   positionals.push(a);
 }
 
+if (args.includes('--version') || args.includes('-v')) {
+  process.stdout.write(require('../package.json').version + '\n');
+  process.exit(0);
+}
+
 if (args.includes('--help') || args.includes('-h')) {
   process.stdout.write(
     [
@@ -58,6 +94,7 @@ if (args.includes('--help') || args.includes('-h')) {
       '                                working with modern clients. `wrap --off` restores normal.',
       '  toolfunnel install-oauth      Install the optional OAuth 2.1 dependency (jose)',
       '  toolfunnel --config-dir <dir> Use <dir> as the CONFIG HOME (see below)',
+      '  toolfunnel --version          Print the version',
       '  toolfunnel --help             Show this help',
       '',
       'CONFIG HOME: the mutable config (tools/ mcp/ hooks/ auth/ logs/ toolfunnel.json) lives in',
@@ -78,6 +115,10 @@ if (args.includes('--help') || args.includes('-h')) {
 // Resolve + seed the config home FIRST - before any src/ module is required - so every
 // module-load-time anchor (register/expose/hooks paths, auth + log config, identity) reads the
 // same resolved home. Precedence: --config-dir > TOOLFUNNEL_HOME env > the package root.
+// Whether the user EXPLICITLY placed the home must be captured BEFORE init: initConfigHome
+// exports the resolved home into process.env.TOOLFUNNEL_HOME for the child tools it spawns,
+// so reading the env afterwards is always-true and the hint branch was dead (0.7.0).
+const explicitHome = !!(flagValue('--config-dir', '') || process.env.TOOLFUNNEL_HOME);
 const { initConfigHome } = require('../src/core/config-home');
 const configHome = initConfigHome({ dir: flagValue('--config-dir', '') }).home;
 
@@ -85,7 +126,7 @@ const configHome = initConfigHome({ dir: flagValue('--config-dir', '') }).home;
 // `git status` after running from a clone was the discovery mechanism. Defaulted homes get
 // the relocation hint.
 process.stderr.write('[toolfunnel] config home: ' + configHome +
-  ((flagValue('--config-dir', '') || process.env.TOOLFUNNEL_HOME)
+  (explicitHome
     ? '\n'
     : ' (default: the package root - use --config-dir <dir> or TOOLFUNNEL_HOME to relocate)\n'));
 
@@ -157,12 +198,40 @@ if (positionals[0] === 'wrap') {
     // up front - informed consent, not a silent default (the old behaviour was worse: the guard
     // still applied, and `wrap` reported success while the gateway refused to connect).
     {
-      const { looksLikePath, isInside } = require('../src/mcp/aggregator');
-      const outsideArgs = (Array.isArray(upstream.args) ? upstream.args : [])
-        .filter((a) => looksLikePath(a) && !isInside(home, a));
-      if (outsideArgs.length) {
-        process.stderr.write('[toolfunnel] ⚠ WRAP SECURITY NOTICE - upstream "' + target + '" uses paths outside the gateway root:\n' +
-          outsideArgs.map((a) => '    ' + a).join('\n') + '\n' +
+      // Enumerate EVERY class the wrap excuses, using the guard's own lists so the notice and the
+      // guard can never classify differently. Args-only was the defect: the archetypal wrap target
+      // (a filesystem server on a documents folder) HAS an outside arg so the notice fired there,
+      // while a clean-args upstream carrying NODE_OPTIONS=--require and an outside cwd wrapped in
+      // total silence - the one moment of informed consent, blind to the class that loads code.
+      const { looksLikePath, isInside, isDriveRelative, CODE_OPT_ENV, CODE_PATH_ENV } = require('../src/mcp/aggregator');
+      const findings = (Array.isArray(upstream.args) ? upstream.args : [])
+        .filter((a) => looksLikePath(a) && !isInside(home, a))
+        .map((a) => 'arg   ' + a);
+      if (typeof upstream.cwd === 'string' && upstream.cwd.length > 0
+        && (isDriveRelative(upstream.cwd) || !isInside(home, upstream.cwd))) {
+        findings.push('cwd   ' + upstream.cwd + '   (bare args resolve against this)');
+      }
+      const envObj = upstream.env && typeof upstream.env === 'object' ? upstream.env : null;
+      if (envObj) {
+        for (const key in envObj) {
+          const upper = String(key).toUpperCase();
+          const isOpt = key === '__proto__' || CODE_OPT_ENV.includes(upper);
+          const isPathVar = CODE_PATH_ENV.includes(upper);
+          if (!isOpt && !isPathVar) continue;
+          let raw;
+          try { raw = String(envObj[key]); } catch (_e) { raw = '(unreadable)'; }
+          // An option-string var loads code whatever its value; a path-list var only when a piece
+          // of it points outside - the same rule the guard applies, so the two agree by construction.
+          if (isPathVar && raw !== '(unreadable)') {
+            const parts = (raw.match(/[A-Za-z]:[^;:]*|[^;:]+/g) || []).filter((t) => t.length > 0);
+            if (!parts.some((t) => isDriveRelative(t) || !isInside(home, t))) continue;
+          }
+          findings.push('env   ' + key + '=' + raw + '   (loads code into the child)');
+        }
+      }
+      if (findings.length) {
+        process.stderr.write('[toolfunnel] ⚠ WRAP SECURITY NOTICE - upstream "' + target + '" reaches outside the gateway root:\n' +
+          findings.map((a) => '    ' + a).join('\n') + '\n' +
           '  While WRAPPED, the path-isolation guard is suspended for this upstream: ToolFunnel is a\n' +
           '  transparent wrapper here, and the wrapped server can reach whatever those paths reach.\n' +
           '  Every call still passes the PreToolUse gate. To restrict it AFTER wrapping: add a\n' +
@@ -181,26 +250,36 @@ if (positionals[0] === 'wrap') {
     // (server/discover), and only on failure fall back to the legacy initialize - otherwise a
     // dual-era upstream would be misreported as legacy just because the legacy handshake works.
     // Separate child per stage: a badly behaved legacy server may react badly to an unknown
-    // method, and the fallback must not inherit a poisoned child.
+    // method, and the fallback must not inherit a soured child.
     if (upstream.transport === 'stdio') {
-      const { McpClient } = require('../src/mcp/mcp-client');
-      const clientOpts = {
+      const { defaultClientFactory } = require('../src/mcp/aggregator');
+      // The probe SPAWNS this upstream, so it goes through the same factory - and therefore the
+      // same isolation guard - as every other spawn. Building McpClient directly here meant the
+      // one code path that runs an upstream's command before the operator has seen anything was
+      // also the one path with no guard on args/cwd/env, while the docs claimed otherwise.
+      // allowOutsidePaths is TRUE because this IS the wrap path: outside references are the
+      // operator's explicit declaration, so the guard warns instead of refusing (same rule the
+      // running gateway applies to the wrapped upstream).
+      const probeUpstream = Object.assign({}, upstream, {
         id: target,
-        command: upstream.command,
-        args: Array.isArray(upstream.args) ? upstream.args : [],
-        env: upstream.env || {},
         // Default the probe's cwd to the CONFIG HOME, same as the aggregator's spawn: relative
         // arg paths are guarded against the home, so they must spawn against it too.
         cwd: upstream.cwd || home,
         // Honour a configured slow-boot window; the probe default stays tight.
         requestTimeoutMs: Number.isFinite(upstream.requestTimeoutMs) && upstream.requestTimeoutMs > 0
           ? upstream.requestTimeoutMs : 6000,
-      };
+        // The probe decides the era ITSELF (server/discover, then a legacy fallback on a fresh
+        // child). Neutralise the stored era policy so a pinned upstream still gets both stages -
+        // otherwise the factory would force one era and the probe would report its own input.
+        legacyPin: false,
+        modernOnly: false,
+      });
+      const newProbeClient = () => defaultClientFactory(probeUpstream, home, () => {}, true, undefined);
 
       let reported = false;
       // Stage 1: modern probe (server/discover).
       try {
-        const probe = new McpClient(clientOpts);
+        const probe = newProbeClient();
         try {
           const disc = await probe.probeDiscover();
           const versions = disc && Array.isArray(disc.supportedVersions) ? disc.supportedVersions : [];
@@ -226,7 +305,7 @@ if (positionals[0] === 'wrap') {
       // Stage 2: legacy fallback (initialize) - the era every current MCP speaks.
       if (!reported) {
         try {
-          const legacy = new McpClient(clientOpts);
+          const legacy = newProbeClient();
           try {
             const init = await legacy.connect();
             const v = init && typeof init.protocolVersion === 'string' ? init.protocolVersion : 'unknown';

package/docs/KNOWN_BUGS.md

@@ -1,99 +1,80 @@
-# Known issues & roadmap
+# Known bugs
 
-This file tracks the state of the 0.6.0 dual-era work, the deliberately-deferred items, and any
-limitations worth knowing about.
+The **Open** list is what remains open as of 0.7.0. **Fixed in 0.7.0** marks the items from
+0.6.0's file that this release closed - kept and marked rather than silently deleted, so a
+0.6.0 reader can see their fate. The full change list is in the
+[release notes](https://github.com/Rendeverance/toolfunnel/releases).
 
-## 0.6.0 - the 2026-07-28 MCP specification
+## Open
 
-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):
+- **OPEN - Modern-upstream subscriptions are not received.** The client does not yet open a
+  `subscriptions/listen` stream to modern upstreams, so their change-notifications never arrive;
+  the listen ack honestly refuses `resourceSubscriptions` when no legacy subscribe-capable
+  upstream is in scope.
+- **OPEN - The elicitation bridge does not cover legacy clients.** A wrapped upstream's mid-call
+  `elicitation/create` bridges to MODERN clients as MRTR (`input_required` + retry), form and url
+  mode, gated on the caller's declared capability (0.7.0). A LEGACY client gets an automatic
+  decline instead - relaying backwards requests to legacy clients is unbuilt - and
+  `sampling/createMessage` / `roots/list` from upstreams are answered `-32601`. 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.
+- **OPEN (deferred) - HTTP cancels are dropped rather than translated.** The sessionless modern
+  era gives a POST no connection identity, so a client `notifications/cancelled` arriving over
+  HTTP is dropped rather than risk cancelling another client's call. Fixing this needs design
+  thought - identifying the caller without reintroducing sessions - so it is deferred rather than
+  patched. stdio (one client per pipe) translates and forwards cancels for both forwarded methods
+  and wrapped tool calls; the remaining best-effort windows there 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).
 
-- **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.
+## Fixed in 0.7.0
 
-## Deliberately deferred (documented dispositions, target: the 28-July reconciliation pass)
+- ***FIXED*** - **Legacy version negotiation.** 0.6.0 answered every `initialize` with
+  2024-11-05 whatever the client asked for, and supported exactly one legacy revision. The
+  gateway now echoes the requested version when it supports it (else answers its latest legacy),
+  and the legacy set spans 2024-11-05 / 2025-03-26 / 2025-06-18 / 2025-11-25. Pinned by
+  `test/negotiation.test.js`. One direction remains conservative: the client still offers
+  2024-11-05 to legacy upstreams (field fidelity is unaffected; only the advertised version
+  string is older than either end requires).
+- ***FIXED*** - **Header validation used a generic error code for an unsupported version.** An
+  unsupported `MCP-Protocol-Version` header answered the generic `-32600`; it now answers
+  `-32022` with `data.supported` and `data.requested` - the same code and shape the `_meta`
+  path already used for the same condition, so a client can renegotiate without parsing prose.
+  Pinned by `test/header-enforcement.test.js`.
+- ***FIXED*** - **The wrap's identity-mirror reconnect re-ran the full era negotiation** (worst
+  case roughly 3 s per respawn against an upstream that ignores `server/discover`). The
+  negotiated era is now remembered per upstream, and a death-driven reconnect goes straight to
+  the era it knows. A failed hinted connect or an explicit reconnect re-negotiates in full, so
+  an upstream upgraded across a restart is never pinned down an era. Pinned by
+  `test/reconnect-era-memo.test.js`.
+- ***FIXED*** - **`io.modelcontextprotocol/logLevel` was stripped on wrapped forwards.** Now
+  era-keyed at the client boundary: a modern upstream gets the caller's level verbatim in
+  `_meta`; a legacy upstream that declared the `logging` capability gets `logging/setLevel`
+  issued before the call (and the key never leaks into legacy `_meta`). Pinned by
+  `test/loglevel.test.js`.
 
-- **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).
+## By design (not bugs)
 
-## Current limitations
+These answer "why doesn't it do X". They are considered decisions, not defects.
 
-- 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).
+- **The config home defaults to the package root.** A git clone keeps working unchanged, and
+  seeding protects it from `npm update`, with an every-start relocation hint. Defaulting it to a
+  per-user directory instead needs a migration story for existing installs, so it ships as its own
+  release rather than as a rider. (`preuninstall` as a rescue mechanism is tested DEAD on npm
+  11.9.0 - it will not be built.)
+- **Funnel-mode curated descriptions carry an `[upstream]` title prefix** that lean passthrough
+  does not. A toggle to reconcile the two is cosmetic.
+- **The `command` slot is not path-guarded, and `PATH` is deliberately permitted.** The command
+  names the interpreter (`node`, a system binary), which by definition lives outside the config
+  home, and guarding `PATH` would break how commands resolve at all - so an upstream entry
+  combining `command: "node"` with a caller-supplied `env.PATH` runs whatever that PATH resolves.
+  This is a documented boundary, not an oversight: an upstream entry already specifies an
+  arbitrary command to execute, so the isolation guard is a **tripwire** for configs that quietly
+  reach outside an auditable config home - not a sandbox against an untrusted pack author.
+  Installing a pack is installing software (see [SECURITY.md](../SECURITY.md)).
+- **A meta-less `server/discover` is answered rather than refused** - permissive by design.
+- **Discover works on a DISABLED upstream**, so its tools can be inspected before enabling. An
+  explicit allowance on the discover path only; the disabled upstream never reaches the tool
+  surface.
 
-Found a bug, or want to help with the 0.6.0 work? Issues and PRs are welcome.
+Found a bug, or want to help with the open work? Issues and PRs are welcome.

package/docs/design.md

@@ -20,21 +20,35 @@ SDK. Two reasons. First, the zero-dependency stance above. Second, ToolFunnel ha
 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
+## 3. The gate: a deny is absolute, an unreadable decision is a deny
 
 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.
+every failure it can *see* as a deny: a hook that blocks, a hook engine that crashes, a malformed
+engine result, a decision too large or too mangled to parse - all of them mean the tool does not
+run. An answer we cannot read is never treated as permission. 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 line is drawn at a hook that never answered at all. A hook *script* that crashes, is missing,
+or hangs past its timeout is a non-blocking error and the call proceeds. That is Claude Code's
+hook protocol and it is a deliberate trade: denying there would mean a single broken hook file -
+a typo, a deleted script, a slow disk - silently taking every tool in the gateway offline, and an
+operator debugging that has no signal to follow. So the runtime failure is reported and the call
+continues, while the *decision* path stays strict. The consequence for anyone writing a gate is
+concrete: deny with `exit 2`, never with a bare non-zero, and if your policy cannot decide, exit 2
+deliberately. Both halves of this contract are pinned by test/gate-semantics.test.js.
 
 ## 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.
+Upstream server definitions can name any executable, but every field that decides what code the
+spawned process runs must stay inside the config home: path-shaped arguments (including the
+value after `=` in a `--flag=value` form), the working directory (`cwd`) bare arguments resolve
+against, and the small set of environment variables that load code on their own (`NODE_OPTIONS`,
+`NODE_PATH`, and their equivalents for other runtimes). The command is not guarded - it is the
+interpreter you chose, not the code it runs. The guard relaxes only by explicit opt-out, each
+per upstream and each with a warning naming itself: wrapping (a wrap is an explicit statement
+that this one server is your entire surface), `allowOutsidePaths: true` on the upstream's own
+entry (its paths and path-list env), and `allowCodeLoadingEnv: true` (the env class on its own).
 
 ## 5. Two eras, served per request
 

package/hooks/hooks.manifest.json

@@ -10,7 +10,7 @@
       "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."
+      "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). Exit 2 denies and blocks the call before it runs; exit 0 allows. Any OTHER exit (a crash, a missing script, a timeout) is a non-blocking error and the call PROCEEDS - write denies as exit 2, never as a bare non-zero. 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",

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

@@ -5,12 +5,20 @@
  * 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.
+ * This is the shape of a real policy gate: it runs INSIDE the gateway, BEFORE a tool executes, and
+ * `process.exit(2)` DENIES the call. 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.
+ * protocol is also supported - see docs/MANUAL.pdf section 10.) Exit 0 = allow.
+ *
+ * EXIT 2, NOT "non-zero" - the difference matters when you write your own. Every OTHER exit (a
+ * crash, a syntax error, a missing file, a timeout) is a NON-BLOCKING ERROR and the call proceeds,
+ * so `exit(1)` on an error path allows the very call you meant to stop. If your policy cannot
+ * reach a decision, exit 2 deliberately. (The gateway does refuse a decision it cannot READ -
+ * output past the cap, unparseable JSON - because an unreadable answer is not permission. It
+ * cannot do the same for a script that never answered: one broken hook file would take every tool
+ * offline.) test/gate-semantics.test.js pins all of this.
  *
  * Zero dependencies - Node built-ins only.
  */