@hegemonart/get-design-done 1.19.6 → 1.20.0

package/scripts/lib/error-classifier.d.cts

@@ -0,0 +1,44 @@
+// scripts/lib/error-classifier.d.cts — types for error-classifier.cjs.
+
+/** Recovery-action categories. Values are stable strings — safe to log. */
+export type FailoverReasonValue =
+  | 'rate_limited'
+  | 'context_overflow'
+  | 'auth_error'
+  | 'network_transient'
+  | 'network_permanent'
+  | 'tool_not_found'
+  | 'validation'
+  | 'unknown';
+
+/** String-constant map of FailoverReason names to values. */
+export const FailoverReason: {
+  readonly RATE_LIMITED: 'rate_limited';
+  readonly CONTEXT_OVERFLOW: 'context_overflow';
+  readonly AUTH_ERROR: 'auth_error';
+  readonly NETWORK_TRANSIENT: 'network_transient';
+  readonly NETWORK_PERMANENT: 'network_permanent';
+  readonly TOOL_NOT_FOUND: 'tool_not_found';
+  readonly VALIDATION: 'validation';
+  readonly UNKNOWN: 'unknown';
+};
+
+/** Result of {@link classify}. */
+export interface ClassifiedError {
+  reason: FailoverReasonValue;
+  retryable: boolean;
+  suggestedAction: string;
+  raw: unknown;
+}
+
+/**
+ * Map a raw error value onto a stable recovery-action category.
+ * Tolerant of null/undefined/non-Error inputs.
+ */
+export function classify(err: unknown): ClassifiedError;
+
+/** Keyed suggested-action strings (read-only). */
+export const SUGGESTED_ACTIONS: Readonly<Record<FailoverReasonValue, string>>;
+
+/** Which reasons are considered safe to retry by policy. */
+export const RETRYABLE: Readonly<Record<FailoverReasonValue, boolean>>;

package/scripts/lib/event-stream/emitter.ts

@@ -0,0 +1,88 @@
+// scripts/lib/event-stream/emitter.ts — in-process pub-sub for Phase 20+
+// telemetry events (Plan 20-06, SDK-08).
+//
+// Thin wrapper around Node's built-in `EventEmitter`. Two additions over
+// the raw primitive:
+//
+//   1. `subscribe(type, handler)` returns an unsubscribe closure — the
+//      standard `on()` / `off()` dance is easy to forget, and our
+//      subscribers (hook consumers, Phase 22 transports) need tidy
+//      lifecycle management.
+//
+//   2. `subscribeAll(handler)` lets observability infra (dashboard,
+//      log transport) see every event without enumerating known types.
+//      We re-emit on a dedicated `'*'` channel so listeners on that
+//      channel observe every `emit()`.
+//
+// Replay semantics:
+//   The bus is live-only. Subscribing does NOT deliver historical
+//   events from `events.jsonl` — that's a Phase 22 transport concern.
+
+import { EventEmitter } from 'node:events';
+
+import type { BaseEvent } from './types.ts';
+
+/**
+ * Default max listeners raised above Node's 10-listener default. Mapper
+ * parallelism + multiple hook consumers + a dashboard transport can
+ * easily stack above 10; 50 is conservative headroom before Node warns.
+ */
+export const DEFAULT_MAX_LISTENERS = 50;
+
+/**
+ * Typed handler for a specific event subtype. `T extends BaseEvent`
+ * means callers can narrow via `subscribe<StateMutationEvent>(…)` and
+ * the handler sees the narrowed shape.
+ */
+export type EventHandler<T extends BaseEvent = BaseEvent> = (ev: T) => void;
+
+/** Unsubscribe closure returned from `subscribe` / `subscribeAll`. */
+export type Unsubscribe = () => void;
+
+/**
+ * In-process event bus. Extends `EventEmitter` so raw consumers can
+ * still call `on()` / `off()` if they need Node-native semantics, but
+ * prefer `subscribe` / `subscribeAll` for ergonomic cleanup.
+ */
+export class EventBus extends EventEmitter {
+  constructor() {
+    super();
+    this.setMaxListeners(DEFAULT_MAX_LISTENERS);
+  }
+
+  /**
+   * Subscribe to one specific event type. The handler fires for every
+   * subsequent `emit(type, ev)` call where `ev.type === type`. Returns
+   * a closure that detaches the listener on invocation.
+   *
+   * @example
+   * const off = bus.subscribe<StateMutationEvent>('state.mutation', (ev) => {
+   *   console.log(ev.payload.tool);
+   * });
+   * // …later
+   * off();
+   */
+  subscribe<T extends BaseEvent = BaseEvent>(
+    type: T['type'],
+    handler: EventHandler<T>,
+  ): Unsubscribe {
+    const listener = handler as unknown as (...args: unknown[]) => void;
+    this.on(type, listener);
+    return () => {
+      this.off(type, listener);
+    };
+  }
+
+  /**
+   * Subscribe to *every* event regardless of type. Listeners registered
+   * here fire on the special `'*'` channel, which `appendEvent()`
+   * re-emits to on every event. Returns an unsubscribe closure.
+   */
+  subscribeAll(handler: EventHandler<BaseEvent>): Unsubscribe {
+    const listener = handler as unknown as (...args: unknown[]) => void;
+    this.on('*', listener);
+    return () => {
+      this.off('*', listener);
+    };
+  }
+}

package/scripts/lib/event-stream/index.ts

@@ -0,0 +1,154 @@
+// scripts/lib/event-stream/index.ts — public API for the Phase 20+
+// telemetry stream (Plan 20-06, SDK-08).
+//
+// Consumers import ONLY from this file. The internal parts
+// (`./types.ts`, `./writer.ts`, `./emitter.ts`) are implementation
+// detail; changing them without updating this export surface is a
+// breaking change for downstream plans (20-05 MCP handlers, 20-13 hooks).
+//
+// Surface:
+//   * appendEvent(ev)          — persist + broadcast one event
+//   * getWriter(opts?)         — lazy singleton EventWriter
+//   * getBus()                 — lazy singleton EventBus
+//   * reset()                  — clear module-level singletons (tests)
+//   * types                    — BaseEvent, KnownEvent, and every pre-
+//                                registered subtype (StateMutationEvent,
+//                                StateTransitionEvent, …).
+
+import { hostname } from 'node:os';
+
+import { EventBus } from './emitter.ts';
+import type { Unsubscribe, EventHandler } from './emitter.ts';
+import { EventWriter } from './writer.ts';
+import type { WriterOptions } from './writer.ts';
+import type { BaseEvent, EventMeta } from './types.ts';
+
+export type {
+  BaseEvent,
+  EventMeta,
+  KnownEvent,
+  StateMutationEvent,
+  StateTransitionEvent,
+  StageEnteredEvent,
+  StageExitedEvent,
+  HookFiredEvent,
+  ErrorEvent,
+} from './types.ts';
+export { EventBus } from './emitter.ts';
+export type { EventHandler, Unsubscribe } from './emitter.ts';
+export { EventWriter, DEFAULT_EVENTS_PATH, DEFAULT_MAX_LINE_BYTES } from './writer.ts';
+export type { WriterOptions } from './writer.ts';
+
+/**
+ * Lazily-constructed module-level singletons. `getWriter()` honors the
+ * first `opts` it receives; subsequent calls with different options are
+ * ignored. Tests that need to vary options across runs should call
+ * {@link reset} between runs.
+ */
+let defaultWriter: EventWriter | null = null;
+let defaultBus: EventBus | null = null;
+/**
+ * Cached host name. `os.hostname()` is cheap but not free (syscall on
+ * some platforms) and we stamp it onto every event; compute once.
+ */
+let cachedHost: string | null = null;
+
+/**
+ * Return the module-level default writer, constructing it on first
+ * call. Passing `opts` on subsequent calls is a no-op (the first
+ * caller wins); that matches the "single shared file per process"
+ * intent.
+ */
+export function getWriter(opts?: WriterOptions): EventWriter {
+  if (defaultWriter === null) {
+    defaultWriter = new EventWriter(opts ?? {});
+  }
+  return defaultWriter;
+}
+
+/** Return the module-level default bus, constructing it on first call. */
+export function getBus(): EventBus {
+  if (defaultBus === null) {
+    defaultBus = new EventBus();
+  }
+  return defaultBus;
+}
+
+/**
+ * Persist `ev` to the on-disk JSONL stream AND broadcast it to the
+ * in-process bus. This is the normal emission path for every Phase 20+
+ * event producer.
+ *
+ * Ordering:
+ *   1. Stamp `_meta` (pid/host/source) if the caller didn't supply it.
+ *   2. Persist via `getWriter().append(ev)` — sync, never throws.
+ *   3. Broadcast via `getBus().emit(ev.type, ev)` AND `emit('*', ev)`
+ *      so typed subscribers and `subscribeAll` observers both see it.
+ *
+ * Bus emission can still throw if a subscriber handler throws; we
+ * intentionally surface that rather than silently swallowing, since a
+ * failing handler is a programming bug, not an expected runtime
+ * condition. Plan 20-13's hooks wrap their handler bodies defensively
+ * for this reason.
+ */
+export function appendEvent(ev: BaseEvent): void {
+  // Stamp writer-injected metadata if absent. We don't clone the full
+  // event — callers typically build it fresh per emission — but we do
+  // need to ensure `_meta` is present by the time we persist.
+  if (ev._meta === undefined) {
+    if (cachedHost === null) {
+      try {
+        cachedHost = hostname();
+      } catch {
+        cachedHost = 'unknown';
+      }
+    }
+    const meta: EventMeta = {
+      pid: process.pid,
+      host: cachedHost,
+      source: 'event-stream',
+    };
+    ev._meta = meta;
+  }
+
+  // Persist first. Bus emission is synchronous; if a subscriber throws
+  // after we've persisted, the durable record is already safe.
+  getWriter().append(ev);
+
+  const bus = getBus();
+  bus.emit(ev.type, ev);
+  bus.emit('*', ev);
+}
+
+/**
+ * Reset module-level singletons. Intended for tests that want a fresh
+ * writer (e.g. pointed at a new temp directory) or a fresh bus (e.g.
+ * to assert isolation between test cases).
+ *
+ * Safe to call from production code but the intended caller is a test.
+ * `appendEvent()` will lazily reconstruct both singletons on the next
+ * emission.
+ */
+export function reset(): void {
+  if (defaultBus !== null) {
+    defaultBus.removeAllListeners();
+  }
+  defaultWriter = null;
+  defaultBus = null;
+}
+
+// Re-export `subscribe`/`subscribeAll` convenience: some callers only
+// need to subscribe, not emit, and `getBus().subscribe(…)` reads fine
+// but the shorter form keeps consumer code terse.
+/** Convenience: subscribe to one event type on the default bus. */
+export function subscribe<T extends BaseEvent = BaseEvent>(
+  type: T['type'],
+  handler: EventHandler<T>,
+): Unsubscribe {
+  return getBus().subscribe<T>(type, handler);
+}
+
+/** Convenience: subscribe to every event on the default bus. */
+export function subscribeAll(handler: EventHandler<BaseEvent>): Unsubscribe {
+  return getBus().subscribeAll(handler);
+}

package/scripts/lib/event-stream/types.ts

@@ -0,0 +1,127 @@
+// scripts/lib/event-stream/types.ts — typed event envelope + pre-registered
+// event shapes, per Plan 20-06 (SDK-08).
+//
+// The event stream is the Phase 20+ observability primitive that every
+// downstream consumer (Plan 20-05 MCP tool handlers, Plan 20-13 hooks)
+// builds on. A single append-only JSONL file at
+// `.design/telemetry/events.jsonl` holds the persisted form; an in-process
+// `EventEmitter` bus (see `./emitter.ts`) broadcasts the same events
+// live to subscribers within the same Node process.
+//
+// Envelope invariants (also encoded in `reference/schemas/events.schema.json`):
+//   * `type`       — required, string, free-form. Pre-registered subtypes
+//                    below are merely the seeded set; unknown types are
+//                    allowed (validation is structural, not a closed enum).
+//   * `timestamp`  — required, ISO-8601 (`date-time` format).
+//   * `sessionId`  — required, stable per GDD pipeline run.
+//   * `stage`      — optional, narrow `Stage` union.
+//   * `cycle`      — optional, free-form string identifier.
+//   * `payload`    — required, opaque object bag.
+//   * `_meta`      — optional, writer-injected `{ pid, host, source }`.
+//   * `_truncated` — optional, writer-set when a payload exceeds
+//                    `maxLineBytes` and has been replaced by a placeholder.
+//
+// Plan 20-04 owns the error taxonomy that feeds `ErrorEvent.payload`:
+// `{ code, message, kind }` mirrors `toToolError(err)` output.
+
+import type { Stage } from '../gdd-state/types.ts';
+
+/** Writer-injected metadata. Never populated by callers. */
+export interface EventMeta {
+  pid: number;
+  host: string;
+  /**
+   * Free-form identifier for the module that produced the event.
+   * Defaults to `"event-stream"` when `appendEvent()` fills the field
+   * itself; callers that wrap `appendEvent()` in a module-specific helper
+   * should overwrite this before calling.
+   */
+  source: string;
+}
+
+/**
+ * Canonical event envelope. All persisted and in-process events share
+ * this shape. Concrete subtypes narrow `type` + `payload` but add no
+ * additional top-level fields.
+ */
+export interface BaseEvent {
+  type: string;
+  timestamp: string;
+  sessionId: string;
+  stage?: Stage;
+  cycle?: string;
+  payload: Record<string, unknown>;
+  _meta?: EventMeta;
+  /**
+   * Set to `true` by the writer when the serialized event exceeded
+   * `maxLineBytes` and the payload has been replaced with a placeholder.
+   * Never set by callers.
+   */
+  _truncated?: boolean;
+}
+
+/**
+ * Emitted by Plan 20-05's MCP tool handlers after a successful
+ * `mutate()` / `transition()` call. `diff` is an opaque structural
+ * description of the change; consumers (Phase 22 dashboard) render it.
+ */
+export type StateMutationEvent = BaseEvent & {
+  type: 'state.mutation';
+  payload: { tool: string; diff: unknown };
+};
+
+/**
+ * Emitted by Plan 20-05 wrapping `transition()`. `pass=false` means
+ * the gate blocked the advance; `blockers` carries the same list the
+ * transition's `TransitionGateFailed` would expose.
+ */
+export type StateTransitionEvent = BaseEvent & {
+  type: 'state.transition';
+  payload: { from: Stage; to: Stage; blockers: string[]; pass: boolean };
+};
+
+/** Lifecycle hook emitted when a pipeline stage begins execution. */
+export type StageEnteredEvent = BaseEvent & {
+  type: 'stage.entered';
+  payload: { stage: Stage };
+};
+
+/**
+ * Lifecycle hook emitted when a pipeline stage finishes. `duration_ms`
+ * measures wall-clock time from `stage.entered`. `outcome` mirrors the
+ * stage's terminal state.
+ */
+export type StageExitedEvent = BaseEvent & {
+  type: 'stage.exited';
+  payload: { stage: Stage; duration_ms: number; outcome: 'pass' | 'fail' | 'halted' };
+};
+
+/** Emitted by Plan 20-13 hook consumers when a hook dispatches a decision. */
+export type HookFiredEvent = BaseEvent & {
+  type: 'hook.fired';
+  payload: { hook: string; decision: string };
+};
+
+/**
+ * Emitted whenever a `GDDError` is surfaced to the user or returned from
+ * a tool handler. `kind` mirrors `classify(err).kind`; `code` +
+ * `message` mirror the error's `code` + `message`.
+ */
+export type ErrorEvent = BaseEvent & {
+  type: 'error';
+  payload: { code: string; message: string; kind: string };
+};
+
+/**
+ * Union of all pre-registered event types. Not a closed enum at the
+ * envelope level — callers can emit unknown types — but downstream
+ * consumers use this to drive typed `switch` statements with exhaustive
+ * checks for the subset they care about.
+ */
+export type KnownEvent =
+  | StateMutationEvent
+  | StateTransitionEvent
+  | StageEnteredEvent
+  | StageExitedEvent
+  | HookFiredEvent
+  | ErrorEvent;

package/scripts/lib/event-stream/writer.ts

@@ -0,0 +1,154 @@
+// scripts/lib/event-stream/writer.ts — append-only JSONL writer for the
+// Phase 20+ telemetry stream (Plan 20-06, SDK-08).
+//
+// Design:
+//   * One file per .design/: `.design/telemetry/events.jsonl`, sibling to
+//     the existing `costs.jsonl` (which this plan does NOT modify).
+//   * Each `append()` is one call to `fs.appendFileSync(…, { flag: 'a' })`.
+//     On POSIX the O_APPEND semantic guarantees that a single write()
+//     under `PIPE_BUF` (4096 bytes) is atomic with respect to other
+//     appenders — multiple processes can append concurrently without
+//     interleaving or corruption. On Windows, `FILE_APPEND_DATA` via the
+//     Node runtime supplies the same guarantee. Typical event lines are
+//     well under 1KB; oversized events are truncated (see below) so we
+//     never approach the 4KB atomicity ceiling even on stricter POSIX
+//     implementations.
+//   * `append()` NEVER throws to the caller. On I/O failure we record
+//     the error (so observability tooling can surface it) and write a
+//     single diagnostic line to stderr.
+//   * Oversized payloads (> `maxLineBytes`, default 64KB) are truncated
+//     rather than dropped: we keep envelope metadata and replace
+//     `payload` with `{ _truncated_placeholder: true }`, then re-serialize
+//     and stamp `_truncated: true` on the line.
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve, isAbsolute, join } from 'node:path';
+
+import type { BaseEvent } from './types.ts';
+
+/** Default relative path for the persisted event stream. */
+export const DEFAULT_EVENTS_PATH = '.design/telemetry/events.jsonl';
+
+/** Default max line size in bytes. JSONL lines that exceed this are truncated. */
+export const DEFAULT_MAX_LINE_BYTES = 64 * 1024; // 64 KiB
+
+/** Constructor options for {@link EventWriter}. */
+export interface WriterOptions {
+  /**
+   * Target file path for persisted events. Resolved to absolute at
+   * construction. Relative paths are resolved against `process.cwd()`.
+   *
+   * Default: `.design/telemetry/events.jsonl`.
+   */
+  path?: string;
+  /**
+   * Maximum serialized line size in bytes (JSON.stringify length + `\n`).
+   * Events exceeding this cap are truncated — the envelope is preserved
+   * and the payload is replaced with a `_truncated_placeholder` marker.
+   *
+   * Default: 65536 (64 KiB).
+   */
+  maxLineBytes?: number;
+}
+
+/**
+ * Append-only JSONL writer. One instance per file path is sufficient;
+ * the module-level cache in `./index.ts` shares a single default writer
+ * across the process so directory creation only happens once.
+ */
+export class EventWriter {
+  /** Resolved absolute target path. */
+  readonly path: string;
+  /** Maximum line size in bytes (see {@link WriterOptions.maxLineBytes}). */
+  readonly maxLineBytes: number;
+  /** Number of failed append attempts since construction. */
+  writeErrors: number = 0;
+  /** The most recent write error, or `null` if none has occurred. */
+  lastError: Error | null = null;
+
+  /** `true` once we've ensured the target directory exists. */
+  private directoryEnsured: boolean = false;
+
+  constructor(opts: WriterOptions = {}) {
+    const rawPath = opts.path ?? DEFAULT_EVENTS_PATH;
+    this.path = isAbsolute(rawPath) ? rawPath : resolve(process.cwd(), rawPath);
+    this.maxLineBytes = opts.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
+  }
+
+  /**
+   * Append one event to the target file.
+   *
+   * Contract:
+   *   * SYNC — returns when the write has been accepted by the kernel.
+   *   * NEVER throws — I/O errors increment {@link writeErrors} and update
+   *     {@link lastError}; a diagnostic is written to stderr and
+   *     execution continues.
+   *   * Truncates oversized payloads rather than dropping the event.
+   */
+  append(ev: BaseEvent): void {
+    try {
+      const line = this.serialize(ev);
+      this.ensureDirectory();
+      appendFileSync(this.path, line, { flag: 'a' });
+    } catch (err) {
+      this.writeErrors += 1;
+      this.lastError = err instanceof Error ? err : new Error(String(err));
+      // One-line diagnostic; intentionally minimal so callers aren't
+      // spammed under sustained failure.
+      try {
+        process.stderr.write(
+          `[event-stream] write failed: ${this.lastError.message}\n`,
+        );
+      } catch {
+        // If stderr itself is broken we have no recourse; swallow.
+      }
+    }
+  }
+
+  /**
+   * Produce the on-disk JSONL representation of an event, truncating
+   * oversized payloads so the line fits within {@link maxLineBytes}.
+   *
+   * Exposed on the instance for unit-testability; callers should use
+   * {@link append}.
+   */
+  serialize(ev: BaseEvent): string {
+    const raw = JSON.stringify(ev) + '\n';
+    if (Buffer.byteLength(raw, 'utf8') <= this.maxLineBytes) {
+      return raw;
+    }
+
+    // Truncate: keep envelope fields, drop payload content.
+    const truncated: BaseEvent = {
+      type: ev.type,
+      timestamp: ev.timestamp,
+      sessionId: ev.sessionId,
+      payload: { _truncated_placeholder: true },
+      _truncated: true,
+    };
+    if (ev.stage !== undefined) truncated.stage = ev.stage;
+    if (ev.cycle !== undefined) truncated.cycle = ev.cycle;
+    if (ev._meta !== undefined) truncated._meta = ev._meta;
+    return JSON.stringify(truncated) + '\n';
+  }
+
+  /**
+   * Ensure the target directory exists. Memoized so we only pay the
+   * filesystem stat cost once per writer lifetime.
+   */
+  private ensureDirectory(): void {
+    if (this.directoryEnsured) return;
+    mkdirSync(dirname(this.path), { recursive: true });
+    this.directoryEnsured = true;
+  }
+}
+
+/**
+ * Convenience helper: resolve a relative events-path against a supplied
+ * base directory (typically the project root) rather than `process.cwd()`.
+ * Intended for tests that scaffold a temp workspace and don't want to
+ * chdir.
+ */
+export function eventsPathFor(baseDir: string): string {
+  return join(baseDir, DEFAULT_EVENTS_PATH);
+}

package/scripts/lib/gdd-errors/classification.ts

@@ -0,0 +1,124 @@
+// scripts/lib/gdd-errors/classification.ts — error classification + MCP helpers.
+//
+// Two exports:
+//   * classify(err)      — normalize any thrown value into an
+//                          ErrorClassification descriptor
+//   * toToolError(err)   — wrap into the shape MCP tool handlers return
+//                          inside data.error
+//
+// These helpers are the bridge between the taxonomy (index.ts) and the
+// MCP tool layer (plan 20-05 wires them into all 11 tool handlers).
+
+import {
+  GDDError,
+  ValidationError,
+  StateConflictError,
+  OperationFailedError,
+} from './index.ts';
+
+/**
+ * The four-valued classification of any error value. `kind === 'unknown'`
+ * means the thrown value was not a GDDError — either a plain Error or a
+ * non-Error value (string, number, etc.).
+ *
+ * Flag semantics:
+ *   shouldThrow=true   — caller should propagate (or rethrow) this error;
+ *                        it represents an invariant violation or bad input
+ *   shouldThrow=false  — caller should embed this in data.error and
+ *                        return normally (expected branching failure)
+ *   retryable=true     — upstream may retry after a backoff (only
+ *                        StateConflictError; e.g. lockfile contention)
+ */
+export interface ErrorClassification {
+  kind: 'validation' | 'state_conflict' | 'operation_failed' | 'unknown';
+  shouldThrow: boolean;
+  retryable: boolean;
+  code: string;
+  message: string;
+}
+
+/**
+ * Classify any value thrown at us. Robust to non-Error throws (strings,
+ * numbers, plain objects) — returns `kind: 'unknown'` with a sensible
+ * message rather than blowing up.
+ */
+export function classify(err: unknown): ErrorClassification {
+  if (err instanceof ValidationError) {
+    return {
+      kind: 'validation',
+      shouldThrow: true,
+      retryable: false,
+      code: err.code,
+      message: err.message,
+    };
+  }
+  if (err instanceof StateConflictError) {
+    return {
+      kind: 'state_conflict',
+      shouldThrow: true,
+      retryable: true,
+      code: err.code,
+      message: err.message,
+    };
+  }
+  if (err instanceof OperationFailedError) {
+    return {
+      kind: 'operation_failed',
+      shouldThrow: false,
+      retryable: false,
+      code: err.code,
+      message: err.message,
+    };
+  }
+  if (err instanceof Error) {
+    return {
+      kind: 'unknown',
+      shouldThrow: true,
+      retryable: false,
+      code: 'UNKNOWN',
+      message: err.message,
+    };
+  }
+  return {
+    kind: 'unknown',
+    shouldThrow: true,
+    retryable: false,
+    code: 'UNKNOWN',
+    message: String(err),
+  };
+}
+
+/**
+ * Shape MCP tool handlers return inside `data.error`. The `context`
+ * key is only present when the error is a GDDError instance — plain
+ * errors don't carry structured context, and we intentionally don't
+ * fabricate one (the `code` + `message` pair is sufficient).
+ */
+export interface ToolErrorPayload {
+  error: {
+    code: string;
+    message: string;
+    kind: ErrorClassification['kind'];
+    context?: Readonly<Record<string, unknown>>;
+  };
+}
+
+/**
+ * Convert any error into the shape MCP tool handlers return in
+ * data.error. Plan 20-05 wires this into the 11 tool handlers; Plan
+ * 20-06 emits it as an `error` event on the telemetry stream.
+ */
+export function toToolError(err: unknown): ToolErrorPayload {
+  const c = classify(err);
+  const out: ToolErrorPayload = {
+    error: {
+      code: c.code,
+      message: c.message,
+      kind: c.kind,
+    },
+  };
+  if (err instanceof GDDError) {
+    out.error.context = err.context;
+  }
+  return out;
+}