@inflexa-ai/harness 0.4.4 → 0.5.0

package/dist/contracts/chat-parts.d.ts

@@ -2,9 +2,10 @@
  * Cortex chat data parts — custom parts emitted via writer.write() / writer.custom()
  * that flow through the chat stream and are rendered by the frontend.
  *
- * 15 part types across four categories:
+ * Categories:
  *   Presentation:    data-presentation (agent-synthesized content),
  *                    data-plan (plan by id), data-file-reference (files by path)
+ *   Approval:        data-ask (a tool's pending user-approval prompt)
  *   Run lifecycle:   run-started, dag-state, run-completed, run-failed, run-synthesis,
  *                    synthesis-progress
  *   Per-step live:   step-activity, step-file-tree
@@ -80,6 +81,23 @@ export interface FileReferencePart {
     title?: string;
     files: FileReferenceEntry[];
 }
+/**
+ * A tool's pending request for an explicit user decision. Re-emitted under the
+ * same `id` when the ask reaches a terminal status, so reconciling readers fold
+ * pending → outcome latest-wins.
+ */
+export interface AskPart {
+    type: "data-ask";
+    /** The ask's ledger uuidv7 id — what a surface passes back to `answer`. */
+    id: string;
+    /** Human-facing headline for the pending approval. */
+    title: string;
+    /** The exact command or operation being approved — what the user sees granted. */
+    command: string;
+    /** Optional additional detail a surface may render. */
+    detail?: string;
+    status: "pending" | "resolved" | "rejected" | "aborted" | "expired";
+}
 export interface RunStartedPart {
     type: "data-run-started";
     runId: string;
@@ -303,4 +321,4 @@ export interface DataPreviewFailedPart {
     /** Optional taxonomy of failure kinds. */
     errorKind?: "render" | "submit" | "build" | "timeout" | "internal";
 }
-export type CortexChatPart = PresentationPart | PlanPart | RunCardPart | FileReferencePart | RunStartedPart | DagStatePart | StepActivityPart | StepFileTreePart | StepOutputPart | StepSummaryPart | StepBlockedPart | RunSynthesisPart | SynthesisProgressPart | RunCompletedPart | RunFailedPart | PreviewPart | DataPreviewFailedPart;
+export type CortexChatPart = PresentationPart | PlanPart | RunCardPart | FileReferencePart | AskPart | RunStartedPart | DagStatePart | StepActivityPart | StepFileTreePart | StepOutputPart | StepSummaryPart | StepBlockedPart | RunSynthesisPart | SynthesisProgressPart | RunCompletedPart | RunFailedPart | PreviewPart | DataPreviewFailedPart;

package/dist/contracts/chat-parts.js

@@ -2,9 +2,10 @@
  * Cortex chat data parts — custom parts emitted via writer.write() / writer.custom()
  * that flow through the chat stream and are rendered by the frontend.
  *
- * 15 part types across four categories:
+ * Categories:
  *   Presentation:    data-presentation (agent-synthesized content),
  *                    data-plan (plan by id), data-file-reference (files by path)
+ *   Approval:        data-ask (a tool's pending user-approval prompt)
  *   Run lifecycle:   run-started, dag-state, run-completed, run-failed, run-synthesis,
  *                    synthesis-progress
  *   Per-step live:   step-activity, step-file-tree

package/dist/contracts/index.d.ts

@@ -1,4 +1,4 @@
-export type { PlanStep, PresentationContent, PresentationPart, PlanPart, RunCardPart, FileReferenceEntry, FileReferencePart, RunStartedPart, StepStatus, DagStepState, DagStatePart, StepPhase, StepActivityPart, FileTreeEntry, StepFileTreePart, StepOutputFile, StepOutputPart, StepSummaryPart, StepBlockedPart, SynthesizedFinding, BiologicalTheme, RunSynthesisPart, SynthesisPhase, SynthesisProgressPart, RunCompletedFinding, RunCompletedPart, RunFailedPart, PreviewPart, DataPreviewFailedPart, CortexChatPart, } from "./chat-parts.js";
+export type { PlanStep, PresentationContent, PresentationPart, PlanPart, RunCardPart, FileReferenceEntry, FileReferencePart, AskPart, RunStartedPart, StepStatus, DagStepState, DagStatePart, StepPhase, StepActivityPart, FileTreeEntry, StepFileTreePart, StepOutputFile, StepOutputPart, StepSummaryPart, StepBlockedPart, SynthesizedFinding, BiologicalTheme, RunSynthesisPart, SynthesisPhase, SynthesisProgressPart, RunCompletedFinding, RunCompletedPart, RunFailedPart, PreviewPart, DataPreviewFailedPart, CortexChatPart, } from "./chat-parts.js";
 export type { EventSource, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, FinishEvent, ChatErrorEvent, CortexChatEvent } from "./chat-events.js";
 export type { TextPart, ToolCallPart, CortexPart, CortexMessage } from "./message.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./part-registry.js";

package/dist/contracts/part-registry.js

@@ -3,6 +3,7 @@ export const PART_REGISTRY = {
     "data-plan": { emitter: "conversation", consumer: "conversation", transient: false, reconciling: false },
     "data-run-card": { emitter: "conversation", consumer: "conversation", transient: false, reconciling: false },
     "data-file-reference": { emitter: "conversation", consumer: "conversation", transient: false, reconciling: false },
+    "data-ask": { emitter: "conversation", consumer: "conversation", transient: false, reconciling: true },
     "data-run-started": { emitter: "workflow", consumer: "sidebar", transient: true, reconciling: false },
     "data-dag-state": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: true },
     "data-step-activity": { emitter: "workflow", consumer: "sidebar", transient: true, reconciling: true },

package/dist/contracts/schemas/chat-parts.d.ts

@@ -103,6 +103,27 @@ export declare const FileReferencePartSchema: z.ZodObject<{
         caption: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+export declare const AskStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    aborted: "aborted";
+    resolved: "resolved";
+    rejected: "rejected";
+    expired: "expired";
+}>;
+export declare const AskPartSchema: z.ZodObject<{
+    type: z.ZodLiteral<"data-ask">;
+    id: z.ZodString;
+    title: z.ZodString;
+    command: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        aborted: "aborted";
+        resolved: "resolved";
+        rejected: "rejected";
+        expired: "expired";
+    }>;
+}, z.core.$strip>;
 export declare const RunStartedPartSchema: z.ZodObject<{
     type: z.ZodLiteral<"data-run-started">;
     runId: z.ZodString;
@@ -478,6 +499,19 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         runId: z.ZodOptional<z.ZodString>;
         caption: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"data-ask">;
+    id: z.ZodString;
+    title: z.ZodString;
+    command: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        aborted: "aborted";
+        resolved: "resolved";
+        rejected: "rejected";
+        expired: "expired";
+    }>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"data-run-started">;
     runId: z.ZodString;

package/dist/contracts/schemas/chat-parts.js

@@ -78,6 +78,16 @@ export const FileReferencePartSchema = z.object({
     title: z.string().optional(),
     files: z.array(FileReferenceEntrySchema).min(1).max(10),
 });
+// ── Ask (user approval) ─────────────────────────────────────────────
+export const AskStatusSchema = z.enum(["pending", "resolved", "rejected", "aborted", "expired"]);
+export const AskPartSchema = z.object({
+    type: z.literal("data-ask"),
+    id: z.string(),
+    title: z.string(),
+    command: z.string(),
+    detail: z.string().optional(),
+    status: AskStatusSchema,
+});
 // ── Run Started ─────────────────────────────────────────────────────
 export const RunStartedPartSchema = z.object({
     type: z.literal("data-run-started"),
@@ -278,6 +288,7 @@ export const CortexChatPartSchema = z.discriminatedUnion("type", [
     PlanPartSchema,
     RunCardPartSchema,
     FileReferencePartSchema,
+    AskPartSchema,
     RunStartedPartSchema,
     DagStatePartSchema,
     StepActivityPartSchema,

package/dist/index.d.ts

@@ -26,6 +26,10 @@ export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 export type { RunLauncher, LaunchOptions, LaunchRunOptions, LaunchOutcome } from "./execution/run-launcher.js";
 export { defineTool, isToolError } from "./tools/define-tool.js";
 export type { Tool, ToolDefinition, ToolContext, ToolError } from "./tools/define-tool.js";
+export { createAskGateway } from "./tools/approval/gateway.js";
+export type { AskGateway, AskGatewayDeps, AskContext, AnswerOutcome, PendingAsk } from "./tools/approval/gateway.js";
+export { UnavailableAsk, AskRejectedError } from "./tools/approval/contract.js";
+export type { Ask, AskRequest, AskReply, AskApproval } from "./tools/approval/contract.js";
 export { runAgent, finalText } from "./loop/run-agent.js";
 export type { RunAgentOptions, RunAgentResult, AgentFinish } from "./loop/run-agent.js";
 export type { AgentDefinition, RunStep, EmitFn, EmitEvent, EventSource } from "./loop/types.js";
@@ -103,7 +107,7 @@ export { queryStepsByRun } from "./state/step-executions.js";
 export type { CortexRunRow, StepExecutionRow, RunStatus } from "./state/schema.js";
 export type { DbError } from "./lib/db-result.js";
 export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifactPathSchema, ReferenceArtifactSchema, ReferenceDataCatalogSchema, ReferenceDatasetSchema, ReferenceSha256Schema, UnknownReferenceDatasetError, referenceArtifactKey, resolveReferenceInstallPlan, } from "./reference-data/catalog.js";
-export type { ReferenceArtifact, ReferenceDataCatalog, ReferenceDataset, ReferenceInstallPlan, ReferenceInstallPlanDataset, } from "./reference-data/catalog.js";
+export type { ReferenceArtifact, ReferenceDataCatalog, ReferenceDataset, ReferenceInstallPlan, ReferenceInstallPlanDataset } from "./reference-data/catalog.js";
 export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt } from "./reference-data/receipt.js";
 export type { ReferenceInstallReceipt, ReferenceReceiptArtifact } from "./reference-data/receipt.js";
 export { queryActiveSandboxes } from "./state/active-sandboxes.js";

package/dist/index.js

@@ -25,6 +25,13 @@ export { UnavailablePreviewPublisher } from "./tools/report/preview-publisher.js
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 // Tool primitive.
 export { defineTool, isToolError } from "./tools/define-tool.js";
+// Seam: tool approval (`ctx.ask`). `createAskGateway` realizes the `Ask` seam
+// over the injected `Pool` and carries the outward `answer`/`pending` API plus
+// the boot-time `sweepExpired`; `UnavailableAsk` is the shipped deny-by-default
+// realization for an unwired or non-interactive host. The `AskRequest`/`AskReply`
+// contract and the `AskRejectedError` denial throw come from the seam contract.
+export { createAskGateway } from "./tools/approval/gateway.js";
+export { UnavailableAsk, AskRejectedError } from "./tools/approval/contract.js";
 // Agent loop.
 export { runAgent, finalText } from "./loop/run-agent.js";
 // `passthroughStep` is the in-process `RunStep`: the host request/chat path runs

package/dist/loop/run-agent.d.ts

@@ -1,9 +1,10 @@
 import { type FinishReason } from "ai";
 import type { AgentSession } from "../auth/types.js";
 import type { AgentChat, PromptCachePolicy } from "../providers/types.js";
+import { type AskApproval, type AskRequest } from "../tools/approval/contract.js";
 import type { AgentDefinition, EmitFn, LoopMessage, RunStep } from "./types.js";
 export interface AgentFinish {
-    readonly reason: FinishReason | "max_iterations";
+    readonly reason: FinishReason | "max_iterations" | "denied";
     readonly cappedOut: boolean;
     readonly truncationRecoveries: number;
 }
@@ -20,6 +21,16 @@ export interface RunAgentOptions {
     readonly provider: AgentChat;
     readonly signal: AbortSignal;
     readonly emit: EmitFn;
+    /**
+     * Per-turn user-approval seam threaded into every tool's `ToolContext` as
+     * `ctx.ask`. A conversation tool calls it to pause for an explicit user
+     * decision; the caller (the turn) wires the realization that surfaces the
+     * prompt and returns the reply. Omitted on non-interactive paths (workflow
+     * contexts, headless embedders): approval then resolves to the shipped
+     * deny-by-default `UnavailableAsk`, so a tool that asks where nothing can
+     * answer is denied rather than left waiting on a surface that never responds.
+     */
+    readonly ask?: (request: AskRequest) => Promise<AskApproval>;
     readonly runStep: RunStep;
     readonly formatStepName?: StepNameFormatter;
     readonly isFatalLoopError?: (err: unknown) => boolean;

package/dist/loop/run-agent.js

@@ -3,6 +3,7 @@ import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
 import { classifyProviderError } from "../providers/errors.js";
 import { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "../providers/prompt-cache.js";
 import { resultStep } from "./run-step.js";
+import { AskRejectedError, UnavailableAsk } from "../tools/approval/contract.js";
 import { isToolError } from "../tools/define-tool.js";
 import { addChatUsage, recordAgentRun } from "./metrics.js";
 const TRUNCATED_PROSE_STEER = "Your previous reply was cut off at the output-token limit; continue concisely, or finish via your terminal tool.";
@@ -31,11 +32,18 @@ export async function runAgent(agent, initial, session, opts) {
             inputSchema: jsonSchema(t.jsonSchema),
         }),
     ]));
+    // Approval resolves once to the caller's seam, or the deny-by-default one
+    // when it wires none: a tool that pauses for a user decision where no
+    // interactive surface is present is denied rather than left waiting on an
+    // answer that cannot come.
+    const unavailableAsk = new UnavailableAsk();
+    const ask = opts.ask ?? ((request) => unavailableAsk.ask(request));
     const toolCtx = (tu) => ({
         session,
         signal,
         emit,
         runStep: (name, fn) => runStep(`${formatStepName.tool(tu.toolName, tu.toolCallId)}:${name}`, fn),
+        ask,
     });
     let iterations = 0;
     let truncationRecoveries = 0;
@@ -44,6 +52,16 @@ export async function runAgent(agent, initial, session, opts) {
     // byte-identical to be read back.
     const providerOptions = promptCacheProviderOptions(opts.promptCache ?? DEFAULT_PROMPT_CACHE);
     const usage = {};
+    // The user said no. A subsequent model call would only let the agent argue
+    // with the decision, or spend a call acknowledging it; the denial tool result
+    // is itself what the surface renders, so the turn ends the moment a denial
+    // lands in a dispatch round — after the concurrent siblings in that same round
+    // have completed and been appended. Mirrors the clean-stop terminal path.
+    const stopOnDenial = async (i) => {
+        await emit({ type: "iteration", source, index: i, final: true });
+        recordAgentRun({ agentId: agent.id, iterations, cappedOut: false, usage });
+        return { messages, finish: { reason: "denied", cappedOut: false, truncationRecoveries } };
+    };
     for (let i = 0; i < agent.maxIterations; i++) {
         iterations = i + 1;
         const request = {
@@ -81,6 +99,8 @@ export async function runAgent(agent, initial, session, opts) {
             }
             results.push(errorResult(trailing, TRUNCATED_TOOL_USE_ERROR));
             messages.push({ role: "tool", content: results });
+            if (hasDenial(results))
+                return stopOnDenial(i);
             continue;
         }
         if (reply.finishReason !== "tool-calls") {
@@ -104,6 +124,8 @@ export async function runAgent(agent, initial, session, opts) {
             });
         }
         messages.push({ role: "tool", content: results });
+        if (hasDenial(results))
+            return stopOnDenial(i);
     }
     // Cache defeater (known; not fixed here). Emptying the tool set changes the
     // very front of the request prefix — tool definitions are cached ahead of
@@ -176,6 +198,8 @@ async function execute(tu, tool, input, ctx, isFatalLoopError) {
     catch (err) {
         if (isFatalLoopError(err))
             throw err;
+        if (isAskRejected(err))
+            return deniedResult(tu, err.feedback);
         return errorResult(tu, toolErrorContent(err));
     }
 }
@@ -206,9 +230,33 @@ function errorResult(toolCall, content) {
         output: { type: "error-text", value: content },
     };
 }
+function isAskRejected(err) {
+    // Name-based fallback recognizes a rejection thrown from a different module
+    // realm, where `instanceof` against this file's class reference would miss it.
+    return err instanceof AskRejectedError || (err instanceof Error && err.name === "AskRejectedError");
+}
+/**
+ * Map a rejected approval to a model-visible `execution-denied` tool result. The
+ * prose is the model's only account of the denial; `isErrorOutput` already
+ * treats `execution-denied` as an error result.
+ */
+function deniedResult(toolCall, feedback) {
+    const reason = feedback === undefined || feedback.length === 0
+        ? "The user rejected this action."
+        : `The user rejected this action with the following feedback: ${feedback}`;
+    return {
+        type: "tool-result",
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output: { type: "execution-denied", reason },
+    };
+}
 function isErrorOutput(result) {
     return result.output.type === "error-text" || result.output.type === "error-json" || result.output.type === "execution-denied";
 }
+function hasDenial(results) {
+    return results.some((r) => r.output.type === "execution-denied");
+}
 export function finalText(messages) {
     const last = messages.at(-1);
     if (last === undefined || last.role !== "assistant")

package/dist/sandbox/docker-client.d.ts

@@ -44,7 +44,12 @@ export interface DockerClientConfig {
     resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** Host lib store; bind-mounted read-only at `/mnt/libs` when set. */
     libStorePath?: string;
-    /** Host ref store; bind-mounted read-only at `/mnt/refs` when set. */
+    /**
+     * Host ref store; bind-mounted read-only at `/mnt/refs`. Embedders pass the
+     * configured store location unconditionally — existence is (re-)checked at each
+     * sandbox creation, so a store installed mid-session is mounted into subsequent
+     * sandboxes without a runtime restart.
+     */
     refStorePath?: string;
     /**
      * Force the container platform (e.g. `linux/amd64`). Set by hosts that mount

package/dist/sandbox/docker-client.js

@@ -28,7 +28,7 @@
  * Either way the workload ends as uid 1000 with `no-new-privileges` and no
  * effective capabilities.
  */
-import { existsSync, statSync } from "node:fs";
+import { existsSync, lstatSync, statSync } from "node:fs";
 import { join } from "node:path";
 import Docker from "dockerode";
 import { ResultAsync, err, ok } from "neverthrow";
@@ -80,6 +80,30 @@ function libStoreUsable(libStorePath) {
     }
     return existsSync(join(current, "packages.txt")) && existsSync(join(current, "meta.json"));
 }
+/**
+ * Whether `refStorePath` is, right now, a real directory fit to be a bind authority.
+ * Deliberately shallow — it checks existence-as-a-directory only, never the store's
+ * interior: the harness knows nothing of the ref store's layout, and dataset
+ * completeness/receipts are the embedder's concern, so (unlike `libStoreUsable`, which
+ * validates harness-known `current` layout) there is nothing here to validate beyond
+ * "a directory is present."
+ *
+ * `lstatSync` (not `statSync`) does NOT follow symlinks, so a symlinked path is rejected
+ * even when it resolves to a directory: the bind authority must itself be the store
+ * directory, not an indirection that may later point elsewhere.
+ *
+ * Binding a missing source makes Docker auto-create a root-owned directory at the path —
+ * the same hazard `libStoreUsable` documents — which would also brick the embedder's
+ * later store install (its store tool cannot write into a root-owned dir).
+ */
+function refStoreUsable(refStorePath) {
+    try {
+        return lstatSync(refStorePath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 async function pollHealth(fetchImpl, url, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     let lastErr;
@@ -187,9 +211,16 @@ export function createDockerSandboxOps(config) {
                 if (config.libStorePath && !libsMounted) {
                     logger.warn("lib store configured but `current` is missing or incomplete at sandbox creation — mounting no library store (sandbox degrades to available:false)", { libStorePath: config.libStorePath, sandboxId });
                 }
+                // Re-checked here too, so a ref store installed after boot is mounted into
+                // the next sandbox. Unlike libs, a missing ref store is NOT warned: a missing
+                // lib store is a degradation (it was configured and working, then broke),
+                // whereas a missing ref store is the normal cold state — the user simply has
+                // not installed reference data yet — and warning on every create would be
+                // noise. A store that appears mid-session is picked up by the next create.
+                const refsMounted = !!config.refStorePath && refStoreUsable(config.refStorePath);
                 const plan = buildMountPlan(meta, {
                     libs: libsMounted,
-                    refs: !!config.refStorePath,
+                    refs: refsMounted,
                 });
                 const hostTreePath = config.resolveWorkspaceRoot(meta.analysisId);
                 // `stepWritePrefix` (not a raw `join`) so the RW bind source runs through
@@ -200,7 +231,7 @@ export function createDockerSandboxOps(config) {
                     `${hostTreePath}:${plan.readonlyTreePath}:ro`,
                     ...(plan.writableStepPath ? [`${hostStepPath}:${plan.writableStepPath}:rw`] : []),
                     ...(libsMounted && config.libStorePath ? [`${config.libStorePath}:${plan.libsPath}:ro`] : []),
-                    ...(config.refStorePath ? [`${config.refStorePath}:${plan.refsPath}:ro`] : []),
+                    ...(refsMounted && config.refStorePath ? [`${config.refStorePath}:${plan.refsPath}:ro`] : []),
                 ];
                 const createFailed = (status, cause) => ({
                     type: "container_create_failed",

package/dist/state/init.js

@@ -245,6 +245,45 @@ CREATE TABLE IF NOT EXISTS cortex_working_memory (
   data        JSONB NOT NULL,
   updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
+
+-- Tool-approval ask ledger — the single source of truth for approval state, one
+-- row per ctx.ask invocation. ctx.ask inserts a 'pending' row and polls it to a
+-- terminal status. The outward answer() writes the decision. reply holds the
+-- recorded AskReply (NULL while pending). Analysis-scoped audit of every
+-- approval-gated action, including grant auto-approvals (recorded 'resolved'
+-- with no prompt shown). A pending row a dead process orphans is swept to
+-- 'expired' at boot.
+CREATE TABLE IF NOT EXISTS cortex_asks (
+  id           TEXT PRIMARY KEY,
+  analysis_id  TEXT NOT NULL,
+  thread_id    TEXT,
+  title        TEXT NOT NULL,
+  command      TEXT NOT NULL,
+  detail       TEXT,
+  status       TEXT NOT NULL,
+  reply        JSONB,
+  created_at   TEXT NOT NULL,
+  resolved_at  TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_cortex_asks_analysis
+  ON cortex_asks(analysis_id);
+
+-- Backs the pending() enumeration and the boot sweep. Partial so it stays
+-- compact against the far larger terminal-row mass.
+CREATE INDEX IF NOT EXISTS idx_cortex_asks_pending
+  ON cortex_asks(status) WHERE status = 'pending';
+
+-- Standing approval grants behind an 'always' reply — keyed by the analysis and
+-- the exact command string the user approved, so a later matching ask
+-- auto-approves without pausing. Lives for the analysis lifecycle, surviving
+-- process restarts, and never applies to another analysis.
+CREATE TABLE IF NOT EXISTS cortex_ask_grants (
+  analysis_id  TEXT NOT NULL,
+  command      TEXT NOT NULL,
+  created_at   TEXT NOT NULL,
+  PRIMARY KEY (analysis_id, command)
+);
 `;
 /**
  * Initialize Cortex state tables. Safe to call on every startup and across

package/dist/tools/__fixtures__/tool-context.js

@@ -3,9 +3,11 @@
  * runner ignores it; imported by the tool unit tests.
  */
 import { makeSession } from "../../providers/__fixtures__/session.js";
+import { UnavailableAsk } from "../approval/contract.js";
 /** Build a `ToolContext` for tests; `emit` records into `emitted`. */
 export function makeToolContext(signal) {
     const emitted = [];
+    const deny = new UnavailableAsk();
     const ctx = {
         session: makeSession(),
         signal: signal ?? new AbortController().signal,
@@ -13,6 +15,7 @@ export function makeToolContext(signal) {
             emitted.push(event);
         },
         runStep: (_name, fn) => fn(),
+        ask: (request) => deny.ask(request),
     };
     return { ctx, emitted };
 }

package/dist/tools/approval/contract.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The tool-approval seam contract: the request a conversation tool pauses on,
+ * the decision the user returns, and the deny-by-default realization shipped for
+ * hosts that wire no interactive surface.
+ *
+ * The seam is generic — nothing here names a tool or a domain. A tool describes
+ * the concrete action it needs approved (`AskRequest`); a surface renders it, the
+ * user decides, and the decision comes back as an `AskApproval` on approval or an
+ * `AskRejectedError` throw on denial.
+ *
+ * These are standalone types so `define-tool.ts` can type-import them into
+ * `ToolContext` without an import cycle back through the tools layer.
+ */
+/**
+ * The human-facing content a surface renders to describe the exact action being
+ * approved. `command` is the concrete operation the user sees and approves — what
+ * they saw is precisely what is granted, nothing broader. No tool- or
+ * domain-specific fields: the harness stays agnostic to what is being approved.
+ */
+export interface AskRequest {
+    readonly title: string;
+    readonly command: string;
+    readonly detail?: string;
+}
+/**
+ * A user's decision on an approval request — three distinct outcomes, never a
+ * boolean. `once` approves the single pending invocation; `always` approves it
+ * AND records a standing grant for the matched action; `reject` denies and MAY
+ * carry model-facing feedback.
+ *
+ * This full three-variant union is the wire type the outward `answer` API takes;
+ * `ctx.ask` itself resolves only with the `AskApproval` subset (denial throws).
+ */
+export type AskReply = {
+    readonly kind: "once";
+} | {
+    readonly kind: "always";
+} | {
+    readonly kind: "reject";
+    readonly feedback?: string;
+};
+/**
+ * The subset of `AskReply` `ctx.ask` may resolve with. Denial never returns — it
+ * throws `AskRejectedError` — so a resolved approval is only ever `once` or
+ * `always`, and a caller never has to inspect for a reject variant.
+ */
+export type AskApproval = Exclude<AskReply, {
+    kind: "reject";
+}>;
+/**
+ * The throw a `reject` reply raises out of `ctx.ask`, carrying the optional
+ * model-facing feedback.
+ *
+ * Denial is a throw rather than a returned reject variant so a tool never has to
+ * inspect the reply to learn it was denied: only asks throw, so the throw itself
+ * is the denial signal, and the loop needs no per-tool "was denied" flag — it maps
+ * the caught error to an execution-denied tool result and stops the turn.
+ */
+export declare class AskRejectedError extends Error {
+    readonly feedback?: string;
+    constructor(feedback?: string);
+}
+/**
+ * The user-approval seam. `ask` pauses on an approval request and resolves with
+ * the approval decision, or throws `AskRejectedError` when the user denies.
+ * Realizations are wired by the embedder; an unwired host resolves to
+ * `UnavailableAsk`.
+ */
+export interface Ask {
+    ask(request: AskRequest): Promise<AskApproval>;
+}
+/**
+ * Deny-by-default realization — the shipped `Ask` for hosts that wire no
+ * interactive surface (workflow contexts, headless embedders). Every request is
+ * denied, so a tool that calls `ctx.ask` where nothing can answer is rejected
+ * rather than left waiting on a surface that will never respond.
+ */
+export declare class UnavailableAsk implements Ask {
+    ask(_request: AskRequest): Promise<AskApproval>;
+}

package/dist/tools/approval/contract.js

@@ -0,0 +1,41 @@
+/**
+ * The tool-approval seam contract: the request a conversation tool pauses on,
+ * the decision the user returns, and the deny-by-default realization shipped for
+ * hosts that wire no interactive surface.
+ *
+ * The seam is generic — nothing here names a tool or a domain. A tool describes
+ * the concrete action it needs approved (`AskRequest`); a surface renders it, the
+ * user decides, and the decision comes back as an `AskApproval` on approval or an
+ * `AskRejectedError` throw on denial.
+ *
+ * These are standalone types so `define-tool.ts` can type-import them into
+ * `ToolContext` without an import cycle back through the tools layer.
+ */
+/**
+ * The throw a `reject` reply raises out of `ctx.ask`, carrying the optional
+ * model-facing feedback.
+ *
+ * Denial is a throw rather than a returned reject variant so a tool never has to
+ * inspect the reply to learn it was denied: only asks throw, so the throw itself
+ * is the denial signal, and the loop needs no per-tool "was denied" flag — it maps
+ * the caught error to an execution-denied tool result and stops the turn.
+ */
+export class AskRejectedError extends Error {
+    feedback;
+    constructor(feedback) {
+        super(feedback ? `approval rejected: ${feedback}` : "approval rejected");
+        this.name = "AskRejectedError";
+        this.feedback = feedback;
+    }
+}
+/**
+ * Deny-by-default realization — the shipped `Ask` for hosts that wire no
+ * interactive surface (workflow contexts, headless embedders). Every request is
+ * denied, so a tool that calls `ctx.ask` where nothing can answer is rejected
+ * rather than left waiting on a surface that will never respond.
+ */
+export class UnavailableAsk {
+    async ask(_request) {
+        throw new AskRejectedError("approval is unavailable in this environment");
+    }
+}

package/dist/tools/approval/gateway.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The poll-based tool-approval gateway — the constructed `Ask` seam realization
+ * an embedder wires over its Postgres pool, plus the outward `answer` / `pending`
+ * API it drives and the boot-time `sweepExpired`.
+ *
+ * `ask` is the per-turn seam an embedder binds: a conversation tool's `ctx.ask`
+ * pauses on it. The database is the single source of truth for ask state — `ask`
+ * inserts a `pending` ledger row, emits the `data-ask` part, and polls that row to
+ * a terminal status; there is no in-memory resolver map. `answer` is one guarded
+ * write. See the poll site below for why.
+ */
+import type { Pool } from "pg";
+import type { EmitFn } from "../../loop/types.js";
+import { type AskApproval, type AskReply, type AskRequest } from "./contract.js";
+import { type AnswerOutcome, type PendingAsk } from "./queries.js";
+export type { AnswerOutcome, PendingAsk } from "./queries.js";
+/** Construction deps: the harness application pool the ledger lives in. */
+export interface AskGatewayDeps {
+    readonly pool: Pool;
+}
+/**
+ * Per-turn context an embedder binds into the `Ask` seam. It scopes the ask to an
+ * analysis/thread, carries the turn's abort `signal`, and supplies the `emit` sink
+ * the `data-ask` part flows through.
+ */
+export interface AskContext {
+    readonly analysisId: string;
+    readonly threadId?: string;
+    readonly signal: AbortSignal;
+    readonly emit: EmitFn;
+}
+/** The gateway surface: the per-turn seam plus the outward embedder-driven API. */
+export interface AskGateway {
+    ask(request: AskRequest, ctx: AskContext): Promise<AskApproval>;
+    answer(id: string, reply: AskReply): Promise<AnswerOutcome>;
+    pending(): Promise<PendingAsk[]>;
+    sweepExpired(): Promise<number>;
+}
+export declare function createAskGateway(deps: AskGatewayDeps): AskGateway;

package/dist/tools/approval/gateway.js

@@ -0,0 +1,133 @@
+/**
+ * The poll-based tool-approval gateway — the constructed `Ask` seam realization
+ * an embedder wires over its Postgres pool, plus the outward `answer` / `pending`
+ * API it drives and the boot-time `sweepExpired`.
+ *
+ * `ask` is the per-turn seam an embedder binds: a conversation tool's `ctx.ask`
+ * pauses on it. The database is the single source of truth for ask state — `ask`
+ * inserts a `pending` ledger row, emits the `data-ask` part, and polls that row to
+ * a terminal status; there is no in-memory resolver map. `answer` is one guarded
+ * write. See the poll site below for why.
+ */
+import { unwrapOrThrow } from "../../lib/result.js";
+import { AskRejectedError } from "./contract.js";
+import { answerAsk, insertGrantedAsk, insertPendingAsk, markAborted, selectAskResolution, selectGrant, selectPending, sweepExpired as sweepExpiredRows, } from "./queries.js";
+import { uuidv7 } from "./uuidv7.js";
+/** Fixed poll cadence — imperceptible against human decision speed, low chatter. */
+const POLL_INTERVAL_MS = 200;
+export function createAskGateway(deps) {
+    const { pool } = deps;
+    async function ask(request, ctx) {
+        const id = uuidv7();
+        const now = new Date().toISOString();
+        const row = {
+            id,
+            analysisId: ctx.analysisId,
+            threadId: ctx.threadId ?? null,
+            title: request.title,
+            command: request.command,
+            detail: request.detail ?? null,
+            createdAt: now,
+        };
+        // A standing grant for this exact command short-circuits the prompt: record
+        // the invocation as `resolved` for the audit trail and return without pausing.
+        if (unwrapOrThrow(await selectGrant(pool, ctx.analysisId, request.command))) {
+            unwrapOrThrow(await insertGrantedAsk(pool, row, now));
+            return { kind: "always" };
+        }
+        unwrapOrThrow(await insertPendingAsk(pool, row));
+        await emitAskPart(ctx.emit, id, request, "pending");
+        // DESIGN(WHY): we poll the ask ledger instead of holding an in-memory
+        // resolver map. The DB is the single source of truth, so answering is a pure
+        // UPDATE, a crash-orphaned pending row just ends the poll, and an answer that
+        // arrives in a different process than the loop (a hosted deployment) still
+        // lands. A resolver map would be a second state to reconcile and cannot be
+        // resolved once its process dies. Latency is invisible at human decision speed
+        // and can be erased later with LISTEN/NOTIFY.
+        // TODO(refine): these ask records might move into provenance later.
+        for (;;) {
+            if (ctx.signal.aborted) {
+                unwrapOrThrow(await markAborted(pool, id, new Date().toISOString()));
+                await emitAskPart(ctx.emit, id, request, "aborted");
+                throwAbort(ctx.signal);
+            }
+            const resolution = unwrapOrThrow(await selectAskResolution(pool, id));
+            if (resolution === null) {
+                // The row vanished out from under the poll — nothing can answer it
+                // now, so deny rather than spin forever. Not reachable through the
+                // ordinary status machine (rows are only ever updated, never deleted).
+                await emitAskPart(ctx.emit, id, request, "expired");
+                throw new AskRejectedError("approval request is no longer available");
+            }
+            if (resolution.status !== "pending") {
+                await emitAskPart(ctx.emit, id, request, resolution.status);
+                return settle(resolution.status, resolution.reply, ctx.signal);
+            }
+            await sleepUntil(POLL_INTERVAL_MS, ctx.signal);
+        }
+    }
+    async function answer(id, reply) {
+        return unwrapOrThrow(await answerAsk(pool, id, reply, new Date().toISOString()));
+    }
+    async function pending() {
+        return unwrapOrThrow(await selectPending(pool));
+    }
+    async function sweepExpired() {
+        return unwrapOrThrow(await sweepExpiredRows(pool, new Date().toISOString()));
+    }
+    return { ask, answer, pending, sweepExpired };
+}
+/** Emit (or reconcile, under the same id) the ask's `data-ask` chat part. */
+function emitAskPart(emit, id, request, status) {
+    return emit({
+        type: "data-ask",
+        data: {
+            id,
+            title: request.title,
+            command: request.command,
+            ...(request.detail !== undefined ? { detail: request.detail } : {}),
+            status,
+        },
+    });
+}
+/** Resolve an approval or throw the terminal denial the ledger recorded. */
+function settle(status, reply, signal) {
+    switch (status) {
+        case "resolved":
+            // Only `once` / `always` reach `resolved`; guard the JSONB round-trip and
+            // default to the narrowest approval if a malformed reply ever slipped in.
+            return reply && (reply.kind === "once" || reply.kind === "always") ? reply : { kind: "once" };
+        case "rejected":
+            throw new AskRejectedError(reply && reply.kind === "reject" ? reply.feedback : undefined);
+        case "expired":
+            throw new AskRejectedError("approval request expired unanswered");
+        case "aborted":
+            throwAbort(signal);
+    }
+}
+/**
+ * Re-raise the turn's cancellation verbatim — `signal.reason` IS the loop's own
+ * cancellation, so its existing turn-abort path recognizes it unchanged. The
+ * fallback covers a signal aborted with no explicit reason.
+ */
+function throwAbort(signal) {
+    throw signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+/** Delay `ms`, resolving early if `signal` aborts, leaving no dangling timer. */
+function sleepUntil(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/tools/approval/queries.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Postgres data access for the tool-approval ledger (`cortex_asks`) and its
+ * standing grants (`cortex_ask_grants`).
+ *
+ * Every operation returns `ResultAsync<T, DbError>` in the `state/` house style —
+ * the `pg` throws are caught only inside `tryQuery`/`tryMutation`/`withTransaction`
+ * (`lib/db-result.ts`); everything above flows `Result`. Absence rides the ok
+ * channel (`ok(null)` / `ok(0)`), never an `err`. The gateway unwraps these at its
+ * seam boundary.
+ */
+import { type ResultAsync } from "neverthrow";
+import type { Pool, PoolClient } from "pg";
+import { type DbError } from "../../lib/db-result.js";
+import type { AskReply } from "./contract.js";
+type Querier = Pool | PoolClient;
+/** The ask ledger's status machine — one `pending` state, four terminal ones. */
+export type AskStatus = "pending" | "resolved" | "rejected" | "aborted" | "expired";
+/** The discriminated outcome of an out-of-band `answer` against a ledger row. */
+export type AnswerOutcome = "applied" | "not_found" | "already_terminal";
+/** An unresolved ask, as enumerated by `pending()`. */
+export interface PendingAsk {
+    readonly id: string;
+    readonly analysisId: string;
+    readonly threadId: string | null;
+    readonly title: string;
+    readonly command: string;
+    readonly detail: string | null;
+    readonly createdAt: string;
+}
+/** The status + recorded reply a poll reads to observe a decision. */
+export interface AskResolution {
+    readonly status: AskStatus;
+    readonly reply: AskReply | null;
+}
+/** Column payload shared by the pending insert and the grant short-circuit insert. */
+export interface AskRow {
+    readonly id: string;
+    readonly analysisId: string;
+    readonly threadId: string | null;
+    readonly title: string;
+    readonly command: string;
+    readonly detail: string | null;
+    readonly createdAt: string;
+}
+/** Insert a fresh `pending` ask before its decision is awaited. */
+export declare function insertPendingAsk(querier: Querier, row: AskRow): ResultAsync<void, DbError>;
+/**
+ * Insert an already-`resolved` ask recording an auto-approval a standing grant
+ * short-circuited: no prompt was shown, but the ledger stays a complete audit of
+ * every approval-gated action. The recorded reply is `{ kind: "always" }`.
+ */
+export declare function insertGrantedAsk(querier: Querier, row: AskRow, resolvedAt: string): ResultAsync<void, DbError>;
+/** Does a standing grant cover `(analysisId, command)` in this analysis? */
+export declare function selectGrant(querier: Querier, analysisId: string, command: string): ResultAsync<boolean, DbError>;
+/** Read a row's current status + recorded reply. `null` when no such row exists. */
+export declare function selectAskResolution(querier: Querier, id: string): ResultAsync<AskResolution | null, DbError>;
+/**
+ * Mark a still-`pending` row `aborted`. Guarded by `WHERE status = 'pending'`, so
+ * a row already answered out of band is left untouched.
+ */
+export declare function markAborted(querier: Querier, id: string, resolvedAt: string): ResultAsync<void, DbError>;
+/** Enumerate every unresolved ask, oldest first. */
+export declare function selectPending(querier: Querier): ResultAsync<PendingAsk[], DbError>;
+/** Sweep every `pending` row to `expired`, returning the count swept. */
+export declare function sweepExpired(querier: Querier, expiredAt: string): ResultAsync<number, DbError>;
+/**
+ * Record a decision against a still-`pending` row and, for an `always` reply,
+ * write the standing grant — both in one transaction, so a crash between them can
+ * never record an approval without the grant it promised.
+ *
+ * The guarded `UPDATE ... WHERE status = 'pending'` makes a duplicate/stale answer
+ * a reported no-op: one row updated → `applied`; zero rows → a follow-up read
+ * discriminates `already_terminal` (the row exists but left `pending`) from
+ * `not_found` (no such id).
+ */
+export declare function answerAsk(pool: Pool, id: string, reply: AskReply, now: string): ResultAsync<AnswerOutcome, DbError>;
+export {};

package/dist/tools/approval/queries.js

@@ -0,0 +1,140 @@
+/**
+ * Postgres data access for the tool-approval ledger (`cortex_asks`) and its
+ * standing grants (`cortex_ask_grants`).
+ *
+ * Every operation returns `ResultAsync<T, DbError>` in the `state/` house style —
+ * the `pg` throws are caught only inside `tryQuery`/`tryMutation`/`withTransaction`
+ * (`lib/db-result.ts`); everything above flows `Result`. Absence rides the ok
+ * channel (`ok(null)` / `ok(0)`), never an `err`. The gateway unwraps these at its
+ * seam boundary.
+ */
+import { okAsync } from "neverthrow";
+import { tryMutation, tryQuery, withTransaction } from "../../lib/db-result.js";
+/** Insert a fresh `pending` ask before its decision is awaited. */
+export function insertPendingAsk(querier, row) {
+    return tryMutation("asks.insertPending", async () => {
+        await querier.query({
+            text: `INSERT INTO cortex_asks
+              (id, analysis_id, thread_id, title, command, detail, status, created_at)
+              VALUES ($1, $2, $3, $4, $5, $6, 'pending', $7)`,
+            values: [row.id, row.analysisId, row.threadId, row.title, row.command, row.detail, row.createdAt],
+        });
+    });
+}
+/**
+ * Insert an already-`resolved` ask recording an auto-approval a standing grant
+ * short-circuited: no prompt was shown, but the ledger stays a complete audit of
+ * every approval-gated action. The recorded reply is `{ kind: "always" }`.
+ */
+export function insertGrantedAsk(querier, row, resolvedAt) {
+    return tryMutation("asks.insertGranted", async () => {
+        await querier.query({
+            text: `INSERT INTO cortex_asks
+              (id, analysis_id, thread_id, title, command, detail, status, reply, created_at, resolved_at)
+              VALUES ($1, $2, $3, $4, $5, $6, 'resolved', $7::jsonb, $8, $9)`,
+            values: [row.id, row.analysisId, row.threadId, row.title, row.command, row.detail, JSON.stringify({ kind: "always" }), row.createdAt, resolvedAt],
+        });
+    });
+}
+/** Does a standing grant cover `(analysisId, command)` in this analysis? */
+export function selectGrant(querier, analysisId, command) {
+    return tryQuery("asks.selectGrant", async () => {
+        const result = await querier.query({
+            text: `SELECT 1 FROM cortex_ask_grants WHERE analysis_id = $1 AND command = $2`,
+            values: [analysisId, command],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
+/** Read a row's current status + recorded reply. `null` when no such row exists. */
+export function selectAskResolution(querier, id) {
+    return tryQuery("asks.selectResolution", async () => {
+        const result = await querier.query({
+            text: `SELECT status, reply FROM cortex_asks WHERE id = $1`,
+            values: [id],
+        });
+        const row = result.rows[0];
+        if (!row)
+            return null;
+        return { status: row.status, reply: row.reply ?? null };
+    });
+}
+/**
+ * Mark a still-`pending` row `aborted`. Guarded by `WHERE status = 'pending'`, so
+ * a row already answered out of band is left untouched.
+ */
+export function markAborted(querier, id, resolvedAt) {
+    return tryMutation("asks.markAborted", async () => {
+        await querier.query({
+            text: `UPDATE cortex_asks SET status = 'aborted', resolved_at = $2 WHERE id = $1 AND status = 'pending'`,
+            values: [id, resolvedAt],
+        });
+    });
+}
+/** Enumerate every unresolved ask, oldest first. */
+export function selectPending(querier) {
+    return tryQuery("asks.selectPending", async () => {
+        const result = await querier.query({
+            text: `SELECT id, analysis_id, thread_id, title, command, detail, created_at
+              FROM cortex_asks WHERE status = 'pending' ORDER BY created_at ASC`,
+        });
+        return result.rows.map((row) => ({
+            id: row.id,
+            analysisId: row.analysis_id,
+            threadId: row.thread_id ?? null,
+            title: row.title,
+            command: row.command,
+            detail: row.detail ?? null,
+            createdAt: row.created_at,
+        }));
+    });
+}
+/** Sweep every `pending` row to `expired`, returning the count swept. */
+export function sweepExpired(querier, expiredAt) {
+    return tryMutation("asks.sweepExpired", async () => {
+        const result = await querier.query({
+            text: `UPDATE cortex_asks SET status = 'expired', resolved_at = $1 WHERE status = 'pending'`,
+            values: [expiredAt],
+        });
+        return result.rowCount ?? 0;
+    });
+}
+/**
+ * Record a decision against a still-`pending` row and, for an `always` reply,
+ * write the standing grant — both in one transaction, so a crash between them can
+ * never record an approval without the grant it promised.
+ *
+ * The guarded `UPDATE ... WHERE status = 'pending'` makes a duplicate/stale answer
+ * a reported no-op: one row updated → `applied`; zero rows → a follow-up read
+ * discriminates `already_terminal` (the row exists but left `pending`) from
+ * `not_found` (no such id).
+ */
+export function answerAsk(pool, id, reply, now) {
+    const status = reply.kind === "reject" ? "rejected" : "resolved";
+    return withTransaction(pool, "asks.answer", (client) => tryMutation("asks.answer:update", () => client.query({
+        text: `UPDATE cortex_asks SET status = $1, reply = $2::jsonb, resolved_at = $3
+                  WHERE id = $4 AND status = 'pending'
+                  RETURNING analysis_id, command`,
+        values: [status, JSON.stringify(reply), now, id],
+    })).andThen((updated) => {
+        if ((updated.rowCount ?? 0) === 0)
+            return discriminateMiss(client, id);
+        if (reply.kind !== "always")
+            return okAsync("applied");
+        const granted = updated.rows[0];
+        return tryMutation("asks.answer:grant", async () => {
+            await client.query({
+                text: `INSERT INTO cortex_ask_grants (analysis_id, command, created_at)
+                      VALUES ($1, $2, $3) ON CONFLICT (analysis_id, command) DO NOTHING`,
+                values: [granted.analysis_id, granted.command, now],
+            });
+        }).map(() => "applied");
+    }));
+}
+/** A zero-row `UPDATE` means the id is absent or already terminal — tell them apart. */
+function discriminateMiss(client, id) {
+    return tryQuery("asks.answer:discriminate", async () => {
+        const result = await client.query({ text: `SELECT 1 FROM cortex_asks WHERE id = $1`, values: [id] });
+        return (result.rowCount ?? 0) > 0 ? "already_terminal" : "not_found";
+    });
+}

package/dist/tools/approval/uuidv7.d.ts

@@ -0,0 +1,14 @@
+/**
+ * UUIDv7 generator for the ask ledger id.
+ *
+ * The package pins no uuidv7 dependency and Node's `crypto.randomUUID` mints
+ * only v4, so a small self-contained helper covers the one call site that needs
+ * a time-ordered id: `cortex_asks.id`. v7's leading 48-bit millisecond timestamp
+ * makes ledger ids monotonically sortable, so a `created_at`-ordered scan and the
+ * id order agree without a second sort key.
+ */
+/**
+ * Mint a RFC 9562 UUIDv7 — 48-bit big-endian unix-millis prefix, version/variant
+ * nibbles patched over otherwise-random bytes.
+ */
+export declare function uuidv7(): string;

package/dist/tools/approval/uuidv7.js

@@ -0,0 +1,25 @@
+/**
+ * UUIDv7 generator for the ask ledger id.
+ *
+ * The package pins no uuidv7 dependency and Node's `crypto.randomUUID` mints
+ * only v4, so a small self-contained helper covers the one call site that needs
+ * a time-ordered id: `cortex_asks.id`. v7's leading 48-bit millisecond timestamp
+ * makes ledger ids monotonically sortable, so a `created_at`-ordered scan and the
+ * id order agree without a second sort key.
+ */
+import { randomBytes } from "node:crypto";
+/**
+ * Mint a RFC 9562 UUIDv7 — 48-bit big-endian unix-millis prefix, version/variant
+ * nibbles patched over otherwise-random bytes.
+ */
+export function uuidv7() {
+    const bytes = randomBytes(16);
+    // 48-bit timestamp occupies the first six bytes, big-endian. Date.now() fits
+    // in 48 bits well past the year 10000, so writeUIntBE never overflows.
+    bytes.writeUIntBE(Date.now(), 0, 6);
+    // Version 7 in the high nibble of byte 6; variant 0b10 in the top bits of byte 8.
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/dist/tools/define-tool.d.ts

@@ -7,8 +7,9 @@
  * `defineTool(...)`; a dependency-bearing tool is a factory closure that
  * captures its deps and calls `defineTool`.
  *
- * `ToolContext` carries exactly the four request-scoped values every tool
- * may need — no pool, no sandbox, no logger. The error contract: an expected
+ * `ToolContext` carries only request-scoped values every tool may need
+ * (`session`, `signal`, `emit`, `runStep`, `ask`) — no pool, no sandbox, no
+ * logger. The error contract: an expected
  * outcome ("not found", "no results") stays in the ok channel as a data
  * variant (`ok({ found: false })`); an unexpected failure is an `err(ToolError)`
  * or a throw. The loop (`dispatchTool`) owns the `is_error` envelope — it maps
@@ -18,6 +19,7 @@ import type { Result } from "neverthrow";
 import { z } from "zod";
 import type { AgentSession } from "../auth/types.js";
 import type { EmitFn, RunStep } from "../loop/types.js";
+import type { AskApproval, AskRequest } from "./approval/contract.js";
 export type { EmitFn };
 /**
  * The error channel of a tool's `Result`. `error` is the message surfaced to
@@ -37,9 +39,9 @@ export type ToolExecutionMode = "step" | "workflow" | "inline";
 export declare function isToolError(value: unknown): value is ToolError;
 /**
  * The request-scoped values passed to every tool's `execute`. No injected
- * dependencies (see the harness-durable-runtime spec) — `session`, `signal`, `emit`, plus the `runStep`
- * durability seam (`passthroughStep` in chat, `DBOS.runStep` in workflows)
- * a tool uses to wrap its own durable work.
+ * dependencies (see the harness-durable-runtime spec) — `session`, `signal`, `emit`, the `runStep`
+ * durability seam (`passthroughStep` in chat, `DBOS.runStep` in workflows) a
+ * tool uses to wrap its own durable work, and the `ask` user-approval seam.
  */
 export interface ToolContext {
     readonly session: AgentSession;
@@ -50,6 +52,14 @@ export interface ToolContext {
      * under the tool's own step name, so a tool just passes a short local label.
      */
     readonly runStep: RunStep;
+    /**
+     * Pause for an explicit user decision on a concrete action. Resolves with the
+     * approval (`once`/`always`) or throws `AskRejectedError` on denial. Resolves
+     * to a deny-by-default realization when the embedder wires none, so a tool
+     * that calls it in a non-interactive context is denied rather than left
+     * waiting on a surface that cannot answer.
+     */
+    readonly ask: (request: AskRequest) => Promise<AskApproval>;
 }
 /**
  * A packaged tool: identity, the Zod input contract, the emitted AI SDK input

package/dist/tools/define-tool.js

@@ -7,8 +7,9 @@
  * `defineTool(...)`; a dependency-bearing tool is a factory closure that
  * captures its deps and calls `defineTool`.
  *
- * `ToolContext` carries exactly the four request-scoped values every tool
- * may need — no pool, no sandbox, no logger. The error contract: an expected
+ * `ToolContext` carries only request-scoped values every tool may need
+ * (`session`, `signal`, `emit`, `runStep`, `ask`) — no pool, no sandbox, no
+ * logger. The error contract: an expected
  * outcome ("not found", "no results") stays in the ok channel as a data
  * variant (`ok({ found: false })`); an unexpected failure is an `err(ToolError)`
  * or a throw. The loop (`dispatchTool`) owns the `is_error` envelope — it maps

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.4.4",
+    "version": "0.5.0",
     "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",