@namzu/sdk 57.0.0 → 58.0.0

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -16,7 +16,9 @@ import type {
 	ReviewedExecution,
 	ToolCallDeclines,
 	ToolCallDenials,
+	ToolCallOutcome,
 } from '../../executor.js'
+import { applyLifecycleHookResults } from '../../plugin-hooks.js'
 import {
 	awaitProjectInstructionCallback,
 	replaceProjectInstructionSnapshot,
@@ -212,11 +214,81 @@ export async function* runToolReview(
 	/** Set only where a person's No is known, so a policy refusal never lands in it. */
 	let declines: ToolCallDeclines | undefined
 
+	/**
+	 * Tell `permission_denied` hooks about each call refused without a person's
+	 * No: a rule, the mode's policy, a classifier or a hook. Observational, so
+	 * a hook's answer changes nothing; one that throws is logged, not allowed to
+	 * fail the step.
+	 */
+	const announceRefusals = async (denials?: ToolCallDenials): Promise<void> => {
+		if (!ctx.pluginManager || !denials || denials.size === 0) return
+		for (const summary of toolCallSummaries) {
+			const reason = denials.get(summary.id)
+			if (reason === undefined || declines?.has(summary.id)) continue
+			if (ctx.abortController.signal.aborted) return
+			try {
+				await ctx.pluginManager.executeHooks(
+					'permission_denied',
+					{
+						sessionId: ctx.recorder.sessionId,
+						turnId: ctx.recorder.turnId,
+						toolName: summary.name,
+						toolInput: summary.input,
+						reason,
+						signal: ctx.abortController.signal,
+					},
+					ctx.emitEvent,
+				)
+			} catch (error) {
+				if (ctx.abortController.signal.aborted) return
+				ctx.log.warn('A permission_denied hook failed', {
+					'exception.message': error instanceof Error ? error.message : String(error),
+				})
+			}
+		}
+	}
+
+	/**
+	 * Tell `post_tool_batch` hooks that every call of this step has settled.
+	 * Fires once per step, before the next model request. A hook may ask for the
+	 * turn to stop once this step is done; an `error` fails the turn like any
+	 * other lifecycle hook.
+	 */
+	const announceBatch = async (outcomes: readonly ToolCallOutcome[]): Promise<void> => {
+		if (!ctx.pluginManager || ctx.abortController.signal.aborted) return
+		const inputs = new Map(toolCallSummaries.map((summary) => [summary.id, summary.input]))
+		const toolCalls = outcomes.map((outcome) => ({
+			toolCallId: outcome.toolCallId,
+			toolName: outcome.toolName,
+			toolInput: inputs.get(outcome.toolCallId),
+			output: outcome.output,
+			isError: outcome.isError === true,
+		}))
+		if (toolCalls.length === 0) return
+		const results = await ctx.pluginManager.executeHooks(
+			'post_tool_batch',
+			{
+				sessionId: ctx.recorder.sessionId,
+				turnId: ctx.recorder.turnId,
+				toolCalls,
+				signal: ctx.abortController.signal,
+			},
+			ctx.emitEvent,
+		)
+		applyLifecycleHookResults('post_tool_batch', results)
+		for (const result of results) {
+			if (result.action === 'continue' && result.halt) {
+				ctx.toolExecutor.requestHalt?.(result.halt.reason)
+			}
+		}
+	}
+
 	/** Executes the batch, answering every call, and appends the results. */
 	const settleBatch = async (
 		denials?: ToolCallDenials,
 		review?: ReviewedExecution,
 	): Promise<void> => {
+		await announceRefusals(denials)
 		const startedAt = Date.now()
 		const batch = await ctx.toolExecutor.executeBatch(
 			response,
@@ -228,6 +300,7 @@ export async function* runToolReview(
 		)
 		toolMs += Date.now() - startedAt
 		executed = batch.results
+		await announceBatch(batch.results)
 		// Registry receipts are ordered by actual completion, include nested
 		// dispatches, and exclude denials/recovered results. A successful possible
 		// mutation permits another experiment; unrelated reads cannot do so.
@@ -533,9 +606,7 @@ export async function* runToolReview(
 			toolCall.authorization = {
 				decision: gateResult.decision,
 				...(gateResult.reason ? { reason: gateResult.reason } : {}),
-				...(gateResult.decision === 'review' && (gateResult.matchedRule || hookAsked)
-					? { explicitReview: true as const }
-					: {}),
+				...(ruleAsked || hookAsked ? { explicitReview: true as const } : {}),
 				...(ruleAsked || hookAsked ? { askRule: true as const } : {}),
 				...(gateResult.decision === 'allow' && allowRuleScope(gateResult.matchedRule)
 					? { allowScope: allowRuleScope(gateResult.matchedRule) }

package/src/runtime/query/path-escalation.ts

@@ -34,6 +34,8 @@ export interface PathEscalations {
 export interface PathEscalationContext {
 	/** The working directory first, then the added directories. */
 	readonly roots: readonly string[]
+	/** Actual shell start directory; roots remain the original authorization boundary. */
+	readonly cwd?: string
 	/** Whether to report paths outside the roots (`outsideRootAccess: 'review'`, no sandbox). */
 	readonly reviewOutside: boolean
 }
@@ -150,7 +152,7 @@ export async function shellEscalations(
 ): Promise<PathEscalations> {
 	const reading = readShellLine(line, dialect)
 	const access = shellPathAccess(reading)
-	const [cwd, ...added] = context.roots
+	const cwd = context.cwd ?? context.roots[0]
 	const outside = new Set<string>()
 	const protectedPaths = new Set<string>()
 	const home = homedir()
@@ -222,14 +224,18 @@ export async function shellEscalations(
 			}
 		}
 	}
-	const removal =
-		cwd === undefined
+	const removalAt = (directory: string | undefined) =>
+		directory === undefined
 			? undefined
 			: dangerousRemoval(reading, access.changesDirectory, {
-					cwd,
-					additionalDirectories: added,
+					cwd: directory,
+					additionalDirectories: context.roots,
 					home,
 				})
+	// Moving into an added directory must not make removal of the original
+	// working directory cease to be catastrophic. Keep both conservative floors.
+	const removal =
+		removalAt(cwd) ?? (cwd !== context.roots[0] ? removalAt(context.roots[0]) : undefined)
 	return {
 		outsidePaths: [...outside],
 		protectedPaths: [...protectedPaths],

package/src/runtime/query/plugin-hooks.ts

@@ -19,9 +19,9 @@ export function applyLifecycleHookResults(
 			case 'continue':
 				continue
 			case 'annotate':
-				if (event !== 'user_prompt_submit') {
+				if (event !== 'user_prompt_submit' && event !== 'subagent_start') {
 					throw new Error(
-						`Plugin hook ${event} returned 'annotate', which only user_prompt_submit accepts`,
+						`Plugin hook ${event} returned 'annotate', which only user_prompt_submit and subagent_start accept`,
 					)
 				}
 				if (result.text.trim().length > 0) annotations.push(result.text.trim())

package/src/runtime/query/prepare-turn.ts

@@ -89,6 +89,8 @@ export interface PreparedTurn {
 	readonly approvalPolicy: SessionApprovalPolicy
 	readonly eventTranslator: EventTranslator
 	readonly executeUserInterruptHooks: (terminalError: unknown) => Promise<void>
+	/** Tell `turn_failure` hooks the root turn failed; never throws, never fires for a cancellation. */
+	readonly executeTurnFailureHooks: (terminalError: unknown) => Promise<void>
 	/**
 	 * Repair reports this turn owes its log.
 	 *
@@ -823,6 +825,36 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 			}
 		}
 
+		const executeTurnFailureHooks = async (terminalError: unknown): Promise<void> => {
+			// A cancellation is the operator's own act, a child's failure reaches its
+			// parent as a tool result, and the turn is already failed: this is a
+			// notice, so nothing it does may change how the turn settles.
+			if (
+				!params.pluginManager ||
+				params.parentSessionId !== undefined ||
+				ctx.abortController.signal.aborted ||
+				isCallerAbortError(terminalError, ctx.abortController.signal)
+			) {
+				return
+			}
+			try {
+				await params.pluginManager.executeHooks(
+					'turn_failure',
+					{
+						sessionId: ctx.sessionId,
+						turnId: ctx.turnId,
+						error: toErrorMessage(terminalError),
+					},
+					eventTranslator.emitEvent,
+				)
+			} catch (error) {
+				ctx.log.error('Turn failure hooks did not settle cleanly', {
+					[NAMZU.TURN_ID]: ctx.turnId,
+					...errorAttributes(error),
+				})
+			}
+		}
+
 		return {
 			turnConfig,
 			budget,
@@ -836,6 +868,7 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 			approvalPolicy,
 			eventTranslator,
 			executeUserInterruptHooks,
+			executeTurnFailureHooks,
 			pendingHistoryRepairs,
 			initialMessages,
 			historyIds,

package/src/runtime/query/review-policy.ts

@@ -28,6 +28,8 @@ import {
 	readShellLine,
 	shellPathAccess,
 } from '../../authorization/shell-paths.js'
+import { effectiveBashWorkingDirectory } from '../../tools/builtins/bash-cwd.js'
+import { BashTool } from '../../tools/builtins/bash.js'
 import { isTrustedReadOnly } from '../../tools/trusted-read-only.js'
 import type { ToolManager } from '../../toolsets/manager.js'
 import type {
@@ -83,10 +85,11 @@ export type ReviewMode =
 	 *
 	 * Where `auto` approves what remains after the questions a person must
 	 * answer (a path outside the roots, a program nobody can name, a protected
-	 * write), `bypass` also approves those. It still asks, or refuses when
+	 * write), `bypass` approves outside paths and unknown programs but not protected
+	 * writes. It still asks, or refuses when
 	 * nobody can be asked: a `deny` rule (the gate refuses before this is
 	 * reached), an `ask` rule or a hook that asked for a person, a catastrophic
-	 * removal, a tool's own `requiresApproval`, a sandbox escape, and a call
+	 * removal, a protected write, a tool's own `requiresApproval`, a sandbox escape, and a call
 	 * whose safety checks did not finish. The dangerous-pattern floor refuses in
 	 * the gate, unchanged. With nobody to ask, whatever would have been asked is
 	 * refused.
@@ -571,14 +574,15 @@ function isPermissive(mode: ReviewMode): boolean {
 
 /**
  * Whether the call is one of the few no mode may settle in advance: a rule or
- * hook asked for a person, a sandbox escape, a catastrophic removal, a check
- * that did not finish, or a tool that always needs approval. The dangerous
+ * hook asked for a person, a sandbox escape, a protected write, a catastrophic
+ * removal, a check that did not finish, or a tool that always needs approval. The dangerous
  * pattern floor and `deny` rules are not here: the gate refuses those first.
  */
 function isBypassImmune(tc: ToolCallSummary): boolean {
 	return (
 		tc.authorization?.askRule === true ||
 		tc.escalation?.sandboxEscape === true ||
+		(tc.escalation?.protectedPaths?.length ?? 0) > 0 ||
 		tc.escalation?.dangerousRemoval !== undefined ||
 		tc.escalation?.unfinishedCheck !== undefined ||
 		tc.requiresApproval === true
@@ -593,6 +597,9 @@ function immuneRefusal(
 	if (!escapeConfirmed && toolCalls.some((tc) => tc.escalation?.sandboxEscape === true)) {
 		return SANDBOX_ESCAPE_UNATTENDED_REFUSAL
 	}
+	if (toolCalls.some((tc) => (tc.escalation?.protectedPaths?.length ?? 0) > 0)) {
+		return PROTECTED_PATH_UNATTENDED_REFUSAL
+	}
 	if (toolCalls.some((tc) => tc.escalation?.dangerousRemoval !== undefined)) {
 		return DANGEROUS_REMOVAL_UNATTENDED_REFUSAL
 	}
@@ -879,7 +886,10 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 	 * path, a path in a variable, a program nobody can name or a `sed` script
 	 * that can run something is not that.
 	 */
-	const shellFileCommandsInRoots = async (tc: ToolCallSummary): Promise<boolean> => {
+	const shellFileCommandsInRoots = async (
+		tc: ToolCallSummary,
+		sessionId?: string,
+	): Promise<boolean> => {
 		const rootList = rootsNow()
 		if (rootList.length === 0) return false
 		if (
@@ -906,23 +916,39 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 			if (invocation.program === 'sed' && !sedOnlyEdits(invocation.args)) return false
 		}
 		if (shellPathAccess(reading).uses.some((use) => use.unresolved)) return false
-		const found = await shellEscalations(line, dialect, { roots: rootList, reviewOutside: true })
-		return (
-			found.outsidePaths.length === 0 &&
-			found.protectedPaths.length === 0 &&
-			found.dangerousRemoval === undefined
+		const cwd =
+			tool.execute === BashTool.execute && rootList[0] !== undefined
+				? effectiveBashWorkingDirectory(sessionId, rootList[0])
+				: undefined
+		const found = await shellEscalations(line, dialect, {
+			roots: rootList,
+			...(cwd !== undefined ? { cwd } : {}),
+			reviewOutside: true,
+		})
+		// A standalone review request carries no sandbox attribution. Retain the
+		// original-root reading too: missing execution metadata can only ask more,
+		// never approve a call the old reading would have sent to a person.
+		const baseline =
+			cwd !== undefined && cwd !== rootList[0]
+				? await shellEscalations(line, dialect, { roots: rootList, reviewOutside: true })
+				: found
+		return [found, baseline].every(
+			(reading) =>
+				reading.outsidePaths.length === 0 &&
+				reading.protectedPaths.length === 0 &&
+				reading.dangerousRemoval === undefined,
 		)
 	}
 
 	/** What `accept-edits` approves without asking: edits, exempt reads and file commands inside the roots. */
-	const acceptEditsAllows = async (tc: ToolCallSummary): Promise<boolean> =>
+	const acceptEditsAllows = async (tc: ToolCallSummary, sessionId?: string): Promise<boolean> =>
 		!tc.authorization?.explicitReview &&
 		tc.escalation === undefined &&
 		!tc.isDestructive &&
 		tc.requiresApproval !== true &&
 		(ACCEPT_EDITS_TOOLS.has(tc.name) ||
 			exempt(tc.name, tc.input) ||
-			(await shellFileCommandsInRoots(tc)))
+			(await shellFileCommandsInRoots(tc, sessionId)))
 
 	/**
 	 * Whether a rule's `allow` is one the classifier should not defer to: the
@@ -944,7 +970,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 	}
 
 	/** Whether `classify` decides this call without the classifier: it would not be asked, or is plainly safe. */
-	const neverSent = async (tc: ToolCallSummary): Promise<boolean> => {
+	const neverSent = async (tc: ToolCallSummary, sessionId?: string): Promise<boolean> => {
 		if (tc.authorization?.decision === 'allow' && !allowRuleTooWide(tc)) return true
 		// A name on the safe list is safe for what it does in the session; a read of
 		// /etc/shadow is still a read of /etc/shadow, and a person's own ask is
@@ -965,7 +991,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		) {
 			return true
 		}
-		return acceptEditsAllows(tc)
+		return acceptEditsAllows(tc, sessionId)
 	}
 
 	return async (request, context?: ResumeContext): Promise<HITLResumeDecision> => {
@@ -1043,7 +1069,10 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 					request.toolCalls.map((tc) =>
 						// The mode covers a write although the flag is set; the classifier
 						// still judges one, so only this branch lifts the flag.
-						acceptEditsAllows(isFileWrite(tc.name) ? { ...tc, isDestructive: false } : tc),
+						acceptEditsAllows(
+							isFileWrite(tc.name) ? { ...tc, isDestructive: false } : tc,
+							request.sessionId,
+						),
 					),
 				)
 			).every(Boolean)
@@ -1093,7 +1122,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				const transcript = context?.transcript() ?? []
 				for (const tc of live) {
 					// The questions a person must answer are asked of a person, never of a model.
-					if (isBypassImmune(tc) || (await neverSent(tc))) continue
+					if (isBypassImmune(tc) || (await neverSent(tc, request.sessionId))) continue
 					const decision = await classifier.review({
 						call: tc,
 						transcript,

package/src/scheduler/local.ts

@@ -133,7 +133,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 				...(options.phaseDetail ? { phaseDetail: options.phaseDetail } : {}),
 				...(options.phaseOrder !== undefined ? { phaseOrder: options.phaseOrder } : {}),
 				input: {
-					messages: [createUserMessage(options.prompt)],
+					messages: [...(options.inheritedMessages ?? []), createUserMessage(options.prompt)],
 					workingDirectory: options.workingDirectory,
 					taskStore: this.parentInput?.taskStore,
 					runtimeToolOverrides: this.parentInput?.runtimeToolOverrides,

package/src/session/retention/archive.ts

@@ -223,7 +223,7 @@ export class ArchivalManager {
 
 		// 6. Dispose the workspace (idempotent — driver contract tolerates
 		//    already-disposed refs; a missing ref is a no-op).
-		if (workspace && sub.workspaceRetention !== 'retain') {
+		if (workspace && sub.workspaceRetention === undefined) {
 			try {
 				const driver = this.deps.workspaceRegistry.get(workspace.meta.backend)
 				await driver.dispose(workspace)

package/src/session/workspace/driver.ts

@@ -47,6 +47,12 @@ export interface WorkspaceInspection {
 	exists: boolean
 	currentRef: string
 	isDirty: boolean
+	/**
+	 * Whether the workspace moved off the commit it started on. Absent when the
+	 * backend cannot tell; a caller deciding whether to keep it treats absent
+	 * as `true`.
+	 */
+	hasNewCommits?: boolean
 }
 
 /**

package/src/session/workspace/git-worktree.ts

@@ -147,11 +147,19 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 			})
 		}
 
+		// The commit the checkout starts on, so a later look can tell a child that
+		// committed from one that did not. Left out when it cannot be read: a ref
+		// without it is always treated as changed.
+		const baseCommit = await this.exec('git', ['-C', worktreePath, 'rev-parse', 'HEAD'])
+			.then((r) => r.stdout.trim() || undefined)
+			.catch(() => undefined)
+
 		const meta: GitWorktreeBackendMeta = {
 			backend: 'git-worktree',
 			repoRoot,
 			branch,
 			worktreePath,
+			...(baseCommit ? { baseCommit } : {}),
 		}
 
 		this.log.info('git-worktree created', {
@@ -202,6 +210,25 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 				[NAMZU.SESSION_ID]: ref.id,
 				'namzu.session.path': owned.worktreePath,
 			})
+			// A branch still on its starting commit holds nothing, so it goes with
+			// its checkout. Compare and delete under Git's ref lock: a branch that
+			// advanced after the worktree listing must keep its new commits.
+			if (owned.baseCommit !== undefined && registered.head === owned.baseCommit) {
+				await this.exec('git', [
+					'-C',
+					owned.repoRoot,
+					'update-ref',
+					'--no-deref',
+					'-d',
+					`refs/heads/${owned.branch}`,
+					owned.baseCommit,
+				]).catch((cause) =>
+					this.log.warn('git-worktree branch left behind', {
+						'namzu.session.branch': owned.branch,
+						'namzu.session.cause': cause instanceof Error ? cause.message : String(cause),
+					}),
+				)
+			}
 		} catch (cause) {
 			// Two concurrent disposals can both observe the entry before one wins.
 			// Re-read after failure and accept only repository evidence that the
@@ -282,10 +309,13 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 			throw new WorkspaceBackendError({ op: 'inspect:status', kind: this.kind, cause })
 		}
 
+		const baseCommit = owned.baseCommit
 		return {
 			exists: true,
 			currentRef: entry.branch ?? entry.head ?? ref.meta.branch,
 			isDirty: statusStdout.trim().length > 0,
+			// Unknown (no recorded start, or HEAD unreadable) reads as "has commits".
+			hasNewCommits: baseCommit === undefined || entry.head !== baseCommit,
 		}
 	}
 
@@ -329,6 +359,7 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 				repoRoot,
 				branch,
 				worktreePath,
+				...(ref.meta.baseCommit ? { baseCommit: ref.meta.baseCommit } : {}),
 			}
 		} catch (cause) {
 			throw new WorkspaceBackendError({ op: `${op}:ownership`, kind: this.kind, cause })

package/src/skills/index.ts

@@ -1,2 +1,7 @@
-export { SKILL_FRONTMATTER_KEYS, loadSkill, discoverSkills } from './loader.js'
+export {
+	SKILL_FRONTMATTER_KEYS,
+	SKILL_FRONTMATTER_TOLERATED_KEYS,
+	loadSkill,
+	discoverSkills,
+} from './loader.js'
 export { SkillCollisionError, SkillRegistry, resolveSkillChain } from './registry.js'

package/src/skills/loader.ts

@@ -1,5 +1,6 @@
 import { readFile, readdir, stat } from 'node:fs/promises'
 import { basename, join } from 'node:path'
+import type { ReasoningEffort } from '../types/provider/chat.js'
 import type {
 	Skill,
 	SkillDisclosureLevel,
@@ -31,8 +32,28 @@ export const SKILL_FRONTMATTER_KEYS: readonly string[] = Object.freeze([
 	'invocation',
 	'disable-model-invocation',
 	'metadata',
+	'when_to_use',
+	'context',
+	'agent',
+	'model',
+	'effort',
+	'background',
 ])
 
+/**
+ * The keys added after other tools' skills already used them. A value in one
+ * that this reader cannot take (`when_to_use: >-`, `model: [a, b]`) leaves the
+ * key absent instead of refusing the skill.
+ */
+export const SKILL_FRONTMATTER_TOLERATED_KEYS: readonly string[] = [
+	'when_to_use',
+	'context',
+	'agent',
+	'model',
+	'effort',
+	'background',
+]
+
 const READS_SKILL_KEY = (key: string): boolean => SKILL_FRONTMATTER_KEYS.includes(key)
 
 /**
@@ -44,6 +65,7 @@ const READS_SKILL_KEY = (key: string): boolean => SKILL_FRONTMATTER_KEYS.include
 export const SKILL_FRONTMATTER_OPTIONS = {
 	lists: ['allowed-tools'],
 	readsKey: READS_SKILL_KEY,
+	tolerates: (key: string): boolean => SKILL_FRONTMATTER_TOLERATED_KEYS.includes(key),
 } as const
 
 /**
@@ -161,6 +183,27 @@ function toSkillMetadata(parsed: ParsedFrontmatter, dirPath: string): SkillMetad
 		}
 	}
 
+	// The fields that shape how the skill RUNS are read leniently, the other
+	// way round from the access fields above: a value this loader does not
+	// understand (`effort: 5000`, `context: sideways`) leaves the skill at its
+	// plain behaviour rather than refusing a skill written for another agent.
+	const whenToUse = scalarAt(values, 'when_to_use')?.trim()
+	if (whenToUse) skillMetadata.whenToUse = whenToUse
+
+	if (scalarAt(values, 'context') === 'fork') skillMetadata.context = 'fork'
+	const agent = scalarAt(values, 'agent')?.trim()
+	if (agent) skillMetadata.agent = agent
+	const model = scalarAt(values, 'model')?.trim()
+	if (model && model.toLowerCase() !== 'inherit') skillMetadata.model = model
+	const effort = scalarAt(values, 'effort')?.trim().toLowerCase()
+	if (effort && (REASONING_EFFORTS as readonly string[]).includes(effort)) {
+		skillMetadata.effort = effort as ReasoningEffort
+	}
+	const background = scalarAt(values, 'background')
+	if (background === 'true' || background === 'false') {
+		skillMetadata.background = background === 'true'
+	}
+
 	const extra = mappingAt(values, 'metadata')
 	if (extra && Object.keys(extra).length > 0) {
 		skillMetadata.metadata = { ...extra }
@@ -169,6 +212,17 @@ function toSkillMetadata(parsed: ParsedFrontmatter, dirPath: string): SkillMetad
 	return skillMetadata
 }
 
+const REASONING_EFFORTS: readonly ReasoningEffort[] = [
+	'none',
+	'minimal',
+	'low',
+	'medium',
+	'high',
+	'xhigh',
+	'max',
+	'ultra',
+]
+
 const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 
 function validateSkillName(name: string, dirPath: string): void {

package/src/skills/registry.ts

@@ -1,11 +1,12 @@
 import { stat } from 'node:fs/promises'
 import { join } from 'node:path'
 import { RegistryCollisionError } from '../registry/collision.js'
-import type {
-	Skill,
-	SkillChain,
-	SkillDisclosureLevel,
-	SkillLoadResult,
+import {
+	type Skill,
+	type SkillChain,
+	type SkillDisclosureLevel,
+	type SkillLoadResult,
+	skillModelDescription,
 } from '../types/skills/index.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import { type Logger, resolveLogger } from '../utils/logger.js'
@@ -273,7 +274,7 @@ export class SkillRegistry {
 			const skill = loaded.skill
 			entries.push({
 				registeredName,
-				description: skill.metadata.description,
+				description: skillModelDescription(skill.metadata),
 				location: join(skill.dirPath, SKILL_FILENAME),
 				directory: skill.dirPath,
 				...(skill.metadata.allowedTools === undefined