@cyanheads/mcp-ts-core 0.8.3 → 0.8.5

package/skills/add-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "2.0"
+  version: "2.4"
   audience: external
   type: reference
 ---
@@ -65,9 +65,19 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
   // (InternalError, ServiceUnavailable, Timeout, ValidationError,
   // SerializationError) bubble freely — only declare domain-specific reasons.
   // Delete this block if no domain failures apply.
+  //
+  // `recovery` is required (≥ 5 words) — it's the agent's next move when this
+  // failure fires. Forcing function for thoughtful guidance: placeholders like
+  // "Try again." get flagged by the linter. The contract `recovery` is the
+  // single source of truth for what flows to the wire — opt in at the throw
+  // site by spreading `ctx.recoveryFor('reason')` into the `data` arg.
   errors: [
-    { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No items matched the query.' },
-    { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited, when: 'Local queue at capacity.', retryable: true },
+    { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
+      when: 'No items matched the query.',
+      recovery: 'Broaden the query or check the spelling and try again.' },
+    { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited,
+      when: 'Local queue at capacity.', retryable: true,
+      recovery: 'Wait a few seconds before retrying or reduce batch size.' },
   ],
 
   async handler(input, ctx) {
@@ -76,7 +86,18 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
     // With an `errors[]` contract: `throw ctx.fail('reason_id', message?, data?)`.
     // Without: throw via factories (`notFound`, `validationError`, …) or plain `Error`.
     const items = await search(input);
-    if (items.length === 0) throw ctx.fail('no_match', `No items matched "${input.query}"`);
+    if (items.length === 0) {
+      // Dynamic recovery — interpolate runtime context, override the contract default.
+      throw ctx.fail('no_match', `No items matched "${input.query}"`, {
+        recovery: { hint: `Try a broader query than "${input.query}", or check the spelling.` },
+      });
+    }
+    if (queue.full()) {
+      // Static recovery — resolve from the contract via ctx.recoveryFor('reason').
+      // Single source of truth: the string lives in errors[] above; this spread
+      // pulls it onto the wire so format()-only clients see the recovery hint.
+      throw ctx.fail('queue_full', undefined, { ...ctx.recoveryFor('queue_full') });
+    }
     return { items };
   },
 
@@ -277,46 +298,59 @@ export const fetchArticles = tool('fetch_articles', {
   description: 'Fetch articles by PMID.',
   errors: [
     { reason: 'no_pmid_match', code: JsonRpcErrorCode.NotFound,
-      when: 'None of the requested PMIDs returned data.' },
+      when: 'None of the requested PMIDs returned data.',
+      recovery: 'Try pubmed_search_articles to discover valid PMIDs first.' },
     { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited,
-      when: 'Local request queue at capacity.', retryable: true },
+      when: 'Local request queue at capacity.', retryable: true,
+      recovery: 'Wait 30 seconds and retry, or reduce batch size.' },
   ],
   input: z.object({ pmids: z.array(z.string()).describe('PMIDs to fetch') }),
   output: z.object({ articles: z.array(ArticleSchema).describe('Resolved articles') }),
   async handler(input, ctx) {
-    if (queue.full()) throw ctx.fail('queue_full');
+    // Static recovery — ctx.recoveryFor pulls the contract recovery onto the wire.
+    // The contract is the single source of truth; this spread surfaces it on the
+    // wire so format()-only clients see the hint mirrored into content[] text.
+    if (queue.full()) throw ctx.fail('queue_full', undefined, { ...ctx.recoveryFor('queue_full') });
+
     const articles = await fetch(input.pmids);
     if (articles.length === 0) {
-      throw ctx.fail('no_pmid_match', `No data for ${input.pmids.length} PMIDs`, { pmids: input.pmids });
+      // Dynamic recovery — interpolate runtime context, override the contract default.
+      throw ctx.fail('no_pmid_match', `No data for ${input.pmids.length} PMIDs`, {
+        pmids: input.pmids,
+        recovery: { hint: `Use pubmed_search_articles to discover valid PMIDs.` },
+      });
     }
     return { articles };
   },
 });
 ```
 
+**`ctx.recoveryFor(reason)`** resolves the contract's `recovery` string into the wire shape `{ recovery: { hint } }` — safe to spread into `data` so format()-only clients see the same recovery hint that structuredContent clients read. Always available on `Context` (no-op `{}` when no contract), strictly typed on `HandlerContext<R>` against the declared reasons. Use it for static recovery; pass `{ recovery: { hint: \`…${dynamic}…\` } }` directly when you need runtime context. The contract is the single source of truth — write the recovery once, lint validates it ≥5 words, the resolver carries it to every throw site.
+
 **Baseline codes** (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring. Wire-level behavior is identical when the contract is omitted, but you lose the type-checked `ctx.fail`, the `tools/list` advertisement, and conformance lint coverage — declare a contract whenever the tool has a domain-specific failure mode.
 
 `ctx.fail` accepts an optional 4th `options` argument for ES2022 cause chaining: `throw ctx.fail('upstream_error', 'Upstream returned 500', { url }, { cause: e })`.
 
 #### Service-layer throws
 
-API-wrapping tools usually delegate to a service: `const data = await ncbi.fetch(input)`. The throw lives in the service, not the handler — and services don't receive `ctx`, so `ctx.fail` is unreachable from there. The fix is to pass `data: { reason: 'X' }` to the factory in the service. The framework's auto-classifier preserves `data` on the wire, so clients see the same `error.data.reason` they would have seen from `ctx.fail`. The handler doesn't catch — it just bubbles.
+API-wrapping tools usually delegate to a service: `await ncbi.fetch(input, ctx)`. The throw lives in the service, not the handler. Services accept `ctx` (the unified Context) so they can call `ctx.log`, `ctx.recoveryFor`, etc. The handler doesn't catch — it just bubbles, and the framework's auto-classifier preserves `data` on the wire.
 
-The contract entry on the tool and the `data: { reason }` on the service throw need to use the **same reason string** so the two sides line up.
+The contract entry on the tool and the `data: { reason }` on the service throw need to use the **same reason string** so the two sides line up. `ctx.recoveryFor('reason')` resolves the contract recovery from the calling tool's `errors[]` — same single-source-of-truth pattern that works in handlers.
 
 ```typescript
-// service — passes data.reason to match the consuming tool's contract
+// service — receives ctx; passes data.reason and spreads ctx.recoveryFor
+import type { Context } from '@cyanheads/mcp-ts-core';
 import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
 
 export class NcbiService {
-  async fetch(pmids: string[]) {
+  async fetch(pmids: string[], ctx: Context) {
     const response = await fetchWithRetry(...);
     if (!response.ok) {
-      throw serviceUnavailable(
-        `NCBI returned HTTP ${response.status}`,
-        { reason: 'ncbi_unreachable', status: response.status },  // ← matches contract entry
-        { cause: undefined },
-      );
+      throw serviceUnavailable(`NCBI returned HTTP ${response.status}`, {
+        reason: 'ncbi_unreachable',
+        status: response.status,
+        ...ctx.recoveryFor('ncbi_unreachable'),  // resolves from caller's contract
+      });
     }
     return response.json();
   }
@@ -326,14 +360,17 @@ export class NcbiService {
 export const fetchArticles = tool('fetch_articles', {
   errors: [
     { reason: 'ncbi_unreachable', code: JsonRpcErrorCode.ServiceUnavailable,
-      when: 'NCBI E-utilities is unreachable.', retryable: true },
+      when: 'NCBI E-utilities is unreachable.', retryable: true,
+      recovery: 'NCBI is degraded; retry in a few minutes.' },
   ],
   async handler(input, ctx) {
-    return { articles: await ncbi.fetch(input.pmids) };  // throws bubble unchanged
+    return { articles: await ncbi.fetch(input.pmids, ctx) };  // throws bubble unchanged
   },
 });
 ```
 
+`ctx.recoveryFor` returns `{}` when the calling tool has no contract or the reason isn't declared, so the spread is always safe — services don't have to know which tool called them.
+
 See `add-service` for the full pattern.
 
 #### Ad-hoc factory throws (fallback)
@@ -354,15 +391,23 @@ throw notFound(
 import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
 throw serviceUnavailable(`arXiv API returned HTTP ${status}. Retry in a few seconds.`);
 
-// Structured hint for programmatic recovery
+// Recovery hint via the canonical `data.recovery.hint` shape — the framework
+// auto-mirrors it into the content[] text as `Recovery: <hint>`, so format()-only
+// clients (Claude Desktop) see the same guidance that structuredContent clients
+// (Claude Code) read from `error.data.recovery.hint`. Other `data` keys reach
+// structuredContent only.
 import { invalidParams } from '@cyanheads/mcp-ts-core/errors';
 throw invalidParams(
-  `Date range exceeds 90-day API limit. Narrow the range or split into multiple queries.`,
-  { maxDays: 90, requestedDays: daysBetween },
+  `Date range exceeds 90-day API limit.`,
+  {
+    maxDays: 90,
+    requestedDays: daysBetween,
+    recovery: { hint: 'Narrow the range or split into multiple queries.' },
+  },
 );
 ```
 
-**Error messages are recovery instructions.** Name what went wrong, why, and what action to take. The message is the agent's only signal — a bare "Not found" is a dead end. See `skills/api-errors/SKILL.md` for the full contract pattern, factories list, and auto-classification table.
+**Error messages are recovery instructions.** Name what went wrong, why, and what action to take. The message is the agent's only signal — a bare "Not found" is a dead end. See `skills/api-errors/SKILL.md` for the full contract pattern, factories list, auto-classification table, and error-path parity (how `data.recovery.hint` reaches both client surfaces).
 
 ### Include operational metadata
 

package/skills/api-auth/SKILL.md

@@ -121,10 +121,11 @@ Set via `MCP_AUTH_MODE` environment variable.
 
 ### tenantId sources
 
-| Transport | Source | Value |
-|:----------|:-------|:------|
-| HTTP with auth | JWT `tid` claim | Auto-propagated from token |
-| Stdio | Hardcoded default | `'default'` |
+| Mode | Source | Value |
+|:-----|:-------|:------|
+| Stdio (any auth mode) | Hardcoded default | `'default'` |
+| HTTP + `MCP_AUTH_MODE=none` | Hardcoded default | `'default'` (single-tenant by design) |
+| HTTP + `MCP_AUTH_MODE=jwt`/`oauth` | JWT `tid` claim | Auto-propagated from token; `undefined` if absent (fail-closed) |
 
 ### Tenant ID validation rules
 
@@ -148,7 +149,7 @@ handler: async (input, ctx) => {
 },
 ```
 
-`ctx.state` throws `McpError(InvalidRequest)` if `tenantId` is missing. In stdio mode, `tenantId` defaults to `'default'` so `ctx.state` works without auth.
+`ctx.state` throws `McpError(InvalidRequest)` if `tenantId` is missing. Stdio (any auth mode) and HTTP+`MCP_AUTH_MODE=none` default `tenantId` to `'default'` so `ctx.state` works without forcing operators to mint tokens. HTTP+`jwt`/`oauth` deliberately fails closed when the token lacks a `tid` claim — distinct authenticated callers must not silently share state.
 
 ---
 

package/skills/api-context/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.sample`, `ctx.progress`), and when to use each.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: reference
 ---
@@ -26,7 +26,7 @@ interface Context {
   // Identity & tracing
   readonly requestId: string;       // Unique per request, auto-generated
   readonly timestamp: string;       // ISO 8601 request start time
-  readonly tenantId?: string;       // From JWT 'tid' claim; 'default' in stdio mode
+  readonly tenantId?: string;       // JWT 'tid' claim; 'default' for stdio and HTTP+MCP_AUTH_MODE=none
   readonly traceId?: string;        // OTEL trace ID (present when OTEL enabled)
   readonly spanId?: string;         // OTEL span ID (present when OTEL enabled)
   readonly auth?: AuthContext;      // Parsed auth claims (clientId, scopes, sub)
@@ -53,10 +53,14 @@ interface Context {
 
   // Raw URI — present only for resource handlers
   readonly uri?: URL;
+
+  // Opt-in contract resolver — always present (returns {} when no contract is attached
+  // or the reason is unknown), strictly typed on HandlerContext<R> against declared reasons.
+  recoveryFor(reason: string): { recovery: { hint: string } } | {};
 }
 ```
 
-> **`ctx.fail` is on `HandlerContext<R>`, not `Context`.** When a definition declares `errors: [...]`, the handler receives `HandlerContext<R> = Context & { fail: TypedFail<R> }` — the typed `fail` lives on the intersection, not on bare `Context`. See [`ctx.fail`](#ctxfail) below.
+> **`ctx.fail` is on `HandlerContext<R>`, not `Context`.** When a definition declares `errors: [...]`, the handler receives `HandlerContext<R> = Context & { fail: TypedFail<R>; recoveryFor: TypedRecoveryFor<R> }` — both the typed `fail` and the strictly-typed `recoveryFor` live on the intersection. The bare `Context.recoveryFor` is the loose, always-present resolver. See [`ctx.fail`](#ctxfail) and [`ctx.recoveryFor`](#ctxrecoveryfor) below.
 
 ### Identity fields
 
@@ -64,7 +68,7 @@ interface Context {
 |:------|:--------------|:-------|
 | `requestId` | Yes | Auto-generated UUID per request |
 | `timestamp` | Yes | ISO 8601, request start |
-| `tenantId` | In stdio (as `'default'`); from JWT `tid` claim in HTTP | JWT / stdio default |
+| `tenantId` | Stdio and HTTP+`MCP_AUTH_MODE=none` (as `'default'`); JWT `tid` claim in HTTP+`jwt`/`oauth` | JWT / single-tenant default |
 | `traceId` | When OTEL enabled | OTEL trace context |
 | `spanId` | When OTEL enabled | OTEL trace context |
 | `auth` | When auth enabled | Parsed JWT claims |
@@ -158,7 +162,7 @@ if (page.cursor) { /* more pages available */ }
 
 ### Behavior notes
 
-- Throws `McpError(InvalidRequest)` if `tenantId` is missing (won't happen in stdio mode — defaults to `'default'`).
+- Throws `McpError(InvalidRequest)` if `tenantId` is missing. Won't happen in stdio (any auth mode) or HTTP+`MCP_AUTH_MODE=none` — both default to `'default'`. Can happen in HTTP+`MCP_AUTH_MODE=jwt`/`oauth` when the token lacks a `tid` claim (intentional fail-closed: distinct authenticated callers must not silently share state).
 - Keys are tenant-prefixed internally; handlers never need to namespace manually.
 - **Workers persistence:** The `in-memory` provider loses data on cold starts. Use `cloudflare-kv`, `cloudflare-r2`, or `cloudflare-d1` for durable storage in Workers.
 
@@ -391,13 +395,57 @@ The contract is opt-in. See `skills/api-errors/SKILL.md` for the full type-drive
 
 ---
 
+## `ctx.recoveryFor`
+
+Always present on `Context`. Resolves the contract `recovery` for a given reason and returns the canonical wire shape `{ recovery: { hint } }`, ready to spread into `data`. The first member of a planned **family of opt-in resolution helpers** (future: `troubleshootingFor`, `userMessageFor`, …).
+
+```ts
+async handler(input, ctx) {
+  // Static recovery — pulled from the contract entry, no string duplication.
+  if (queue.full()) throw ctx.fail('queue_full', undefined, { ...ctx.recoveryFor('queue_full') });
+
+  // Dynamic recovery — interpolate runtime context, override the contract default.
+  if (!matched) throw ctx.fail('no_match', `No items for "${input.query}"`, {
+    recovery: { hint: `Try a broader query than "${input.query}", or check spelling.` },
+  });
+}
+```
+
+### Signature
+
+```ts
+// Loose (always present on Context — works without a contract attached):
+ctx.recoveryFor(reason: string): { recovery: { hint: string } } | {}
+
+// Strict (HandlerContext<R> when the definition declares errors[]):
+ctx.recoveryFor(reason: R): { recovery: { hint: string } }
+```
+
+### Behavior
+
+| Aspect | Detail |
+|:-------|:-------|
+| No contract attached | Returns `{}` — spread is a no-op. Always safe. |
+| Unknown reason | Returns `{}` (TS prevents this for typed callers; runtime is loose for JS / stale contracts). |
+| Declared reason | Returns `{ recovery: { hint: <contract.recovery> } }` — spread into `data`. |
+| Override | Caller can override by spreading `recoveryFor` first then writing `recovery: { hint: '...' }` after — last write wins. |
+| Service usage | Services that accept `ctx: Context` can spread `ctx.recoveryFor('reason')` directly; the no-op fallback means they don't need to know which tool called them. |
+
+### Why opt-in resolution, not auto-population
+
+The framework never injects `data.recovery.hint` without an explicit signal at the throw site. Authors opt in by typing `ctx.recoveryFor('reason')` — the same way `ctx.fail('reason')` opts into resolving the contract `code`. The contract is the single source of truth for the recovery hint; the resolver is a typed lookup keyed by the same reason the author already typed. No magic, no hidden transformation.
+
+The `≥5 words` lint rule on contract `recovery` (validated at lint time) makes this load-bearing — every `ctx.recoveryFor` call site benefits from the thoughtfulness the contract enforced.
+
+---
+
 ## Quick reference
 
 | Property | Type | Present when |
 |:---------|:-----|:-------------|
 | `ctx.requestId` | `string` | Always |
 | `ctx.timestamp` | `string` | Always |
-| `ctx.tenantId` | `string \| undefined` | Always in stdio (`'default'`); HTTP with auth |
+| `ctx.tenantId` | `string \| undefined` | Stdio (`'default'`); HTTP+`MCP_AUTH_MODE=none` (`'default'`); HTTP+`jwt`/`oauth` (JWT `tid` claim — undefined if absent) |
 | `ctx.traceId` | `string \| undefined` | OTEL enabled |
 | `ctx.spanId` | `string \| undefined` | OTEL enabled |
 | `ctx.auth` | `AuthContext \| undefined` | Auth enabled |
@@ -411,3 +459,4 @@ The contract is opt-in. See `skills/api-errors/SKILL.md` for the full type-drive
 | `ctx.progress` | `ContextProgress \| undefined` | Tool defined with `task: true` |
 | `ctx.uri` | `URL \| undefined` | Resource handlers only |
 | `ctx.fail` | `(reason, msg?, data?, opts?) => McpError` | Definition declares `errors[]` contract |
+| `ctx.recoveryFor` | `(reason) => { recovery: { hint } } \| {}` | Always (no-op when no contract); strictly typed on `HandlerContext<R>` |

package/skills/api-errors/SKILL.md

@@ -4,7 +4,7 @@ description: >
   McpError constructor, JsonRpcErrorCode reference, and error handling patterns for `@cyanheads/mcp-ts-core`. Use when looking up error codes, understanding where errors should be thrown vs. caught, or using ErrorHandler.tryCatch in services.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.4"
   audience: external
   type: reference
 ---
@@ -37,11 +37,14 @@ export const fetchTool = tool('fetch_articles', {
 
   errors: [
     { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
-      when: 'No requested PMID returned data' },
+      when: 'No requested PMID returned data',
+      recovery: 'Try pubmed_search_articles to discover valid PMIDs first.' },
     { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited,
-      when: 'Local request queue is at capacity', retryable: true },
+      when: 'Local request queue is at capacity', retryable: true,
+      recovery: 'Wait 30 seconds and retry, or reduce batch size.' },
     { reason: 'ncbi_down', code: JsonRpcErrorCode.ServiceUnavailable,
-      when: 'NCBI E-utilities unreachable after retries', retryable: true },
+      when: 'NCBI E-utilities unreachable after retries', retryable: true,
+      recovery: 'NCBI is degraded; retry in a few minutes.' },
   ],
 
   async handler(input, ctx) {
@@ -61,9 +64,60 @@ export const fetchTool = tool('fetch_articles', {
 |:--------|:---------|
 | Compile time | `ctx.fail('typo')` is a TS error. Auto-completes declared reasons. |
 | Runtime | `ctx.fail(reason, msg?, data?, options?)` builds an `McpError(contract.code, msg, { ...data, reason }, options)` — `data.reason` is auto-populated from the contract and cannot be overridden by caller-supplied data (spread first, then `reason` written last), so observers see a stable identifier. `options` accepts `{ cause }` for ES2022 error chaining. |
-| Lint (startup) | Each `code` validated against `JsonRpcErrorCode`. Reasons validated as snake_case + unique within contract. |
+| Lint (startup) | Each `code` validated against `JsonRpcErrorCode`. Reasons validated as snake_case + unique within contract. `recovery` validated as non-empty and ≥ 5 words. |
 | Lint (conformance) | If the handler `throw new McpError(JsonRpcErrorCode.X)` outside `ctx.fail`, conformance check warns when X isn't declared. |
 
+> **`recovery` is opt-in resolution, not auto-population.** The contract `recovery` is required metadata documenting the agent's next move when this failure mode fires (a forcing function for thoughtful guidance — placeholders like "Try again." get flagged by the linter). It does **not** automatically appear in runtime `data.recovery.hint` — the framework never injects it without an explicit signal at the throw site. Authors opt in by spreading `ctx.recoveryFor('reason')` into the `data` argument, the same way `ctx.fail('reason')` opts into resolving the contract `code`. What the author types at the throw site is what flows to the wire, with no hidden transformation; the resolver is just a typed lookup keyed by the same `reason` the author already typed.
+
+#### `ctx.recoveryFor` — opt-in contract resolution
+
+`ctx.recoveryFor(reason)` returns `{ recovery: { hint: <contract.recovery> } }` for a declared reason, ready to spread into `data`. Always available on `Context` (returns `{}` when no contract is attached or the reason is unknown — spread-safe with no optional chaining). On `HandlerContext<R>` it tightens to a typed signature constrained to the declared reason union.
+
+```ts
+export const calculateTool = tool('calculate', {
+  // ...
+  errors: [
+    { reason: 'empty_expression', code: JsonRpcErrorCode.ValidationError,
+      when: 'Expression is empty or whitespace-only.',
+      recovery: 'Provide a non-empty mathematical expression to evaluate.' },
+  ],
+  handler(input, ctx) {
+    if (!input.expression.trim()) {
+      // Static recovery — resolve from the contract.
+      throw ctx.fail('empty_expression', undefined, { ...ctx.recoveryFor('empty_expression') });
+    }
+    // ...
+  },
+});
+```
+
+Same pattern works inside services that accept `ctx`:
+
+```ts
+export class MathService {
+  parse(expr: string, ctx: Context) {
+    try {
+      return mathjs.parse(expr);
+    } catch (err) {
+      throw validationError(`Parse failed: ${err.message}`, {
+        reason: 'parse_failed',
+        ...ctx.recoveryFor('parse_failed'),  // {} if calling tool has no matching reason
+      });
+    }
+  }
+}
+```
+
+The contract is the single source of truth — write the recovery once, lint validates ≥5 words, the resolver carries it to every throw site that opts in. For runtime-context recovery (interpolating input values, attempted IDs, queue state), override at the throw site:
+
+```ts
+throw ctx.fail('no_match', `No item ${id}`, {
+  recovery: { hint: `No item ${id}; try IDs 1-100 instead.` },
+});
+```
+
+`ctx.recoveryFor` is the first member of a planned **family of opt-in resolution helpers**. Future contract-bound fields (`troubleshootingFor`, `userMessageFor`, …) follow the same shape: single-purpose, spreadable wire-shape, `{}` fallback when not applicable.
+
 **Skip the contract** for one-off internal tools or quick prototypes — `ctx` is plain `Context` (no `fail`) and you throw via [factories](#error-factories-fallback) directly. Behavior is identical at the wire; the contract just adds compile-time safety.
 
 > **Limits of the conformance lint.** The conformance and prefer-fail rules scan the handler's source text for `throw` statements. Errors thrown from called services (e.g. `await myService.fetch()` raising `RateLimited` internally) are invisible — the lint only sees what's lexically in the handler. Treat the contract as the *advertised* failure surface; bubbled-up codes still reach the client correctly via the auto-classifier, just without lint enforcement.
@@ -81,13 +135,28 @@ throw serviceUnavailable('Upstream timeout',          { reason: 'evaluation_time
 ```ts
 // my-tool.tool.ts
 errors: [
-  { reason: 'empty_expression',   code: JsonRpcErrorCode.ValidationError,    when: 'Input is empty.' },
-  { reason: 'evaluation_timeout', code: JsonRpcErrorCode.ServiceUnavailable, when: 'Upstream exceeded the configured timeout.' },
+  { reason: 'empty_expression',   code: JsonRpcErrorCode.ValidationError,
+    when: 'Input is empty.',
+    recovery: 'Provide a non-empty expression to evaluate.' },
+  { reason: 'evaluation_timeout', code: JsonRpcErrorCode.ServiceUnavailable,
+    when: 'Upstream exceeded the configured timeout.',
+    recovery: 'Simplify the expression or retry the request after a brief delay.' },
 ]
 ```
 
 The handler doesn't catch and re-throw — letting service errors bubble unchanged keeps "logic throws, framework catches" intact. The wire payload still carries `code` + `data.reason`, and clients can switch on reason without parsing message text. What's lost is lint-time enforcement that every reason is reachable; compensate with one wire-shape test per reason.
 
+To carry the contract `recovery` from a service throw, accept `ctx` and spread the resolver:
+
+```ts
+throw validationError(message, {
+  reason: 'parse_failed',
+  ...ctx.recoveryFor('parse_failed'),  // {} when calling tool has no matching reason
+});
+```
+
+`ctx.recoveryFor` is always present on `Context` (no-op when no contract), so services don't need to know which tool called them — the spread is safe either way.
+
 ---
 
 ## Error Factories (fallback)
@@ -416,6 +485,9 @@ The linter validates the structure of `errors[]` and (when present) cross-checks
 | `error-contract-reason-format` | warning | `reason` not snake_case |
 | `error-contract-reason-unique` | error | Duplicate `reason` within one contract |
 | `error-contract-when-required` | error | `when` missing or empty |
+| `error-contract-recovery-required` | error | `recovery` missing or not a string |
+| `error-contract-recovery-empty` | error | `recovery` is empty/whitespace-only |
+| `error-contract-recovery-min-words` | warning | `recovery` has fewer than 5 words — placeholders like "Try again." or "Check input." get flagged in favor of specific guidance |
 | `error-contract-retryable-type` | warning | `retryable` is present but not a boolean |
 
 ### Conformance rules

package/skills/design-mcp-server/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Design the tool surface, resources, and service layer for a new MCP server. Use when starting a new server, planning a major feature expansion, or when the user describes a domain/API they want to expose via MCP. Produces a design doc at docs/design.md that drives implementation.
 metadata:
   author: cyanheads
-  version: "2.7"
+  version: "2.8"
   audience: external
   type: workflow
 ---
@@ -346,10 +346,17 @@ throw new Error('Not found');
 // Good — names both resolution options
 "No session working directory set. Please specify a 'path' or use 'git_set_working_dir' first."
 
-// Good — structured hint in error data
+// Good — structured hint in error data using the canonical `data.recovery.hint` shape.
+// The framework auto-mirrors `data.recovery.hint` into the content[] text as
+// `Recovery: <hint>` so format()-only clients (Claude Desktop) see the same
+// guidance structuredContent clients (Claude Code) read from `error.data.recovery.hint`.
 throw forbidden(
   "Cannot perform 'reset --hard' on protected branch 'main' without explicit confirmation.",
-  { branch: 'main', operation: 'reset --hard', hint: 'Set the confirmed parameter to true to proceed.' },
+  {
+    branch: 'main',
+    operation: 'reset --hard',
+    recovery: { hint: 'Set the confirmed parameter to true to proceed.' },
+  },
 );
 
 // Good — upstream error with actionable context

package/templates/AGENTS.md

@@ -168,11 +168,13 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire payload's `data.recovery.hint` (which the framework mirrors into `content[]` text), pass it explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
 errors: [
-  { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No item matched the query' },
+  { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
+    when: 'No item matched the query',
+    recovery: 'Broaden the query or check the spelling and try again.' },
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);

package/templates/CLAUDE.md

@@ -168,11 +168,13 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire payload's `data.recovery.hint` (which the framework mirrors into `content[]` text), pass it explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
 errors: [
-  { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No item matched the query' },
+  { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
+    when: 'No item matched the query',
+    recovery: 'Broaden the query or check the spelling and try again.' },
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);

package/templates/src/mcp-server/tools/definitions/echo.tool.ts

@@ -28,6 +28,7 @@ export const echoTool = tool('template_echo_message', {
       reason: 'empty_message',
       code: JsonRpcErrorCode.InvalidParams,
       when: 'Message contained only whitespace.',
+      recovery: 'Provide a message with at least one non-whitespace character.',
     },
   ],