feat(hooks): hook-driven request context propagation in tool dispatch

[bntvllnt]

Closes #15, #16, #17, #18.

What

Two coupled additions enabling per-tool server-side context injection.

`extendArgs` (#16)

`OnCallResult` gains an optional `extendArgs?: Record<string, unknown>` field. When the `onToolCall` hook returns it during the `before` phase, the framework merges the key/value pairs into args before `client[type](toolDef.ref, args)`.

• On collision: server-side wins (consistent with the design discussion in v0.3.0: Hook-driven request context propagation in tool dispatch #15).
• Empty / undefined is a no-op (no allocation, no merge).
• Only the `before` phase honors it. Returning `extendArgs` from `success` or `error` is silently ignored.
• Aborts win over extendArgs — when the hook returns `{ abort: true, extendArgs: {...} }`, dispatch never happens.

Reserved `_` prefix (#17)

Arg keys starting with underscore are framework-controlled. Two layers protect them:

1. Schema layer — `prepareTools` strips `*` keys from the published `zodShape`. The MCP SDK's Zod validator silently strips `*` keys from incoming requests via Zod's default strip mode, so spoofed values never reach the dispatched function.
2. Handler layer — The registered tool handler explicitly rejects any `_*` key reaching it with a structured "Reserved arg keys not allowed" error. This defends against transports that bypass the SDK's schema validation.

Hook-supplied `_*` keys via `extendArgs` are exempt from both layers — the server is trusted by definition.

Why

The `onToolCall` hook already receives `apiKey`, but currently has no way to pass that or any server-resolved context downstream. This blocks a class of common MCP server patterns:

Use case	What `extendArgs` enables
Per-action authorization	Server validates apiKey + scope, action re-validates as defense-in-depth
Request tracing	Hook injects request ID; action correlates its own logs with framework events
Multi-tenancy	Server-resolved tenant ID enforced via index queries — caller cannot spoof
Per-key feature flags	Hook computes flag map, action branches without re-fetching from DB
Audit metadata	Hook injects caller label/keyId, action records in domain audit log
Per-key quotas	Hook injects remaining quota, action enforces or warns near limit

The framework stays neutral: it doesn't define WHAT goes in `extendArgs`, only HOW. The reserved-prefix protection is what makes it safe.

Files changed

File	Lines	Why
`src/tools/types.ts`	+32	`OnCallResult.extendArgs` field with TSDoc + example
`src/tools/register.ts`	+53/-5	`isReservedKey` helper, `stripReservedFromShape` in `prepareTools`, reject loop at handler entry, `extendArgs` merge before dispatch
`tests/context-propagation.test.ts`	+494 (NEW)	12 tests covering all behaviors
`CHANGELOG.md`	+8	v0.3.0 "Added" section
`llms.txt`	+9	New "Request Context Propagation" section
`docs/security.md`	+72	Defense-in-depth section with 4 use-case patterns + anti-patterns

Backward compatibility

Strictly additive:

• `OnCallResult` gets a new optional field. Existing hooks unchanged.
• `prepareTools` strips `*` from the published shape. Verified zero impact across vllnt-owned consumers (no current consumer publishes `*` args).
• The handler-level `*` reject is new behavior. Any consumer accepting `*` request args today (none expected) would now get a structured rejection.

Test plan

• All 127 tests pass (115 existing + 12 new)
• `pnpm lint` clean
• `pnpm typecheck` clean
• 12 new tests cover: merge precedence (server wins), no-op cases (undefined / empty), abort precedence, phase isolation (only `before`), reserved-key rejection at handler boundary, top-level-only nested-key passthrough, schema stripping, end-to-end SDK strip + extendArgs injection
• CHANGELOG entry references v0.3.0: Hook-driven request context propagation in tool dispatch #15, extendArgs in OnCallResult — let onToolCall hook inject server-side context into dispatched args #16, Reserved _-prefix in tool args — reject client-supplied keys to prevent context spoofing #17
• llms.txt updated for LLM-readable API surface
• docs/security.md adds the production patterns section

Documentation coverage (full)

All v0.3.0 doc surfaces updated in commit `2822ef5`:

• `README.md` — Security section + Known Limitations updated
• `llms.txt` — Request Context Propagation section
• `llms-full.txt` — Full Lifecycle Hooks & Request Context Propagation section (~120 lines), all 5 patterns + anti-patterns; Types section expanded with `LifecycleHooks`, `CallContext`, `OnCallResult`, expanded `ToolDef`
• `docs/api-reference.md` — `LifecycleHooks`, `CallContext`, `OnCallResult` reference sections; reserved-prefix subsection; `hooks` field added to `ServerConfig` table
• `docs/examples.md` — 4 worked patterns (per-action auth, request tracing, multi-tenancy, per-key feature flags) + anti-patterns table
• `docs/security.md` — defense-in-depth section with 4 use-case patterns + anti-patterns
• `CHANGELOG.md` — v0.3.0 Added section

Motivation

Surfaced by an audit of a real-world Convex MCP server where ~80 ops/control-plane actions were publicly callable. The framework hook validated apiKey + scope, but the action handlers had no way to re-validate — so any caller bypassing the MCP HTTP layer hit zero authorization. Per-action re-validation requires the framework to propagate apiKey into args. This PR ships that primitive.

The design is intentionally generic — auth is one of six documented patterns. Anyone building a Convex+MCP server with per-action authorization, request tracing, multi-tenancy, audit, feature flags, or quotas can use this.