@namzu/sdk 57.0.0 → 58.0.0

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. */

package/src/types/tool/index.ts

@@ -93,6 +93,12 @@ export interface SkillRegistryRef {
 						 * silent `both` — the fail-open answer.
 						 */
 						invocation?: 'model' | 'operator' | 'both'
+						/** `fork` hands the skill to a delegated agent; see `SkillMetadata.context`. */
+						context?: 'inline' | 'fork'
+						agent?: string
+						model?: string
+						effort?: import('../provider/chat.js').ReasoningEffort
+						background?: boolean
 					}
 					body?: string
 					/** The skill's directory, which `${CLAUDE_SKILL_DIR}` in `allowed-tools` names. */
@@ -324,6 +330,22 @@ export interface FileReadTracker {
 	 * only as a rendering, and nothing may be replayed on top of it.
 	 */
 	recordFullRead?(key: string, content: string, callId: string, renderedFingerprint: string): void
+	/**
+	 * Optional body of a file whose latest observation was the whole file (a
+	 * full read, a full write, or an edit's result), for a host that wants to
+	 * show what changed under it. Absent after a windowed read, for a file too
+	 * large to keep, and once the ledger has dropped the oldest bodies.
+	 */
+	fullBody?(key: string): string | undefined
+	/** Optional: the keys {@link fullBody} holds a body for, oldest first. */
+	fullBodyPaths?(): readonly string[]
+	/**
+	 * Optional: record that the whole file now reads `content`, as an
+	 * observation with no witness (the host has told the model about it, or
+	 * read it itself). Advances the fingerprint and the kept body, so the next
+	 * mutation compares against this body and not the one before it.
+	 */
+	recordFullBody?(key: string, content: string): void
 	/**
 	 * Optional witness of the full read above: the call whose receipt holds the
 	 * body, and the fingerprint of what that call emitted.
@@ -574,6 +596,22 @@ export interface ToolContext {
 	 */
 	receiptVisible?: (callId: string, renderedFingerprint: string) => boolean
 
+	/**
+	 * The conversation this call belongs to, read live: the messages the model
+	 * is shown right now, including the assistant message that issued this
+	 * call, and the system prompt assembled for the current iteration.
+	 *
+	 * Absent when the host cannot say. A tool that needs it (one that starts a
+	 * delegate which continues this conversation) must then refuse rather than
+	 * start the delegate without the context it was asked to inherit. Read
+	 * only: the arrays are the turn's own and a tool must copy before it
+	 * changes anything.
+	 */
+	conversation?: {
+		messages(): readonly import('../message/index.js').Message[]
+		systemPrompt(): string | undefined
+	}
+
 	/**
 	 * Where work that outlives this call is held.
 	 *

package/src/types/workspace/ref.ts

@@ -29,6 +29,8 @@ export interface GitWorktreeBackendMeta {
 	branch: string
 	/** Absolute path to the worktree directory. */
 	worktreePath: string
+	/** The commit the checkout started on; absent on refs made before it was recorded. */
+	baseCommit?: string
 }
 
 /**

package/src/utils/frontmatter.ts

@@ -145,6 +145,18 @@ export interface FrontmatterOptions {
 	 * key is parsed and refused exactly as before.
 	 */
 	readonly readsKey?: (key: string) => boolean
+	/**
+	 * Read keys that are read when they are plain and skipped, rather than
+	 * refused, when they are not: a value in a block scalar, a flow sequence
+	 * or flow mapping, or one written as indented lines under the key.
+	 *
+	 * For a key added to a loader after skills written for other tools already
+	 * used it in a spelling this reader cannot take. Refusing the file over
+	 * such a key would turn a skill that loaded into one that does not, for the
+	 * sake of a field that only adds behaviour. The key then reads as absent,
+	 * which is what it meant to everything before it was read.
+	 */
+	readonly tolerates?: (key: string) => boolean
 }
 
 export interface ParsedFrontmatter {
@@ -282,6 +294,15 @@ export function parseFrontmatter(
 		skipping = false
 		const value = normalizeScalar(line.slice(colonIdx + 1))
 
+		if (
+			options.tolerates?.(key) &&
+			(value === '' || UNSUPPORTED_YAML.some(({ pattern }) => pattern.test(value)))
+		) {
+			currentKey = key
+			skipping = true
+			continue
+		}
+
 		if (listKeys.has(key) && /^\[.*\]$/.test(value)) {
 			currentKey = key
 			const items = value