@sayknow-cli/coding-agent 0.4.6 → 0.5.0

package/src/edit/path-mutation-lock.ts

@@ -0,0 +1,112 @@
+/**
+ * Path-scoped mutation coordinator for edit tools.
+ *
+ * Serializes concurrent read→compute→write windows against the same absolute
+ * path so independent sessions cannot silently overwrite each other's successful
+ * disjoint edits (https://github.com/jaybeyond/Sayknow_CLI/issues/2900).
+ *
+ * - Always: in-process async mutex keyed by resolved absolute path.
+ * - Optionally: durable cross-process `<path>.lock` via `withFileLock` for real
+ *   filesystem mutations (subagents / separate processes).
+ *
+ * Nested acquisition of the same path is not supported; callers that already
+ * hold the lock must not re-enter.
+ */
+import * as path from "node:path";
+import { type FileLockOptions, withFileLock } from "../config/file-lock";
+
+type AsyncMutex = {
+	acquire(): Promise<() => void>;
+};
+
+const pathMutexes = new Map<string, AsyncMutex>();
+
+function createAsyncMutex(): AsyncMutex {
+	let locked = false;
+	const waiters: Array<() => void> = [];
+	return {
+		async acquire(): Promise<() => void> {
+			if (!locked) {
+				locked = true;
+				return () => release();
+			}
+			const { promise, resolve } = Promise.withResolvers<void>();
+			waiters.push(resolve);
+			await promise;
+			return () => release();
+		},
+	};
+
+	function release(): void {
+		const next = waiters.shift();
+		if (next) {
+			next();
+			return;
+		}
+		locked = false;
+	}
+}
+
+function mutexFor(absolutePath: string): AsyncMutex {
+	const key = path.resolve(absolutePath);
+	let mutex = pathMutexes.get(key);
+	if (!mutex) {
+		mutex = createAsyncMutex();
+		pathMutexes.set(key, mutex);
+	}
+	return mutex;
+}
+
+async function withInProcessPathLock<T>(absolutePath: string, fn: () => Promise<T>): Promise<T> {
+	const release = await mutexFor(absolutePath).acquire();
+	try {
+		return await fn();
+	} finally {
+		release();
+	}
+}
+
+/** Default lock budget: long enough for large writes + formatter writeback. */
+const DEFAULT_CROSS_PROCESS_LOCK: FileLockOptions = {
+	staleMs: 60_000,
+	retries: 600,
+	retryDelayMs: 50,
+};
+
+export type EditPathMutationOptions = {
+	/**
+	 * When true (default), also acquire a durable cross-process file lock.
+	 * Disable for injectible/in-memory filesystem tests that do not touch disk.
+	 */
+	crossProcess?: boolean;
+	fileLock?: FileLockOptions;
+};
+
+/**
+ * Run `fn` while holding exclusive mutation rights for every absolute path.
+ * Paths are locked in lexicographic order to avoid deadlocks on multi-path ops
+ * (e.g. rename source + destination).
+ */
+export async function withEditPathMutation<T>(
+	absolutePaths: readonly string[],
+	fn: () => Promise<T>,
+	options: EditPathMutationOptions = {},
+): Promise<T> {
+	const unique = [...new Set(absolutePaths.map(entry => path.resolve(entry)))].sort();
+	if (unique.length === 0) return fn();
+
+	const crossProcess = options.crossProcess !== false;
+	const fileLock = { ...DEFAULT_CROSS_PROCESS_LOCK, ...options.fileLock };
+
+	const runAt = async (index: number): Promise<T> => {
+		if (index >= unique.length) return fn();
+		const target = unique[index];
+		const next = () => runAt(index + 1);
+		return withInProcessPathLock(target, async () => {
+			if (!crossProcess) return next();
+			return withFileLock(target, next, fileLock);
+		});
+	};
+
+	return runAt(0);
+}

package/src/eval/js/tool-bridge.ts

@@ -30,7 +30,7 @@ function toolResultHasError(result: AgentToolResult): boolean {
 }
 
 function getTool(session: ToolSession, name: string): AgentTool {
-	const tool = session.getToolByName?.(name);
+	const tool = session.getToolForExecution ? session.getToolForExecution(name) : session.getToolByName?.(name);
 	if (!tool) {
 		throw new ToolError(`Unknown tool from js runtime: ${name}`);
 	}

package/src/eval/py/executor.ts

@@ -61,7 +61,7 @@ export interface PythonExecutorOptions {
 	/** @internal Bridge session id, set by `executePython` before delegating. */
 	bridgeSessionId?: string;
 	/** @internal Bridge endpoint info, set by `executePython` before delegating. */
-	bridge?: { url: string; token: string };
+	bridge?: { url: string; capability: string };
 }
 
 export interface PythonKernelExecutor {
@@ -106,6 +106,7 @@ export interface PythonResult {
 interface PythonSession {
 	sessionId: string;
 	kernel: PythonKernel;
+	bridgeCapability?: string;
 	ownerIds: Set<string>;
 	hasFallbackOwner: boolean;
 	queue: Promise<void>;
@@ -261,14 +262,14 @@ function buildKernelEnv(options: {
 	sessionFile?: string;
 	artifactsDir?: string;
 	bridgeSessionId?: string;
-	bridge?: { url: string; token: string };
+	bridge?: { url: string; capability: string };
 }): Record<string, string> | undefined {
 	const env: Record<string, string> = {};
 	if (options.sessionFile) env.PI_SESSION_FILE = options.sessionFile;
 	if (options.artifactsDir) env.PI_ARTIFACTS_DIR = options.artifactsDir;
 	if (options.bridge && options.bridgeSessionId) {
 		env.PI_TOOL_BRIDGE_URL = options.bridge.url;
-		env.PI_TOOL_BRIDGE_TOKEN = options.bridge.token;
+		env.PI_TOOL_BRIDGE_CAPABILITY = options.bridge.capability;
 		env.PI_TOOL_BRIDGE_SESSION = options.bridgeSessionId;
 	}
 	return Object.keys(env).length > 0 ? env : undefined;
@@ -328,6 +329,7 @@ async function acquireSession(sessionId: string, cwd: string, options: PythonExe
 			const session: PythonSession = {
 				sessionId,
 				kernel,
+				bridgeCapability: options.bridge?.capability,
 				ownerIds: new Set(),
 				hasFallbackOwner: false,
 				queue: Promise.resolve(),
@@ -361,12 +363,25 @@ async function replaceSessionKernel(
 		throw new PythonExecutionCancelledError(false);
 	}
 	requireRemainingTimeoutMs(options.deadlineMs);
-	const next = await startKernel(cwd, options);
-	if (sessions.get(session.sessionId) !== session) {
-		await next.shutdown().catch(() => undefined);
-		throw new PythonExecutionCancelledError(false);
+	const bridge = options.bridge;
+	const previousCapability = bridge?.capability;
+	const nextCapability = bridge ? crypto.randomUUID() : undefined;
+	if (bridge && nextCapability) bridge.capability = nextCapability;
+	let next: PythonKernel | undefined;
+	try {
+		next = await startKernel(cwd, options);
+		if (sessions.get(session.sessionId) !== session) {
+			throw new PythonExecutionCancelledError(false);
+		}
+		session.kernel = next;
+		session.bridgeCapability = nextCapability;
+	} catch (err) {
+		await next?.shutdown().catch(() => undefined);
+		if (bridge && previousCapability && bridge.capability === nextCapability) {
+			bridge.capability = previousCapability;
+		}
+		throw err;
 	}
-	session.kernel = next;
 }
 
 async function resetSession(sessionId: string): Promise<void> {
@@ -481,8 +496,8 @@ async function executeWithKernel(
 			displayOutputs.push({ type: "status", event });
 		});
 	const unregisterBridge =
-		options?.toolSession && options?.bridgeSessionId
-			? registerPyToolBridge(options.bridgeSessionId, {
+		options?.toolSession && options?.bridgeSessionId && options.bridge
+			? registerPyToolBridge(options.bridgeSessionId, options.bridge.capability, {
 					toolSession: options.toolSession,
 					signal: options.signal,
 					emitStatus,
@@ -499,8 +514,11 @@ async function executeWithKernel(
 		});
 
 		if (result.cancelled) {
+			// Prefer the caller-configured timeout for the user-facing annotation.
+			// Remaining wall-clock budget can shrink after async setup (Settings.init,
+			// kernel start) and would otherwise flake Math.round() second formatting.
 			const annotation = result.timedOut
-				? formatKernelTimeoutAnnotation(executionTimeoutMs, result.kernelKilled ?? false)
+				? formatKernelTimeoutAnnotation(options?.timeoutMs ?? executionTimeoutMs, result.kernelKilled ?? false)
 				: undefined;
 			let crashNotice: string | null = null;
 			if (result.kernelKilled) {
@@ -554,7 +572,9 @@ async function executeWithKernel(
 				cancelled: true,
 				displayOutputs,
 				stdinRequested: false,
-				...(await sink.dump(timedOut ? formatTimeoutAnnotation(executionTimeoutMs) : undefined)),
+				...(await sink.dump(
+					timedOut ? formatTimeoutAnnotation(options?.timeoutMs ?? executionTimeoutMs) : undefined,
+				)),
 			};
 		}
 		const error = err instanceof Error ? err : new Error(String(err));
@@ -578,7 +598,8 @@ async function ensureKernelAvailable(cwd: string, options: PythonExecutorOptions
 async function ensureToolBridge(options: PythonExecutorOptions): Promise<void> {
 	if (!options.toolSession || options.bridge) return;
 	try {
-		options.bridge = await ensurePyToolBridge();
+		const bridge = await ensurePyToolBridge();
+		options.bridge = { ...bridge, capability: crypto.randomUUID() };
 	} catch (err) {
 		logger.warn("Failed to start Python tool bridge", {
 			error: err instanceof Error ? err.message : String(err),
@@ -607,6 +628,9 @@ async function executeOnSession(code: string, cwd: string, options: PythonExecut
 		await resetSession(sessionId);
 	}
 	const session = await acquireSession(sessionId, cwd, options);
+	if (options.bridge && session.bridgeCapability) {
+		options.bridge.capability = session.bridgeCapability;
+	}
 	return await runQueued(session, options, async () => {
 		if (options.signal?.aborted) {
 			throw new PythonExecutionCancelledError(isTimedOutCancellation(options.signal.reason, options.signal));

package/src/eval/py/kernel.ts

@@ -8,9 +8,6 @@
  * Shutdown writes `{"type":"exit"}` and escalates to SIGTERM/SIGKILL on
  * timeout.
  */
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
 import { $env, isBunTestRuntime, logger, Snowflake } from "@sayknow-cli/utils";
 import type { Subprocess } from "bun";
 import { $ } from "bun";
@@ -18,7 +15,7 @@ import { Settings } from "../../config/settings";
 import { type KernelDisplayOutput, renderKernelDisplay } from "./display";
 import { resolvePythonIpcTrace, resolvePythonSkipCheck } from "./env";
 import { PYTHON_PRELUDE } from "./prelude";
-import RUNNER_SCRIPT from "./runner.py" with { type: "text" };
+import { ensureRunnerScript } from "./runner-artifact";
 import { ensurePythonRuntime, filterEnv, type PythonRuntimeOptions } from "./runtime";
 
 export type { KernelDisplayOutput, PythonStatusEvent } from "./display";
@@ -27,23 +24,6 @@ export { renderKernelDisplay } from "./display";
 // Dual-read: `SKC_PYTHON_IPC_TRACE` is preferred, then legacy `PI_PYTHON_IPC_TRACE`.
 const TRACE_IPC = resolvePythonIpcTrace($env);
 
-// Cache the runner script on disk so the subprocess loads it normally. Cached
-// per script hash so installs don't race across versions.
-const RUNNER_CACHE_DIR = path.join(os.tmpdir(), "skc-python-runner");
-let RUNNER_SCRIPT_PATH: string | null = null;
-
-async function ensureRunnerScript(): Promise<string> {
-	if (RUNNER_SCRIPT_PATH) return RUNNER_SCRIPT_PATH;
-	await fs.promises.mkdir(RUNNER_CACHE_DIR, { recursive: true });
-	const hash = Bun.hash(RUNNER_SCRIPT).toString(36);
-	const target = path.join(RUNNER_CACHE_DIR, `runner-${hash}.py`);
-	if (!fs.existsSync(target)) {
-		await Bun.write(target, RUNNER_SCRIPT);
-	}
-	RUNNER_SCRIPT_PATH = target;
-	return target;
-}
-
 const SHUTDOWN_GRACE_MS = 1_000;
 const STARTUP_TIMEOUT_MS = 10_000;
 // How long to wait after SIGINT for the runner to emit `done`. If the cell is

package/src/eval/py/prelude.py

@@ -453,10 +453,10 @@ if "__skc_prelude_loaded__" not in globals():
 
     if all(
         _k in os.environ
-        for _k in ("PI_TOOL_BRIDGE_URL", "PI_TOOL_BRIDGE_TOKEN", "PI_TOOL_BRIDGE_SESSION")
+        for _k in ("PI_TOOL_BRIDGE_URL", "PI_TOOL_BRIDGE_CAPABILITY", "PI_TOOL_BRIDGE_SESSION")
     ):
         tool = _ToolProxy(
             os.environ["PI_TOOL_BRIDGE_URL"],
-            os.environ["PI_TOOL_BRIDGE_TOKEN"],
+            os.environ["PI_TOOL_BRIDGE_CAPABILITY"],
             os.environ["PI_TOOL_BRIDGE_SESSION"],
         )

package/src/eval/py/runner-artifact.ts

@@ -0,0 +1,84 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { postmortem } from "@sayknow-cli/utils";
+import RUNNER_SCRIPT from "./runner.py" with { type: "text" };
+
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+const DIRECTORY_PREFIX = "skc-python-runner-";
+
+interface RunnerScriptArtifact {
+	directory: string;
+	scriptPath: string;
+}
+
+async function initializeRunnerScript(tempRoot: string): Promise<RunnerScriptArtifact> {
+	const directory = await fs.mkdtemp(path.join(tempRoot, DIRECTORY_PREFIX));
+	try {
+		if (process.platform !== "win32") await fs.chmod(directory, DIRECTORY_MODE);
+		const scriptPath = path.join(directory, "runner.py");
+		const handle = await fs.open(scriptPath, "wx", FILE_MODE);
+		try {
+			await handle.writeFile(RUNNER_SCRIPT, { encoding: "utf8" });
+			if (process.platform !== "win32") await handle.chmod(FILE_MODE);
+		} finally {
+			await handle.close();
+		}
+		return { directory, scriptPath };
+	} catch (error) {
+		await fs.rm(directory, { recursive: true, force: true }).catch(() => {});
+		throw error;
+	}
+}
+
+export interface RunnerScriptCache {
+	ensureRunnerScript(): Promise<string>;
+	cleanup(): Promise<void>;
+}
+
+export function createRunnerScriptCache(tempRoot: string): RunnerScriptCache {
+	let initialization: Promise<RunnerScriptArtifact> | null = null;
+	let artifact: RunnerScriptArtifact | null = null;
+	let cleanupAttempt: Promise<void> | null = null;
+
+	return {
+		async ensureRunnerScript() {
+			if (artifact) return artifact.scriptPath;
+			if (!initialization) initialization = initializeRunnerScript(tempRoot);
+			try {
+				artifact = await initialization;
+				return artifact.scriptPath;
+			} catch (error) {
+				if (initialization) initialization = null;
+				throw error;
+			}
+		},
+		async cleanup() {
+			if (cleanupAttempt) return await cleanupAttempt;
+			cleanupAttempt = (async () => {
+				const initialized = await initialization?.catch(() => null);
+				const directory = artifact?.directory ?? initialized?.directory;
+				artifact = null;
+				initialization = null;
+				if (directory) await fs.rm(directory, { recursive: true, force: true });
+			})();
+			try {
+				await cleanupAttempt;
+			} finally {
+				cleanupAttempt = null;
+			}
+		},
+	};
+}
+
+/** @internal Test-only initializer for isolated artifact assertions. */
+export function createRunnerScriptInitializer(tempRoot: string): () => Promise<string> {
+	return createRunnerScriptCache(tempRoot).ensureRunnerScript;
+}
+
+const processRunnerScriptCache = createRunnerScriptCache(os.tmpdir());
+
+export const ensureRunnerScript = () => processRunnerScriptCache.ensureRunnerScript();
+
+postmortem.register("python-runner-artifact", () => processRunnerScriptCache.cleanup());

package/src/eval/py/tool-bridge.ts

@@ -19,7 +19,10 @@ export interface PyToolBridgeEntry {
 
 export interface PyToolBridgeInfo {
 	url: string;
-	token: string;
+}
+
+interface PyToolBridgeRegistration extends PyToolBridgeEntry {
+	sessionId: string;
 }
 
 interface BridgeServer {
@@ -27,11 +30,20 @@ interface BridgeServer {
 	stop: () => Promise<void>;
 }
 
-const registrations = new Map<string, PyToolBridgeEntry>();
+const registrations = new Map<string, PyToolBridgeRegistration>();
 let serverPromise: Promise<BridgeServer> | null = null;
 
+function isCanonicalCapability(capability: string): boolean {
+	return capability.length > 0 && !/\s/.test(capability);
+}
+
+function parseBearerCapability(authorization: string | null): string | null {
+	if (!authorization?.startsWith("Bearer ")) return null;
+	const capability = authorization.slice("Bearer ".length);
+	return isCanonicalCapability(capability) ? capability : null;
+}
+
 async function startServer(): Promise<BridgeServer> {
-	const token = crypto.randomUUID();
 	const server = Bun.serve({
 		hostname: "127.0.0.1",
 		port: 0,
@@ -40,7 +52,12 @@ async function startServer(): Promise<BridgeServer> {
 			if (req.method !== "POST" || url.pathname !== "/v1/tool") {
 				return new Response("Not Found", { status: 404 });
 			}
-			if (req.headers.get("authorization") !== `Bearer ${token}`) {
+			const capability = parseBearerCapability(req.headers.get("authorization"));
+			if (!capability) {
+				return new Response("Forbidden", { status: 403 });
+			}
+			const registration = registrations.get(capability);
+			if (!registration) {
 				return new Response("Forbidden", { status: 403 });
 			}
 
@@ -55,19 +72,15 @@ async function startServer(): Promise<BridgeServer> {
 			if (!sessionId || !name) {
 				return Response.json({ ok: false, error: "Missing session/name" }, { status: 400 });
 			}
-			const entry = registrations.get(sessionId);
-			if (!entry) {
-				return Response.json(
-					{ ok: false, error: `No active Python tool bridge session: ${sessionId}` },
-					{ status: 200 },
-				);
+			if (sessionId !== registration.sessionId) {
+				return new Response("Forbidden", { status: 403 });
 			}
 
 			try {
 				const value = await callSessionTool(name, body.args, {
-					session: entry.toolSession,
-					signal: entry.signal,
-					emitStatus: entry.emitStatus,
+					session: registration.toolSession,
+					signal: registration.signal,
+					emitStatus: registration.emitStatus,
 				});
 				return Response.json({ ok: true, value });
 			} catch (err) {
@@ -81,7 +94,6 @@ async function startServer(): Promise<BridgeServer> {
 
 	const info: PyToolBridgeInfo = {
 		url: `http://${server.hostname}:${server.port}`,
-		token,
 	};
 	logger.debug("Python tool bridge listening", { url: info.url });
 
@@ -111,11 +123,15 @@ export async function ensurePyToolBridge(): Promise<PyToolBridgeInfo> {
  * Register a tool session for the duration of one execution. The returned
  * function MUST be called to remove the entry once execution finishes.
  */
-export function registerPyToolBridge(sessionId: string, entry: PyToolBridgeEntry): () => void {
-	registrations.set(sessionId, entry);
+export function registerPyToolBridge(sessionId: string, capability: string, entry: PyToolBridgeEntry): () => void {
+	if (!isCanonicalCapability(capability)) {
+		throw new Error("Python tool bridge capability must be a non-empty canonical bearer token");
+	}
+	const registration = { ...entry, sessionId };
+	registrations.set(capability, registration);
 	return () => {
-		if (registrations.get(sessionId) === entry) {
-			registrations.delete(sessionId);
+		if (registrations.get(capability) === registration) {
+			registrations.delete(capability);
 		}
 	};
 }

package/src/extensibility/extensions/runner.ts

@@ -201,6 +201,7 @@ export class ExtensionRunner {
 	#getAllToolsFn: ExtensionContext["getAllTools"] = () => [];
 	#getResolveToolFn: ExtensionContext["resolveTool"] = () => undefined;
 	#cycleModelFn: ExtensionContextActions["cycleModel"] = undefined;
+	#setModelProfileFn: ExtensionContextActions["setModelProfile"] = undefined;
 	#cycleThinkingLevelFn: ExtensionContextActions["cycleThinkingLevel"] = undefined;
 	#setQueueModeFn: ExtensionContextActions["setQueueMode"] = undefined;
 	#getSkillStateFn: ExtensionContextActions["getSkillState"] = undefined;
@@ -313,6 +314,7 @@ export class ExtensionRunner {
 		this.#getAllToolsFn = contextActions.getAllTools ?? (() => []);
 		this.#getResolveToolFn = contextActions.resolveTool ?? (() => undefined);
 		this.#cycleModelFn = contextActions.cycleModel;
+		this.#setModelProfileFn = contextActions.setModelProfile;
 		this.#cycleThinkingLevelFn = contextActions.cycleThinkingLevel;
 		this.#setQueueModeFn = contextActions.setQueueMode;
 		this.#getSkillStateFn = contextActions.getSkillState;
@@ -562,6 +564,7 @@ export class ExtensionRunner {
 			getAllTools: () => this.#getAllToolsFn(),
 			resolveTool: name => this.#getResolveToolFn(name),
 			cycleModel: async () => await this.#cycleModelFn?.(),
+			setModelProfile: async name => (await this.#setModelProfileFn?.(name)) ?? false,
 			cycleThinkingLevel: () => this.#cycleThinkingLevelFn?.(),
 			setQueueMode: (kind, mode) => this.#setQueueModeFn?.(kind, mode) ?? false,
 			invokeSkill: async (name, args) => await this.#invokeSkillFn?.(name, args),
@@ -581,6 +584,7 @@ export class ExtensionRunner {
 			setSdkPermissionProvider: provider => this.#setSdkPermissionProviderFn?.(provider),
 			sdkBindings: () => [
 				...(this.#cycleModelFn ? ["cycleModel"] : []),
+				...(this.#setModelProfileFn ? ["setModelProfile"] : []),
 				...(this.#cycleThinkingLevelFn ? ["cycleThinkingLevel"] : []),
 				...(this.#setQueueModeFn ? ["setQueueMode"] : []),
 				...(this.#getSkillStateFn ? ["getSkillState"] : []),

package/src/extensibility/extensions/types.ts

@@ -290,6 +290,18 @@ export interface ExtensionTranscriptEntry {
 	textSummary: string;
 	ts: string;
 	body?: string;
+	/**
+	 * Durable, image-free message blocks used by rich transcript consumers such
+	 * as ACP replay. Binary image payloads intentionally remain unavailable.
+	 */
+	content?: Array<
+		| { type: "text"; text: string }
+		| { type: "thinking"; thinking: string }
+		| { type: "toolCall"; id: string; name: string; arguments: unknown }
+	>;
+	toolCallId?: string;
+	toolName?: string;
+	isError?: boolean;
 }
 
 export interface ContextUsage {
@@ -361,6 +373,7 @@ export interface ExtensionContext {
 	resolveTool(name: string): Pick<Tool, "safeSummary" | "safeSummaryFields"> | undefined;
 	/** Session control seams used by the SDK host. */
 	cycleModel(): Promise<{ model: Model; thinkingLevel: ThinkingLevel | undefined } | undefined>;
+	setModelProfile?(name: string): Promise<boolean>;
 	cycleThinkingLevel(): ThinkingLevel | undefined;
 	setQueueMode(kind: "steering" | "follow_up" | "interrupt", mode: unknown): boolean;
 	getSkillState(): unknown;
@@ -379,7 +392,15 @@ export interface ExtensionContext {
 
 	getJobs(): unknown;
 	/** Typed skill and mode controls exposed to the SDK host. */
-	invokeSkill?(name: string, args?: string): Promise<unknown>;
+	invokeSkill?(
+		name: string,
+		args?: string,
+		options?: {
+			onPreflightAccepted?: () => void;
+			onPreflightAcceptCommit?: () => void | Promise<void>;
+			onSkillPrepared?: (meta: { name: string; path: string; lineCount?: number; cleanedArgs?: string }) => void;
+		},
+	): Promise<unknown>;
 	setPlanMode?(on: boolean): unknown;
 	operateGoal?(op: "create" | "get" | "resume" | "pause" | "complete" | "drop", objective?: string): Promise<unknown>;
 
@@ -1122,7 +1143,11 @@ 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"; onPreflightAccepted?: () => void },
+		options?: {
+			deliverAs?: "steer" | "followUp";
+			onPreflightAccepted?: () => void;
+			onPreflightAcceptCommit?: () => void | Promise<void>;
+		},
 	): Promise<void>;
 
 	/** Append a custom entry to the session for state persistence (not sent to LLM). */
@@ -1331,7 +1356,11 @@ export type SendMessageHandler = <T = unknown>(
 
 export type SendUserMessageHandler = (
 	content: string | (TextContent | ImageContent)[],
-	options?: { deliverAs?: "steer" | "followUp"; onPreflightAccepted?: () => void },
+	options?: {
+		deliverAs?: "steer" | "followUp";
+		onPreflightAccepted?: () => void;
+		onPreflightAcceptCommit?: () => void | Promise<void>;
+	},
 ) => void | Promise<void>;
 
 export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
@@ -1429,6 +1458,7 @@ export interface ExtensionContextActions {
 	clearContext?: () => Promise<boolean>;
 	/** Session control and query seams exposed to the per-session SDK host. */
 	cycleModel?: () => Promise<{ model: Model; thinkingLevel: ThinkingLevel | undefined } | undefined>;
+	setModelProfile?: (name: string) => Promise<boolean>;
 	cycleThinkingLevel?: () => ThinkingLevel | undefined;
 	setQueueMode?: (kind: "steering" | "follow_up" | "interrupt", mode: unknown) => boolean;
 	getSkillState?: () => unknown;
@@ -1455,7 +1485,15 @@ export interface ExtensionContextActions {
 			| undefined,
 	) => void;
 	sdkControl?: (operation: string, input: Record<string, unknown>) => unknown | Promise<unknown>;
-	invokeSkill?: (name: string, args?: string) => Promise<unknown>;
+	invokeSkill?: (
+		name: string,
+		args?: string,
+		options?: {
+			onPreflightAccepted?: () => void;
+			onPreflightAcceptCommit?: () => void | Promise<void>;
+			onSkillPrepared?: (meta: { name: string; path: string; lineCount?: number; cleanedArgs?: string }) => void;
+		},
+	) => Promise<unknown>;
 	setPlanMode?: (on: boolean) => unknown;
 	operateGoal?: (
 		op: "create" | "get" | "resume" | "pause" | "complete" | "drop",