@arnilo/prism-coding-agent 0.0.10 → 0.0.12

package/CHANGELOG.md

@@ -1,4 +1,25 @@
 # Changelog
+## [Unreleased]
+
+## [0.0.12] - 2026-07-22
+
+### Changed
+
+- Released with exact 0.0.12 graph.
+
+
+## [0.0.11] - 2026-07-22
+
+### Docs
+
+- Documented ask_user_decision multi/free-text/suspend glue + `runCodingGoalVerify` in `docs/coding-agent-tools.md` / README.
+
+### Added
+
+- `runCodingGoalVerify` / `createCodingGoalVerifyWorkflow`: thin goal→verify composition over plan Markdown, named checks, workflow suspend/approve, and bounded PR handoff (peer `@arnilo/prism-workflows`). No Goal table / second runtime.
+- Opt-in `createAskUserDecisionTool({ ask })`: model proposes 2+ options with exactly 3 pros + 3 cons each; host `ask` returns `selectedId` / `selectedIds` / `customText`. Supports `selectionMode: "single" | "multiple"` and `allowCustom` (custom XOR selection; default/hard custom bytes match question caps). Not in `createCodingTools` / `createAllTools` / `createReadOnlyTools`.
+- Durable ask-user helpers: `suspendAskUserDecision`, `createAskUserDecisionResumeValidator`, `validateAskUserDecisionResume`, `validateAskUserDecisionAgentResume` (workflow-first; agent path reuses same validator without new `AgentRunInterruption` kinds).
+
 ## [0.0.10] - 2026-07-21
 
 ### Changed

package/README.md

@@ -1,6 +1,6 @@
 # @arnilo/prism-coding-agent
 
-Optional first-party coding tools package for [Prism](https://www.npmjs.com/package/@arnilo/prism). Provides host shell/filesystem/repository tools — `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search` — plus opt-in structured Git/check tools via `createGitTools()` and durable plan/checkpoint helpers for workflow composition — as Prism `ToolDefinition` objects. **Inert until a host imports it and registers the tools into a `ToolRegistry`.**
+Optional first-party coding tools package for [Prism](https://www.npmjs.com/package/@arnilo/prism). Provides host shell/filesystem/repository tools — `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search` — plus opt-in structured Git/check tools via `createGitTools()`, opt-in `createAskUserDecisionTool({ ask })`, and durable plan/checkpoint helpers for workflow composition — as Prism `ToolDefinition` objects. **Inert until a host imports it and registers the tools into a `ToolRegistry`.** No tool is auto-registered; hosts pick factories (or filter aggregator output) and may mix in their own `ToolDefinition`s.
 
 Behavior is a behavioral port of the pi coding agent's `bash`/`read`/`write`/`edit` tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies). List/search/Git are native Prism tools.
 
@@ -12,7 +12,7 @@ Behavior is a behavioral port of the pi coding agent's `bash`/`read`/`write`/`ed
 npm install @arnilo/prism-coding-agent
 ```
 
-`@arnilo/prism` is a peer dependency.
+`@arnilo/prism` is a peer dependency. `runCodingGoalVerify` also peers `@arnilo/prism-workflows`.
 
 ## Usage
 
@@ -38,7 +38,7 @@ Shared `ToolsOptions.executionPolicy` applies to every tool returned by full, al
 Individual tools with options:
 
 ```ts
-import { createShellTool, createWriteTool } from "@arnilo/prism-coding-agent";
+import { createShellTool, createWriteTool, createAskUserDecisionTool } from "@arnilo/prism-coding-agent";
 
 const shell = createShellTool(process.cwd(), {
   shellPath: "/bin/bash",        // force bash; default: SHELL env → /bin/bash → sh
@@ -54,6 +54,14 @@ const remoteWrite = createWriteTool(process.cwd(), {
     mkdir: async (dir) => { /* mkdir -p remotely */ },
   },
 });
+
+// Opt-in: not in createCodingTools(). Host owns the UI.
+const askUser = createAskUserDecisionTool({
+  ask: async ({ question, options }) => {
+    const selectedId = await host.promptChoice(question, options);
+    return { selectedId };
+  },
+});
 ```
 
 ## Tools
@@ -67,6 +75,7 @@ const remoteWrite = createWriteTool(process.cwd(), {
 | `repo_list` | `{ path?, includeHidden?, maxDepth?, maxResults?, offset? }` | Deterministic relative entries; skips hidden/excluded basenames; does not follow symlinks; paginates with `nextOffset`. |
 | `repo_search` | `{ query, path?, mode?, caseSensitive?, includeHidden?, context?, maxMatches? }` | Literal (default) or bounded regex matches with context; skips binary/excluded paths; finite scan/match/time caps. |
 | `git_*` / `coding_check` | via `createGitTools(cwd, { commitIdentity, checks? })` | Opt-in structured Git status/diff/branch/worktree/apply/commit/PR-handoff and named checks. Not in `createCodingTools()`. |
+| `ask_user_decision` | via `createAskUserDecisionTool({ ask })` | Opt-in user choice: question + options (3 pros/3 cons); `selectionMode` single\|multiple; `allowCustom` for XOR free-text; host `ask` returns `selectedId` / `selectedIds` / `customText`. Durable: `suspendAskUserDecision` + resume validators. Not in default aggregators. |
 
 ### pi name mapping
 
@@ -78,9 +87,9 @@ const remoteWrite = createWriteTool(process.cwd(), {
 
 ## Exports
 
-Factories: `createShellTool`, `createReadTool`, `createWriteTool`, `createEditTool`, `createRepoListTool`, `createRepoSearchTool`, `createCodingTools`, `createReadOnlyTools`, `createAllTools`, `createGitTools`, `createCodingCheckTool`, `createLocalBashOperations`, `createLocalRepositoryOperations`, `createGitOperations`.
+Factories: `createShellTool`, `createReadTool`, `createWriteTool`, `createEditTool`, `createRepoListTool`, `createRepoSearchTool`, `createCodingTools`, `createReadOnlyTools`, `createAllTools`, `createGitTools`, `createCodingCheckTool`, `createAskUserDecisionTool`, `createLocalBashOperations`, `createLocalRepositoryOperations`, `createGitOperations`.
 
-Helpers: `detectSupportedImageMimeType`, `detectSupportedImageMimeTypeFromFile`, `getShellConfig`, `killProcessTree`, `waitForChildProcess`, `withFileMutationQueue`, `resolveRepositoryLimits`, `writeCodingPlanFile`, `readCodingPlanFile`, `buildCodingCheckpointMetadata`, `validateCodingCheckpointMetadata`, `assertCodingResumeAllowed`, `fingerprintJson`. Default/hard coding, repository, Git, and plan/checkpoint limit constants are exported for host configuration.
+Helpers: `detectSupportedImageMimeType`, `detectSupportedImageMimeTypeFromFile`, `getShellConfig`, `killProcessTree`, `waitForChildProcess`, `withFileMutationQueue`, `resolveRepositoryLimits`, `writeCodingPlanFile`, `readCodingPlanFile`, `buildCodingCheckpointMetadata`, `validateCodingCheckpointMetadata`, `assertCodingResumeAllowed`, `fingerprintJson`, `runCodingGoalVerify`, `createCodingGoalVerifyWorkflow`, `suspendAskUserDecision`, `createAskUserDecisionResumeValidator`, `validateAskUserDecisionResume`, `validateAskUserDecisionAgentResume`. Default/hard coding, repository, Git, and plan/checkpoint limit constants are exported for host configuration.
 
 Option/operation types: `ToolsOptions`, `ShellToolOptions`/`BashOperations`, `ReadToolOptions`/`ReadOperations`/`ReadTextOptions`/`ReadTextResult`, `WriteToolOptions`/`WriteOperations`, `EditToolOptions`/`EditOperations`/`EditToolDetails`.
 

package/dist/ask-user-decision.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Opt-in `ask_user_decision` tool: model proposes choices with pros/cons;
+ * host-injected `ask` blocks until the user picks one or more option ids.
+ *
+ * Durable path (opt-in): `suspendAskUserDecision` / `validateAskUserDecisionResume`
+ * compose `@arnilo/prism-workflows` suspend/resume — no Goal DB, no second store.
+ * Blocking `ask()` remains the default. Agent durable interruption kinds are
+ * unchanged; hosts reuse the same resume validator against host-held request data.
+ *
+ * Not included in `createCodingTools` / `createAllTools` / `createReadOnlyTools`.
+ */
+import type { ExecutionPolicy, JsonObject, ToolDefinition } from "@arnilo/prism";
+import { type WorkflowResumeValidator, type WorkflowSuspension } from "@arnilo/prism-workflows";
+export declare const ASK_USER_DECISION_TOOL_NAME: "ask_user_decision";
+export declare const ASK_USER_DECISION_SUSPEND_REASON: "ask_user_decision";
+/** Exactly three rationale bullets per side. */
+export declare const ASK_USER_DECISION_RATIONALE_COUNT: 3;
+export declare const DEFAULT_MAX_ASK_USER_DECISION_OPTIONS = 6;
+export declare const HARD_MAX_ASK_USER_DECISION_OPTIONS = 16;
+export declare const DEFAULT_MAX_ASK_USER_DECISION_QUESTION_BYTES = 2048;
+export declare const HARD_MAX_ASK_USER_DECISION_QUESTION_BYTES = 8192;
+export declare const DEFAULT_MAX_ASK_USER_DECISION_LABEL_BYTES = 512;
+export declare const HARD_MAX_ASK_USER_DECISION_LABEL_BYTES = 2048;
+export declare const DEFAULT_MAX_ASK_USER_DECISION_BULLET_BYTES = 512;
+export declare const HARD_MAX_ASK_USER_DECISION_BULLET_BYTES = 2048;
+/** Same ceiling as question text — free-text answers stay short. */
+export declare const DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES = 2048;
+export declare const HARD_MAX_ASK_USER_DECISION_CUSTOM_BYTES = 8192;
+export type AskUserDecisionSelectionMode = "single" | "multiple";
+export interface AskUserDecisionOption {
+    readonly id: string;
+    readonly label: string;
+    readonly pros: readonly [string, string, string];
+    readonly cons: readonly [string, string, string];
+}
+export interface AskUserDecisionRequest {
+    readonly question: string;
+    readonly options: readonly AskUserDecisionOption[];
+    readonly selectionMode: AskUserDecisionSelectionMode;
+    readonly allowCustom: boolean;
+    readonly toolCallId: string;
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Host answer shapes. Custom text is XOR with selection (v1): never both.
+ * `allowCustom` must be true for `{ customText }`.
+ */
+export type AskUserDecisionAnswer = {
+    readonly selectedId: string;
+    readonly selectedIds?: never;
+    readonly customText?: never;
+} | {
+    readonly selectedIds: readonly string[];
+    readonly selectedId?: never;
+    readonly customText?: never;
+} | {
+    readonly selectedId: string;
+    readonly selectedIds: readonly string[];
+    readonly customText?: never;
+} | {
+    readonly customText: string;
+    readonly selectedId?: never;
+    readonly selectedIds?: never;
+};
+export type ResolvedAskUserDecisionAnswer = {
+    readonly kind: "selection";
+    readonly selectedId: string;
+    readonly selectedIds: readonly string[];
+} | {
+    readonly kind: "custom";
+    readonly customText: string;
+};
+export type AskUserDecisionHandler = (request: AskUserDecisionRequest) => Promise<AskUserDecisionAnswer>;
+export interface AskUserDecisionToolOptions {
+    /** Required host UI/callback — tool fails closed without it. */
+    readonly ask: AskUserDecisionHandler;
+    readonly executionPolicy?: ExecutionPolicy;
+    readonly maxOptions?: number;
+    readonly maxQuestionBytes?: number;
+    readonly maxLabelBytes?: number;
+    readonly maxBulletBytes?: number;
+    readonly maxCustomTextBytes?: number;
+}
+export interface ResolvedAskUserDecisionLimits {
+    readonly maxOptions: number;
+    readonly maxQuestionBytes: number;
+    readonly maxLabelBytes: number;
+    readonly maxBulletBytes: number;
+    readonly maxCustomTextBytes: number;
+}
+export declare function resolveAskUserDecisionLimits(options?: Pick<AskUserDecisionToolOptions, "maxOptions" | "maxQuestionBytes" | "maxLabelBytes" | "maxBulletBytes" | "maxCustomTextBytes">): ResolvedAskUserDecisionLimits;
+/** Normalize host answer against mode + allowCustom. Exported for tests. */
+export declare function resolveAskUserDecisionAnswer(answer: AskUserDecisionAnswer | null | undefined, selectionMode: AskUserDecisionSelectionMode, options: readonly AskUserDecisionOption[], gates: {
+    readonly allowCustom: boolean;
+    readonly maxCustomTextBytes: number;
+}): ResolvedAskUserDecisionAnswer;
+/** Parse + validate model args into a bounded decision request. Exported for tests. */
+export declare function parseAskUserDecisionArgs(args: Record<string, unknown>, limits: ResolvedAskUserDecisionLimits): {
+    question: string;
+    options: AskUserDecisionOption[];
+    selectionMode: AskUserDecisionSelectionMode;
+    allowCustom: boolean;
+};
+/**
+ * Create the opt-in `ask_user_decision` tool.
+ * Host must supply `ask`; factory throws if missing.
+ */
+export declare function createAskUserDecisionTool(options: AskUserDecisionToolOptions): ToolDefinition;
+/** Durable decision payload for workflow suspension `data` (no AbortSignal / secrets). */
+export interface AskUserDecisionSuspendData {
+    readonly question: string;
+    readonly options: readonly AskUserDecisionOption[];
+    readonly selectionMode: AskUserDecisionSelectionMode;
+    readonly allowCustom: boolean;
+    readonly toolCallId?: string;
+    readonly sessionId?: string;
+    readonly runId?: string;
+}
+export interface SuspendAskUserDecisionOptions {
+    readonly reason?: string;
+    readonly maxCustomTextBytes?: number;
+}
+/** JSON Schema describing resume `input` (= AskUserDecisionAnswer). */
+export declare function askUserDecisionResumeSchema(request: Pick<AskUserDecisionSuspendData, "selectionMode" | "allowCustom" | "options">): JsonObject;
+export declare function toAskUserDecisionSuspendData(request: {
+    readonly question: string;
+    readonly options: readonly AskUserDecisionOption[];
+    readonly selectionMode: AskUserDecisionSelectionMode;
+    readonly allowCustom: boolean;
+    readonly toolCallId?: string;
+    readonly sessionId?: string;
+    readonly runId?: string;
+}): AskUserDecisionSuspendData;
+/**
+ * Return from a workflow node to pause for a user decision (opt-in durable path).
+ * Host resumes via `resumeWorkflow` + `createAskUserDecisionResumeValidator` / `validateAskUserDecisionResume`.
+ */
+export declare function suspendAskUserDecision(request: AskUserDecisionSuspendData | Pick<AskUserDecisionRequest, "question" | "options" | "selectionMode" | "allowCustom" | "toolCallId" | "sessionId" | "runId">, options?: SuspendAskUserDecisionOptions): WorkflowSuspension<AskUserDecisionAnswer>;
+/**
+ * Validate resume input against the original decision request.
+ * Shared by workflow `validateResume` and host-held agent resume adapters.
+ */
+export declare function validateAskUserDecisionResume(request: AskUserDecisionSuspendData, value: unknown, limits?: Pick<ResolvedAskUserDecisionLimits, "maxCustomTextBytes">): ResolvedAskUserDecisionAnswer;
+/**
+ * Workflow `validateResume` adapter. Reads durable request from `suspension.data`
+ * (written by `suspendAskUserDecision`). Deny paths skip answer validation.
+ */
+export declare function createAskUserDecisionResumeValidator(limits?: Pick<ResolvedAskUserDecisionLimits, "maxCustomTextBytes">): WorkflowResumeValidator;
+/**
+ * Thin agent-path adapter: same validation as workflow resume, for hosts that
+ * persist `AskUserDecisionSuspendData` outside `AgentRunInterruption` (core kinds
+ * unchanged in 0.0.12). Call after operator supplies an answer.
+ */
+export declare function validateAskUserDecisionAgentResume(input: {
+    readonly request: AskUserDecisionSuspendData;
+    readonly answer: unknown;
+    readonly maxCustomTextBytes?: number;
+}): ResolvedAskUserDecisionAnswer;

package/dist/ask-user-decision.js

@@ -0,0 +1,471 @@
+import { suspend, } from "@arnilo/prism-workflows";
+import { enforceExecutionPolicy } from "./execution-policy.js";
+import { validateCodingLimit } from "./limits.js";
+export const ASK_USER_DECISION_TOOL_NAME = "ask_user_decision";
+export const ASK_USER_DECISION_SUSPEND_REASON = "ask_user_decision";
+/** Exactly three rationale bullets per side. */
+export const ASK_USER_DECISION_RATIONALE_COUNT = 3;
+export const DEFAULT_MAX_ASK_USER_DECISION_OPTIONS = 6;
+export const HARD_MAX_ASK_USER_DECISION_OPTIONS = 16;
+export const DEFAULT_MAX_ASK_USER_DECISION_QUESTION_BYTES = 2_048;
+export const HARD_MAX_ASK_USER_DECISION_QUESTION_BYTES = 8_192;
+export const DEFAULT_MAX_ASK_USER_DECISION_LABEL_BYTES = 512;
+export const HARD_MAX_ASK_USER_DECISION_LABEL_BYTES = 2_048;
+export const DEFAULT_MAX_ASK_USER_DECISION_BULLET_BYTES = 512;
+export const HARD_MAX_ASK_USER_DECISION_BULLET_BYTES = 2_048;
+/** Same ceiling as question text — free-text answers stay short. */
+export const DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES = DEFAULT_MAX_ASK_USER_DECISION_QUESTION_BYTES;
+export const HARD_MAX_ASK_USER_DECISION_CUSTOM_BYTES = HARD_MAX_ASK_USER_DECISION_QUESTION_BYTES;
+export function resolveAskUserDecisionLimits(options) {
+    return {
+        maxOptions: validateCodingLimit("maxOptions", options?.maxOptions ?? DEFAULT_MAX_ASK_USER_DECISION_OPTIONS, HARD_MAX_ASK_USER_DECISION_OPTIONS),
+        maxQuestionBytes: validateCodingLimit("maxQuestionBytes", options?.maxQuestionBytes ?? DEFAULT_MAX_ASK_USER_DECISION_QUESTION_BYTES, HARD_MAX_ASK_USER_DECISION_QUESTION_BYTES),
+        maxLabelBytes: validateCodingLimit("maxLabelBytes", options?.maxLabelBytes ?? DEFAULT_MAX_ASK_USER_DECISION_LABEL_BYTES, HARD_MAX_ASK_USER_DECISION_LABEL_BYTES),
+        maxBulletBytes: validateCodingLimit("maxBulletBytes", options?.maxBulletBytes ?? DEFAULT_MAX_ASK_USER_DECISION_BULLET_BYTES, HARD_MAX_ASK_USER_DECISION_BULLET_BYTES),
+        maxCustomTextBytes: validateCodingLimit("maxCustomTextBytes", options?.maxCustomTextBytes ?? DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES, HARD_MAX_ASK_USER_DECISION_CUSTOM_BYTES),
+    };
+}
+function errorResult(toolCallId, message) {
+    return {
+        toolCallId,
+        name: ASK_USER_DECISION_TOOL_NAME,
+        content: [{ type: "text", text: message }],
+        error: { message },
+    };
+}
+function assertByteLimit(label, text, maxBytes) {
+    const bytes = Buffer.byteLength(text, "utf8");
+    if (bytes < 1 || bytes > maxBytes) {
+        throw new Error(`${label} must be 1..${maxBytes} UTF-8 bytes`);
+    }
+    if (/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/.test(text)) {
+        throw new Error(`${label} contains control characters`);
+    }
+}
+function requireThreeBullets(value, label, maxBytes) {
+    if (!Array.isArray(value) || value.length !== ASK_USER_DECISION_RATIONALE_COUNT) {
+        throw new Error(`${label} must be exactly ${ASK_USER_DECISION_RATIONALE_COUNT} strings`);
+    }
+    const out = [];
+    for (let i = 0; i < ASK_USER_DECISION_RATIONALE_COUNT; i++) {
+        const item = value[i];
+        if (typeof item !== "string") {
+            throw new Error(`${label}[${i}] must be a string`);
+        }
+        const trimmed = item.trim();
+        assertByteLimit(`${label}[${i}]`, trimmed, maxBytes);
+        out.push(trimmed);
+    }
+    return out;
+}
+function parseSelectionMode(value) {
+    if (value === undefined || value === null)
+        return "single";
+    if (value === "single" || value === "multiple")
+        return value;
+    throw new Error('selectionMode must be "single" or "multiple"');
+}
+function hasSelectionFields(answer) {
+    if (!answer)
+        return false;
+    if (typeof answer.selectedId === "string" && answer.selectedId.trim() !== "")
+        return true;
+    return Array.isArray(answer.selectedIds) && answer.selectedIds.length > 0;
+}
+/** Normalize host answer against mode + allowCustom. Exported for tests. */
+export function resolveAskUserDecisionAnswer(answer, selectionMode, options, gates) {
+    const customRaw = answer && typeof answer.customText === "string" ? answer.customText.trim() : "";
+    const hasCustom = customRaw.length > 0;
+    const hasSelection = hasSelectionFields(answer);
+    if (hasCustom && hasSelection) {
+        throw new Error("customText is mutually exclusive with selectedId/selectedIds");
+    }
+    if (hasCustom) {
+        if (!gates.allowCustom)
+            throw new Error("customText rejected (allowCustom=false)");
+        assertByteLimit("customText", customRaw, gates.maxCustomTextBytes);
+        return { kind: "custom", customText: customRaw };
+    }
+    const byId = new Map(options.map((o) => [o.id, o]));
+    const rawIds = [];
+    if (answer && Array.isArray(answer.selectedIds)) {
+        for (const id of answer.selectedIds) {
+            if (typeof id !== "string")
+                throw new Error("selectedIds entries must be strings");
+            rawIds.push(id.trim());
+        }
+    }
+    if (answer && typeof answer.selectedId === "string") {
+        const id = answer.selectedId.trim();
+        if (rawIds.length === 0)
+            rawIds.push(id);
+        else if (!(rawIds.length === 1 && rawIds[0] === id)) {
+            throw new Error("selectedId and selectedIds disagree");
+        }
+    }
+    if (rawIds.length === 0) {
+        throw new Error(gates.allowCustom
+            ? "ask() must return selectedId/selectedIds or customText"
+            : selectionMode === "multiple"
+                ? "ask() must return non-empty selectedIds"
+                : "ask() must return selectedId");
+    }
+    const seen = new Set();
+    const selectedIds = [];
+    for (const id of rawIds) {
+        if (!byId.has(id))
+            throw new Error(`ask() returned unknown selectedId: ${id}`);
+        if (seen.has(id))
+            throw new Error(`duplicate selectedId: ${id}`);
+        seen.add(id);
+        selectedIds.push(id);
+    }
+    if (selectionMode === "single" && selectedIds.length !== 1) {
+        // Single accepts selectedIds only when length is exactly 1.
+        throw new Error("single selectionMode requires exactly one selected id");
+    }
+    return { kind: "selection", selectedIds, selectedId: selectedIds[0] };
+}
+function parseAllowCustom(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value !== "boolean")
+        throw new Error("allowCustom must be a boolean");
+    return value;
+}
+/** Parse + validate model args into a bounded decision request. Exported for tests. */
+export function parseAskUserDecisionArgs(args, limits) {
+    if (typeof args.question !== "string") {
+        throw new Error("question must be a string");
+    }
+    const question = args.question.trim();
+    assertByteLimit("question", question, limits.maxQuestionBytes);
+    const selectionMode = parseSelectionMode(args.selectionMode);
+    const allowCustom = parseAllowCustom(args.allowCustom);
+    if (!Array.isArray(args.options)) {
+        throw new Error("options must be an array");
+    }
+    if (args.options.length < 2) {
+        throw new Error("options must include at least 2 choices");
+    }
+    if (args.options.length > limits.maxOptions) {
+        throw new Error(`options exceeds maxOptions (${limits.maxOptions})`);
+    }
+    const seen = new Set();
+    const options = [];
+    for (let i = 0; i < args.options.length; i++) {
+        const raw = args.options[i];
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            throw new Error(`options[${i}] must be an object`);
+        }
+        const row = raw;
+        if (typeof row.id !== "string")
+            throw new Error(`options[${i}].id must be a string`);
+        const id = row.id.trim();
+        if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(id)) {
+            throw new Error(`options[${i}].id has invalid format`);
+        }
+        if (seen.has(id))
+            throw new Error(`duplicate option id: ${id}`);
+        seen.add(id);
+        if (typeof row.label !== "string")
+            throw new Error(`options[${i}].label must be a string`);
+        const label = row.label.trim();
+        assertByteLimit(`options[${i}].label`, label, limits.maxLabelBytes);
+        options.push({
+            id,
+            label,
+            pros: requireThreeBullets(row.pros, `options[${i}].pros`, limits.maxBulletBytes),
+            cons: requireThreeBullets(row.cons, `options[${i}].cons`, limits.maxBulletBytes),
+        });
+    }
+    return { question, options, selectionMode, allowCustom };
+}
+/**
+ * Create the opt-in `ask_user_decision` tool.
+ * Host must supply `ask`; factory throws if missing.
+ */
+export function createAskUserDecisionTool(options) {
+    if (typeof options?.ask !== "function") {
+        throw new Error("ask_user_decision requires options.ask");
+    }
+    const limits = resolveAskUserDecisionLimits(options);
+    const ask = options.ask;
+    return {
+        name: ASK_USER_DECISION_TOOL_NAME,
+        description: "Ask the user to choose a direction when instructions are ambiguous and the choice matters. " +
+            "Provide 2+ options; each option MUST include exactly 3 pros and 3 cons. " +
+            'Use selectionMode "multiple" when several options may apply together; default is single choice. ' +
+            "Set allowCustom=true only when a short free-text alternative to the listed options is acceptable " +
+            "(custom answer is mutually exclusive with selecting option ids). " +
+            "Do not use for trivia, confirmations that are already clear, or when a single safe default exists.",
+        exclusive: true,
+        parameters: {
+            type: "object",
+            properties: {
+                question: {
+                    type: "string",
+                    description: "Clear decision question for the user",
+                },
+                selectionMode: {
+                    type: "string",
+                    enum: ["single", "multiple"],
+                    description: 'single (default) or multiple selection',
+                },
+                allowCustom: {
+                    type: "boolean",
+                    description: "When true, host may return customText instead of selecting option ids (XOR). Default false.",
+                },
+                options: {
+                    type: "array",
+                    minItems: 2,
+                    maxItems: limits.maxOptions,
+                    items: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Stable option id returned when selected (e.g. keep_sqlite)",
+                            },
+                            label: {
+                                type: "string",
+                                description: "User-facing option label",
+                            },
+                            pros: {
+                                type: "array",
+                                minItems: 3,
+                                maxItems: 3,
+                                items: { type: "string" },
+                                description: "Exactly 3 advantages of this option",
+                            },
+                            cons: {
+                                type: "array",
+                                minItems: 3,
+                                maxItems: 3,
+                                items: { type: "string" },
+                                description: "Exactly 3 disadvantages of this option",
+                            },
+                        },
+                        required: ["id", "label", "pros", "cons"],
+                        additionalProperties: false,
+                    },
+                    description: `2..${limits.maxOptions} options with pros/cons`,
+                },
+            },
+            required: ["question", "options"],
+            additionalProperties: false,
+        },
+        async execute(args, context) {
+            const toolCallId = context.toolCallId;
+            if (context.signal?.aborted)
+                return errorResult(toolCallId, "Operation aborted");
+            let parsed;
+            try {
+                parsed = parseAskUserDecisionArgs(args, limits);
+            }
+            catch (error) {
+                return errorResult(toolCallId, error instanceof Error ? error.message : String(error));
+            }
+            const policyCheck = await enforceExecutionPolicy(options.executionPolicy, {
+                kind: "ask_user_decision",
+                operation: "ask",
+                risk: "medium",
+                metadata: {
+                    optionCount: parsed.options.length,
+                    optionIds: parsed.options.map((o) => o.id),
+                    selectionMode: parsed.selectionMode,
+                    allowCustom: parsed.allowCustom,
+                    sessionId: context.sessionId,
+                    runId: context.runId,
+                    signal: context.signal,
+                },
+            }, toolCallId, ASK_USER_DECISION_TOOL_NAME);
+            if (!policyCheck.allowed)
+                return policyCheck.result;
+            let answer;
+            try {
+                answer = await ask({
+                    question: parsed.question,
+                    options: parsed.options,
+                    selectionMode: parsed.selectionMode,
+                    allowCustom: parsed.allowCustom,
+                    toolCallId,
+                    sessionId: context.sessionId,
+                    runId: context.runId,
+                    signal: context.signal,
+                });
+            }
+            catch (error) {
+                return errorResult(toolCallId, error instanceof Error ? error.message : String(error));
+            }
+            if (context.signal?.aborted)
+                return errorResult(toolCallId, "Operation aborted");
+            let resolved;
+            try {
+                resolved = resolveAskUserDecisionAnswer(answer, parsed.selectionMode, parsed.options, {
+                    allowCustom: parsed.allowCustom,
+                    maxCustomTextBytes: limits.maxCustomTextBytes,
+                });
+            }
+            catch (error) {
+                return errorResult(toolCallId, error instanceof Error ? error.message : String(error));
+            }
+            if (resolved.kind === "custom") {
+                return {
+                    toolCallId,
+                    name: ASK_USER_DECISION_TOOL_NAME,
+                    content: [
+                        {
+                            type: "text",
+                            text: `User provided custom answer: ${resolved.customText}`,
+                        },
+                    ],
+                    metadata: {
+                        customText: resolved.customText,
+                        selectionMode: parsed.selectionMode,
+                        allowCustom: parsed.allowCustom,
+                        question: parsed.question,
+                        options: parsed.options,
+                    },
+                };
+            }
+            const selected = resolved.selectedIds.map((id) => parsed.options.find((o) => o.id === id));
+            const labelText = selected.map((o) => `"${o.label}" (id=${o.id})`).join(", ");
+            return {
+                toolCallId,
+                name: ASK_USER_DECISION_TOOL_NAME,
+                content: [
+                    {
+                        type: "text",
+                        text: parsed.selectionMode === "multiple"
+                            ? `User selected ${selected.length} option(s): ${labelText}.`
+                            : `User selected ${labelText}.`,
+                    },
+                ],
+                metadata: {
+                    selectedId: resolved.selectedId,
+                    selectedIds: resolved.selectedIds,
+                    selectedLabels: selected.map((o) => o.label),
+                    selectionMode: parsed.selectionMode,
+                    allowCustom: parsed.allowCustom,
+                    question: parsed.question,
+                    options: parsed.options,
+                },
+            };
+        },
+    };
+}
+/** JSON Schema describing resume `input` (= AskUserDecisionAnswer). */
+export function askUserDecisionResumeSchema(request) {
+    const optionIds = request.options.map((o) => o.id);
+    const selectionProps = {
+        selectedId: { type: "string", enum: optionIds },
+        selectedIds: {
+            type: "array",
+            minItems: 1,
+            maxItems: optionIds.length,
+            items: { type: "string", enum: optionIds },
+        },
+    };
+    if (!request.allowCustom) {
+        return {
+            type: "object",
+            additionalProperties: false,
+            properties: selectionProps,
+            // Host may send either field; tool/validator enforces mode + XOR with custom.
+            anyOf: [{ required: ["selectedId"] }, { required: ["selectedIds"] }],
+        };
+    }
+    return {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            ...selectionProps,
+            customText: {
+                type: "string",
+                minLength: 1,
+                maxLength: DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES,
+            },
+        },
+        anyOf: [
+            { required: ["selectedId"] },
+            { required: ["selectedIds"] },
+            { required: ["customText"] },
+        ],
+    };
+}
+export function toAskUserDecisionSuspendData(request) {
+    return {
+        question: request.question,
+        options: request.options,
+        selectionMode: request.selectionMode,
+        allowCustom: request.allowCustom,
+        ...(request.toolCallId ? { toolCallId: request.toolCallId } : {}),
+        ...(request.sessionId ? { sessionId: request.sessionId } : {}),
+        ...(request.runId ? { runId: request.runId } : {}),
+    };
+}
+function isAskUserDecisionSuspendData(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const row = value;
+    return (typeof row.question === "string"
+        && Array.isArray(row.options)
+        && (row.selectionMode === "single" || row.selectionMode === "multiple")
+        && typeof row.allowCustom === "boolean");
+}
+/**
+ * Return from a workflow node to pause for a user decision (opt-in durable path).
+ * Host resumes via `resumeWorkflow` + `createAskUserDecisionResumeValidator` / `validateAskUserDecisionResume`.
+ */
+export function suspendAskUserDecision(request, options) {
+    const data = toAskUserDecisionSuspendData(request);
+    if (data.options.length < 2) {
+        throw new Error("suspendAskUserDecision requires at least 2 options");
+    }
+    return suspend({
+        reason: options?.reason ?? ASK_USER_DECISION_SUSPEND_REASON,
+        data,
+        resumeSchema: askUserDecisionResumeSchema(data),
+    });
+}
+/**
+ * Validate resume input against the original decision request.
+ * Shared by workflow `validateResume` and host-held agent resume adapters.
+ */
+export function validateAskUserDecisionResume(request, value, limits) {
+    if (!isAskUserDecisionSuspendData(request)) {
+        throw new Error("invalid ask_user_decision suspend data");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("resume input must be an ask_user_decision answer object");
+    }
+    const maxCustomTextBytes = limits?.maxCustomTextBytes ?? DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES;
+    return resolveAskUserDecisionAnswer(value, request.selectionMode, request.options, { allowCustom: request.allowCustom, maxCustomTextBytes });
+}
+/**
+ * Workflow `validateResume` adapter. Reads durable request from `suspension.data`
+ * (written by `suspendAskUserDecision`). Deny paths skip answer validation.
+ */
+export function createAskUserDecisionResumeValidator(limits) {
+    return (input) => {
+        if (!isAskUserDecisionSuspendData(input.suspension.data)) {
+            throw new Error("suspension.data missing ask_user_decision request");
+        }
+        // Deny (and other no-input resumes) may omit answer; approve supplies it.
+        if (input.value === undefined || input.value === null)
+            return;
+        validateAskUserDecisionResume(input.suspension.data, input.value, limits);
+    };
+}
+/**
+ * Thin agent-path adapter: same validation as workflow resume, for hosts that
+ * persist `AskUserDecisionSuspendData` outside `AgentRunInterruption` (core kinds
+ * unchanged in 0.0.12). Call after operator supplies an answer.
+ */
+export function validateAskUserDecisionAgentResume(input) {
+    return validateAskUserDecisionResume(input.request, input.answer, input.maxCustomTextBytes === undefined
+        ? undefined
+        : { maxCustomTextBytes: input.maxCustomTextBytes });
+}
+//# sourceMappingURL=ask-user-decision.js.map

package/dist/goal-verify.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Thin goal→verify composition: plan Markdown + named checks + workflow
+ * suspend/approve + bounded handoff. Not a second agent/workflow engine.
+ */
+import type { OwnershipScope, SecretRedactor } from "@arnilo/prism";
+import { type WorkflowCheckpointAdapter, type WorkflowEvent, type WorkflowResumeValidator, type WorkflowRunResult } from "@arnilo/prism-workflows";
+import { type CodingCheckSummary, type CodingCheckpointMetadata, type CodingHandoffSummary } from "./coding-checkpoint.js";
+export declare const CODING_GOAL_VERIFY_WORKFLOW_ID: "coding-goal-verify";
+export declare const CODING_GOAL_VERIFY_REVISION: "1";
+export declare const CODING_GOAL_VERIFY_SUSPEND_REASON: "approve-coding-goal-verify";
+export declare class CodingGoalVerifyError extends Error {
+    readonly code = "ERR_PRISM_CODING_GOAL_VERIFY";
+    constructor(message: string);
+}
+export interface CodingGoalVerifyApproval {
+    /** Host validator; required — helper fails closed without it. */
+    readonly validateResume: WorkflowResumeValidator;
+    readonly reason?: string;
+}
+export interface RunCodingGoalVerifyOptions {
+    readonly goal: string;
+    readonly cwd: string;
+    readonly taskId?: string;
+    readonly title?: string;
+    readonly baseBranch?: string;
+    readonly branch?: string;
+    /** Named checks to execute via `runCheck` (host-declared; no free-form shell). */
+    readonly checks: readonly string[];
+    readonly runCheck: (name: string) => Promise<CodingCheckSummary>;
+    /** Host-owned bounded handoff; required before completion. */
+    readonly buildHandoff: (input: {
+        readonly coding: CodingCheckpointMetadata;
+        readonly checks: readonly CodingCheckSummary[];
+    }) => Promise<CodingHandoffSummary>;
+    readonly approval: CodingGoalVerifyApproval;
+    readonly checkpoints: WorkflowCheckpointAdapter;
+    readonly ownership?: OwnershipScope;
+    readonly redactor?: SecretRedactor;
+    readonly signal?: AbortSignal;
+    readonly onEvent?: (event: WorkflowEvent) => void;
+    /** Second call after suspension — mirrors workflow resume. */
+    readonly resume?: {
+        readonly runId: string;
+        readonly decision: "approve" | "deny";
+        readonly expectedVersion: number;
+        readonly input?: unknown;
+    };
+}
+/** Build the durable DAG used by `runCodingGoalVerify` (exported for hosts that want the definition alone). */
+export declare function createCodingGoalVerifyWorkflow(options: {
+    readonly goal: string;
+    readonly cwd: string;
+    readonly taskId: string;
+    readonly title: string;
+    readonly baseBranch: string;
+    readonly branch: string;
+    readonly checks: readonly string[];
+    readonly runCheck: (name: string) => Promise<CodingCheckSummary>;
+    readonly buildHandoff: RunCodingGoalVerifyOptions["buildHandoff"];
+    readonly suspendReason: string;
+}): import("@arnilo/prism-workflows").WorkflowDefinition;
+/**
+ * Run (or resume) a thin goal→verify coding composition.
+ * Fails closed when `approval` / `approval.validateResume` is missing.
+ */
+export declare function runCodingGoalVerify(options: RunCodingGoalVerifyOptions): Promise<WorkflowRunResult>;

package/dist/goal-verify.js

@@ -0,0 +1,283 @@
+import { defineWorkflow, functionNode, resumeWorkflow, runWorkflow, suspend, } from "@arnilo/prism-workflows";
+import { CODING_STATE_KEY, assertCodingResumeAllowed, buildCodingCheckpointMetadata, codingCheckpointStatePatch, codingPlanPathForTask, createCodingPlanMarkdown, fingerprintJson, parseCodingPlanTodos, readCodingCheckpointFromState, readCodingPlanFile, writeCodingPlanFile, } from "./coding-checkpoint.js";
+import { DEFAULT_MAX_CHECK_SUMMARY_BYTES, DEFAULT_MAX_PR_HANDOFF_BYTES } from "./limits.js";
+export const CODING_GOAL_VERIFY_WORKFLOW_ID = "coding-goal-verify";
+export const CODING_GOAL_VERIFY_REVISION = "1";
+export const CODING_GOAL_VERIFY_SUSPEND_REASON = "approve-coding-goal-verify";
+export class CodingGoalVerifyError extends Error {
+    code = "ERR_PRISM_CODING_GOAL_VERIFY";
+    constructor(message) {
+        super(message);
+        this.name = "CodingGoalVerifyError";
+    }
+}
+function requireCoding(state) {
+    const coding = readCodingCheckpointFromState(state);
+    if (!coding)
+        throw new CodingGoalVerifyError("missing state.coding");
+    return coding;
+}
+function clipSummary(summary) {
+    const max = DEFAULT_MAX_CHECK_SUMMARY_BYTES;
+    const bytes = Buffer.from(summary, "utf8");
+    if (bytes.length <= max)
+        return summary;
+    return bytes.subarray(0, max).toString("utf8");
+}
+function normalizeChecks(checks) {
+    return checks.map((check) => ({
+        name: check.name,
+        exitCode: check.exitCode,
+        summary: clipSummary(check.summary),
+    }));
+}
+function assertHandoffBounded(handoff) {
+    const encoded = Buffer.byteLength(JSON.stringify(handoff), "utf8");
+    if (encoded > DEFAULT_MAX_PR_HANDOFF_BYTES) {
+        throw new CodingGoalVerifyError(`handoff exceeds ${DEFAULT_MAX_PR_HANDOFF_BYTES} byte limit (${encoded} bytes)`);
+    }
+}
+function fingerprintsFor(checks) {
+    return {
+        workflowRevision: CODING_GOAL_VERIFY_REVISION,
+        toolFingerprint: fingerprintJson({ tools: ["coding_check", "git_pr_handoff"], checks }),
+        policyFingerprint: fingerprintJson({ requireApproval: [CODING_GOAL_VERIFY_SUSPEND_REASON] }),
+    };
+}
+function defaultTodos(checkNames) {
+    return [
+        { id: "plan", text: "Write goal plan Markdown", done: false },
+        ...checkNames.map((name) => ({ id: `check-${name}`, text: `Run named check ${name}`, done: false })),
+        { id: "handoff", text: "Emit bounded PR handoff", done: false },
+    ];
+}
+function markTodos(todos, doneIds) {
+    return todos.map((todo) => (doneIds.has(todo.id) ? { ...todo, done: true } : todo));
+}
+/** Build the durable DAG used by `runCodingGoalVerify` (exported for hosts that want the definition alone). */
+export function createCodingGoalVerifyWorkflow(options) {
+    const planPath = codingPlanPathForTask(options.taskId);
+    const fps = () => fingerprintsFor(options.checks);
+    const planNode = functionNode({
+        execute: async (ctx) => {
+            const todos = defaultTodos(options.checks);
+            const markdown = createCodingPlanMarkdown({
+                title: options.title,
+                taskId: options.taskId,
+                status: "planned",
+                todos,
+                notes: options.goal,
+            });
+            const plan = await writeCodingPlanFile({
+                workspaceRoot: options.cwd,
+                planPath,
+                markdown,
+            });
+            const metadata = buildCodingCheckpointMetadata({
+                taskId: options.taskId,
+                workspaceRoot: options.cwd,
+                baseBranch: options.baseBranch,
+                branch: options.branch,
+                planPath,
+                plan,
+                fingerprints: fps(),
+                todos: parseCodingPlanTodos(markdown),
+                status: "planned",
+            });
+            await ctx.updateState(codingCheckpointStatePatch(metadata), { mode: "merge" });
+            return { planPath, planSha256: plan.sha256 };
+        },
+    });
+    const verifyNode = functionNode({
+        execute: async (ctx) => {
+            const coding = requireCoding(ctx.state);
+            const checks = normalizeChecks(await Promise.all(options.checks.map((name) => options.runCheck(name))));
+            const failed = checks.some((check) => check.exitCode !== 0);
+            const done = new Set([
+                "plan",
+                ...options.checks.map((name) => `check-${name}`),
+            ]);
+            const todos = markTodos(coding.todos.length ? coding.todos : defaultTodos(options.checks), done);
+            const markdown = createCodingPlanMarkdown({
+                title: options.title,
+                taskId: options.taskId,
+                status: failed ? "awaiting_approval" : "ready_for_handoff",
+                todos,
+                notes: options.goal,
+            });
+            const plan = await writeCodingPlanFile({
+                workspaceRoot: options.cwd,
+                planPath,
+                markdown,
+            });
+            const next = buildCodingCheckpointMetadata({
+                ...coding,
+                plan,
+                checks,
+                todos: parseCodingPlanTodos(markdown),
+                status: failed ? "awaiting_approval" : "ready_for_handoff",
+                fingerprints: fps(),
+                updatedAt: new Date().toISOString(),
+            });
+            await ctx.updateState(codingCheckpointStatePatch(next), { mode: "merge" });
+            return { checks, failed };
+        },
+    });
+    const reviewNode = functionNode({
+        execute: async (ctx) => {
+            const coding = requireCoding(ctx.state);
+            const failed = coding.checks.some((check) => check.exitCode !== 0);
+            if (!failed)
+                return { approved: true, skipped: true };
+            if (!ctx.resume) {
+                return suspend({
+                    reason: options.suspendReason,
+                    data: {
+                        taskId: coding.taskId,
+                        branch: coding.branch,
+                        planSha256: coding.plan.sha256,
+                        checks: coding.checks,
+                    },
+                    resumeSchema: {
+                        type: "object",
+                        required: ["reviewer"],
+                        properties: { reviewer: { type: "string" } },
+                    },
+                });
+            }
+            const reviewer = ctx.resume.input?.reviewer ?? "unknown";
+            return { approved: true, reviewer, planSha256: coding.plan.sha256 };
+        },
+    });
+    const handoffNode = functionNode({
+        execute: async (ctx) => {
+            const coding = requireCoding(ctx.state);
+            const planFile = await readCodingPlanFile({
+                workspaceRoot: options.cwd,
+                planPath: coding.planPath,
+                expected: coding.plan,
+            });
+            assertCodingResumeAllowed({
+                metadata: coding,
+                expected: fps(),
+                expectedWorkspaceRoot: options.cwd,
+                expectedBaseBranch: options.baseBranch,
+                planBytes: Buffer.from(planFile.markdown, "utf8"),
+            });
+            const handoff = await options.buildHandoff({ coding, checks: coding.checks });
+            assertHandoffBounded(handoff);
+            const todos = markTodos(coding.todos.length ? coding.todos : defaultTodos(options.checks), new Set(["plan", "handoff", ...options.checks.map((name) => `check-${name}`)]));
+            const markdown = createCodingPlanMarkdown({
+                title: options.title,
+                taskId: options.taskId,
+                status: "completed",
+                todos,
+                notes: options.goal,
+            });
+            const plan = await writeCodingPlanFile({
+                workspaceRoot: options.cwd,
+                planPath,
+                markdown,
+            });
+            const next = buildCodingCheckpointMetadata({
+                ...coding,
+                plan,
+                handoff,
+                todos: parseCodingPlanTodos(markdown),
+                status: "completed",
+                fingerprints: fps(),
+                updatedAt: new Date().toISOString(),
+            });
+            await ctx.updateState(codingCheckpointStatePatch(next), { mode: "merge" });
+            return { handoff, codingStatus: next.status };
+        },
+    });
+    return defineWorkflow({
+        revision: CODING_GOAL_VERIFY_REVISION,
+        id: CODING_GOAL_VERIFY_WORKFLOW_ID,
+        nodes: {
+            plan: planNode,
+            verify: verifyNode,
+            review: reviewNode,
+            handoff: handoffNode,
+        },
+        edges: [
+            ["plan", "verify"],
+            ["verify", "review"],
+            ["review", "handoff"],
+        ],
+        limits: { maxConcurrency: 1, maxStateBytes: 64 * 1024 },
+    });
+}
+/**
+ * Run (or resume) a thin goal→verify coding composition.
+ * Fails closed when `approval` / `approval.validateResume` is missing.
+ */
+export async function runCodingGoalVerify(options) {
+    if (!options.approval?.validateResume) {
+        throw new CodingGoalVerifyError("approval.validateResume is required");
+    }
+    if (!Array.isArray(options.checks) || options.checks.length < 1) {
+        throw new CodingGoalVerifyError("checks must declare at least one named check");
+    }
+    for (const name of options.checks) {
+        if (typeof name !== "string" || !/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name)) {
+            throw new CodingGoalVerifyError(`invalid check name: ${String(name)}`);
+        }
+    }
+    if (typeof options.runCheck !== "function") {
+        throw new CodingGoalVerifyError("runCheck is required");
+    }
+    if (typeof options.buildHandoff !== "function") {
+        throw new CodingGoalVerifyError("buildHandoff is required");
+    }
+    if (typeof options.goal !== "string" || options.goal.trim().length < 1) {
+        throw new CodingGoalVerifyError("goal is required");
+    }
+    if (typeof options.cwd !== "string" || options.cwd.length < 1) {
+        throw new CodingGoalVerifyError("cwd is required");
+    }
+    const taskId = options.taskId ?? "goal";
+    const title = options.title ?? options.goal.slice(0, 120);
+    const baseBranch = options.baseBranch ?? "main";
+    const branch = options.branch ?? `codex/${taskId}`;
+    const suspendReason = options.approval.reason ?? CODING_GOAL_VERIFY_SUSPEND_REASON;
+    const workflow = createCodingGoalVerifyWorkflow({
+        goal: options.goal,
+        cwd: options.cwd,
+        taskId,
+        title,
+        baseBranch,
+        branch,
+        checks: options.checks,
+        runCheck: options.runCheck,
+        buildHandoff: options.buildHandoff,
+        suspendReason,
+    });
+    const validateState = async (input) => {
+        if (CODING_STATE_KEY in input.value) {
+            readCodingCheckpointFromState(input.value);
+        }
+    };
+    const shared = {
+        checkpoints: options.checkpoints,
+        redactor: options.redactor,
+        ownership: options.ownership,
+        validateState,
+        validateResume: options.approval.validateResume,
+        signal: options.signal,
+        onEvent: options.onEvent,
+    };
+    if (options.resume) {
+        return resumeWorkflow(workflow, { runId: options.resume.runId, workflowId: workflow.id }, {
+            ...shared,
+            resume: {
+                decision: options.resume.decision,
+                expectedVersion: options.resume.expectedVersion,
+                input: options.resume.input,
+            },
+        });
+    }
+    return runWorkflow(workflow, { goal: options.goal, baseBranch }, shared);
+}
+//# sourceMappingURL=goal-verify.js.map

package/dist/index.d.ts

@@ -18,9 +18,13 @@ export { createGitTools, createGitStatusTool, createGitDiffTool, createGitBranch
 export type { GitToolsOptions } from "./git-tools.js";
 export { createCodingCheckTool } from "./checks.js";
 export type { CodingCheckToolOptions, NamedCheckDefinition } from "./checks.js";
+export { ASK_USER_DECISION_RATIONALE_COUNT, ASK_USER_DECISION_SUSPEND_REASON, ASK_USER_DECISION_TOOL_NAME, DEFAULT_MAX_ASK_USER_DECISION_BULLET_BYTES, DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES, DEFAULT_MAX_ASK_USER_DECISION_LABEL_BYTES, DEFAULT_MAX_ASK_USER_DECISION_OPTIONS, DEFAULT_MAX_ASK_USER_DECISION_QUESTION_BYTES, HARD_MAX_ASK_USER_DECISION_BULLET_BYTES, HARD_MAX_ASK_USER_DECISION_CUSTOM_BYTES, HARD_MAX_ASK_USER_DECISION_LABEL_BYTES, HARD_MAX_ASK_USER_DECISION_OPTIONS, HARD_MAX_ASK_USER_DECISION_QUESTION_BYTES, askUserDecisionResumeSchema, createAskUserDecisionResumeValidator, createAskUserDecisionTool, parseAskUserDecisionArgs, resolveAskUserDecisionAnswer, resolveAskUserDecisionLimits, suspendAskUserDecision, toAskUserDecisionSuspendData, validateAskUserDecisionAgentResume, validateAskUserDecisionResume, } from "./ask-user-decision.js";
+export type { AskUserDecisionAnswer, AskUserDecisionHandler, AskUserDecisionOption, AskUserDecisionRequest, AskUserDecisionSelectionMode, AskUserDecisionSuspendData, AskUserDecisionToolOptions, ResolvedAskUserDecisionAnswer, ResolvedAskUserDecisionLimits, SuspendAskUserDecisionOptions, } from "./ask-user-decision.js";
 export { createDirectoryArtifactWriter, createTempArtifactWriter, sha256Hex } from "./artifacts.js";
 export { CODING_CHECKPOINT_SCHEMA_VERSION, CODING_STATE_KEY, CodingCheckpointError, assertCodingResumeAllowed, buildCodingCheckpointMetadata, codingCheckpointStatePatch, codingPlanPathForTask, createCodingArtifactRef, createCodingPlanMarkdown, fingerprintJson, parseCodingPlanTodos, readCodingCheckpointFromState, readCodingPlanFile, resolveCodingCheckpointLimits, validateCodingCheckpointMetadata, verifyCodingArtifactBytes, writeCodingPlanFile, } from "./coding-checkpoint.js";
 export type { CodingArtifactKind, CodingArtifactRef, CodingCheckSummary, CodingCheckpointLimitOptions, CodingCheckpointMetadata, CodingFingerprints, CodingHandoffSummary, CodingTaskStatus, CodingTodoItem, ResolvedCodingCheckpointLimits, } from "./coding-checkpoint.js";
+export { CODING_GOAL_VERIFY_REVISION, CODING_GOAL_VERIFY_SUSPEND_REASON, CODING_GOAL_VERIFY_WORKFLOW_ID, CodingGoalVerifyError, createCodingGoalVerifyWorkflow, runCodingGoalVerify, } from "./goal-verify.js";
+export type { CodingGoalVerifyApproval, RunCodingGoalVerifyOptions, } from "./goal-verify.js";
 export { withFileMutationQueue } from "./file-mutation-queue.js";
 export { enforceExecutionPolicy } from "./execution-policy.js";
 export { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, DEFAULT_MAX_TEXT_SCAN_BYTES, DEFAULT_MAX_WRITE_BYTES, DEFAULT_MAX_EDIT_FILE_BYTES, DEFAULT_MAX_EDIT_INPUT_BYTES, DEFAULT_MAX_EDITS, DEFAULT_SHELL_TIMEOUT_SECONDS, DEFAULT_MAX_TOTAL_OUTPUT_BYTES, DEFAULT_MAX_REPO_DEPTH, DEFAULT_MAX_REPO_ENTRIES, DEFAULT_MAX_REPO_FILES, DEFAULT_MAX_REPO_RESULTS, DEFAULT_MAX_REPO_CONCURRENCY, DEFAULT_MAX_SEARCH_SCAN_BYTES, DEFAULT_MAX_SEARCH_FILE_BYTES, DEFAULT_MAX_SEARCH_MATCHES, DEFAULT_MAX_SEARCH_PATTERN_BYTES, DEFAULT_MAX_SEARCH_LINE_BYTES, DEFAULT_MAX_SEARCH_CONTEXT_LINES, DEFAULT_MAX_SEARCH_TIME_MS, DEFAULT_MAX_GIT_PATHS, DEFAULT_MAX_GIT_REF_BYTES, DEFAULT_MAX_GIT_MESSAGE_BYTES, DEFAULT_MAX_GIT_OUTPUT_BYTES, DEFAULT_MAX_GIT_DIFF_LINES, DEFAULT_MAX_GIT_CHANGED_FILES, DEFAULT_MAX_GIT_PATCH_BYTES, DEFAULT_MAX_GIT_WORKTREES, DEFAULT_GIT_TIMEOUT_MS, DEFAULT_MAX_CHECK_NAMES, DEFAULT_MAX_CHECK_CONCURRENCY, DEFAULT_CHECK_TIMEOUT_MS, DEFAULT_MAX_CHECK_DIAGNOSTIC_LINES, DEFAULT_MAX_CHECK_OUTPUT_BYTES, DEFAULT_MAX_PR_HANDOFF_BYTES, DEFAULT_MAX_PR_COMMITS, DEFAULT_MAX_PLAN_BYTES, DEFAULT_MAX_TODOS, DEFAULT_MAX_TODO_TEXT_BYTES, DEFAULT_MAX_CODING_ARTIFACTS, DEFAULT_MAX_CODING_ARTIFACT_BYTES, DEFAULT_MAX_CHECK_SUMMARY_BYTES, DEFAULT_MAX_CODING_CHECKPOINT_BYTES, HARD_MAX_BYTES, HARD_MAX_LINES, HARD_MAX_TEXT_SCAN_BYTES, HARD_MAX_IMAGE_BYTES, HARD_MAX_WRITE_BYTES, HARD_MAX_EDIT_FILE_BYTES, HARD_MAX_EDIT_INPUT_BYTES, HARD_MAX_EDITS, HARD_SHELL_TIMEOUT_SECONDS, HARD_MAX_TOTAL_OUTPUT_BYTES, HARD_MAX_REPO_DEPTH, HARD_MAX_REPO_ENTRIES, HARD_MAX_REPO_FILES, HARD_MAX_REPO_RESULTS, HARD_MAX_REPO_CONCURRENCY, HARD_MAX_SEARCH_SCAN_BYTES, HARD_MAX_SEARCH_FILE_BYTES, HARD_MAX_SEARCH_MATCHES, HARD_MAX_SEARCH_PATTERN_BYTES, HARD_MAX_SEARCH_LINE_BYTES, HARD_MAX_SEARCH_CONTEXT_LINES, HARD_MAX_SEARCH_TIME_MS, HARD_MAX_GIT_PATHS, HARD_MAX_GIT_REF_BYTES, HARD_MAX_GIT_MESSAGE_BYTES, HARD_MAX_GIT_OUTPUT_BYTES, HARD_MAX_GIT_DIFF_LINES, HARD_MAX_GIT_CHANGED_FILES, HARD_MAX_GIT_PATCH_BYTES, HARD_MAX_GIT_WORKTREES, HARD_GIT_TIMEOUT_MS, HARD_MAX_CHECK_NAMES, HARD_MAX_CHECK_CONCURRENCY, HARD_CHECK_TIMEOUT_MS, HARD_MAX_CHECK_DIAGNOSTIC_LINES, HARD_MAX_CHECK_OUTPUT_BYTES, HARD_MAX_PR_HANDOFF_BYTES, HARD_MAX_PR_COMMITS, HARD_MAX_PLAN_BYTES, HARD_MAX_TODOS, HARD_MAX_TODO_TEXT_BYTES, HARD_MAX_CODING_ARTIFACTS, HARD_MAX_CODING_ARTIFACT_BYTES, HARD_MAX_CHECK_SUMMARY_BYTES, HARD_MAX_CODING_CHECKPOINT_BYTES, } from "./limits.js";
@@ -52,6 +56,8 @@ export interface ToolsOptions {
 }
 /**
  * Full coding tool set: `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search`.
+ * Opt-in tools (`createGitTools`, `createAskUserDecisionTool`, `createCodingCheckTool`)
+ * stay out — hosts register them explicitly.
  */
 export declare function createCodingTools(cwd: string, options?: ToolsOptions): readonly ToolDefinition[];
 /**

package/dist/index.js

@@ -14,8 +14,10 @@ export { createLocalRepositoryOperations, resolveRepositoryLimits, compileSearch
 export { createGitOperations, resolveGitLimits, parsePorcelainV2, GitError, SAFE_GIT_ENV, SAFE_GIT_CONFIG_ARGS, createBoundGitRunner, runGitCli, } from "./git.js";
 export { createGitTools, createGitStatusTool, createGitDiffTool, createGitBranchTool, createGitWorktreeTool, createGitApplyTool, createGitCommitTool, createGitPrHandoffTool, } from "./git-tools.js";
 export { createCodingCheckTool } from "./checks.js";
+export { ASK_USER_DECISION_RATIONALE_COUNT, ASK_USER_DECISION_SUSPEND_REASON, ASK_USER_DECISION_TOOL_NAME, DEFAULT_MAX_ASK_USER_DECISION_BULLET_BYTES, DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES, DEFAULT_MAX_ASK_USER_DECISION_LABEL_BYTES, DEFAULT_MAX_ASK_USER_DECISION_OPTIONS, DEFAULT_MAX_ASK_USER_DECISION_QUESTION_BYTES, HARD_MAX_ASK_USER_DECISION_BULLET_BYTES, HARD_MAX_ASK_USER_DECISION_CUSTOM_BYTES, HARD_MAX_ASK_USER_DECISION_LABEL_BYTES, HARD_MAX_ASK_USER_DECISION_OPTIONS, HARD_MAX_ASK_USER_DECISION_QUESTION_BYTES, askUserDecisionResumeSchema, createAskUserDecisionResumeValidator, createAskUserDecisionTool, parseAskUserDecisionArgs, resolveAskUserDecisionAnswer, resolveAskUserDecisionLimits, suspendAskUserDecision, toAskUserDecisionSuspendData, validateAskUserDecisionAgentResume, validateAskUserDecisionResume, } from "./ask-user-decision.js";
 export { createDirectoryArtifactWriter, createTempArtifactWriter, sha256Hex } from "./artifacts.js";
 export { CODING_CHECKPOINT_SCHEMA_VERSION, CODING_STATE_KEY, CodingCheckpointError, assertCodingResumeAllowed, buildCodingCheckpointMetadata, codingCheckpointStatePatch, codingPlanPathForTask, createCodingArtifactRef, createCodingPlanMarkdown, fingerprintJson, parseCodingPlanTodos, readCodingCheckpointFromState, readCodingPlanFile, resolveCodingCheckpointLimits, validateCodingCheckpointMetadata, verifyCodingArtifactBytes, writeCodingPlanFile, } from "./coding-checkpoint.js";
+export { CODING_GOAL_VERIFY_REVISION, CODING_GOAL_VERIFY_SUSPEND_REASON, CODING_GOAL_VERIFY_WORKFLOW_ID, CodingGoalVerifyError, createCodingGoalVerifyWorkflow, runCodingGoalVerify, } from "./goal-verify.js";
 // --- generic primitives (re-exported for hosts that want them) ---
 export { withFileMutationQueue } from "./file-mutation-queue.js";
 export { enforceExecutionPolicy } from "./execution-policy.js";
@@ -43,6 +45,8 @@ function withRepositoryDefaults(toolOptions, shared) {
 }
 /**
  * Full coding tool set: `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search`.
+ * Opt-in tools (`createGitTools`, `createAskUserDecisionTool`, `createCodingCheckTool`)
+ * stay out — hosts register them explicitly.
  */
 export function createCodingTools(cwd, options) {
     const policy = options?.executionPolicy;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arnilo/prism-coding-agent",
-  "version": "0.0.10",
-  "description": "Optional coding-agent tools (shell, read, write, edit, repo_list, repo_search, opt-in Git/check, and durable plan/checkpoint helpers) package for Prism.",
+  "version": "0.0.12",
+  "description": "Optional coding-agent tools (shell, read, write, edit, repo_list, repo_search, opt-in Git/check/ask-user-decision, and durable plan/checkpoint helpers) package for Prism.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -28,11 +28,13 @@
     "diff": "^9.0.0"
   },
   "peerDependencies": {
-    "@arnilo/prism": "0.0.10"
+    "@arnilo/prism": "0.0.12",
+    "@arnilo/prism-workflows": "0.0.12"
   },
   "devDependencies": {
     "@arnilo/prism": "file:../..",
-    "@arnilo/prism-evals": "file:../evals"
+    "@arnilo/prism-evals": "file:../evals",
+    "@arnilo/prism-workflows": "file:../workflows"
   },
   "engines": {
     "node": ">=20"