@namzu/sdk 2.0.0 → 3.0.0

package/src/types/guardrail/index.ts

@@ -0,0 +1,62 @@
+import type { RunId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
+
+/**
+ * Guardrails inspect what goes INTO a run and what comes OUT of it.
+ *
+ * namzu had three good gates on tool calls — probe veto, `VerificationGate`,
+ * HITL review — and they all point the same way: they protect the world
+ * from the agent. Nothing protected the user from the agent's own output,
+ * and nothing looked at the prompt before the run started.
+ *
+ * The concrete failure: an agent reads a credential file, the read is
+ * allowed (it is a legitimate file), the secret enters context, and it is
+ * repeated in the final answer. Every existing gate is upstream of that
+ * and none of them fire.
+ */
+
+export interface InputGuardrailContext {
+	readonly runId: RunId
+	/** The messages the run is about to start with. */
+	readonly messages: readonly Message[]
+	/** The assembled system prompt, when there is one. */
+	readonly systemPrompt?: string
+}
+
+export interface OutputGuardrailContext {
+	readonly runId: RunId
+	/** The run's final assistant text. */
+	readonly output: string
+	/** Full message history, for a guardrail that needs the conversation. */
+	readonly messages: readonly Message[]
+}
+
+/**
+ * What a guardrail decided.
+ *
+ * `rewrite` matters as much as `tripwire`: a PII policy usually wants to
+ * redact an account number, not throw the whole answer away. A gate that
+ * can only abort forces every redaction use case to be implemented
+ * somewhere else.
+ */
+export type GuardrailVerdict =
+	| { readonly action: 'pass' }
+	| { readonly action: 'block'; readonly reason: string }
+	| { readonly action: 'rewrite'; readonly output: string; readonly reason?: string }
+
+export type InputGuardrail = (
+	ctx: InputGuardrailContext,
+) => GuardrailVerdict | Promise<GuardrailVerdict>
+
+export type OutputGuardrail = (
+	ctx: OutputGuardrailContext,
+) => GuardrailVerdict | Promise<GuardrailVerdict>
+
+/** Convenience: a named guardrail, so a block can say which rule tripped. */
+export interface NamedGuardrail<T> {
+	readonly name: string
+	readonly check: T
+}
+
+export type InputGuardrailSpec = InputGuardrail | NamedGuardrail<InputGuardrail>
+export type OutputGuardrailSpec = OutputGuardrail | NamedGuardrail<OutputGuardrail>

package/src/types/hitl/index.ts

@@ -1,3 +1,5 @@
+import type { WorkingStateSnapshot } from '../../compaction/wire.js'
+import type { SerializedSpanContext } from '../../telemetry/attributes.js'
 import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { CheckpointId, PlanId, RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
@@ -9,7 +11,27 @@ export type HITLResumeDecision =
 	| { action: 'continue' }
 	| { action: 'approve_plan'; feedback?: string }
 	| { action: 'reject_plan'; feedback: string }
-	| { action: 'approve_tools' }
+	| {
+			action: 'approve_tools'
+			/**
+			 * Grant keys to remember, so calls covered by them are not asked
+			 * about again for the rest of the run.
+			 *
+			 * Nothing is remembered unless this says so, and only an explicit
+			 * approval can say it — a denial or a non-response leaves nothing
+			 * behind. Non-reuse was deliberate ("consent is not
+			 * transferable"); what changes is that the SCOPE becomes the
+			 * approver's to choose rather than being fixed at "this one call"
+			 * or, in the only escape available, "everything for the session".
+			 *
+			 * Keys come from {@link ToolGrantKeys}, so a grant can be as
+			 * narrow as one exact invocation or as wide as a whole tool.
+			 * `bash` is unconditionally non-read-only and in no allowlist, so
+			 * `bash: git status` re-prompted on every batch forever and the
+			 * only way out was a blanket grant that also covered `rm -rf`.
+			 */
+			remember?: readonly string[]
+	  }
 	| { action: 'modify_tools'; modifications: ToolModification[] }
 	| { action: 'reject_tools'; feedback: string }
 	| {
@@ -101,22 +123,54 @@ export interface CheckpointSummary {
 	lastAssistantMessage?: string
 }
 
-export interface ActiveNodeInfo {
-	agentId: string
-	agentType: 'reactive' | 'pipeline' | 'router' | 'supervisor'
-
-	nodeRef?: string
-
-	parentAgentId?: string
-
-	depth: number
-}
-
-export interface BranchStackEntry {
-	agentId: string
-	decision: string
-	confidence: number
-	timestamp: number
+/**
+ * A decision the run is parked on, recorded durably.
+ *
+ * Without this the park exists only as a suspended `await` inside one
+ * process: a checkpoint written at a tool-review gate looks identical to a
+ * checkpoint written mid-run, so nothing on disk says "a human owes this
+ * run an answer". Kill the process and the request is gone — the approval
+ * queue a host would build from durable state has nothing to read, and a
+ * resumed run silently re-asks the model instead of honoring the approval
+ * that was already granted.
+ *
+ * `request` is stored verbatim so a fresh process can render exactly what
+ * the human was shown, and apply the answer to exactly those tool calls.
+ */
+export interface PendingDecision {
+	/** The request the run parked on, as the `resumeHandler` received it. */
+	readonly request: HITLDecisionRequest
+	/** Epoch ms at which the run parked. */
+	readonly parkedAt: number
+	/**
+	 * Epoch ms after which this park is no longer worth serving.
+	 *
+	 * Absolute, not a duration, so it survives the process that set it —
+	 * every timer in the SDK is an in-process `setTimeout` and the
+	 * park-record delay is deliberately `unref`'d, so nothing in-memory can
+	 * outlive a redeploy. Without it a run parks for approval, the worker is
+	 * replaced, nobody answers, and the checkpoint stays outstanding
+	 * forever: every approval-queue reader keeps serving it and its
+	 * workspace is never reclaimed.
+	 *
+	 * The run timeout cannot cover this. `checkLimitsDetailed` is only
+	 * reached between iterations and a park suspends mid-iteration, so a
+	 * long-lived process hard-stops the run immediately AFTER the human
+	 * finally approves, while across a restart the restored elapsed time
+	 * excludes parked time entirely — the same configuration giving two
+	 * opposite outcomes.
+	 *
+	 * Absent means no deadline, which is today's behaviour.
+	 */
+	readonly deadlineAt?: number
+	/**
+	 * Set once the decision arrives, so a resolved checkpoint stays
+	 * distinguishable from one that was never parked. A checkpoint is
+	 * outstanding when `pending` is set and `resolvedAt` is not.
+	 */
+	readonly resolvedAt?: number
+	/** The answer, when one arrived. Kept as evidence of who decided what. */
+	readonly decision?: HITLResumeDecision
 }
 
 export interface IterationCheckpoint {
@@ -127,6 +181,12 @@ export interface IterationCheckpoint {
 	tokenUsage: TokenUsage
 	costInfo: CostInfo
 	planStatus?: PlanStatus
+
+	/**
+	 * Present when the run parked at this checkpoint awaiting a human.
+	 * See {@link PendingDecision}.
+	 */
+	pending?: PendingDecision
 	guardState: {
 		iterationCount: number
 		elapsedMs: number
@@ -135,9 +195,31 @@ export interface IterationCheckpoint {
 
 	toolResultHashes?: Record<string, string>
 
-	branchStack?: BranchStackEntry[]
-
-	activeNode?: ActiveNodeInfo
+	/**
+	 * Compaction's accumulated working state at the moment of the
+	 * checkpoint.
+	 *
+	 * Absent on checkpoints written before this existed, and absent when
+	 * compaction is disabled — in both cases the resumed run starts with an
+	 * empty manager, which is exactly today's behaviour.
+	 */
+	workingState?: WorkingStateSnapshot
+
+	/**
+	 * The trace this checkpoint was taken inside.
+	 *
+	 * A resumed run used to mint a fresh root span with a new trace id and
+	 * no link to the one that crashed, so the failure and its recovery could
+	 * not be reconstructed as one timeline. Every span carries the run id,
+	 * which is enough to find both traces by query and not enough to see one
+	 * waterfall — and even that goes away for a replay fork, which mints a
+	 * new run id.
+	 *
+	 * Absent on checkpoints written before this existed, and on runs with no
+	 * telemetry registered; in both cases the resumed run starts its own
+	 * trace, which is exactly today's behaviour.
+	 */
+	traceContext?: SerializedSpanContext
 }
 
 export function autoApproveHandler(request: HITLDecisionRequest): Promise<HITLResumeDecision> {

package/src/types/ids/index.ts

@@ -4,11 +4,11 @@ export type SessionId = `ses_${string}`
 export type ToolCallId = `call_${string}`
 /**
  * Provider-issued tool-use identifier surfaced on the streaming event bus.
- * Providers emit different prefixes (Anthropic: `toolu_*`, OpenAI: `call_*`,
+ * Providers emit different prefixes (`toolu_*`, `call_*`,
  * others vary), so this type intentionally stays unbranded — we accept the
  * provider's verbatim string and use it solely as a correlation key across
  * `tool_input_*`, `tool_executing`, and `tool_completed` events. Distinct
- * from {@link ToolCallId} which is the OpenAI-format identifier carried in
+ * from {@link ToolCallId} which is the wire-format identifier carried in
  * persisted assistant messages and replay records.
  */
 export type ToolUseId = string

package/src/types/message/content.ts

@@ -0,0 +1,50 @@
+import type { ToolResultBlock, ToolResultContent } from './index.js'
+
+/**
+ * Normalize tool-result content to blocks.
+ *
+ * A plain string is the common case and stays first-class; this is the
+ * adapter for drivers that want to walk blocks uniformly.
+ */
+export function toToolResultBlocks(content: ToolResultContent): readonly ToolResultBlock[] {
+	return typeof content === 'string' ? [{ type: 'text', text: content }] : content
+}
+
+/**
+ * Flatten tool-result content to text.
+ *
+ * For drivers that cannot express non-text tool results, and for every
+ * host-facing surface (transcript, compaction, UI) that reasons over
+ * strings. Non-text blocks become a short, honest placeholder rather than
+ * their base64 payload: dumping the bytes is what made `computer-use`
+ * send megabytes of undecodable characters as text, and silently dropping
+ * them would let the model believe it saw something it did not.
+ */
+export function toolResultToText(content: ToolResultContent): string {
+	if (typeof content === 'string') return content
+	return content
+		.map((block) => {
+			switch (block.type) {
+				case 'text':
+					return block.text
+				case 'image':
+					return `[image: ${block.mediaType}, ${describeSize(block.data)} — not renderable by this provider]`
+				case 'document':
+					return `[document${block.name ? ` "${block.name}"` : ''}: ${block.mediaType}, ${describeSize(block.data)} — not renderable by this provider]`
+			}
+		})
+		.join('\n')
+}
+
+/** True when the content needs a driver that can carry non-text blocks. */
+export function hasNonTextBlocks(content: ToolResultContent): boolean {
+	return typeof content !== 'string' && content.some((b) => b.type !== 'text')
+}
+
+/** Approximate decoded byte count of a base64 payload, for a human-readable note. */
+function describeSize(base64: string): string {
+	const bytes = Math.floor((base64.length * 3) / 4)
+	if (bytes < 1024) return `${bytes} B`
+	if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}

package/src/types/message/index.ts

@@ -4,16 +4,88 @@ export type CacheHint = 'cache' | 'ephemeral' | 'none'
 
 /**
  * An image attached to a user message (vision input). Additive: providers
- * that support vision (e.g. Anthropic) emit it as an image content block
+ * that support vision emit it as an image content block
  * alongside the text; providers that don't simply ignore it.
  */
 export interface ImageAttachment {
+	/**
+	 * Optional, and optional forever: an attachment without a discriminant
+	 * is an image, which is what every attachment was before documents
+	 * existed. Requiring it would have broken every caller to describe a
+	 * default they were already relying on.
+	 */
+	readonly type?: 'image'
 	/** Base64-encoded image bytes (no `data:` URI prefix). */
 	readonly data: string
 	/** IANA media type, e.g. `image/png`, `image/jpeg`, `image/webp`. */
 	readonly mediaType: string
 }
 
+/**
+ * A document attached to a user message.
+ *
+ * Documents existed in the type system only in the TOOL-RESULT direction,
+ * so "here is the contract, answer questions about it" was reachable only
+ * by having a tool read the file and stringify it. That loses the
+ * provider's native document handling — page structure, built-in OCR,
+ * citations — and pays the text cost instead.
+ */
+export interface DocumentAttachment {
+	readonly type: 'document'
+	/**
+	 * Ask the model to cite this document when it uses it.
+	 *
+	 * Opt-in, because it is not free: the provider splits the document
+	 * into citable units and the answer carries the passages it leaned
+	 * on, which costs tokens on a turn that may not need them.
+	 *
+	 * Citations come back on the assistant message, not in its text —
+	 * see {@link Citation}.
+	 */
+	readonly citations?: boolean
+	/** Base64-encoded bytes (no `data:` URI prefix). */
+	readonly data: string
+	/** IANA media type, e.g. `application/pdf`. */
+	readonly mediaType: string
+	/** Shown to the model, so it can refer to the file by name. */
+	readonly name?: string
+}
+
+/**
+ * Where a passage the model cited came from.
+ *
+ * Sending a document buys the provider's native handling of it — page
+ * structure, built-in OCR, and the ability to say WHICH passage an
+ * answer rests on. namzu could send the document and could not receive
+ * the third: an answer about a contract arrived as prose, and checking
+ * it meant reading the contract again by hand. A citation is the
+ * difference between an answer you trust and one you verify.
+ *
+ * The location is a union rather than a page number because providers
+ * segment differently and the segmentation is theirs: pages for a
+ * paginated document, character offsets for plain text, block indices
+ * for something already structured. Flattening them all to "page" would
+ * invent a number for the two that have none.
+ */
+export interface Citation {
+	/** The passage itself, verbatim from the source. */
+	readonly citedText: string
+	/** Which attachment, by position in the message that carried it. */
+	readonly documentIndex: number
+	readonly documentTitle?: string
+	readonly location:
+		| { readonly kind: 'page'; readonly start: number; readonly end: number }
+		| { readonly kind: 'char'; readonly start: number; readonly end: number }
+		| { readonly kind: 'block'; readonly start: number; readonly end: number }
+}
+
+/** What a user message may carry alongside its text. */
+export type MessageAttachment = ImageAttachment | DocumentAttachment
+
+export const isDocumentAttachment = (
+	attachment: MessageAttachment,
+): attachment is DocumentAttachment => attachment.type === 'document'
+
 export interface ToolCall {
 	id: string
 	type: 'function'
@@ -28,14 +100,49 @@ export interface ToolCall {
 	 */
 	metadata?: {
 		inputTruncated?: boolean
+		/**
+		 * The partial argument buffer as it arrived, when the stream cut off
+		 * mid-JSON. `function.arguments` is normalized to `"{}"` in that
+		 * case so tool args stay clean, which leaves this as the only record
+		 * of what the model was actually saying — and a `repairToolCall`
+		 * hook has nothing to repair without it.
+		 */
+		partialArguments?: string
 	}
 }
 
 export interface BaseMessage {
+	/**
+	 * Widened from `string | null` so `ToolMessage` can carry content
+	 * blocks. Each variant below narrows it back to exactly what that role
+	 * may hold, so no caller loses type safety — only the shared base is
+	 * permissive.
+	 */
 	role: MessageRole
-	content: string | null
+	content: string | null | readonly ToolResultBlock[]
 	timestamp?: number
 	cacheHint?: CacheHint
+	/**
+	 * Exempt this message from compaction and from tool-result clearing.
+	 *
+	 * Everything the run protected before was protected by POSITION — the
+	 * leading system run, the working-memory slot, the last N turns, the
+	 * most recent tool results. A standing constraint stated in the middle
+	 * of a conversation ("the account id is X; never bill a different
+	 * one") therefore aged out at the same rate as chatter, and no
+	 * positional rule could express it.
+	 *
+	 * Protection is transitive across a tool pair: pinning a
+	 * `tool_result` also pins the assistant turn that called it, and
+	 * pinning that turn pins every result answering it. Half a pair is not
+	 * a smaller history, it is one the provider rejects.
+	 *
+	 * Pinned turns are exempt from the reclaim that keeps a long run
+	 * alive, so this is a budget the setter spends. Nothing caps it: a cap
+	 * would have to guess which pin mattered, and dropping the wrong one
+	 * quietly is worse than a run that overflows in the open.
+	 */
+	retain?: boolean
 }
 
 export interface SystemMessage extends BaseMessage {
@@ -46,20 +153,93 @@ export interface SystemMessage extends BaseMessage {
 export interface UserMessage extends BaseMessage {
 	role: 'user'
 	content: string
-	/** Optional image attachments (vision input). */
-	attachments?: readonly ImageAttachment[]
+	/** Optional image or document attachments. */
+	attachments?: readonly MessageAttachment[]
+}
+
+/**
+ * An opaque reasoning block produced by the model.
+ *
+ * Deliberately opaque: the SDK stores and replays it, never interprets it.
+ * A provider whose reasoning blocks are signed requires the preceding
+ * assistant turn to be echoed back **verbatim** — thinking blocks and
+ * their cryptographic `signature` included — whenever a `tool_result`
+ * follows. namzu's drivers *rebuilt* each assistant turn as
+ * `[text?, ...tool_use]`, which is exactly the pattern such a contract
+ * prohibits, and `AssistantMessage` had nowhere to keep a signature
+ * even if a driver had parsed one.
+ *
+ * The requirement is not one vendor's quirk: dropping reasoning items
+ * costs measurable multi-step accuracy wherever they are signed.
+ */
+export interface ReasoningBlock {
+	readonly type: 'thinking' | 'redacted_thinking'
+	readonly text?: string
+	/** Cryptographic signature; replaying it unchanged is mandatory. */
+	readonly signature?: string
+	/** Opaque payload for the ZDR / stateless path. */
+	readonly encrypted?: string
 }
 
 export interface AssistantMessage extends BaseMessage {
 	role: 'assistant'
 	content: string | null
 	toolCalls?: ToolCall[]
+	/**
+	 * Reasoning the model emitted before this turn's content, in order.
+	 * Replayed verbatim and ahead of the text/tool blocks — see
+	 * {@link ReasoningBlock}.
+	 */
+	reasoning?: readonly ReasoningBlock[]
+	/**
+	 * Passages this turn rests on, when the request asked for them.
+	 *
+	 * On the message rather than inside its text: the text is what a
+	 * human reads and the citations are what a checker follows, and
+	 * splicing markers into the prose would make the answer worse to read
+	 * in exchange for making it machine-checkable. Empty and absent mean
+	 * the same thing — the model cited nothing.
+	 */
+	citations?: readonly Citation[]
 }
 
+/**
+ * A block of tool-result content the model can actually perceive.
+ *
+ * `ToolMessage.content` was `string`, so anything non-textual had to be
+ * stringified to reach the model. `@namzu/computer-use`'s `screenshot`
+ * returned ~400 KB–2.7 MB of base64 as TEXT — roughly 100k–670k tokens of
+ * characters no model can decode — and every MCP `image`/`resource` block
+ * was silently dropped by the adapter. Computer use was, in practice,
+ * non-functional.
+ */
+export type ToolResultBlock =
+	| { readonly type: 'text'; readonly text: string }
+	| { readonly type: 'image'; readonly data: string; readonly mediaType: string }
+	| DocumentAttachment
+
+/**
+ * String stays a first-class shape, not a deprecated one: it is the
+ * overwhelmingly common case, and keeping it means every existing tool and
+ * driver compiles unchanged while the block array is added beside it.
+ */
+export type ToolResultContent = string | readonly ToolResultBlock[]
+
 export interface ToolMessage extends BaseMessage {
 	role: 'tool'
-	content: string
+	content: ToolResultContent
 	toolCallId: string
+	/**
+	 * Marks the result as a failure on the wire — each provider spells it
+	 * differently (`is_error`, `status: 'error'`), and every driver has
+	 * somewhere to put it.
+	 *
+	 * The executor already computed this and routed it to the SSE bridge,
+	 * the A2A bridge and the TUI — then dropped it at the provider
+	 * boundary, so the model's trained tool-failure recovery path never
+	 * fired and namzu relied on prose formatting to convey failure.
+	 */
+	isError?: boolean
 }
 
 export type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage
@@ -75,7 +255,7 @@ export function createSystemMessage(content: string, cacheHint?: CacheHint): Sys
 
 export function createUserMessage(
 	content: string,
-	attachments?: readonly ImageAttachment[],
+	attachments?: readonly MessageAttachment[],
 ): UserMessage {
 	return {
 		role: 'user',
@@ -88,10 +268,31 @@ export function createUserMessage(
 export function createAssistantMessage(
 	content: string | null,
 	toolCalls?: ToolCall[],
+	reasoning?: readonly ReasoningBlock[],
+	citations?: readonly Citation[],
 ): AssistantMessage {
-	return { role: 'assistant', content, toolCalls, timestamp: Date.now() }
+	return {
+		role: 'assistant',
+		content,
+		toolCalls,
+		...(reasoning && reasoning.length > 0 ? { reasoning } : {}),
+		...(citations && citations.length > 0 ? { citations } : {}),
+		timestamp: Date.now(),
+	}
 }
 
-export function createToolMessage(content: string, toolCallId: string): ToolMessage {
-	return { role: 'tool', content, toolCallId, timestamp: Date.now() }
+export function createToolMessage(
+	content: ToolResultContent,
+	toolCallId: string,
+	isError?: boolean,
+): ToolMessage {
+	return {
+		role: 'tool',
+		content,
+		toolCallId,
+		...(isError !== undefined ? { isError } : {}),
+		timestamp: Date.now(),
+	}
 }
+
+export { hasNonTextBlocks, toToolResultBlocks, toolResultToText } from './content.js'

package/src/types/plugin/index.ts

@@ -9,6 +9,7 @@ import {
 	PLUGIN_NAME_MAX_LENGTH,
 } from '../../constants/plugin/index.js'
 import type { PluginId, RunId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
 import type { ToolResult } from '../tool/index.js'
 
 // ---------------------------------------------------------------------------
@@ -109,6 +110,35 @@ export function assertPluginHookEvent(event: PluginHookEvent): void {
 	}
 }
 
+/**
+ * What an extension is shown about a model call it is about to make.
+ *
+ * A projection, not the live request object. The wire params carry driver
+ * concerns an extension has no business depending on, and handing them
+ * over would make every future field of that type part of the plugin
+ * contract by accident.
+ */
+export interface PluginModelRequest {
+	readonly model: string
+	readonly messages: readonly Message[]
+	/** Names only. A hook auditing tool exposure needs the set, not the schemas. */
+	readonly toolNames: readonly string[]
+	readonly temperature?: number
+	readonly maxTokens?: number
+}
+
+/** What an extension is shown about the model's reply. */
+export interface PluginModelResponse {
+	readonly content: string | null
+	readonly toolNames: readonly string[]
+	readonly finishReason: string
+	readonly usage: {
+		readonly promptTokens: number
+		readonly completionTokens: number
+		readonly totalTokens: number
+	}
+}
+
 export interface PluginHookContext {
 	readonly runId: RunId
 	readonly pluginId: PluginId
@@ -117,6 +147,42 @@ export interface PluginHookContext {
 	readonly toolInput?: unknown
 	readonly toolResult?: ToolResult
 	readonly iteration?: number
+
+	/**
+	 * The request about to be sent, on `pre_llm_call`.
+	 *
+	 * Both model-call hooks fired directly beside this data and were handed
+	 * none of it — only a run id and an iteration number — so an extension
+	 * could observe THAT a call was happening and nothing about what it
+	 * was. A redaction pass, a prompt audit, a per-tenant token ledger: all
+	 * of them needed the one thing the hook did not carry.
+	 *
+	 * Read-only. Frozen before fan-out for the same reason probe events
+	 * are: a hook that mutated the live request would change what every
+	 * later hook sees, and the last one registered would silently win.
+	 * Shaping the request stays the job of the single-slot host callback
+	 * that owns it, where one writer is the contract rather than an
+	 * accident of registration order.
+	 *
+	 * The freeze is one level deep, as elsewhere: each message is a frozen
+	 * copy, so writing to one is inert and cannot reach the run's history,
+	 * but a nested array inside a message is still the run's own.
+	 */
+	readonly request?: Readonly<PluginModelRequest>
+
+	/**
+	 * What came back, on `post_llm_call`. Read-only, same reasoning.
+	 */
+	readonly response?: Readonly<PluginModelResponse>
+	/**
+	 * Aborts when this hook's deadline expires.
+	 *
+	 * The runtime stops waiting on a slow hook either way, but without a
+	 * signal the hook itself never learns it was abandoned: an HTTP request
+	 * inside it keeps a socket open and its eventual result is written into
+	 * a run that moved on without it. A hook doing I/O should forward this.
+	 */
+	readonly signal?: AbortSignal
 }
 
 export type PluginHookResult =
@@ -124,7 +190,6 @@ export type PluginHookResult =
 	| { action: 'skip'; reason: string }
 	| { action: 'modify'; input: unknown }
 	| { action: 'error'; message: string }
-	| { action: 'resume'; input: string }
 	| { action: 'retry' }
 
 export function assertPluginHookResult(result: PluginHookResult): asserts result {
@@ -134,7 +199,6 @@ export function assertPluginHookResult(result: PluginHookResult): asserts result
 		case 'skip':
 		case 'modify':
 		case 'error':
-		case 'resume':
 		case 'retry':
 			break
 		default: {
@@ -147,6 +211,22 @@ export function assertPluginHookResult(result: PluginHookResult): asserts result
 export interface PluginHookDefinition {
 	readonly event: PluginHookEvent
 	readonly handler: (context: PluginHookContext) => Promise<PluginHookResult>
+	/**
+	 * Lower runs first. Default 100.
+	 *
+	 * Order was install order, which is neither declared nor stable — it
+	 * depends on when each plugin happened to be installed. That is fine
+	 * for hooks that only observe, and wrong for the ones that decide:
+	 * `executeHooks` SHORT-CIRCUITS on `skip` and `error`, so a hook that
+	 * denies a dangerous command only gets to deny it if it runs before
+	 * whatever else stops the chain. A guard that fires depending on
+	 * installation history is not a guard.
+	 *
+	 * Ties keep registration order, so plugins that never set a priority
+	 * behave exactly as before. Convention: guards below 100, observers
+	 * above.
+	 */
+	readonly priority?: number
 }
 
 // ---------------------------------------------------------------------------