@namzu/sdk 27.0.0 → 28.0.0

package/src/tools/env-scrub.ts

@@ -0,0 +1,91 @@
+/**
+ * Credential scrubbing for an environment a tool *inherits* rather than one a
+ * host *hands* it.
+ *
+ * The distinction is the whole design. `process.env` arrives by inheritance —
+ * nobody decided the model's command should see it, it is simply what a child
+ * process gets by default. A `ToolContext.env` entry is the opposite: a host
+ * wrote that key deliberately. So the inherited half is scrubbed and the
+ * explicit half is not, and a host that means to hand a command a credential
+ * can still do it by naming it.
+ *
+ * ## This is a denylist, and a denylist is not a boundary
+ *
+ * Stated plainly because the sandbox tiers state their limits the same way
+ * (`sandbox/isolation.ts`): a control that is believed to be enforcing more
+ * than it does is worse than one nobody trusted. This function catches keys
+ * whose *name* looks like a credential. It cannot catch a secret whose name
+ * does not — `DATABASE_URL` with a password in the userinfo, an S3 pre-signed
+ * URL in `ARTIFACT_URL`, a bearer token someone parked in `MY_VAR`. Those
+ * still reach the command.
+ *
+ * The actual boundary is the sandbox, where the inherited set is an allowlist
+ * (`SANDBOX_SAFE_ENV_KEYS`, seven keys) rather than a denylist. An allowlist
+ * is correct there because a sandbox is a fresh environment; it is wrong on
+ * the host path, where the same agent is expected to run `pnpm test`, `make`
+ * and `docker build`, all of which need far more than seven variables. So the
+ * host path gets the weaker control on purpose, and says so.
+ *
+ * ## Why this exists at all
+ *
+ * Namzu reads its own provider credentials out of the environment. A command
+ * that prints its environment — `env`, `printenv`, a Makefile echoing `$(ENV)`,
+ * a build script dumping config on failure — therefore returned the operator's
+ * API keys as tool output. That output is not ephemeral: it is appended to the
+ * durable transcript, persisted by the session store, and re-sent to the model
+ * provider as history on every later turn of the run. One incidental `env` in
+ * a build script converted a local secret into a permanently recorded one that
+ * had also been transmitted to a third party.
+ *
+ * The model does not have to be adversarial for this to fire, which is why it
+ * is scrubbed rather than merely policed.
+ */
+
+import { isCredentialEnvKey } from '../constants/credential-env-keys.js'
+
+// Re-exported from its historical home: this module's importers already
+// name it here, and the predicate did not change — only where it lives.
+export { isCredentialEnvKey }
+
+// The key-name vocabulary moved to `constants/credential-env-keys.ts`, a
+// leaf with no imports, so `EnvCredentialProvider` can read the SAME table.
+// Two copies would mean a name in one and not the other — a variable the
+// credential seam reads a secret from and this scrub hands to a shell.
+
+/** Outcome of a scrub — the surviving environment and what was withheld. */
+export interface ScrubbedEnv {
+	readonly env: Record<string, string>
+	/**
+	 * Names of the dropped variables, sorted. Names only — never values.
+	 *
+	 * Returned rather than swallowed because a command that genuinely needed
+	 * `FOO_TOKEN` otherwise fails with an authentication error that points
+	 * nowhere. Naming the withheld key turns that into a readable failure the
+	 * model can act on, which is the same reason a denied tool call here
+	 * carries the rule that denied it.
+	 */
+	readonly dropped: readonly string[]
+}
+
+/**
+ * Drop credential-shaped keys from an inherited environment.
+ *
+ * Values are never inspected — only key names — so this cannot itself become
+ * a place a secret is read, logged or compared.
+ */
+export function scrubInheritedEnv(source: NodeJS.ProcessEnv = process.env): ScrubbedEnv {
+	const env: Record<string, string> = {}
+	const dropped: string[] = []
+
+	for (const [key, value] of Object.entries(source)) {
+		if (value === undefined) continue
+		if (isCredentialEnvKey(key)) {
+			dropped.push(key)
+			continue
+		}
+		env[key] = value
+	}
+
+	dropped.sort()
+	return { env, dropped }
+}

package/src/tools/memory/read.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
-import type { MemoryId } from '../../types/ids/index.js'
 import type { MemoryStore } from '../../types/memory/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
+import { asMemoryId } from '../../utils/id.js'
 import { defineTool } from '../defineTool.js'
 
 export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
@@ -17,7 +17,10 @@ export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 		destructive: false,
 		concurrencySafe: true,
 		async execute({ id }) {
-			const memoryId = id as MemoryId
+			// Checked, not cast. `id` is model-authored and becomes a store key
+			// on the next line; nothing downstream re-examines it, so this is
+			// the only place a `ses_`-shaped value can be stopped.
+			const memoryId = asMemoryId(id)
 			const content = await store.get(memoryId)
 
 			if (!content) {

package/src/tools/task/create.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 import type { RunId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
+import { asTaskId } from '../../utils/id.js'
 import { defineTool } from '../defineTool.js'
 
 export function buildTaskCreateTool(taskStore: TaskStore, runId: RunId): ToolDefinition {
@@ -38,7 +39,7 @@ export function buildTaskCreateTool(taskStore: TaskStore, runId: RunId): ToolDef
 				description,
 				activeForm,
 				owner,
-				blockedBy: blockedBy as `task_${string}`[] | undefined,
+				blockedBy: blockedBy?.map(asTaskId),
 				metadata,
 			})
 

package/src/tools/task/update.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
-import type { TaskId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
+import { asTaskId } from '../../utils/id.js'
 import { defineTool } from '../defineTool.js'
 
 export function buildTaskUpdateTool(taskStore: TaskStore): ToolDefinition {
@@ -45,7 +45,10 @@ export function buildTaskUpdateTool(taskStore: TaskStore): ToolDefinition {
 			addBlockedBy,
 			metadata,
 		}) {
-			const taskId = id as TaskId
+			// Checked. Without it a malformed id reads as "Task not found",
+			// which tells the model its task disappeared rather than that it
+			// named the wrong thing.
+			const taskId = asTaskId(id)
 
 			if (status === 'deleted') {
 				const deleted = await taskStore.delete(taskId)
@@ -57,12 +60,12 @@ export function buildTaskUpdateTool(taskStore: TaskStore): ToolDefinition {
 
 			if (addBlocks) {
 				for (const blockedId of addBlocks) {
-					await taskStore.block(taskId, blockedId as TaskId)
+					await taskStore.block(taskId, asTaskId(blockedId))
 				}
 			}
 			if (addBlockedBy) {
 				for (const blockerId of addBlockedBy) {
-					await taskStore.block(blockerId as TaskId, taskId)
+					await taskStore.block(asTaskId(blockerId), taskId)
 				}
 			}
 

package/src/types/acp/index.ts

@@ -0,0 +1,163 @@
+import type { SerializableHostCommand } from '../command/index.js'
+import type { ToolCallView } from '../tool/presentation.js'
+
+/**
+ * The wire shapes an editor or an orchestrator sees.
+ *
+ * Declared here rather than inferred from the server's own returns, because
+ * these cross a process boundary: a shape that only exists as a function's
+ * inferred return type is a contract nobody can read, and the reader is
+ * frequently writing the client in another language.
+ *
+ * Everything here is JSON. No `Date`, no `Map`, no branded id reaching the
+ * wire as anything but a string — a peer cannot construct a branded id and
+ * should not have to.
+ */
+
+/** What the client says it can do. */
+export interface AcpClientCapabilities {
+	/**
+	 * Capability names the client supports.
+	 *
+	 * An array of strings rather than a booleans object, so a client can
+	 * declare a capability this agent has not heard of without the field
+	 * being dropped by a parser that only knew the old shape.
+	 */
+	readonly capabilities?: readonly string[]
+}
+
+export interface AcpInitializeParams extends AcpClientCapabilities {
+	/** The revision the client speaks. */
+	readonly protocolVersion?: number
+	/** Free-form, for logs. Never used to vary behaviour. */
+	readonly clientInfo?: { readonly name?: string; readonly version?: string }
+}
+
+export interface AcpInitializeResult {
+	readonly protocolVersion: number
+	readonly agentInfo: { readonly name: string; readonly version: string }
+	/**
+	 * The commands a client may offer its operator.
+	 *
+	 * Comes from `HostCommandRegistry.describe()`, never hand-written here.
+	 * A front end that authored its own list would be a second definition of
+	 * the command surface, and the one that drifted would be the one an
+	 * operator was looking at.
+	 */
+	readonly commands: readonly SerializableHostCommand[]
+	/** Which capabilities this agent needs the client to have. */
+	readonly requiredClientCapabilities: readonly string[]
+	/**
+	 * Capabilities that change what this agent can do without being required.
+	 *
+	 * Kept apart from `required` because demanding a filesystem of a peer that
+	 * is not an editor would refuse a session that is perfectly able to run.
+	 */
+	readonly optionalClientCapabilities: readonly string[]
+}
+
+export interface AcpSessionNewParams {
+	/** Where the agent works. Absent means the process's own directory. */
+	readonly cwd?: string
+}
+
+export interface AcpSessionNewResult {
+	readonly sessionId: string
+}
+
+export interface AcpSessionLoadParams {
+	/** The session to resume. Answered with the SAME id, never a new one. */
+	readonly sessionId: string
+	readonly cwd?: string
+}
+
+/** What the agent asks the client before running a tool batch. */
+export interface AcpRequestPermissionParams {
+	readonly sessionId: string
+	readonly toolCalls: readonly {
+		readonly id: string
+		readonly name: string
+		readonly input: unknown
+		readonly isDestructive: boolean
+	}[]
+}
+
+/**
+ * The client's answer.
+ *
+ * `approve_all` is a distinct outcome rather than `approve` plus a flag,
+ * because the two mean different things to the human who chose one and a
+ * boolean beside an enum invites a client to send `approve` with the flag on.
+ */
+export interface AcpRequestPermissionResult {
+	readonly outcome: 'approve' | 'approve_all' | 'reject'
+	/** Why, for a rejection. Reaches the MODEL, so it is worth writing. */
+	readonly feedback?: string
+}
+
+export interface AcpFsReadParams {
+	readonly sessionId: string
+	readonly path: string
+}
+
+export interface AcpFsReadResult {
+	readonly content: string
+}
+
+export interface AcpFsWriteParams {
+	readonly sessionId: string
+	readonly path: string
+	readonly content: string
+}
+
+export interface AcpSessionPromptParams {
+	readonly sessionId: string
+	/** The operator's message, already plain text. */
+	readonly prompt: string
+}
+
+/** Why a prompt stopped, in the peer's vocabulary. */
+export type AcpStopReason = 'end_turn' | 'cancelled' | 'refused' | 'error' | 'max_turns'
+
+export interface AcpSessionPromptResult {
+	readonly stopReason: AcpStopReason
+}
+
+export interface AcpSessionCancelParams {
+	readonly sessionId: string
+}
+
+/**
+ * One streamed update.
+ *
+ * A discriminated union on `kind`, and closed: an open one would let this
+ * bridge emit an update shape no client can render, which fails silently at
+ * the far end — the same reason `ToolCallView` is closed.
+ */
+export type AcpSessionUpdate =
+	/** A fragment of the assistant's answer. */
+	| { readonly kind: 'agent_message_chunk'; readonly text: string }
+	/** A fragment of the assistant's reasoning, when the model emits any. */
+	| { readonly kind: 'agent_thought_chunk'; readonly text: string }
+	/**
+	 * A tool call, rendered by the TOOL rather than by this bridge.
+	 *
+	 * `view` is a `ToolCallView` verbatim. This module never compares a tool
+	 * name: the moment a front end writes `name === 'edit'`, a tool it has
+	 * not heard of can never be shown properly, which is the defect
+	 * `createToolPresenter` exists to have fixed once.
+	 */
+	| {
+			readonly kind: 'tool_call'
+			readonly toolCallId: string
+			readonly title: string
+			readonly status: 'pending' | 'completed' | 'failed'
+			readonly view: ToolCallView
+	  }
+	/** The turn is over. Carries the same reason the prompt result will. */
+	| { readonly kind: 'turn_ended'; readonly stopReason: AcpStopReason }
+
+export interface AcpSessionUpdateNotification {
+	readonly sessionId: string
+	readonly update: AcpSessionUpdate
+}

package/src/types/agent/base.ts

@@ -1,11 +1,12 @@
-import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
+import type { Logger } from '../../utils/logger.js'
+import type { CostInfo, RunExecutionStatus, TokenUsage } from '../common/index.js'
 import type { ResumeHandler } from '../hitl/index.js'
 import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
 import type { Message } from '../message/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { StopReason } from '../run/stop-reason.js'
-import type { ProjectId, ThreadId } from '../session/ids.js'
+import type { ProjectId, TopicId } from '../session/ids.js'
 import type { TaskStore } from '../task/index.js'
 import type { ToolAvailability } from '../tool/index.js'
 
@@ -23,6 +24,67 @@ export interface BaseAgentConfig {
 	costLimitUsd?: number
 	permissionMode?: PermissionMode
 
+	/**
+	 * The tools this run may use, narrowing whatever its registry holds.
+	 *
+	 * `allowedTools` existed on `QueryParams` and on `ToolContext` and
+	 * nowhere on the path a delegation takes — so a supervisor handing a
+	 * read-only research subtask to an agent whose definition also grants
+	 * `write` and `bash` had no way to say so. The child ran with
+	 * everything the agent had.
+	 *
+	 * `query()` binds this to BOTH the request tool list and the
+	 * `ToolExecutor`, which is what makes it enforced rather than
+	 * presentational: narrowing only the request showed the model fewer
+	 * tools and let it call any of them by name.
+	 */
+	/**
+	 * Text queued for this run since its last turn, drained at the boundary.
+	 *
+	 * A callback rather than an array, because the queue is owned by
+	 * whoever accepts the messages — `AgentManager` for a delegated child, a
+	 * host for a top-level run — and an array captured at config time would
+	 * be whatever was queued before the run started.
+	 *
+	 * It exists because two public APIs could accept text and silently never
+	 * deliver it. `AgentManager.continueTask` and `queueMessage` pushed onto
+	 * `pendingMessages` and nothing in the kernel ever drained it — the
+	 * manager interface's own docblock said so, and `continue_task` was
+	 * unmounted from the coordinator tools because of it. The steering
+	 * channel had the mirror-image hole: it can only ride on a tool result,
+	 * so guidance queued during a turn that called no tools stayed pending
+	 * until the run ended.
+	 */
+	inboundMessages?: () => import('../message/index.js').Message[]
+
+	allowedTools?: readonly string[]
+
+	/**
+	 * Tools this run may NOT use, subtracted from whatever it would
+	 * otherwise have.
+	 *
+	 * Separate from `allowedTools` because they answer different
+	 * questions and a delegation needs the second. `allowedTools` absent
+	 * means "everything the registry holds", so a caller narrowing a child
+	 * would otherwise have to enumerate the agent's whole tool set to
+	 * remove one from it — and would then silently pin that list against
+	 * an agent that later gains a tool.
+	 */
+	deniedTools?: readonly string[]
+
+	/** Persona for this run, overriding what the agent's definition supplies. */
+	persona?: import('../persona/index.js').AgentPersona
+
+	/**
+	 * Override the logger this run's `AbstractAgent.bindRun` uses instead of
+	 * the logger the agent was CONSTRUCTED with. Same reason `thinking` and
+	 * `effort` are declared here rather than per-config: every concrete agent
+	 * builds its `runConfig` by hand-listing fields, and a field absent from a
+	 * hand-listed literal is dropped in silence. A host that wants one run's
+	 * output routed differently — without reconstructing the agent — sets this.
+	 */
+	logger?: Logger
+
 	/**
 	 * Extra environment variables for this agent's tools and sandboxed
 	 * commands, merged over whatever ambient environment the execution path
@@ -100,7 +162,7 @@ export interface BaseAgentConfig {
 	 * need to be updated before this tightens. Tightening to required
 	 * lands with the `AgentFactoryOptions` triple refactor.
 	 */
-	threadId?: ThreadId
+	topicId?: TopicId
 
 	/** Session under which the run executes. See `projectId` for the tightening plan. */
 	sessionId?: SessionId
@@ -133,7 +195,7 @@ export interface BaseAgentConfig {
 	 * however carefully its parent had been wired.
 	 *
 	 * What that cost is narrower than "no gate in children" and worth
-	 * stating exactly. A `VerificationGate` DENY still bites inside a
+	 * stating exactly. A `AuthorizationGate` DENY still bites inside a
 	 * child, because denials are threaded into the executor and no later
 	 * approval releases them. What was lost is the REVIEW tier: every call
 	 * the gate left undecided went to the resume handler, and for a child
@@ -178,7 +240,7 @@ export interface AgentInput {
 
 export interface BaseAgentResult {
 	runId: RunId
-	status: AgentStatus
+	status: RunExecutionStatus
 	stopReason?: StopReason
 	usage: TokenUsage
 	cost: CostInfo

package/src/types/agent/delegate.ts

@@ -0,0 +1,110 @@
+import type { AgentRuntimeContext } from './base.js'
+
+/**
+ * A delegate that need not be an in-process Namzu agent.
+ *
+ * Delegation was reachable exactly one way: `TaskScheduler.createTask` with
+ * an `agentId` the host's `AgentManager` could resolve. Every delegate was
+ * therefore a Namzu agent, in this process, built from this kernel's own
+ * definition — so a host with a specialist behind an A2A card, an ACP
+ * connection, or any service at all had nowhere to put it except by
+ * implementing the whole `TaskScheduler` surface, most of which is about
+ * bookkeeping the kernel already does.
+ *
+ * This is the surface a foreign delegate actually has to provide: take a
+ * prompt, return an outcome, and say whether it can be cancelled or
+ * continued. `DelegatingTaskScheduler` presents any set of these as a
+ * `TaskScheduler`, so the two delegation tools and everything else that
+ * speaks to a scheduler are unchanged.
+ *
+ * **The roster is still enforced upstream.** The delegation tools check
+ * `allowedAgentIds` before an id reaches any scheduler, so registering a
+ * delegate here does not by itself make it reachable — the same complete
+ * mediation the tools already document.
+ */
+
+export interface DelegateRequest {
+	/** What the delegate is being asked to do. */
+	readonly prompt: string
+	/** The parent's working directory, for a delegate that shares a disk. */
+	readonly workingDirectory: string
+	readonly runtimeContext?: AgentRuntimeContext
+	/**
+	 * The parent's resolved environment.
+	 *
+	 * Forwarded for the reason the `Agent` tool gives for forwarding it to a
+	 * local child: a delegate that cannot see it runs against different
+	 * services than the run that launched it, silently. A remote delegate
+	 * may well ignore it, which is its business.
+	 */
+	readonly env?: Readonly<Record<string, string>>
+}
+
+/**
+ * What a delegate did.
+ *
+ * `status` is the delegate's own answer and is the only authority a foreign
+ * delegate has — there is no second layer to cross-check it against the way
+ * a local run's `TaskHandle.state` and `BaseAgentResult.status` check each
+ * other. `DelegatingTaskScheduler` maps this onto BOTH so that
+ * `taskSucceeded` and `taskFailed` keep working unchanged; that mapping is
+ * the whole reason this type is this small.
+ */
+export interface DelegateResult {
+	readonly status: 'completed' | 'failed' | 'cancelled'
+	/** The answer, when there is one. */
+	readonly output?: string
+	/** Why it failed, in the delegate's own words. */
+	readonly error?: string
+}
+
+/**
+ * What a delegate can do beyond answering once.
+ *
+ * Declared rather than assumed, and a `false` here is REFUSED at the call
+ * rather than quietly no-op'd. A `continueTask` that silently did nothing
+ * would have the parent believe it steered a worker that never heard it.
+ */
+export interface DelegateCapabilities {
+	/** Can a running delegation be cancelled? */
+	readonly cancel: boolean
+	/** Can a message be sent to a delegation already in flight? */
+	readonly continue: boolean
+}
+
+export interface Delegate {
+	/**
+	 * The id the delegation tools name.
+	 *
+	 * Shares a namespace with local agent ids on purpose: a supervisor
+	 * should not have to know whether the specialist it is calling is in
+	 * this process, and moving one from local to remote should not rewrite
+	 * every caller. The collision that follows is refused loudly at
+	 * registration rather than resolved by precedence.
+	 */
+	readonly id: string
+
+	readonly capabilities: DelegateCapabilities
+
+	/**
+	 * Run the delegation to completion.
+	 *
+	 * `signal` fires when the delegation is cancelled. A delegate declaring
+	 * `capabilities.cancel` must honour it; one that does not will never be
+	 * handed a signal that fires, because the scheduler refuses the cancel
+	 * before it gets that far.
+	 */
+	dispatch(
+		request: DelegateRequest,
+		opts: { readonly signal?: AbortSignal },
+	): Promise<DelegateResult>
+
+	/**
+	 * Deliver a message to a delegation in flight.
+	 *
+	 * Present only when `capabilities.continue` is true. The two are checked
+	 * against each other at registration, because a capability that claims a
+	 * method the object does not have is a lie the caller finds at runtime.
+	 */
+	continue?(message: string): Promise<void>
+}

package/src/types/agent/index.ts

@@ -5,7 +5,7 @@ export * from './pipeline.js'
 export * from './router.js'
 export * from './supervisor.js'
 export * from './factory.js'
-export * from './gateway.js'
+export * from './scheduler.js'
 export * from './task.js'
 export * from './lifecycle-event.js'
 export * from './manager.js'

package/src/types/agent/manager.ts

@@ -1,5 +1,6 @@
 import type { RunId, TaskId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
+import type { CancelCause } from '../run/cancel-cause.js'
 import type { RunEventListener } from '../run/events.js'
 import type { AgentLifecycleListener } from './lifecycle-event.js'
 import type { AgentTask, AgentTaskContext, AgentTaskState, SendMessageOptions } from './task.js'
@@ -16,7 +17,12 @@ export interface AgentManagerContract {
 	): Promise<AgentTask>
 
 	cancel(taskId: TaskId): void
-	cancelAll(parentRunId: RunId): void
+	/**
+	 * Defaults to `'parent'` when a caller names nothing, because this call
+	 * site IS a parent abandoning its children — unlike `AbstractAgent.cancel`,
+	 * where the caller could be anyone.
+	 */
+	cancelAll(parentRunId: RunId, cause?: CancelCause): void
 
 	/**
 	 * Queue a message for a running task.

package/src/types/agent/reactive.ts

@@ -1,18 +1,19 @@
 import type { CompactionConfig } from '../../config/runtime.js'
 import type { QueryParams } from '../../runtime/query/index.js'
+import type { SteeringChannel } from '../../runtime/query/steering.js'
 import type { AdvisoryConfig } from '../advisory/index.js'
+import type { AuthorizationGateConfig } from '../authorization/index.js'
 import type { InputGuardrailSpec, OutputGuardrailSpec } from '../guardrail/index.js'
 import type { ResumeHandler } from '../hitl/index.js'
 import type { AgentPersona } from '../persona/index.js'
 import type { LLMProvider } from '../provider/index.js'
 import type { CheckpointStore } from '../run/checkpoint-store.js'
-import type { PrepareStepChain, StepResult, StopCondition } from '../run/index.js'
+import type { BeforeStep, PrepareStepChain, StepResult, StopCondition } from '../run/index.js'
 import type { SandboxProvider } from '../sandbox/index.js'
 import type { Skill } from '../skills/index.js'
 import type { StructuredOutputConfig } from '../structured-output/index.js'
 import type { ToolRegistryContract } from '../tool/index.js'
 import type { RepairToolCall } from '../tool/repair.js'
-import type { VerificationGateConfig } from '../verification/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { WorkingMemoryProvider } from './working-memory.js'
 
@@ -21,6 +22,17 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 
 	persona?: AgentPersona
 
+	/**
+	 * Channel a host uses to hand guidance to this run's current turn.
+	 *
+	 * Present here for the same reason it is on `SupervisorAgentConfig`, and
+	 * the reason that file gives twice already: a capability the kernel
+	 * honours in `drainQuery` and not on the surface hosts actually
+	 * construct is a capability nobody can reach. This is the archetype most
+	 * hosts run, and it was the one that could not be steered at all.
+	 */
+	steering?: SteeringChannel
+
 	skills?: Skill[]
 
 	basePrompt?: string
@@ -39,7 +51,13 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	 * canonical brick patterns hard-deny instead of executing
 	 * silently.
 	 */
-	verificationGate?: VerificationGateConfig
+	/**
+	 * @deprecated Renamed to `authorizationGate`. Removed in the next major.
+	 * Setting both to different configs throws.
+	 */
+	verificationGate?: AuthorizationGateConfig
+
+	authorizationGate?: AuthorizationGateConfig
 
 	/**
 	 * Optional ephemeral sandbox provider. When set, drainQuery creates
@@ -100,6 +118,12 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	stopWhen?: StopCondition
 	onStepFinish?: (step: StepResult) => void
 	prepareStep?: PrepareStepChain
+	/**
+	 * Refuse the next model call before it is made. See {@link BeforeStep}.
+	 * A throw fails CLOSED, opposite to `prepareStep` beside it.
+	 */
+	beforeStep?: BeforeStep
+
 	structuredOutput?: StructuredOutputConfig
 	inputGuardrails?: readonly InputGuardrailSpec[]
 	outputGuardrails?: readonly OutputGuardrailSpec[]