@arnilo/prism-coding-agent 0.0.96 → 0.1.0

package/CHANGELOG.md

@@ -1,11 +1,149 @@
 # Changelog
+
+## [0.1.0] - 2026-08-09
+
+### Changed
+- Released with exact 0.1.0 graph.
+
+## [0.0.28] - 2026-08-08
+
+### Changed
+- Released with exact 0.0.28 graph.
+
+## [0.0.27] - 2026-08-07
+
+### Added
+- `createCodingLifecycleEmitter(options?)` — consumer-gated coding lifecycle events (Phase 10): ships `process_*` (reuses `CodingProcessEvent`) plus `file_changed`, `worktree_changed`, `permission_denied`, `configuration_changed`; synchronous bounded `emit`/`on`; drops unknown/oversized events without breaking producer paths; invalid limits fail closed with `CodingLifecycleError` (`ERR_PRISM_LIFECYCLE_LIMIT`); frozen `DEFAULT_LIFECYCLE_MAX_*` / `HARD_LIFECYCLE_MAX_*` caps.
+- `onEvent` option on `createWriteTool` / `createEditTool` / `createMoveTool` / `createDeleteTool` / `createGitWorktreeTool` — tools emit `file_changed` (write/edit/move/delete) and `worktree_changed` (add/remove) after successful mutation, and `permission_denied` via the shared `enforceExecutionPolicy` deny hook (never raw tool arguments).
+- `enforceExecutionPolicy(..., onDenied?)` — optional callback invoked once per policy denial (additive; existing callers unaffected).
+
+## [0.0.26] - 2026-08-06
+
+### Added
+- `createGitHubForge(options)` — reference GitHub adapter: issue context, authenticated push (`GIT_CONFIG_*` credential injection, never argv), PR create/update, review comments, checks/status, bounded `reconcileHandoff`; every mutation gated by `ExecutionPolicy` and recorded in `ToolEffectStore` (retry never duplicates PRs/comments); typed `ERR_PRISM_FORGE_*` codes; frozen `DEFAULT_MAX_FORGE_*` / `HARD_MAX_FORGE_*` caps; no octokit dependency.
+- `createGitAwareRepositoryOperations(cwd, options?)` — ignore-aware enumeration via fixed `git ls-files` with native walker fallback; host-only `includeIgnored`; `DEFAULT_MAX_LS_FILES_OUTPUT_BYTES` / `HARD_MAX_LS_FILES_OUTPUT_BYTES`.
+- `createLanguageIntelligence(options)` — host-selected LSP 3.17 client (Content-Length framing); symbols/definitions/references/diagnostics/hover/rename; lazy spawn; `ERR_PRISM_LSP_*`; frozen `DEFAULT_MAX_LSP_*` / `HARD_MAX_LSP_*` caps.
+- `createProcessSessions(options)` — managed process sessions (start/output/input/wait/signal/kill/release); optional sandbox `startProcess` backend + `reconcile`/sandbox-loss → `unknown`; ownership/identity + expiry sweep; `CodingProcessEvent`; `ERR_PRISM_PROCESS_*`; frozen `DEFAULT_MAX_PROCESS_*` / `HARD_MAX_PROCESS_*` caps; `OutputAccumulator.readRaw` for cursor paging.
+- `CreateGitHubForgeOptions.fetch?` — host-injectable fetch (defaults to `globalThis.fetch`); enables routing forge traffic through an egress proxy and mock-fetch tests.
+
+## [0.0.25] - 2026-08-06
+
+### Added
+- `ask_user_decision` durable elicitation hook maps onto shared pending decisions (blocking `ask()` unchanged for process-local path).
+
+### Changed
+- Released with exact 0.0.25 graph.
+
+See [migration guide](../../docs/migration.md) for the 0.0.24 → 0.0.25 notes.
+
+## [0.0.24] - 2026-08-04
+
+### Added
+- Durable `AgentEventSource` (memory + PostgreSQL LISTEN/NOTIFY), recoverable `ToolEffectStore`, and AG-UI MCP/MCP Apps/A2A fronting for Phase 7.
+
+### Changed
+- Publishable graph remains **47** manifests at **0.0.24**; peers and lockfile move together.
+
+See [migration guide](../../docs/migration.md) for the 0.0.23 → 0.0.24 notes.
+
+## [0.0.23] - 2026-08-03
+
+### Changed
+- Released with exact 0.0.23 graph.
+
+## [0.0.22] - 2026-07-31
+
+### Changed
+- Released with exact 0.0.22 graph.
+
+## [0.0.21] - 2026-07-31
+
+### Added
+- `repo_search` `outputMode` (`content` | `files_with_matches` | `count`).
+- Bounded `glob` tool (`*`/`?`/`**`; no brace expansion).
+- Optional session-scoped `requireReadBeforeWrite` + `ReadPathSet` + `force` on write/edit.
+- Bounded `delete` (file or empty dir) and `move` tools with dual-path mutation queue.
+
+### Changed
+- `createCodingTools` returns 9 tools; `createReadOnlyTools` returns 4 (includes `glob`).
+
+## [0.0.20] - 2026-07-31
+
+### Changed
+- Released with exact 0.0.20 graph.
+
+## [0.0.19] - 2026-07-30
+
+### Changed
+- Released with exact 0.0.19 graph.
+
+## [0.0.18] - 2026-07-30
+
+### Changed
+- `repo_search` is literal-only: `mode: "regex"` removed from the tool schema; `compileSearchPattern` no longer compiles `RegExp` (ReDoS mitigation).
+- Default `write`/`edit` local `writeFile` uses same-directory temp + `rename` for crash-safe replacement.
+
+## [0.0.17] - 2026-07-29
+
+### Added
+- `ShellToolOptions.envAllowlist` restricts the environment the spawn hook and child process see (secret scrubbing without re-implementing the hook).
+
+### Changed
+- Released with exact 0.0.17 graph.
+
+## [0.0.16] - 2026-07-26
+
+### Changed
+- Released with exact 0.0.16 graph.
+
+## [0.0.15] - 2026-07-26
+
+## [0.0.14] - 2026-07-26
+
+### Changed
+
+- Released with exact 0.0.14 graph.
+
+## [0.0.13] - 2026-07-24
+
+### Changed
+
+- Released with exact 0.0.13 graph.
+
+## [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
+
+- Released with exact 0.0.10 graph.
+
+### Notes
+
+- Sandbox composition / workspace-mode contract lives in `@arnilo/prism-coding-security` (required `workspaceMode`, same-tree Git via `createGitTools(composition.workspaceRoot, { execFile })`). Coding-agent tool surfaces unchanged for 0.0.10.
+
 ## [0.0.96] - 2026-07-21
 
 ### Changed
 
 - Released with exact 0.0.96 graph.
 
-
 ## [0.0.9] - 2026-07-21
 
 - Added bounded native `repo_list` / `repo_search` tools with streaming walks, literal/regex search, finite depth/entry/match/scan/time caps, and pluggable `RepositoryOperations`.
@@ -18,7 +156,6 @@
 
 - Released with the exact 0.0.8 first-party package graph.
 
-
 ## [0.0.7] - 2026-07-19
 
 - Released with the exact 0.0.7 first-party package graph.
@@ -42,7 +179,6 @@
 
 - Pinned the required `@arnilo/prism` peer and package metadata to 0.0.5; runtime behavior is unchanged.
 
-
 ## [0.0.4] - 2026-07-14
 
 ### Added

package/README.md

@@ -1,10 +1,10 @@
 # @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`, `glob`, `delete`, `move` — plus opt-in structured Git/check tools via `createGitTools()`, opt-in `createAskUserDecisionTool({ ask })` (durable runs surface as shared elicitation decisions), 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.
+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/glob/Git are native Prism tools (hand-rolled glob; no picomatch/ripgrep).
 
-> ⚠️ **These tools perform real shell and filesystem operations on the host. They provide no sandbox.** Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. See the [coding agent tools docs](https://github.com/ashiqrniloy/prism/blob/main/docs/coding-agent-tools.md) and the [host security guide](https://github.com/ashiqrniloy/prism/blob/main/docs/host-security.md).
+> ⚠️ **These tools perform real shell and filesystem operations on the host. They provide no sandbox.** Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. For disposable sandbox composition with required `workspaceMode`, use `@arnilo/prism-coding-security` (`createSandboxCodingComposition`). See the [coding agent tools docs](https://github.com/ashiqrniloy/prism/blob/main/docs/coding-agent-tools.md) and the [host security guide](https://github.com/ashiqrniloy/prism/blob/main/docs/host-security.md).
 
 ## Install
 
@@ -12,11 +12,11 @@ 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
 
-Register the full coding set:
+Register the full coding set (nine tools):
 
 ```ts
 import { createToolRegistry } from "@arnilo/prism";
@@ -25,7 +25,7 @@ import { createCodingTools } from "@arnilo/prism-coding-agent";
 const tools = createToolRegistry(createCodingTools(process.cwd()));
 ```
 
-Read-only subset (inspection-only agents):
+Read-only subset (inspection-only agents — includes `glob`):
 
 ```ts
 import { createReadOnlyTools } from "@arnilo/prism-coding-agent";
@@ -38,7 +38,14 @@ 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,
+  createReadPathSet,
+  createReadTool,
+  createEditTool,
+} from "@arnilo/prism-coding-agent";
 
 const shell = createShellTool(process.cwd(), {
   shellPath: "/bin/bash",        // force bash; default: SHELL env → /bin/bash → sh
@@ -54,19 +61,37 @@ const remoteWrite = createWriteTool(process.cwd(), {
     mkdir: async (dir) => { /* mkdir -p remotely */ },
   },
 });
+
+// Optional soft guard: share one ReadPathSet across read/write/edit.
+const readPaths = createReadPathSet();
+const read = createReadTool(process.cwd(), { readPathSet: readPaths });
+const write = createWriteTool(process.cwd(), { requireReadBeforeWrite: true, readPathSet: readPaths });
+const edit = createEditTool(process.cwd(), { requireReadBeforeWrite: true, readPathSet: readPaths });
+
+// 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
 
 | Tool | Input | Result |
 | --- | --- | --- |
-| `shell` | `{ command, timeout? }` | Combined output + `metadata.exitCode`; 600-second default timeout and 64 MiB total-output cap. Non-zero exit is **not** an error. |
-| `read` | `{ path, offset?, limit? }` | Streamed bounded text page or bounded `[note, ImageContent]`. |
-| `write` | `{ path, content }` | Bounded UTF-8 input; `Successfully wrote N bytes (M lines) to <abs>`. |
-| `edit` | `{ path, edits: [{oldText,newText}] }` | Bounded target/input/count; `Successfully replaced N block(s)` + diff metadata. |
-| `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()`. |
+| `shell` | `{ command, timeout? }` | Combined output + `metadata.exitCode`; 600-second default timeout and 64 MiB total-output cap. Non-zero exit is **not** an error. Prefer dedicated tools when they fit. |
+| `read` | `{ path, offset?, limit? }` | Streamed bounded text page or bounded `[note, ImageContent]`. Continue with suggested offset when truncated. |
+| `write` | `{ path, content, force? }` | Full overwrite; bounded UTF-8 input; optional read-before-write. |
+| `edit` | `{ path, edits: [{oldText,newText}], force? }` | Exact-then-fuzzy replace; **fuzzy may succeed silently** — prefer exact `oldText`; duplicates fail closed. |
+| `repo_list` | `{ path?, includeHidden?, maxDepth?, maxResults?, offset? }` | Deterministic relative entries; paginates with `nextOffset`. Prefer `glob` for patterns. |
+| `repo_search` | `{ query, path?, mode?, caseSensitive?, includeHidden?, context?, maxMatches?, outputMode? }` | Literal search; `outputMode`: `content` \| `files_with_matches` \| `count`. |
+| `glob` | `{ pattern, path?, includeHidden?, maxDepth?, maxResults?, offset? }` | Filename match (`*`/`?`/`**`; no braces). Files only. |
+| `delete` | `{ path }` | High-risk: file or empty dir only; **no trash**. |
+| `move` | `{ from, to, overwrite? }` | High-risk rename/move; `overwrite` default false; **no trash**. |
+| `git_*` / `coding_check` | via `createGitTools(cwd, { commitIdentity, checks? })` | Opt-in structured Git + named checks. Not in `createCodingTools()`. |
+| `ask_user_decision` | via `createAskUserDecisionTool({ ask })` | Opt-in user choice. Not in default aggregators. |
 
 ### pi name mapping
 
@@ -74,19 +99,23 @@ const remoteWrite = createWriteTool(process.cwd(), {
 | --- | --- |
 | `shell` | `bash` |
 | `read` / `write` / `edit` | `read` / `write` / `edit` |
-| `repo_list` / `repo_search` | _(native; no pi equivalent shipped)_ |
+| `repo_list` / `repo_search` / `glob` / `delete` / `move` | _(native; no pi equivalent shipped)_ |
+
+### Phase 4 non-goals
+
+No PDF reader, trash daemon, or PTY in 0.0.21. Phase 9 optionals: `createLanguageIntelligence`, `createProcessSessions`, `createGitHubForge`. See [coding agent tools docs](https://github.com/ashiqrniloy/prism/blob/main/docs/coding-agent-tools.md), [language intelligence](https://github.com/ashiqrniloy/prism/blob/main/docs/language-intelligence.md), [process sessions](https://github.com/ashiqrniloy/prism/blob/main/docs/process-sessions.md), and [forge integration](https://github.com/ashiqrniloy/prism/blob/main/docs/forge-integration.md).
 
 ## Exports
 
-Factories: `createShellTool`, `createReadTool`, `createWriteTool`, `createEditTool`, `createRepoListTool`, `createRepoSearchTool`, `createCodingTools`, `createReadOnlyTools`, `createAllTools`, `createGitTools`, `createCodingCheckTool`, `createLocalBashOperations`, `createLocalRepositoryOperations`, `createGitOperations`.
+Factories: `createShellTool`, `createReadTool`, `createWriteTool`, `createEditTool`, `createRepoListTool`, `createRepoSearchTool`, `createGlobTool`, `createDeleteTool`, `createMoveTool`, `createCodingTools`, `createReadOnlyTools`, `createAllTools`, `createGitTools`, `createCodingCheckTool`, `createAskUserDecisionTool`, `createLocalBashOperations`, `createLocalRepositoryOperations`, `createGitAwareRepositoryOperations`, `createLanguageIntelligence`, `createProcessSessions`, `createGitHubForge`, `createGitOperations`, `createReadPathSet`.
 
-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`, `matchGlobPattern`, `validateGlobPattern`, `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`.
+Option/operation types: `ToolsOptions`, `ShellToolOptions`/`BashOperations`, `ReadToolOptions`/`ReadOperations`/`ReadTextOptions`/`ReadTextResult`, `WriteToolOptions`/`WriteOperations`, `EditToolOptions`/`EditOperations`/`EditToolDetails`, `DeleteToolOptions`/`DeleteOperations`, `MoveToolOptions`/`MoveOperations`, `GlobToolOptions`, `ReadPathSet`.
 
 Text reads stop after one page or `maxScanBytes` instead of loading the file. Custom `ReadOperations` must implement bounded `readText` and `statFile`; custom `EditOperations` must implement `statFile` and honor the supplied read cap/signal. Successful truncated shell output is retained in an exclusive Unix `0600` temp file owned by the host; timeout, abort, output-limit, and spill failures remove unpublished spill files. Hosts should delete published `metadata.fullOutputPath` files after use.
 
-Network-free adversarial evaluation fixtures live in `src/__tests__/eval-fixtures.test.ts` and reuse `@arnilo/prism-evals` for CI thresholds. See `examples/coding-browser-evaluation.ts` and `docs/evaluations.md`.
+Network-free adversarial evaluation fixtures live in `src/__tests__/eval-fixtures.test.ts` and reuse `@arnilo/prism-evals` for CI thresholds. See `examples/coding-browser-evaluation.ts`, `examples/coding-tools-capability-gaps.ts`, and `docs/evaluations.md`.
 
 ## License
 

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;