@kortyx/hooks 0.27.0 → 0.28.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.28.1](https://github.com/kortyx-io/kortyx/compare/hooks-v0.28.0...hooks-v0.28.1) (2026-09-21)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/core bumped to 0.10.1
+    * @kortyx/providers bumped to 0.8.2
+    * @kortyx/telemetry-contracts bumped to 0.11.1
+
+## [0.28.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.27.0...hooks-v0.28.0) (2026-09-21)
+
+
+### Features
+
+* **hooks:** add model-driven interrupt contracts to useReason ([#224](https://github.com/kortyx-io/kortyx/issues/224)) ([e0147d5](https://github.com/kortyx-io/kortyx/commit/e0147d5234ca38d450d452af924b242f8cbdeb16))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/core bumped to 0.10.0
+    * @kortyx/providers bumped to 0.8.1
+    * @kortyx/telemetry-contracts bumped to 0.11.0
+
 ## [0.27.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.26.0...hooks-v0.27.0) (2026-09-21)
 
 

package/README.md

@@ -27,9 +27,16 @@ npm install @kortyx/hooks
 - `useRuntimeContext(...)` for request context made available to node execution.
 - `useNodeState(...)` / `useWorkflowState(...)` for stateful node logic.
 
-`useReason({ interrupt })` defaults to required interrupt behavior. Use
-`interrupt.mode: "optional"` when the model should decide whether to continue
-with a single model call or pause for user input.
+Define reusable model-driven human-input contracts with
+`defineInterruptContract(...)`, then pass one or more through
+`useReason({ interrupts: { contracts } })`. Contract calls share the ordinary
+tool loop, so tools can run before and after a pause. Use `mode: "optional"`
+when the model may finish without asking, and `maxRequests` to bound sequential
+human turns.
+
+The singular `useReason({ interrupt })` option and `result.interruptResponse`
+are deprecated and will be removed in the next major release. Migrate to
+`interrupts.contracts` and `result.interruptHistory`.
 
 ## Runtime Resume Behavior
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _kortyx_core from '@kortyx/core';
-import { WorkflowDefinition, TokenUsage, InterruptInput, GraphState, NodeConfig, InterruptResult } from '@kortyx/core';
+import { WorkflowDefinition, TokenUsage, InterruptInput, GraphState, NodeConfig, InterruptResumeValue, InterruptResult } from '@kortyx/core';
 import { K as KortyxTelemetryConfig, R as ReasonTraceAdapter, a as KortyxTraceMetadata, b as ReportErrorOptions, c as KortyxTelemetryEventType } from './tracing-BsxYlgEw.js';
 export { E as EnsureWorkflowTopologyRequest, d as EnsureWorkflowTopologyResponse, e as KortyxErrorDetails, f as KortyxTelemetryContentCapture, g as KortyxTelemetryCorrelation, h as KortyxTelemetryEvent, i as KortyxTelemetryPrompt, j as KortyxTelemetryReporter, k as KortyxTelemetryService, l as KortyxTraceAdapter, m as KortyxTraceErrorProjection, n as ReasonTraceAttributes, o as ReasonTraceSpan, p as ReasonTraceSpanEndArgs, q as ReasonTraceSpanStartArgs } from './tracing-BsxYlgEw.js';
 import { FailureDescriptor, KortyxError } from '@kortyx/core/errors';
@@ -95,7 +95,7 @@ type HookNodeRuntimeContext = {
     };
     config: NodeConfig;
     emit: (event: string, payload: unknown) => void;
-    awaitInterrupt: (args: InterruptInput) => InterruptResult;
+    awaitInterrupt: (args: InterruptInput) => InterruptResumeValue;
     callWorkflow?: WorkflowCallService;
     workflowCallTelemetry?: KortyxTelemetryConfig | undefined;
 };
@@ -120,6 +120,30 @@ type SchemaLike<T> = {
         };
     };
 };
+type InterruptContract<TRequest = unknown, TResponse = unknown> = {
+    /** Human-readable guidance included in the model-visible control tool. */
+    description: string;
+    requestSchema: SchemaLike<TRequest>;
+    responseSchema: SchemaLike<TResponse>;
+    /** Stable UI contract identifier. */
+    schemaId: string;
+    /** Version of the UI contract payload. */
+    schemaVersion: string;
+};
+type InterruptContractMap = Record<string, InterruptContract<unknown, unknown>>;
+type UseReasonInterruptsConfig<TContracts extends InterruptContractMap = InterruptContractMap> = {
+    mode?: "required" | "optional" | undefined;
+    /** Maximum number of model-requested human interactions for this operation. */
+    maxRequests?: number | undefined;
+    contracts: TContracts;
+};
+type InterruptHistoryEntry<TContracts extends InterruptContractMap = InterruptContractMap> = {
+    [TName in Extract<keyof TContracts, string>]: TContracts[TName] extends InterruptContract<infer TRequest, infer TResponse> ? {
+        contract: TName;
+        request: TRequest;
+        response: TResponse;
+    } : never;
+}[Extract<keyof TContracts, string>];
 type StructuredPath = string;
 type UseReasonStructuredFieldMode = "append" | "text-delta" | "set";
 type UseReasonStructuredFieldKey = string;
@@ -171,6 +195,10 @@ type UseReasonStructuredConfig = {
      */
     fields?: UseReasonStructuredFields | undefined;
 };
+/**
+ * @deprecated Use `UseReasonInterruptsConfig` and `defineInterruptContract`.
+ * Removed in the next major release.
+ */
 type UseReasonInterruptConfig<TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult> = {
     mode?: "required" | "optional" | undefined;
     requestSchema: SchemaLike<TRequest>;
@@ -183,7 +211,7 @@ type UseReasonToolExecution = {
     approval?: boolean | Record<string, boolean> | undefined;
     emit?: boolean | Record<string, boolean> | undefined;
 };
-type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult> = {
+type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap> = {
     model: ProviderModelRef;
     input: string;
     system?: string | undefined;
@@ -200,7 +228,9 @@ type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = Interrup
     telemetry?: KortyxTraceMetadata | undefined;
     outputSchema?: SchemaLike<TOutput> | undefined;
     structured?: UseReasonStructuredConfig | undefined;
+    /** @deprecated Use `interrupts`. Removed in the next major release. */
     interrupt?: UseReasonInterruptConfig<TRequest, TResponse> | undefined;
+    interrupts?: UseReasonInterruptsConfig<TContracts> | undefined;
     tools?: KortyxExecutableTool[] | undefined;
     toolExecution?: UseReasonToolExecution | undefined;
 };
@@ -215,7 +245,7 @@ type UseReasonStep = {
     providerMetadata?: KortyxProviderMetadata | undefined;
     warnings?: KortyxWarning[] | undefined;
 };
-type UseReasonResult<TOutput = unknown, TResponse = InterruptResult> = {
+type UseReasonResult<TOutput = unknown, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap> = {
     id?: string;
     opId: string;
     text: string;
@@ -225,7 +255,9 @@ type UseReasonResult<TOutput = unknown, TResponse = InterruptResult> = {
     providerMetadata?: KortyxProviderMetadata;
     warnings?: KortyxWarning[];
     output?: TOutput;
+    /** @deprecated Use `interruptHistory`. Removed in the next major release. */
     interruptResponse?: TResponse;
+    interruptHistory?: InterruptHistoryEntry<TContracts>[];
     toolCalls?: KortyxToolCall[];
     toolResults?: KortyxToolResult[];
     steps?: UseReasonStep[];
@@ -239,10 +271,19 @@ type UseInterruptArgs<TRequest extends InterruptInput = InterruptInput, TRespons
     id?: string | undefined;
     meta?: Record<string, unknown> | undefined;
 };
+type UseContractInterruptArgs<TRequest, TResponse> = {
+    contract: InterruptContract<TRequest, TResponse>;
+    request: TRequest;
+    id?: string | undefined;
+    meta?: Record<string, unknown> | undefined;
+};
+
+declare const defineInterruptContract: <TRequest, TResponse>(contract: InterruptContract<TRequest, TResponse>) => InterruptContract<TRequest, TResponse>;
 
 type StateSetter<T> = (next: T | ((prev: T) => T)) => void;
 declare function useStructuredData<TData = unknown>(args: UseStructuredDataArgs<TData>): void;
-declare function useReason<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult>(args: UseReasonArgs<TOutput, TRequest, TResponse>): Promise<UseReasonResult<TOutput, TResponse>>;
+declare function useReason<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap>(args: UseReasonArgs<TOutput, TRequest, TResponse, TContracts>): Promise<UseReasonResult<TOutput, TResponse, TContracts>>;
+declare function useInterrupt<TRequest, TResponse>(args: UseContractInterruptArgs<TRequest, TResponse>): Promise<TResponse>;
 declare function useInterrupt<TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult>(args: UseInterruptArgs<TRequest, TResponse>): Promise<TResponse>;
 /** Live execution signal for cooperative I/O. Never store it in workflow state. */
 declare function useAbortSignal(): AbortSignal | undefined;
@@ -264,4 +305,4 @@ declare function useTool<T extends KortyxExecutableTool>(args: UseToolArgs<T>):
 /** Best effort lifecycle facts. Engine snapshots and interrupt tokens never leave the runtime. */
 declare function emitWorkflowCall(telemetry: KortyxTelemetryConfig | undefined, type: KortyxTelemetryEventType, payload: Record<string, unknown>): void;
 
-export { type CompleteResponseOptions, type HookRuntimeContext, KortyxTelemetryConfig, KortyxTelemetryEventType, KortyxTraceMetadata, ParallelError, ReasonTraceAdapter, ReportErrorOptions, type UseInterruptArgs, type UseReasonArgs, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, type UseToolArgs, WorkflowCallError, type WorkflowCallOutcome, type WorkflowCallService, completeResponse, createWorkflowHooks, emitWorkflowCall, parallel, reportError, runWithHookContext, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useTool, useWorkflow, useWorkflowState, workflowCallFingerprint };
+export { type CompleteResponseOptions, type HookRuntimeContext, type InterruptContract, type InterruptContractMap, type InterruptHistoryEntry, KortyxTelemetryConfig, KortyxTelemetryEventType, KortyxTraceMetadata, ParallelError, ReasonTraceAdapter, ReportErrorOptions, type UseContractInterruptArgs, type UseInterruptArgs, type UseReasonArgs, type UseReasonInterruptConfig, type UseReasonInterruptsConfig, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, type UseToolArgs, WorkflowCallError, type WorkflowCallOutcome, type WorkflowCallService, completeResponse, createWorkflowHooks, defineInterruptContract, emitWorkflowCall, parallel, reportError, runWithHookContext, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useTool, useWorkflow, useWorkflowState, workflowCallFingerprint };

package/dist/index.js

@@ -23,6 +23,7 @@ __export(index_exports, {
   WorkflowCallError: () => WorkflowCallError,
   completeResponse: () => completeResponse,
   createWorkflowHooks: () => createWorkflowHooks,
+  defineInterruptContract: () => defineInterruptContract,
   emitWorkflowCall: () => emitWorkflowCall,
   parallel: () => parallel,
   reportError: () => reportError,
@@ -349,6 +350,97 @@ var awaitInterruptInternal = (args) => {
   return Promise.resolve(response);
 };
 
+// src/interrupt-contract.ts
+var CONTROL_TOOL_PREFIX = "kortyx_request_input__";
+var LEGACY_CONTRACT_NAME = "default";
+var legacyWarningEmitted = false;
+var legacyConfigs = /* @__PURE__ */ new WeakSet();
+var defineInterruptContract = (contract) => {
+  if (!contract || typeof contract !== "object")
+    throw new Error("defineInterruptContract requires a contract object.");
+  for (const [field, value] of [
+    ["description", contract.description],
+    ["schemaId", contract.schemaId],
+    ["schemaVersion", contract.schemaVersion]
+  ])
+    if (typeof value !== "string" || value.trim().length === 0)
+      throw new Error(
+        `Interrupt contract ${field} must be a non-empty string.`
+      );
+  if (typeof contract.requestSchema?.safeParse !== "function")
+    throw new Error(
+      "Interrupt contract requestSchema must provide safeParse(value)."
+    );
+  if (typeof contract.responseSchema?.safeParse !== "function")
+    throw new Error(
+      "Interrupt contract responseSchema must provide safeParse(value)."
+    );
+  return contract;
+};
+var interruptControlToolName = (name) => `${CONTROL_TOOL_PREFIX}${name}`;
+var isInterruptControlToolName = (name) => name.startsWith(CONTROL_TOOL_PREFIX);
+var assertInterruptContractName = (name) => {
+  if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name))
+    throw new Error(
+      `Invalid useReason interrupt contract name "${name}". Use letters, numbers, underscores, or hyphens, starting with a letter.`
+    );
+  if (interruptControlToolName(name).length > 64)
+    throw new Error(
+      `useReason interrupt contract name "${name}" is too long for a provider tool name.`
+    );
+};
+var warnLegacyUseReasonInterrupt = () => {
+  if (legacyWarningEmitted) return;
+  legacyWarningEmitted = true;
+  process.emitWarning(
+    "useReason({ interrupt }) is deprecated and will be removed in the next major release. Define an interrupt contract with defineInterruptContract() and pass it through useReason({ interrupts: { contracts } }). See docs/internal/next-major-removals.md.",
+    {
+      code: "KORTYX_USE_REASON_INTERRUPT_DEPRECATED",
+      type: "DeprecationWarning"
+    }
+  );
+};
+var normalizeReasonInterrupts = (args) => {
+  if (args.interrupt && args.interrupts)
+    throw new Error(
+      "useReason cannot receive both deprecated `interrupt` and `interrupts`. Migrate the legacy configuration to an interrupt contract."
+    );
+  if (args.interrupts) {
+    for (const [name, contract] of Object.entries(args.interrupts.contracts)) {
+      assertInterruptContractName(name);
+      defineInterruptContract(contract);
+    }
+    if (Object.keys(args.interrupts.contracts).length === 0)
+      throw new Error("useReason interrupts.contracts cannot be empty.");
+    if (args.interrupts.maxRequests !== void 0 && (!Number.isInteger(args.interrupts.maxRequests) || args.interrupts.maxRequests < 1))
+      throw new Error("useReason interrupts.maxRequests must be at least 1.");
+    return args.interrupts;
+  }
+  if (!args.interrupt) return void 0;
+  warnLegacyUseReasonInterrupt();
+  const normalized = {
+    mode: args.interrupt.mode,
+    maxRequests: 1,
+    contracts: {
+      [LEGACY_CONTRACT_NAME]: {
+        description: "Ask the user for the additional information required to complete this request.",
+        requestSchema: args.interrupt.requestSchema,
+        responseSchema: args.interrupt.responseSchema ?? {
+          safeParse: (value) => ({
+            success: true,
+            data: value
+          })
+        },
+        schemaId: args.interrupt.schemaId ?? "kortyx.legacy-interrupt",
+        schemaVersion: args.interrupt.schemaVersion ?? "1"
+      }
+    }
+  };
+  legacyConfigs.add(normalized);
+  return normalized;
+};
+var isLegacyInterruptContracts = (config) => Boolean(config && legacyConfigs.has(config));
+
 // src/reason/use-reason.ts
 var import_core6 = require("@kortyx/core");
 
@@ -2362,6 +2454,7 @@ var emitReasonStructuredOutput = (args) => {
 // src/reason/tools.ts
 var import_core5 = require("@kortyx/core");
 var import_errors6 = require("@kortyx/core/errors");
+var import_zod4 = require("zod");
 var toToolDefinitions = (tools2) => tools2.map((tool) => ({
   name: tool.name,
   ...tool.title ? { title: tool.title } : {},
@@ -2397,7 +2490,12 @@ var normalizeToolResult = (toolCall, value) => {
   };
 };
 var createInitialMessages = (args) => [
-  ...typeof args.system === "string" && args.system.length > 0 ? [{ role: "system", content: args.system }] : [],
+  ...typeof args.system === "string" || args.interruptInstructions ? [
+    {
+      role: "system",
+      content: [args.system, args.interruptInstructions].filter((value) => Boolean(value)).join("\n\n")
+    }
+  ] : [],
   { role: "user", content: String(args.input ?? "") }
 ];
 var runReasonToolLoop = async (args) => {
@@ -2412,19 +2510,23 @@ var runReasonToolLoop = async (args) => {
   const checkpoint = saved?.status === "tool_loop" ? saved : void 0;
   const opId = checkpoint?.opId ?? args.opId;
   const tools2 = useReasonArgs.tools ?? [];
+  const interruptConfig = normalizeReasonInterrupts({
+    interrupt: useReasonArgs.interrupt,
+    interrupts: useReasonArgs.interrupts
+  });
+  const interruptByToolName = /* @__PURE__ */ new Map();
   const toolByName = /* @__PURE__ */ new Map();
   let separateOutput = false;
   for (const tool of tools2) {
+    if (isInterruptControlToolName(tool.name))
+      throw new Error(
+        `useReason tool name "${tool.name}" uses the reserved interrupt control-tool namespace.`
+      );
     if (toolByName.has(tool.name)) {
       throw new Error(`useReason received duplicate tool name "${tool.name}".`);
     }
     toolByName.set(tool.name, tool);
   }
-  if (useReasonArgs.interrupt) {
-    throw new Error(
-      "useReason tools cannot be combined with useReason interrupt mode yet. Use toolExecution.approval for tool approval."
-    );
-  }
   separateOutput = Boolean(
     useReasonArgs.model.provider.getModel(useReasonArgs.model.modelId, {
       ...useReasonArgs.model.options,
@@ -2436,21 +2538,63 @@ var runReasonToolLoop = async (args) => {
       ) ?? {}
     }).requiresSeparateStructuredOutput
   );
-  const toolDefinitions = toToolDefinitions(tools2);
+  const interruptDefinitions = [];
+  for (const [name, contract] of Object.entries(
+    interruptConfig?.contracts ?? {}
+  )) {
+    const toolName = interruptControlToolName(name);
+    if (toolByName.has(toolName))
+      throw new Error(
+        `useReason tool name "${toolName}" is reserved for interrupt contracts.`
+      );
+    let inputSchema;
+    try {
+      inputSchema = (0, import_zod4.toJSONSchema)(contract.requestSchema);
+    } catch (error) {
+      throw new Error(
+        `useReason interrupt contract "${name}" requestSchema must support JSON Schema conversion.`,
+        { cause: error }
+      );
+    }
+    interruptByToolName.set(toolName, { name, contract });
+    interruptDefinitions.push({
+      name: toolName,
+      title: `Request human input: ${name}`,
+      description: [
+        contract.description,
+        "Call this only when human input is needed. Execution pauses until the validated response is returned as this tool's result."
+      ].join(" "),
+      inputSchema,
+      metadata: {
+        kortyxControl: "interrupt",
+        contract: name,
+        schemaId: contract.schemaId,
+        schemaVersion: contract.schemaVersion
+      }
+    });
+  }
+  const toolDefinitions = [
+    ...toToolDefinitions(tools2),
+    ...interruptDefinitions
+  ];
   let finalizing = checkpoint?.finalizing ?? false;
   let completed = false;
   const maxSteps = Math.max(1, useReasonArgs.toolExecution?.maxSteps ?? 3);
   const messages = checkpoint?.messages ?? createInitialMessages({
     system: useReasonArgs.system,
-    input: useReasonArgs.outputSchema ? withOutputGuardrails(useReasonArgs.input, useReasonArgs.outputSchema) : useReasonArgs.input
+    input: useReasonArgs.outputSchema ? withOutputGuardrails(useReasonArgs.input, useReasonArgs.outputSchema) : useReasonArgs.input,
+    ...interruptConfig ? {
+      interruptInstructions: [
+        "Human-input rules:",
+        "- The kortyx_request_input__* tools pause this reasoning operation and return the validated human response as a normal tool result.",
+        "- Call at most one human-input tool in a model turn, and do not combine it with other tool calls in that turn.",
+        interruptConfig.mode === "required" ? "- You must call at least one human-input tool before returning the final answer." : "- Human input is optional; call a human-input tool only when the request cannot be completed safely without it."
+      ].join("\n")
+    } : {}
   });
   const steps = checkpoint?.steps ?? [];
-  const allToolCalls = steps.flatMap(
-    (step) => step.toolCalls
-  );
-  const allToolResults = steps.flatMap(
-    (step) => step.toolResults
-  );
+  const allToolCalls = steps.flatMap((step) => step.toolCalls).filter((call) => !interruptByToolName.has(call.name));
+  const allToolResults = steps.flatMap((step) => step.toolResults).filter((result) => !interruptByToolName.has(result.name));
   let finalText = "";
   let finalRaw;
   let finalOutput;
@@ -2466,6 +2610,7 @@ var runReasonToolLoop = async (args) => {
   );
   let pending = checkpoint?.pending;
   const approvedCalls = checkpoint?.approvedCalls ?? [];
+  const interruptHistory = checkpoint?.interruptHistory ?? [];
   const save = () => {
     ctx.currentNodeState.byKey[checkpointKey] = {
       status: "tool_loop",
@@ -2473,6 +2618,7 @@ var runReasonToolLoop = async (args) => {
       messages,
       steps,
       approvedCalls,
+      interruptHistory,
       finalizing,
       ...pending ? { pending } : {}
     };
@@ -2551,6 +2697,10 @@ var runReasonToolLoop = async (args) => {
           ...step.warnings ? { warnings: step.warnings } : {}
         });
       if (toolCalls.length === 0) {
+        if (interruptConfig?.mode === "required" && interruptHistory.length === 0)
+          throw new Error(
+            "useReason interrupts.mode is required, but the model returned a final answer without requesting human input."
+          );
         if (separateOutput && !finalizing) {
           if (args.allowValidatedToolOutput && useReasonArgs.outputSchema) {
             try {
@@ -2595,7 +2745,9 @@ var runReasonToolLoop = async (args) => {
           "Provider requested a tool during schema-only finalization."
         );
       if (!reused) {
-        allToolCalls.push(...toolCalls);
+        allToolCalls.push(
+          ...toolCalls.filter((call) => !interruptByToolName.has(call.name))
+        );
         messages.push({
           role: "assistant",
           content: step.text,
@@ -2605,6 +2757,84 @@ var runReasonToolLoop = async (args) => {
       }
       pending = step;
       save();
+      const interruptCalls = toolCalls.filter(
+        (call) => interruptByToolName.has(call.name)
+      );
+      if (interruptCalls.length > 0) {
+        if (toolCalls.length !== 1)
+          throw new Error(
+            "A useReason interrupt contract call must be the only tool call in its model turn."
+          );
+        const interruptCall = interruptCalls[0];
+        if (!interruptCall)
+          throw new Error("Missing useReason interrupt control call.");
+        if (interruptHistory.length >= (interruptConfig?.maxRequests ?? 1))
+          throw new Error(
+            `useReason reached interrupts.maxRequests (${interruptConfig?.maxRequests ?? 1}).`
+          );
+        const resolved = interruptByToolName.get(interruptCall.name);
+        if (!resolved)
+          throw new Error(
+            `Unknown useReason interrupt contract tool "${interruptCall.name}".`
+          );
+        if (toolResults.some((result3) => result3.toolCallId === interruptCall.id)) {
+          pending = void 0;
+          save();
+          continue;
+        }
+        const request = parseWithSchema(
+          resolved.contract.requestSchema,
+          interruptCall.input,
+          `useReason interrupt contract "${resolved.name}" request`
+        );
+        traceSpan?.addEvent?.("useReason.interrupt.requested", {
+          checkpointKey,
+          contract: resolved.name,
+          interruptIndex: interruptHistory.length
+        });
+        const question = request && typeof request === "object" && !Array.isArray(request) && typeof request.question === "string" ? String(request.question) : void 0;
+        const response = await awaitInterruptInternal({
+          request: {
+            kind: "custom",
+            request,
+            contract: resolved.name,
+            ...question ? { question } : {},
+            schemaId: resolved.contract.schemaId,
+            schemaVersion: resolved.contract.schemaVersion
+          },
+          responseSchema: resolved.contract.responseSchema,
+          id: `${id ?? "reason"}:${resolved.name}:${interruptHistory.length + 1}`,
+          meta: {
+            __kortyxReason: {
+              opId,
+              stepIndex,
+              interruptIndex: interruptHistory.length,
+              contract: resolved.name
+            }
+          }
+        });
+        const result2 = normalizeToolResult(interruptCall, response);
+        toolResults.push(result2);
+        messages.push({
+          role: "tool",
+          content: result2.content,
+          toolCallId: result2.toolCallId,
+          name: result2.name
+        });
+        interruptHistory.push({
+          contract: resolved.name,
+          request,
+          response
+        });
+        traceSpan?.addEvent?.("useReason.interrupt.resolved", {
+          checkpointKey,
+          contract: resolved.name,
+          interruptIndex: interruptHistory.length - 1
+        });
+        pending = void 0;
+        save();
+        continue;
+      }
       for (const toolCall of toolCalls) {
         if (toolResults.some((result2) => result2.toolCallId === toolCall.id)) {
           await replayToolObservations(
@@ -2814,7 +3044,11 @@ var runReasonToolLoop = async (args) => {
       ...finalOutput !== void 0 ? { output: finalOutput } : {},
       toolCalls: allToolCalls,
       toolResults: allToolResults,
-      steps
+      steps,
+      ...interruptHistory.length > 0 ? { interruptHistory } : {},
+      ...isLegacyInterruptContracts(interruptConfig) && interruptHistory.length > 0 ? {
+        interruptResponse: interruptHistory.at(-1)?.response
+      } : {}
     };
     traceSpan?.end?.({
       ...aggregatedUsage !== void 0 ? { usage: aggregatedUsage } : {},
@@ -2825,7 +3059,8 @@ var runReasonToolLoop = async (args) => {
         textLength: finalText.length,
         toolCallCount: allToolCalls.length,
         toolResultCount: allToolResults.length,
-        toolStepCount: steps.length
+        toolStepCount: steps.length,
+        interruptCount: interruptHistory.length
       },
       telemetry: {
         ...useReasonArgs.telemetry ?? {},
@@ -2855,7 +3090,7 @@ var resolveEffectiveReasoningIncludeThoughts = (args) => args.reasoning?.include
 var resolveEffectiveResponseFormatType = (args) => args.responseFormat?.type ?? args.model.options?.responseFormat?.type;
 var assertReasoningThoughtsCompatibility = (args) => {
   if (!resolveEffectiveReasoningIncludeThoughts(args)) return;
-  const usesStructuredOutput = Boolean(args.outputSchema) || Boolean(args.interrupt) || Boolean(args.structured) || resolveEffectiveResponseFormatType(args) === "json";
+  const usesStructuredOutput = Boolean(args.outputSchema) || Boolean(args.interrupt) || Boolean(args.interrupts) || Boolean(args.structured) || resolveEffectiveResponseFormatType(args) === "json";
   if (!usesStructuredOutput) return;
   throw new Error(
     "useReason does not support reasoning.includeThoughts with structured output, interrupt mode, or JSON responseFormat. Disable includeThoughts for this call."
@@ -2863,6 +3098,10 @@ var assertReasoningThoughtsCompatibility = (args) => {
 };
 async function runReason(args) {
   assertReasoningThoughtsCompatibility(args);
+  const interruptConfig = normalizeReasonInterrupts({
+    interrupt: args.interrupt,
+    interrupts: args.interrupts
+  });
   const ctx = getHookContext();
   const abortSignal = (0, import_core6.combineAbortSignals)(
     ctx.node.abortSignal,
@@ -2877,20 +3116,23 @@ async function runReason(args) {
     args.outputSchema,
     args.responseFormat ?? args.model.options?.responseFormat
   );
+  const usesLegacyNoToolInterrupt = Boolean(
+    args.interrupt && !args.interrupts && !args.tools?.length
+  );
   args = {
     ...args,
     abortSignal,
-    ...!args.interrupt && inferred.responseFormat ? { responseFormat: inferred.responseFormat } : {}
+    ...!usesLegacyNoToolInterrupt && inferred.responseFormat ? { responseFormat: inferred.responseFormat } : {}
   };
   const id = typeof args.id === "string" && args.id.length > 0 ? args.id : void 0;
-  const opId = createRuntimeId2();
+  const provisionalOpId = createRuntimeId2();
   const checkpointKey = resolveReasonCheckpointKey({
     ...id ? { id } : {},
     autoIndex: ctx.reasonCallIndex++
   });
-  const existingCompleted = readReasonCompletedCheckpoint(
-    ctx.currentNodeState.byKey[checkpointKey]
-  );
+  const checkpointValue = ctx.currentNodeState.byKey[checkpointKey];
+  const opId = checkpointValue && typeof checkpointValue === "object" && "status" in checkpointValue && checkpointValue.status === "tool_loop" && "opId" in checkpointValue && typeof checkpointValue.opId === "string" ? checkpointValue.opId : provisionalOpId;
+  const existingCompleted = readReasonCompletedCheckpoint(checkpointValue);
   if (existingCompleted) {
     await replayToolObservations(
       existingCompleted.result.steps?.flatMap(
@@ -2899,9 +3141,7 @@ async function runReason(args) {
     );
     return existingCompleted.result;
   }
-  const existingCheckpoint = readReasonCheckpoint(
-    ctx.currentNodeState.byKey[checkpointKey]
-  );
+  const existingCheckpoint = readReasonCheckpoint(checkpointValue);
   const reasonMeta = typeof id === "string" ? { id, opId } : { opId };
   return withSafeTraceSpan(
     getReasonTraceAdapter(),
@@ -2920,7 +3160,8 @@ async function runReason(args) {
         ...args.telemetry?.prompt?.version !== void 0 ? { promptVersion: args.telemetry.prompt.version } : {},
         ...args.telemetry?.prompt?.type ? { promptType: args.telemetry.prompt.type } : {},
         hasOutputSchema: Boolean(args.outputSchema),
-        hasInterrupt: Boolean(args.interrupt),
+        hasInterrupt: Boolean(interruptConfig),
+        interruptContractCount: Object.keys(interruptConfig?.contracts ?? {}).length,
         hasStructured: Boolean(args.structured),
         hasTools: Boolean(args.tools?.length)
       },
@@ -2930,7 +3171,7 @@ async function runReason(args) {
       }
     },
     async (traceSpan) => {
-      if (args.tools?.length) {
+      if ((args.tools?.length || args.interrupts) && !existingCheckpoint) {
         return runReasonToolLoop({
           useReasonArgs: args,
           allowValidatedToolOutput,
@@ -3199,6 +3440,24 @@ function useReason2(args) {
   return useReason(args);
 }
 function useInterrupt(args) {
+  if ("contract" in args) {
+    const contract = defineInterruptContract(args.contract);
+    return awaitInterruptInternal({
+      request: {
+        kind: "custom",
+        request: parseWithSchema(
+          contract.requestSchema,
+          args.request,
+          "useInterrupt contract request"
+        ),
+        schemaId: contract.schemaId,
+        schemaVersion: contract.schemaVersion,
+        ...args.id ? { id: args.id } : {},
+        ...args.meta ? { meta: args.meta } : {}
+      },
+      responseSchema: contract.responseSchema
+    });
+  }
   return awaitInterruptInternal(args);
 }
 function useAbortSignal() {
@@ -3697,6 +3956,7 @@ async function runWorkflowCall(args, task) {
   WorkflowCallError,
   completeResponse,
   createWorkflowHooks,
+  defineInterruptContract,
   emitWorkflowCall,
   parallel,
   reportError,