@namzu/sdk 42.0.2 → 44.0.0

package/src/types/session/turn.ts

@@ -0,0 +1,289 @@
+import type { SessionTokenBudgetSummary } from '../../store/budget/index.js'
+import type { CostInfo, TokenUsage } from '../common/index.js'
+import type {
+	CheckpointId,
+	MessageId,
+	ProjectId,
+	SessionId,
+	TenantId,
+	TurnId,
+} from '../ids/index.js'
+import type { Message } from '../message/index.js'
+import type { ProviderErrorInfo } from '../provider/index.js'
+import type { TurnConfig } from './config.js'
+import type { StepResult } from './step.js'
+import type { StopReason } from './stop-reason.js'
+
+export type { TurnId }
+
+/**
+ * Where a turn is in its lifecycle. Six members, unchanged from the type it
+ * replaces. `Turn.status` and `TurnSettlement.status` use it.
+ */
+export type TurnExecutionStatus =
+	| 'idle'
+	| 'pending'
+	| 'running'
+	| 'completed'
+	| 'failed'
+	| 'cancelled'
+
+/**
+ * The domain status a session log's fold derives for a turn.
+ *
+ *  - `queued` — the turn exists and has not started.
+ *  - `running` — the iteration loop is in flight, or the turn is paused on a
+ *    provider wait with no decision open.
+ *  - `awaiting_hitl` — synchronously waiting on a human (user present).
+ *  - `awaiting_hitl_resolution` — paused with a decision open; the user is
+ *    absent and the turn persists until the decision is resolved or the turn
+ *    is abandoned.
+ *  - `awaiting_subsession` — delegated to a child session and suspended until
+ *    it settles. Session-level fan-in treats this as active.
+ *  - `succeeded`, `failed`, `cancelled` — terminal.
+ *
+ * The wire form (`WireTurnStatus`) maps both `awaiting_hitl*` members to
+ * `awaiting_input`.
+ */
+export type TurnStatus =
+	| 'queued'
+	| 'running'
+	| 'awaiting_hitl'
+	| 'awaiting_hitl_resolution'
+	| 'awaiting_subsession'
+	| 'succeeded'
+	| 'failed'
+	| 'cancelled'
+
+/** The durable subset of {@link TurnConfig} recorded in `turn_started.config`. */
+export interface TurnConfigSnapshot {
+	model: string
+	tokenBudget: number
+	timeoutMs: number
+	streamIdleTimeoutMs?: number
+	maxRequestRichContentBytes?: number
+	maxIterations?: number
+	temperature?: number
+	maxResponseTokens?: number
+	costLimitUsd?: number
+}
+
+/**
+ * The token ledger a turn spends from.
+ *
+ * Keyed by the ROOT session and the root turn: a root turn opens its own
+ * ledger with its own limit, a child session's turns bind to the key of the
+ * root turn that spawned them, and a resumed paused turn reuses its key. So a
+ * limit that changes between two turns of one session is two ledgers, never a
+ * mismatch.
+ */
+export interface TurnBudgetBinding {
+	readonly rootSessionId: SessionId
+	readonly rootTurnId: TurnId
+	readonly accountId: string
+}
+
+/** Which surface opened a session or a turn, and the caller-side ids it used. */
+export type OriginProtocol =
+	| 'cli'
+	| 'sdk'
+	| 'ag-ui'
+	| 'a2a'
+	| 'acp'
+	| 'http'
+	| 'desktop'
+	| 'resident'
+
+/** What kind of work a turn is. A prompt, a goal round, a resident step and a verification step are each a new turn. */
+export type TurnOriginKind = 'prompt' | 'goal-round' | 'resident-step' | 'verification'
+
+export interface Origin {
+	readonly protocol: OriginProtocol
+	/** The caller's own session, thread or context id. Any string; not required to be a UUID. */
+	readonly externalSessionId?: string
+	/** The caller's own id for this unit of work, such as the id an AG-UI client gives its turn. Echoed back verbatim. */
+	readonly externalTurnId?: string
+	readonly kind?: TurnOriginKind
+	readonly goalId?: string
+	readonly round?: number
+}
+
+/**
+ * A caller-side name for a session. The index's `external_refs` table is
+ * derived from these (and from `origin`), never written directly, so it
+ * survives a rebuild.
+ */
+export interface ExternalRef {
+	readonly protocol: string
+	readonly kind: 'session' | 'thread' | 'context'
+	/** Any string; no UUID requirement. */
+	readonly externalId: string
+}
+
+/** Which override, if any, decided a turn's `result`. `model` means the model's own text. */
+export type TurnResultSource =
+	| 'model'
+	| 'guardrail_blocked'
+	| 'guardrail_rewritten'
+	| 'review'
+	| 'outstanding_work'
+	| 'structured_output'
+
+/** How a turn ended: carried on `turn_completed` and `turn_failed`. */
+export interface TurnSettlement {
+	/** `completed` or `cancelled` on `turn_completed`; `failed` on `turn_failed`. */
+	readonly status: TurnExecutionStatus
+	readonly iterations: number
+	/** Usage of this turn only; descendant spend is in the budget summary. */
+	readonly usage: TokenUsage
+	readonly cost: CostInfo
+	readonly durationMs: number
+	/** The assistant message holding the answer, after any `message_replaced`. */
+	readonly resultMessageId?: MessageId
+	readonly resultSource: TurnResultSource
+	readonly structuredOutput?: unknown
+	/** The provider-chain member that served the end of the turn, when it was not the configured one. */
+	readonly servingProvider?: string
+	/** Delegated tasks still running when the turn ended. Not cancelled; named. */
+	readonly abandonedTaskIds: readonly string[]
+	/** Background jobs the model was waiting on that were still running. Not stopped; named. */
+	readonly abandonedJobIds: readonly string[]
+}
+
+/** Metadata of one turn: who ran it, with what, and where it sits in the session tree. */
+export interface TurnMetadata {
+	/** This turn's owner, independent of a shared ancestor token account. */
+	readonly scope?: {
+		readonly tenantId: TenantId
+		readonly projectId: ProjectId
+		readonly sessionId: SessionId
+		readonly turnId: TurnId
+	}
+	agentId: string
+	agentName: string
+	config: TurnConfig
+	/** The provider the turn was configured with: the head of the chain. */
+	provider: string
+	/** The chain member the turn was routed to at the end, when not the configured one. */
+	servingProvider?: string
+	/** Present on a child session's turn: the parent session that delegated it. */
+	parentSessionId?: SessionId
+	/** Present on a child session's turn: the parent turn whose tool call spawned the child. */
+	parentTurnId?: TurnId
+	/** Child sessions this turn spawned. */
+	childSessionIds?: SessionId[]
+}
+
+/** Where a replayed turn was forked from. A fork is always a NEW session. */
+export interface TurnForkOrigin {
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	readonly checkpointId: CheckpointId
+}
+
+/**
+ * One turn of a session, as `query()`, `drainQuery()` and `runAgent()`
+ * return it.
+ *
+ * `messages` is the session's context at settle: the fold of the log, with
+ * every `message_replaced` applied. `result` is the authoritative answer,
+ * after guardrail, review, outstanding-work and structured-output overrides.
+ */
+export interface Turn {
+	id: TurnId
+	sessionId: SessionId
+	status: TurnExecutionStatus
+	metadata: TurnMetadata
+	messages: Message[]
+	/** Usage of this turn only; descendant spend is in `budget`. */
+	tokenUsage: TokenUsage
+	budget?: SessionTokenBudgetSummary
+	budgetBinding?: TurnBudgetBinding
+	costInfo: CostInfo
+	currentIteration: number
+	startedAt: number
+	endedAt?: number
+	stopReason?: StopReason
+	lastError?: string
+	lastProviderError?: ProviderErrorInfo
+	result?: string
+	/** Per-iteration record of what the loop did. Absent on a turn that never entered the loop. */
+	steps?: readonly StepResult[]
+	/** Schema-validated final output, when one was requested and produced. */
+	structuredOutput?: unknown
+	/** Delegated tasks still running when this turn ended. */
+	abandonedTaskIds?: readonly string[]
+	/** Background jobs the model awaited that were still running when this turn ended. */
+	abandonedJobIds?: readonly string[]
+	/** Present on a child session's turn. */
+	parentSessionId?: SessionId
+	/** Present on a child session's turn. */
+	parentTurnId?: TurnId
+	depth?: number
+	/** Present when this turn's session was forked from another session's checkpoint. */
+	forkedFrom?: TurnForkOrigin
+}
+
+/** @see Turn */
+export type AgentTurn = Turn
+
+/**
+ * The state of a session's active turn: the last `turn_started` whose
+ * `turnId` has no `turn_completed` or `turn_failed` yet.
+ *
+ *  - `paused` — its last segment record is `turn_paused`. Only
+ *    `resumeSession` (same `turnId`) or `abandonTurn` ends it.
+ *  - `running` — a live lease on the session is held.
+ *  - `interrupted` — no live lease and not paused: the process that ran it
+ *    is gone.
+ */
+export type ActiveTurnState = 'running' | 'paused' | 'interrupted'
+
+/**
+ * A session has at most one active turn. Starting another while one is
+ * running, paused or interrupted is refused with this error.
+ *
+ * Only an `interrupted` turn can be closed automatically, and only when the
+ * caller opts in (`beginTurn({ abandonInterrupted: true })`). A paused turn is
+ * never closed implicitly. Parallel work uses child sessions or separate
+ * sessions.
+ */
+export class TurnInProgressError extends Error {
+	override readonly name = 'TurnInProgressError' as const
+	readonly sessionId: SessionId
+	readonly activeTurnId: TurnId
+	readonly state: ActiveTurnState
+
+	constructor(params: { sessionId: SessionId; activeTurnId: TurnId; state: ActiveTurnState }) {
+		const remedy =
+			params.state === 'paused'
+				? 'Resume it with resumeSession or close it with abandonTurn.'
+				: params.state === 'interrupted'
+					? 'Its process is gone: resume it, abandon it, or begin the next turn with abandonInterrupted.'
+					: 'Wait for it to end, or cancel it.'
+		super(
+			`Session ${params.sessionId} already has an active turn ${params.activeTurnId} (${params.state}). ${remedy}`,
+		)
+		this.sessionId = params.sessionId
+		this.activeTurnId = params.activeTurnId
+		this.state = params.state
+	}
+}
+
+/**
+ * Recognises a {@link TurnInProgressError}, including one from another copy
+ * of this package, so a host protocol server can map it to its own error.
+ */
+export function isTurnInProgressError(value: unknown): value is TurnInProgressError {
+	if (value instanceof TurnInProgressError) return true
+	if (typeof value !== 'object' || value === null) return false
+	const candidate = value as Partial<TurnInProgressError>
+	return (
+		candidate.name === 'TurnInProgressError' &&
+		typeof candidate.sessionId === 'string' &&
+		typeof candidate.activeTurnId === 'string' &&
+		(candidate.state === 'running' ||
+			candidate.state === 'paused' ||
+			candidate.state === 'interrupted')
+	)
+}

package/src/types/structured-output/index.ts

@@ -25,13 +25,13 @@ export interface StructuredOutputConfig<TSchema extends z.ZodType = z.ZodType> {
 	 */
 	maxRetries?: number
 
-	/** Review the JSON-decoded result before settlement. Narrow the value before use: serialization may change schema output types. Exceptions fail the run; cancellation is propagated. */
+	/** Review the JSON-decoded result before settlement. Narrow the value before use: serialization may change schema output types. Exceptions fail the turn; cancellation is propagated. */
 	review?: (
 		output: unknown,
-		context: import('../run/answer-review.js').AnswerReviewContext,
+		context: import('../session/answer-review.js').AnswerReviewContext,
 	) =>
-		| import('../run/answer-review.js').AnswerReview
-		| Promise<import('../run/answer-review.js').AnswerReview>
+		| import('../session/answer-review.js').AnswerReview
+		| Promise<import('../session/answer-review.js').AnswerReview>
 	/** Corrections allowed after host rejection, separate from schema retries. Default 3; zero allows no correction. */
 	maxReviews?: number
 }

package/src/types/summary/deliverable.ts

@@ -17,7 +17,7 @@
  * handle all variants exhaustively.
  */
 
-import type { RunId, SessionId } from '../ids/index.js'
+import type { SessionId, TurnId } from '../ids/index.js'
 import type { DeliverableId, SummaryId } from '../session/ids.js'
 
 /** Discriminator for {@link DeliverableRef}. */
@@ -52,15 +52,15 @@ export interface SessionSummaryDeliverable {
 }
 
 /**
- * A specific persisted message within a session run — useful for referencing
+ * A specific persisted message within a session turn — useful for referencing
  * a single LLM turn as an artifact (e.g. a decision record).
  */
 export interface MessageDeliverable {
 	readonly id: DeliverableId
 	readonly kind: 'message'
 	readonly sessionId: SessionId
-	readonly runId: RunId
-	/** Opaque identifier bound to the run's persisted message log. */
+	readonly turnId: TurnId
+	/** The message's id in the session log. */
 	readonly messageId: string
 }
 

package/src/types/task/index.ts

@@ -1,4 +1,4 @@
-import type { RunId, TaskId, TenantId } from '../ids/index.js'
+import type { SessionId, TaskId, TenantId, TurnId } from '../ids/index.js'
 
 /**
  * `failed` exists because a unit that did not succeed had nowhere to say so.
@@ -40,7 +40,10 @@ export function assertTaskStatus(status: TaskStatus): void {
 
 export interface Task {
 	readonly id: TaskId
-	readonly runId: RunId
+	/** The session the task belongs to (`<session-id>/tasks/`). */
+	readonly sessionId: SessionId
+	/** The turn that created the task. */
+	readonly turnId: TurnId
 	readonly tenantId?: TenantId
 
 	subject: string
@@ -77,7 +80,8 @@ export interface TaskEvent {
 export type TaskEventListener = (event: TaskEvent) => void
 
 export interface CreateTaskParams {
-	runId: RunId
+	sessionId: SessionId
+	turnId: TurnId
 	tenantId?: TenantId
 	subject: string
 	description?: string
@@ -101,7 +105,7 @@ export interface TaskStore {
 	get(id: TaskId): Promise<Task | undefined>
 	update(id: TaskId, updates: UpdateTaskParams): Promise<Task | undefined>
 	delete(id: TaskId): Promise<boolean>
-	list(filter?: { status?: TaskStatus; owner?: string; runId?: RunId }): Promise<Task[]>
+	list(filter?: { status?: TaskStatus; owner?: string; sessionId?: SessionId }): Promise<Task[]>
 
 	claim(id: TaskId, owner: string): Promise<Task | undefined>
 

package/src/types/tool/index.ts

@@ -6,7 +6,7 @@ import type { CodeNavigationProvider } from '../code-navigation/index.js'
 // the guardrails is described here. Erased at compile time, so neither
 // module exists at runtime to depend on the other.
 import type { ToolResultGuardrailSpec } from '../guardrail/index.js'
-import type { RunId } from '../ids/index.js'
+import type { SessionId, TurnId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { Sandbox } from '../sandbox/index.js'
@@ -92,7 +92,7 @@ export interface SkillRegistryRef {
  * `ToolRegistryRef` exists: this type file is imported by everything, and
  * naming the implementation here would drag a `node:child_process` module
  * into every consumer's type graph. `owner` is not on this surface at all —
- * the executor binds it to the run, so a tool cannot start a job that
+ * the executor binds it to the turn, so a tool cannot start a job that
  * outlives, or is billed to, somebody else's run.
  */
 export interface BackgroundJobRegistryRef {
@@ -129,12 +129,12 @@ export interface BackgroundJobRegistryRef {
 		exitCode?: number
 	}>
 	/**
-	 * Say that the model is waiting on this job, so the run stays open for it
+	 * Say that the model is waiting on this job, so the turn stays open for it
 	 * when the model stops calling tools.
 	 *
 	 * Called by `wait_for_job` and nothing else. The kernel holds a finishing
 	 * run open — bounded, and for no model tokens — only for a job marked
-	 * here; a job nobody marked never delays a run, which is what a dev server
+	 * here; a job nobody marked never delays a turn, which is what a dev server
 	 * or a watcher needs. Optional for the reason `waitForExit` is: a host
 	 * implementing this interface directly may have nowhere to record the
 	 * intent, and then there is simply no hold.
@@ -143,7 +143,7 @@ export interface BackgroundJobRegistryRef {
 }
 
 /**
- * Tracks which files the agent has read in the current run.
+ * Tracks which files the agent has read in the current turn.
  * Write tool consults this to enforce the "read before overwrite" invariant
  * an existing file must be read first or the write fails.
  * Keys are the resolved path used by the tool — sandbox-relative when a sandbox
@@ -340,26 +340,52 @@ export interface ToolContext {
 	 * deadline; an optional signal can cancel capture earlier. Never replays
 	 * effects. Unsupported stores return undefined.
 	 */
-	captureRunEvidence?: (
+	captureSessionEvidence?: (
 		maxReadBytes?: number,
 		signal?: AbortSignal,
-	) => Promise<import('../../store/evidence/types.js').RunTextEvidenceSource | undefined>
+	) => Promise<import('../../store/evidence/types.js').SessionTextEvidenceSource | undefined>
 
-	runId: RunId
+	/** The session this call belongs to. */
+	sessionId: SessionId
+	/** The turn this call belongs to. */
+	turnId: TurnId
 	workingDirectory: string
 	/**
 	 * Directories besides the working directory the file tools may reach,
-	 * absolute. A host adds one for a session (`/add-dir`); a sandboxed run
+	 * absolute. A host adds one for a session (`/add-dir`); a sandboxed turn
 	 * binds each. Relative paths still resolve against the working
 	 * directory; an absolute path inside any of these is accepted.
 	 */
 	additionalDirectories?: readonly string[]
+	/**
+	 * Absolute paths outside the working directory and the added directories
+	 * that THIS call was approved to reach.
+	 *
+	 * Set by the executor only for a call a review approved after the
+	 * kernel named these paths in it (`ToolCallSummary.escalation`), and only
+	 * when the turn asked for that (`QueryParams.outsideRootAccess:
+	 * 'review'`). The file tools treat each as one more root for this call
+	 * alone; nothing here widens the next call. Absent is the ordinary case:
+	 * a path outside the roots is refused.
+	 */
+	approvedPaths?: readonly string[]
+	/**
+	 * This call was approved to run outside the turn's sandbox.
+	 *
+	 * Set by the executor only when a reviewer CONFIRMED the escape for this
+	 * call by id (`HITLResumeDecision.confirmedEscalations`) and the turn
+	 * allows escapes at all (`QueryParams.sandboxEscape: 'review'`). A tool
+	 * that offers an escape honours it only when this is `true`, and refuses
+	 * the request otherwise.
+	 */
+	sandboxEscapeApproved?: boolean
 	abortSignal: AbortSignal
 	env: Record<string, string>
 	log: (level: 'info' | 'warn' | 'error', message: string) => void
 	permissionContext?: {
 		mode: PermissionMode
-		runId: string
+		sessionId: string
+		turnId: string
 		workingDirectory: string
 	}
 
@@ -382,7 +408,7 @@ export interface ToolContext {
 	allowedTools?: readonly string[]
 	sandbox?: Sandbox
 	/**
-	 * Symbol resolution for this run, when a host wired one up.
+	 * Symbol resolution for this turn, when a host wired one up.
 	 *
 	 * Absent means the `lsp` tool is not registered at all — see
 	 * `tools/builtins/lsp.ts` for why a tool that is always present and
@@ -409,14 +435,14 @@ export interface ToolContext {
 	/**
 	 * Where the `skill` tool reads from.
 	 *
-	 * Absent means the run has no skills, and the tool says so rather than
+	 * Absent means the turn has no skills, and the tool says so rather than
 	 * reporting an empty list — "no skills here" and "no registry" are
 	 * different answers.
 	 */
 	skills?: SkillRegistryRef
 
 	/**
-	 * How this run reaches the web.
+	 * How this turn reaches the web.
 	 *
 	 * Two independent halves, and either may be absent. This kernel ships a
 	 * guarded fetch provider and NO search backend, so `search` missing is
@@ -470,9 +496,9 @@ export interface ToolContext {
 	maxToolOutputChars?: number
 
 	/**
-	 * Screens the RUN asked for, applied to results this call produces.
+	 * Screens the TURN asked for, applied to results this call produces.
 	 *
-	 * Worth having because a run usually does not build its registry: a host
+	 * Worth having because a turn usually does not build its registry: a host
 	 * assembles one and hands it to `runAgent`, so a registry-construction
 	 * option alone is the host's to write and the kernel's default reaches
 	 * nobody.
@@ -481,9 +507,9 @@ export interface ToolContext {
 	 * the registry was built with them — including an empty array, which means
 	 * none — because a registry that stated its policy has stated it. These
 	 * apply to a registry that declared none, which is the ordinary case: a
-	 * host assembles a registry and hands it to a run it does not own.
+	 * host assembles a registry and hands it to a turn it does not own.
 	 *
-	 * `undefined` means the run declared none; an empty array means the run
+	 * `undefined` means the turn declared none; an empty array means the turn
 	 * declared none ON PURPOSE, which is how a caller turns off a screen the
 	 * executor would otherwise install by default.
 	 */
@@ -505,7 +531,7 @@ export interface ToolContext {
 	 *
 	 * Tools are host-installed code — the model cannot add one — so the trust
 	 * boundary this protects is the MODEL's reach. `allowedTools` is enforced
-	 * again at dispatch. When the run has an operator authorization gate, a
+	 * again at dispatch. When the turn has an operator authorization gate, a
 	 * nested call must be explicitly allowed by that gate; a deny or an
 	 * undecided call fails closed because another durable human review cannot
 	 * be opened from inside the already-executing parent.
@@ -527,13 +553,13 @@ export interface ToolContext {
 	toolUseId?: string
 
 	/**
-	 * Stable, run-scoped identity shared by every direct tool call the model
+	 * Stable, turn-scoped identity shared by every direct tool call the model
 	 * issued in the same response batch.
 	 *
 	 * `toolUseId` answers "which call is this?"; this answers "which sibling
 	 * calls were launched together?". Hosts use it to keep a concurrent group
 	 * visible while one sibling is still running without accidentally reviving
-	 * terminal work from an older batch or another run whose provider reused a
+	 * terminal work from an older batch or another turn whose provider reused a
 	 * call id. Optional because a host may invoke a tool directly, outside the
 	 * query executor.
 	 */
@@ -543,7 +569,7 @@ export interface ToolContext {
 	 * How this execution entered the tool registry.
 	 *
 	 * Present on executor-owned calls. Optional because a host may invoke a
-	 * tool directly outside a run and construct its own minimal context.
+	 * tool directly outside a turn and construct its own minimal context.
 	 */
 	source?: ToolCallSource
 
@@ -565,7 +591,7 @@ export interface ToolContext {
 	 * own, and one tool may pause more than once.
 	 *
 	 * Absent when whatever is driving the tool provides no route to a
-	 * human — a host calling a tool directly, outside a run. A tool must
+	 * human — a host calling a tool directly, outside a turn. A tool must
 	 * treat it as optional and decide what to do without one, and must
 	 * never read an unanswered pause as consent; the outcome says which it
 	 * was, in its own shape, so silence cannot be destructured into a yes.
@@ -642,7 +668,7 @@ export interface ToolResult {
 	 */
 	retryable?: boolean
 	/**
-	 * Facts this result pins into the run's working memory, by key. The
+	 * Facts this result pins into the turn's working memory, by key. The
 	 * kernel keeps them in the working-memory slot — in front of the model
 	 * every iteration, across compaction — and a later pin under the same
 	 * key replaces the earlier one. For what a tool knows and the model
@@ -711,13 +737,34 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * chaining — has nothing to decompose and must not claim otherwise.
 	 */
 	commandArgument?: string
+	/**
+	 * The argument that holds a filesystem path the tool resolves against the
+	 * turn's roots (the working directory and the added directories).
+	 *
+	 * Declared so the kernel can see, BEFORE the call runs, that it names a
+	 * path outside those roots and turn it into an approval request instead
+	 * of a refusal (`QueryParams.outsideRootAccess: 'review'`). A tool that
+	 * does not declare it keeps refusing such a path at execution, which is
+	 * the safe direction to be wrong in.
+	 */
+	pathArgument?: string
+	/**
+	 * The boolean argument by which a call asks to run outside the turn's
+	 * sandbox, when the tool offers that at all (the shipped `bash` does).
+	 *
+	 * A call that sets it under a sandbox is always reviewed, is never
+	 * approved by a mode, a remembered grant or an `allow` rule, and runs
+	 * unconfined only when a reviewer confirmed it by id. See
+	 * `ToolContext.sandboxEscapeApproved`.
+	 */
+	sandboxEscapeArgument?: string
 	execute(input: TInput, context: ToolContext): Promise<ToolResult>
 	tier?: string
 	permissions?: ToolPermission[]
 	category?: 'filesystem' | 'shell' | 'network' | 'analysis' | 'custom'
 
 	/**
-	 * Deadline for a single execution, overriding the run-level default.
+	 * Deadline for a single execution, overriding the turn-level default.
 	 *
 	 * On expiry the executor stops waiting and returns a model-visible
 	 * error result, so a slow dependency becomes something the agent can
@@ -747,21 +794,21 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	maxRetries?: number
 
 	/**
-	 * This tool's output IS the run's answer: settle with it instead of
+	 * This tool's output IS the turn's answer: settle with it instead of
 	 * asking the model to restate it.
 	 *
 	 * Every delegation path is blocking and returns the worker's final
 	 * text as the dispatching call's result, after which the loop went
 	 * round again — so a router agent, whose entire job is to pick a
 	 * specialist, paid one extra model call per request at the parent's
-	 * full context size, the most expensive call in the run. The relay is
+	 * full context size, the most expensive call in the turn. The relay is
 	 * also LOSSY: the parent paraphrases the worker's answer through its
 	 * own (compacted) context, so what the caller receives is not what the
 	 * worker produced.
 	 *
 	 * Honoured only when the terminal call is the ONLY call in the turn
 	 * and it did not fail. A model that asked for other work in the same
-	 * turn meant to see those results, and ending the run would discard
+	 * turn meant to see those results, and ending the turn would discard
 	 * answers it requested; that turn takes the ordinary path and the
 	 * reason is logged. A failed terminal call is not an answer either —
 	 * the error goes back to the model, which is the point of returning