@gajae-code/coding-agent 0.10.2 → 0.11.0

package/src/extensibility/extensions/runner.ts

@@ -6,7 +6,7 @@ import type { CredentialDisabledEvent, ImageContent, Model, ProviderResponseMeta
 import type { KeyId } from "@gajae-code/tui";
 import { logger } from "@gajae-code/utils";
 import type { ModelRegistry } from "../../config/model-registry";
-import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/unattended-session";
+import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/workflow-gate-broker";
 import { type Theme, theme } from "../../modes/theme/theme";
 import type { SessionManager } from "../../session/session-manager";
 import type {
@@ -182,10 +182,41 @@ export class ExtensionRunner {
 	#waitForIdleFn: () => Promise<void> = async () => {};
 	#abortFn: () => void = () => {};
 	#hasPendingMessagesFn: () => boolean = () => false;
+	#getPendingMessageCountsFn: () => { steering: number; followUp: number; nextTurn: number } = () => ({
+		steering: 0,
+		followUp: 0,
+		nextTurn: 0,
+	});
 	#getContextUsageFn: () => ContextUsage | undefined = () => undefined;
 	#compactFn: (instructionsOrOptions?: string | CompactOptions) => Promise<void> = async () => {};
 	#getSystemPromptFn: () => string[] = () => [];
 	#getWorkflowGateFn: () => WorkflowGateEmitter | undefined = () => undefined;
+	#clearContextFn: () => Promise<boolean> = async () => false;
+	#getTranscriptFn: ExtensionContext["getTranscript"] = () => [];
+	#getTranscriptBodyFn: ExtensionContext["getTranscriptBody"] = () => undefined;
+	#getGoalStateFn: ExtensionContext["getGoalState"] = () => undefined;
+	#getTodoStateFn: ExtensionContext["getTodoState"] = () => undefined;
+	#getQueuedMessagesFn: ExtensionContext["getQueuedMessages"] = () => [];
+	#getActiveToolsFn: ExtensionContext["getActiveTools"] = () => [];
+	#getAllToolsFn: ExtensionContext["getAllTools"] = () => [];
+	#cycleModelFn: ExtensionContextActions["cycleModel"] = undefined;
+	#cycleThinkingLevelFn: ExtensionContextActions["cycleThinkingLevel"] = undefined;
+	#setQueueModeFn: ExtensionContextActions["setQueueMode"] = undefined;
+	#getSkillStateFn: ExtensionContextActions["getSkillState"] = undefined;
+	#getConfigItemsFn: ExtensionContextActions["getConfigItems"] = undefined;
+	#getBranchCandidatesFn: ExtensionContextActions["getBranchCandidates"] = undefined;
+	#getExtensionsFn: ExtensionContextActions["getExtensions"] = undefined;
+	#getArtifactFn: ExtensionContextActions["getArtifact"] = undefined;
+	#getArtifactRangeFn: ExtensionContextActions["getArtifactRange"] = undefined;
+
+	#getJobsFn: ExtensionContextActions["getJobs"] = undefined;
+	#sdkControlFn: ExtensionContextActions["sdkControl"] = undefined;
+	#setSdkPermissionProviderFn: ExtensionContextActions["setSdkPermissionProvider"] = undefined;
+
+	#invokeSkillFn: ExtensionContextActions["invokeSkill"] = undefined;
+	#setPlanModeFn: ExtensionContextActions["setPlanMode"] = undefined;
+	#operateGoalFn: ExtensionContextActions["operateGoal"] = undefined;
+
 	#newSessionHandler: NewSessionHandler = async () => ({ cancelled: false });
 	#branchHandler: BranchHandler = async () => ({ cancelled: false });
 	#navigateTreeHandler: NavigateTreeHandler = async () => ({ cancelled: false });
@@ -249,6 +280,14 @@ export class ExtensionRunner {
 		this.runtime.setModel = actions.setModel;
 		this.runtime.getThinkingLevel = actions.getThinkingLevel;
 		this.runtime.setThinkingLevel = actions.setThinkingLevel;
+		this.runtime.getThinkingVisibility = actions.getThinkingVisibility;
+		this.runtime.setThinkingVisibility = actions.setThinkingVisibility;
+		this.runtime.cycleThinkingLevel = actions.cycleThinkingLevel;
+		this.runtime.setThinkingLevelForControl = actions.setThinkingLevelForControl;
+		this.runtime.setThinkingVisibilityForControl = actions.setThinkingVisibilityForControl;
+		this.runtime.setModelTemporaryForControl = actions.setModelTemporaryForControl;
+		this.runtime.fetchUsageReportsForControl = actions.fetchUsageReportsForControl;
+		this.runtime.getThinkingScopeForControl = actions.getThinkingScopeForControl;
 		this.runtime.getSessionName = actions.getSessionName;
 		this.runtime.setSessionName = actions.setSessionName;
 
@@ -257,9 +296,36 @@ export class ExtensionRunner {
 		this.#isIdleFn = contextActions.isIdle;
 		this.#abortFn = contextActions.abort;
 		this.#hasPendingMessagesFn = contextActions.hasPendingMessages;
+		this.#getPendingMessageCountsFn =
+			contextActions.getPendingMessageCounts ?? (() => ({ steering: 0, followUp: 0, nextTurn: 0 }));
 		this.#shutdownHandler = contextActions.shutdown;
 		this.#getSystemPromptFn = contextActions.getSystemPrompt;
 		this.#getWorkflowGateFn = contextActions.getWorkflowGate ?? (() => undefined);
+		this.#clearContextFn = contextActions.clearContext ?? (async () => false);
+		this.#getTranscriptFn = contextActions.getTranscript ?? (() => []);
+		this.#getTranscriptBodyFn = contextActions.getTranscriptBody ?? (() => undefined);
+		this.#getGoalStateFn = contextActions.getGoalState ?? (() => undefined);
+		this.#getTodoStateFn = contextActions.getTodoState ?? (() => undefined);
+		this.#getQueuedMessagesFn = contextActions.getQueuedMessages ?? (() => []);
+		this.#getActiveToolsFn = contextActions.getActiveTools ?? (() => []);
+		this.#getAllToolsFn = contextActions.getAllTools ?? (() => []);
+		this.#cycleModelFn = contextActions.cycleModel;
+		this.#cycleThinkingLevelFn = contextActions.cycleThinkingLevel;
+		this.#setQueueModeFn = contextActions.setQueueMode;
+		this.#getSkillStateFn = contextActions.getSkillState;
+		this.#invokeSkillFn = contextActions.invokeSkill;
+		this.#setPlanModeFn = contextActions.setPlanMode;
+		this.#operateGoalFn = contextActions.operateGoal;
+
+		this.#getConfigItemsFn = contextActions.getConfigItems;
+		this.#getBranchCandidatesFn = contextActions.getBranchCandidates;
+		this.#getExtensionsFn = contextActions.getExtensions;
+		this.#getArtifactFn = contextActions.getArtifact;
+		this.#getArtifactRangeFn = contextActions.getArtifactRange;
+
+		this.#getJobsFn = contextActions.getJobs;
+		this.#sdkControlFn = contextActions.sdkControl;
+		this.#setSdkPermissionProviderFn = contextActions.setSdkPermissionProvider;
 
 		// Command context actions (optional, only for interactive mode)
 		if (commandContextActions) {
@@ -297,8 +363,8 @@ export class ExtensionRunner {
 	 * Forward a `credential_disabled` event from `AuthStorage` to extension handlers.
 	 *
 	 * If {@link initialize} has not yet run, the event is buffered and replayed once
-	 * initialize wires the runtime/UI context. This matters because mode controllers
-	 * (interactive, RPC, ACP, print, subagent) call `initialize()` AFTER `createAgentSession`
+	 * initialize wires the runtime/UI context. This matters because session frontends
+	 * (interactive, ACP, print, and subagent) call `initialize()` AFTER `createAgentSession`
 	 * returns, but `AuthStorage` can fire `credential_disabled` during startup model probes
 	 * inside `createAgentSession()`. Without deferral, extension handlers would observe
 	 * `hasUI=false`, an unset model, and no-op runtime actions on exactly the headline
@@ -483,10 +549,52 @@ export class ExtensionRunner {
 			isIdle: () => this.#isIdleFn(),
 			abort: () => this.#abortFn(),
 			hasPendingMessages: () => this.#hasPendingMessagesFn(),
+			getPendingMessageCounts: () => this.#getPendingMessageCountsFn(),
+			getTranscript: () => this.#getTranscriptFn(),
+			getTranscriptBody: entryId => this.#getTranscriptBodyFn(entryId),
+			getGoalState: () => this.#getGoalStateFn(),
+			getTodoState: () => this.#getTodoStateFn(),
+			getQueuedMessages: () => this.#getQueuedMessagesFn(),
+			getActiveTools: () => this.#getActiveToolsFn(),
+			getAllTools: () => this.#getAllToolsFn(),
+			cycleModel: async () => await this.#cycleModelFn?.(),
+			cycleThinkingLevel: () => this.#cycleThinkingLevelFn?.(),
+			setQueueMode: (kind, mode) => this.#setQueueModeFn?.(kind, mode) ?? false,
+			invokeSkill: async (name, args) => await this.#invokeSkillFn?.(name, args),
+
+			setPlanMode: on => this.#setPlanModeFn?.(on),
+			operateGoal: async (op, objective) => await this.#operateGoalFn?.(op, objective),
+
+			getSkillState: () => this.#getSkillStateFn?.(),
+			getConfigItems: () => this.#getConfigItemsFn?.(),
+			getBranchCandidates: () => this.#getBranchCandidatesFn?.(),
+			getExtensions: () => this.#getExtensionsFn?.(),
+			getArtifact: id => this.#getArtifactFn?.(id),
+			getArtifactRange: (id, offset, length) => this.#getArtifactRangeFn?.(id, offset, length),
+
+			getJobs: () => this.#getJobsFn?.(),
+			sdkControl: (operation, input) => this.#sdkControlFn?.(operation, input),
+			setSdkPermissionProvider: provider => this.#setSdkPermissionProviderFn?.(provider),
+			sdkBindings: () => [
+				...(this.#cycleModelFn ? ["cycleModel"] : []),
+				...(this.#cycleThinkingLevelFn ? ["cycleThinkingLevel"] : []),
+				...(this.#setQueueModeFn ? ["setQueueMode"] : []),
+				...(this.#getSkillStateFn ? ["getSkillState"] : []),
+				...(this.#getConfigItemsFn ? ["getConfigItems"] : []),
+				...(this.#getBranchCandidatesFn ? ["getBranchCandidates"] : []),
+				...(this.#getExtensionsFn ? ["getExtensions"] : []),
+				...(this.#getArtifactRangeFn ? ["getArtifactRange"] : []),
+				...(this.#getJobsFn ? ["getJobs"] : []),
+				...(this.#sdkControlFn ? ["sdkControl"] : []),
+				...(this.#invokeSkillFn ? ["invokeSkill"] : []),
+				...(this.#setPlanModeFn ? ["setPlanMode"] : []),
+				...(this.#operateGoalFn ? ["operateGoal"] : []),
+			],
 			shutdown: () => this.#shutdownHandler(),
 			getSystemPrompt: () => [...this.#getSystemPromptFn()],
 			hasQueuedMessages: () => this.#hasPendingMessagesFn(), // deprecated alias
 			workflowGate: this.#getWorkflowGateFn(),
+			clearContext: () => this.#clearContextFn(),
 		};
 	}
 
@@ -734,7 +842,7 @@ export class ExtensionRunner {
 	async emitInput(
 		text: string,
 		images: ImageContent[] | undefined,
-		source: "interactive" | "rpc" | "extension",
+		source: "interactive" | "sdk" | "extension",
 	): Promise<InputEventResult> {
 		const handlers = this.#handlersByEvent.get("input") ?? [];
 		if (handlers.length === 0) return {};

package/src/extensibility/extensions/types.ts

@@ -7,6 +7,7 @@
  * - Register commands, keyboard shortcuts, and CLI flags
  * - Interact with the user via UI primitives
  */
+
 import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel } from "@gajae-code/agent-core";
 import type { CompactionResult } from "@gajae-code/agent-core/compaction";
 import type {
@@ -21,6 +22,7 @@ import type {
 	Static,
 	TextContent,
 	TSchema,
+	UsageReport,
 } from "@gajae-code/ai";
 import type { OAuthCredentials, OAuthLoginCallbacks } from "@gajae-code/ai/utils/oauth/types";
 import type * as piCodingAgent from "@gajae-code/coding-agent";
@@ -32,8 +34,13 @@ import type { PythonResult } from "../../eval/py/executor";
 import type { BashResult } from "../../exec/bash-executor";
 import type { ExecOptions, ExecResult } from "../../exec/exec";
 import type { CustomEditor } from "../../modes/components/custom-editor";
-import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/unattended-session";
+import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/workflow-gate-broker";
 import type { Theme } from "../../modes/theme/theme";
+import type {
+	ClientBridgePermissionOption,
+	ClientBridgePermissionOutcome,
+	ClientBridgePermissionToolCall,
+} from "../../session/client-bridge";
 import type { CustomMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
 import type {
@@ -114,7 +121,7 @@ export interface ExtensionUIDialogOptions {
 	/**
 	 * For interactive TUI select dialogs, render the focused option across
 	 * multiple rows instead of truncating it. This is a select-only rendering
-	 * hint; non-TUI bridges (RPC, ACP) drop it and do not serialize it.
+	 * hint; non-TUI clients (SDK, ACP) drop it and do not serialize it.
 	 */
 	wrapFocused?: boolean;
 	/**
@@ -128,7 +135,7 @@ export interface ExtensionUIDialogOptions {
 	 * inline: selecting it keeps the title and option list on screen and opens
 	 * a free-text input below the list. Submitting calls `onSubmit` with the
 	 * typed text and resolves the select with `optionLabel`; Escape returns to
-	 * option selection. Non-TUI bridges (RPC, ACP) drop it; callers must keep
+	 * option selection. Non-TUI clients (SDK, ACP) drop it; callers must keep
 	 * a fallback path for selects that resolve `optionLabel` without invoking
 	 * `onSubmit`.
 	 */
@@ -164,7 +171,7 @@ export type ExtensionWidgetContent = string[] | ExtensionUiComponentFactory | un
 
 /**
  * UI context for extensions to request interactive UI.
- * Each mode (interactive, RPC, print) provides its own implementation.
+ * Interactive, SDK, and headless callers provide their own implementation.
  */
 // fallow-ignore-next-line code-duplication
 // Parallel to HookUIContext: extensions expose a strictly larger UI surface
@@ -272,6 +279,14 @@ export interface ExtensionUIContext {
 // Extension Context
 // ============================================================================
 
+export interface ExtensionTranscriptEntry {
+	id: string;
+	role: string;
+	textSummary: string;
+	ts: string;
+	body?: string;
+}
+
 export interface ContextUsage {
 	/** Context tokens, or null if unknown (e.g. right after compaction, before next LLM response). */
 	tokens: number | null;
@@ -309,7 +324,7 @@ export interface ExtensionContext {
 	getContextUsage(): ContextUsage | undefined;
 	/** Compact the session context (interactive mode shows UI). */
 	compact(instructionsOrOptions?: string | CompactOptions): Promise<void>;
-	/** Whether UI is available (false in print/RPC mode) */
+	/** Whether an interactive UI is available */
 	hasUI: boolean;
 	/** Current working directory */
 	cwd: string;
@@ -327,17 +342,65 @@ export interface ExtensionContext {
 	abort(): void;
 	/** Whether there are queued messages waiting */
 	hasPendingMessages(): boolean;
+	/** Typed pending-message counts per queue (steering, follow-up, next-turn). */
+	getPendingMessageCounts(): { steering: number; followUp: number; nextTurn: number };
+	/** Read-only session data exposed to extensions and the SDK host. */
+	getTranscript(): ExtensionTranscriptEntry[];
+	getTranscriptBody(entryId: string): string | undefined;
+	getGoalState(): unknown;
+	getTodoState(): unknown;
+	getQueuedMessages(): unknown[];
+	getActiveTools(): string[];
+	getAllTools(): string[];
+	/** Session control seams used by the SDK host. */
+	cycleModel(): Promise<{ model: Model; thinkingLevel: ThinkingLevel | undefined } | undefined>;
+	cycleThinkingLevel(): ThinkingLevel | undefined;
+	setQueueMode(kind: "steering" | "follow_up" | "interrupt", mode: unknown): boolean;
+	getSkillState(): unknown;
+	getConfigItems(): unknown;
+	getBranchCandidates(): unknown;
+	getExtensions(): unknown;
+	getArtifact(id: string): Uint8Array | string | undefined | Promise<Uint8Array | string | undefined>;
+	getArtifactRange?(
+		id: string,
+		offset: number,
+		length: number,
+	):
+		| { bytes: Uint8Array; totalBytes: number }
+		| undefined
+		| Promise<{ bytes: Uint8Array; totalBytes: number } | undefined>;
+
+	getJobs(): unknown;
+	/** Typed skill and mode controls exposed to the SDK host. */
+	invokeSkill?(name: string, args?: string): Promise<unknown>;
+	setPlanMode?(on: boolean): unknown;
+	operateGoal?(op: "create" | "get" | "resume" | "pause" | "complete" | "drop", objective?: string): Promise<unknown>;
+
+	/** Typed nonvisual session controls exposed to the SDK host. */
+	sdkControl?(operation: string, input: Record<string, unknown>): unknown | Promise<unknown>;
+	/** Install a permission callback backed by a live SDK reverse provider lease. */
+	setSdkPermissionProvider?(
+		provider:
+			| ((
+					toolCall: ClientBridgePermissionToolCall,
+					options: ClientBridgePermissionOption[],
+					signal?: AbortSignal,
+			  ) => Promise<ClientBridgePermissionOutcome>)
+			| undefined,
+	): void;
+	/** Names of session SDK seams actually installed by the active runtime. */
+	sdkBindings?(): readonly string[];
+
 	/** Gracefully shutdown and exit. */
 	shutdown(): void;
 	/** Get the current effective system prompt. */
 	getSystemPrompt(): string[];
 	/** @deprecated Use hasPendingMessages() instead */
 	hasQueuedMessages(): boolean;
-	/**
-	 * Unattended workflow-gate bridge. Present only when the session runs in
-	 * unattended/RPC mode; `undefined` in interactive/TUI mode (notify-only).
-	 */
+	/** SDK workflow-gate bridge, when a session has a remote gate responder. */
 	workflowGate?: WorkflowGateEmitter;
+	/** Clear the active conversation while preserving the saved session identity. */
+	clearContext(): Promise<boolean>;
 }
 
 /**
@@ -611,12 +674,12 @@ export interface UserPythonEvent {
 // Input Events
 // ============================================================================
 
-/** Fired when the user submits input (interactive mode only). */
+/** Fired when input enters through an interactive, SDK, or extension source. */
 export interface InputEvent {
 	type: "input";
 	text: string;
 	images?: ImageContent[];
-	source: "interactive" | "rpc" | "extension";
+	source: "interactive" | "sdk" | "extension";
 }
 
 // ============================================================================
@@ -1026,8 +1089,8 @@ export interface ExtensionAPI {
 	/** Send a user message to the agent, or queue it when deliverAs is set. */
 	sendUserMessage(
 		content: string | (TextContent | ImageContent)[],
-		options?: { deliverAs?: "steer" | "followUp" },
-	): void;
+		options?: { deliverAs?: "steer" | "followUp"; onPreflightAccepted?: () => void },
+	): Promise<void>;
 
 	/** Append a custom entry to the session for state persistence (not sent to LLM). */
 	appendEntry<T = unknown>(customType: string, data?: T): void;
@@ -1054,7 +1117,31 @@ export interface ExtensionAPI {
 	getThinkingLevel(): ThinkingLevel | undefined;
 
 	/** Set thinking level for the current session. */
-	setThinkingLevel(level: ThinkingLevel): void;
+	setThinkingLevel(level: ThinkingLevel, persist?: boolean): void;
+
+	/** Get whether thinking output is visible in the current session. */
+	getThinkingVisibility(): "visible" | "hidden";
+
+	/** Set whether thinking output is visible for the current session. */
+	setThinkingVisibility(visibility: "visible" | "hidden", persist?: boolean): void;
+
+	/** Cycle the current model's available thinking levels. */
+	cycleThinkingLevel(): ThinkingLevel | undefined;
+
+	/** Set thinking level from a session or durable global control surface. */
+	setThinkingLevelForControl(level: ThinkingLevel, persist: boolean): Promise<void>;
+
+	/** Set thinking visibility from a session or durable global control surface. */
+	setThinkingVisibilityForControl(visibility: "visible" | "hidden", persist: boolean): Promise<void>;
+
+	/** Set the model for this session only. Returns false when it is unavailable. */
+	setModelTemporaryForControl(model: Model, expectedSessionId?: string): Promise<boolean>;
+
+	/** Fetch provider usage through the session's canonical provider resolution. */
+	fetchUsageReportsForControl(): Promise<UsageReport[] | null>;
+
+	/** Report whether the current effort follows global config or a session override. */
+	getThinkingScopeForControl(): "session" | "global config";
 
 	/** Get the current session name. */
 	getSessionName(): string | undefined;
@@ -1209,8 +1296,8 @@ export type SendMessageHandler = <T = unknown>(
 
 export type SendUserMessageHandler = (
 	content: string | (TextContent | ImageContent)[],
-	options?: { deliverAs?: "steer" | "followUp" },
-) => void;
+	options?: { deliverAs?: "steer" | "followUp"; onPreflightAccepted?: () => void },
+) => void | Promise<void>;
 
 export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
 
@@ -1224,10 +1311,29 @@ export type SetActiveToolsHandler = (toolNames: string[]) => Promise<void>;
 
 export type SetModelHandler = (model: Model) => Promise<boolean>;
 
+export type CycleThinkingLevelHandler = () => ThinkingLevel | undefined;
+
+export type SetThinkingLevelForControlHandler = (level: ThinkingLevel, persist: boolean) => Promise<void>;
+
+export type SetThinkingVisibilityForControlHandler = (
+	visibility: "visible" | "hidden",
+	persist: boolean,
+) => Promise<void>;
+
+export type SetModelTemporaryForControlHandler = (model: Model, expectedSessionId?: string) => Promise<boolean>;
+
+export type FetchUsageReportsForControlHandler = () => Promise<UsageReport[] | null>;
+
+export type GetThinkingScopeForControlHandler = () => "session" | "global config";
+
 export type GetThinkingLevelHandler = () => ThinkingLevel | undefined;
 
 export type SetThinkingLevelHandler = (level: ThinkingLevel, persist?: boolean) => void;
 
+export type GetThinkingVisibilityHandler = () => "visible" | "hidden";
+
+export type SetThinkingVisibilityHandler = (visibility: "visible" | "hidden", persist?: boolean) => void;
+
 /** Shared state created by loader, used during registration and runtime. */
 export interface ExtensionRuntimeState {
 	flagValues: Map<string, boolean | string>;
@@ -1248,6 +1354,14 @@ export interface ExtensionActions {
 	setModel: SetModelHandler;
 	getThinkingLevel: GetThinkingLevelHandler;
 	setThinkingLevel: SetThinkingLevelHandler;
+	getThinkingVisibility: GetThinkingVisibilityHandler;
+	setThinkingVisibility: SetThinkingVisibilityHandler;
+	cycleThinkingLevel: CycleThinkingLevelHandler;
+	setThinkingLevelForControl: SetThinkingLevelForControlHandler;
+	setThinkingVisibilityForControl: SetThinkingVisibilityForControlHandler;
+	setModelTemporaryForControl: SetModelTemporaryForControlHandler;
+	fetchUsageReportsForControl: FetchUsageReportsForControlHandler;
+	getThinkingScopeForControl: GetThinkingScopeForControlHandler;
 	getSessionName: () => string | undefined;
 	setSessionName: (name: string) => Promise<void>;
 }
@@ -1258,12 +1372,57 @@ export interface ExtensionContextActions {
 	isIdle: () => boolean;
 	abort: () => void;
 	hasPendingMessages: () => boolean;
+	/** Typed pending-message counts per queue; optional for embedders without a counted queue. */
+	getPendingMessageCounts?: () => { steering: number; followUp: number; nextTurn: number };
+	getTranscript?: () => ExtensionTranscriptEntry[];
+	getTranscriptBody?: (entryId: string) => string | undefined;
+	getGoalState?: () => unknown;
+	getTodoState?: () => unknown;
+	getQueuedMessages?: () => unknown[];
+	getActiveTools?: () => string[];
+	getAllTools?: () => string[];
 	shutdown: () => void;
 	getContextUsage: () => ContextUsage | undefined;
 	compact: (instructionsOrOptions?: string | CompactOptions) => Promise<void>;
 	getSystemPrompt: () => string[];
-	/** Unattended workflow-gate bridge (present only in unattended/RPC mode). */
+	/** SDK workflow-gate bridge, when a session has a remote gate responder. */
 	getWorkflowGate?: () => WorkflowGateEmitter | undefined;
+	/** Clear the active conversation while preserving the saved session identity. */
+	clearContext?: () => Promise<boolean>;
+	/** Session control and query seams exposed to the per-session SDK host. */
+	cycleModel?: () => Promise<{ model: Model; thinkingLevel: ThinkingLevel | undefined } | undefined>;
+	cycleThinkingLevel?: () => ThinkingLevel | undefined;
+	setQueueMode?: (kind: "steering" | "follow_up" | "interrupt", mode: unknown) => boolean;
+	getSkillState?: () => unknown;
+	getConfigItems?: () => unknown;
+	getBranchCandidates?: () => unknown;
+	getExtensions?: () => unknown;
+	getArtifact?: (id: string) => Uint8Array | string | undefined | Promise<Uint8Array | string | undefined>;
+	getArtifactRange?: (
+		id: string,
+		offset: number,
+		length: number,
+	) =>
+		| { bytes: Uint8Array; totalBytes: number }
+		| undefined
+		| Promise<{ bytes: Uint8Array; totalBytes: number } | undefined>;
+	getJobs?: () => unknown;
+	setSdkPermissionProvider?: (
+		provider:
+			| ((
+					toolCall: ClientBridgePermissionToolCall,
+					options: ClientBridgePermissionOption[],
+					signal?: AbortSignal,
+			  ) => Promise<ClientBridgePermissionOutcome>)
+			| undefined,
+	) => void;
+	sdkControl?: (operation: string, input: Record<string, unknown>) => unknown | Promise<unknown>;
+	invokeSkill?: (name: string, args?: string) => Promise<unknown>;
+	setPlanMode?: (on: boolean) => unknown;
+	operateGoal?: (
+		op: "create" | "get" | "resume" | "pause" | "complete" | "drop",
+		objective?: string,
+	) => Promise<unknown>;
 }
 
 /** Actions for ExtensionCommandContext (ctx.* in command handlers). */

package/src/extensibility/hooks/types.ts

@@ -45,7 +45,7 @@ export type { ExecOptions, ExecResult } from "../../exec/exec";
 
 /**
  * UI context for hooks to request interactive UI from the harness.
- * Each mode (interactive, RPC, print) provides its own implementation.
+ * Interactive and headless callers provide their own implementation.
  */
 // fallow-ignore-next-line code-duplication
 // Parallel to ExtensionUIContext: hooks expose a deliberately narrower UI