@wix/pathgrade 0.29.0

package/dist/affected/select.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Core selection pipeline for affected-eval-selection.
+ *
+ * Given a set of discovered eval files and a set of changed files,
+ * computes which evals should run. See `docs/003-affected-eval-selection.md`
+ * §"Design Overview" and §"Precedence" for the authoritative specification.
+ *
+ * Precedence (when multiple mechanisms apply):
+ *   1. `affected.global` match short-circuits and selects every discovered
+ *      eval. (Wiring lands in Issue 8.)
+ *   2. `alwaysRun: true` unconditionally unions the eval into selection.
+ *   3. `deps` (full override) replaces the auto-detected skill root.
+ *   4. `extraDeps` is unioned with `deps` or the skill root.
+ *   5. Auto-detected skill root (`<skillRoot>/**`) is the default.
+ *   6. `onMissing` (no anchor + no meta) → fail-closed select with warning.
+ */
+import type { SelectionResult } from './types.js';
+export interface SelectAffectedInput {
+    evalFiles: string[];
+    changedFiles: string[];
+    repoRoot: string;
+    baseRef: string;
+    /**
+     * Repo-level "rerun everything" triggers from `pathgrade()` plugin
+     * options (`affected.global`). Any match short-circuits selection and
+     * every discovered eval is selected with reason `global-match`.
+     */
+    global?: string[];
+}
+export declare function selectAffected(input: SelectAffectedInput): SelectionResult;

package/dist/affected/select.js

@@ -0,0 +1,101 @@
+/**
+ * Core selection pipeline for affected-eval-selection.
+ *
+ * Given a set of discovered eval files and a set of changed files,
+ * computes which evals should run. See `docs/003-affected-eval-selection.md`
+ * §"Design Overview" and §"Precedence" for the authoritative specification.
+ *
+ * Precedence (when multiple mechanisms apply):
+ *   1. `affected.global` match short-circuits and selects every discovered
+ *      eval. (Wiring lands in Issue 8.)
+ *   2. `alwaysRun: true` unconditionally unions the eval into selection.
+ *   3. `deps` (full override) replaces the auto-detected skill root.
+ *   4. `extraDeps` is unioned with `deps` or the skill root.
+ *   5. Auto-detected skill root (`<skillRoot>/**`) is the default.
+ *   6. `onMissing` (no anchor + no meta) → fail-closed select with warning.
+ */
+import * as path from 'path';
+import { findSkillRoot } from './anchor.js';
+import { parsePathgradeMeta } from './meta.js';
+import { intersect } from './glob.js';
+export function selectAffected(input) {
+    const { evalFiles, changedFiles, repoRoot, baseRef, global } = input;
+    const selected = [];
+    const skipped = [];
+    const warnings = [];
+    // Precedence #1: global match short-circuits everything.
+    if (global && global.length > 0) {
+        const hit = intersect(global, changedFiles);
+        if (hit.matched) {
+            for (const evalFile of evalFiles) {
+                selected.push({ file: evalFile, reason: 'global-match' });
+            }
+            selected.sort((a, b) => a.file.localeCompare(b.file));
+            return {
+                baseRef,
+                changedFiles: [...changedFiles],
+                globalMatch: hit.matchedGlob,
+                selected,
+                skipped,
+                warnings,
+            };
+        }
+    }
+    for (const evalFile of evalFiles) {
+        const absEval = path.resolve(repoRoot, evalFile);
+        const skillRoot = findSkillRoot(absEval, repoRoot);
+        const meta = parsePathgradeMeta(absEval);
+        // Precedence #2: alwaysRun wins over dep matching.
+        if (meta?.alwaysRun === true) {
+            selected.push({ file: evalFile, reason: 'always-run' });
+            continue;
+        }
+        // Precedence #6: fail-closed when we have no signal at all.
+        if (!skillRoot && !meta) {
+            selected.push({ file: evalFile, reason: 'on-missing-fail-closed' });
+            warnings.push(`${evalFile}: no SKILL.md anchor and no __pathgradeMeta — selecting fail-closed`);
+            continue;
+        }
+        const depGlobs = resolveDepGlobs(skillRoot, meta);
+        if (depGlobs.length === 0) {
+            // Meta present but declares no deps (e.g., `{}`). Treat as
+            // fail-closed — the user left deps ambiguous.
+            selected.push({ file: evalFile, reason: 'on-missing-fail-closed' });
+            warnings.push(`${evalFile}: __pathgradeMeta declares no deps and no SKILL.md anchor — selecting fail-closed`);
+            continue;
+        }
+        const hit = intersect(depGlobs, changedFiles);
+        if (hit.matched) {
+            selected.push({
+                file: evalFile,
+                reason: 'deps-match',
+                matchedGlob: hit.matchedGlob,
+            });
+        }
+        else {
+            skipped.push({ file: evalFile, reason: 'no-matching-deps' });
+        }
+    }
+    selected.sort((a, b) => a.file.localeCompare(b.file));
+    skipped.sort((a, b) => a.file.localeCompare(b.file));
+    return {
+        baseRef,
+        changedFiles: [...changedFiles],
+        selected,
+        skipped,
+        warnings,
+    };
+}
+function resolveDepGlobs(skillRoot, meta) {
+    const globs = [];
+    if (meta?.deps && meta.deps.length > 0) {
+        globs.push(...meta.deps);
+    }
+    else if (skillRoot) {
+        globs.push(`${skillRoot}/**`);
+    }
+    if (meta?.extraDeps && meta.extraDeps.length > 0) {
+        globs.push(...meta.extraDeps);
+    }
+    return globs;
+}

package/dist/affected/sidecar.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Selection sidecar — plumbing between CLI and reporter.
+ *
+ * `pathgrade run --changed` computes selection in the CLI, before vitest
+ * spawns. `PathgradeReporter` runs inside the vitest process and can't
+ * see that decision directly. The sidecar bridges them: the CLI writes a
+ * small JSON file at `.pathgrade/selection.json`; the reporter reads it
+ * (if present) at run-end and merges it into `results.json`.
+ *
+ * Shape mirrors Issue 10's wire format but flattens `selected` to file
+ * paths and summarizes `changed_files` as a count — downstream consumers
+ * (PR comments, dashboards) want the decision, not the per-trial reason
+ * breakdown.
+ */
+import type { SelectionResult } from './types.js';
+import type { PathgradeSelectionReport } from '../types.js';
+export declare const SIDECAR_FILENAME = "selection.json";
+export declare function getSidecarPath(cwd: string): string;
+/**
+ * Flatten a `SelectionResult` into the compact shape written to
+ * `.pathgrade/selection.json` (and merged into `results.json` as
+ * `PathgradeReport.selection`).
+ */
+export declare function toSelectionReport(result: SelectionResult): PathgradeSelectionReport;
+export declare function writeSidecar(cwd: string, result: SelectionResult): Promise<void>;
+/**
+ * Read the sidecar if present. Returns `null` when missing, and `null`
+ * with an optional warning when the file exists but is malformed — the
+ * reporter is expected to tolerate corruption rather than break the run.
+ */
+export declare function readSidecar(cwd: string, onWarning?: (msg: string) => void): Promise<PathgradeSelectionReport | null>;
+export declare function clearSidecar(cwd: string): Promise<void>;

package/dist/affected/sidecar.js

@@ -0,0 +1,86 @@
+/**
+ * Selection sidecar — plumbing between CLI and reporter.
+ *
+ * `pathgrade run --changed` computes selection in the CLI, before vitest
+ * spawns. `PathgradeReporter` runs inside the vitest process and can't
+ * see that decision directly. The sidecar bridges them: the CLI writes a
+ * small JSON file at `.pathgrade/selection.json`; the reporter reads it
+ * (if present) at run-end and merges it into `results.json`.
+ *
+ * Shape mirrors Issue 10's wire format but flattens `selected` to file
+ * paths and summarizes `changed_files` as a count — downstream consumers
+ * (PR comments, dashboards) want the decision, not the per-trial reason
+ * breakdown.
+ */
+import * as path from 'path';
+import fs from 'fs-extra';
+import { getPathgradeDir } from '../reporters/results-path.js';
+export const SIDECAR_FILENAME = 'selection.json';
+export function getSidecarPath(cwd) {
+    return path.join(getPathgradeDir(cwd), SIDECAR_FILENAME);
+}
+/**
+ * Flatten a `SelectionResult` into the compact shape written to
+ * `.pathgrade/selection.json` (and merged into `results.json` as
+ * `PathgradeReport.selection`).
+ */
+export function toSelectionReport(result) {
+    const report = {
+        base_ref: result.baseRef,
+        changed_files_count: result.changedFiles.length,
+        selected: result.selected.map(s => s.file).sort(),
+        skipped: [...result.skipped].sort((a, b) => a.file.localeCompare(b.file)).map(s => ({
+            file: s.file,
+            reason: s.reason,
+        })),
+    };
+    if (result.globalMatch !== undefined)
+        report.global_match = result.globalMatch;
+    return report;
+}
+export async function writeSidecar(cwd, result) {
+    const sidecarPath = getSidecarPath(cwd);
+    await fs.ensureDir(path.dirname(sidecarPath));
+    await fs.writeJSON(sidecarPath, toSelectionReport(result), { spaces: 2 });
+}
+/**
+ * Read the sidecar if present. Returns `null` when missing, and `null`
+ * with an optional warning when the file exists but is malformed — the
+ * reporter is expected to tolerate corruption rather than break the run.
+ */
+export async function readSidecar(cwd, onWarning) {
+    const sidecarPath = getSidecarPath(cwd);
+    if (!(await fs.pathExists(sidecarPath)))
+        return null;
+    try {
+        const raw = await fs.readJSON(sidecarPath);
+        if (!isSelectionReport(raw)) {
+            onWarning?.(`${sidecarPath}: malformed sidecar (shape mismatch), ignoring.`);
+            return null;
+        }
+        return raw;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        onWarning?.(`${sidecarPath}: malformed sidecar (${msg}), ignoring.`);
+        return null;
+    }
+}
+export async function clearSidecar(cwd) {
+    const sidecarPath = getSidecarPath(cwd);
+    try {
+        await fs.remove(sidecarPath);
+    }
+    catch {
+        // Best-effort clear — a missing file is the expected case.
+    }
+}
+function isSelectionReport(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.base_ref === 'string' &&
+        typeof v.changed_files_count === 'number' &&
+        Array.isArray(v.selected) &&
+        Array.isArray(v.skipped));
+}

package/dist/affected/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared types for the affected-eval-selection pipeline.
+ *
+ * This file is the single source of truth for the `SelectionResult` shape
+ * and `SelectionReason` enum. Extended across Issues 5–11; do not duplicate.
+ */
+export type SelectionReason = 'deps-match' | 'always-run' | 'global-match' | 'on-missing-fail-closed';
+export interface SelectionEntry {
+    file: string;
+    reason: SelectionReason;
+    /** Glob that matched a changed file (populated for `deps-match` / `global-match`). */
+    matchedGlob?: string;
+}
+export interface SelectionSkipped {
+    file: string;
+    reason: 'no-matching-deps';
+}
+export interface SelectionResult {
+    /** `"<ref>@<sha>"`, or `"explicit"` for `--changed-files` inputs. */
+    baseRef: string;
+    changedFiles: string[];
+    /** Glob from `affected.global` that fired short-circuit, if any. */
+    globalMatch?: string;
+    selected: SelectionEntry[];
+    skipped: SelectionSkipped[];
+    warnings: string[];
+}
+/**
+ * Public SDK type — exported from `@wix/pathgrade` so evals can annotate
+ * their `__pathgradeMeta` export with a typed shape.
+ *
+ * `onMissing` is intentionally NOT a user-writable field: it names
+ * pathgrade's *runtime behavior* when an eval has neither a SKILL.md
+ * anchor nor an explicit meta declaration.
+ */
+export interface PathgradeMeta {
+    /** Full-override dep globs (repo-relative). Replaces auto-detected SKILL.md anchor. */
+    deps?: string[];
+    /** Additional dep globs unioned with the auto-detected SKILL.md anchor. */
+    extraDeps?: string[];
+    /** When true, unconditionally include this eval in every `pathgrade run --changed`. */
+    alwaysRun?: boolean;
+}

package/dist/affected/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared types for the affected-eval-selection pipeline.
+ *
+ * This file is the single source of truth for the `SelectionResult` shape
+ * and `SelectionReason` enum. Extended across Issues 5–11; do not duplicate.
+ */
+export {};

package/dist/agents/claude/ask-user-answer-store.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-turn answer store shared by the ask-user-bridge (writer) and the
+ * SDK-message-projector (reader).
+ *
+ * The bridge resolves an `AskUserQuestion` ask-bus batch synchronously inside
+ * its `canUseTool` callback and writes the resulting `answers` map plus the
+ * answer source (`'reaction' | 'fallback' | 'declined'`) keyed by the SDK's
+ * `toolUseID`. After the turn's `for await` of the typed-message stream
+ * completes, the projector consults the store while building the `ToolEvent`
+ * for each `AskUserQuestion` tool-use block — the structured input the SDK
+ * already gave us, plus the answer values and source the bridge attached.
+ *
+ * This is the only piece of cross-module state the bridge owns. It exists
+ * because the SDK's `canUseTool` callback runs ahead of the assistant message
+ * the projector ultimately sees — both sides need a join key.
+ */
+import type { AskAnswerSource } from '../../sdk/ask-bus/types.js';
+export interface AskUserAnswerEntry {
+    /** The SDK-shape `answers` map (question text → answer string). */
+    readonly answers: Record<string, string>;
+    /** Source tag from the `AskAnswer` resolution — what the projector stamps. */
+    readonly source: AskAnswerSource;
+}
+export interface AskUserAnswerStore {
+    record(toolUseId: string, entry: AskUserAnswerEntry): void;
+    get(toolUseId: string | undefined): AskUserAnswerEntry | undefined;
+}
+export declare function createAskUserAnswerStore(): AskUserAnswerStore;

package/dist/agents/claude/ask-user-answer-store.js

@@ -0,0 +1,29 @@
+/**
+ * Per-turn answer store shared by the ask-user-bridge (writer) and the
+ * SDK-message-projector (reader).
+ *
+ * The bridge resolves an `AskUserQuestion` ask-bus batch synchronously inside
+ * its `canUseTool` callback and writes the resulting `answers` map plus the
+ * answer source (`'reaction' | 'fallback' | 'declined'`) keyed by the SDK's
+ * `toolUseID`. After the turn's `for await` of the typed-message stream
+ * completes, the projector consults the store while building the `ToolEvent`
+ * for each `AskUserQuestion` tool-use block — the structured input the SDK
+ * already gave us, plus the answer values and source the bridge attached.
+ *
+ * This is the only piece of cross-module state the bridge owns. It exists
+ * because the SDK's `canUseTool` callback runs ahead of the assistant message
+ * the projector ultimately sees — both sides need a join key.
+ */
+export function createAskUserAnswerStore() {
+    const entries = new Map();
+    return {
+        record(toolUseId, entry) {
+            entries.set(toolUseId, entry);
+        },
+        get(toolUseId) {
+            if (toolUseId === undefined)
+                return undefined;
+            return entries.get(toolUseId);
+        },
+    };
+}

package/dist/agents/claude/ask-user-bridge.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Ask-user bridge — `canUseTool` callback expressed as a pure factory over
+ * `(askBus, getTurnNumber, answerStore)`.
+ *
+ *   - For every tool name that is NOT `AskUserQuestion`, the bridge returns
+ *     `{ behavior: 'allow', updatedInput: input }`. That matches the
+ *     `permissionMode: 'default'` choice — every tool decision still routes
+ *     through this callback, but only `AskUserQuestion` actually blocks on
+ *     the ask-bus.
+ *   - For `AskUserQuestion`, the bridge constructs a live `AskBatch` from
+ *     the SDK's already-typed `AskUserQuestionInput`, emits it onto the bus,
+ *     awaits resolution, and returns the SDK's documented `answers` shape
+ *     (`{ [questionText]: string }`, multi-select comma-joined per the SDK's
+ *     own field comment) on `updatedInput`.
+ *   - **Declined resolution → SDK deny.** When every `AskAnswer` carries
+ *     `source: 'declined'` (the `'decline'` fallback path, plus the
+ *     declined-shape any `'error'` unmatched signal produces), the bridge
+ *     surfaces the SDK's `{ behavior: 'deny', message: 'User declined to
+ *     answer' }` instead of `'allow'` with empty answer strings.
+ *   - **Bus rejection → SDK deny + `lastError()`.** A bus timeout (or any
+ *     other rejection) becomes `{ behavior: 'deny', message: err.message }`
+ *     to the SDK *and* is captured on `lastError()` so the driver can
+ *     re-throw after the SDK stream ends. The conversation runner's catch
+ *     reports `completionReason: 'error'` with the same message.
+ */
+import type { CanUseTool } from '@anthropic-ai/claude-agent-sdk';
+import type { AskBus } from '../../sdk/ask-bus/types.js';
+import type { AskUserAnswerStore } from './ask-user-answer-store.js';
+export interface AskUserBridgeDeps {
+    /** Per-conversation bus from `AgentSessionOptions.askBus`. */
+    askBus: AskBus;
+    /** Returns the current turn number — driver increments before runTurn. */
+    getTurnNumber: () => number;
+    /** Per-turn answer store written here, read by the projector. */
+    answerStore: AskUserAnswerStore;
+}
+/**
+ * The bridge is a callable `CanUseTool` with two side accessors used by the
+ * driver to bubble bus rejections out of the turn loop:
+ *
+ *   - `lastError()` returns the most recent ask-bus rejection captured by
+ *     this bridge instance, or null. The driver checks it after the SDK
+ *     stream ends; a non-null value gets thrown so `runConversation` reports
+ *     `completionReason: 'error'` with the bus error message.
+ *   - `clearLastError()` resets the field — called at the top of each turn
+ *     so a stale error from a prior turn never triggers a spurious throw.
+ *
+ * Encoded as attached function properties so existing call sites
+ * (`const canUseTool = createAskUserBridge(...); canUseTool(...)`) keep
+ * working unchanged.
+ */
+export type AskUserBridge = CanUseTool & {
+    lastError(): Error | null;
+    clearLastError(): void;
+};
+export declare function createAskUserBridge(deps: AskUserBridgeDeps): AskUserBridge;

package/dist/agents/claude/ask-user-bridge.js

@@ -0,0 +1,162 @@
+/**
+ * Ask-user bridge — `canUseTool` callback expressed as a pure factory over
+ * `(askBus, getTurnNumber, answerStore)`.
+ *
+ *   - For every tool name that is NOT `AskUserQuestion`, the bridge returns
+ *     `{ behavior: 'allow', updatedInput: input }`. That matches the
+ *     `permissionMode: 'default'` choice — every tool decision still routes
+ *     through this callback, but only `AskUserQuestion` actually blocks on
+ *     the ask-bus.
+ *   - For `AskUserQuestion`, the bridge constructs a live `AskBatch` from
+ *     the SDK's already-typed `AskUserQuestionInput`, emits it onto the bus,
+ *     awaits resolution, and returns the SDK's documented `answers` shape
+ *     (`{ [questionText]: string }`, multi-select comma-joined per the SDK's
+ *     own field comment) on `updatedInput`.
+ *   - **Declined resolution → SDK deny.** When every `AskAnswer` carries
+ *     `source: 'declined'` (the `'decline'` fallback path, plus the
+ *     declined-shape any `'error'` unmatched signal produces), the bridge
+ *     surfaces the SDK's `{ behavior: 'deny', message: 'User declined to
+ *     answer' }` instead of `'allow'` with empty answer strings.
+ *   - **Bus rejection → SDK deny + `lastError()`.** A bus timeout (or any
+ *     other rejection) becomes `{ behavior: 'deny', message: err.message }`
+ *     to the SDK *and* is captured on `lastError()` so the driver can
+ *     re-throw after the SDK stream ends. The conversation runner's catch
+ *     reports `completionReason: 'error'` with the same message.
+ */
+export function createAskUserBridge(deps) {
+    const { askBus, getTurnNumber, answerStore } = deps;
+    let lastError = null;
+    const canUseTool = async (toolName, input, options) => {
+        if (toolName !== 'AskUserQuestion') {
+            return { behavior: 'allow', updatedInput: input };
+        }
+        const turnNumber = getTurnNumber();
+        const batch = buildBatchFromInput(input, turnNumber, options.toolUseID);
+        const handle = askBus.emit(batch);
+        let resolution;
+        try {
+            resolution = await handle.resolution;
+        }
+        catch (err) {
+            // Ask-bus timeouts and other rejections deny the SDK with
+            // the underlying error message AND surface on `lastError()` so
+            // the driver re-throws after the turn ends. The conversation
+            // runner's catch reports `completionReason: 'error'` with the
+            // same message — no half-state where the SDK keeps running on
+            // a tool refusal that the runner never noticed.
+            lastError = err instanceof Error ? err : new Error(String(err));
+            return { behavior: 'deny', message: lastError.message };
+        }
+        // Live batches always settle (either to a resolution or a rejection).
+        // A null resolution means a 'post-hoc' batch — impossible here since
+        // we just emitted lifecycle: 'live'. Throw if the bus contract is
+        // ever weakened upstream.
+        if (resolution === null) {
+            throw new Error(`ask-user bridge: live batch ${batch.batchId} resolved to null`);
+        }
+        const answers = buildSdkAnswers(batch.questions, resolution.answers);
+        const source = pickAnswerSource(resolution.answers);
+        answerStore.record(options.toolUseID, { answers, source });
+        // A fully-declined resolution (every answer `source: 'declined'`)
+        // surfaces as the SDK's documented `deny` shape. Returning an `allow`
+        // with empty `answers` strings would make Claude believe the user
+        // typed empty answers — strictly worse than telling the SDK the
+        // tool call was refused. Mixed-disposition resolutions (e.g. one
+        // declined among reactions) still allow with whatever `answers`
+        // the bus yielded, since at least one question carries a real value.
+        if (resolution.answers.length > 0
+            && resolution.answers.every((a) => a.source === 'declined')) {
+            return { behavior: 'deny', message: 'User declined to answer' };
+        }
+        const allow = {
+            behavior: 'allow',
+            updatedInput: { ...input, answers },
+        };
+        return allow;
+    };
+    const bridge = canUseTool;
+    bridge.lastError = () => lastError;
+    bridge.clearLastError = () => { lastError = null; };
+    return bridge;
+}
+/**
+ * Build an `AskBatch` (lifecycle: 'live') from the SDK's `AskUserQuestionInput`.
+ *
+ * The SDK input is already typed and validated (1-4 questions, 2-4 options
+ * each), so this is a structural translation rather than a parse. The batch
+ * id reuses the SDK's `toolUseID` so the projector can join the resolution
+ * back onto the matching `tool_use` block in the assistant message.
+ */
+function buildBatchFromInput(input, turnNumber, toolUseId) {
+    const rawQuestions = Array.isArray(input.questions) ? input.questions : [];
+    const questions = [];
+    rawQuestions.forEach((raw, index) => {
+        const text = typeof raw.question === 'string' ? raw.question : '';
+        const header = typeof raw.header === 'string' && raw.header.length > 0
+            ? raw.header
+            : undefined;
+        const options = readOptions(raw.options);
+        questions.push({
+            id: `q-${index}`,
+            ...(header ? { header } : {}),
+            question: text,
+            options,
+            isOther: false,
+            isSecret: false,
+        });
+    });
+    return {
+        batchId: toolUseId,
+        turnNumber,
+        source: 'claude',
+        lifecycle: 'live',
+        sourceTool: 'AskUserQuestion',
+        toolUseId,
+        questions,
+    };
+}
+function readOptions(raw) {
+    if (!Array.isArray(raw))
+        return null;
+    return raw.map((opt) => {
+        const label = typeof opt.label === 'string' ? opt.label : '';
+        const description = typeof opt.description === 'string' && opt.description.length > 0
+            ? opt.description
+            : undefined;
+        return description ? { label, description } : { label };
+    });
+}
+/**
+ * Translate the bus's `AskAnswer[]` into the SDK's documented `answers` shape
+ * — `{ [questionText]: string }` per `sdk-tools.d.ts:2702`. Multi-select is
+ * joined with a single comma; the SDK's own field comment specifies that
+ * "multi-select answers are comma-separated" without prescribing whitespace,
+ * so we follow whatever the bundled binary expects rather than imposing a
+ * stricter "comma-space" assumption.
+ */
+function buildSdkAnswers(questions, answers) {
+    const byId = new Map();
+    for (const a of answers)
+        byId.set(a.questionId, a);
+    const out = {};
+    for (const q of questions) {
+        const a = byId.get(q.id);
+        if (!a)
+            continue;
+        out[q.question] = a.values.join(',');
+    }
+    return out;
+}
+/**
+ * Pick a single source tag for the whole batch. In the happy path every
+ * question is answered by the same disposition; if mixed, the most-specific
+ * source wins (`reaction` > `fallback` > `declined`). The projector consumes
+ * a single tag per tool event.
+ */
+function pickAnswerSource(answers) {
+    if (answers.some((a) => a.source === 'reaction'))
+        return 'reaction';
+    if (answers.some((a) => a.source === 'fallback'))
+        return 'fallback';
+    return 'declined';
+}

package/dist/agents/claude/sdk-message-projector.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SDK message projector — typed `SDKMessage[]` → `AgentTurnResult`.
+ *
+ * Replaces the legacy NDJSON parser (`extractClaudeStreamJsonEvents`). Pure
+ * function: no I/O, no ask-bus, no session state. The Claude SDK driver
+ * buffers each turn's `SDKMessage` stream (`for await`) and hands the array
+ * here; the projector returns the public `AgentTurnResult` plus the
+ * `session_id` the orchestrator threads into the next turn's
+ * `Options.resume`.
+ *
+ * Boundary with the live ask-user bridge: for an `AskUserQuestion`
+ * tool-use block the projector emits a `ToolEvent` whose `arguments` shape
+ * is the structured `AskUserQuestionInput` (questions / headers / options /
+ * multiSelect) plus `answerSource: 'unknown'`. The bridge attaches the
+ * answer values and the `'reaction' | 'fallback' | 'declined'` source tag
+ * onto the same envelope; the projector itself never mints them.
+ */
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { AgentTurnResult } from '../../types.js';
+import type { AskUserAnswerStore } from './ask-user-answer-store.js';
+export interface ProjectTurnInput {
+    /** Buffered typed-message stream from one `query()` call. */
+    messages: SDKMessage[];
+    /** Forwarded onto `ToolEvent.turnNumber`; optional for projector unit use. */
+    turnNumber?: number;
+    /** First user message of the turn — used for slash-command skill detection. */
+    firstMessage?: string;
+    /**
+     * Optional per-turn answer store written by the ask-user-bridge.
+     * When present, the projector merges `answers` + `answerSource` from the
+     * store onto each `AskUserQuestion` ToolEvent envelope using the SDK's
+     * `toolUseID` (the tool-use block `id`) as the join key. When absent or
+     * empty for a given `toolUseID`, the projector keeps the boundary stamp
+     * `answerSource: 'unknown'` it stamped before the bridge existed.
+     */
+    answerStore?: AskUserAnswerStore;
+}
+export interface ProjectedTurn {
+    result: AgentTurnResult;
+    /** `session_id` reported on init/result; the orchestrator uses this for `resume`. */
+    sessionId?: string;
+}
+export declare function projectSdkMessages(input: ProjectTurnInput): ProjectedTurn;