@cyanheads/mcp-ts-core 0.12.6 → 0.12.7

package/scripts/devcheck.ts

@@ -139,6 +139,12 @@ interface Check {
   /** If true, this check is skipped in fast mode (typically network-bound or very slow). */
   slowCheck?: boolean;
   tip?: (c: Colors) => string;
+  /**
+   * Optional rewrite of the output shown in the summary, applied after
+   * `isSuccess` has read the tool's own output. Use when a tool reports a
+   * defensible verdict under a name the project does not recognize.
+   */
+  transformOutput?: (result: ShellResult) => string;
 }
 
 // =============================================================================
@@ -273,22 +279,275 @@ const OUTDATED_ALLOWLIST = new Set(DEVCHECK_CONFIG.outdated?.allowlist ?? []);
 /** Use bun for package management commands if available, otherwise npm. */
 const PM_CMD = spawnSync('bun', ['--version'], { stdio: 'ignore' }).status === 0 ? 'bun' : 'npm';
 
+// ── Declared dependency identity (alias-aware) ───────────────────────
+
+/** The package.json block that declared a dependency, as `bun outdated` marks it. */
+type DependencyGroup = 'dev' | 'optional' | 'peer' | 'prod';
+
 /**
- * Direct dependencies from package.json, used to classify audit vulnerabilities
- * as direct (fixable by us) vs transitive/upstream (requires upstream fix).
+ * One `package.json` dependency entry resolved through any `npm:` alias.
+ * `bun outdated` reports rows under the *resolved* package name, so
+ * `"typescript-v6": "npm:typescript@^6.0.3"` is printed as `typescript`.
+ * Carrying the declared key alongside the resolved target is what lets the
+ * Outdated check name — and allowlist — the dependency the project declares.
  */
-const DIRECT_DEPS: ReadonlySet<string> = (() => {
+interface DeclaredDependency {
+  group: DependencyGroup;
+  /** The `package.json` key. */
+  key: string;
+  /** Version range with any `npm:<target>@` alias prefix stripped. */
+  range: string;
+  /** Registry package name the key resolves to; equals `key` when not aliased. */
+  target: string;
+}
+
+const DEPENDENCY_GROUPS: ReadonlyArray<readonly [DependencyGroup, string]> = [
+  ['prod', 'dependencies'],
+  ['dev', 'devDependencies'],
+  ['peer', 'peerDependencies'],
+  ['optional', 'optionalDependencies'],
+];
+
+/** Splits an `npm:<target>@<range>` alias spec; returns null for a plain range. */
+function parseAliasSpec(spec: string): { range: string; target: string } | null {
+  if (!spec.startsWith('npm:')) return null;
+  const rest = spec.slice(4);
+  // Scoped targets lead with `@`, so only a later `@` separates the range.
+  const separator = rest.lastIndexOf('@');
+  if (separator <= 0) return { range: '*', target: rest };
+  return { range: rest.slice(separator + 1), target: rest.slice(0, separator) };
+}
+
+const DECLARED_DEPENDENCIES: readonly DeclaredDependency[] = (() => {
   try {
     const pkg = JSON.parse(readFileSync(path.join(ROOT_DIR, 'package.json'), 'utf-8'));
-    return new Set<string>([
-      ...Object.keys(pkg.dependencies ?? {}),
-      ...Object.keys(pkg.devDependencies ?? {}),
-    ]);
+    const declared: DeclaredDependency[] = [];
+    for (const [group, block] of DEPENDENCY_GROUPS) {
+      for (const [key, spec] of Object.entries(pkg[block] ?? {})) {
+        if (typeof spec !== 'string') continue;
+        const alias = parseAliasSpec(spec);
+        declared.push({ group, key, range: alias?.range ?? spec, target: alias?.target ?? key });
+      }
+    }
+    return declared;
   } catch {
-    return new Set<string>();
+    return [];
   }
 })();
 
+/** Direct dependency keys used to distinguish direct audit findings from transitive ones. */
+const DIRECT_DEPS: ReadonlySet<string> = new Set(
+  DECLARED_DEPENDENCIES.filter(({ group }) => group === 'prod' || group === 'dev').map(
+    ({ key }) => key,
+  ),
+);
+
+// ── Minimal range matching (alias attribution only) ──────────────────
+
+type VersionTriple = readonly [number, number, number];
+
+/** Parses a possibly partial version (`6`, `0.12`, `1.2.3-rc.1`) plus its precision. */
+function parseVersionParts(value: string): { segments: number; triple: VersionTriple } | null {
+  const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(value.trim().replace(/^[v=\s]+/, ''));
+  if (!match) return null;
+  const segments = match[3] !== undefined ? 3 : match[2] !== undefined ? 2 : 1;
+  return {
+    segments,
+    triple: [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)],
+  };
+}
+
+function compareVersions(a: VersionTriple, b: VersionTriple): number {
+  for (let index = 0; index < 3; index++) {
+    const difference = (a[index] ?? 0) - (b[index] ?? 0);
+    if (difference !== 0) return difference < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/** The exclusive upper bound of a caret range, honoring 0.x and partial versions. */
+function caretCeiling(bound: VersionTriple, segments: number): VersionTriple {
+  if (bound[0] > 0) return [bound[0] + 1, 0, 0];
+  if (segments === 1) return [1, 0, 0];
+  if (bound[1] > 0) return [0, bound[1] + 1, 0];
+  if (segments === 2) return [0, 1, 0];
+  return [0, 0, bound[2] + 1];
+}
+
+/**
+ * Whether a version satisfies one comparator. Covers the operators a
+ * hand-written `package.json` range uses (`^`, `~`, exact, the four
+ * inequalities). Anything unrecognized is treated as unconstrained, so an
+ * exotic range never *excludes* a candidate — attribution then reports
+ * ambiguity instead of guessing.
+ */
+function comparatorAdmits(comparator: string, version: VersionTriple): boolean {
+  const token = comparator.trim();
+  if (token === '' || token === '*' || token === 'x' || token === 'latest') return true;
+  const match = /^(\^|~|>=|<=|>|<|=)?\s*(.+)$/.exec(token);
+  const parsed = parseVersionParts(match?.[2] ?? '');
+  if (!parsed) return true;
+  const order = compareVersions(version, parsed.triple);
+  switch (match?.[1] ?? '=') {
+    case '>':
+      return order > 0;
+    case '>=':
+      return order >= 0;
+    case '<':
+      return order < 0;
+    case '<=':
+      return order <= 0;
+    case '~': {
+      const ceiling: VersionTriple =
+        parsed.segments === 1
+          ? [parsed.triple[0] + 1, 0, 0]
+          : [parsed.triple[0], parsed.triple[1] + 1, 0];
+      return order >= 0 && compareVersions(version, ceiling) < 0;
+    }
+    case '^':
+      return (
+        order >= 0 && compareVersions(version, caretCeiling(parsed.triple, parsed.segments)) < 0
+      );
+    default:
+      return order === 0;
+  }
+}
+
+/** Whether an installed version falls inside a declared range. */
+function rangeAdmits(range: string, version: string): boolean {
+  const parsed = parseVersionParts(version);
+  if (!parsed) return true;
+  return range.split('||').some((alternative) =>
+    alternative
+      .trim()
+      .split(/\s+/)
+      .every((comparator) => comparatorAdmits(comparator, parsed.triple)),
+  );
+}
+
+// ── `bun outdated` row attribution ───────────────────────────────────
+
+/** Trailing workspace-type marker `bun outdated` appends to the package cell. */
+const OUTDATED_GROUP_MARKER = /\s*\((dev|peer|prod|optional)\)$/;
+
+/** One parsed `bun outdated` table row, resolved back to what package.json declares. */
+interface OutdatedRow {
+  /** Declared keys the row could belong to, in declaration order. */
+  candidates: string[];
+  current: string;
+  /** The declared key when attribution is unambiguous, else null. */
+  declaredKey: string | null;
+  group: DependencyGroup | null;
+  /** The row verbatim, used to key the rendered rewrite back to its line. */
+  line: string;
+  /** First cell as printed, marker included. */
+  rawName: string;
+  /** Resolved package name `bun outdated` printed. */
+  target: string;
+  update: string;
+}
+
+/**
+ * Maps a printed row back to the `package.json` keys that could have produced
+ * it. A target-name-only map is not enough: a direct dependency and one or more
+ * aliases can share a target, so candidates are narrowed by which declared
+ * range admits the installed version. When that still leaves more than one, the
+ * row is reported as ambiguous rather than attributed — an alias's allowlist
+ * entry must never stand in for a same-named direct dependency's finding.
+ */
+function attributeOutdatedRow(
+  target: string,
+  group: DependencyGroup | null,
+  current: string,
+): Pick<OutdatedRow, 'candidates' | 'declaredKey'> {
+  const matches = DECLARED_DEPENDENCIES.filter(
+    (declared) => declared.target === target && (group === null || declared.group === group),
+  );
+  const candidates = matches.map((declared) => declared.key);
+  if (candidates.length <= 1) return { candidates, declaredKey: candidates[0] ?? null };
+
+  const admitting = matches.filter((declared) => rangeAdmits(declared.range, current));
+  return { candidates, declaredKey: admitting.length === 1 ? (admitting[0]?.key ?? null) : null };
+}
+
+/** Parses the package rows out of a `bun outdated` table, skipping its chrome. */
+function parseOutdatedRows(output: string): OutdatedRow[] {
+  const rows: OutdatedRow[] = [];
+  // `bun outdated` emits markdown-style rows (`| col1 | col2 | ... |`), so
+  // split('|') yields an empty leading cell — package data starts at index [1].
+  for (const line of output.split('\n')) {
+    if (!line.includes('|')) continue;
+    const cells = line.split('|').map((cell) => cell.trim());
+    const rawName = cells[1] ?? '';
+    // Skip table chrome: header row and separator (e.g., "---")
+    if (!rawName || rawName === 'Package' || /^-+$/.test(rawName)) continue;
+    const group = (OUTDATED_GROUP_MARKER.exec(rawName)?.[1] ?? null) as DependencyGroup | null;
+    const target = rawName.replace(OUTDATED_GROUP_MARKER, '');
+    const current = cells[2] ?? '';
+    const update = (cells[3] ?? '').replace(/\*/g, '').trim();
+    rows.push({
+      ...attributeOutdatedRow(target, group, current),
+      current,
+      group,
+      line,
+      rawName,
+      target,
+      update,
+    });
+  }
+  return rows;
+}
+
+/**
+ * Reprints the table with each row named by the dependency the project declares,
+ * so an alias row reads as `typescript-v6 (dev)` rather than `typescript`. Rows
+ * whose attribution is ambiguous keep the printed name and are called out below
+ * the table.
+ */
+function renderOutdatedTable(output: string): string {
+  if (!output.includes('|')) return output;
+  const attributed = new Map(parseOutdatedRows(output).map((row) => [row.line, row]));
+
+  const lines = output.split('\n').map((line) => {
+    const cell = line.split('|')[1];
+    if (cell === undefined || /^-+$/.test(cell.trim())) return { line, display: null };
+    const row = attributed.get(line);
+    let display = cell.trim();
+    if (row?.declaredKey && row.declaredKey !== row.target) {
+      display = row.group ? `${row.declaredKey} (${row.group})` : row.declaredKey;
+    }
+    return { line, display };
+  });
+
+  // Keep bun's own column width unless a declared key needs more room; the
+  // horizontal rules then grow by the same delta so the table stays square.
+  const headerCell = lines.find(({ display }) => display === 'Package')?.line.split('|')[1];
+  const baseWidth = Math.max((headerCell?.length ?? 2) - 2, 0);
+  const width = Math.max(baseWidth, ...lines.map(({ display }) => display?.length ?? 0));
+  const delta = width - baseWidth;
+  const rendered = lines.map(({ line, display }) => {
+    if (display === null) {
+      return delta > 0 && line.includes('|')
+        ? line.replace(/-+/, (run) => run.padEnd(run.length + delta, '-'))
+        : line;
+    }
+    return `| ${display.padEnd(width)} ${line.slice(line.indexOf('|', line.indexOf('|') + 1))}`;
+  });
+
+  const ambiguous = [...attributed.values()].filter(
+    (row) => row.candidates.length > 1 && row.declaredKey === null,
+  );
+  if (ambiguous.length === 0) return rendered.join('\n');
+  return [
+    ...rendered,
+    '',
+    ...ambiguous.map(
+      (row) =>
+        `! ${row.rawName} matches ${row.candidates.join(' and ')} — attribution is ambiguous, so no allowlist entry applies.`,
+    ),
+  ].join('\n');
+}
+
 /**
  * Parses `bun audit` output and classifies high/critical vulnerabilities as
  * direct (in our package.json) or upstream (transitive dependency we can't fix).
@@ -589,6 +848,26 @@ const ALL_CHECKS: Check[] = [
     getCommand: (ctx) => [path.join(ctx.rootDir, 'node_modules', '.bin', 'tsc'), '--noEmit'],
     tip: () => 'Check TypeScript errors in your IDE or the console output.',
   },
+  {
+    name: 'TypeScript (Worker)',
+    flag: '--no-types-worker',
+    canFix: false,
+    // The workerd type environment is its own program: Cloudflare's ambient
+    // globals cannot share one with @types/node's (#397). It reads the built
+    // declarations, so it only has something to check after a build.
+    getCommand: (ctx) => {
+      if (!existsSync(path.join(ctx.rootDir, 'tsconfig.worker.json'))) return null;
+      if (!existsSync(path.join(ctx.rootDir, 'dist'))) return null;
+      return [
+        path.join(ctx.rootDir, 'node_modules', '.bin', 'tsc'),
+        '--project',
+        'tsconfig.worker.json',
+        '--noEmit',
+      ];
+    },
+    tip: (c) =>
+      `Build first (${c.bold('bun run build')}), then ${c.bold('bun run typecheck:worker')}.`,
+  },
   {
     name: 'Tests',
     flag: '--test',
@@ -681,34 +960,21 @@ const ALL_CHECKS: Check[] = [
       const output = result.stdout.trim();
       if (result.exitCode !== 0 && !output.includes('|')) return false;
 
-      // Parse the tabular output. `bun outdated` emits markdown-style rows
-      // (`| col1 | col2 | ... |`), so split('|') yields an empty leading cell —
-      // package data starts at index [1]. Strip the trailing `(dev|peer|prod|optional)`
-      // workspace-type marker so the allowlist takes the bare package name.
-      const lines = output.split('\n');
-      const stripWorkspaceMarker = (cell: string): string =>
-        cell.replace(/\s*\((?:dev|peer|prod|optional)\)$/, '');
-      const packageLines = lines.filter((line) => {
-        if (!line.includes('|')) return false;
-        // Skip table chrome: header row and separator (e.g., "---")
-        const firstCell = line.split('|')[1]?.trim() ?? '';
-        if (!firstCell || firstCell === 'Package' || /^-+$/.test(firstCell)) return false;
-        return true;
-      });
-
       // A row is a real finding only if it's neither allowlisted, a peer range,
       // nor a version held back by bunfig's `minimumReleaseAge` supply-chain guard.
-      const unexpected = packageLines.filter((line) => {
-        const cells = line.split('|').map((cell) => cell.trim());
-        const rawName = cells[1] ?? '';
-        const pkgName = stripWorkspaceMarker(rawName);
-        if (OUTDATED_ALLOWLIST.has(pkgName)) return false;
+      const unexpected = parseOutdatedRows(output).filter((row) => {
+        // The allowlist is keyed on the `package.json` key, so an aliased row
+        // matches through its resolved declaration. Where attribution stayed
+        // ambiguous, no entry applies — suppressing the row would risk hiding a
+        // same-named direct dependency behind an alias's exemption.
+        const ambiguous = row.candidates.length > 1 && row.declaredKey === null;
+        if (!ambiguous && OUTDATED_ALLOWLIST.has(row.declaredKey ?? row.target)) return false;
 
         // A peerDependency range declares the *lowest* version supported, not
         // the version to track — widening it as upstream publishes only narrows
         // what consumers may install. Currency for the versions actually
         // exercised is enforced through the matching devDependency row.
-        if (rawName.endsWith('(peer)')) return false;
+        if (row.group === 'peer') return false;
 
         // `Update` is the newest version installable under the declared range;
         // `Latest` ignores the range. Update === Current means there is nothing
@@ -717,13 +983,12 @@ const ALL_CHECKS: Check[] = [
         // 13.0.1). Crossing that cap is a deliberate range change, i.e.
         // maintenance work rather than a gate failure. The gate fails on what
         // `bun update` would actually change: being behind within the range.
-        const current = cells[2] ?? '';
-        const update = (cells[3] ?? '').replace(/\*/g, '').trim();
-        return !(current !== '' && update === current);
+        return !(row.current !== '' && row.update === row.current);
       });
 
       return unexpected.length === 0;
     },
+    transformOutput: (result) => renderOutdatedTable(result.stdout),
     tip: (c) =>
       `Run ${c.bold(`${PM_CMD} update`)} to upgrade; the ${c.bold('maintenance')} skill then investigates changelogs and adopts upstream changes. Configure allowlist in ${c.bold('devcheck.config.json')}.`,
   },
@@ -967,7 +1232,7 @@ function parseArgs(args: string[]): Omit<AppContext, 'rootDir' | 'stagedFiles'>
 }
 
 async function runCheck(check: Check, ctx: AppContext): Promise<CommandResult> {
-  const { name, getCommand, isSuccess } = check;
+  const { name, getCommand, isSuccess, transformOutput } = check;
   const log: string[] = [];
   const baseResult: CommandResult = {
     checkName: name,
@@ -1070,6 +1335,11 @@ async function runCheck(check: Check, ctx: AppContext): Promise<CommandResult> {
     }
   }
 
+  // 8. Rewrite the displayed output — after isSuccess has read the tool's own.
+  if (transformOutput) {
+    finalResult.stdout = transformOutput(finalResult);
+  }
+
   log.push(UI.formatCheckResult(finalResult, uiMode));
 
   return finalResult;

package/scripts/lint-packaging.ts

@@ -38,7 +38,10 @@
  *      (`name`, server key, `interface.displayName`) carry the unscoped machine
  *      name while the `npx -y` install arg carries the full `package.json`
  *      name (scoped if scoped). An unscoped install arg for a scoped package
- *      is a guaranteed install 404. Gated by `devcheck.config.json`
+ *      is a guaranteed install 404. Each present plugin manifest's `version`
+ *      must equal `package.json`'s, so a release cannot ship stale plugin
+ *      metadata (issue #393); `.codex-plugin/mcp.json` is connection config and
+ *      carries no version. Gated by `devcheck.config.json`
  *      `packaging.pluginManifests` (default on); each manifest is skipped
  *      cleanly when absent (issue #240).
  *
@@ -424,20 +427,36 @@ function installArg(entry: Record<string, unknown>): unknown {
 /**
  * Check 10: plugin marketplace manifests. Display fields (`name`, server key,
  * `interface.displayName`) must equal the unscoped machine name; the install
- * arg must equal the full `package.json` name (the real `npx` target). Empty
- * descriptions ship blank marketplace cards. Each manifest is validated only
- * when present, so HTTP-only and non-plugin consumers are unaffected. The
- * caller gates the whole check on `packaging.pluginManifests`.
+ * arg must equal the full `package.json` name (the real `npx` target); the
+ * declared `version` must equal `package.json`'s, so a release cannot ship a
+ * manifest advertising an earlier one. Empty descriptions ship blank
+ * marketplace cards. Each manifest is validated only when present, so HTTP-only
+ * and non-plugin consumers are unaffected. The caller gates the whole check on
+ * `packaging.pluginManifests`.
+ *
+ * `.codex-plugin/mcp.json` is connection configuration and carries no version.
  */
 export function checkPluginManifests(
   inputs: PluginManifestInputs,
   unscopedName: string,
   fullName: string,
+  packageVersion?: string,
 ): string[] {
   const errors: string[] = [];
   const optOut =
     '(or set "packaging": { "pluginManifests": false } in devcheck.config.json to opt out)';
 
+  /** Version parity for one plugin manifest; skipped when package.json has none. */
+  const checkVersion = (file: string, manifest: Record<string, unknown>): void => {
+    if (!isNonEmptyString(packageVersion)) return;
+    if (manifest.version === packageVersion) return;
+    errors.push(
+      manifest.version === undefined
+        ? `${file} has no "version" — must declare the package.json version "${packageVersion}"`
+        : `${file} "version" is "${String(manifest.version)}" — must equal the package.json version "${packageVersion}"`,
+    );
+  };
+
   // ── .claude-plugin/plugin.json ──
   const claude = inputs.claudePlugin;
   if (isRecord(claude)) {
@@ -445,6 +464,7 @@ export function checkPluginManifests(
     if (!isNonEmptyString(claude.description)) {
       errors.push(`${f} "description" is empty — populate it ${optOut}`);
     }
+    checkVersion(f, claude);
     if (claude.name !== unscopedName) {
       errors.push(
         `${f} "name" is "${String(claude.name)}" — must equal the unscoped package name "${unscopedName}"`,
@@ -474,6 +494,7 @@ export function checkPluginManifests(
     if (!isNonEmptyString(codex.description)) {
       errors.push(`${f} "description" is empty — populate it ${optOut}`);
     }
+    checkVersion(f, codex);
     if (codex.name !== unscopedName) {
       errors.push(
         `${f} "name" is "${String(codex.name)}" — must equal the unscoped package name "${unscopedName}"`,
@@ -533,7 +554,7 @@ async function main(): Promise<void> {
   const warnings: string[] = [];
   const notes: string[] = [];
 
-  const pkg = tryReadJson<{ name?: string }>(resolve('package.json'));
+  const pkg = tryReadJson<{ name?: string; version?: string }>(resolve('package.json'));
   const unscopedName = pkg?.name?.split('/').pop();
 
   // ── Manifest-dependent checks (1–4 + manifest identity) ──
@@ -662,6 +683,7 @@ async function main(): Promise<void> {
           },
           unscopedName,
           pkg.name,
+          pkg.version,
         ),
       );
     } else {

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.21"
+  version: "2.22"
   audience: external
   type: reference
 ---
@@ -226,6 +226,37 @@ export const submitObservations = getServerConfig().enableWrites
 
 The wrapper preserves all original definition fields (handler, schemas, auth scopes, error contracts) — when re-enabled, the tool already conforms to every lint rule.
 
+#### Audit what still names the tool
+
+Gating a tool removes it from `tools/list`, but nothing rewrites the rest of the server. Every reference that survives points a client at a name it cannot call. Sweep for the tool's name across three surfaces and fix what the gate makes wrong:
+
+| Surface | What the gate requires |
+|:---|:---|
+| **Static prose** — server `instructions`, tool descriptions, field `.describe()` text | Do not describe a disabled tool as currently callable. |
+| **Recovery text** — `errors[].recovery`, `ctx.fail` hints, `ctx.enrich` notices, service summaries | Offer an available next step, or say the capability is unavailable in this deployment. |
+| **Structured suggestions** — `nextToolSuggestions`, or any `{ toolName, args }` entry a client executes | Emit a suggestion only when its target is enabled under the same configuration. |
+
+A suggestion is executable; prose is not. When no callable alternative exists, prose may still explain the limitation — but the executable entry goes:
+
+```typescript
+const { enableWrites } = getServerConfig();
+
+// The suggestion is emitted only under the config that registers its target.
+const nextToolSuggestions = enableWrites
+  ? [{ toolName: 'brapi_submit_observations', args: { studyDbId } }]
+  : [];
+
+return {
+  observations,
+  nextToolSuggestions,
+  ...(enableWrites
+    ? {}
+    : { notice: 'Submitting observations is turned off in this deployment.' }),
+};
+```
+
+The same audit applies to a tool's own `errors[].recovery`: a hint naming a tool that this deployment gates off sends the agent to a dead end at exactly the moment it is recovering from a failure.
+
 ## Schemas: what the framework stores vs. what clients see
 
 `tool()` and the handler factory do not hand your Zod schemas to the SDK verbatim. Two deliberate transforms sit in between.
@@ -796,6 +827,7 @@ return { items: hits };
 - [ ] If tool returns unbounded arrays: pagination with total count, or `spillover()` / DataCanvas for *analytical* working sets (an agent would SQL them — not a discovery/search surface). If any tool emits a `canvas_id`, a `dataframe_query` tool is registered in the same server — a token with no query tool is dead output
 - [ ] If tool returns one large *document* (not a row set) that can overflow context: `outlineOnOverflow()` returns a `full | outline` union so the agent re-calls with `sections: [...]` — not one-sided truncation
 - [ ] If tool is feature-gated: evaluated whether `disabledTool()` wrapper is appropriate (present in manifest but uncallable)
+- [ ] If a tool is gated off: swept the server for its name — no prose calls it available, no recovery hint routes to it, and every structured suggestion naming it is emitted only under the config that registers it
 - [ ] If the tool filters a bounded list locally (no upstream search): a distinct local param (`filter`/`nameContains`, not `query`), filters the full set (not one page), strict token match by default
 - [ ] Registered in the project's existing `createApp()` tool list (directly or via barrel)
 - [ ] Test file created via `add-test` skill, or handler tested directly with `createMockContext()`

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.8"
+  version: "1.9"
   audience: external
   type: reference
 ---
@@ -362,6 +362,7 @@ Important properties:
 - **`_meta.error` is NOT emitted.** Error code/data live on `structuredContent.error` instead. Don't read `_meta.error` in clients or tests — it doesn't exist.
 - **`data` propagation is restricted** to explicitly-thrown `McpError.data` and `ZodError.issues`. Auto-classified plain errors (`TypeError`, network errors, etc.) emit `code` + `message` only — no `data` — so internal classification context never leaks to clients.
 - **Recovery hint mirroring is automatic.** When the thrown `McpError` carries `data.recovery.hint`, the handler factory appends it to the `content[]` text so the markdown surface matches the JSON surface. Authors don't need to format the hint manually.
+- **Argument-schema rejection is a tool error with the same envelope.** An unknown root key, a wrong type, a missing required field, or a failed constraint returns `isError: true` with `structuredContent.error.code = -32602` (`InvalidParams`) and the readable `Invalid arguments for tool <name>: …` diagnostic in `content[]`. The handler never runs. Two neighbouring failures keep the protocol error path instead, arriving as a JSON-RPC error rather than a tool result: an unknown or disabled tool name, and a malformed request envelope.
 
 **Handler — throw freely, no try/catch:**
 

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.23"
+  version: "2.24"
   audience: external
   type: workflow
 ---
@@ -257,6 +257,8 @@ const wrapupInstructions = tool('git_wrapup_instructions', {
 
 Prior art: [`git_wrapup_instructions`](https://github.com/cyanheads/git-mcp-server) walks through staging, commit, and push with repo state inspected. If a server has recurring "how do I do X well given my state" questions, an instruction tool typically beats N topic-specific tools and duplicating guidance in tool descriptions.
 
+**Suggestions are scoped to what this deployment registers.** A `nextToolSuggestions` entry is an executable call, so it is only correct when its target is enabled under the same configuration — a tool wrapped in `disabledTool()` is absent from `tools/list`, and a suggestion naming it hands the agent a call that fails on dispatch. Build the array from the same config the registration reads, and when the target is off, drop the entry rather than the explanation: `guidance` can still say the capability is unavailable in this deployment and what to do instead. The audit and a worked example live under *Feature-flagged tools* in `add-tool/SKILL.md`.
+
 #### Reference tools
 
 **Applies when:** the domain speaks in opaque vocabulary — enum codes, classification systems, identifier formats, per-source coverage windows — that agents must supply as inputs elsewhere. Skip when inputs are self-evident (free text, ISO dates, well-known formats).
@@ -493,6 +495,8 @@ throw notFound(`Paper '${id}' not found on arXiv. Verify the ID format (e.g., '2
 
 **During design, settle the full contract for each tool** — reason, code, when-clause, *and the verbatim `recovery` string* — in the tool's section of the design doc; they become the literal `errors: [...]` entries during scaffolding. Hold every recovery string (and zero-hit notice, and resolver `guidance`) to the **no-dead-ends rule: it names the concrete next tool call**, with the reference tool as the most common routing target. Settled at design time these stay sharp; left to implementation they degrade into "check your input." Not every failure needs a contract entry; baseline infrastructure errors (5xx, timeouts, validation) are fine to let bubble.
 
+**A routing target must be callable in the deployment doing the routing.** A recovery string, notice, or `guidance` line that names a config-gated tool is a dead end wherever that gate is off — the agent is sent to a tool absent from `tools/list`, at the moment it is already recovering from a failure. Prefer routing to ungated tools (the reference tool is a good target precisely because nothing gates it). Where the target genuinely is gated, resolve the text from the same config that decides registration, and say the capability is unavailable in this deployment rather than naming a call that cannot be made. Structured follow-ups are stricter still — see *Instruction tools* above.
+
 #### Design table
 
 Summarize each tool:
@@ -701,6 +705,7 @@ Items without an `If …:` prefix apply to every design. Conditional items only
 - [ ] **If an upstream API has no native search but the relevant set is bounded:** MCP-side list filtering considered — a distinct local filter param (`filter`/`nameContains`, not `query`), filtering the full set, strict token match (fuzzy only when a caller needs typo tolerance)
 - [ ] **If the server has workflow tools:** call-flow documented (upstream sequence + mode arms) in design doc's Workflow Analysis
 - [ ] **If state-aware procedural guidance adds value:** instruction tool considered with `nextToolSuggestions` pre-filled from diagnostics
+- [ ] **If any tool is config-gated:** nothing routes to it while the gate is off — recovery strings, notices, and `guidance` name a callable target or state the capability is unavailable, and structured follow-ups naming it are emitted only under the config that registers it
 - [ ] **If workflow tools have destructive modes:** destructive arm gated on a `ctx.requestInput` confirmation read back from `ctx.inputs`, with `destructiveHint` annotation so clients that never fulfil the round still surface the risk
 - [ ] **If a parameter determines blast radius:** safe default set (e.g., `mode: 'preview'`, `dryRun: true`, `confirmCount` required)
 - [ ] **App tools default to no.** If one was proposed, verified there's a real human-in-the-loop in an MCP Apps-capable client justifying the iframe/CSP/`format()`-twin maintenance cost — otherwise dropped in favor of a standard tool