@namzu/sdk 34.2.0 → 35.0.0

package/src/manager/run/persistence.ts

@@ -2,9 +2,11 @@ import { AUTO_CONTINUATION_USER_MESSAGE } from '../../constants/continuation.js'
 import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
 import { NAMZU } from '../../constants/telemetry/index.js'
 import { resolveModelPricing } from '../../pricing/index.js'
+import type { TokenBudget } from '../../run/token-budget.js'
 import { DiskCheckpointStore } from '../../store/run/checkpoint-disk.js'
 import { RunDiskStore } from '../../store/run/disk.js'
 import { getActiveSpanContext } from '../../telemetry/runtime-accessors.js'
+import { mergeTokenUsage } from '../../types/common/index.js'
 import { type CostInfo, type TokenUsage, accumulateTokenUsage } from '../../types/common/index.js'
 import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
@@ -38,6 +40,7 @@ export interface PricingSubject {
 }
 
 export class RunPersistence {
+	readonly budget?: TokenBudget
 	private run: Run
 	private runStore: RunStore
 	private checkpointStore: CheckpointStore
@@ -54,6 +57,7 @@ export class RunPersistence {
 	private readonly _projectId: ProjectId
 
 	constructor(config: RunPersistenceConfig) {
+		this.budget = config.budget
 		this.pricing = config.pricing
 		this.log = config.log
 		this._sessionId = config.sessionId
@@ -148,11 +152,24 @@ export class RunPersistence {
 	}
 
 	get tokenUsage(): TokenUsage {
-		return this.run.tokenUsage
+		return this.budget
+			? mergeTokenUsage(this.run.tokenUsage, this.budget.ownUsage)
+			: this.run.tokenUsage
 	}
 
 	get costInfo(): CostInfo {
-		return this.run.costInfo
+		const unpriced = Math.max(0, this.tokenUsage.totalTokens - this.run.tokenUsage.totalTokens)
+		return unpriced > 0
+			? { ...this.run.costInfo, unpricedTokens: this.run.costInfo.unpricedTokens + unpriced }
+			: this.run.costInfo
+	}
+
+	private syncBudget(): void {
+		if (!this.budget) return
+		this.run.costInfo = this.costInfo
+		this.run.tokenUsage = this.tokenUsage
+		this.run.budget = this.budget.summary()
+		this.run.budgetBinding = this.budget.binding
 	}
 
 	get currentIteration(): number {
@@ -160,11 +177,18 @@ export class RunPersistence {
 	}
 
 	getRun(): Readonly<Run> {
-		return this.run
+		if (!this.budget) return this.run
+		return {
+			...this.run,
+			tokenUsage: this.tokenUsage,
+			costInfo: this.costInfo,
+			budget: this.budget.summary(),
+			budgetBinding: this.budget.binding,
+		}
 	}
 
 	getSession(): Readonly<Run> {
-		return this.run
+		return this.getRun()
 	}
 
 	getRunStore(): RunStore {
@@ -525,6 +549,8 @@ export class RunPersistence {
 		this.run.tokenUsage = { ...tokenUsage }
 		this.run.costInfo = { ...costInfo }
 		this.run.currentIteration = currentIteration
+		this.budget?.recordUsage(tokenUsage)
+		this.syncBudget()
 	}
 
 	/**
@@ -588,7 +614,9 @@ export class RunPersistence {
 			id: generateEmergencySaveId(),
 			runId: this.run.id,
 			messages: this.run.messages,
-			tokenUsage: this.run.tokenUsage,
+			tokenUsage: this.tokenUsage,
+			budgetBinding: this.budget?.binding,
+			budgetAccountId: this.budget?.accountId,
 			currentIteration: this.run.currentIteration,
 			startedAt: this.run.startedAt,
 			savedAt: Date.now(),
@@ -673,6 +701,8 @@ export class RunPersistence {
 	}
 
 	async persist(): Promise<void> {
+		await this.budget?.flush()
+		this.syncBudget()
 		await this.runStore.writeRunMeta(this.run)
 		await this.runStore.writeMessages(this.run, this._lastEventSeq)
 		// Optional on the contract: a backend whose runs are already queryable

package/src/plugin/index.ts

@@ -2,3 +2,22 @@ export { discoverPlugins, loadPluginManifest, discoverAllPluginDirs } from './lo
 export type { PluginDiscoveryOptions, PluginEnablementCapabilities } from './loader.js'
 export { PluginLifecycleManager } from './lifecycle.js'
 export { PluginResolver } from './resolver.js'
+export {
+	attachShellHooks,
+	createShellHook,
+	DEFAULT_SHELL_HOOK_TIMEOUT_MS,
+	MAX_SHELL_HOOK_TIMEOUT_MS,
+	runShellHook,
+	SHELL_HOOK_EVENTS,
+	SHELL_HOOKS_PLUGIN_ID,
+	shellHookMatches,
+	shellHookVerdict,
+} from './shell-hook.js'
+export type {
+	ShellHookEntry,
+	ShellHookEvent,
+	ShellHookInput,
+	ShellHookOptions,
+	ShellHookOutcome,
+	ShellHooksConfig,
+} from './shell-hook.js'

package/src/plugin/shell-hook.ts

@@ -0,0 +1,403 @@
+/**
+ * A shell command as a plugin hook.
+ *
+ * The lifecycle manager carries a hook system — `pre_tool_use`,
+ * `post_tool_use`, `run_start`, `run_end` and the rest — and `registerHook`
+ * lets a host attach a handler without a plugin on disk. What every host then
+ * writes for itself is the same adapter: run a command, hand it the event,
+ * read its exit code. This file is that adapter, once, so an operator
+ * application, an ACP server and an embedder all offer the same contract and
+ * an operator's hook script works under all three.
+ *
+ * ## The contract
+ *
+ * The command runs with `sh -c` in `cwd`. It receives one JSON object on
+ * stdin — `event`, `cwd`, `run_id`, and for tool events `tool_name`,
+ * `tool_input` and (after the call) `tool_result` — and the same facts as
+ * `NAMZU_HOOK_EVENT`, `NAMZU_RUN_ID`, `NAMZU_TOOL_NAME` and, when the input
+ * names a file, `NAMZU_TOOL_PATH`. Its exit code is its answer:
+ *
+ * - `0` — carry on.
+ * - `2` — **block.** Before a tool (`pre_tool_use`) the call is skipped and the
+ *   model is told why, with the hook's stderr as the reason. On any other
+ *   event a 2 is reported and the run carries on: there is nothing left to
+ *   block once the tool has run or the run has started.
+ * - anything else — the hook's own failure. Reported through the logger,
+ *   never blocking. A formatter that crashed must not stop the agent editing,
+ *   and a script missing its interpreter (127) must not read as "forbidden".
+ *
+ * `2` rather than any non-zero, because a verdict and a failure are different
+ * facts and one exit code cannot carry both.
+ *
+ * ## What a hook cannot do here
+ *
+ * Modify a tool's input or replace its result. The hook protocol allows both
+ * (`modify`, `replace`); this adapter exposes neither, because a shell command
+ * that rewrites what the model asked for deserves its own design and audit,
+ * not a JSON field on stdout nobody reviewed.
+ *
+ * ## Bounds
+ *
+ * Each hook has a deadline (`timeoutMs`, default 30 s, capped at ten minutes)
+ * and its output is captured to a bound. A hook that times out is reported
+ * and does not block: one that could not answer in time has not answered no.
+ */
+
+import { spawn } from 'node:child_process'
+
+import type { PluginId } from '../types/ids/index.js'
+import type {
+	PluginCompactionInfo,
+	PluginHookContext,
+	PluginHookDefinition,
+	PluginHookEvent,
+	PluginHookResult,
+} from '../types/plugin/index.js'
+import { asPluginId } from '../utils/id.js'
+import { NOOP_LOGGER } from '../utils/log/create-logger.js'
+import type { Logger } from '../utils/logger.js'
+import type { PluginLifecycleManager } from './lifecycle.js'
+
+/**
+ * The events a shell hook may attach to: the ones an operator can act on
+ * from a script. The model-call and iteration events stay in-process —
+ * they carry the messages, and a shell is not where those go.
+ */
+export type ShellHookEvent = Extract<
+	PluginHookEvent,
+	| 'user_prompt_submit'
+	| 'session_start'
+	| 'session_end'
+	| 'pre_tool_use'
+	| 'post_tool_use'
+	| 'pre_compact'
+	| 'post_compact'
+	| 'subagent_stop'
+	| 'run_start'
+	| 'run_end'
+>
+
+export const SHELL_HOOK_EVENTS: readonly ShellHookEvent[] = [
+	'user_prompt_submit',
+	'session_start',
+	'session_end',
+	'pre_tool_use',
+	'post_tool_use',
+	'pre_compact',
+	'post_compact',
+	'subagent_stop',
+	'run_start',
+	'run_end',
+]
+
+/** One shell command at one event. */
+export interface ShellHookEntry {
+	/** Run with `sh -c`, in the working directory, with the event JSON on stdin. */
+	readonly command: string
+	/** Tool names this applies to: `*`, a name, or `a|b|prefix*`. Absent means every tool. */
+	readonly matcher?: string
+	/** Deadline in milliseconds; default `DEFAULT_SHELL_HOOK_TIMEOUT_MS`, capped at `MAX_SHELL_HOOK_TIMEOUT_MS`. */
+	readonly timeoutMs?: number
+}
+
+/** Event → entries, the shape a host's config file carries. */
+export type ShellHooksConfig = { readonly [event in ShellHookEvent]?: readonly ShellHookEntry[] }
+
+/** The plugin id host shell hooks register under when the host names none. */
+export const SHELL_HOOKS_PLUGIN_ID: PluginId = asPluginId('6d6f6bec-9d54-485b-90ca-52edbac1009d')
+
+export const DEFAULT_SHELL_HOOK_TIMEOUT_MS = 30_000
+export const MAX_SHELL_HOOK_TIMEOUT_MS = 10 * 60_000
+/** Captured output bound per stream. */
+const MAX_CAPTURE_BYTES = 64 * 1024
+
+/**
+ * `matcher` against a tool name: `*`, or a `|`-separated list of names, each
+ * of which may end in `*`. Case-sensitive, because tool names are. A matcher
+ * on an event with no tool (`run_start`) matches nothing unless it is `*`.
+ */
+export function shellHookMatches(
+	matcher: string | undefined,
+	toolName: string | undefined,
+): boolean {
+	if (matcher === undefined || matcher.trim() === '' || matcher.trim() === '*') return true
+	if (toolName === undefined) return false
+	return matcher.split('|').some((part) => {
+		const candidate = part.trim()
+		if (candidate.length === 0) return false
+		return candidate.endsWith('*')
+			? toolName.startsWith(candidate.slice(0, -1))
+			: toolName === candidate
+	})
+}
+
+/** What one hook run came back with, before it is mapped to a verdict. */
+export interface ShellHookOutcome {
+	readonly exitCode: number | null
+	readonly timedOut: boolean
+	readonly stdout: string
+	readonly stderr: string
+	/** Set when the process could not be started at all. */
+	readonly spawnError?: string
+}
+
+export interface ShellHookInput {
+	readonly event: ShellHookEvent
+	readonly cwd: string
+	readonly runId: string
+	readonly sessionId?: string
+	readonly parentRunId?: string
+	readonly prompt?: string
+	readonly compaction?: PluginCompactionInfo
+	readonly toolName?: string
+	readonly toolInput?: unknown
+	readonly toolResult?: {
+		readonly success: boolean
+		readonly output: string
+		readonly error?: string
+	}
+}
+
+/** Run one hook command to completion, bounded by its deadline and capture. */
+export function runShellHook(
+	entry: ShellHookEntry,
+	input: ShellHookInput,
+	signal?: AbortSignal,
+): Promise<ShellHookOutcome> {
+	const timeoutMs = Math.min(
+		MAX_SHELL_HOOK_TIMEOUT_MS,
+		Math.max(1, entry.timeoutMs ?? DEFAULT_SHELL_HOOK_TIMEOUT_MS),
+	)
+	const payload = JSON.stringify({
+		event: input.event,
+		cwd: input.cwd,
+		run_id: input.runId,
+		...(input.sessionId !== undefined ? { session_id: input.sessionId } : {}),
+		...(input.parentRunId !== undefined ? { parent_run_id: input.parentRunId } : {}),
+		...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
+		...(input.compaction !== undefined ? { compaction: input.compaction } : {}),
+		...(input.toolName !== undefined ? { tool_name: input.toolName } : {}),
+		...(input.toolInput !== undefined ? { tool_input: input.toolInput } : {}),
+		...(input.toolResult !== undefined ? { tool_result: input.toolResult } : {}),
+	})
+	const toolPath = pathOf(input.toolInput)
+	return new Promise((resolve) => {
+		let child: ReturnType<typeof spawn>
+		try {
+			child = spawn('sh', ['-c', entry.command], {
+				cwd: input.cwd,
+				env: {
+					...process.env,
+					NAMZU_HOOK_EVENT: input.event,
+					NAMZU_RUN_ID: input.runId,
+					...(input.sessionId !== undefined ? { NAMZU_SESSION_ID: input.sessionId } : {}),
+					...(input.toolName !== undefined ? { NAMZU_TOOL_NAME: input.toolName } : {}),
+					...(toolPath !== undefined ? { NAMZU_TOOL_PATH: toolPath } : {}),
+				},
+				stdio: ['pipe', 'pipe', 'pipe'],
+				// Its own process group, so the deadline can kill everything the
+				// command started. `sh -c 'sleep 5'` is one process under a shell
+				// that execs its last command and two under one that forks it;
+				// killing only the shell in the second case leaves `sleep` holding
+				// the stdout pipe, and the outcome cannot settle until it exits on
+				// its own — the hook's deadline becomes the grandchild's.
+				detached: process.platform !== 'win32',
+			})
+		} catch (error) {
+			resolve({
+				exitCode: null,
+				timedOut: false,
+				stdout: '',
+				stderr: '',
+				spawnError: error instanceof Error ? error.message : String(error),
+			})
+			return
+		}
+		let stdout = ''
+		let stderr = ''
+		let timedOut = false
+		let settled = false
+		const capture = (current: string, chunk: Buffer): string =>
+			current.length >= MAX_CAPTURE_BYTES
+				? current
+				: (current + chunk.toString('utf8')).slice(0, MAX_CAPTURE_BYTES)
+		child.stdout?.on('data', (chunk: Buffer) => {
+			stdout = capture(stdout, chunk)
+		})
+		child.stderr?.on('data', (chunk: Buffer) => {
+			stderr = capture(stderr, chunk)
+		})
+		const finish = (outcome: ShellHookOutcome) => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			signal?.removeEventListener('abort', onAbort)
+			resolve(outcome)
+		}
+		const killTree = () => {
+			if (child.pid !== undefined && process.platform !== 'win32') {
+				try {
+					process.kill(-child.pid, 'SIGKILL')
+					return
+				} catch {
+					// The group is already gone, or this platform has no groups;
+					// the child alone is the best that can be done.
+				}
+			}
+			child.kill('SIGKILL')
+		}
+		const timer = setTimeout(() => {
+			timedOut = true
+			killTree()
+		}, timeoutMs)
+		const onAbort = () => killTree()
+		signal?.addEventListener('abort', onAbort, { once: true })
+		child.on('error', (error) => {
+			finish({ exitCode: null, timedOut, stdout, stderr, spawnError: error.message })
+		})
+		child.on('close', (code) => {
+			finish({ exitCode: code, timedOut, stdout, stderr })
+		})
+		child.on('exit', () => {
+			// After a kill, a survivor that still holds the pipes must not hold
+			// the outcome: drop our ends so `close` follows `exit` promptly.
+			if (timedOut || signal?.aborted) {
+				child.stdout?.destroy()
+				child.stderr?.destroy()
+			}
+		})
+		child.stdin?.on('error', () => {
+			// A hook that never reads stdin closes it; that is not a failure.
+		})
+		child.stdin?.end(payload)
+	})
+}
+
+function pathOf(toolInput: unknown): string | undefined {
+	if (toolInput === null || typeof toolInput !== 'object') return undefined
+	const record = toolInput as Record<string, unknown>
+	for (const key of ['path', 'file_path', 'filePath']) {
+		const value = record[key]
+		if (typeof value === 'string' && value.length > 0) return value
+	}
+	return undefined
+}
+
+/**
+ * The verdict, from the outcome and the event. Pure apart from the logger,
+ * so the mapping — the part that decides what the model is told — is
+ * testable without a process.
+ */
+export function shellHookVerdict(
+	event: ShellHookEvent,
+	entry: ShellHookEntry,
+	outcome: ShellHookOutcome,
+	log: Logger = NOOP_LOGGER,
+): PluginHookResult {
+	const attrs = { 'namzu.hook.event': event, 'namzu.hook.command': entry.command }
+	if (outcome.spawnError !== undefined) {
+		log.warn('hook could not start', { ...attrs, 'namzu.hook.error': outcome.spawnError })
+		return { action: 'continue' }
+	}
+	if (outcome.timedOut) {
+		log.warn('hook timed out', attrs)
+		return { action: 'continue' }
+	}
+	if (outcome.exitCode === 0) {
+		// On the prompt event, what the hook printed is context for the
+		// model — the branch, the time, a ticket. Everywhere else stdout is
+		// the operator's to read and the model's business not at all.
+		const text = outcome.stdout.trim()
+		if (event === 'user_prompt_submit' && text.length > 0) return { action: 'annotate', text }
+		return { action: 'continue' }
+	}
+	if (outcome.exitCode === 2) {
+		const reason =
+			outcome.stderr.trim() || outcome.stdout.trim() || `blocked by hook \`${entry.command}\``
+		if (event === 'pre_tool_use' || event === 'user_prompt_submit')
+			return { action: 'skip', reason }
+		log.warn('hook returned 2 on an event it cannot block', {
+			...attrs,
+			'namzu.hook.reason': reason,
+		})
+		return { action: 'continue' }
+	}
+	log.warn('hook failed', {
+		...attrs,
+		'namzu.hook.exit': outcome.exitCode ?? -1,
+		'namzu.hook.stderr': outcome.stderr.trim().slice(0, 500),
+	})
+	return { action: 'continue' }
+}
+
+export interface ShellHookOptions {
+	/** Where the command runs and what `cwd` says on stdin. */
+	readonly cwd: string
+	readonly log?: Logger
+}
+
+/** One entry as a hook definition the lifecycle manager accepts. */
+export function createShellHook(
+	event: ShellHookEvent,
+	entry: ShellHookEntry,
+	options: ShellHookOptions,
+): PluginHookDefinition {
+	const log = options.log ?? NOOP_LOGGER
+	return {
+		event,
+		handler: async (context: PluginHookContext) => {
+			if (!shellHookMatches(entry.matcher, context.toolName)) return { action: 'continue' }
+			const outcome = await runShellHook(
+				entry,
+				{
+					event,
+					cwd: options.cwd,
+					runId: String(context.runId),
+					...(context.sessionId !== undefined ? { sessionId: String(context.sessionId) } : {}),
+					...(context.parentRunId !== undefined
+						? { parentRunId: String(context.parentRunId) }
+						: {}),
+					...(context.prompt !== undefined ? { prompt: context.prompt } : {}),
+					...(context.compaction !== undefined ? { compaction: context.compaction } : {}),
+					...(context.toolName !== undefined ? { toolName: context.toolName } : {}),
+					...(context.toolInput !== undefined ? { toolInput: context.toolInput } : {}),
+					...(context.toolResult !== undefined
+						? {
+								toolResult: {
+									success: context.toolResult.success,
+									output: context.toolResult.output,
+									...(context.toolResult.error !== undefined
+										? { error: context.toolResult.error }
+										: {}),
+								},
+							}
+						: {}),
+				},
+				context.signal,
+			)
+			return shellHookVerdict(event, entry, outcome, log)
+		},
+	}
+}
+
+/**
+ * Register every entry on the manager, in file order within an event. The
+ * manager runs `post_*` hooks in reverse, as it does for plugins, so a
+ * formatter registered last runs first after a write. Returns how many were
+ * attached.
+ */
+export function attachShellHooks(
+	manager: Pick<PluginLifecycleManager, 'registerHook'>,
+	hooks: ShellHooksConfig,
+	options: ShellHookOptions & { readonly pluginId?: PluginId },
+): number {
+	const pluginId = options.pluginId ?? SHELL_HOOKS_PLUGIN_ID
+	let count = 0
+	for (const event of SHELL_HOOK_EVENTS) {
+		for (const entry of hooks[event] ?? []) {
+			manager.registerHook(pluginId, createShellHook(event, entry, options))
+			count += 1
+		}
+	}
+	return count
+}

package/src/prompt/coding-agent-doctrine.ts

@@ -0,0 +1,118 @@
+/**
+ * How a coding agent works, as text the model reads.
+ *
+ * A system prompt built from the kernel says WHO the agent is and what tools
+ * it has. Nothing said HOW it should work: whether to act or ask, how much of
+ * a request to deliver, what to do when a test fails, when a shell command is
+ * the wrong tool, what is off-limits in git without a person saying so. Every
+ * one of those was left to the underlying model's defaults, and the defaults
+ * differ per provider — so the same session felt like a different agent
+ * depending on which model was behind it, and an operator experienced the gap
+ * as "it narrates instead of doing", "it stopped halfway", "it asked me three
+ * things it could have decided".
+ *
+ * This lived in the operator application first. It moved here because none of
+ * it is about that application: every rule names a builtin tool of this kernel
+ * (`read`, `edit`, `bash`, `task_create`, `Agent`) or a behaviour any coding
+ * agent built on it wants, and a second host would otherwise copy the text and
+ * let the two drift.
+ *
+ * Two texts, not one, and the split is by TOOL SET rather than by topic.
+ * `CODING_AGENT_WORKING_DOCTRINE` names only the builtins and is meant for the
+ * parent and for every delegated sub-agent, because a delegated task edits the
+ * same repository under the same rules. `CODING_AGENT_DELEGATION_DOCTRINE`
+ * names `task_create` and `Agent`, which a sub-agent does not have, and so is
+ * for the parent only. An adversarial review caught a draft ordering children
+ * to plan with a tool they could not call; a rule about a tool the reader does
+ * not have is not guidance, it is an instruction to fail.
+ *
+ * Each rule names a behaviour, not a value; a rule about one repository
+ * belongs in that repository's instructions file, which the model receives
+ * separately. A host that wants its own identity block puts it in
+ * `systemPrompt`; the contribution below lands after it.
+ */
+
+import type { PromptContribution } from './contributions.js'
+
+export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
+
+### Delivering work
+- Act when you have enough information. Do not re-derive facts already established, and do not re-open a decision the user has already made.
+- The requested scope is the deliverable. Do not quietly narrow it, widen it, or turn it into something adjacent. Read ambiguity the way a careful colleague would; make the routine judgment calls yourself and check in only when different readings would produce materially different work.
+- Finish the whole task, not just the easy parts. If one part is blocked — a tool or capability you do not have, an input that is missing — say so plainly, do not improvise a result for it, finish every other part in full, and say explicitly what you left out and why. Scaling the work down is the user's call.
+- If you find a real problem with the task as stated, say so in a sentence or two, then keep going under a stated assumption. Reserve blocking questions for cases where proceeding under any assumption would be unsafe or would make the work useless if wrong.
+- If the user repeats or reaffirms a request after you raised a concern, that is their decision: say so and do the full request.
+
+### Reporting
+- Report outcomes faithfully. If tests fail, say so and show the output. If you skipped a step, say it was skipped. When something is done and verified, state it plainly without hedging.
+- Never present a green run on a subset as a green run. Name what was actually executed.
+- Reference code as \`path:line\` so the user can jump to it.
+- Correct an earlier statement only when the error would change the user's code, conclusions or decisions; state it once, plainly, and continue. No apologies, no tally of past mistakes.
+
+### Reading and editing code
+- Read a file before you edit it, and read enough of the surrounding code to match its comment density, naming and idiom. Code that reads like the file it lives in is the goal; code that reads like a different author is a defect.
+- Prefer the dedicated tools over shell equivalents: \`read\` over \`cat\`, the \`grep\` tool over running \`grep\` or \`rg\` through bash, \`glob\` over \`find\` or \`ls -R\`, \`edit\` over \`sed -i\`. To change an existing file use \`edit\`; use \`write\` only to create a file or when the user asked for a whole-file rewrite. The dedicated tools are bounded, previewable and permission-aware; a shell command is none of those.
+- Independent tool calls go in one response. Reading three files, or running a grep and a glob, does not need three turns. Tools that mutate the workspace — \`bash\`, \`edit\`, \`write\` — are applied one after another even when you emit them together; read-only tools run in parallel.
+- After a change, run the checks that would catch a mistake in it — the package's tests, typecheck, lint — before you report it done. A change you did not verify is a change you are guessing about.
+- Never leave the working tree in a state you have not described. If you created scratch files, say where; if you touched files outside the request, say which.
+
+### Working with git
+- Never push, force-push, reset, rebase, clean, or otherwise discard or rewrite history unless the user explicitly asked for that action. Approval for one push does not extend to the next.
+- Before any command that could discard uncommitted work, run \`git status\`. If there are changes there that you did not make, stop and ask rather than stashing, committing or discarding somebody else's work.
+- Commit only when the user asks, on the branch that is checked out. Do not create or switch branches unless the user asks or the project's instructions require it.
+- After a broad \`git add\`, review what was staged before committing; a file whose name looks harmless can still carry a secret.
+
+### Keeping the user informed
+- Before a batch of tool calls, say in one short line what you are about to do and why. When you have been working for a while without saying anything, say in a few words where you are, then continue. One line, not a paragraph; the tool rows on screen already show the details.
+- Keep the final reply short and specific: what changed, what was verified, what is left. Do not restate the transcript.`
+
+/**
+ * Parent-only: rules about `task_create` / `task_update` and `Agent`, which a
+ * delegated sub-agent does not have. See the module comment for the split.
+ */
+export const CODING_AGENT_DELEGATION_DOCTRINE = `### Planning and delegating
+- For work that is genuinely multi-step — several files, several distinct stages, anything you would write a checklist for — open a task list with \`task_create\` and keep it current with \`task_update\`, marking each step done when it is done rather than at the end. Do not open one for a single inspect-edit-test cycle; the list is for the user to follow, and a list of one item tells them nothing.
+- When the \`Agent\` tool is available, delegate genuinely independent work through it and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Each sub-agent starts with no context, so the prompt must carry everything it needs.
+- Delegate lookups — where something is defined, which files reference it, how a module works — with \`subagent_type: "explore"\`: it has reading and searching tools only and never interrupts the user for permission. Reserve the default sub-agent for work that changes files or runs commands.`
+
+/**
+ * For a session whose permission layer refuses every mutation. Says what that
+ * layer will enforce anyway, so the model plans instead of discovering the
+ * boundary one refused call at a time.
+ */
+export const PLAN_MODE_DOCTRINE = `## Plan mode
+
+You are in plan mode. Read, search and think; do not change anything. \`read\`, \`grep\`, \`glob\` and the other read-only tools work as usual, and you may keep a task list. Any \`edit\`, \`write\` or shell command that changes state will be refused, so do not attempt one.
+
+When you have understood the task, reply with the plan: what you would change, in which files, in what order, and what you would verify. Be concrete — name files and functions — and short enough to read in one screen. Then stop and wait; the user will leave plan mode to have the plan carried out, and that switch is their approval.`
+
+export const CODING_AGENT_DOCTRINE_CONTRIBUTION_ID = 'namzu.coding-agent-doctrine'
+
+export interface CodingAgentDoctrineOptions {
+	/**
+	 * Include the parent-only delegation rules. Default `true`; a host
+	 * building the prompt of a delegated sub-agent, which has no `Agent` or
+	 * `task_create`, passes `false`.
+	 */
+	delegation?: boolean
+}
+
+/**
+ * The doctrine as a `static` contribution: it depends on nothing that changes
+ * inside a run, so it belongs in the cached prefix. Register it on the
+ * `PromptContributionRegistry` handed to `query`; it renders after
+ * `systemPrompt` and the skills section.
+ */
+export function codingAgentDoctrineContribution(
+	options: CodingAgentDoctrineOptions = {},
+): PromptContribution {
+	const text =
+		options.delegation === false
+			? CODING_AGENT_WORKING_DOCTRINE
+			: `${CODING_AGENT_WORKING_DOCTRINE}\n\n${CODING_AGENT_DELEGATION_DOCTRINE}`
+	return {
+		id: CODING_AGENT_DOCTRINE_CONTRIBUTION_ID,
+		placement: 'static',
+		render: () => text,
+	}
+}

package/src/prompt/index.ts

@@ -13,3 +13,11 @@ export type {
 	PromptContributionContext,
 	PromptPlacement,
 } from './contributions.js'
+export {
+	CODING_AGENT_DELEGATION_DOCTRINE,
+	CODING_AGENT_DOCTRINE_CONTRIBUTION_ID,
+	CODING_AGENT_WORKING_DOCTRINE,
+	PLAN_MODE_DOCTRINE,
+	codingAgentDoctrineContribution,
+} from './coding-agent-doctrine.js'
+export type { CodingAgentDoctrineOptions } from './coding-agent-doctrine.js'

package/src/provider/errors.ts

@@ -412,7 +412,7 @@ function vendorRetryAfter(err: unknown): string | undefined {
  * isolation — that is what would catch a driver that stops going through
  * `providerVendorError`/`providerHttpError` and attaches one directly.
  * `packages/sdk/src/provider/__tests__/errors.test.ts` pins the same thing
- * against this shared function directly. See `docs/conventions/index.md`.
+ * against this shared function directly. See "index".
  *
  * `name` is checked too, because AWS models its failures as distinct classes
  * (`ThrottlingException`, `ValidationException`, `AccessDeniedException`) rather