@namzu/sdk 30.2.0 → 31.0.0

package/src/types/provider/interface.ts

@@ -52,7 +52,8 @@ export interface LLMProvider {
 	 */
 	chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk>
 
-	listModels?(): Promise<ModelInfo[]>
+	/** Optional cancellation belongs to the surface asking for this menu. */
+	listModels?(signal?: AbortSignal): Promise<ModelInfo[]>
 
 	/**
 	 * Establish whether this credential actually works. Resolves if it does,
@@ -87,7 +88,7 @@ export interface LLMProvider {
 	 * as a bad key would tell an operator on broken wifi to go and rotate a
 	 * credential that is fine.
 	 */
-	probeCredential?(): Promise<void>
+	probeCredential?(signal?: AbortSignal): Promise<void>
 
 	/**
 	 * Is this driver able to serve traffic? A summary bit; `doctorCheck` is
@@ -132,11 +133,12 @@ export interface LLMProvider {
 	 * the start rather than a quieter one. Building that choice needs the
 	 * answer BEFORE the request exists.
 	 *
-	 * There are three states and they mean different things:
+	 * There are four states and they mean different things:
 	 *
-	 * - **method absent** — this driver has no effort concept at all. Setting
-	 *   `effort` on a run using it is refused, not ignored, so a caller should
-	 *   offer no control rather than a disabled one.
+	 * - **method absent** — this driver cannot enumerate effort for any model.
+	 * - **`undefined`** — the driver understands effort, but cannot establish
+	 *   the levels for this model id. Compatible endpoints with private model
+	 *   names are the common case. A caller must not fabricate a picker.
 	 * - **empty array** — the driver implements effort and THIS model has no
 	 *   levels. A real answer, not a missing one.
 	 * - **non-empty** — offer exactly these, and nothing else.
@@ -156,6 +158,18 @@ export interface LLMProvider {
 	 * stale on the next model release and goes stale SILENTLY — surfacing as
 	 * a vendor rejection rather than a failing build.
 	 */
+	reasoningEffortLevelsFor?(
+		model: string,
+		thinking?: import('./chat.js').ThinkingConfig,
+	): readonly import('./chat.js').ReasoningEffort[] | undefined
+
+	/**
+	 * Legacy effort menu which cannot distinguish an unknown model from a model
+	 * with no effort support.
+	 *
+	 * @deprecated Implement and consume {@link LLMProvider.reasoningEffortLevelsFor}
+	 * instead. Kept for one compatibility window; decorators still preserve it.
+	 */
 	effortLevelsFor?(
 		model: string,
 		thinking?: import('./chat.js').ThinkingConfig,
@@ -173,7 +187,8 @@ export interface LLMProvider {
 	 * parses a real per-model `context_length` off the vendor listing and
 	 * throws it away, because there was no member to return it through.
 	 *
-	 * Three states, exactly like {@link LLMProvider.effortLevelsFor}: the
+	 * Three states, like the non-empty half of
+	 * {@link LLMProvider.reasoningEffortLevelsFor}: the
 	 * member ABSENT means this driver cannot answer at all; a resolved
 	 * `undefined` means it asked and does not know; a number is the answer.
 	 * The three are different facts and collapsing any two of them turns

package/src/types/provider/stream.ts

@@ -2,6 +2,12 @@ import type { TokenUsage } from '../common/index.js'
 
 export interface StreamChunk {
 	id: string
+	/**
+	 * Adapter-private lossless-JSON state for replaying the completed native
+	 * assistant response. Emitted only once the state is complete; aggregators
+	 * retain the last defined value and the query stores it in message source.
+	 */
+	replayState?: unknown
 	delta: {
 		content?: string
 		toolCalls?: Array<{

package/src/types/rag/embedding.ts

@@ -1,15 +1,24 @@
+import type { RAGOperationOptions } from './scope.js'
+
 export interface EmbeddingProvider {
 	readonly id: string
 	readonly model: string
 	readonly dimensions: number
 
-	embed(texts: string[]): Promise<number[][]>
-	embedQuery(query: string): Promise<number[]>
+	/**
+	 * Implementations should stop owned I/O when `options.signal` aborts.
+	 * A caller still bounds its own wait: a custom provider may be
+	 * non-cooperative, just as any other host-supplied implementation may be.
+	 */
+	embed(texts: string[], options?: RAGOperationOptions): Promise<number[][]>
+	embedQuery(query: string, options?: RAGOperationOptions): Promise<number[]>
 }
 
 export interface EmbeddingConfig {
 	model: string
+	/** Expected positive vector width. HTTP responses with another width are refused. */
 	dimensions?: number
+	/** Positive number of inputs sent in one operation. */
 	batchSize?: number
 }
 
@@ -25,4 +34,9 @@ export interface HttpEmbeddingConfig extends EmbeddingConfig {
 	apiKey: string
 	/** Root of an embeddings API; `/embeddings` is appended. */
 	baseUrl: string
+	/**
+	 * Whole-request bound for each HTTP batch, including response-body reads.
+	 * Defaults to 30 seconds. Set `0` to preserve the former unbounded behavior.
+	 */
+	requestTimeoutMs?: number
 }

package/src/types/rag/ingestion.ts

@@ -1,5 +1,5 @@
 import type { DocumentId, KnowledgeBaseId } from '../ids/index.js'
-import type { DocumentMetadata, TenantScope } from './scope.js'
+import type { DocumentMetadata, RAGOperationOptions, TenantScope } from './scope.js'
 
 export interface IngestionResult {
 	documentId: DocumentId
@@ -14,6 +14,7 @@ export interface IngestionPipeline {
 		metadata: DocumentMetadata,
 		scope: TenantScope,
 		knowledgeBaseId: KnowledgeBaseId,
+		options?: RAGOperationOptions,
 	): Promise<IngestionResult>
 
 	remove(documentId: DocumentId): Promise<void>

package/src/types/rag/knowledge-base.ts

@@ -3,7 +3,7 @@ import type { ChunkingConfig } from './chunking.js'
 import type { EmbeddingConfig } from './embedding.js'
 import type { IngestionResult } from './ingestion.js'
 import type { RetrievalConfig, RetrievalQuery, RetrievalResult } from './retrieval.js'
-import type { DocumentMetadata } from './scope.js'
+import type { DocumentMetadata, RAGOperationOptions } from './scope.js'
 
 export interface KnowledgeBaseConfig {
 	id?: KnowledgeBaseId
@@ -20,8 +20,12 @@ export interface KnowledgeBase {
 	readonly id: KnowledgeBaseId
 	readonly config: KnowledgeBaseConfig
 
-	ingest(content: string, metadata?: DocumentMetadata): Promise<IngestionResult>
+	ingest(
+		content: string,
+		metadata?: DocumentMetadata,
+		options?: RAGOperationOptions,
+	): Promise<IngestionResult>
 	remove(documentId: DocumentId): Promise<void>
-	query(query: RetrievalQuery): Promise<RetrievalResult>
+	query(query: RetrievalQuery, options?: RAGOperationOptions): Promise<RetrievalResult>
 	clear(): Promise<void>
 }

package/src/types/rag/retrieval.ts

@@ -1,6 +1,6 @@
 import type { KnowledgeBaseId } from '../ids/index.js'
 import type { ProjectId } from '../session/ids.js'
-import type { TenantScope } from './scope.js'
+import type { RAGOperationOptions, TenantScope } from './scope.js'
 import type { VectorSearchResult } from './vector.js'
 
 export type RetrievalMode = 'vector' | 'keyword' | 'hybrid'
@@ -48,5 +48,6 @@ export interface Retriever {
 		query: RetrievalQuery,
 		scope: TenantScope,
 		knowledgeBaseId?: KnowledgeBaseId,
+		options?: RAGOperationOptions,
 	): Promise<RetrievalResult>
 }

package/src/types/rag/scope.ts

@@ -5,6 +5,11 @@ export interface TenantScope {
 	namespace?: string
 }
 
+/** Cancellation shared by one public RAG operation and its downstream I/O. */
+export interface RAGOperationOptions {
+	readonly signal?: AbortSignal
+}
+
 export interface DocumentMetadata {
 	source?: string
 	title?: string

package/src/types/rag/vector.ts

@@ -1,4 +1,5 @@
 import type { ChunkId, DocumentId, KnowledgeBaseId, TenantId } from '../ids/index.js'
+import type { RAGOperationOptions } from './scope.js'
 import type { Chunk } from './storage.js'
 
 export interface VectorSearchResult {
@@ -27,8 +28,10 @@ export interface VectorStoreQuery {
 }
 
 export interface VectorStore {
-	upsert(chunks: Chunk[]): Promise<void>
-	search(query: VectorStoreQuery): Promise<VectorSearchResult[]>
+	/** Persist chunks, stopping owned I/O when the operation is cancelled. */
+	upsert(chunks: Chunk[], options?: RAGOperationOptions): Promise<void>
+	/** Search chunks, stopping owned I/O when the operation is cancelled. */
+	search(query: VectorStoreQuery, options?: RAGOperationOptions): Promise<VectorSearchResult[]>
 	delete(chunkIds: ChunkId[]): Promise<void>
 	deleteByDocument(documentId: DocumentId): Promise<void>
 	deleteByKnowledgeBase(knowledgeBaseId: KnowledgeBaseId, tenantId: TenantId): Promise<void>

package/src/types/run/config.ts

@@ -8,6 +8,26 @@ import type { CheckpointStore } from './checkpoint-store.js'
 export interface AgentRunConfig {
 	model: string
 	timeoutMs: number
+	/**
+	 * Maximum silence between provider stream chunks, in milliseconds.
+	 *
+	 * Defaults to five minutes at the `query()` boundary. This is distinct
+	 * from `timeoutMs`, which is checked between agent iterations and cannot
+	 * settle a provider iterator whose pending `next()` never returns. Set
+	 * `0` to retain unbounded stream silence. Positive values must be integer
+	 * milliseconds accepted by the platform timer.
+	 */
+	streamIdleTimeoutMs?: number
+	/**
+	 * Maximum accumulated inline image/document payload on one provider request.
+	 *
+	 * Defaults to 24 MiB. The budget is shared by user attachments and rich
+	 * tool-result blocks. When history exceeds it, the provider-bound projection
+	 * replaces the oldest values with model-visible omission markers; the run's
+	 * canonical messages and durable evidence remain unchanged. Set `0` to keep
+	 * the prior unbounded behaviour.
+	 */
+	maxRequestRichContentBytes?: number
 	maxResponseTokens?: number
 
 	/**

package/src/types/run/events.ts

@@ -581,15 +581,33 @@ type CoreRunEvent =
 	// run when the request asks for something the provider DRIVER declared
 	// it cannot do — tools registered against a no-tools driver (tool
 	// surfaces stripped so the model is never told about uncallable
-	// tools), or image attachments against a no-vision driver (attachments
-	// dropped). Hosts surface these so degradation is visible, not silent.
+	// tools), image attachments against a no-vision driver, or document
+	// attachments against a no-documents driver. Hosts surface these so
+	// degradation is visible, not silent.
 	| {
 			type: 'capability_warning'
 			runId: RunId
-			capability: 'tools' | 'vision'
+			capability: 'tools' | 'vision' | 'documents'
 			providerId: string
 			message: string
 	  }
+	/**
+	 * Provider-invalid tool history was repaired before the first model call.
+	 *
+	 * Counts, not content: a host can surface and audit the rewrite without
+	 * copying tool output or conversation secrets into its event channel.
+	 * `fresh-history` names caller-supplied history. `abandoned-checkpoint`
+	 * excludes any incomplete turn still owned by a durable pending/recovered
+	 * resume plan; that turn is completed by its authority path instead.
+	 */
+	| {
+			type: 'message_history_repaired'
+			runId: RunId
+			source: 'fresh-history' | 'abandoned-checkpoint'
+			duplicateToolResultsRemoved: number
+			orphanedToolResultsRemoved: number
+			syntheticToolResultsInserted: number
+	  }
 	| {
 			type: 'token_usage_updated'
 			runId: RunId
@@ -623,6 +641,13 @@ type CoreRunEvent =
 			 * Absent when the run has no compaction configuration, because
 			 * nothing then resolves a window and inventing one would be the
 			 * guess this exists to replace.
+			 *
+			 * This is a state snapshot, not merely a receipt for a model call.
+			 * It is also emitted immediately after an automatic context edit:
+			 * cumulative `usage`/`cost` may be unchanged (or may include a
+			 * verifier call) while `contextTokens` falls to its post-edit
+			 * estimate. Hosts therefore need not wait for another provider
+			 * response to learn that compaction made room.
 			 */
 			contextTokens?: number
 			contextMeasuredBy?: 'provider' | 'estimate'

package/src/types/run/metadata.ts

@@ -42,6 +42,8 @@ export interface RunConfigSnapshot {
 	model: string
 	tokenBudget: number
 	timeoutMs: number
+	streamIdleTimeoutMs?: number
+	maxRequestRichContentBytes?: number
 	maxIterations?: number
 	temperature?: number
 	maxResponseTokens?: number

package/src/types/run/step.ts

@@ -1,6 +1,6 @@
 import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { MessageId } from '../ids/index.js'
-import type { ToolCall } from '../message/index.js'
+import type { ProviderRoute, ToolCall } from '../message/index.js'
 import type { ProviderErrorCode } from '../provider/errors.js'
 
 /**
@@ -125,12 +125,7 @@ export interface StepResult {
  * the same provider twice — two models, or two credentials, on one driver.
  * `providerId` alone could not tell those apart.
  */
-export interface StepProvenance {
-	readonly providerId: string
-	readonly model: string
-	/** 0 is the head, i.e. the provider the run was configured with. */
-	readonly chainIndex: number
-}
+export interface StepProvenance extends ProviderRoute {}
 
 /**
  * Why a step ended in `finishReason: 'error'`.

package/src/types/run/store.ts

@@ -27,10 +27,40 @@
  * re-keyed per call, it happens once, deliberately, as its own change.
  */
 
+import type { Message } from '../message/index.js'
 import type { AuditEvent } from './audit.js'
 import type { Run } from './entity.js'
 import type { PersistedRunEvent, RunEvent } from './events.js'
 
+/**
+ * The run's surviving message history, and whether it can be placed against
+ * the durable event log without guessing.
+ *
+ * `available` is stronger than "some bytes were found": `throughEventSeq`
+ * names the exact event-log head the snapshot was published after. A caller
+ * can therefore refuse a stale snapshot left by an earlier pause or a crash
+ * during final persistence instead of presenting it as the whole run.
+ *
+ * `legacy-unverified` preserves read access to the raw message arrays written
+ * before snapshots carried that boundary. Those messages are real, but no
+ * stored fact proves which event-log head they represent, so they must not be
+ * used to claim a complete transcript.
+ */
+export type RunMessageSnapshot =
+	| {
+			readonly kind: 'available'
+			readonly throughEventSeq: number
+			readonly messages: readonly Message[]
+	  }
+	| {
+			readonly kind: 'legacy-unverified'
+			readonly messages: readonly Message[]
+	  }
+	| {
+			readonly kind: 'unavailable'
+			readonly reason: 'not-persisted'
+	  }
+
 /** What a caller asks the log for. See {@link RunStore.readEvents}. */
 export interface ReadRunEventsOptions {
 	/**
@@ -41,6 +71,17 @@ export interface ReadRunEventsOptions {
 	 * delivered twice. Absent means the whole log.
 	 */
 	readonly sinceSeq?: number
+	/**
+	 * Refuse a disk transcript with a torn, malformed, or discontinuously
+	 * numbered record instead of skipping past it.
+	 *
+	 * The default stays `tolerant`: an incident viewer is usually better served
+	 * by every intact event around one damaged line. A caller making a
+	 * completeness claim — an export, a replay proof, an archive — chooses
+	 * `strict`, because one skipped line makes that claim false even when the
+	 * rest of the log remains useful.
+	 */
+	readonly integrity?: 'tolerant' | 'strict'
 }
 
 /**
@@ -72,8 +113,25 @@ export interface RunStore {
 	/** Persist the run record: status, metadata, usage, timings. */
 	writeRunMeta(run: Run): Promise<void>
 
-	/** Persist the run's full message history. */
-	writeMessages(run: Run): Promise<void>
+	/**
+	 * Publish the run's surviving message history through a durable event.
+	 *
+	 * The boundary is required. Messages are written after the terminal or
+	 * pause event, and a resumed run reuses the same run id; without the
+	 * boundary an older, valid file is indistinguishable from the current
+	 * run's final snapshot.
+	 */
+	writeMessages(run: Run, throughEventSeq: number): Promise<void>
+
+	/**
+	 * Read the published message snapshot back.
+	 *
+	 * Missing data is `unavailable`, never an available empty list. An empty
+	 * list is a real snapshot only after {@link RunStore.writeMessages}
+	 * explicitly published it. This distinction closes the crash window where
+	 * the run's terminal event and metadata landed but its messages did not.
+	 */
+	readMessages(): Promise<RunMessageSnapshot>
 
 	/**
 	 * Append one event to the run's durable event log.

package/src/types/sandbox/index.ts

@@ -31,7 +31,25 @@ export function assertSandboxStatus(status: SandboxStatus): void {
 // Sandbox environment — detected platform capability
 // ---------------------------------------------------------------------------
 
-export type SandboxEnvironment = 'linux-namespace' | 'macos-seatbelt' | 'basic'
+export type SandboxEnvironment = 'linux-bwrap' | 'linux-namespace' | 'macos-seatbelt' | 'basic'
+
+/**
+ * Every tier, in the order a detector prefers them: strongest first.
+ *
+ * Exported because the alternative is what was there — a hand-written
+ * alternation in a doctor test that had to be edited by whoever added a tier,
+ * and was not, so the first new tier in a year failed a test that was
+ * describing the tier list rather than checking anything about it.
+ *
+ * `assertSandboxEnvironment` reads this too, so the union, the runtime list and
+ * the exhaustive check cannot drift apart.
+ */
+export const SANDBOX_ENVIRONMENTS: readonly SandboxEnvironment[] = [
+	'linux-bwrap',
+	'macos-seatbelt',
+	'linux-namespace',
+	'basic',
+]
 
 /**
  * A security control a sandbox tier either provides or does not.
@@ -60,16 +78,11 @@ export const SANDBOX_ISOLATION_CONTROLS: readonly SandboxIsolationControl[] = [
 export type SandboxIsolationReport = Readonly<Record<SandboxIsolationControl, boolean>>
 
 export function assertSandboxEnvironment(env: SandboxEnvironment): void {
-	switch (env) {
-		case 'linux-namespace':
-		case 'macos-seatbelt':
-		case 'basic':
-			return
-		default: {
-			const _exhaustive: never = env
-			throw new Error(`Unknown SandboxEnvironment: ${_exhaustive}`)
-		}
-	}
+	// Membership, not a switch. A `case` per tier is a second list to keep in
+	// step with the union, and the switch's `never` arm only catches a tier
+	// ADDED to the union — never one added here and forgotten there.
+	if (SANDBOX_ENVIRONMENTS.includes(env)) return
+	throw new Error(`Unknown SandboxEnvironment: ${env}`)
 }
 
 // ---------------------------------------------------------------------------
@@ -207,7 +220,8 @@ export interface Sandbox {
 	setNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>
 
 	/**
-	 * Open a real pseudo-terminal inside this sandbox.
+	 * Open a real pseudo-terminal whose complete process tree is confined to
+	 * and owned by this sandbox.
 	 *
 	 * Optional, and a backend that cannot provide one must **throw** rather
 	 * than hand back a pipe — the same rule {@link Sandbox.setNetworkPolicy}
@@ -217,7 +231,14 @@ export interface Sandbox {
 	 * exits immediately, the progress bar prints ten thousand lines, and
 	 * nothing says why.
 	 *
-	 * See `sandbox/terminal.ts` for why the backing binding is optional.
+	 * A backend that implements this method MUST make {@link destroy} kill and
+	 * await every terminal it returned. Merely starting a host pseudo-terminal
+	 * with `rootDir` as its working directory does not satisfy either the
+	 * confinement or the ownership contract.
+	 *
+	 * @deprecated No built-in backend currently satisfies both guarantees.
+	 * Use a separately owned terminal backend; this member will be removed in
+	 * a future major release after the repository's deprecation window.
 	 */
 	openTerminal?(options: OpenTerminalOptions): Promise<TerminalSession>
 	writeFile(path: string, content: string | Buffer): Promise<void>
@@ -242,7 +263,20 @@ export interface Sandbox {
 	 * MAY throw for other I/O failures.
 	 */
 	listFiles(rootPath: string): Promise<readonly SandboxFileEntry[]>
-	destroy(): Promise<void>
+	/**
+	 * Release every resource owned by this sandbox.
+	 *
+	 * The signal belongs to a fresh teardown operation, not to the run that is
+	 * already ending. Implementations should stop their teardown transport and
+	 * settle promptly when it aborts. Hosts may still impose an independent
+	 * wait bound because a third-party implementation can ignore the signal.
+	 */
+	destroy(options?: SandboxDestroyOptions): Promise<void>
+}
+
+/** Authority for a teardown operation owned independently of the ending run. */
+export interface SandboxDestroyOptions {
+	readonly signal?: AbortSignal
 }
 
 // ---------------------------------------------------------------------------
@@ -418,6 +452,15 @@ export interface ResolvedContainerSandboxLayout {
 // ---------------------------------------------------------------------------
 
 export interface SandboxCreateConfig {
+	/**
+	 * Withdraws authority to publish the allocation to the run.
+	 *
+	 * Providers should stop their transport and reconcile any resource they can
+	 * identify. This signal is not, by itself, proof that a remote allocation
+	 * was rolled back: a service that commits before returning its identifier
+	 * still needs a client-owned reconciliation key or an external reaper.
+	 */
+	readonly signal?: AbortSignal
 	readonly workingDirectory?: string
 	readonly env?: Record<string, string>
 	readonly timeoutMs?: number

package/src/types/session/store.ts

@@ -321,6 +321,24 @@ export interface SessionStore {
 	 */
 	appendMessage(sessionId: SessionId, message: Message, tenantId: TenantId): Promise<MessageId>
 
+	/**
+	 * Replace the conversation view with a compacted history. OPTIONAL.
+	 *
+	 * This is not deletion of the underlying log. A durable implementation may
+	 * append one replacement record and project every later read from it, which
+	 * keeps the write atomic while preserving the earlier records for recovery.
+	 *
+	 * Optional because existing hosts implement this interface, and manual
+	 * compaction is a host capability rather than a requirement every store must
+	 * gain. A caller that offers durable compaction checks for it and refuses to
+	 * claim persistence when the store cannot perform the replacement.
+	 */
+	replaceMessages?(
+		sessionId: SessionId,
+		messages: readonly Message[],
+		tenantId: TenantId,
+	): Promise<void>
+
 	/**
 	 * Load the full message history for a session in insertion order.
 	 * Returns an empty array when the session has no messages.

package/src/types/tool/index.ts

@@ -18,16 +18,6 @@ export interface ToolRegistryRef {
 	getAvailability(name: string): ToolAvailability
 }
 
-/**
- * The slice of the background job registry a tool is given.
- *
- * A structural reference rather than the class, for the reason
- * `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
- * outlives, or is billed to, somebody else's run.
- */
 /**
  * The slice of the skills registry a tool is given.
  *
@@ -67,6 +57,16 @@ export interface SkillRegistryRef {
 	names(): readonly string[]
 }
 
+/**
+ * The slice of the background job registry a tool is given.
+ *
+ * A structural reference rather than the class, for the reason
+ * `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
+ * outlives, or is billed to, somebody else's run.
+ */
 export interface BackgroundJobRegistryRef {
 	start(params: { command: string; workingDirectory: string }): { id: string; status: string }
 	get(id: string): { id: string; status: string; exitCode?: number }
@@ -207,7 +207,9 @@ export interface ToolContext {
 	 * `linux-namespace` tier the wrapping `sh` is PID 1 of a fresh PID
 	 * namespace, so a backgrounded grandchild dies the moment that shell
 	 * exits, on the successful path. It returns in milliseconds looking like
-	 * it worked, with the work already dead.
+	 * it worked, with the work already dead. It is also absent from sandboxed
+	 * query-built contexts: the shipped registry owns host processes and
+	 * cannot preserve a sandbox boundary.
 	 */
 	backgroundJobs?: BackgroundJobRegistryRef
 
@@ -415,6 +417,26 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * request.
 	 */
 	outputSchema?: Record<string, unknown>
+	/**
+	 * The argument that holds a shell command line, when one does.
+	 *
+	 * Declared on the tool because only the tool knows. An operator writing
+	 * `bash = { "git status*" = "allow" }` means the `command` argument, and
+	 * every other way of learning that is a list somewhere else that drifts:
+	 * a host compiling permissions has the tool's NAME and no reason to know
+	 * which of its arguments is the interesting one.
+	 *
+	 * What it buys is the difference between a permission about text and a
+	 * permission about commands. A rule routed through this argument reads
+	 * `git status && rm -rf ~` as the two commands it is, so an `allow`
+	 * written for `git status*` declines it instead of approving it on the
+	 * strength of the first few words. See `decomposeCommandLine`.
+	 *
+	 * Omit it on every tool that takes no command line. A tool that runs
+	 * something but takes an argument list rather than a line — no shell, no
+	 * chaining — has nothing to decompose and must not claim otherwise.
+	 */
+	commandArgument?: string
 	execute(input: TInput, context: ToolContext): Promise<ToolResult>
 	tier?: string
 	permissions?: ToolPermission[]

package/src/types/topic/entity.ts

@@ -67,10 +67,9 @@ export type TopicStatus = 'open' | 'archived'
  *     the kernel.
  *   - `ownerVersion` is the CAS counter for mutations — `updateTopic` and
  *     archival transitions require a matching version and reject
- *     {@link import('../../session/errors.js').StaleThreadError} on mismatch
- *     (error class name is unchanged this release — see NZ-TOPIC-01 risks).
- *     Mirrors the {@link import('./entity.js').Session} handoff CAS pattern
- *     (§6.1).
+ *     {@link import('../../session/errors.js').StaleTopicError} on mismatch
+ *     with `details.topicId`. Mirrors the
+ *     {@link import('./entity.js').Session} handoff CAS pattern (§6.1).
  *   - No fan-in `deriveStatus()` helper — status is owner-managed, not
  *     Run-derived. This is the Topic-vs-Session contract boundary.
  */

package/src/types/topic/store.ts

@@ -69,9 +69,9 @@ export interface TopicStore {
 	/**
 	 * Persist a mutation to a Topic record. CAS on `ownerVersion`: if the
 	 * supplied `topic.ownerVersion` does not match the persisted version,
-	 * rejects with {@link import('../../session/errors.js').StaleThreadError}
-	 * (class name unchanged this release). On success the write commits with
-	 * `ownerVersion + 1` and a refreshed `updatedAt`.
+	 * rejects with {@link import('../../session/errors.js').StaleTopicError}
+	 * using `details.topicId`. On success the write commits with `ownerVersion
+	 * + 1` and a refreshed `updatedAt`.
 	 *
 	 * Archival transition (`status: 'open' → 'archived'`) shares this path;
 	 * the caller is responsible for verifying that no non-terminal Sessions