@namzu/sdk 34.1.0 → 35.0.0

package/src/tools/paths.ts

@@ -35,6 +35,70 @@ export function resolveWithin(root: string, candidate: string | undefined): stri
 }
 
 /** True when `candidate` resolves inside `root`. */
+/**
+ * The directories a tool may reach: the working directory first, then any
+ * the host added for the session (`/add-dir`). Relative paths resolve
+ * against the first; an absolute path is accepted inside any.
+ */
+export function toolRoots(context: {
+	readonly workingDirectory: string
+	readonly additionalDirectories?: readonly string[]
+}): readonly string[] {
+	return [context.workingDirectory, ...(context.additionalDirectories ?? [])]
+}
+
+function describeRoots(roots: readonly string[]): string {
+	return roots.length === 1
+		? `inside ${resolve(roots[0] as string)}`
+		: `inside ${resolve(roots[0] as string)} or the added directories ${roots
+				.slice(1)
+				.map((r) => resolve(r))
+				.join(', ')}`
+}
+
+/** `resolveWithin` over several roots. See `toolRoots` for the order. */
+export function resolveWithinAny(roots: readonly string[], candidate: string | undefined): string {
+	const [first, ...rest] = roots
+	if (first === undefined) throw new Error('No root to resolve within.')
+	if (rest.length === 0) return resolveWithin(first, candidate)
+	const resolved =
+		candidate === undefined || candidate === ''
+			? resolve(first)
+			: resolve(resolve(first), candidate)
+	for (const root of roots) {
+		if (isWithin(root, resolved)) return resolveWithin(root, resolved)
+	}
+	throw new Error(
+		`Path escapes the working directory: ${candidate}. Tools may only reach ${describeRoots(roots)}.`,
+	)
+}
+
+/** `resolveWithinReal` over several roots: the first that contains the path, links followed. */
+export async function resolveWithinAnyReal(
+	roots: readonly string[],
+	candidate: string | undefined,
+): Promise<string> {
+	const [first, ...rest] = roots
+	if (first === undefined) throw new Error('No root to resolve within.')
+	if (rest.length === 0) return resolveWithinReal(first, candidate)
+	const resolved =
+		candidate === undefined || candidate === ''
+			? resolve(first)
+			: resolve(resolve(first), candidate)
+	let firstError: unknown
+	for (const root of roots) {
+		try {
+			return await resolveWithinReal(root, resolved)
+		} catch (err) {
+			firstError ??= err
+		}
+	}
+	throw new Error(
+		`Path escapes the working directory: ${candidate}. Tools may only reach ${describeRoots(roots)}.`,
+		{ cause: firstError },
+	)
+}
+
 export function isWithin(root: string, candidate: string): boolean {
 	try {
 		resolveWithin(root, candidate)

package/src/tools/roster.ts

@@ -0,0 +1,46 @@
+/**
+ * Narrower rosters from a wider one.
+ *
+ * A delegate that can only look, or a file-defined agent with an allowlist,
+ * needs a registry that is the parent's minus something — and every host
+ * that builds delegates wrote the same two loops. They live here so the
+ * predicate for "read-only" is the one the authorization gate and the
+ * prompt exemption already use (`isTrustedReadOnly`), not a third reading
+ * of the same flag.
+ *
+ * Both filters INTERSECT: a name in an allowlist that the source does not
+ * carry is simply not there. A filter can never widen.
+ */
+
+import { ToolRegistry } from '../registry/tool/execute.js'
+import type { ToolRegistryContract } from '../types/tool/index.js'
+import { isTrustedReadOnly } from './trusted-read-only.js'
+
+/**
+ * The tools that declare themselves read-only and are trusted to say so.
+ *
+ * Decided by `isTrustedReadOnly` with no input, which is each tool's own
+ * declaration: a new read-only builtin joins the roster without this file
+ * learning its name, and a connected server's tool that merely CLAIMS to be
+ * read-only stays out unless its provenance is trusted.
+ */
+export function filterReadOnlyTools(source: ToolRegistryContract): ToolRegistry {
+	const filtered = new ToolRegistry()
+	for (const tool of source.getAll()) {
+		if (isTrustedReadOnly(tool, undefined)) filtered.register(tool)
+	}
+	return filtered
+}
+
+/** The tools whose names are listed. Names the source does not carry are ignored. */
+export function filterToolsNamed(
+	source: ToolRegistryContract,
+	names: Iterable<string>,
+): ToolRegistry {
+	const allowed = new Set(names)
+	const filtered = new ToolRegistry()
+	for (const tool of source.getAll()) {
+		if (allowed.has(tool.name)) filtered.register(tool)
+	}
+	return filtered
+}

package/src/types/agent/base.ts

@@ -1,3 +1,4 @@
+import type { TokenBudget } from '../../run/token-budget.js'
 import type { ProjectInstructionContext } from '../../runtime/query/project-instructions.js'
 import type { PathBuilder } from '../../session/workspace/path-builder.js'
 import type { Logger } from '../../utils/logger.js'
@@ -19,6 +20,8 @@ export type AgentContextLevel = 'full' | 'standard' | 'minimal'
 export interface BaseAgentConfig {
 	model: string
 	tokenBudget: number
+	/** Aggregate authority inherited by descendants; supplied independently of the numeric local cap. */
+	budget?: TokenBudget
 	timeoutMs: number
 	/** See {@link import('../run/config.js').AgentRunConfig.streamIdleTimeoutMs}. */
 	streamIdleTimeoutMs?: number
@@ -271,6 +274,9 @@ export interface AgentInput {
 }
 
 export interface BaseAgentResult {
+	/** Aggregate tree accounting, separate from this invocation's own usage. */
+	budget?: ReturnType<TokenBudget['summary']>
+
 	runId: RunId
 	status: RunExecutionStatus
 	stopReason?: StopReason

package/src/types/agent/pipeline.ts

@@ -1,8 +1,11 @@
+import type { TokenBudget } from '../../run/token-budget.js'
 import type { RunId } from '../ids/index.js'
 import type { LLMProvider } from '../provider/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 
 export interface StepContext {
+	/** Shared authority; reserve a child scope before invoking another agent. */
+	budget: TokenBudget
 	runId: RunId
 	stepIndex: number
 	totalSteps: number

package/src/types/agent/router.ts

@@ -15,9 +15,8 @@ export interface RoutingDecision {
 	 *
 	 * Routing runs before the delegate's run exists, so it has no
 	 * `RunPersistence` to accumulate into. Reporting it here lets the
-	 * router fold it into the result it returns, instead of the caller
-	 * seeing only the delegate's usage and under-reporting every routed
-	 * run by one model call.
+	 * router report its own model usage. The separate budget summary includes
+	 * both routing and every delegated descendant.
 	 */
 	usage?: TokenUsage
 }

package/src/types/agent/scheduler.ts

@@ -1,3 +1,4 @@
+import type { TokenBudget } from '../../run/token-budget.js'
 import type { TaskId } from '../ids/index.js'
 import type { AgentPersona } from '../persona/index.js'
 import type { CancelCause } from '../run/cancel-cause.js'
@@ -101,6 +102,9 @@ export interface CreateTaskOptions {
 }
 
 export interface TaskScheduler {
+	/** Authority under which this scheduler reserves and meters child execution. */
+	readonly budget?: TokenBudget
+
 	createTask(options: CreateTaskOptions): Promise<TaskHandle>
 
 	waitForTask(taskId: TaskId): Promise<TaskHandle>

package/src/types/agent/task.ts

@@ -1,3 +1,4 @@
+import type { TokenBudget } from '../../run/token-budget.js'
 import type { ActorRef } from '../../types/session/actor.js'
 import type { WorkspaceBackendKind } from '../../types/workspace/ref.js'
 import type { ResumeHandler } from '../hitl/index.js'
@@ -37,7 +38,8 @@ export interface AgentTaskContext {
 
 	depth: number
 
-	budgetTracker: AgentTaskBudget
+	/** Shared authority for this parent and every delegated descendant. */
+	budget: TokenBudget
 
 	factoryOptions?: AgentFactoryOptions
 
@@ -112,11 +114,8 @@ export interface AgentTaskContext {
 	parentActor: ActorRef
 }
 
-export interface AgentTaskBudget {
-	total: number
-
-	remaining: number
-}
+/** Budget authority shared by an agent task and its descendants. */
+export type AgentTaskBudget = TokenBudget
 
 export interface AgentTask {
 	taskId: TaskId
@@ -127,18 +126,6 @@ export interface AgentTask {
 	state: AgentTaskState
 	result?: BaseAgentResult
 
-	/**
-	 * Tokens reserved from the shared pool when this child was spawned.
-	 *
-	 * A RESERVATION, not a spend: it is subtracted up front so siblings
-	 * cannot each be promised the same headroom, and the unused part is
-	 * returned when the child settles. Without the return, a pool shrank
-	 * by the full allocation every spawn regardless of what the child
-	 * actually used, so a long session ran out of budget while almost none
-	 * of it had been spent.
-	 */
-	budgetReservation?: number
-
 	pendingMessages: Message[]
 	createdAt: number
 	completedAt?: number

package/src/types/common/index.ts

@@ -85,6 +85,9 @@ export function mergeTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsa
 		totalTokens: Math.max(current.totalTokens, next.totalTokens, promptTokens + completionTokens),
 		cachedTokens: Math.max(current.cachedTokens, next.cachedTokens),
 		cacheWriteTokens: Math.max(current.cacheWriteTokens, next.cacheWriteTokens),
+		...(current.reasoningTokens !== undefined || next.reasoningTokens !== undefined
+			? { reasoningTokens: Math.max(current.reasoningTokens ?? 0, next.reasoningTokens ?? 0) }
+			: {}),
 	}
 }
 

package/src/types/computer-use/index.ts

@@ -30,6 +30,14 @@ export interface ComputerUseCapabilities {
 	readonly keyboard: boolean
 	readonly cursorPosition: boolean
 	readonly clipboard: boolean
+	/**
+	 * Why every flag above is false, when a host loaded but the desktop did
+	 * not answer — a WSL process with PowerShell and no interactive Windows
+	 * session, an ssh session with no display. Present, the tool stays
+	 * mounted and says this in its description and in every refusal, so the
+	 * model reads the reason once and does not try again.
+	 */
+	readonly unavailableReason?: string
 }
 
 // ---------------------------------------------------------------------------

package/src/types/hitl/index.ts

@@ -4,6 +4,7 @@ import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { CheckpointId, PlanId, RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
 import type { PlanStatus } from '../plan/index.js'
+import type { TokenBudgetBinding } from '../run/token-budget-store.js'
 
 export type { CheckpointId }
 
@@ -203,6 +204,10 @@ export interface PendingDecision {
 }
 
 export interface IterationCheckpoint {
+	/** Reference to the canonical tree ledger; a checkpoint never resets it. */
+	readonly budgetBinding?: TokenBudgetBinding
+	/** Also present for non-durable accounts; those require the live authority on resume. */
+	readonly budgetAccountId?: string
 	id: CheckpointId
 	runId: RunId
 	iteration: number

package/src/types/ids/brand.ts

@@ -1,57 +1,14 @@
-/**
- * Nominal-brand machinery for the id types — declared here, not yet applied.
- *
- * Today every id in `./index.ts` is a bare template-literal type, and
- * TypeScript's assignability rule for those means
- * `const x: RunId = 'run_totally-made-up'` compiles with no cast and no
- * factory call. The result is indistinguishable at the type level from an id
- * `generateRunId()` actually minted, so the compiler cannot tell a real id
- * from a plausible-looking string.
- *
- * Applying this brand is a separate change, on purpose: flipping the
- * declarations turns every existing bare literal into an error at once, and
- * that is a `major` with a migration in front of it. This file ships the
- * machinery and the runtime constructors that use it so the two can land
- * independently — the constructors are useful on their own, since there is
- * no runtime prefix validation in the tree at all today.
- *
- * **The prefix stays in the type, and that is the one place this diverges
- * from a plain `Branded<B>`.** A brand alone would render as `RunId` in
- * hovers and errors and tell a reader nothing about the shape. Keeping
- * `` `${Prefix}_${string}` `` in the intersection means an editor hover still
- * shows `run_${string}`, which is most of what makes these ids readable in
- * a log line.
- */
-
+/** Nominal identity is independent of the identifier's serialized spelling. */
 declare const ID_BRAND: unique symbol
 
-/**
- * An id with both its wire shape and a nominal tag.
- *
- * `B` is a string tag rather than the type's own name by convention — two
- * ids with the same prefix but different meanings must not be mutually
- * assignable, and only the tag can separate them.
- */
-export type Id<Prefix extends string, B extends string> = `${Prefix}_${string}` & {
+/** An opaque string whose tag prevents mixing different entity types. */
+export type Id<B extends string> = string & {
 	readonly [ID_BRAND]: B
 }
 
 /**
- * The one way to produce a branded id without a runtime check.
- *
- * A brand cannot be constructed by writing it — `{ [ID_BRAND]: 'RunId' }` is
- * not something a caller can type, since the symbol is not exported. So
- * every id has to come from somewhere, and there are exactly three places:
- * `generate*Id()` mints one, `as*Id()` checks a string into one, and this.
- *
- * Named `unsafeId` rather than `toId` because the name is the warning, and
- * kept HERE rather than in `utils/id.ts` because this file has no imports —
- * `types/ids/index.ts` needs it for `UNKNOWN_TENANT_ID` and cannot import
- * from `utils/id.ts` without closing a cycle.
- *
- * Not exported from the package barrel. A consumer that needs an id from a
- * string wants the checked constructor; one that wants to skip the check is
- * asking for the thing the brand exists to prevent.
+ * Internal escape hatch for factories and checked constructors. Not exported
+ * from the package barrel; consumers validate external strings with `as*Id`.
  */
 export function unsafeId<T extends string>(value: string): T {
 	return value as unknown as T

package/src/types/ids/index.ts

@@ -1,25 +1,21 @@
-import { type Id, unsafeId } from './brand.js'
+import type { Id } from './brand.js'
 
 /**
- * Every id here is NOMINAL as of NZ-SURF-11: `Id<Prefix, Tag>` intersects the
- * wire shape with a unique-symbol brand, so `const a: RunId = 'run_x'` no
- * longer compiles and neither does handing a `SessionId` where a `RunId` was
- * asked for. Ids are minted by `generate*Id()` or checked by `as*Id()` in
- * `utils/id.ts`; fixtures use `test-support/ids.ts`.
+ * Entity ids are opaque branded strings. Factories mint UUIDs; checked
+ * constructors reject every other spelling, including earlier type prefixes.
+ * A RunId cannot be assigned to a SessionId even though their wire shapes
+ * are identical. Persisted records and typed fields establish the kind,
+ * not the spelling of the id.
  *
- * **What this does NOT stop, measured rather than assumed:** a type
- * ASSERTION. `'run_x' as RunId` and `someString as RunId` both still compile,
- * because TypeScript's assertion rule only asks that the two types be
- * comparable and a string is comparable to a branded string. The brand makes
- * a rule against `as <IdType>` enforceable — it does not replace one. See
- * `__tests__/an-id-is-not-a-string.test.ts`, which pins both halves.
+ * Brands do not validate a type assertion. Use the checked constructors
+ * for values received from JSON, flags, URLs, or other untyped boundaries.
  */
-export type RunId = Id<'run', 'RunId'>
-export type MessageId = Id<'msg', 'MessageId'>
-export type SessionId = Id<'ses', 'SessionId'>
+export type RunId = Id<'RunId'>
+export type MessageId = Id<'MessageId'>
+export type SessionId = Id<'SessionId'>
 /** Identifies one durable completion goal across its revisions. */
-export type GoalId = Id<'goal', 'GoalId'>
-export type ToolCallId = Id<'call', 'ToolCallId'>
+export type GoalId = Id<'GoalId'>
+export type ToolCallId = Id<'ToolCallId'>
 /**
  * Provider-issued tool-use identifier surfaced on the streaming event bus.
  * Providers emit different prefixes (`toolu_*`, `call_*`,
@@ -30,38 +26,38 @@ export type ToolCallId = Id<'call', 'ToolCallId'>
  * persisted assistant messages and replay records.
  */
 export type ToolUseId = string
-export type ActivityId = Id<'act', 'ActivityId'>
-export type TaskId = Id<'task', 'TaskId'>
-export type PlanId = Id<'plan', 'PlanId'>
-export type KnowledgeBaseId = Id<'kb', 'KnowledgeBaseId'>
-export type DocumentId = Id<'doc', 'DocumentId'>
-export type ChunkId = Id<'chk', 'ChunkId'>
-export type ConnectorId = Id<'conn', 'ConnectorId'>
-export type ConnectorInstanceId = Id<'ci', 'ConnectorInstanceId'>
-export type TenantId = Id<'tnt', 'TenantId'>
-export type CredentialId = Id<'cred', 'CredentialId'>
-export type ExecutionContextId = Id<'ectx', 'ExecutionContextId'>
-export type MCPServerId = Id<'mcp', 'MCPServerId'>
-export type MCPClientId = Id<'mcpc', 'MCPClientId'>
-export type MCPSessionId = Id<'mcps', 'MCPSessionId'>
-export type EnvironmentId = Id<'env', 'EnvironmentId'>
-export type CheckpointId = Id<'cp', 'CheckpointId'>
-export type LockId = Id<'lock', 'LockId'>
-export type AdvisoryId = Id<'adv', 'AdvisoryId'>
-export type AdvisoryCallId = Id<'advc', 'AdvisoryCallId'>
-export type EmergencySaveId = Id<'esave', 'EmergencySaveId'>
-export type MemoryId = Id<'mem', 'MemoryId'>
-export type PluginId = Id<'plg', 'PluginId'>
-export type SandboxId = Id<'sbx', 'SandboxId'>
+export type ActivityId = Id<'ActivityId'>
+export type TaskId = Id<'TaskId'>
+export type PlanId = Id<'PlanId'>
+export type KnowledgeBaseId = Id<'KnowledgeBaseId'>
+export type DocumentId = Id<'DocumentId'>
+export type ChunkId = Id<'ChunkId'>
+export type ConnectorId = Id<'ConnectorId'>
+export type ConnectorInstanceId = Id<'ConnectorInstanceId'>
+export type TenantId = Id<'TenantId'>
+export type CredentialId = Id<'CredentialId'>
+export type ExecutionContextId = Id<'ExecutionContextId'>
+export type MCPServerId = Id<'MCPServerId'>
+export type MCPClientId = Id<'MCPClientId'>
+export type MCPSessionId = Id<'MCPSessionId'>
+export type EnvironmentId = Id<'EnvironmentId'>
+export type CheckpointId = Id<'CheckpointId'>
+export type LockId = Id<'LockId'>
+export type AdvisoryId = Id<'AdvisoryId'>
+export type AdvisoryCallId = Id<'AdvisoryCallId'>
+export type EmergencySaveId = Id<'EmergencySaveId'>
+export type MemoryId = Id<'MemoryId'>
+export type PluginId = Id<'PluginId'>
+export type SandboxId = Id<'SandboxId'>
 /** LOG-14: the audit trail's own record id — distinct from `RunEvent.seq`. */
-export type AuditEventId = Id<'aud', 'AuditEventId'>
+export type AuditEventId = Id<'AuditEventId'>
 
 // Actor identifiers (Session Hierarchy §4.3).
 //
 // This block used to say "branded so actor refs cannot be constructed from
 // bare strings" while the compiler enforced nothing. NZ-SURF-11 made that
 // true for `UserId`: `const a: UserId = 'usr_made-up'` is now an error.
-export type UserId = Id<'usr', 'UserId'>
+export type UserId = Id<'UserId'>
 
 /**
  * @deprecated An agent is identified by its REGISTRY KEY, and this type
@@ -77,47 +73,42 @@ export type UserId = Id<'usr', 'UserId'>
  *
  * Kept for one release rather than deleted, per the deprecate-before-remove
  * rule: a consumer that annotated its own variable `AgentId` still compiles
- * and gets a warning. `asAgentId` is deprecated for the same reason and
- * would throw on every value the kernel actually produces.
+ * and gets a warning. `asAgentId` is deprecated for the same reason: registry
+ * keys have no entity-id spelling contract.
  */
-export type AgentId = Id<'agt', 'AgentId'>
+export type AgentId = Id<'AgentId'>
 
 // Shared-store placeholder refs (Session Hierarchy §4.2 / §3.2). Full shapes
 // land in later phases; kept here as opaque branded IDs so ProjectConfig can
 // reference them today.
-export type MemoryStoreRef = Id<'mms', 'MemoryStoreRef'>
-export type VaultRef = Id<'vlt', 'VaultRef'>
-export type KnowledgeBaseRef = Id<'kbs', 'KnowledgeBaseRef'>
+export type MemoryStoreRef = Id<'MemoryStoreRef'>
+export type VaultRef = Id<'VaultRef'>
+export type KnowledgeBaseRef = Id<'KnowledgeBaseRef'>
 
-// Session hierarchy IDs. Convention #2 branded IDs; prefixes mandated by the
-// five-layer hierarchy (Project → Thread → Session → SubSession → Run). The
-// `types/session/ids.ts` barrel re-exports these for co-location ergonomics.
-export type ProjectId = Id<'prj', 'ProjectId'>
+// Session hierarchy identities; types/session/ids.ts re-exports these.
+export type ProjectId = Id<'ProjectId'>
 /**
- * NZ-TOPIC-04: narrowed from the NZ-TOPIC-01 alias `type TopicId = ThreadId`
- * (both `thd_${string}`) to its own prefix. `thd_` from here on means only
- * the pre-0.2.0 top-level container (`session/migration/id-prefix.ts`,
- * `session/migration/filesystem.ts`) -- a meaning `ThreadId` never carried;
- * it was purely the deprecated name for THIS type. Deleted rather than
- * repurposed to mean the legacy container instead: a name whose meaning
- * silently changes under unmigrated callers is worse than a name that is
- * gone (Convention #0, no silent long-lived compat).
+ * A topic is distinct from its project; each carries its own opaque UUID.
  */
-export type TopicId = Id<'top', 'TopicId'>
-export type SubSessionId = Id<'sub', 'SubSessionId'>
-export type HandoffId = Id<'hof', 'HandoffId'>
-export type WorkspaceId = Id<'wsp', 'WorkspaceId'>
-export type SummaryId = Id<'sum', 'SummaryId'>
-export type DeliverableId = Id<'del', 'DeliverableId'>
+export type TopicId = Id<'TopicId'>
+export type SubSessionId = Id<'SubSessionId'>
+export type HandoffId = Id<'HandoffId'>
+export type WorkspaceId = Id<'WorkspaceId'>
+export type SummaryId = Id<'SummaryId'>
+export type DeliverableId = Id<'DeliverableId'>
 
 /**
- * Sentinel {@link TenantId} for legacy pre-0.2.0 runs rehomed by the
- * boot-time filesystem migration. Consumers with strict tenant enforcement
- * should either tag these records on first access or reject them until a
- * real tenant is assigned — the kernel surfaces the sentinel but does not
- * prescribe policy (Convention #17).
+ * @deprecated All prefixed IDs are rejected by InvalidIdError. This error
+ * remains exported for callers that referenced the earlier exception type.
  */
-// `unsafeId`, not `asTenantId`: `utils/id.ts` imports this file, so reaching
-// for its constructor here would close a cycle. The prefix is pinned by
-// `__tests__/an-id-is-not-a-string.test.ts` instead.
-export const UNKNOWN_TENANT_ID = unsafeId<TenantId>('tnt_unknown_legacy')
+export class RetiredIdPrefixError extends Error {
+	constructor(
+		readonly value: string,
+		readonly expectedPrefix: string,
+	) {
+		super(
+			`Retired id prefix: ${JSON.stringify(value)} is not a ${JSON.stringify(expectedPrefix)} id. Records written by namzu before 0.2 are not read by this version; open them with a 0.x namzu that migrates them, or start fresh.`,
+		)
+		this.name = 'RetiredIdPrefixError'
+	}
+}

package/src/types/permission/index.ts

@@ -1 +1,12 @@
 export type PermissionMode = 'plan' | 'auto'
+
+/**
+ * What the model is told when a mutating call is refused under plan mode.
+ *
+ * Here rather than beside the review policy because two doors say it: the
+ * review-time policy (`createReviewPolicy({ mode: 'plan' })`) and the
+ * execution-time floor in the tool registry. One text, so the model gets
+ * the same instruction whichever door it hit.
+ */
+export const PLAN_MODE_REFUSAL =
+	'Refused: plan mode is read-only. Explore with the reading tools, then present the plan as your reply — what you would change, in which files, and in what order. The user will switch out of plan mode to have it carried out.'

package/src/types/plugin/index.ts

@@ -8,7 +8,7 @@ import {
 	MAX_TOOLS_PER_PLUGIN,
 	PLUGIN_NAME_MAX_LENGTH,
 } from '../../constants/plugin/index.js'
-import type { PluginId, RunId } from '../ids/index.js'
+import type { PluginId, RunId, SessionId } from '../ids/index.js'
 import type { Message, ToolResultContent } from '../message/index.js'
 import type { CancelCause } from '../run/cancel-cause.js'
 import type { ToolResult } from '../tool/index.js'
@@ -84,6 +84,20 @@ export function assertPluginContributionType(type: PluginContributionType): void
 // ---------------------------------------------------------------------------
 
 export type PluginHookEvent =
+	/**
+	 * The operator's prompt, before the model sees it. Carries `prompt`.
+	 * The one event that can BLOCK a run (`skip`) and the one that can add
+	 * to what the model is told (`annotate`).
+	 */
+	| 'user_prompt_submit'
+	/** A host's session opened or closed. Carries `sessionId`; `runId` is minted for the session's own hooks. */
+	| 'session_start'
+	| 'session_end'
+	/** A compaction pass is about to run / has run. Carries `compaction`. */
+	| 'pre_compact'
+	| 'post_compact'
+	/** A delegated run ended. Fired after its own `run_end`; carries `parentRunId`. */
+	| 'subagent_stop'
 	| 'run_start'
 	| 'run_end'
 	| 'run_interrupt'
@@ -96,6 +110,12 @@ export type PluginHookEvent =
 
 export function assertPluginHookEvent(event: PluginHookEvent): void {
 	switch (event) {
+		case 'user_prompt_submit':
+		case 'session_start':
+		case 'session_end':
+		case 'pre_compact':
+		case 'post_compact':
+		case 'subagent_stop':
 		case 'run_start':
 		case 'run_end':
 		case 'run_interrupt':
@@ -142,10 +162,28 @@ export interface PluginModelResponse {
 	}
 }
 
+/** What a compaction hook is shown about the pass. */
+export interface PluginCompactionInfo {
+	/** `threshold`: the estimate crossed the line. `overflow`: the provider rejected the prompt. */
+	readonly reason: 'threshold' | 'overflow'
+	readonly tokensBefore: number
+	/** Present on `post_compact`. */
+	readonly tokensAfter?: number
+	readonly contextWindowTokens: number
+}
+
 export interface PluginHookContext {
 	readonly runId: RunId
 	readonly pluginId: PluginId
 	readonly event: PluginHookEvent
+	/** The host's session, on `session_*` and `user_prompt_submit`. */
+	readonly sessionId?: SessionId
+	/** The run that delegated, on `subagent_stop`. */
+	readonly parentRunId?: RunId
+	/** The operator's prompt, on `user_prompt_submit`. */
+	readonly prompt?: string
+	/** The pass, on `pre_compact` and `post_compact`. */
+	readonly compaction?: PluginCompactionInfo
 	readonly toolName?: string
 	readonly toolInput?: unknown
 	readonly toolResult?: ToolResult
@@ -204,6 +242,15 @@ export interface PluginHookContext {
 
 export type PluginHookResult =
 	| { action: 'continue' }
+	/**
+	 * Add to what the model is told, without changing anything else.
+	 *
+	 * The answer a `user_prompt_submit` hook gives when it has context the
+	 * model should have — the branch, the time, a ticket — and no opinion
+	 * on the prompt. Accepted on that event only: a tool hook that returns
+	 * it is rejected, because a tool result is not a place for context.
+	 */
+	| { action: 'annotate'; text: string }
 	| { action: 'skip'; reason: string }
 	| { action: 'modify'; input: unknown }
 	| { action: 'error'; message: string }
@@ -238,6 +285,7 @@ export function assertPluginHookResult(result: PluginHookResult): asserts result
 	const action = result.action
 	switch (action) {
 		case 'continue':
+		case 'annotate':
 		case 'skip':
 		case 'modify':
 		case 'error':

package/src/types/run/config.ts

@@ -1,3 +1,4 @@
+import type { TokenBudget } from '../../run/token-budget.js'
 import type { ModelPricing } from '../../utils/cost.js'
 import type { Logger } from '../../utils/logger.js'
 import type { RunId, SessionId, TenantId } from '../ids/index.js'
@@ -152,6 +153,8 @@ export interface AgentRunConfig {
  * Convention #17).
  */
 export interface RunPersistenceConfig {
+	/** Shared account for this invocation and its delegated descendants. */
+	budget?: TokenBudget
 	runId: RunId
 	agentId: string
 	agentName: string