@namzu/sdk 53.2.1 → 54.0.0

package/src/tools/builtins/bash.ts

@@ -23,6 +23,7 @@ import { defineTool } from '../defineTool.js'
 import { scrubInheritedEnv } from '../env-scrub.js'
 import { createHostOutputDecoder } from '../host-output.js'
 import { looksBinary, windowText } from '../text-window.js'
+import { judgeExit } from './exit-semantics.js'
 import { jsonStringEscapes } from './json-string-hint.js'
 
 // Namzu owns its own bash timeout knob — `NAMZU_BASH_TIMEOUT_MS` — and
@@ -669,11 +670,14 @@ const BashToolBase = defineTool({
 				.filter(Boolean)
 				.join('\n\n')
 
+			const judged = result.timedOut ? undefined : judgeExit(input.command, result.exitCode)
+			const answered = judged !== undefined && !judged.isError
 			return {
-				success: !result.timedOut && result.exitCode === 0,
+				success: answered,
 				output: output || '(no output)',
 				data: {
 					exitCode: result.exitCode,
+					...(judged?.note ? { exitNote: judged.note } : {}),
 					sandboxed: true,
 					timedOut: result.timedOut,
 					stdoutTruncated: result.stdoutTruncated ?? false,
@@ -681,12 +685,13 @@ const BashToolBase = defineTool({
 				},
 				error: result.timedOut
 					? `Command timed out after ${input.timeout}ms. Any captured output before the deadline is above.`
-					: result.exitCode !== 0
+					: !answered
 						? `Command exited with code ${result.exitCode}`
 						: undefined,
 				facts: commandFacts({
 					command: input.command,
 					exitCode: result.exitCode,
+					...(judged?.note ? { exitNote: judged.note } : {}),
 					timedOut: result.timedOut,
 					stdout: result.stdout,
 					stderr: result.stderr,
@@ -801,35 +806,44 @@ const BashToolBase = defineTool({
 			// and appending this to every result would make the common case noisy
 			// to buy nothing. A failing one is exactly where "authentication
 			// failed" has to be distinguishable from "the variable was withheld".
+			// A status the command uses to answer (no match, files differ) is a
+			// result, not a failure; the model sees it as an ordinary call.
+			const judged =
+				!timedOut && exitCode !== undefined ? judgeExit(input.command, exitCode) : undefined
+			const answered = judged !== undefined && !judged.isError
 			const output = [
 				formatShellOutput(failure.stdout, failure.stderr),
 				clipped.length > 0
 					? `[${clipped.join(' and ')} ${clipped.length === 1 ? 'was' : 'were'} truncated by the host output cap. The omitted output is unavailable in this result.]`
 					: '',
-				describeWithheldEnv(inherited.dropped),
+				answered ? '' : describeWithheldEnv(inherited.dropped),
 			]
 				.filter(Boolean)
 				.join('\n\n')
 
 			return {
-				success: false,
+				success: answered,
 				output: output || '(no output)',
 				data: {
 					...(exitCode !== undefined ? { exitCode } : {}),
+					...(judged?.note ? { exitNote: judged.note } : {}),
 					...(leaveSandbox ? { sandboxed: false, sandboxEscape: true } : {}),
 					timedOut,
 					stdoutTruncated: failure.stdoutTruncated ?? false,
 					stderrTruncated: failure.stderrTruncated ?? false,
 					...(failure.signal ? { signal: failure.signal } : {}),
 				},
-				error: timedOut
-					? `Command timed out after ${input.timeout}ms. Any output it produced before the deadline is above.`
-					: exitCode !== undefined
-						? `Command exited with code ${exitCode}`
-						: `Command failed: ${failure.message}`,
+				error: answered
+					? undefined
+					: timedOut
+						? `Command timed out after ${input.timeout}ms. Any output it produced before the deadline is above.`
+						: exitCode !== undefined
+							? `Command exited with code ${exitCode}`
+							: `Command failed: ${failure.message}`,
 				facts: commandFacts({
 					command: input.command,
 					...(exitCode !== undefined ? { exitCode } : {}),
+					...(judged?.note ? { exitNote: judged.note } : {}),
 					timedOut,
 					...(failure.signal ? { signal: failure.signal } : {}),
 					stdout: failure.stdout ?? '',
@@ -851,6 +865,7 @@ const BashToolBase = defineTool({
 function commandFacts(input: {
 	command: string
 	exitCode?: number
+	exitNote?: string
 	timedOut?: boolean
 	signal?: string
 	stdout: string
@@ -867,6 +882,7 @@ function commandFacts(input: {
 		kind: 'command',
 		command: input.command,
 		...(input.exitCode !== undefined ? { exitCode: input.exitCode } : {}),
+		...(input.exitNote ? { exitNote: input.exitNote } : {}),
 		...(input.timedOut ? { timedOut: true } : {}),
 		...(input.signal ? { signal: input.signal } : {}),
 		...(input.stdout && !outBinary ? { stdout: windowText(input.stdout, outBytes) } : {}),

package/src/tools/builtins/browser.ts

@@ -280,7 +280,7 @@ function actModelSchema(actions: readonly BrowserActActionName[]) {
 			origin: {
 				type: 'string',
 				description:
-					'REQUIRED. The origin from the latest snapshot header ("Page: <origin> — …"), e.g. https://github.com. The call is refused if the page is no longer there.',
+					'REQUIRED. The origin from the latest snapshot header ("Page: <origin> — …"), e.g. https://example.com. The call is refused if the page is no longer there.',
 			},
 			ref: { type: 'string', description: 'Element ref from the latest snapshot, like e12.' },
 			text: { type: 'string' },

package/src/tools/builtins/computer-use.ts

@@ -109,7 +109,7 @@ export function computerUseUnavailableReason(
 	model?: string,
 ): string | undefined {
 	if (!resolveProviderCapabilities(provider).supportsToolResultImages) {
-		return `The ${provider.id} provider cannot return images in tool results, so the model would never see a screenshot. Use a provider that can (for example Anthropic, Codex or Google) for computer use.`
+		return `The ${provider.id} provider cannot return images in tool results, so the model would never see a screenshot. Use a provider that can return images in tool results for computer use.`
 	}
 	// The driver can carry the image; the model behind it may still not read one.
 	// It would act on a screen it never saw, and the first screenshot would make
@@ -508,7 +508,7 @@ function buildDescription(
 		available.includes('type_text')
 	)
 		lines.push(
-			'To start a Windows program, a shell command (Start-Process notepad, or cmd.exe /c start calc) is surest when you have a shell tool. The Start menu searches by display names in the system language, and ENTER on a name it does not find opens a web search in the browser.',
+			'To start a Windows program, a shell command (Start-Process <program>, or cmd.exe /c start <program>) is surest when you have a shell tool. The Start menu searches by display names in the system language, and ENTER on a name it does not find opens a web search in the browser.',
 		)
 	if (available.includes('list_windows'))
 		lines.push(

package/src/tools/builtins/edit-apply.ts

@@ -130,6 +130,13 @@ function normalizeInsertLine(
 	return { success: true, value }
 }
 
+/** A refused edit, with the kind of refusal when it is one a host can phrase. */
+export type EditApplyFailure = {
+	success: false
+	error: string
+	reason?: 'text_not_found' | 'not_unique'
+}
+
 /**
  * Apply every operation in order, or none of them.
  *
@@ -149,7 +156,7 @@ function normalizeInsertLine(
 export function applyEdit(
 	content: string,
 	operations: readonly NormalizedEditInput[],
-): { success: true; content: string; replacements: number } | { success: false; error: string } {
+): { success: true; content: string; replacements: number } | EditApplyFailure {
 	let current = content
 	let replacements = 0
 
@@ -159,6 +166,7 @@ export function applyEdit(
 			return {
 				success: false,
 				error: framedError(result.error, index, operations.length),
+				...(result.reason ? { reason: result.reason } : {}),
 			}
 		}
 		current = result.content
@@ -171,7 +179,7 @@ export function applyEdit(
 function applyOne(
 	content: string,
 	input: NormalizedEditInput,
-): { success: true; content: string; replacements: number } | { success: false; error: string } {
+): { success: true; content: string; replacements: number } | EditApplyFailure {
 	if (input.operation === 'insert') {
 		return applyLineInsert(content, input)
 	}
@@ -191,6 +199,7 @@ function applyOne(
 		if (resolved === null) {
 			return {
 				success: false,
+				reason: 'text_not_found',
 				error:
 					'old_string/oldStr not found in file. Make sure the string matches exactly, including whitespace and indentation.',
 			}
@@ -225,6 +234,7 @@ function applyOne(
 		const secondLine = content.slice(0, secondIndex).split('\n').length
 		return {
 			success: false,
+			reason: 'not_unique',
 			error: `old_string/oldStr is not unique — found at lines ${lineNumber} and ${secondLine}. Provide more surrounding context to make it unique, or use replace_all: true.`,
 		}
 	}

package/src/tools/builtins/edit.ts

@@ -2,12 +2,18 @@ import { readFile } from 'node:fs/promises'
 
 import { z } from 'zod'
 import type { ToolContext, ToolResult } from '../../types/tool/index.js'
+import type { ToolFacts } from '../../types/tool/presentation.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
 import { clip, describeChange } from './classifier-input.js'
 import { fingerprintContent, staleFileError, unreadFileError } from './content-fingerprint.js'
-import { type NormalizedEditInput, applyEdit, normalizeEditInput } from './edit-apply.js'
+import {
+	type EditApplyFailure,
+	type NormalizedEditInput,
+	applyEdit,
+	normalizeEditInput,
+} from './edit-apply.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { jsonStringEscapes } from './json-string-hint.js'
 import { lineDiff } from './line-diff.js'
@@ -334,7 +340,7 @@ function recordDrift(context: ToolContext, key: string): void {
 }
 
 type EditAdmission =
-	| { success: false; output: ''; error: string }
+	| { success: false; output: ''; error: string; facts: ToolFacts }
 	| { success: true; result: ReturnType<typeof applyEdit> }
 
 /**
@@ -359,7 +365,12 @@ function admitAgainstRead(
 ): EditAdmission {
 	const tracker = context.fileReadTracker
 	if (tracker && !tracker.hasRead(key)) {
-		return { success: false, output: '', error: unreadFileError(key, 'edit') }
+		return {
+			success: false,
+			output: '',
+			error: unreadFileError(key, 'edit'),
+			facts: { kind: 'failure', reason: 'not_read', subject: key },
+		}
 	}
 	const seen = tracker?.fingerprint?.(key)
 	const applied = applyEdit(content, operations)
@@ -367,7 +378,12 @@ function admitAgainstRead(
 		const recoverable = applied.success && operations.every((o) => o.operation === 'replace')
 		if (!recoverable) {
 			recordDrift(context, key)
-			return { success: false, output: '', error: staleFileError(key) }
+			return {
+				success: false,
+				output: '',
+				error: staleFileError(key),
+				facts: { kind: 'failure', reason: 'changed_on_disk', subject: key },
+			}
 		}
 	}
 	return { success: true, result: applied }
@@ -397,6 +413,18 @@ function editFacts(path: string, replacements: number, before: string, after: st
 	}
 }
 
+/** A refused edit, with the kind of refusal when the text said it. */
+function refusedEdit(result: EditApplyFailure, path: string) {
+	return {
+		success: false as const,
+		output: '' as const,
+		error: result.error,
+		...(result.reason
+			? { facts: { kind: 'failure' as const, reason: result.reason, subject: path } }
+			: {}),
+	}
+}
+
 export const EditTool = defineTool({
 	name: 'edit',
 	description:
@@ -529,9 +557,7 @@ export const EditTool = defineTool({
 				const admitted = admitAgainstRead(context, parsed.data.path, content, normalized.operations)
 				if (!admitted.success) return admitted
 				const result = admitted.result
-				if (!result.success) {
-					return { success: false as const, output: '', error: result.error }
-				}
+				if (!result.success) return refusedEdit(result, parsed.data.path)
 
 				await context.sandbox.writeFile(parsed.data.path, result.content)
 				recordEditedContent(context, parsed.data.path, result.content)
@@ -554,7 +580,7 @@ export const EditTool = defineTool({
 			const admitted = admitAgainstRead(context, hostPath, content, normalized.operations)
 			if (!admitted.success) return admitted
 			const result = admitted.result
-			if (!result.success) return { success: false as const, output: '', error: result.error }
+			if (!result.success) return refusedEdit(result, hostPath)
 
 			// Temp file, fsync, rename — a reader sees the old body or the new
 			// one, never a half-written one. A plain `writeFile` that fails

package/src/tools/builtins/exit-semantics.ts

@@ -0,0 +1,198 @@
+/**
+ * How a shell command's exit code is judged.
+ *
+ * Some programs use a non-zero status to answer a question rather than to
+ * report a failure: `grep` exits 1 when nothing matched, `diff` exits 1 when
+ * the files differ, `test` exits 1 when the condition is false. Reading those
+ * as failures turns a normal answer into a red error and sends the model off
+ * to "fix" it. Every other command keeps the plain rule: non-zero is a failure.
+ *
+ * The command is judged by the last command on its line (the one whose status
+ * the shell reports), but only when nothing earlier in an `&&` chain could
+ * have supplied that status: after `cd missing && grep x f` a 1 may come from
+ * `cd`, so the line is judged by the plain rule.
+ */
+
+/** What an exit code means for one command line. */
+export interface ExitJudgement {
+	/** The command failed. */
+	readonly isError: boolean
+	/** A short plain sentence for a non-zero status that is not a failure. */
+	readonly note?: string
+}
+
+/** Longest line the splitter reads; a longer one gets the plain rule. */
+const MAX_COMMAND_CHARS = 10_000
+
+const PLAIN_FAILURE: ExitJudgement = { isError: true }
+
+interface Parsed {
+	/** Command texts in order, with the separator that preceded each. */
+	readonly segments: readonly string[]
+	readonly separators: readonly string[]
+}
+
+/**
+ * Cut a line at unquoted `|`, `|&`, `||`, `&&`, `;`, `&` and newlines.
+ * Undefined when the line has a shape this reading does not follow (an open
+ * quote, a subshell or group, a here-document): the caller then keeps the
+ * plain rule, which is the safe reading.
+ */
+function split(command: string): Parsed | undefined {
+	const segments: string[] = []
+	const separators: string[] = []
+	let current = ''
+	let pending = ''
+	let quote: '"' | "'" | null = null
+	const push = (): void => {
+		segments.push(current)
+		separators.push(pending)
+		current = ''
+	}
+	for (let i = 0; i < command.length; i++) {
+		const ch = command.charAt(i)
+		const next = command.charAt(i + 1)
+		if (quote === "'") {
+			if (ch === "'") quote = null
+			current += ch
+			continue
+		}
+		if (ch === '\\') {
+			current += ch + next
+			i += 1
+			continue
+		}
+		if (ch === '`') {
+			const end = command.indexOf('`', i + 1)
+			if (end === -1) return undefined
+			current += command.slice(i, end + 1)
+			i = end
+			continue
+		}
+		if (ch === '$' && (next === '(' || next === '{')) {
+			const close = next === '(' ? ')' : '}'
+			let depth = 0
+			let j = i + 1
+			for (; j < command.length; j++) {
+				const c = command.charAt(j)
+				if (c === next) depth += 1
+				else if (c === close && --depth === 0) break
+			}
+			if (j >= command.length) return undefined
+			current += command.slice(i, j + 1)
+			i = j
+			continue
+		}
+		if (quote === '"') {
+			if (ch === '"') quote = null
+			current += ch
+			continue
+		}
+		if (ch === '"' || ch === "'") {
+			quote = ch
+			current += ch
+			continue
+		}
+		if (ch === '(' || ch === ')') return undefined
+		if (ch === '<' && next === '<' && command.charAt(i + 2) !== '<') return undefined
+		if (ch === '>' && next === '&') {
+			// `2>&1` and `>&2` are redirects, not a background `&`.
+			current += ch + next
+			i += 1
+			continue
+		}
+		if (ch === '&' && command.charAt(i - 1) === '>') {
+			current += ch
+			continue
+		}
+		if (ch === '|' || ch === '&' || ch === ';' || ch === '\n') {
+			let sep = ch
+			if ((ch === '|' || ch === '&') && next === ch) {
+				sep = ch + ch
+				i += 1
+			} else if (ch === '|' && next === '&') {
+				sep = '|&'
+				i += 1
+			}
+			push()
+			pending = sep === '\n' ? ';' : sep
+			continue
+		}
+		current += ch
+	}
+	if (quote !== null) return undefined
+	push()
+	// A trailing separator (`a;`) leaves an empty last segment: drop it.
+	const kept: string[] = []
+	const keptSeparators: string[] = []
+	segments.forEach((segment, index) => {
+		if (segment.trim().length === 0) return
+		kept.push(segment.trim())
+		keptSeparators.push(separators[index] ?? '')
+	})
+	return kept.length === 0 ? undefined : { segments: kept, separators: keptSeparators }
+}
+
+/**
+ * Whether an earlier command in an `&&` chain could be the one whose status
+ * the line ended with: the last pipeline is joined to what precedes it by `&&`.
+ */
+function followsAndChain(parsed: Parsed): boolean {
+	let index = parsed.segments.length - 1
+	// Walk back over the pipeline the last command belongs to.
+	while (index > 0 && (parsed.separators[index] === '|' || parsed.separators[index] === '|&')) {
+		index -= 1
+	}
+	return parsed.separators[index] === '&&'
+}
+
+const NO_MATCHES = 'No matches found'
+
+const SEARCH_WORDS = new Set(['grep', 'rg', 'egrep', 'fgrep'])
+
+/** The subcommand of a `git` line, skipping global options (`-C <dir>`, `-c <k=v>`). */
+function gitSubcommand(words: readonly string[]): string | undefined {
+	if (words[0] !== 'git') return undefined
+	for (let i = 1; i < words.length; i++) {
+		const word = words[i] as string
+		if (word.startsWith('-')) {
+			if (word === '-C' || word === '-c') i += 1
+			continue
+		}
+		return word
+	}
+	return undefined
+}
+
+function questionNote(command: string): string | undefined {
+	const words = command.trim().split(/\s+/)
+	const first = words[0] ?? ''
+	if (first === 'git') {
+		const sub = gitSubcommand(words)
+		if (sub === 'diff') return 'Files differ'
+		if (sub === 'grep') return NO_MATCHES
+		return undefined
+	}
+	if (SEARCH_WORDS.has(first)) return NO_MATCHES
+	if (first === 'find') return 'Some directories were inaccessible'
+	if (first === 'diff') return 'Files differ'
+	if (first === 'test' || first === '[') return 'Condition is false'
+	return undefined
+}
+
+/**
+ * Judge a finished command's exit code.
+ *
+ * Exit 0 is never a failure. For `grep`, `rg`, `egrep`, `fgrep`, `find`,
+ * `diff`, `test`, `[`, `git diff` and `git grep` as the last command of the
+ * line, exit 1 is an answer (with a short note) and 2 or more is a failure.
+ * Anything else, or a line the reading cannot follow, fails on any non-zero.
+ */
+export function judgeExit(command: string, exitCode: number): ExitJudgement {
+	if (exitCode === 0) return { isError: false }
+	if (exitCode !== 1 || command.length > MAX_COMMAND_CHARS) return PLAIN_FAILURE
+	const parsed = split(command)
+	if (!parsed || followsAndChain(parsed)) return PLAIN_FAILURE
+	const note = questionNote(parsed.segments[parsed.segments.length - 1] as string)
+	return note === undefined ? PLAIN_FAILURE : { isError: false, note }
+}

package/src/tools/builtins/write-file.ts

@@ -210,7 +210,7 @@ function enforceReadBeforeOverwrite(
 		success: false,
 		output: '',
 		error: `${key} already exists. Use the \`read\` tool on it first in this conversation, then call \`write\` again — or prefer \`edit\` for a targeted change.`,
-		facts: { kind: 'failure', reason: 'already_exists', subject: key },
+		facts: { kind: 'failure', reason: 'not_read', subject: key },
 	}
 }
 
@@ -232,7 +232,12 @@ function enforceFreshOverwrite(
 		// so a reader that cannot touch the filesystem stops referencing this
 		// path. Optional on the interface; an older tracker keeps its behavior.
 		context.fileReadTracker?.recordDriftObserved?.(key)
-		return { success: false, output: '', error: staleFileError(key, 'write') }
+		return {
+			success: false,
+			output: '',
+			error: staleFileError(key, 'write'),
+			facts: { kind: 'failure', reason: 'changed_on_disk', subject: key },
+		}
 	}
 	return null
 }

package/src/tools/coordinator/ask-user-question.ts

@@ -366,7 +366,7 @@ export function buildAskUserQuestionTool(config: AskUserQuestionToolOptions): To
 	return defineTool({
 		name: ASK_USER_QUESTION_TOOL_NAME,
 		description:
-			'Ask the user when you are blocked on a decision that is genuinely theirs to make — one you cannot resolve from their request, your tools, the files you can read, or sensible defaults. The question must be the genuinely undecidable thing in THIS task. Never ask for information a tool can discover (do not ask what you can read, list, or search), never re-ask what the conversation already answers, and never ask meta-questions like "Shall I proceed?" — plan ratification goes through approve_plan. Provide 2-4 genuinely distinct options derived from the actual context — concrete paths, never generic placeholders (for example, asked to prepare a presentation, ask "Who is the audience?" with options like Board / Engineering team / Customer); keep labels short (1-5 words) and give each option a one-line description of what practically changes if it is chosen. If you recommend an option, put it FIRST and set recommended: true on it; the host marks it for the user, so never write "(Recommended)" or any translation of it into a label, and never end a label with a parenthesised note (put qualifiers in the description). Set multiSelect: true only when several options can apply at once. An option may carry a preview (plain text or markdown) that the host shows beside the list while it is focused; use it only when seeing the thing helps the choice. A free-text "Something else" escape hatch is always shown automatically — do not add your own "Other" option. Put the questions in the questions array. Use ONE entry for a single decision. Put several entries in the same call only when they are related decisions that ALL block your next step and the user can answer them together (for example which account, for what purpose, which environment before a credentialed step), at most 4, each with a short unique header; the user answers them all in one card and you get one answer per question. Never batch questions that depend on one another\'s answers — ask the first, then decide. Most work needs at most 2-3 questions in all, so prefer proceeding on stated defaults over interrogating the user. Never invent answers or synthetic content on the user\'s behalf unless they explicitly asked for a random/test scenario. The answers arrive as this tool\'s result; a question the result says was not answered must not be assumed, and if the result says the user did not answer at all, do not ask again — proceed on your best judgment without assuming consent.',
+			'Ask the user when you are blocked on a decision that is genuinely theirs to make — one you cannot resolve from their request, your tools, the files you can read, or sensible defaults. The question must be the genuinely undecidable thing in THIS task. Never ask for information a tool can discover (do not ask what you can read, list, or search), never re-ask what the conversation already answers, and never ask meta-questions like "Shall I proceed?" — plan ratification goes through approve_plan. Provide 2-4 genuinely distinct options derived from the actual context — concrete paths, never generic placeholders (for example, asked to prepare a presentation, ask who the audience is, with an option for each plausible audience); keep labels short (1-5 words) and give each option a one-line description of what practically changes if it is chosen. If you recommend an option, put it FIRST and set recommended: true on it; the host marks it for the user, so never write "(Recommended)" or any translation of it into a label, and never end a label with a parenthesised note (put qualifiers in the description). Set multiSelect: true only when several options can apply at once. An option may carry a preview (plain text or markdown) that the host shows beside the list while it is focused; use it only when seeing the thing helps the choice. A free-text "Something else" escape hatch is always shown automatically — do not add your own "Other" option. Put the questions in the questions array. Use ONE entry for a single decision. Put several entries in the same call only when they are related decisions that ALL block your next step and the user can answer them together (for example which account, for what purpose, which environment before a credentialed step), at most 4, each with a short unique header; the user answers them all in one card and you get one answer per question. Never batch questions that depend on one another\'s answers — ask the first, then decide. Most work needs at most 2-3 questions in all, so prefer proceeding on stated defaults over interrogating the user. Never invent answers or synthetic content on the user\'s behalf unless they explicitly asked for a random/test scenario. The answers arrive as this tool\'s result; a question the result says was not answered must not be assumed, and if the result says the user did not answer at all, do not ask again — proceed on your best judgment without assuming consent.',
 		inputSchema,
 		modelInputSchema: structuredClone(askUserQuestionModelInputSchema),
 		enforceModelInput: true,

package/src/tools/coordinator/index.ts

@@ -252,7 +252,7 @@ const approvePlanModelInputSchema: Record<string, unknown> = {
 	properties: {
 		title: {
 			type: 'string',
-			description: 'Short title for the plan (e.g. "TypeScript Security & Performance Review").',
+			description: 'Short title for the plan (e.g. "Security & Performance Review").',
 		},
 		summary: {
 			type: 'string',
@@ -1279,7 +1279,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			inputSchema: z.object({
 				title: z
 					.string()
-					.describe('Short title for the plan (e.g. "TypeScript Security & Performance Review")'),
+					.describe('Short title for the plan (e.g. "Security & Performance Review")'),
 				summary: z.string().describe('1-3 sentence summary of what you plan to do'),
 				steps: z
 					.preprocess(normalizeApprovePlanSteps, z.array(approvePlanStepSchema))

package/src/tools/memory/delete.ts

@@ -10,7 +10,7 @@ export function buildDeleteMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'delete_memory',
 		description:
-			'Permanently delete a stored memory by ID. Use update_memory with status archived when the record should remain available for inspection. Deletion does not erase past conversation transcripts. Pass the revision from read_memory when available to refuse a stale deletion.',
+			'Permanently remove a memory by ID, for one that should not be kept at all. Use update_memory with status archived when the record should stay available to inspect. Past conversation transcripts are not changed. Pass the revision from read_memory when available, so a deletion of a memory that changed since you read it is refused. Returns a confirmation.',
 		inputSchema: z.object({
 			id: z.string().describe('Memory ID to permanently delete'),
 			revision: z

package/src/tools/memory/fields.ts

@@ -9,7 +9,7 @@ export const memoryFieldsSchema = {
 		.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
 		.optional()
 		.describe(
-			'Unique kebab-case slug, e.g. "deploys-need-a-changeset"; other memories link to it as [[name]]',
+			'Unique kebab-case slug, e.g. "prefers-short-answers"; other memories link to it as [[name]]',
 		),
 	description: z
 		.string()

package/src/tools/memory/read.ts

@@ -16,7 +16,7 @@ export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'read_memory',
 		description:
-			'Read the full content of a specific memory by its ID or its name. For a text or Markdown memory the result ends with how old the memory is and resolves any [[name]] links it contains.',
+			'Read one memory in full by its ID or its name. Use it when the index or a search shows that a memory bears on the task. Returns the memory text; a text or Markdown memory ends with how old it is and the memories its [[name]] links point to.',
 		inputSchema: z.object({
 			id: z
 				.string()

package/src/tools/memory/save.ts

@@ -10,11 +10,12 @@ export function buildSaveMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'save_memory',
 		description: [
-			'Save a new memory for future sessions: something true now that a later session could not work out from the code, the git history or the files themselves. Do not save what those already say.',
-			'Choose a type: user (who the user is and how they like to work), feedback (a rule the user gave about how to work), project (a fact or decision about the work), reference (where to look for something).',
+			'Save one memory for later sessions in this project: a single fact that the code, the history and the docs do not already hold.',
+			'Choose a type: user (who the person is and how they like to work), feedback (a rule they gave about how to work), project (a fact or decision about the work), reference (where to look for something).',
 			'For feedback and project memories, write the rule or fact first, then a line starting "Why:" and a line starting "How to apply:".',
 			'Link a related memory by writing [[its-name]] in the content.',
-			'If a memory on this already exists, use update_memory instead: a name another memory holds is refused.',
+			'The name must be new: a name another memory holds is refused, and the reply points to update_memory.',
+			"Returns the saved memory's id and name.",
 		].join(' '),
 		inputSchema: z.object({
 			title: z.string().min(1).describe('Short descriptive title'),

package/src/tools/memory/search.ts

@@ -16,7 +16,7 @@ function defineSearchMemoryTool(search: SearchMemory): ToolDefinition {
 	return defineTool({
 		name: 'search_memory',
 		description:
-			'Search active stored memories by relevant words or tags. The built-in stores rank matches in names, titles, descriptions, summaries and full content. Built-in search examines at most 256 recent candidates per call; if incomplete, continue with the returned scan_offset. Use read_memory for evidence. Set status to archived to inspect obsolete records.',
+			"Find stored memories by words or tags. Use it when the topic is not in the index, before saving (to see whether a memory already covers it), and to reach what earlier turns recorded on their own. Matches are ranked across names, titles, descriptions, summaries and content; one call examines at most 256 recent candidates, and an incomplete result returns a scan_offset to continue from. Set status to archived to look at retired memories. Returns a numbered list with each memory's id, title, type and description; open one with read_memory.",
 		inputSchema: z.object({
 			query: z.string().optional().describe('Relevant words or identifiers to search'),
 			tags: z.array(z.string()).optional().describe('Filter by tags (all must match)'),

package/src/tools/memory/update.ts

@@ -12,7 +12,7 @@ export function buildUpdateMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'update_memory',
 		description:
-			'Correct an existing memory in place, or archive an obsolete claim so it is no longer recalled. Prefer this to saving a second memory about the same thing. Identify it by the ID from search_memory or by its name from the memory index; current evidence should determine corrections. Pass the revision from read_memory when available to refuse a stale correction.',
+			'Correct a memory in place, or archive one that is no longer true so it stops being recalled. Use it when a memory on the same topic already exists, which keeps the store free of duplicates, and when current evidence shows a memory is wrong. Identify the memory by the ID from search_memory or by its name from the index. Pass the revision from read_memory when available, so a change made since you read it is refused instead of overwritten. Returns the memory as it now stands.',
 		inputSchema: z.object({
 			id: z
 				.string()

package/src/tools/schedules/schedule-tool.ts

@@ -121,7 +121,7 @@ const inputSchema = z.object({
 			rules: z
 				.record(z.string(), z.union([EFFECT, z.record(z.string(), EFFECT)]))
 				.optional()
-				.describe('Extra rules, e.g. {"bash": {"npm test*": "allow"}}'),
+				.describe('Extra rules, e.g. {"bash": {"<command> *": "allow"}}'),
 			browser: z
 				.object({
 					profile: z
@@ -131,7 +131,7 @@ const inputSchema = z.object({
 					sites: z
 						.record(z.string(), z.enum(['read', 'ask', 'act']))
 						.describe(
-							'Site to level, e.g. {"https://github.com": "read"}. read: open and read only; ask: changes wait for the operator; act: changes run unasked. Unlisted sites are denied; there is no "*".',
+							'Site to level, e.g. {"https://example.com": "read"}. read: open and read only; ask: changes wait for the operator; act: changes run unasked. Unlisted sites are denied; there is no "*".',
 						),
 					headed: z.boolean().optional().describe('Show the browser window; default no window'),
 				})
@@ -239,7 +239,7 @@ function browserGrant(
 		return {
 			ok: false,
 			error:
-				'permissions.browser.sites is empty; list each site the run may open, e.g. {"https://github.com": "read"}.',
+				'permissions.browser.sites is empty; list each site the run may open, e.g. {"https://example.com": "read"}.',
 		}
 	}
 	const sites: Record<string, ScheduleBrowserSiteLevel> = {}

package/src/toolsets/manager.ts

@@ -1012,7 +1012,12 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 			'namzu.registry.errors': errorMessage,
 			'namzu.registry.empty': isEmptyInput,
 		})
-		return { success: false, output: '', error: enrichedMessage }
+		return {
+			success: false,
+			output: '',
+			error: enrichedMessage,
+			facts: { kind: 'failure', reason: 'invalid_arguments' },
+		}
 	}
 }