@namzu/sdk 57.1.0 → 58.1.0

package/src/tools/builtins/view-image.ts

@@ -3,14 +3,14 @@ import { open } from 'node:fs/promises'
 import { inflateSync } from 'node:zlib'
 import { z } from 'zod'
 import { admitMcpImageBatch } from '../../connector/mcp/image-admission.js'
-import type { ToolContext, ToolDefinition } from '../../types/tool/index.js'
+import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { STANDARD_SCREENSHOT_LIMITS, fitPng, screenshotTargetSize } from './computer-use-image.js'
 
 // 16 MiB becomes less than the runtime's 24 MiB encoded rich-content budget.
 // Admission is per artifact; the runtime still budgets accumulated images.
-const MAX_BYTES = 16 * 1024 * 1024
+export const MAX_BYTES = 16 * 1024 * 1024
 const READ_CHUNK_BYTES = 1024 * 1024
 const MAX_EDGE = 16_384
 const MAX_PIXELS = 16_000_000
@@ -55,7 +55,7 @@ async function readBounded(
 	}
 }
 
-async function readArtifact(
+export async function readArtifact(
 	path: string,
 	context: ToolContext,
 ): Promise<{ path: string; bytes: Buffer; sandboxed: boolean }> {
@@ -168,7 +168,7 @@ function webpDimensions(bytes: Buffer): Pick<Raster, 'width' | 'height'> {
 	return dimensions ?? malformed()
 }
 
-function describeRaster(bytes: Buffer): Raster {
+export function describeRaster(bytes: Buffer): Raster {
 	let raster: Raster
 	if (bytes.subarray(0, 8).equals(PNG_SIGNATURE)) {
 		if (bytes.length < 33) malformed()
@@ -313,6 +313,75 @@ async function validatedPng(bytes: Buffer, raster: Raster): Promise<Buffer> {
 	return canonical
 }
 
+/**
+ * Validate and fit the bytes of a saved image and shape them as a tool result
+ * carrying the pixels. `view_image` and an image `read` share this, so both
+ * give the model the same checked picture and the same source dimensions.
+ */
+export async function inspectImageBytes(
+	artifact: { readonly path: string; readonly bytes: Buffer; readonly sandboxed: boolean },
+	signal: AbortSignal,
+): Promise<ToolResult> {
+	const source = describeRaster(artifact.bytes)
+	if (
+		!admitMcpImageBatch([
+			{
+				type: 'image',
+				mimeType: source.mediaType,
+				data: artifact.bytes.toString('base64'),
+			},
+		])
+	)
+		malformed()
+	signal.throwIfAborted()
+	let image = {
+		data: artifact.bytes,
+		width: source.width,
+		height: source.height,
+	}
+	if (source.mediaType === 'image/png') {
+		const png = await validatedPng(artifact.bytes, source)
+		image = await fitPng(png, STANDARD_SCREENSHOT_LIMITS)
+	} else {
+		const target = screenshotTargetSize(source.width, source.height)
+		if (target.width !== source.width || target.height !== source.height)
+			throw new Error(
+				`This ${source.mediaType} image needs resizing. JPEG/WebP decoding and resizing are unavailable here; export a PNG (or a smaller JPEG/WebP) and inspect that file.`,
+			)
+	}
+	signal.throwIfAborted()
+	const validation = source.mediaType === 'image/png' ? 'decoded' : 'container'
+	const output = `Image artifact: ${artifact.path} (${source.width}x${source.height}, ${source.mediaType}); shown at ${image.width}x${image.height}.`
+	return {
+		success: true,
+		output,
+		content: [
+			{
+				type: 'text',
+				text: `${output}\n${validation === 'container' ? 'The complete container and dimensions were validated; compressed JPEG/WebP pixels were not decoded by this tool. ' : ''}Inspect these pixels for visual evidence. This saved artifact is not a current computer_use screenshot; capture the application before GUI input.`,
+			},
+			{
+				type: 'image',
+				mediaType: source.mediaType,
+				data: image.data.toString('base64'),
+			},
+		],
+		data: {
+			path: artifact.path,
+			sandboxed: artifact.sandboxed,
+			artifact: true,
+			mediaType: source.mediaType,
+			sourceWidth: source.width,
+			sourceHeight: source.height,
+			width: image.width,
+			height: image.height,
+			sourceBytes: artifact.bytes.length,
+			sha256: createHash('sha256').update(artifact.bytes).digest('hex'),
+			validation,
+		},
+	}
+}
+
 /**
  * Inspect an artifact without granting screen-coordinate authority. An image
  * file can be a reference, render or export; it is never a computer_use frame.
@@ -343,64 +412,7 @@ export function createViewImageTool(
 				return { success: false, output: message, error: message }
 			}
 			const artifact = await readArtifact(input.path, context)
-			const source = describeRaster(artifact.bytes)
-			if (
-				!admitMcpImageBatch([
-					{
-						type: 'image',
-						mimeType: source.mediaType,
-						data: artifact.bytes.toString('base64'),
-					},
-				])
-			)
-				malformed()
-			context.abortSignal.throwIfAborted()
-			let image = {
-				data: artifact.bytes,
-				width: source.width,
-				height: source.height,
-			}
-			if (source.mediaType === 'image/png') {
-				const png = await validatedPng(artifact.bytes, source)
-				image = await fitPng(png, STANDARD_SCREENSHOT_LIMITS)
-			} else {
-				const target = screenshotTargetSize(source.width, source.height)
-				if (target.width !== source.width || target.height !== source.height)
-					throw new Error(
-						`This ${source.mediaType} image needs resizing. JPEG/WebP decoding and resizing are unavailable here; export a PNG (or a smaller JPEG/WebP) and inspect that file.`,
-					)
-			}
-			context.abortSignal.throwIfAborted()
-			const validation = source.mediaType === 'image/png' ? 'decoded' : 'container'
-			const output = `Image artifact: ${artifact.path} (${source.width}x${source.height}, ${source.mediaType}); shown at ${image.width}x${image.height}.`
-			return {
-				success: true,
-				output,
-				content: [
-					{
-						type: 'text',
-						text: `${output}\n${validation === 'container' ? 'The complete container and dimensions were validated; compressed JPEG/WebP pixels were not decoded by this tool. ' : ''}Inspect these pixels for visual evidence. This saved artifact is not a current computer_use screenshot; capture the application before GUI input.`,
-					},
-					{
-						type: 'image',
-						mediaType: source.mediaType,
-						data: image.data.toString('base64'),
-					},
-				],
-				data: {
-					path: artifact.path,
-					sandboxed: artifact.sandboxed,
-					artifact: true,
-					mediaType: source.mediaType,
-					sourceWidth: source.width,
-					sourceHeight: source.height,
-					width: image.width,
-					height: image.height,
-					sourceBytes: artifact.bytes.length,
-					sha256: createHash('sha256').update(artifact.bytes).digest('hex'),
-					validation,
-				},
-			}
+			return inspectImageBytes(artifact, context.abortSignal)
 		},
 	})
 }

package/src/tools/file-read-tracker.ts

@@ -1,6 +1,10 @@
 import type { FileReadTracker, ReadWindowEntry } from '../types/tool/index.js'
 import { fingerprintContent } from './builtins/content-fingerprint.js'
 
+/** A body larger than this is not kept; the file's change is still seen by fingerprint. */
+const MAX_BODY_CHARS = 512 * 1024
+const MAX_BODIES = 128
+
 /** Host-owned observation ledger. Share only across turns of the same conversation and filesystem. */
 export function createFileReadTracker(): FileReadTracker {
 	const paths = new Set<string>()
@@ -27,6 +31,21 @@ export function createFileReadTracker(): FileReadTracker {
 	// `editChain` or `readWitness` answers; it says only that what this ledger
 	// holds for the path is known to be behind the disk.
 	const drifted = new Set<string>()
+	// The body of each file whose last observation was the whole file, newest
+	// last, so a host can show what changed under it. Bounded: a file larger
+	// than the cap keeps no body (its change is still detectable by
+	// fingerprint), and the oldest bodies go first.
+	const bodies = new Map<string, string>()
+	function keepBody(key: string, content: string | undefined): void {
+		bodies.delete(key)
+		if (content === undefined || content.length > MAX_BODY_CHARS) return
+		bodies.set(key, content)
+		while (bodies.size > MAX_BODIES) {
+			const oldest = bodies.keys().next().value
+			if (oldest === undefined) break
+			bodies.delete(oldest)
+		}
+	}
 	// One observation, whatever witness the caller goes on to record against it.
 	// A shared function rather than `this.recordRead`, so a destructured method
 	// keeps working.
@@ -41,6 +60,9 @@ export function createFileReadTracker(): FileReadTracker {
 		}
 		if (next !== undefined) fingerprints.set(key, next)
 		else fingerprints.delete(key)
+		// A write supplies the whole body; any other observation without a
+		// witness may be a window of the file, which proves nothing about the rest.
+		keepBody(key, fullWriteCallId ? content : undefined)
 		if (next !== undefined && fullWriteCallId) {
 			writes.set(key, fullWriteCallId)
 			// A full body arrived whole in one call, so the chain is empty
@@ -76,12 +98,19 @@ export function createFileReadTracker(): FileReadTracker {
 		recordRead: observe,
 		recordFullRead(key, content, callId, renderedFingerprint) {
 			observe(key, content)
+			keepBody(key, content)
 			// A surviving write witness outranks this one: it names a body the
 			// model composed itself, and the chain machinery can replay onto it.
 			// This is the same observation either way — only the witness differs.
 			if (!writes.has(key)) reads.set(key, { callId, renderedFingerprint })
 		},
 		readWitness: (key) => reads.get(key),
+		fullBody: (key) => bodies.get(key),
+		fullBodyPaths: () => [...bodies.keys()],
+		recordFullBody(key, content) {
+			observe(key, content)
+			keepBody(key, content)
+		},
 		recordEdit(key, content, callId) {
 			// Both conditions are about the PRE-image, not this edit. A chain
 			// replays only if the content this edit ran against is itself
@@ -97,6 +126,7 @@ export function createFileReadTracker(): FileReadTracker {
 			// no chain can be rooted at a rendering to carry it forward.
 			reads.delete(key)
 			fingerprints.set(key, fingerprintContent(content))
+			keepBody(key, content)
 			if (!chained) {
 				writes.delete(key)
 				chains.delete(key)

package/src/toolsets/manager.ts

@@ -547,7 +547,7 @@ export class ToolManager {
 
 		const parts: string[] = []
 		const contractNote = `<tool_runtime_contract>
-Executable tool names, descriptions, and JSON input schemas are attached through the runtime tools parameter. Treat that runtime schema as authoritative; this prompt section is a discoverability summary only.
+Executable tool names, descriptions, and JSON input schemas are attached through the runtime tools parameter. Treat that runtime schema as authoritative. This catalogue is a snapshot for discovery, not live availability status: a tool listed under deferred_tools may already be loaded through history. If its schema is visible in the current runtime tools parameter, call it directly without searching again.
 </tool_runtime_contract>`
 
 		if (active.length > 0) {
@@ -571,8 +571,8 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 				this.has('search_tools') &&
 				this.availability('search_tools') === 'active' &&
 				(!names || names.includes('search_tools'))
-					? 'Use search_tools to load these before use:'
-					: 'Deferred tools are discoverable but not executable until the runtime activates them:'
+					? "Only when a needed deferred tool's schema is absent from the current runtime tools parameter, use search_tools with its exact name to load it:"
+					: 'For a needed deferred tool whose schema is absent, wait for runtime activation before calling it:'
 			parts.push(`<deferred_tools>\n${deferredIntro}\n${entries}\n</deferred_tools>`)
 		}
 

package/src/types/agent/query.ts

@@ -18,6 +18,8 @@ import type { WorkingMemoryProvider } from './working-memory.js'
 
 export interface QueryAgentConfig extends BaseAgentConfig {
 	systemPrompt?: string
+	/** Host lifecycle hooks; forwarded unchanged to the child query. */
+	pluginManager?: QueryParams['pluginManager']
 	/** Provider-hosted search for this turn; the selected driver must support it. */
 	webSearch?: { mode: 'live' | 'cached' }
 

package/src/types/agent/task.ts

@@ -28,8 +28,12 @@ export type ChildWorkspaceRequest =
 			readonly baseRef?: string
 			/** Relative directory within the checkout where this child starts. */
 			readonly subdirectory?: string
-			/** The existing SDK behavior is `dispose`; CLI delegates select `retain`. */
-			readonly retention?: 'dispose' | 'retain'
+			/**
+			 * The existing SDK behavior is `dispose`; `retain` always keeps the
+			 * checkout; `retain-changed` removes it when the child ended with no
+			 * uncommitted changes and no new commits, and keeps it otherwise.
+			 */
+			readonly retention?: 'dispose' | 'retain' | 'retain-changed'
 	  }
 
 export function isTerminalAgentTaskState(state: AgentTaskState): boolean {

package/src/types/connector/mcp.ts

@@ -410,6 +410,12 @@ export interface MCPPromptMessage {
 export interface MCPClientCapabilities {
 	roots?: { listChanged?: boolean }
 	sampling?: Record<string, never>
+	/**
+	 * Declared on a legacy-era `initialize` when the client was built with
+	 * {@link MCPClientConfig.onElicitation}; an empty object means form mode
+	 * only. The client sets it, a caller passing it by hand gets no handler.
+	 */
+	elicitation?: Record<string, never>
 	experimental?: Record<string, unknown>
 }
 
@@ -451,6 +457,34 @@ export interface MCPInitializeResult {
 	instructions?: string
 }
 
+/**
+ * A server's request for structured input from the person, form mode.
+ *
+ * `requestedSchema` is the server's flat object schema, kept as received:
+ * the host decides which property shapes it can show.
+ */
+export interface MCPElicitationRequest {
+	readonly serverName: string
+	readonly message: string
+	readonly requestedSchema: {
+		readonly type?: 'object'
+		readonly properties?: Readonly<Record<string, unknown>>
+		readonly required?: readonly string[]
+	}
+}
+
+/**
+ * What the person did: `accept` carries the form values, `decline` is an
+ * explicit no, `cancel` is a dismissal (closed without choosing).
+ */
+export type MCPElicitationResult =
+	| {
+			readonly action: 'accept'
+			readonly content: Readonly<Record<string, string | number | boolean | readonly string[]>>
+	  }
+	| { readonly action: 'decline' }
+	| { readonly action: 'cancel' }
+
 export type MCPConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error'
 
 export interface MCPClientConfig {
@@ -466,6 +500,20 @@ export interface MCPClientConfig {
 	transportFactory?: () => MCPTransport
 	capabilities?: MCPClientCapabilities
 	clientInfo?: { name: string; version: string }
+	/**
+	 * Answer a server's `elicitation/create` (form mode) by asking the person.
+	 *
+	 * Setting it makes the client declare the `elicitation` capability on a
+	 * legacy-era handshake. Left out, nothing is declared and a server's
+	 * elicitation request is refused as an unknown method, exactly as before.
+	 * `signal` fires when the server withdraws the request or the connection
+	 * ends; a handler that throws answers `cancel`. URL-mode requests are
+	 * never passed here: they are refused as invalid params.
+	 */
+	onElicitation?: (
+		request: MCPElicitationRequest,
+		context: { readonly signal: AbortSignal },
+	) => Promise<MCPElicitationResult>
 	/**
 	 * Deadline for a single JSON-RPC round trip. Defaults to
 	 * `DEFAULT_MCP_REQUEST_TIMEOUT_MS`.

package/src/types/hitl/index.ts

@@ -249,7 +249,7 @@ export interface ToolCallSummary {
 		explicitReview?: true
 		/**
 		 * A rule written to ask a person (a `review` rule), or a hook that asked
-		 * for one, requested this review. Unlike {@link explicitReview} it is not
+		 * for one, requested this review. Like {@link explicitReview}, it is not
 		 * set when an `allow` rule was demoted to review because the call reaches
 		 * past its boundary. `bypass` and `classify` keep this question for a
 		 * person; they answer the demoted kind themselves.

package/src/types/plugin/index.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod'
 import {
+	MAX_AGENT_DIRS_PER_PLUGIN,
+	MAX_COMMAND_DIRS_PER_PLUGIN,
 	MAX_CONNECTORS_PER_PLUGIN,
 	MAX_HOOKS_PER_PLUGIN,
 	MAX_MCP_SERVERS_PER_PLUGIN,
@@ -100,10 +102,27 @@ export type PluginHookEvent =
 	/** A compaction pass is about to run / has run. Carries `compaction`. */
 	| 'pre_compact'
 	| 'post_compact'
-	/** A child session's turn ended. Fired after its own `turn_end`; carries `parentSessionId` and `parentTurnId`. */
+	/**
+	 * A child session is starting, before its first prompt. Carries `parentSessionId`,
+	 * `parentTurnId` and `agentType`. A hook may `annotate` to add context to the
+	 * child's turn.
+	 */
+	| 'subagent_start'
+	/** A child session's turn ended. Fired after its own `turn_end`; carries `parentSessionId`, `parentTurnId` and `agentType`. */
 	| 'subagent_stop'
+	/**
+	 * A child session's turn is starting. Fired right after its own
+	 * `turn_start`; carries `parentSessionId` and `parentTurnId`. Observational.
+	 */
+	| 'subagent_start'
 	| 'turn_start'
 	| 'turn_end'
+	/**
+	 * A turn ended because the model call or the turn itself failed, not because
+	 * the model finished. Carries `error` (the message). Observational: the turn
+	 * has already failed.
+	 */
+	| 'turn_failure'
 	| 'turn_interrupt'
 	| 'pre_tool_use'
 	| 'post_tool_use'
@@ -113,6 +132,19 @@ export type PluginHookEvent =
 	 * and `toolResult`.
 	 */
 	| 'post_tool_use_failure'
+	/**
+	 * Every tool call of one model step has settled, before the next model
+	 * request. Fired once per step; carries `toolCalls`. `post_tool_use` fires
+	 * per call and calls may run side by side, so this is the place to look at
+	 * the step as a whole. `continue` may carry `halt`.
+	 */
+	| 'post_tool_batch'
+	/**
+	 * A tool call was refused without a person saying No: by a rule, the
+	 * policy of the current mode, a classifier, or a hook. Carries `toolName`,
+	 * `toolInput` and `reason`. Observational.
+	 */
+	| 'permission_denied'
 	/**
 	 * A person is about to be asked whether a tool call may run. Carries
 	 * `toolName` and `toolInput`. A hook may answer before the question is
@@ -151,13 +183,17 @@ export function assertPluginHookEvent(event: PluginHookEvent): void {
 		case 'session_end':
 		case 'pre_compact':
 		case 'post_compact':
+		case 'subagent_start':
 		case 'subagent_stop':
 		case 'turn_start':
 		case 'turn_end':
+		case 'turn_failure':
 		case 'turn_interrupt':
 		case 'pre_tool_use':
 		case 'post_tool_use':
 		case 'post_tool_use_failure':
+		case 'post_tool_batch':
+		case 'permission_denied':
 		case 'permission_request':
 		case 'notification':
 		case 'pre_llm_call':
@@ -217,6 +253,16 @@ export interface PluginCompactionInfo {
 	readonly contextWindowTokens: number
 }
 
+/** One call in a `post_tool_batch` hook's context. */
+export interface PluginToolBatchCall {
+	readonly toolCallId: string
+	readonly toolName: string
+	readonly toolInput: unknown
+	/** The text the model was given for the call, a refusal or an error included. */
+	readonly output: string
+	readonly isError: boolean
+}
+
 /** What a `notification` hook is shown. */
 export interface PluginNotificationInfo {
 	/**
@@ -234,10 +280,12 @@ export interface PluginHookContext {
 	readonly event: PluginHookEvent
 	/** The host's session. Always present. */
 	readonly sessionId: SessionId
-	/** The session that delegated, on `subagent_stop`. */
+	/** The session that delegated, on `subagent_start` and `subagent_stop`. */
 	readonly parentSessionId?: SessionId
-	/** The turn whose tool call spawned the child, on `subagent_stop`. */
+	/** The turn whose tool call spawned the child, on `subagent_start` and `subagent_stop`. */
 	readonly parentTurnId?: TurnId
+	/** The name of the agent the child runs, on `subagent_start` and `subagent_stop`. */
+	readonly agentType?: string
 	/** The operator's prompt, on `user_prompt_submit`. */
 	readonly prompt?: string
 	/** The pass, on `pre_compact` and `post_compact`. */
@@ -245,6 +293,12 @@ export interface PluginHookContext {
 	readonly toolName?: string
 	readonly toolInput?: unknown
 	readonly toolResult?: ToolResult
+	/** The calls of one model step with their outcomes, on `post_tool_batch`. */
+	readonly toolCalls?: readonly PluginToolBatchCall[]
+	/** Why the call was refused, on `permission_denied`. */
+	readonly reason?: string
+	/** The failure's message, on `turn_failure`. */
+	readonly error?: string
 	/** What the host is telling the operator, on `notification`. */
 	readonly notification?: PluginNotificationInfo
 	/**
@@ -406,19 +460,27 @@ export function assertPluginHookResult(result: PluginHookResult): asserts result
 /** Actions the query can interpret for a particular hook event. */
 export type PluginHookResultFor<E extends PluginHookEvent> = E extends 'user_prompt_submit'
 	? Extract<PluginHookResult, { action: 'continue' | 'annotate' | 'skip' | 'error' }>
-	: E extends 'pre_tool_use'
-		? Extract<PluginHookResult, { action: 'continue' | 'skip' | 'modify' | 'error' }>
-		: E extends 'post_tool_use'
-			? Extract<PluginHookResult, { action: 'continue' | 'replace' | 'retry' | 'error' }>
-			: E extends 'post_tool_use_failure'
-				? Extract<PluginHookResult, { action: 'continue' | 'error' }>
-				: E extends 'permission_request'
-					? Extract<PluginHookResult, { action: 'continue' | 'skip' }>
-					: E extends 'turn_end' | 'subagent_stop' | 'pre_compact'
-						? Extract<PluginHookResult, { action: 'continue' | 'skip' | 'error' }>
-						: E extends 'turn_interrupt' | 'session_start' | 'session_end' | 'notification'
-							? Extract<PluginHookResult, { action: 'continue' }>
-							: Extract<PluginHookResult, { action: 'continue' | 'error' }>
+	: E extends 'subagent_start'
+		? Extract<PluginHookResult, { action: 'continue' | 'annotate' | 'error' }>
+		: E extends 'pre_tool_use'
+			? Extract<PluginHookResult, { action: 'continue' | 'skip' | 'modify' | 'error' }>
+			: E extends 'post_tool_use'
+				? Extract<PluginHookResult, { action: 'continue' | 'replace' | 'retry' | 'error' }>
+				: E extends 'post_tool_use_failure'
+					? Extract<PluginHookResult, { action: 'continue' | 'error' }>
+					: E extends 'permission_request'
+						? Extract<PluginHookResult, { action: 'continue' | 'skip' }>
+						: E extends 'turn_end' | 'subagent_stop' | 'pre_compact'
+							? Extract<PluginHookResult, { action: 'continue' | 'skip' | 'error' }>
+							: E extends
+										| 'turn_interrupt'
+										| 'session_start'
+										| 'session_end'
+										| 'notification'
+										| 'turn_failure'
+										| 'permission_denied'
+								? Extract<PluginHookResult, { action: 'continue' }>
+								: Extract<PluginHookResult, { action: 'continue' | 'error' }>
 
 /** The event and its handler verdict stay correlated, including in hook arrays. */
 export type PluginHookDefinition<E extends PluginHookEvent = PluginHookEvent> =
@@ -475,6 +537,18 @@ export interface PluginManifest {
 	readonly mcpServers?: readonly PluginMCPServerConfig[]
 	readonly connectors?: readonly string[]
 	readonly personas?: readonly string[]
+	/**
+	 * Folders of markdown prompt files, relative to the plugin folder. Each
+	 * file is a slash command named `<plugin>__<file name>`. The runtime does
+	 * not read them: the host that owns slash commands does.
+	 */
+	readonly commands?: readonly string[]
+	/**
+	 * Folders of markdown agent files, relative to the plugin folder. Each
+	 * file is an agent type named `<plugin>__<name>`. Read by the host that
+	 * owns delegation, not by the runtime.
+	 */
+	readonly agents?: readonly string[]
 }
 
 export const PluginMCPServerConfigSchema = z
@@ -487,6 +561,16 @@ export const PluginMCPServerConfigSchema = z
 	})
 	.strict()
 
+/** A folder inside the plugin: relative, no `..` step, no drive or root. */
+const PluginRelativeDirSchema = z
+	.string()
+	.min(1)
+	.refine(
+		(value) =>
+			!/^([a-zA-Z]:|[\\/])/.test(value) && !value.split(/[\\/]/).some((part) => part === '..'),
+		'must be a folder inside the plugin, with no ".." and no absolute path',
+	)
+
 export const PluginManifestSchema = z.object({
 	name: z
 		.string()
@@ -503,6 +587,8 @@ export const PluginManifestSchema = z.object({
 	mcpServers: z.array(PluginMCPServerConfigSchema).max(MAX_MCP_SERVERS_PER_PLUGIN).optional(),
 	connectors: z.array(z.string()).max(MAX_CONNECTORS_PER_PLUGIN).optional(),
 	personas: z.array(z.string()).max(MAX_PERSONAS_PER_PLUGIN).optional(),
+	commands: z.array(PluginRelativeDirSchema).max(MAX_COMMAND_DIRS_PER_PLUGIN).optional(),
+	agents: z.array(PluginRelativeDirSchema).max(MAX_AGENT_DIRS_PER_PLUGIN).optional(),
 })
 
 // ---------------------------------------------------------------------------

package/src/types/session/sub-session.ts

@@ -100,8 +100,12 @@ export interface SubSession {
 	failureMode: FailureMode
 	completionMode: CompletionMode
 	workspaceId: WorkspaceId | null
-	/** Keep this delegated workspace when the child ends or its session is archived. */
-	workspaceRetention?: 'retain'
+	/**
+	 * Keep this delegated workspace when the child ends or its session is
+	 * archived. `retain-changed` keeps it only if the child changed something;
+	 * a workspace that is still there is therefore one worth keeping.
+	 */
+	workspaceRetention?: 'retain' | 'retain-changed'
 	/**
 	 * For interventions, the immutable artifact being addressed. Chains form
 	 * a strict acyclic DAG — see session-hierarchy.md §4.5.

package/src/types/skills/index.ts

@@ -1,3 +1,5 @@
+import type { ReasoningEffort } from '../provider/chat.js'
+
 /**
  * Who may reach for a skill.
  *
@@ -37,6 +39,52 @@ export interface SkillMetadata {
 	invocation?: SkillInvocation
 
 	metadata?: Record<string, string>
+
+	/**
+	 * When the model should reach for the skill, in the author's words.
+	 * Shown to the model next to the description (`when_to_use`); see
+	 * {@link skillModelDescription}.
+	 */
+	whenToUse?: string
+
+	/**
+	 * Where the skill runs. `fork` hands its instructions to a delegated agent
+	 * and returns that agent's report; absent or `inline` loads them into the
+	 * current conversation.
+	 */
+	context?: 'inline' | 'fork'
+
+	/** The delegated agent type a `fork` skill runs as (`agent`). */
+	agent?: string
+
+	/**
+	 * The model a `fork` skill's delegated agent runs on (`model`). An inline
+	 * skill runs on the turn's own model; this does not switch it.
+	 */
+	model?: string
+
+	/**
+	 * The reasoning effort requested for a `fork` skill's delegated agent
+	 * (`effort`), even without `model`. The host validates the combination;
+	 * this does not switch the current turn's effort for an inline skill.
+	 */
+	effort?: ReasoningEffort
+
+	/** Whether a `fork` skill's agent runs in the background (`background`). */
+	background?: boolean
+}
+
+/**
+ * What the model reads as a skill's description: the description, then the
+ * author's `when_to_use` guidance when there is one.
+ */
+export function skillModelDescription(metadata: {
+	description: string
+	whenToUse?: string
+}): string {
+	const description = metadata.description.trim()
+	const when = metadata.whenToUse?.trim()
+	return when ? `${description} - ${when}` : description
 }
 
 /** What a skill that says nothing means. */