@namzu/sdk 62.15.0 → 63.0.0

package/src/plugin/shell-hook.ts

@@ -22,7 +22,10 @@
  * `permission_mode`. The Namzu names stay, so no existing script changes.
  * The same facts go out as
  * same facts as `NAMZU_HOOK_EVENT`, `NAMZU_SESSION_ID`, `NAMZU_TURN_ID`,
- * `NAMZU_TOOL_NAME` and, when the input names a file, `NAMZU_TOOL_PATH`.
+ * `NAMZU_TOOL_NAME` and, when the input names a file, `NAMZU_TOOL_PATH`;
+ * `NAMZU_PROJECT_DIR` is the folder the session was started for.
+ * `session_start` also sends `source` (`startup` or `resume`) and `session_end`
+ * `reason` (`exit` or `replaced`).
  *
  * `session_start` and `session_end` run outside any turn, so they carry no
  * `turn_id` on stdin and no `NAMZU_TURN_ID` in the environment — not even
@@ -32,8 +35,8 @@
  * Its answer is the exit code and, on exit `0`, an optional JSON object on
  * stdout. The exit codes:
  *
- * - `0` — carry on. On `user_prompt_submit`, plain (non-JSON) stdout becomes
- *   context for the model.
+ * - `0` — carry on. On `user_prompt_submit`, `subagent_start` and
+ *   `session_start`, plain (non-JSON) stdout becomes context for the model.
  * - `2` — **block**, read per event: 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 `user_prompt_submit` the turn ends; on `turn_end` and `subagent_stop`
@@ -68,7 +71,9 @@
  *   `permissionDecisionReason`, `updatedInput` and `additionalContext` for
  *   `pre_tool_use`; `additionalContext` for `user_prompt_submit`,
  *   `post_tool_use`, `post_tool_use_failure`, `turn_end`, `subagent_stop`,
- *   `session_start`, `notification`; and for `permission_request` a `decision`
+ *   `session_start` (context for the whole session), `notification`;
+ *   `updatedToolOutput` for `post_tool_use` (the text the model reads instead
+ *   of the tool's result); and for `permission_request` a `decision`
  *   `{ behavior: "allow" }` or `{ behavior: "deny", message, interrupt }`.
  *
  * ## What a hook may decide, and what it may not
@@ -123,6 +128,7 @@ import { RENAMED_PLUGIN_HOOK_EVENTS } 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 { boundHookReplacement } from './hook-context.js'
 import type { PluginLifecycleManager } from './lifecycle.js'
 import { postHookJson } from './shell-hook-http.js'
 
@@ -181,8 +187,10 @@ interface ShellHookEntryBase {
 	 * What this applies to. On a tool event (and `permission_request`) the tool
 	 * name; on `notification` the notification type. `*` or absent matches
 	 * everything; a list of names (`a|b`, `a,b`, each optionally ending in `*`
-	 * as a prefix) matches those; anything else is a regular expression tested
-	 * against the name.
+	 * as a prefix) matches those without regard to case, and on a tool event
+	 * also by the names skills write (`Bash`, `Edit`); anything else is a
+	 * regular expression tested against the name (and, on a tool event, the
+	 * names skills write for that tool).
 	 */
 	readonly matcher?: string
 	/** Deadline in milliseconds; default `DEFAULT_SHELL_HOOK_TIMEOUT_MS`, capped at `MAX_SHELL_HOOK_TIMEOUT_MS`. */
@@ -202,10 +210,19 @@ interface ShellHookEntryBase {
 	 * What the hook's own failure does: it could not start, it timed out, it
 	 * exited with a code other than `0` or `2`, or it printed JSON that is not
 	 * valid. `continue` (the default) reports it and lets the action go ahead;
-	 * `block` counts it as exit `2`, so the action the event guards is refused.
+	 * `block` counts it as exit `2`, so the action the event guards is refused;
+	 * on `post_tool_use` and `post_tool_use_failure`, where the call has already
+	 * run, it withholds the result from the model instead (set it on a hook that
+	 * redacts).
 	 * Not read on a `prompt` hook or an `async` command.
 	 */
 	readonly onFailure?: ShellHookOnFailure
+	/**
+	 * Where the entry was declared, as a label a host shows (a file's path).
+	 * It has no effect on how the hook runs, and two entries that differ only
+	 * here are the same entry.
+	 */
+	readonly source?: string
 }
 
 /** One shell command at one event. */
@@ -269,6 +286,51 @@ export const MAX_SHELL_HOOK_TIMEOUT_MS = 10 * 60_000
 /** Captured output bound per stream. */
 const MAX_CAPTURE_BYTES = 64 * 1024
 
+/**
+ * How a skill writes each name in `SKILL_TOOL_NAME_ALIASES` (the alias table
+ * is keyed lower-case). A regular-expression matcher is also tested against
+ * these, so `^(Edit|Write)$` written for those names still fires.
+ */
+const WRITTEN_TOOL_NAMES: Readonly<Record<string, string>> = Object.freeze({
+	read: 'Read',
+	write: 'Write',
+	edit: 'Edit',
+	multiedit: 'MultiEdit',
+	bash: 'Bash',
+	grep: 'Grep',
+	glob: 'Glob',
+	ls: 'LS',
+	webfetch: 'WebFetch',
+	websearch: 'WebSearch',
+	skill: 'Skill',
+	askuserquestion: 'AskUserQuestion',
+	task: 'Task',
+	agent: 'Agent',
+	lsp: 'LSP',
+	toolsearch: 'ToolSearch',
+	bashoutput: 'BashOutput',
+	taskoutput: 'TaskOutput',
+	killshell: 'KillShell',
+	killbash: 'KillBash',
+	taskstop: 'TaskStop',
+	taskcreate: 'TaskCreate',
+	taskupdate: 'TaskUpdate',
+	tasklist: 'TaskList',
+})
+
+/** The names a skill writes for the tool called `toolName` here. */
+function writtenNamesFor(toolName: string): string[] {
+	const lower = toolName.toLowerCase()
+	const names: string[] = []
+	for (const [written, tool] of Object.entries(SKILL_TOOL_NAME_ALIASES)) {
+		if (tool !== lower) continue
+		names.push(written)
+		const spelled = WRITTEN_TOOL_NAMES[written]
+		if (spelled !== undefined) names.push(spelled)
+	}
+	return names
+}
+
 /**
  * `matcher` against a name (a tool's, or a notification's type).
  *
@@ -276,25 +338,55 @@ const MAX_CAPTURE_BYTES = 64 * 1024
  * matches exactly, each part optionally ending in `*` as a prefix (the
  * spelling this adapter has always taken). Anything else is a regular
  * expression, tested unanchored against the name; one that does not compile
- * matches nothing. Case-sensitive, because tool names are. A matcher on an
- * event that has no name (`turn_start`) matches nothing unless it is `*`.
+ * matches nothing. A matcher on an event that has no name (`turn_start`)
+ * matches nothing unless it is `*`.
+ *
+ * Names in a list compare without regard to case. With `tool: true` (the
+ * event's name is a tool: the tool events and `permission_request`) they also
+ * take the names skills write, the way an entry's `if` does: `Bash` matches
+ * the tool `bash`, `MultiEdit` matches `edit`, and a prefix such as `Web*`
+ * matches `web_fetch` by its written name too. Where the name is not a tool
+ * (a notification's type, an agent's name, a session's `source` or `reason`)
+ * no tool alias applies, since those words are not tool names; case is still
+ * ignored there, because a guard that silently never runs over a capital
+ * letter is worse than one that also runs for a name differing only in case.
+ *
+ * A list part ending in `.*` is also tried as a regular expression.
+ *
+ * A regular expression is tested, case-sensitively as written, against the
+ * real name and, with `tool: true`, against each name skills write for that
+ * tool, so one written for those names still fires. It never matches less
+ * than it did against the real name alone.
  */
 export function shellHookMatches(
 	matcher: string | undefined,
 	toolName: string | undefined,
+	options: { readonly tool?: boolean } = {},
 ): boolean {
 	if (matcher === undefined || matcher.trim() === '' || matcher.trim() === '*') return true
 	if (toolName === undefined) return false
+	const tool = options.tool === true
 	const parts = matcher.split(/[|,]/).map((part) => part.trim())
 	if (parts.every((part) => /^[A-Za-z0-9_.:-]+\*?$/.test(part))) {
-		return parts.some((candidate) =>
-			candidate.endsWith('*')
-				? toolName.startsWith(candidate.slice(0, -1))
-				: toolName === candidate,
-		)
+		const subject = toolName.toLowerCase()
+		const listed = parts.some((candidate) => {
+			const prefix = candidate.endsWith('*')
+			const written = (prefix ? candidate.slice(0, -1) : candidate).toLowerCase()
+			const spellings = [written]
+			if (tool) {
+				const alias = SKILL_TOOL_NAME_ALIASES[written]
+				if (alias !== undefined) spellings.push(alias)
+			}
+			return spellings.some((name) => (prefix ? subject.startsWith(name) : subject === name))
+		})
+		// `Bash.*` reads as the prefix `bash.` above, which no tool has. A part
+		// ending in `.*` is also a regular expression, so it is tried as one.
+		if (listed || !matcher.includes('.*')) return listed
 	}
 	try {
-		return new RegExp(matcher).test(toolName)
+		const expression = new RegExp(matcher)
+		if (expression.test(toolName)) return true
+		return tool && writtenNamesFor(toolName).some((name) => expression.test(name))
 	} catch {
 		return false
 	}
@@ -311,6 +403,7 @@ export function shellHookIfMatches(
 	filter: string | undefined,
 	toolName: string | undefined,
 	toolInput: unknown,
+	pathFilter?: ShellHookPathFilter,
 ): boolean {
 	if (filter === undefined || filter.trim() === '') return true
 	if (toolName === undefined) return true
@@ -318,10 +411,17 @@ export function shellHookIfMatches(
 	if (!shape) return true
 	const written = (shape[1] ?? '').toLowerCase()
 	const tool = SKILL_TOOL_NAME_ALIASES[written] ?? written
-	if (tool !== toolName.toLowerCase()) return false
 	const specifier = shape[2]?.trim()
-	if (specifier === undefined || specifier === '' || specifier.replaceAll('*', '') === '')
-		return true
+	const hasPattern =
+		specifier !== undefined && specifier !== '' && specifier.replaceAll('*', '') !== ''
+	// A path pattern is the permission rules' own: the host that has them says
+	// whether this call's path is named. It decides for the tools it knows.
+	if (hasPattern && pathFilter !== undefined) {
+		const answer = pathFilter(tool, specifier, toolName, toolInput)
+		if (answer !== undefined) return answer
+	}
+	if (tool !== toolName.toLowerCase()) return false
+	if (!hasPattern) return true
 	if (tool !== 'bash') return true
 	const line =
 		toolInput !== null && typeof toolInput === 'object'
@@ -345,12 +445,28 @@ export function shellHookIfMatches(
 	}
 }
 
+/**
+ * A host's reading of a path pattern in a hook's `if`: whether the call's path
+ * is named by `pattern` the way the host's permission rules read it. `tool` is
+ * the filter's tool (`edit`, `read`), `callTool` the tool being called.
+ * `undefined` means the host does not read this tool's paths, and the
+ * filter is then read as it is for any other tool.
+ */
+export type ShellHookPathFilter = (
+	tool: string,
+	pattern: string,
+	callTool: string,
+	toolInput: unknown,
+) => boolean | undefined
+
 /** 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 hook printed more on stdout than is kept (`MAX_CAPTURE_BYTES`). */
+	readonly stdoutTruncated?: boolean
 	/** Set when the process could not be started at all. */
 	readonly spawnError?: string
 }
@@ -362,6 +478,12 @@ export interface ShellHookInput {
 	readonly sessionId: string
 	/** The turn the hook fired in. Absent on `session_start` and `session_end`. */
 	readonly turnId?: string
+	/** Why the session started, on `session_start`. Sent as `source`. */
+	readonly sessionSource?: string
+	/** Why the session closed, on `session_end`. Sent as `reason`. */
+	readonly endReason?: string
+	/** The folder the session was started for. Sent as `NAMZU_PROJECT_DIR`; absent, `cwd`. */
+	readonly projectDir?: string
 	/** The delegating session, on `subagent_start` and `subagent_stop`. */
 	readonly parentSessionId?: string
 	/** The parent turn whose tool call spawned the child, on `subagent_start` and `subagent_stop`. */
@@ -403,6 +525,7 @@ export function shellHookPayload(input: ShellHookInput): string {
 		...(input.transcriptPath !== undefined ? { transcript_path: input.transcriptPath } : {}),
 		...(input.permissionMode !== undefined ? { permission_mode: input.permissionMode } : {}),
 		...(input.turnId !== undefined ? { turn_id: input.turnId } : {}),
+		...(input.sessionSource !== undefined ? { source: input.sessionSource } : {}),
 		...(input.parentSessionId !== undefined ? { parent_session_id: input.parentSessionId } : {}),
 		...(input.parentTurnId !== undefined ? { parent_turn_id: input.parentTurnId } : {}),
 		...(input.agentType !== undefined
@@ -429,7 +552,11 @@ export function shellHookPayload(input: ShellHookInput): string {
 					})),
 				}
 			: {}),
-		...(input.reason !== undefined ? { reason: input.reason } : {}),
+		...(input.reason !== undefined
+			? { reason: input.reason }
+			: input.endReason !== undefined
+				? { reason: input.endReason }
+				: {}),
 		...(input.event === 'turn_failure' && input.error !== undefined ? { error: input.error } : {}),
 		...(input.notification !== undefined
 			? {
@@ -463,6 +590,7 @@ export function runShellHook(
 				...inherited,
 				NAMZU_HOOK_EVENT: input.event,
 				NAMZU_SESSION_ID: input.sessionId,
+				NAMZU_PROJECT_DIR: input.projectDir ?? input.cwd,
 				...(input.turnId !== undefined ? { NAMZU_TURN_ID: input.turnId } : {}),
 				...(input.toolName !== undefined ? { NAMZU_TOOL_NAME: input.toolName } : {}),
 				...(toolPath !== undefined ? { NAMZU_TOOL_PATH: toolPath } : {}),
@@ -507,17 +635,24 @@ export function runShellHook(
 		}
 		let stdout = ''
 		let stderr = ''
+		let stdoutTruncated = false
 		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)
+		const capture = (current: string, chunk: Buffer): { text: string; cut: boolean } => {
+			if (current.length >= MAX_CAPTURE_BYTES) return { text: current, cut: chunk.length > 0 }
+			const joined = current + chunk.toString('utf8')
+			return {
+				text: joined.slice(0, MAX_CAPTURE_BYTES),
+				cut: joined.length > MAX_CAPTURE_BYTES,
+			}
+		}
 		child.stdout?.on('data', (chunk: Buffer) => {
-			stdout = capture(stdout, chunk)
+			const next = capture(stdout, chunk)
+			stdout = next.text
+			if (next.cut) stdoutTruncated = true
 		})
 		child.stderr?.on('data', (chunk: Buffer) => {
-			stderr = capture(stderr, chunk)
+			stderr = capture(stderr, chunk).text
 		})
 		const finish = (outcome: ShellHookOutcome) => {
 			if (settled) return
@@ -550,11 +685,18 @@ export function runShellHook(
 				timedOut,
 				stdout,
 				stderr,
+				...(stdoutTruncated ? { stdoutTruncated } : {}),
 				spawnError: error.message,
 			})
 		})
 		child.on('close', (code) => {
-			finish({ exitCode: code, timedOut, stdout, stderr })
+			finish({
+				exitCode: code,
+				timedOut,
+				stdout,
+				stderr,
+				...(stdoutTruncated ? { stdoutTruncated } : {}),
+			})
 		})
 		child.on('exit', () => {
 			// After a kill, a survivor that still holds the pipes must not hold
@@ -610,6 +752,8 @@ interface ShellHookReading {
 	context?: string
 	halt?: { reason: string }
 	notice?: string
+	/** Text that replaces a tool's result, on `post_tool_use`. */
+	replacement?: string
 	/** The hook asked for its stdout to stay out of the debug log. */
 	suppressOutput?: boolean
 	/** Why the JSON was set aside, when it was. */
@@ -728,6 +872,12 @@ function readShellHookJson(event: ShellHookEvent, stdout: string): ShellHookRead
 			reading.updatedInput = specific.updatedInput
 		}
 	}
+	if (event === 'post_tool_use' && specific.updatedToolOutput !== undefined) {
+		if (typeof specific.updatedToolOutput !== 'string') {
+			return { invalid: 'hookSpecificOutput: `updatedToolOutput` must be a string' }
+		}
+		reading.replacement = boundHookReplacement(specific.updatedToolOutput)
+	}
 	if (event === 'permission_request') {
 		const decision = specific.decision
 		if (!isRecord(decision)) {
@@ -765,15 +915,30 @@ export function shellHookVerdict(
 	}
 	// A failure of the hook itself is "carry on" unless the entry asked for
 	// it to count as a refusal, which is exit 2 with the failure as the reason.
-	const failed = (reason: string): PluginHookResult =>
-		entry.onFailure === 'block' && entry.type !== 'prompt' && !isAsyncShellHook(entry)
-			? shellHookVerdict(
-					event,
-					{ ...entry, onFailure: 'continue' },
-					{ exitCode: 2, timedOut: false, stdout: '', stderr: `hook failed: ${reason}` },
-					log,
-				)
-			: { action: 'continue' }
+	const failed = (reason: string, shown: string = reason): PluginHookResult => {
+		if (entry.onFailure !== 'block' || entry.type === 'prompt' || isAsyncShellHook(entry)) {
+			return { action: 'continue' }
+		}
+		// The call has run and a refusal cannot undo it, but the hook may have
+		// been the one thing keeping something out of the result (a redaction),
+		// so a failed guard withholds the result instead of passing it on. The
+		// kernel marks the record as it does for any replaced result.
+		if (event === 'post_tool_use' || event === 'post_tool_use_failure') {
+			const line = `A hook guarding this result failed, so the result is not shown (${shown}). The tool call itself has already run.`
+			return {
+				action: 'replace',
+				output: line,
+				content: [{ type: 'text', text: line }],
+				disclose: true,
+			}
+		}
+		return shellHookVerdict(
+			event,
+			{ ...entry, onFailure: 'continue' },
+			{ exitCode: 2, timedOut: false, stdout: '', stderr: `hook failed: ${reason}` },
+			log,
+		)
+	}
 	if (outcome.spawnError !== undefined) {
 		log.warn('hook could not start', {
 			...attrs,
@@ -822,12 +987,20 @@ export function shellHookVerdict(
 
 	// Exit 0.
 	const text = outcome.stdout.trim()
-	const reading = readShellHookJson(event, outcome.stdout)
+	const reading: ShellHookReading | undefined =
+		outcome.stdoutTruncated === true && text.startsWith('{')
+			? {
+					invalid: `answer is too large: the hook printed more than the ${MAX_CAPTURE_BYTES} characters of stdout that are read`,
+				}
+			: readShellHookJson(event, outcome.stdout)
 	if (reading === undefined) {
 		// 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.
-		if ((event === 'user_prompt_submit' || event === 'subagent_start') && text.length > 0)
+		if (
+			(event === 'user_prompt_submit' || event === 'subagent_start' || event === 'session_start') &&
+			text.length > 0
+		)
 			return { action: 'annotate', text }
 		return { action: 'continue' }
 	}
@@ -836,7 +1009,9 @@ export function shellHookVerdict(
 			...attrs,
 			'namzu.hook.problem': reading.invalid,
 		})
-		return failed(reading.invalid)
+		// The parser's own detail can quote a piece of the answer; the line the
+		// model reads keeps only the lead.
+		return failed(reading.invalid, reading.invalid.split(' (')[0])
 	}
 	if (!reading.suppressOutput) {
 		log.debug('hook output', {
@@ -885,11 +1060,34 @@ export function shellHookVerdict(
 			const context = [reading.block, reading.context].filter(Boolean).join('\n')
 			return context.length > 0 ? { action: 'annotate', text: context } : { action: 'continue' }
 		}
+		case 'session_start': {
+			// Nothing here can be refused. What the hook said for the model becomes
+			// the session's context; a stop request and a warning still count.
+			return reading.context !== undefined
+				? { action: 'annotate', text: reading.context }
+				: {
+						action: 'continue',
+						...(reading.halt ? { halt: reading.halt } : {}),
+						...(reading.notice ? { notice: reading.notice } : {}),
+					}
+		}
 		case 'post_tool_use':
 		case 'post_tool_use_failure': {
 			// The call has run, so a "block" cannot undo it: its reason is what the
 			// model is told about the result.
 			const context = [reading.block, reading.context].filter(Boolean).join('\n')
+			// A replacement is the hook's text in place of the tool's: the record
+			// says so beside it (the kernel adds the mark).
+			if (reading.replacement !== undefined) {
+				return {
+					action: 'replace',
+					output: reading.replacement,
+					disclose: true,
+					...(context.length > 0 ? { context } : {}),
+					...(reading.halt ? { halt: reading.halt } : {}),
+					...(reading.notice ? { notice: reading.notice } : {}),
+				}
+			}
 			return {
 				action: 'continue',
 				...(context.length > 0 ? { context } : {}),
@@ -986,6 +1184,28 @@ export interface ShellHookOptions {
 	readonly transcriptPath?: (sessionId: string) => string | undefined
 	/** The permission mode in force now, sent as `permission_mode`. Called at each run. */
 	readonly permissionMode?: () => string | undefined
+	/**
+	 * The folder the session was started for, sent to every command as
+	 * `NAMZU_PROJECT_DIR`. Absent, `cwd`.
+	 */
+	readonly projectDir?: string
+	/** How a path pattern in an entry's `if` is read. Absent, such a filter runs the hook. */
+	readonly pathFilter?: ShellHookPathFilter
+	/**
+	 * A deadline, in milliseconds, for entries of an event that set no
+	 * `timeoutMs` of their own (an entry's own is honoured as written, up to
+	 * the cap). Absent, or an event not listed, the ordinary default applies.
+	 */
+	readonly defaultTimeoutMs?: { readonly [event in ShellHookEvent]?: number }
+	/**
+	 * Called when a hook of this adapter ran out its deadline and was ended.
+	 * `hook` is the command, URL or prompt text the entry names.
+	 */
+	readonly onTimeout?: (info: {
+		readonly event: ShellHookEvent
+		readonly hook: string
+		readonly timeoutMs: number
+	}) => void
 }
 
 /** The deadline for `prompt` hooks when they name none. */
@@ -1087,10 +1307,19 @@ function readJudgement(reply: string): { ok: boolean; reason: string } | undefin
 /** One entry as a hook definition the lifecycle manager accepts. */
 export function createShellHook(
 	event: ShellHookEvent,
-	entry: ShellHookHandler,
+	configured: ShellHookHandler,
 	options: ShellHookOptions,
 ): PluginHookDefinition {
 	const log = options.log ?? NOOP_LOGGER
+	const eventDefault = options.defaultTimeoutMs?.[event]
+	const entry: ShellHookHandler =
+		configured.timeoutMs === undefined && eventDefault !== undefined
+			? { ...configured, timeoutMs: eventDefault }
+			: configured
+	const reportTimeout = (timedOut: boolean): void => {
+		if (!timedOut) return
+		options.onTimeout?.({ event, hook: describeShellHook(entry), timeoutMs: hookTimeout(entry) })
+	}
 	// `once` is per definition, and a definition is per session: the manager
 	// is built for one session and its hooks are attached to it.
 	let spent = false
@@ -1102,14 +1331,26 @@ export function createShellHook(
 		handler: async (context: PluginHookContext) => {
 			if (spent) return { action: 'continue' }
 			// A notification is matched on its type; every other event on the tool.
+			const namesATool = !(
+				event === 'notification' ||
+				event === 'subagent_start' ||
+				event === 'subagent_stop' ||
+				event === 'session_start' ||
+				event === 'session_end'
+			)
 			const subject =
 				event === 'notification'
 					? context.notification?.type
 					: event === 'subagent_start' || event === 'subagent_stop'
 						? context.agentType
-						: context.toolName
-			if (!shellHookMatches(entry.matcher, subject)) return { action: 'continue' }
-			if (!shellHookIfMatches(entry.if, context.toolName, context.toolInput)) {
+						: event === 'session_start'
+							? context.source
+							: event === 'session_end'
+								? context.endReason
+								: context.toolName
+			if (!shellHookMatches(entry.matcher, subject, { tool: namesATool }))
+				return { action: 'continue' }
+			if (!shellHookIfMatches(entry.if, context.toolName, context.toolInput, options.pathFilter)) {
 				return { action: 'continue' }
 			}
 			if (entry.once === true) spent = true
@@ -1118,7 +1359,10 @@ export function createShellHook(
 			const hookInput: ShellHookInput = {
 				event,
 				cwd: options.cwd,
+				...(options.projectDir !== undefined ? { projectDir: options.projectDir } : {}),
 				sessionId: String(context.sessionId),
+				...(context.source !== undefined ? { sessionSource: context.source } : {}),
+				...(context.endReason !== undefined ? { endReason: context.endReason } : {}),
 				...(context.turnId !== undefined ? { turnId: String(context.turnId) } : {}),
 				...(context.parentSessionId !== undefined
 					? { parentSessionId: String(context.parentSessionId) }
@@ -1159,6 +1403,7 @@ export function createShellHook(
 					timeoutMs: hookTimeout(entry),
 					...(context.signal !== undefined ? { signal: context.signal } : {}),
 				})
+				reportTimeout(response.timedOut)
 				const ok = response.status !== null && response.status >= 200 && response.status < 300
 				return shellHookVerdict(
 					event,
@@ -1187,6 +1432,7 @@ export function createShellHook(
 				return { action: 'continue' }
 			}
 			const outcome = await runShellHook(entry, hookInput, context.signal)
+			reportTimeout(outcome.timedOut)
 			return shellHookVerdict(event, entry, outcome, log)
 		},
 	} as PluginHookDefinition

package/src/public-runtime.ts

@@ -697,9 +697,15 @@ export {
 
 export {
 	attachShellHooks,
+	boundHookContext,
+	boundHookReplacement,
 	createShellHook,
 	DEFAULT_SHELL_HOOK_TIMEOUT_MS,
 	definePlugin,
+	frameOperatorHookContext,
+	MAX_HOOK_CONTEXT_CHARS,
+	MAX_HOOK_REPLACEMENT_CHARS,
+	sessionStartHookContext,
 	discoverAllPluginDirs,
 	discoverPlugins,
 	assertEnableable,

package/src/public-types.ts

@@ -244,6 +244,7 @@ export type {
 	ShellHookOnFailure,
 	ShellHookInput,
 	ShellHookOptions,
+	ShellHookPathFilter,
 	ShellHookOutcome,
 	ShellHooksConfig,
 } from './plugin/shell-hook.js'

package/src/runtime/query/executor/tool-call-admission.ts

@@ -1,4 +1,5 @@
 import { GENAI, NAMZU } from '../../../constants/telemetry/index.js'
+import { boundHookContext } from '../../../plugin/hook-context.js'
 import { callableToolNames, formatToolNames } from '../../../registry/tool/callable.js'
 import { renderToolSchema } from '../../../registry/tool/schema.js'
 import type { ToolCall, ToolInputError } from '../../../types/message/index.js'
@@ -433,12 +434,9 @@ function interpretPreToolResults(
  */
 export function hookNote(texts: readonly string[]): string {
 	const joined = texts.join('\n')
-	return `[Hook note]\n${joined.length > MAX_HOOK_NOTE_CHARS ? `${joined.slice(0, MAX_HOOK_NOTE_CHARS)}\n[truncated]` : joined}`
+	return `[Hook note]\n${boundHookContext(joined)}`
 }
 
-/** A hook's text is one more thing for the model to read; it gets a bound. */
-const MAX_HOOK_NOTE_CHARS = 8_000
-
 /**
  * Turn the call the model issued into a name and a parsed input, giving
  * a configured repairer one chance to fix it first.

package/src/runtime/query/executor.ts

@@ -564,8 +564,14 @@ interface PostToolOverride {
 	readonly output: string
 	readonly isError: boolean
 	readonly content?: ToolResultContent
+	/** A hook replaced a result that stood; the record says so beside it. */
+	readonly replacedByHook?: true
 }
 
+/** What the record and the model are told beside a result a hook replaced. */
+export const HOOK_REPLACED_RESULT_NOTE =
+	"A hook replaced this tool result: the text above is the hook's, not the tool's own output."
+
 /** What `pre_tool_use` hooks said about a call beyond running it or not. */
 export interface PreToolHookNotes {
 	/** The strictest permission answer among the hooks: `ask` outranks `allow`. */
@@ -2944,9 +2950,12 @@ export class ToolExecutor {
 		// receipt and the host's alike, framed as a hook's words. Added after
 		// the output budget so a bounded result is never trimmed to make room
 		// for it; the note has its own bound (`hookNote`).
-		const hookTexts = [preparedHookContext, post.context].filter(
-			(text): text is string => text !== undefined && text.length > 0,
-		)
+		// The mark comes first so the bound on hook text never cuts it off.
+		const hookTexts = [
+			postOverride?.replacedByHook === true ? HOOK_REPLACED_RESULT_NOTE : undefined,
+			preparedHookContext,
+			post.context,
+		].filter((text): text is string => text !== undefined && text.length > 0)
 		if (hookTexts.length > 0) {
 			const note = hookNote(hookTexts)
 			output = `${output}\n\n${note}`
@@ -3562,8 +3571,11 @@ export class ToolExecutor {
 					override = {
 						output: result.output,
 						isError: false,
+						...(result.disclose === true ? { replacedByHook: true as const } : {}),
 						...(result.content !== undefined ? { content: result.content } : {}),
 					}
+					if (result.context) contexts.push(result.context)
+					if (result.halt) this.requestHalt(result.halt.reason)
 					continue
 				// `retry` was a declared variant with no implementation: every
 				// site that consumed it threw. Here it finally means something