toolfunnel 0.7.0 → 0.8.0

package/docs/KNOWN_BUGS.md

@@ -1,80 +1,100 @@
-# Known bugs
-
-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).
-
-## Open
-
-- **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).
-
-## Fixed in 0.7.0
-
-- ***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`.
-
-## By design (not bugs)
-
-These answer "why doesn't it do X". They are considered decisions, not defects.
-
-- **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 open work? Issues and PRs are welcome.
+# Known bugs
+
+The **Open** list is what remains open as of 0.8.0. **Fixed in 0.8.0** marks the defects a
+0.7.x user could meet that this release closed. The full change list is in the
+[release notes](https://github.com/Rendeverance/toolfunnel/releases).
+
+## Open
+
+- **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. 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).
+- **OPEN - A wrapped server's `instructions` are not covered by tool approval.** Tool descriptor
+  approval pins each tool's model-facing fields (`name`, `title`, `description`, `inputSchema`,
+  `outputSchema`, `annotations`). In wrap mode the wrapped server's `instructions` also reach the
+  model, unpinned, and a tool's `_meta`, `execution` and `icons` are forwarded without being
+  hashed. Pinning `instructions` is planned.
+- **OPEN - A command on a drive mounted after startup stops being retried.** A missing command is a
+  permanent failure: about five minutes of retries, then the upstream stops (named on stderr and
+  in `/health.stopped`) until `expose.json` is saved, the gateway restarts, or the upstream is
+  reconnected. A drive or share that appears later than that is not noticed on its own.
+- **OPEN (minor) - A very large approvals file slows refused calls.** Each refused call re-reads
+  `mcp/tool-approvals.json`; at 22 MB that costs about half a second per refused call. A home
+  with two real upstreams holds about 250 KB.
+
+## Fixed in 0.8.0
+
+- ***FIXED*** - **A hook's decision was ignored when the hook printed anything before its JSON.**
+  The exit code decided instead, so a gate that logged a line and then denied, exiting 0, let the
+  call through. The decision is now read wherever it sits, and two different decisions (a hook
+  that echoes model-supplied text after its own answer) fail closed. Pinned by
+  `test/gate-semantics.test.js`.
+- ***FIXED*** - **The hook engine substituted stand-ins when one of its parts failed to load.** It
+  now refuses to load and names the missing part. Pinned by `test/hook-engine-requires.test.js`.
+- ***FIXED*** - **Child hooks saw the wrong `HOOKS_DIR` and `CLAUDE_PROJECT_DIR`.** Both now point
+  at the config home. Pinned by `test/hook-env.test.js`.
+- ***FIXED*** - **A relative upstream `cwd` was checked against one directory and spawned in
+  another.** The isolation guard and the spawn now both resolve it against the config home.
+  Pinned by `test/upstream-cwd.test.js`.
+- ***FIXED*** - **Stopping a stdio gateway could leave its upstreams running (POSIX).** SIGINT or
+  SIGTERM now closes every upstream, then exits 130 or 143. Pinned by
+  `test/stdio-shutdown.test.js`.
+- ***FIXED*** - **A permanent startup failure retried forever, and on Windows a missing command
+  looked like a crashing server.** A missing command, a missing working directory or an isolation
+  refusal now stops after about five minutes with one line naming the cause, and shows in
+  `/health.stopped`. Pinned by `test/permanent-failure-ceiling.test.js`.
+- ***FIXED*** - **A wrong-typed config field was coerced or dropped silently.** The config now
+  refuses to load, naming the file, the entry and the field. Pinned by
+  `test/fail-loud-config.test.js`.
+- ***FIXED*** - **The legacy dispatcher answered notifications.** A notification now never gets a
+  reply. Pinned by `test/legacy-notifications.test.js`.
+
+## By design (not bugs)
+
+These answer "why doesn't it do X". They are considered decisions, not defects.
+
+- **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.
+- **Upstreams connect all at once, with no concurrency cap.** Right for the handful to tens of
+  upstreams a gateway holds.
+- **The legacy SSE transport's dead-client prune branch never runs.** The stream's close and error
+  handlers already clean up; the only effect is a counter that reads high. Cosmetic.
+- **Tool approval trusts a version bump.** A change at the same server version waits for
+  acceptance; a changed version is approved and reported, because that is what an update looks
+  like. A maintainer can bump the version too: `strictApproval: true` on an upstream holds every
+  change for acceptance.
+
+Found a bug, or want to help with the open work? Issues and PRs are welcome.

package/docs/design.md

@@ -1,84 +1,84 @@
-# 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: 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 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 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
-
-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.
+# 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: 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 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 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
+
+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 (a tool new in a release is added to the register once). 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.