zeitlich 0.2.48 → 0.2.50

package/dist/{types-DwBYd0ij.d.ts → types-DZnUqCAP.d.cts}

@@ -1,838 +1,861 @@
-import { ActivityFunctionWithOptions, QueryDefinition, ChildWorkflowOptions, ActivityInterfaceFor } from '@temporalio/workflow';
+import { QueryDefinition, ActivityFunctionWithOptions, ChildWorkflowOptions, ActivityInterfaceFor } from '@temporalio/workflow';
 import { UpdateDefinition } from '@temporalio/common/lib/interfaces';
 import { z } from 'zod';
-import { g as SandboxSnapshot, c as SandboxFileSystem, F as FileStat, D as DirentEntry, a as SandboxCreateOptions, S as SandboxOps, h as SandboxCapability } from './types-CJ7tCdl6.js';
+import { d as SandboxFileSystem, F as FileStat, D as DirentEntry, g as SandboxSnapshot, f as SandboxCreateOptions, c as SandboxOps, h as SandboxCapability } from './types-D8W5TnSa.cjs';
 
 /**
- * A tool definition with a name, description, and Zod schema for arguments.
- * Does not include a handler - use ToolWithHandler for tools with handlers.
+ * JSON primitive types that Temporal can serialize
  */
-interface ToolDefinition<TName extends string = string, TSchema extends z.ZodType = z.ZodType> {
-    name: TName;
-    description: string;
-    schema: TSchema;
-    strict?: boolean;
-    max_uses?: number;
-}
+type JsonPrimitive = string | number | boolean | null | undefined;
 /**
- * A tool definition with an integrated handler function.
- * This is the primary type for defining tools in the router.
+ * JSON-serializable value (recursive type for Temporal compatibility)
  */
-interface ToolWithHandler<TName extends string = string, TSchema extends z.ZodType = z.ZodType, TResult = unknown, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> {
-    name: TName;
-    description: string;
-    schema: TSchema;
-    handler: ToolHandler<z.infer<TSchema>, TResult, TContext, TToolResponse>;
-    strict?: boolean;
-    max_uses?: number;
-    /** Whether this tool is available to the agent (default: true). Disabled tools are excluded from definitions and rejected at parse time. */
-    enabled?: boolean | (() => boolean);
-    /** Per-tool lifecycle hooks (run in addition to global hooks) */
-    hooks?: ToolHooks<z.infer<TSchema>, TResult>;
-}
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
 /**
- * A map of tool keys to tool definitions with handlers.
+ * Type constraint ensuring T only contains JSON-serializable values.
+ * Use this for custom state to ensure Temporal workflow compatibility.
  *
- * Handler uses `any` intentionally — this is a type-system boundary where heterogeneous
- * tool types are stored together. Type safety for individual tools is enforced by
- * `defineTool()` at the definition site and generic inference utilities like
- * `InferToolResults<T>` at the consumption site.
+ * Allows: primitives, arrays, plain objects, and JsonValue
+ * Rejects: functions, symbols, undefined, class instances with methods
  */
-type ToolMap = Record<string, {
-    name: string;
-    description: string | (() => string);
-    schema: z.ZodType | (() => z.ZodType);
-    handler: ToolHandler<any, any, any, any>;
-    strict?: boolean;
-    max_uses?: number;
-    enabled?: boolean | (() => boolean);
-    hooks?: ToolHooks<any, any>;
-}>;
+type JsonSerializable<T> = {
+    [K in keyof T]: T[K] extends JsonValue ? T[K] : T[K] extends JsonPrimitive ? T[K] : T[K] extends (infer U)[] ? U extends JsonValue ? T[K] : JsonSerializable<U>[] : T[K] extends object ? JsonSerializable<T[K]> : never;
+};
 /**
- * Extract the tool names from a tool map (uses the tool's name property, not the key).
+ * Full state type combining base state with custom state
  */
-type ToolNames<T extends ToolMap> = T[keyof T]["name"];
+type AgentState<TCustom extends JsonSerializable<TCustom>> = BaseAgentState & TCustom;
 /**
- * A raw tool call as received from the LLM before parsing.
+ * The slice of agent state that is persisted alongside the thread in the
+ * thread store (e.g. Redis) so that a workflow can terminate, store its
+ * state, and be continued or forked later with that state rehydrated.
+ *
+ * Only fields that make sense to carry across workflow runs belong here.
+ * Runtime bookkeeping like status, version, turns, tools, fileTree, token
+ * counters, and the system prompt is intentionally NOT persisted — each run
+ * rebuilds those from scratch.
  */
-interface RawToolCall {
-    id?: string;
-    name: string;
-    args: unknown;
+interface PersistedThreadState {
+    /** Task map serialized as entries so it round-trips through JSON. */
+    tasks: [string, WorkflowTask][];
+    /** All custom state fields declared by the caller. */
+    custom: Record<string, JsonValue>;
 }
 /**
- * A parsed tool call with validated arguments for a specific tool.
+ * Agent state manager interface
+ * Note: Temporal handlers must be set up in the workflow file due to
+ * Temporal's workflow isolation requirements. This manager provides
+ * the state and helpers needed for those handlers.
  */
-interface ParsedToolCall<TName extends string = string, TArgs = unknown> {
-    id: string;
-    name: TName;
-    args: TArgs;
+interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
+    /** Typed query definition registered for this agent's state */
+    readonly stateQuery: QueryDefinition<AgentState<TCustom>>;
+    /** Typed update definition registered for waiting on this agent's state change */
+    readonly stateChangeUpdate: UpdateDefinition<AgentState<TCustom>, [number]>;
+    /** Get current status */
+    getStatus(): AgentStatus;
+    /** Check if agent is running */
+    isRunning(): boolean;
+    /** Check if agent is in terminal state */
+    isTerminal(): boolean;
+    /** Get current state version */
+    getVersion(): number;
+    /** Set status to RUNNING */
+    run(): void;
+    /** Set status to WAITING_FOR_INPUT */
+    waitForInput(): void;
+    /** Set status to COMPLETED */
+    complete(): void;
+    /** Set status to FAILED */
+    fail(): void;
+    /** Set status to CANCELLED */
+    cancel(): void;
+    /** Increment state version (call after state changes) */
+    incrementVersion(): void;
+    /** Increment turns (call after each turn) */
+    incrementTurns(): void;
+    /** Get current turns */
+    getTurns(): number;
+    /** Get the system prompt */
+    getSystemPrompt(): unknown;
+    /** Set the system prompt */
+    setSystemPrompt(newSystemPrompt: unknown): void;
+    /** Get a custom state value by key */
+    get<K extends keyof TCustom>(key: K): TCustom[K];
+    /** Set a custom state value by key */
+    set<K extends keyof TCustom>(key: K, value: TCustom[K]): void;
+    /** Bulk-merge a partial update into custom state */
+    mergeUpdate(update: Partial<AgentState<TCustom>>): void;
+    /** Get full state for query handler */
+    getCurrentState(): AgentState<TCustom>;
+    /** Check if should return from waitForStateChange */
+    shouldReturnFromWait(lastKnownVersion: number): boolean;
+    /** Get all tasks */
+    getTasks(): WorkflowTask[];
+    /** Get a task by ID */
+    getTask(id: string): WorkflowTask | undefined;
+    /** Add or update a task */
+    setTask(task: WorkflowTask): void;
+    /** Delete a task by ID */
+    deleteTask(id: string): boolean;
+    /** Set the tools (converts Zod schemas to JSON Schema for serialization) */
+    setTools(newTools: ToolDefinition[]): void;
+    /**
+     * Snapshot the fields that should survive across workflow runs
+     * (tasks + all custom state). Safe to pass directly to
+     * {@link ThreadOps.saveThreadState}. Rehydrate on the next run with
+     * `mergeUpdate({ tasks: new Map(slice.tasks), ...slice.custom })`.
+     */
+    getPersistedSlice(): PersistedThreadState;
+    /** Update the usage */
+    updateUsage(usage: TokenUsage): void;
+    /** Get the total usage */
+    getTotalUsage(): {
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        totalCachedWriteTokens: number;
+        totalCachedReadTokens: number;
+        totalReasonTokens: number;
+        turns: number;
+    };
 }
+
 /**
- * Union type of all possible parsed tool calls from a tool map.
- */
-type ParsedToolCallUnion<T extends ToolMap> = {
-    [K in keyof T]: ParsedToolCall<T[K]["name"], z.infer<T[K]["schema"]>>;
-}[keyof T];
-/**
- * Function signature for appending tool results to a thread.
- */
-type AppendToolResultFn = ActivityFunctionWithOptions<(id: string, config: ToolResultConfig) => Promise<void>>;
-/**
- * The response from a tool handler.
- * Contains the content for the tool message and the result to return from processToolCalls.
+ * Ephemeral virtual filesystem backed by a {@link FileResolver}.
  *
- * Tools that don't return additional data should use `data: null` (TResult defaults to null).
- * Tools that may fail to produce data should type TResult as `SomeType | null`.
+ * Created fresh for each tool invocation from the current workflow file tree.
+ * Directory structure is inferred from file paths. All mutations are tracked
+ * and can be retrieved via {@link getMutations} after the handler completes.
  */
-interface ToolHandlerResponse<TResult = null, TToolResponse = JsonValue> {
-    /** Content sent back to the LLM as the tool call response */
-    toolResponse: TToolResponse;
-    /** Data returned to the workflow and hooks for further processing */
-    data: TResult;
-    /**
-     * When true, the tool result has already been appended to the thread
-     * by the handler itself (e.g. via `withAutoAppend`), so the router
-     * will skip the `appendToolResult` call. This avoids sending large
-     * payloads through Temporal's activity payload limit.
-     */
-    resultAppended?: boolean;
+declare class VirtualFileSystem<TCtx = unknown, TMeta = FileEntryMetadata> implements SandboxFileSystem {
+    private resolver;
+    private ctx;
+    readonly workspaceBase: string;
+    private entries;
+    private directories;
+    private mutations;
+    private inlineFiles;
+    constructor(tree: FileEntry<TMeta>[], resolver: FileResolver<TCtx, TMeta>, ctx: TCtx, workspaceBase?: string, inlineFiles?: Record<string, string>);
+    /** Return all mutations accumulated during this invocation. */
+    getMutations(): TreeMutation<TMeta>[];
+    /** Look up a file entry by virtual path. */
+    getEntry(path: string): FileEntry<TMeta> | undefined;
+    readFile(path: string): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
     /**
-     * When true, the session will rewind: any in-flight parallel tool
-     * calls are cancelled and the LLM call is retried. The session reuses
-     * the same `assistantMessageId` for the retry; the next `runAgent`
-     * activity truncates the thread from that id on entry, wiping the
-     * triggering assistant message and any tool results already appended
-     * before re-invoking the LLM.
-     *
-     * The `toolResponse` for a rewinding tool call is ignored (never
-     * appended) since the thread is rewound back to the pre-assistant
-     * state on the next invocation.
+     * Resolve the string content for an entry, preferring inline content
+     * carried on the entry itself before consulting the resolver. Used by
+     * `readFile`, `appendFile`, and `cp` so all read paths agree on the
+     * lookup precedence.
      */
-    rewind?: boolean;
-    /** Token usage from the tool execution (e.g. child agent invocations) */
-    usage?: TokenUsage;
-    /** Thread ID used by the handler (surfaced to the LLM for subagent thread continuation) */
-    threadId?: string;
-    /** Sandbox ID created or used by the handler (e.g. child agent sandbox) */
-    sandboxId?: string;
-    /** Snapshot captured on exit when `sandboxShutdown === "snapshot"`. */
-    snapshot?: SandboxSnapshot;
-    /** Snapshot captured immediately after sandbox seeding (before the agent loop starts) when `sandbox.mode === "new"` and `sandboxShutdown === "snapshot"`. Intended as a reusable "base" for new threads that want to skip re-seeding. */
-    baseSnapshot?: SandboxSnapshot;
-    /** Unvalidated metadata passthrough from handler to hooks (e.g. infrastructure state) */
-    metadata?: Record<string, unknown>;
+    private readEntryContent;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    appendFile(path: string, content: string | Uint8Array): Promise<void>;
+    mkdir(_path: string, _options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    cp(src: string, dest: string, _options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    readlink(_path: string): Promise<string>;
+    resolvePath(base: string, path: string): string;
+    private addParentDirectories;
 }
-/**
- * Base context the router always injects into every handler invocation.
- * Handlers can rely on these fields being present without casting.
- */
-interface RouterContext {
-    threadId: string;
-    /** Redis key suffix for thread storage. Defaults to 'messages'. */
-    threadKey?: string;
-    toolCallId: string;
-    toolName: string;
-    sandboxId?: string;
+
+/** Allowed value types for file-entry metadata. */
+type FileEntryMetadata = Record<string, string | number | boolean | null>;
+/** JSON-serializable metadata for a single file in the virtual tree. */
+interface FileEntry<TMeta = FileEntryMetadata> {
+    id: string;
+    /** Virtual path, e.g. "/src/index.ts" */
+    path: string;
+    size: number;
+    /** ISO-8601 date string (JSON-safe) */
+    mtime: string;
+    metadata: TMeta;
     /**
-     * Id of the assistant message that issued this tool call (the message
-     * the session passed as `assistantMessageId` into `runAgent`). Present
-     * for any tool call processed through `processToolCalls` from a
-     * session; may be absent when the router is driven manually (e.g.
-     * tests, custom orchestrators).
+     * Optional inline content carried directly on the entry. When present the
+     * {@link VirtualFileSystem} returns this string from `readFile` /
+     * `readFileBuffer` (and uses it as the source for `cp` / `appendFile`)
+     * without consulting the resolver.
      *
-     * Subagent handlers that fork the parent's thread mid-call use this
-     * to truncate the orphan trailing assistant message from the forked
-     * thread so the child's first model call sees a well-formed history.
+     * Use this for files that exist purely in workflow state and have no
+     * backing in the consumer's data layer (e.g. skill resources bundled at
+     * session creation time). Because the content travels with the entry,
+     * any tool handler that constructs a `VirtualFileSystem` from `fileTree`
+     * sees the same content — no separate `inlineFiles` plumbing required.
+     *
+     * Read-only: entries with `inlineContent` reject in-place mutations
+     * (`writeFile`, `appendFile`, `rm`, `mv` of the entry, `cp` over the
+     * entry as destination). The resolver has no contract for the synthetic
+     * `id` these entries carry, so attempting a mutation throws an `EROFS`
+     * error instead of silently routing a doomed call through the resolver.
      */
-    assistantMessageId?: string;
+    inlineContent?: string;
 }
 /**
- * A handler function for a specific tool.
- * Receives the parsed args and a context that always includes {@link RouterContext}
- * fields, plus any additional properties when TContext extends RouterContext.
+ * Flat list of file entries.
+ * Directories are inferred from file paths at runtime.
  */
-type ToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> = (args: TArgs, context: TContext) => ToolHandlerResponse<TResult, TToolResponse> | Promise<ToolHandlerResponse<TResult, TToolResponse>>;
+type VirtualFileTree<TMeta = FileEntryMetadata> = FileEntry<TMeta>[];
+type TreeMutation<TMeta = FileEntryMetadata> = {
+    type: "add";
+    entry: FileEntry<TMeta>;
+} | {
+    type: "remove";
+    path: string;
+} | {
+    type: "update";
+    path: string;
+    entry: Partial<FileEntry<TMeta>>;
+};
 /**
- * Activity-compatible tool handler that always returns a Promise.
- * Use this for tool handlers registered as Temporal activities.
+ * Consumer-provided bridge to the existing DB / S3 / CRUD layer.
  *
- * @example
- * ```typescript
- * const readHandler: ActivityToolHandler<
- *   FileReadArgs,
- *   ReadResult,
- *   RouterContext & { scopedNodes: FileNode[]; provider: FileSystemProvider }
- * > = async (args, context) => {
- *   // context.threadId, context.sandboxId etc. are always available
- *   return readHandler(args, context.scopedNodes, context.provider);
- * };
- * ```
- */
-type ActivityToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> = (args: TArgs, context: TContext) => Promise<ToolHandlerResponse<TResult, TToolResponse>>;
-/**
- * Extract the args type for a specific tool name from a tool map.
- */
-type ToolArgs<T extends ToolMap, TName extends ToolNames<T>> = z.infer<Extract<T[keyof T], {
-    name: TName;
-}>["schema"]>;
-/**
- * Extract the result type for a specific tool name from a tool map.
- */
-type ToolResult<T extends ToolMap, TName extends ToolNames<T>> = Extract<T[keyof T], {
-    name: TName;
-}>["handler"] extends ToolHandler<unknown, infer R, RouterContext, any> ? Awaited<R> : never;
-/**
- * The result of processing a tool call.
+ * Generic over `TCtx` so every call receives workflow-level context
+ * (e.g. `{ projectId: string }`) without the resolver holding state.
+ *
+ * Generic over `TMeta` so resolved entries carry typed metadata.
  */
-interface ToolCallResult<TName extends string = string, TResult = unknown> {
-    toolCallId: string;
-    name: TName;
-    data: TResult;
-    usage?: TokenUsage;
-    /** Unvalidated metadata passthrough from handler to hooks (e.g. infrastructure state) */
-    metadata?: Record<string, unknown>;
+interface FileResolver<TCtx = unknown, TMeta = FileEntryMetadata> {
+    resolveEntries(ctx: TCtx): Promise<FileEntry<TMeta>[]>;
+    readFile(id: string, ctx: TCtx, metadata: TMeta): Promise<string>;
+    readFileBuffer(id: string, ctx: TCtx, metadata: TMeta): Promise<Uint8Array>;
+    writeFile(id: string, content: string | Uint8Array, ctx: TCtx, metadata: TMeta): Promise<void>;
+    createFile(path: string, content: string | Uint8Array, ctx: TCtx): Promise<FileEntry<TMeta>>;
+    deleteFile(id: string, ctx: TCtx, metadata: TMeta): Promise<void>;
 }
 /**
- * Infer result types from a tool map based on handler return types.
+ * Workflow-side operations for the virtual filesystem.
+ *
+ * Unlike {@link SandboxOps}, this only exposes what is actually needed:
+ * resolving the initial file tree from the consumer's data layer.
  */
-type InferToolResults<T extends ToolMap> = {
-    [K in keyof T as T[K]["name"]]: T[K]["handler"] extends ToolHandler<any, infer R, any, any> ? Awaited<R> : never;
-};
+interface VirtualFsOps<TCtx = unknown, TMeta = FileEntryMetadata> {
+    resolveFileTree(ctx: TCtx): Promise<{
+        fileTree: FileEntry<TMeta>[];
+    }>;
+}
 /**
- * Union of all possible tool call results based on handler return types.
+ * Maps generic {@link VirtualFsOps} method names to scope-prefixed names.
+ *
+ * @example
+ * ```typescript
+ * type Ops = PrefixedVirtualFsOps<"codingAgent">;
+ * // → { virtualFsCodingAgentResolveFileTree: ... }
+ * ```
  */
-type ToolCallResultUnion<TResults extends Record<string, unknown>> = {
-    [TName in keyof TResults & string]: ToolCallResult<TName, TResults[TName]>;
-}[keyof TResults & string];
+type PrefixedVirtualFsOps<TPrefix extends string, TCtx = unknown, TMeta = FileEntryMetadata> = {
+    [K in keyof VirtualFsOps<TCtx, TMeta> as `virtualFs${Capitalize<TPrefix>}${Capitalize<K & string>}`]: VirtualFsOps<TCtx, TMeta>[K];
+};
 /**
- * Context passed to processToolCalls for hook execution and handler invocation
+ * The portion of workflow `AgentState` that the virtual filesystem reads via
+ * {@link queryParentWorkflowState}. Populated automatically by the session
+ * when `virtualFs` config is provided.
  */
-interface ProcessToolCallsContext {
-    /** Current turn number (for hooks) */
-    turn?: number;
-    /** Active sandbox ID (when a sandbox is configured for this session) */
-    sandboxId?: string;
-    /**
-     * Id of the assistant message that produced these tool calls. The
-     * router forwards it into every handler's {@link RouterContext} so
-     * handlers can reference the message they were issued from (e.g.
-     * subagent forks that need to truncate the orphan assistant message
-     * out of a parent-forked thread).
-     */
-    assistantMessageId?: string;
+interface VirtualFsState<TCtx = unknown, TMeta = FileEntryMetadata> {
+    fileTree: FileEntry<TMeta>[];
+    virtualFsCtx: TCtx;
+    /** In-memory file contents keyed by path, bypassing the resolver (e.g. skill resources). */
+    inlineFiles?: Record<string, string>;
 }
 /**
- * Signal that a tool handler requested a rewind. Attached to the
- * {@link ProcessToolCallsResult} so the session can reuse the same
- * `assistantMessageId` for the retry; the next `runAgent` activity
- * then truncates the thread from that id on entry.
+ * Extended router context injected by {@link withVirtualFs}.
+ * Guarantees a live (ephemeral) virtual filesystem built from the workflow
+ * file tree.
  */
-interface RewindSignal {
-    toolCallId: string;
-    toolName: string;
+interface VirtualFsContext<TCtx = unknown, TMeta = FileEntryMetadata> extends RouterContext {
+    virtualFs: VirtualFileSystem<TCtx, TMeta>;
 }
+
 /**
- * Result returned by {@link ToolRouter.processToolCalls}.
- *
- * The object is a standard array of tool call results for successful
- * tool calls (cancelled or rewinding siblings are omitted), extended
- * with a `rewind` property when any tool in the batch requested a
- * rewind. Using an array-with-property lets existing code that treats
- * the return value as `ToolCallResultUnion[]` continue to work.
+ * Agent execution status
  */
-type ProcessToolCallsResult<TResults extends Record<string, unknown>> = ToolCallResultUnion<TResults>[] & {
-    rewind?: RewindSignal;
-};
+type AgentStatus = "RUNNING" | "WAITING_FOR_INPUT" | "COMPLETED" | "FAILED" | "CANCELLED";
 /**
- * Result from PreToolUse hook - can block or modify execution
+ * Base state that all agents must have
  */
-interface PreToolUseHookResult {
-    /** Skip this tool call entirely */
-    skip?: boolean;
-    /** Modified args to use instead (must match schema) */
-    modifiedArgs?: unknown;
+interface BaseAgentState {
+    tools: SerializableToolDefinition[];
+    status: AgentStatus;
+    version: number;
+    turns: number;
+    tasks: Map<string, WorkflowTask>;
+    fileTree: FileEntry[];
+    /** In-memory file contents keyed by path, bypassing the resolver (e.g. skill resources). */
+    inlineFiles?: Record<string, string>;
+    virtualFsCtx?: unknown;
+    systemPrompt?: unknown;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    cachedWriteTokens: number;
+    cachedReadTokens: number;
 }
 /**
- * Result from PostToolUseFailure hook - can recover from errors
+ * File representation for agent workflows
  */
-interface PostToolUseFailureHookResult {
-    /** Provide a fallback result instead of throwing */
-    fallbackContent?: JsonValue;
-    /** Whether to suppress the error (still logs, but continues) */
-    suppress?: boolean;
+interface AgentFile {
+    /** Database/S3 file ID */
+    id: string;
+    /** Virtual path for agent (e.g., "evidence/invoice.pdf") */
+    path: string;
+    /** Original filename */
+    filename: string;
+    /** Generic description for prompt */
+    description?: string;
+    /** MIME type of the file */
+    mimeType?: string;
+}
+interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedWriteTokens?: number;
+    cachedReadTokens?: number;
+    reasonTokens?: number;
 }
 /**
- * Per-tool lifecycle hooks - defined directly on a tool definition.
- * Runs in addition to global hooks (global pre → tool pre → execute → tool post → global post).
+ * Configuration for a Zeitlich agent
  */
-interface ToolHooks<TArgs = unknown, TResult = unknown> {
-    /** Called before this tool executes - can skip or modify args */
-    onPreToolUse?: (ctx: {
-        args: TArgs;
-        threadId: string;
-        turn: number;
-    }) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
-    /** Called after this tool executes successfully */
-    onPostToolUse?: (ctx: {
-        args: TArgs;
-        result: TResult;
-        threadId: string;
-        turn: number;
-        durationMs: number;
-        metadata?: Record<string, unknown>;
-    }) => void | Promise<void>;
-    /** Called when this tool execution fails */
-    onPostToolUseFailure?: (ctx: {
-        args: TArgs;
-        error: Error;
-        threadId: string;
-        turn: number;
-    }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
+interface AgentConfig {
+    /** The name of the agent, should be unique within the workflows, ideally Pascal Case */
+    agentName: string;
+    /** Description, used for sub agents */
+    description?: string;
 }
 /**
- * Context for PreToolUse hook - called before tool execution
+ * A JSON-serializable tool definition for state storage.
+ * Uses a plain JSON Schema object instead of a live Zod instance,
+ * so it survives Temporal serialization without losing constraints (min, max, etc.).
  */
-interface PreToolUseHookContext<T extends ToolMap> {
-    /** The tool call about to be executed */
-    toolCall: ParsedToolCallUnion<T>;
-    /** Thread identifier */
-    threadId: string;
-    /** Current turn number */
-    turn: number;
+interface SerializableToolDefinition {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+    max_uses?: number;
 }
 /**
- * PreToolUse hook - called before tool execution, can block or modify
+ * Configuration passed to runAgent activity
  */
-type PreToolUseHook<T extends ToolMap> = (ctx: PreToolUseHookContext<T>) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
+interface RunAgentConfig extends AgentConfig {
+    /** The thread ID to use for the session */
+    threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
+    /** Metadata for the session */
+    metadata?: Record<string, unknown>;
+    /**
+     * The id under which the assistant message produced by this call will
+     * be appended. The activity truncates the thread from this id on
+     * entry (no-op on the first attempt) so that:
+     *
+     * - Rewind retries can reuse the same id and the previous (bad)
+     *   assistant + its tool results are wiped before the retry LLM call.
+     * - Resetting the Temporal workflow to this activity restores the
+     *   pre-call thread state: replay re-truncates, re-invokes, and
+     *   appends under the same id.
+     */
+    assistantMessageId: string;
+}
 /**
- * Context for PostToolUse hook - called after successful tool execution
+ * Configuration for appending a tool result
  */
-interface PostToolUseHookContext<T extends ToolMap, TResult = unknown> {
-    /** The tool call that was executed */
-    toolCall: ParsedToolCallUnion<T>;
-    /** The result from the tool handler */
-    result: TResult;
-    /** Thread identifier */
+interface ToolResultConfig {
     threadId: string;
-    /** Current turn number */
-    turn: number;
-    /** Execution duration in milliseconds */
-    durationMs: number;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
+    toolCallId: string;
+    /** The name of the tool that produced this result */
+    toolName: string;
+    /** Content for the tool result — string, object, or array. The adapter converts to its SDK-native format. */
+    content: JsonValue;
 }
 /**
- * PostToolUse hook - called after successful tool execution
+ * Status of a workflow task
  */
-type PostToolUseHook<T extends ToolMap, TResult = unknown> = (ctx: PostToolUseHookContext<T, TResult>) => void | Promise<void>;
+type TaskStatus = "pending" | "in_progress" | "completed";
 /**
- * Context for PostToolUseFailure hook - called when tool execution fails
+ * A task managed within a workflow for tracking work items
  */
-interface PostToolUseFailureHookContext<T extends ToolMap> {
-    /** The tool call that failed */
-    toolCall: ParsedToolCallUnion<T>;
-    /** The error that occurred */
-    error: Error;
-    /** Thread identifier */
-    threadId: string;
-    /** Current turn number */
-    turn: number;
+interface WorkflowTask {
+    /** Unique task identifier */
+    id: string;
+    /** Brief, actionable title in imperative form */
+    subject: string;
+    /** Detailed description of what needs to be done */
+    description: string;
+    /** Present continuous form shown in spinner when in_progress */
+    activeForm: string;
+    /** Current status of the task */
+    status: TaskStatus;
+    /** Arbitrary key-value pairs for tracking */
+    metadata: Record<string, string>;
+    /** IDs of tasks that must complete before this one can start */
+    blockedBy: string[];
+    /** IDs of tasks that are waiting for this one to complete */
+    blocks: string[];
 }
 /**
- * PostToolUseFailure hook - called when tool execution fails
+ * Exit reasons for session termination
  */
-type PostToolUseFailureHook<T extends ToolMap> = (ctx: PostToolUseFailureHookContext<T>) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
+type SessionExitReason = "completed" | "max_turns" | "waiting_for_input" | "failed" | "cancelled";
 /**
- * Tool execution hooks — the subset of hooks consumed by the tool router.
- * Session/message lifecycle hooks live in lib/hooks/types.ts.
+ * Helper to check if status is terminal
  */
-interface ToolRouterHooks<T extends ToolMap, TResult = unknown> {
-    /** Called before each tool execution - can block or modify */
-    onPreToolUse?: PreToolUseHook<T>;
-    /** Called after each successful tool execution */
-    onPostToolUse?: PostToolUseHook<T, TResult>;
-    /** Called when tool execution fails */
-    onPostToolUseFailure?: PostToolUseFailureHook<T>;
-}
+declare function isTerminalStatus(status: AgentStatus): boolean;
+
 /**
- * Options for creating a tool router.
+ * A tool definition with a name, description, and Zod schema for arguments.
+ * Does not include a handler - use ToolWithHandler for tools with handlers.
  */
-interface ToolRouterOptions<T extends ToolMap> {
-    /** Map of tools with their handlers */
-    tools: T;
-    /** Thread ID for appending tool results */
-    threadId: string;
-    /** Redis key suffix for thread storage. Defaults to 'messages'. */
-    threadKey?: string;
-    /** Function to append tool results to the thread (called automatically after each handler).
-     *  Accepts a Temporal activity proxy with {@link ActivityFunctionWithOptions}. */
-    appendToolResult: AppendToolResultFn;
-    /** Whether to process tools in parallel (default: true) */
-    parallel?: boolean;
-    /** Tool execution lifecycle hooks (pre/post tool use) */
-    hooks?: ToolRouterHooks<T, ToolCallResultUnion<InferToolResults<T>>>;
-    /** Additional tools to auto-register (e.g. subagent, skill tools built by register helpers) */
-    plugins?: ToolMap[string][];
+interface ToolDefinition<TName extends string = string, TSchema extends z.ZodType = z.ZodType> {
+    name: TName;
+    description: string;
+    schema: TSchema;
+    strict?: boolean;
+    max_uses?: number;
 }
 /**
- * The tool router interface with full type inference for both args and results.
+ * A tool definition with an integrated handler function.
+ * This is the primary type for defining tools in the router.
  */
-interface ToolRouter<T extends ToolMap> {
-    /** Check if the router has any tools */
-    hasTools(): boolean;
-    /**
-     * Parse and validate a raw tool call against the router's tools.
-     * Returns a typed tool call with validated arguments.
-     */
-    parseToolCall(toolCall: RawToolCall): ParsedToolCallUnion<T>;
-    /**
-     * Check if a tool with the given name exists in the router.
-     */
-    hasTool(name: string): boolean;
-    /**
-     * Get all tool names in the router.
-     */
-    getToolNames(): ToolNames<T>[];
-    /**
-     * Get all tool definitions (without handlers) for passing to LLM.
-     */
-    getToolDefinitions(): ToolDefinition[];
-    /**
-     * Process all tool calls using the registered handlers.
-     * Returns typed results based on handler return types.
-     * @param toolCalls - Array of parsed tool calls to process
-     * @param context - Optional context including turn number for hooks
-     */
-    processToolCalls(toolCalls: ParsedToolCallUnion<T>[], context?: ProcessToolCallsContext): Promise<ProcessToolCallsResult<InferToolResults<T>>>;
-    /**
-     * Process tool calls matching a specific name with a custom handler.
-     * Useful for overriding the default handler for specific cases.
-     */
-    processToolCallsByName<TName extends ToolNames<T>, TResult>(toolCalls: ParsedToolCallUnion<T>[], toolName: TName, handler: ToolHandler<ToolArgs<T, TName>, TResult>, context?: ProcessToolCallsContext): Promise<ToolCallResult<TName, TResult>[]>;
-    /**
-     * Filter tool calls by name.
-     */
-    filterByName<TName extends ToolNames<T>>(toolCalls: ParsedToolCallUnion<T>[], name: TName): ParsedToolCall<TName, ToolArgs<T, TName>>[];
-    /**
-     * Check if any tool call matches the given name.
-     */
-    hasToolCall(toolCalls: ParsedToolCallUnion<T>[], name: ToolNames<T>): boolean;
-    /**
-     * Filter results by tool name.
-     */
-    getResultsByName<TName extends ToolNames<T>>(results: ToolCallResultUnion<InferToolResults<T>>[], name: TName): ToolCallResult<TName, ToolResult<T, TName>>[];
+interface ToolWithHandler<TName extends string = string, TSchema extends z.ZodType = z.ZodType, TResult = unknown, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> {
+    name: TName;
+    description: string;
+    schema: TSchema;
+    handler: ToolHandler<z.infer<TSchema>, TResult, TContext, TToolResponse>;
+    strict?: boolean;
+    max_uses?: number;
+    /** Whether this tool is available to the agent (default: true). Disabled tools are excluded from definitions and rejected at parse time. */
+    enabled?: boolean | (() => boolean);
+    /** Per-tool lifecycle hooks (run in addition to global hooks) */
+    hooks?: ToolHooks<z.infer<TSchema>, TResult>;
 }
-
 /**
- * JSON primitive types that Temporal can serialize
+ * A map of tool keys to tool definitions with handlers.
+ *
+ * Handler uses `any` intentionally — this is a type-system boundary where heterogeneous
+ * tool types are stored together. Type safety for individual tools is enforced by
+ * `defineTool()` at the definition site and generic inference utilities like
+ * `InferToolResults<T>` at the consumption site.
  */
-type JsonPrimitive = string | number | boolean | null | undefined;
+type ToolMap = Record<string, {
+    name: string;
+    description: string | (() => string);
+    schema: z.ZodType | (() => z.ZodType);
+    handler: ToolHandler<any, any, any, any>;
+    strict?: boolean;
+    max_uses?: number;
+    enabled?: boolean | (() => boolean);
+    hooks?: ToolHooks<any, any>;
+}>;
 /**
- * JSON-serializable value (recursive type for Temporal compatibility)
+ * Extract the tool names from a tool map (uses the tool's name property, not the key).
  */
-type JsonValue = JsonPrimitive | JsonValue[] | {
-    [key: string]: JsonValue;
-};
+type ToolNames<T extends ToolMap> = T[keyof T]["name"];
 /**
- * Type constraint ensuring T only contains JSON-serializable values.
- * Use this for custom state to ensure Temporal workflow compatibility.
- *
- * Allows: primitives, arrays, plain objects, and JsonValue
- * Rejects: functions, symbols, undefined, class instances with methods
+ * A raw tool call as received from the LLM before parsing.
  */
-type JsonSerializable<T> = {
-    [K in keyof T]: T[K] extends JsonValue ? T[K] : T[K] extends JsonPrimitive ? T[K] : T[K] extends (infer U)[] ? U extends JsonValue ? T[K] : JsonSerializable<U>[] : T[K] extends object ? JsonSerializable<T[K]> : never;
-};
+interface RawToolCall {
+    id?: string;
+    name: string;
+    args: unknown;
+}
 /**
- * Full state type combining base state with custom state
+ * A parsed tool call with validated arguments for a specific tool.
  */
-type AgentState<TCustom extends JsonSerializable<TCustom>> = BaseAgentState & TCustom;
+interface ParsedToolCall<TName extends string = string, TArgs = unknown> {
+    id: string;
+    name: TName;
+    args: TArgs;
+}
 /**
- * The slice of agent state that is persisted alongside the thread in the
- * thread store (e.g. Redis) so that a workflow can terminate, store its
- * state, and be continued or forked later with that state rehydrated.
- *
- * Only fields that make sense to carry across workflow runs belong here.
- * Runtime bookkeeping like status, version, turns, tools, fileTree, token
- * counters, and the system prompt is intentionally NOT persisted — each run
- * rebuilds those from scratch.
+ * Union type of all possible parsed tool calls from a tool map.
  */
-interface PersistedThreadState {
-    /** Task map serialized as entries so it round-trips through JSON. */
-    tasks: [string, WorkflowTask][];
-    /** All custom state fields declared by the caller. */
-    custom: Record<string, JsonValue>;
-}
+type ParsedToolCallUnion<T extends ToolMap> = {
+    [K in keyof T]: ParsedToolCall<T[K]["name"], z.infer<T[K]["schema"]>>;
+}[keyof T];
 /**
- * Agent state manager interface
- * Note: Temporal handlers must be set up in the workflow file due to
- * Temporal's workflow isolation requirements. This manager provides
- * the state and helpers needed for those handlers.
+ * Function signature for appending tool results to a thread.
  */
-interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
-    /** Typed query definition registered for this agent's state */
-    readonly stateQuery: QueryDefinition<AgentState<TCustom>>;
-    /** Typed update definition registered for waiting on this agent's state change */
-    readonly stateChangeUpdate: UpdateDefinition<AgentState<TCustom>, [number]>;
-    /** Get current status */
-    getStatus(): AgentStatus;
-    /** Check if agent is running */
-    isRunning(): boolean;
-    /** Check if agent is in terminal state */
-    isTerminal(): boolean;
-    /** Get current state version */
-    getVersion(): number;
-    /** Set status to RUNNING */
-    run(): void;
-    /** Set status to WAITING_FOR_INPUT */
-    waitForInput(): void;
-    /** Set status to COMPLETED */
-    complete(): void;
-    /** Set status to FAILED */
-    fail(): void;
-    /** Set status to CANCELLED */
-    cancel(): void;
-    /** Increment state version (call after state changes) */
-    incrementVersion(): void;
-    /** Increment turns (call after each turn) */
-    incrementTurns(): void;
-    /** Get current turns */
-    getTurns(): number;
-    /** Get the system prompt */
-    getSystemPrompt(): unknown;
-    /** Set the system prompt */
-    setSystemPrompt(newSystemPrompt: unknown): void;
-    /** Get a custom state value by key */
-    get<K extends keyof TCustom>(key: K): TCustom[K];
-    /** Set a custom state value by key */
-    set<K extends keyof TCustom>(key: K, value: TCustom[K]): void;
-    /** Bulk-merge a partial update into custom state */
-    mergeUpdate(update: Partial<AgentState<TCustom>>): void;
-    /** Get full state for query handler */
-    getCurrentState(): AgentState<TCustom>;
-    /** Check if should return from waitForStateChange */
-    shouldReturnFromWait(lastKnownVersion: number): boolean;
-    /** Get all tasks */
-    getTasks(): WorkflowTask[];
-    /** Get a task by ID */
-    getTask(id: string): WorkflowTask | undefined;
-    /** Add or update a task */
-    setTask(task: WorkflowTask): void;
-    /** Delete a task by ID */
-    deleteTask(id: string): boolean;
-    /** Set the tools (converts Zod schemas to JSON Schema for serialization) */
-    setTools(newTools: ToolDefinition[]): void;
+type AppendToolResultFn = ActivityFunctionWithOptions<(id: string, config: ToolResultConfig) => Promise<void>>;
+/**
+ * The response from a tool handler.
+ * Contains the content for the tool message and the result to return from processToolCalls.
+ *
+ * Tools that don't return additional data should use `data: null` (TResult defaults to null).
+ * Tools that may fail to produce data should type TResult as `SomeType | null`.
+ */
+interface ToolHandlerResponse<TResult = null, TToolResponse = JsonValue> {
+    /** Content sent back to the LLM as the tool call response */
+    toolResponse: TToolResponse;
+    /** Data returned to the workflow and hooks for further processing */
+    data: TResult;
     /**
-     * Snapshot the fields that should survive across workflow runs
-     * (tasks + all custom state). Safe to pass directly to
-     * {@link ThreadOps.saveThreadState}. Rehydrate on the next run with
-     * `mergeUpdate({ tasks: new Map(slice.tasks), ...slice.custom })`.
+     * When true, the tool result has already been appended to the thread
+     * by the handler itself (e.g. via `withAutoAppend`), so the router
+     * will skip the `appendToolResult` call. This avoids sending large
+     * payloads through Temporal's activity payload limit.
+     */
+    resultAppended?: boolean;
+    /**
+     * When true, the session will rewind: any in-flight parallel tool
+     * calls are cancelled and the LLM call is retried. The session reuses
+     * the same `assistantMessageId` for the retry; the next `runAgent`
+     * activity truncates the thread from that id on entry, wiping the
+     * triggering assistant message and any tool results already appended
+     * before re-invoking the LLM.
+     *
+     * The `toolResponse` for a rewinding tool call is ignored (never
+     * appended) since the thread is rewound back to the pre-assistant
+     * state on the next invocation.
      */
-    getPersistedSlice(): PersistedThreadState;
-    /** Update the usage */
-    updateUsage(usage: TokenUsage): void;
-    /** Get the total usage */
-    getTotalUsage(): {
-        totalInputTokens: number;
-        totalOutputTokens: number;
-        totalCachedWriteTokens: number;
-        totalCachedReadTokens: number;
-        totalReasonTokens: number;
-        turns: number;
-    };
+    rewind?: boolean;
+    /** Token usage from the tool execution (e.g. child agent invocations) */
+    usage?: TokenUsage;
+    /** Thread ID used by the handler (surfaced to the LLM for subagent thread continuation) */
+    threadId?: string;
+    /** Sandbox ID created or used by the handler (e.g. child agent sandbox) */
+    sandboxId?: string;
+    /** Snapshot captured on exit when `sandboxShutdown === "snapshot"`. */
+    snapshot?: SandboxSnapshot;
+    /** Snapshot captured immediately after sandbox seeding (before the agent loop starts) when `sandbox.mode === "new"` and `sandboxShutdown === "snapshot"`. Intended as a reusable "base" for new threads that want to skip re-seeding. */
+    baseSnapshot?: SandboxSnapshot;
+    /** Unvalidated metadata passthrough from handler to hooks (e.g. infrastructure state) */
+    metadata?: Record<string, unknown>;
 }
-
 /**
- * Ephemeral virtual filesystem backed by a {@link FileResolver}.
- *
- * Created fresh for each tool invocation from the current workflow file tree.
- * Directory structure is inferred from file paths. All mutations are tracked
- * and can be retrieved via {@link getMutations} after the handler completes.
+ * Base context the router always injects into every handler invocation.
+ * Handlers can rely on these fields being present without casting.
  */
-declare class VirtualFileSystem<TCtx = unknown, TMeta = FileEntryMetadata> implements SandboxFileSystem {
-    private resolver;
-    private ctx;
-    readonly workspaceBase: string;
-    private entries;
-    private directories;
-    private mutations;
-    private inlineFiles;
-    constructor(tree: FileEntry<TMeta>[], resolver: FileResolver<TCtx, TMeta>, ctx: TCtx, workspaceBase?: string, inlineFiles?: Record<string, string>);
-    /** Return all mutations accumulated during this invocation. */
-    getMutations(): TreeMutation<TMeta>[];
-    /** Look up a file entry by virtual path. */
-    getEntry(path: string): FileEntry<TMeta> | undefined;
-    readFile(path: string): Promise<string>;
-    readFileBuffer(path: string): Promise<Uint8Array>;
+interface RouterContext {
+    threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
+    toolCallId: string;
+    toolName: string;
+    sandboxId?: string;
     /**
-     * Resolve the string content for an entry, preferring inline content
-     * carried on the entry itself before consulting the resolver. Used by
-     * `readFile`, `appendFile`, and `cp` so all read paths agree on the
-     * lookup precedence.
+     * Id of the assistant message that issued this tool call (the message
+     * the session passed as `assistantMessageId` into `runAgent`). Present
+     * for any tool call processed through `processToolCalls` from a
+     * session; may be absent when the router is driven manually (e.g.
+     * tests, custom orchestrators).
+     *
+     * Subagent handlers that fork the parent's thread mid-call use this
+     * to truncate the orphan trailing assistant message from the forked
+     * thread so the child's first model call sees a well-formed history.
      */
-    private readEntryContent;
-    exists(path: string): Promise<boolean>;
-    stat(path: string): Promise<FileStat>;
-    readdir(path: string): Promise<string[]>;
-    readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
-    writeFile(path: string, content: string | Uint8Array): Promise<void>;
-    appendFile(path: string, content: string | Uint8Array): Promise<void>;
-    mkdir(_path: string, _options?: {
-        recursive?: boolean;
-    }): Promise<void>;
-    rm(path: string, options?: {
-        recursive?: boolean;
-        force?: boolean;
-    }): Promise<void>;
-    cp(src: string, dest: string, _options?: {
-        recursive?: boolean;
-    }): Promise<void>;
-    mv(src: string, dest: string): Promise<void>;
-    readlink(_path: string): Promise<string>;
-    resolvePath(base: string, path: string): string;
-    private addParentDirectories;
-}
-
-/** Allowed value types for file-entry metadata. */
-type FileEntryMetadata = Record<string, string | number | boolean | null>;
-/** JSON-serializable metadata for a single file in the virtual tree. */
-interface FileEntry<TMeta = FileEntryMetadata> {
-    id: string;
-    /** Virtual path, e.g. "/src/index.ts" */
-    path: string;
-    size: number;
-    /** ISO-8601 date string (JSON-safe) */
-    mtime: string;
-    metadata: TMeta;
+    assistantMessageId?: string;
     /**
-     * Optional inline content carried directly on the entry. When present the
-     * {@link VirtualFileSystem} returns this string from `readFile` /
-     * `readFileBuffer` (and uses it as the source for `cp` / `appendFile`)
-     * without consulting the resolver.
-     *
-     * Use this for files that exist purely in workflow state and have no
-     * backing in the consumer's data layer (e.g. skill resources bundled at
-     * session creation time). Because the content travels with the entry,
-     * any tool handler that constructs a `VirtualFileSystem` from `fileTree`
-     * sees the same content — no separate `inlineFiles` plumbing required.
+     * Persist the parent session's current `PersistedThreadState` slice
+     * (tasks + custom state) to the durable thread store. Wired up by
+     * the session — absent for manually-driven routers (tests, custom
+     * orchestrators).
      *
-     * Read-only: entries with `inlineContent` reject in-place mutations
-     * (`writeFile`, `appendFile`, `rm`, `mv` of the entry, `cp` over the
-     * entry as destination). The resolver has no contract for the synthetic
-     * `id` these entries carry, so attempting a mutation throws an `EROFS`
-     * error instead of silently routing a doomed call through the resolver.
+     * Subagent handlers invoke this before spawning a child that will
+     * read the parent's thread (`newThreadSource: "from-parent"` or an
+     * explicit parent threadId): the parent's slice otherwise only
+     * lands in storage at session-exit time, so the child would load a
+     * stale (or empty) snapshot. Best-effort — failures are logged by
+     * the session but never thrown.
      */
-    inlineContent?: string;
+    persistThreadState?: () => Promise<void>;
 }
 /**
- * Flat list of file entries.
- * Directories are inferred from file paths at runtime.
+ * A handler function for a specific tool.
+ * Receives the parsed args and a context that always includes {@link RouterContext}
+ * fields, plus any additional properties when TContext extends RouterContext.
  */
-type VirtualFileTree<TMeta = FileEntryMetadata> = FileEntry<TMeta>[];
-type TreeMutation<TMeta = FileEntryMetadata> = {
-    type: "add";
-    entry: FileEntry<TMeta>;
-} | {
-    type: "remove";
-    path: string;
-} | {
-    type: "update";
-    path: string;
-    entry: Partial<FileEntry<TMeta>>;
-};
+type ToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> = (args: TArgs, context: TContext) => ToolHandlerResponse<TResult, TToolResponse> | Promise<ToolHandlerResponse<TResult, TToolResponse>>;
 /**
- * Consumer-provided bridge to the existing DB / S3 / CRUD layer.
- *
- * Generic over `TCtx` so every call receives workflow-level context
- * (e.g. `{ projectId: string }`) without the resolver holding state.
+ * Activity-compatible tool handler that always returns a Promise.
+ * Use this for tool handlers registered as Temporal activities.
  *
- * Generic over `TMeta` so resolved entries carry typed metadata.
+ * @example
+ * ```typescript
+ * const readHandler: ActivityToolHandler<
+ *   FileReadArgs,
+ *   ReadResult,
+ *   RouterContext & { scopedNodes: FileNode[]; provider: FileSystemProvider }
+ * > = async (args, context) => {
+ *   // context.threadId, context.sandboxId etc. are always available
+ *   return readHandler(args, context.scopedNodes, context.provider);
+ * };
+ * ```
  */
-interface FileResolver<TCtx = unknown, TMeta = FileEntryMetadata> {
-    resolveEntries(ctx: TCtx): Promise<FileEntry<TMeta>[]>;
-    readFile(id: string, ctx: TCtx, metadata: TMeta): Promise<string>;
-    readFileBuffer(id: string, ctx: TCtx, metadata: TMeta): Promise<Uint8Array>;
-    writeFile(id: string, content: string | Uint8Array, ctx: TCtx, metadata: TMeta): Promise<void>;
-    createFile(path: string, content: string | Uint8Array, ctx: TCtx): Promise<FileEntry<TMeta>>;
-    deleteFile(id: string, ctx: TCtx, metadata: TMeta): Promise<void>;
-}
+type ActivityToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> = (args: TArgs, context: TContext) => Promise<ToolHandlerResponse<TResult, TToolResponse>>;
 /**
- * Workflow-side operations for the virtual filesystem.
- *
- * Unlike {@link SandboxOps}, this only exposes what is actually needed:
- * resolving the initial file tree from the consumer's data layer.
+ * Extract the args type for a specific tool name from a tool map.
  */
-interface VirtualFsOps<TCtx = unknown, TMeta = FileEntryMetadata> {
-    resolveFileTree(ctx: TCtx): Promise<{
-        fileTree: FileEntry<TMeta>[];
-    }>;
+type ToolArgs<T extends ToolMap, TName extends ToolNames<T>> = z.infer<Extract<T[keyof T], {
+    name: TName;
+}>["schema"]>;
+/**
+ * Extract the result type for a specific tool name from a tool map.
+ */
+type ToolResult<T extends ToolMap, TName extends ToolNames<T>> = Extract<T[keyof T], {
+    name: TName;
+}>["handler"] extends ToolHandler<unknown, infer R, RouterContext, any> ? Awaited<R> : never;
+/**
+ * The result of processing a tool call.
+ */
+interface ToolCallResult<TName extends string = string, TResult = unknown> {
+    toolCallId: string;
+    name: TName;
+    data: TResult;
+    usage?: TokenUsage;
+    /** Unvalidated metadata passthrough from handler to hooks (e.g. infrastructure state) */
+    metadata?: Record<string, unknown>;
 }
 /**
- * Maps generic {@link VirtualFsOps} method names to scope-prefixed names.
- *
- * @example
- * ```typescript
- * type Ops = PrefixedVirtualFsOps<"codingAgent">;
- * // → { virtualFsCodingAgentResolveFileTree: ... }
- * ```
+ * Infer result types from a tool map based on handler return types.
  */
-type PrefixedVirtualFsOps<TPrefix extends string, TCtx = unknown, TMeta = FileEntryMetadata> = {
-    [K in keyof VirtualFsOps<TCtx, TMeta> as `virtualFs${Capitalize<TPrefix>}${Capitalize<K & string>}`]: VirtualFsOps<TCtx, TMeta>[K];
+type InferToolResults<T extends ToolMap> = {
+    [K in keyof T as T[K]["name"]]: T[K]["handler"] extends ToolHandler<any, infer R, any, any> ? Awaited<R> : never;
 };
 /**
- * The portion of workflow `AgentState` that the virtual filesystem reads via
- * {@link queryParentWorkflowState}. Populated automatically by the session
- * when `virtualFs` config is provided.
+ * Union of all possible tool call results based on handler return types.
  */
-interface VirtualFsState<TCtx = unknown, TMeta = FileEntryMetadata> {
-    fileTree: FileEntry<TMeta>[];
-    virtualFsCtx: TCtx;
-    /** In-memory file contents keyed by path, bypassing the resolver (e.g. skill resources). */
-    inlineFiles?: Record<string, string>;
+type ToolCallResultUnion<TResults extends Record<string, unknown>> = {
+    [TName in keyof TResults & string]: ToolCallResult<TName, TResults[TName]>;
+}[keyof TResults & string];
+/**
+ * Context passed to processToolCalls for hook execution and handler invocation
+ */
+interface ProcessToolCallsContext {
+    /** Current turn number (for hooks) */
+    turn?: number;
+    /** Active sandbox ID (when a sandbox is configured for this session) */
+    sandboxId?: string;
+    /**
+     * Id of the assistant message that produced these tool calls. The
+     * router forwards it into every handler's {@link RouterContext} so
+     * handlers can reference the message they were issued from (e.g.
+     * subagent forks that need to truncate the orphan assistant message
+     * out of a parent-forked thread).
+     */
+    assistantMessageId?: string;
+    /**
+     * Optional callback that flushes the session's in-memory
+     * `PersistedThreadState` slice to the durable thread store. The
+     * router forwards it into every handler's {@link RouterContext}
+     * verbatim. The session uses this to let mid-loop tool handlers
+     * (notably subagents that fork or continue the parent's thread)
+     * persist the parent's slice before the child reads it.
+     */
+    persistThreadState?: () => Promise<void>;
 }
 /**
- * Extended router context injected by {@link withVirtualFs}.
- * Guarantees a live (ephemeral) virtual filesystem built from the workflow
- * file tree.
+ * Signal that a tool handler requested a rewind. Attached to the
+ * {@link ProcessToolCallsResult} so the session can reuse the same
+ * `assistantMessageId` for the retry; the next `runAgent` activity
+ * then truncates the thread from that id on entry.
  */
-interface VirtualFsContext<TCtx = unknown, TMeta = FileEntryMetadata> extends RouterContext {
-    virtualFs: VirtualFileSystem<TCtx, TMeta>;
+interface RewindSignal {
+    toolCallId: string;
+    toolName: string;
 }
-
 /**
- * Agent execution status
+ * Result returned by {@link ToolRouter.processToolCalls}.
+ *
+ * The object is a standard array of tool call results for successful
+ * tool calls (cancelled or rewinding siblings are omitted), extended
+ * with a `rewind` property when any tool in the batch requested a
+ * rewind. Using an array-with-property lets existing code that treats
+ * the return value as `ToolCallResultUnion[]` continue to work.
  */
-type AgentStatus = "RUNNING" | "WAITING_FOR_INPUT" | "COMPLETED" | "FAILED" | "CANCELLED";
+type ProcessToolCallsResult<TResults extends Record<string, unknown>> = ToolCallResultUnion<TResults>[] & {
+    rewind?: RewindSignal;
+};
 /**
- * Base state that all agents must have
+ * Result from PreToolUse hook - can block or modify execution
  */
-interface BaseAgentState {
-    tools: SerializableToolDefinition[];
-    status: AgentStatus;
-    version: number;
-    turns: number;
-    tasks: Map<string, WorkflowTask>;
-    fileTree: FileEntry[];
-    /** In-memory file contents keyed by path, bypassing the resolver (e.g. skill resources). */
-    inlineFiles?: Record<string, string>;
-    virtualFsCtx?: unknown;
-    systemPrompt?: unknown;
-    totalInputTokens: number;
-    totalOutputTokens: number;
-    cachedWriteTokens: number;
-    cachedReadTokens: number;
+interface PreToolUseHookResult {
+    /** Skip this tool call entirely */
+    skip?: boolean;
+    /** Modified args to use instead (must match schema) */
+    modifiedArgs?: unknown;
 }
 /**
- * File representation for agent workflows
+ * Result from PostToolUseFailure hook - can recover from errors
  */
-interface AgentFile {
-    /** Database/S3 file ID */
-    id: string;
-    /** Virtual path for agent (e.g., "evidence/invoice.pdf") */
-    path: string;
-    /** Original filename */
-    filename: string;
-    /** Generic description for prompt */
-    description?: string;
-    /** MIME type of the file */
-    mimeType?: string;
-}
-interface TokenUsage {
-    inputTokens?: number;
-    outputTokens?: number;
-    cachedWriteTokens?: number;
-    cachedReadTokens?: number;
-    reasonTokens?: number;
+interface PostToolUseFailureHookResult {
+    /** Provide a fallback result instead of throwing */
+    fallbackContent?: JsonValue;
+    /** Whether to suppress the error (still logs, but continues) */
+    suppress?: boolean;
 }
 /**
- * Configuration for a Zeitlich agent
+ * Per-tool lifecycle hooks - defined directly on a tool definition.
+ * Runs in addition to global hooks (global pre → tool pre → execute → tool post → global post).
  */
-interface AgentConfig {
-    /** The name of the agent, should be unique within the workflows, ideally Pascal Case */
-    agentName: string;
-    /** Description, used for sub agents */
-    description?: string;
+interface ToolHooks<TArgs = unknown, TResult = unknown> {
+    /** Called before this tool executes - can skip or modify args */
+    onPreToolUse?: (ctx: {
+        args: TArgs;
+        threadId: string;
+        turn: number;
+    }) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
+    /** Called after this tool executes successfully */
+    onPostToolUse?: (ctx: {
+        args: TArgs;
+        result: TResult;
+        threadId: string;
+        turn: number;
+        durationMs: number;
+        metadata?: Record<string, unknown>;
+    }) => void | Promise<void>;
+    /** Called when this tool execution fails */
+    onPostToolUseFailure?: (ctx: {
+        args: TArgs;
+        error: Error;
+        threadId: string;
+        turn: number;
+    }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
 }
 /**
- * A JSON-serializable tool definition for state storage.
- * Uses a plain JSON Schema object instead of a live Zod instance,
- * so it survives Temporal serialization without losing constraints (min, max, etc.).
+ * Context for PreToolUse hook - called before tool execution
  */
-interface SerializableToolDefinition {
-    name: string;
-    description: string;
-    schema: Record<string, unknown>;
-    strict?: boolean;
-    max_uses?: number;
+interface PreToolUseHookContext<T extends ToolMap> {
+    /** The tool call about to be executed */
+    toolCall: ParsedToolCallUnion<T>;
+    /** Thread identifier */
+    threadId: string;
+    /** Current turn number */
+    turn: number;
 }
 /**
- * Configuration passed to runAgent activity
+ * PreToolUse hook - called before tool execution, can block or modify
  */
-interface RunAgentConfig extends AgentConfig {
-    /** The thread ID to use for the session */
+type PreToolUseHook<T extends ToolMap> = (ctx: PreToolUseHookContext<T>) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
+/**
+ * Context for PostToolUse hook - called after successful tool execution
+ */
+interface PostToolUseHookContext<T extends ToolMap, TResult = unknown> {
+    /** The tool call that was executed */
+    toolCall: ParsedToolCallUnion<T>;
+    /** The result from the tool handler */
+    result: TResult;
+    /** Thread identifier */
     threadId: string;
-    /** Redis key suffix for thread storage. Defaults to 'messages'. */
-    threadKey?: string;
-    /** Metadata for the session */
-    metadata?: Record<string, unknown>;
-    /**
-     * The id under which the assistant message produced by this call will
-     * be appended. The activity truncates the thread from this id on
-     * entry (no-op on the first attempt) so that:
-     *
-     * - Rewind retries can reuse the same id and the previous (bad)
-     *   assistant + its tool results are wiped before the retry LLM call.
-     * - Resetting the Temporal workflow to this activity restores the
-     *   pre-call thread state: replay re-truncates, re-invokes, and
-     *   appends under the same id.
-     */
-    assistantMessageId: string;
+    /** Current turn number */
+    turn: number;
+    /** Execution duration in milliseconds */
+    durationMs: number;
 }
 /**
- * Configuration for appending a tool result
+ * PostToolUse hook - called after successful tool execution
  */
-interface ToolResultConfig {
+type PostToolUseHook<T extends ToolMap, TResult = unknown> = (ctx: PostToolUseHookContext<T, TResult>) => void | Promise<void>;
+/**
+ * Context for PostToolUseFailure hook - called when tool execution fails
+ */
+interface PostToolUseFailureHookContext<T extends ToolMap> {
+    /** The tool call that failed */
+    toolCall: ParsedToolCallUnion<T>;
+    /** The error that occurred */
+    error: Error;
+    /** Thread identifier */
     threadId: string;
-    /** Redis key suffix for thread storage. Defaults to 'messages'. */
-    threadKey?: string;
-    toolCallId: string;
-    /** The name of the tool that produced this result */
-    toolName: string;
-    /** Content for the tool result — string, object, or array. The adapter converts to its SDK-native format. */
-    content: JsonValue;
+    /** Current turn number */
+    turn: number;
 }
 /**
- * Status of a workflow task
+ * PostToolUseFailure hook - called when tool execution fails
  */
-type TaskStatus = "pending" | "in_progress" | "completed";
+type PostToolUseFailureHook<T extends ToolMap> = (ctx: PostToolUseFailureHookContext<T>) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
 /**
- * A task managed within a workflow for tracking work items
+ * Tool execution hooks — the subset of hooks consumed by the tool router.
+ * Session/message lifecycle hooks live in lib/hooks/types.ts.
  */
-interface WorkflowTask {
-    /** Unique task identifier */
-    id: string;
-    /** Brief, actionable title in imperative form */
-    subject: string;
-    /** Detailed description of what needs to be done */
-    description: string;
-    /** Present continuous form shown in spinner when in_progress */
-    activeForm: string;
-    /** Current status of the task */
-    status: TaskStatus;
-    /** Arbitrary key-value pairs for tracking */
-    metadata: Record<string, string>;
-    /** IDs of tasks that must complete before this one can start */
-    blockedBy: string[];
-    /** IDs of tasks that are waiting for this one to complete */
-    blocks: string[];
+interface ToolRouterHooks<T extends ToolMap, TResult = unknown> {
+    /** Called before each tool execution - can block or modify */
+    onPreToolUse?: PreToolUseHook<T>;
+    /** Called after each successful tool execution */
+    onPostToolUse?: PostToolUseHook<T, TResult>;
+    /** Called when tool execution fails */
+    onPostToolUseFailure?: PostToolUseFailureHook<T>;
 }
 /**
- * Exit reasons for session termination
+ * Options for creating a tool router.
  */
-type SessionExitReason = "completed" | "max_turns" | "waiting_for_input" | "failed" | "cancelled";
+interface ToolRouterOptions<T extends ToolMap> {
+    /** Map of tools with their handlers */
+    tools: T;
+    /** Thread ID for appending tool results */
+    threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
+    /** Function to append tool results to the thread (called automatically after each handler).
+     *  Accepts a Temporal activity proxy with {@link ActivityFunctionWithOptions}. */
+    appendToolResult: AppendToolResultFn;
+    /** Whether to process tools in parallel (default: true) */
+    parallel?: boolean;
+    /** Tool execution lifecycle hooks (pre/post tool use) */
+    hooks?: ToolRouterHooks<T, ToolCallResultUnion<InferToolResults<T>>>;
+    /** Additional tools to auto-register (e.g. subagent, skill tools built by register helpers) */
+    plugins?: ToolMap[string][];
+}
 /**
- * Helper to check if status is terminal
+ * The tool router interface with full type inference for both args and results.
  */
-declare function isTerminalStatus(status: AgentStatus): boolean;
+interface ToolRouter<T extends ToolMap> {
+    /** Check if the router has any tools */
+    hasTools(): boolean;
+    /**
+     * Parse and validate a raw tool call against the router's tools.
+     * Returns a typed tool call with validated arguments.
+     */
+    parseToolCall(toolCall: RawToolCall): ParsedToolCallUnion<T>;
+    /**
+     * Check if a tool with the given name exists in the router.
+     */
+    hasTool(name: string): boolean;
+    /**
+     * Get all tool names in the router.
+     */
+    getToolNames(): ToolNames<T>[];
+    /**
+     * Get all tool definitions (without handlers) for passing to LLM.
+     */
+    getToolDefinitions(): ToolDefinition[];
+    /**
+     * Process all tool calls using the registered handlers.
+     * Returns typed results based on handler return types.
+     * @param toolCalls - Array of parsed tool calls to process
+     * @param context - Optional context including turn number for hooks
+     */
+    processToolCalls(toolCalls: ParsedToolCallUnion<T>[], context?: ProcessToolCallsContext): Promise<ProcessToolCallsResult<InferToolResults<T>>>;
+    /**
+     * Process tool calls matching a specific name with a custom handler.
+     * Useful for overriding the default handler for specific cases.
+     */
+    processToolCallsByName<TName extends ToolNames<T>, TResult>(toolCalls: ParsedToolCallUnion<T>[], toolName: TName, handler: ToolHandler<ToolArgs<T, TName>, TResult>, context?: ProcessToolCallsContext): Promise<ToolCallResult<TName, TResult>[]>;
+    /**
+     * Filter tool calls by name.
+     */
+    filterByName<TName extends ToolNames<T>>(toolCalls: ParsedToolCallUnion<T>[], name: TName): ParsedToolCall<TName, ToolArgs<T, TName>>[];
+    /**
+     * Check if any tool call matches the given name.
+     */
+    hasToolCall(toolCalls: ParsedToolCallUnion<T>[], name: ToolNames<T>): boolean;
+    /**
+     * Filter results by tool name.
+     */
+    getResultsByName<TName extends ToolNames<T>>(results: ToolCallResultUnion<InferToolResults<T>>[], name: TName): ToolCallResult<TName, ToolResult<T, TName>>[];
+}
 
 /**
  * Context for SessionStart hook - called when session begins
@@ -1843,4 +1866,4 @@ interface ZeitlichSession<M = unknown, HasSandbox extends boolean = boolean> {
     }): Promise<SessionResult<M, T, HasSandbox>>;
 }
 
-export { type SandboxShutdown as $, type AgentResponse as A, type BaseAgentState as B, type PostToolUseFailureHookContext as C, type PostToolUseFailureHookResult as D, type PostToolUseHook as E, type FileEntryMetadata as F, type PostToolUseHookContext as G, type Hooks as H, type InferToolResults as I, type JsonValue as J, type PreHumanMessageAppendHook as K, type PreHumanMessageAppendHookContext as L, type ModelInvokerConfig as M, type PreToolUseHook as N, type PreToolUseHookContext as O, type PersistedThreadState as P, type PreToolUseHookResult as Q, type RouterContext as R, type ScopedPrefix as S, type ThreadOps as T, type ProcessToolCallsContext as U, type VirtualFsContext as V, type ProcessToolCallsResult as W, type RawToolCall as X, type RewindSignal as Y, type RunAgentActivity as Z, type SandboxInit as _, type ModelInvoker as a, type SerializableToolDefinition as a0, type SessionConfig as a1, type SessionEndHook as a2, type SessionEndHookContext as a3, type SessionExitReason as a4, type SessionRequiredCaps as a5, type SessionResult as a6, type SessionStartHook as a7, type SessionStartHookContext as a8, type SubagentChildWorkflowOptions as a9, VirtualFileSystem as aA, type VirtualFileTree as aB, type VirtualFsOps as aC, type VirtualFsState as aD, type WorkflowTask as aE, type ZeitlichSession as aF, isTerminalStatus as aG, type ToolRouterOptions as aH, type SubagentConfig as aa, type SubagentContinuationCaps as ab, type SubagentDefinition as ac, type SubagentFnResult as ad, type SubagentHandlerResponse as ae, type SubagentHooks as af, type SubagentSandboxConfig as ag, type SubagentSandboxShutdown as ah, type SubagentSessionInput as ai, type SubagentWorkflow as aj, type SubagentWorkflowInput as ak, type TaskStatus as al, type ThreadInit as am, type TokenUsage as an, type ToolArgs as ao, type ToolCallResult as ap, type ToolCallResultUnion as aq, type ToolDefinition as ar, type ToolHandler as as, type ToolHooks as at, type ToolMap as au, type ToolNames as av, type ToolResult as aw, type ToolRouter as ax, type ToolRouterHooks as ay, type ToolWithHandler as az, type PrefixedThreadOps as b, type ToolHandlerResponse as c, type ActivityToolHandler as d, type ToolResultConfig as e, type RunAgentConfig as f, type SkillProvider as g, type SkillMetadata as h, type Skill as i, type FileResolver as j, type TreeMutation as k, type PrefixedVirtualFsOps as l, type AgentConfig as m, type AgentFile as n, type AgentState as o, type AgentStateManager as p, type AgentStatus as q, type AppendToolResultFn as r, type FileEntry as s, type JsonPrimitive as t, type JsonSerializable as u, type ParsedToolCall as v, type ParsedToolCallUnion as w, type PostHumanMessageAppendHook as x, type PostHumanMessageAppendHookContext as y, type PostToolUseFailureHook as z };
+export { type SandboxShutdown as $, type AgentResponse as A, type BaseAgentState as B, type PostToolUseFailureHookContext as C, type PostToolUseFailureHookResult as D, type PostToolUseHook as E, type FileEntryMetadata as F, type PostToolUseHookContext as G, type Hooks as H, type InferToolResults as I, type JsonValue as J, type PreHumanMessageAppendHook as K, type PreHumanMessageAppendHookContext as L, type ModelInvokerConfig as M, type PreToolUseHook as N, type PreToolUseHookContext as O, type PersistedThreadState as P, type PreToolUseHookResult as Q, type RouterContext as R, type ScopedPrefix as S, type ThreadOps as T, type ProcessToolCallsContext as U, type VirtualFsContext as V, type ProcessToolCallsResult as W, type RawToolCall as X, type RewindSignal as Y, type RunAgentActivity as Z, type SandboxInit as _, type ModelInvoker as a, type SerializableToolDefinition as a0, type SessionConfig as a1, type SessionEndHook as a2, type SessionEndHookContext as a3, type SessionExitReason as a4, type SessionRequiredCaps as a5, type SessionResult as a6, type SessionStartHook as a7, type SessionStartHookContext as a8, type SubagentChildWorkflowOptions as a9, VirtualFileSystem as aA, type VirtualFileTree as aB, type VirtualFsOps as aC, type VirtualFsState as aD, type WorkflowTask as aE, type ZeitlichSession as aF, isTerminalStatus as aG, type ToolRouterOptions as aH, type SubagentConfig as aa, type SubagentContinuationCaps as ab, type SubagentDefinition as ac, type SubagentFnResult as ad, type SubagentHandlerResponse as ae, type SubagentHooks as af, type SubagentSandboxConfig as ag, type SubagentSandboxShutdown as ah, type SubagentSessionInput as ai, type SubagentWorkflow as aj, type SubagentWorkflowInput as ak, type TaskStatus as al, type ThreadInit as am, type TokenUsage as an, type ToolArgs as ao, type ToolCallResult as ap, type ToolCallResultUnion as aq, type ToolDefinition as ar, type ToolHandler as as, type ToolHooks as at, type ToolMap as au, type ToolNames as av, type ToolResult as aw, type ToolRouter as ax, type ToolRouterHooks as ay, type ToolWithHandler as az, type PrefixedThreadOps as b, type ToolHandlerResponse as c, type ActivityToolHandler as d, type RunAgentConfig as e, type ToolResultConfig as f, type SkillProvider as g, type SkillMetadata as h, type Skill as i, type FileResolver as j, type TreeMutation as k, type PrefixedVirtualFsOps as l, type AgentConfig as m, type AgentFile as n, type AgentState as o, type AgentStateManager as p, type AgentStatus as q, type AppendToolResultFn as r, type FileEntry as s, type JsonPrimitive as t, type JsonSerializable as u, type ParsedToolCall as v, type ParsedToolCallUnion as w, type PostHumanMessageAppendHook as x, type PostHumanMessageAppendHookContext as y, type PostToolUseFailureHook as z };