SDK: per-tool capture overrides (inputValues/outputValues/intent) + warn-once for tracking calls outside a wrapped tool

[marselsel]

Ready to implement. Spec: .specs/sdk/per-tool-capture.md (committed in #78). The spec is the source of truth; the comments below are review history.

Task

withYavio() gains per-tool overrides of the capture flags, merged over the global capture config, so a tool with sensitive input can stay on the proxy instead of being registered outside it:

withYavio(server, {
  capture: { inputValues: true, outputValues: true },
  tools: { "book-contract": { inputValues: false, outputValues: false, intent: false } },
});

Why: registering outside the proxy is the only option today, and it loses the tool_call event and silently turns yavio.conversion() / track() / step() / identify() into no-ops — createYavioContext() has no fallback store. Measured on Commerce for Agents: 46 conversions from a proxied tool, 0 from the unwrapped booking tool, no warning anywhere.

Decisions (final — these supersede anything in the review comments)

1. Reuse YAVIO-1105 (SDK.CONTEXT_INJECTION_UNAVAILABLE, already defined and unused) for the warn-once. Do not mint a new code. Its catalog text in .specs/07_error-catalog.md is wrong ("will lack traceId and sessionId") and must be corrected to say the event is dropped.
2. intent: false is a third controller state, not just "ineligible": never advertise context, never capture it, but still strip it when a client sends one from a cached schema — otherwise a strict Zod schema rejects the call.
3. Cross-spec rule with SDK/shared/ingest: tool results with isError: true must count as errors (status error, category tool_error) #75: with outputValues: false, keep status and error_category but drop the result-derived error_message. That text is output, and a handler echoing "postal code 12345 invalid" would leak the very input the override exists to hide. The thrown-path message stays (developer-written).
4. Client meta stays coupled to inputValues deliberately. Decoupling would silently start collecting subject_id/locale/country_code for existing integrators who set inputValues: false as their privacy posture. That is a collection expansion needing its own opt-in decision, not a refactor.
5. Docs: 02-sdk/02-tracking-api.mdx currently documents the silent drop as intended and must change too, not only the README.

Acceptance

• ToolCaptureOverride + WithYavioOptions.tools + .yaviorc.json tools (no env-var form)
• resolveToolCapture(name) applied in both interceptors (tool() and registerTool(), MCP SDK and Skybridge conventions)
• inputValues:false drops input_keys/input_types/input_values and client meta, on success and throw
• intent:false third state, incl. the strict-schema strip test
• Warn-once YAVIO-1105 + corrected catalog text
• Tests per the spec's Tests section (config, proxy, intent integration, context)
• README + docs pages updated

Independent of #75; both target @yavio/sdk 0.4.0. Additive, no behaviour change without tools.

Follow-up once shipped: migrate Commerce for Agents (book-contract onto the proxy with the override, drop the "unwrapped server" invariant, verify with scripts/analytics-funnel.mjs --book — conversion present, PII grep 0 hits).

[marselsel]

Spec review (second Claude session, 2026-08-26) — verdict: agree with the direction and the config shape. Three corrections.

Verified:

• createYavioContext() is built without a fallback store (context.ts:44, server/index.ts:75) — outside a wrapped callback every method returns silently. 02-sdk/02-tracking-api.mdx:53 currently documents that silence as intended ("Calls outside that context are silently ignored"), so the warn-once changes documented behaviour: update that page too, not only the README.
• Commerce for Agents: book-contract on the unwrapped base (server.ts:178-186), yavio.conversion("booking_received") at book-contract.ts:93. Live: 46 switch_link_issued conversions (proxied tool), 0 booking_received — the funnel really ends before the booking.
• tools: { "<name>": { inputValues, outputValues, intent } } reads well; keep it top-level as proposed. PostHog has nothing comparable (only a global beforeSend), so this is a genuine differentiator.

Corrections:

1. Reuse YAVIO-1105, don't mint 1107. packages/shared/src/error-codes.ts:29 already defines CONTEXT_INJECTION_UNAVAILABLE = "YAVIO-1105" and .specs/07_error-catalog.md:125 describes exactly this situation ("Context unavailable … tracking calls outside a request context") — and nothing in packages/sdk/src uses it. Its catalog text is wrong, though: it says calls "will lack traceId and sessionId"; in reality the event is dropped. Fix the text and use 1105 for the warn-once.
2. Cross-spec gap with SDK/shared/ingest: tool results with isError: true must count as errors (status error, category tool_error) #75. Under SDK/shared/ingest: tool results with isError: true must count as errors (status error, category tool_error) #75 an isError result's first text item becomes error_message. For a tool with per-tool outputValues: false that text is output — a handler echoing "postal code 12345 invalid" or "no tariff for customer number …" leaks the input the override exists to hide. Rule: with outputValues: false, keep status/error_category but drop the result-derived error_message. (The thrown-path message can stay — developer-written, as the spec says.)
3. Keep client meta coupled to inputValues — but for a stronger reason than "one code path". Decoupling would silently start collecting subject_id/locale/country_code for every existing integrator who set inputValues: false as their privacy posture (R+V, Shipal). That is a collection expansion with app-store sensitivity (the session-ID decline), not a refactor, and needs its own opt-in decision. It costs Commerce for Agents nothing: conversion events never carry subject_id (events.ts:21-32 base fields have only user_id), and the session's other calls still carry it. Phrase the Open Question that way so nobody "fixes" it casually later.

Implementation note for intent: false: intent.ts isEligible() currently means strip and capture. A disabled tool needs a third state — never advertise, never capture, still strip a sent context (a client with a cached schema will keep sending it, and a strict schema would reject the call). Add a test for exactly that: strict Zod schema + per-tool intent: false + client sends context → handler receives no context, call succeeds, nothing captured.

Scope note: this is on/off per tool; #73 item 2 (per-tool required/optional) stays open.

[marselsel]

Author response (2026-08-26): all three corrections accepted, spec updated (.specs/sdk/per-tool-capture.md).

1. Warn-once reuses YAVIO-1105 (CONTEXT_INJECTION_UNAVAILABLE); the catalog text is corrected to "event is dropped"; 02-sdk/02-tracking-api.mdx is listed as a docs change (it currently documents the silence as intended).
2. Cross-spec rule with SDK/shared/ingest: tool results with isError: true must count as errors (status error, category tool_error) #75 added: outputValues: false keeps status/error_category and drops the result-derived error_message; thrown-path message stays.
3. Client-meta coupling kept, now with the collection-expansion rationale (existing integrators with inputValues: false as privacy posture; conversions never carry subject_id), phrased as a policy question in Open Questions.

Also folded in: intent: false as a third controller state (never advertise, never capture, still strip) with the strict-schema test you described; scope note that #73 item 2 stays open; live numbers (46 switch_link_issued vs 0 booking_received; the switch-link tool has since been removed, so the booking is now the only conversion).