@namzu/sdk 63.0.0 → 64.0.0

package/src/public-runtime.ts

@@ -697,8 +697,13 @@ export {
 
 export {
 	attachShellHooks,
+	boundCompactionSummary,
 	boundHookContext,
 	boundHookReplacement,
+	boundLastAssistantMessage,
+	compactionHookInstructions,
+	MAX_COMPACTION_SUMMARY_HOOK_CHARS,
+	MAX_LAST_MESSAGE_HOOK_CHARS,
 	createShellHook,
 	DEFAULT_SHELL_HOOK_TIMEOUT_MS,
 	definePlugin,
@@ -716,8 +721,13 @@ export {
 	PluginResolver,
 	runShellHook,
 	SHELL_HOOK_EVENTS,
+	SHELL_HOOK_PASCAL_EVENT_NAMES,
+	SHELL_HOOK_WRITTEN_TOOL_NAMES,
 	SHELL_HOOKS_PLUGIN_ID,
+	shellHookToolName,
 	shellHookIfMatches,
+	shellHookIfProblem,
+	shellHookMatcherProblem,
 	shellHookMatches,
 	shellHookVerdict,
 } from './plugin/index.js'
@@ -1343,6 +1353,7 @@ export { assertTaskStatus, isTerminalTaskStatus } from './types/task/index.js'
 // offer "compact this conversation", could not shrink an idle session
 // between turns, and could not collapse a span it had chosen.
 export { compactNow, compactRegion } from './compaction/manual.js'
+export { CompactionRefusedError } from './compaction/hooks.js'
 // A host persisting manual compaction has to recognise the system message on
 // resume. Export the identity predicate rather than making every host copy the
 // marker string and eventually disagree with the writer.
@@ -1380,6 +1391,7 @@ export { isWorkingMemoryMessage } from './runtime/query/iteration/phases/working
 // `any` — and the first host to try (`@namzu/cli`'s `/compact`) did exactly
 // that before this line existed.
 export type { CompactNowInput, CompactionResult } from './compaction/manual.js'
+export type { CompactionHookHost, ManualCompactionHooks } from './compaction/hooks.js'
 export type {
 	CompactionSummaryRoute,
 	CompactionSummaryRouter,

package/src/public-types.ts

@@ -242,12 +242,14 @@ export type {
 	ShellHookHandler,
 	ShellHookJudge,
 	ShellHookOnFailure,
+	ShellHookCall,
 	ShellHookInput,
 	ShellHookOptions,
 	ShellHookPathFilter,
 	ShellHookOutcome,
 	ShellHooksConfig,
 } from './plugin/shell-hook.js'
+export type { ShellHookToolNames } from './plugin/shell-hook-tool-names.js'
 
 export type {
 	PlanApprovalHandler,

package/src/runtime/query/compact-session.ts

@@ -1,3 +1,4 @@
+import type { ManualCompactionHooks } from '../../compaction/hooks.js'
 import {
 	type CompactNowInput,
 	type CompactionResult,
@@ -13,8 +14,14 @@ import { generateMessageId } from '../../utils/id.js'
 import { type SessionLocatorOptions, locateSessionLog, withSessionLease } from './abandon-turn.js'
 
 /** A compaction a host asks for between turns. */
-export interface CompactSessionParams extends Omit<CompactNowInput, 'messages' | 'onShed'> {
+export interface CompactSessionParams
+	extends Omit<CompactNowInput, 'messages' | 'onShed' | 'hooks'> {
 	readonly sessionId: SessionId
+	/**
+	 * Fire `pre_compact` and `post_compact` around the pass. The session and
+	 * the trigger are this call's own. See {@link CompactNowInput.hooks}.
+	 */
+	readonly hooks?: Omit<ManualCompactionHooks, 'sessionId' | 'trigger'>
 	/**
 	 * Who asked. `'manual'` (the default) is a person's request; `'idle'` is a
 	 * host compacting a conversation nobody is using before its prompt cache
@@ -37,7 +44,7 @@ export interface CompactSessionParams extends Omit<CompactNowInput, 'messages' |
 export async function compactSession(
 	params: CompactSessionParams,
 ): Promise<CompactionResult | null> {
-	const { sessionId, locator = {}, trigger = 'manual', ...input } = params
+	const { sessionId, locator = {}, trigger = 'manual', hooks, ...input } = params
 	const log = await locateSessionLog(sessionId, locator)
 	return withSessionLease(log, locator.lease, async (lease) => {
 		const active = await log.activeTurn({ lease })
@@ -47,7 +54,11 @@ export async function compactSession(
 		const history = await readFoldedHistory(log)
 		const ids = new Map<Message, MessageId>()
 		for (const entry of history) if (entry.messageId) ids.set(entry.message, entry.messageId)
-		const result = await compactNow({ ...input, messages: history.map((entry) => entry.message) })
+		const result = await compactNow({
+			...input,
+			messages: history.map((entry) => entry.message),
+			...(hooks ? { hooks: { ...hooks, sessionId, trigger } } : {}),
+		})
 		if (!result) return null
 		const head = await log.head()
 		if (!head) {
@@ -105,7 +116,7 @@ export interface CompactSessionRangeParams extends CompactSessionParams {
 export async function compactSessionRange(
 	params: CompactSessionRangeParams,
 ): Promise<CompactionResult | null> {
-	const { sessionId, locator = {}, from, until, ...input } = params
+	const { sessionId, locator = {}, from, until, hooks, ...input } = params
 	const log = await locateSessionLog(sessionId, locator)
 	return withSessionLease(log, locator.lease, async (lease) => {
 		const active = await log.activeTurn({ lease })
@@ -134,6 +145,7 @@ export async function compactSessionRange(
 			messages: history.map((entry) => entry.message),
 			start,
 			end,
+			...(hooks ? { hooks: { ...hooks, sessionId, trigger: 'manual' as const } } : {}),
 		})
 		if (!result) return null
 		const head = await log.head()

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

@@ -78,6 +78,7 @@ export async function runPreToolHook(
 	toolName: string,
 	input: unknown,
 	signal: AbortSignal = host.config.abortSignal,
+	toolCallId?: string,
 ): Promise<PreToolHookOutcome> {
 	signal.throwIfAborted()
 	if (!host.config.pluginManager) return { kind: 'continue', input, modified: false }
@@ -88,6 +89,7 @@ export async function runPreToolHook(
 				sessionId: host.config.sessionId,
 				turnId: host.config.turnId,
 				toolName,
+				...(toolCallId !== undefined ? { toolCallId } : {}),
 				toolInput: input,
 				signal,
 			},
@@ -155,7 +157,7 @@ export async function prepareDirectCall(
 					: {}),
 			}
 		}
-		const preOutcome = await runPreToolHook(host, toolName, resolved.input)
+		const preOutcome = await runPreToolHook(host, toolName, resolved.input, undefined, toolCall.id)
 		if (preOutcome.kind === 'skip' || preOutcome.kind === 'error') {
 			return {
 				kind: 'synthetic',
@@ -297,7 +299,13 @@ export async function prepareDirectCall(
 		}
 	}
 
-	const preOutcome = await runPreToolHook(host, toolName, preparation.prepared.input)
+	const preOutcome = await runPreToolHook(
+		host,
+		toolName,
+		preparation.prepared.input,
+		undefined,
+		toolCall.id,
+	)
 	if (preOutcome.kind === 'skip' || preOutcome.kind === 'error') {
 		return {
 			kind: 'synthetic',

package/src/runtime/query/executor.ts

@@ -63,6 +63,7 @@ import type {
 	ToolDispatchOptions,
 	ToolFacts,
 	ToolHandoff,
+	ToolProgressDetails,
 	ToolResult,
 } from '../../types/tool/index.js'
 import type { RepairToolCall } from '../../types/tool/repair.js'
@@ -272,7 +273,9 @@ function boundedToolProgress(message: string): string {
  * complete useful working set; intermediate states may be replaced.
  */
 class ToolProgressPublisher {
-	private pending: { readonly message: string; readonly fraction?: number } | undefined
+	private pending:
+		| { readonly message: string; readonly fraction?: number; readonly outputLines?: number }
+		| undefined
 	private draining: Promise<void> | null = null
 	private accepting = true
 
@@ -280,15 +283,18 @@ class ToolProgressPublisher {
 		private readonly emitEvent: EmitEvent,
 		private readonly base: Omit<
 			Extract<SessionEventDraft, { type: 'tool_progress' }>,
-			'message' | 'fraction'
+			'message' | 'fraction' | 'outputLines'
 		>,
 	) {}
 
-	report(message: string, fraction?: number): void {
+	report(message: string, fraction?: number, details?: ToolProgressDetails): void {
 		if (!this.accepting) return
 		this.pending = {
 			message,
 			...(fraction !== undefined ? { fraction: Math.min(1, Math.max(0, fraction)) } : {}),
+			...(details?.outputLines !== undefined && Number.isFinite(details.outputLines)
+				? { outputLines: Math.max(0, Math.floor(details.outputLines)) }
+				: {}),
 		}
 		this.startDrain()
 	}
@@ -323,6 +329,7 @@ class ToolProgressPublisher {
 				...this.base,
 				message: boundedToolProgress(update.message),
 				...(update.fraction !== undefined ? { fraction: update.fraction } : {}),
+				...(update.outputLines !== undefined ? { outputLines: update.outputLines } : {}),
 			}).catch(() => {})
 		}
 	}
@@ -605,6 +612,14 @@ export interface ToolCallOutcome {
 	inputFailure?: CompletedToolRecord['inputFailure']
 	/** A pre-tool hook deliberately skipped execution; its receipt is not an output candidate. */
 	skipped?: true
+	/**
+	 * The call never ran: the person declined it, a rule refused it, its input
+	 * was refused before it started, or the turn ended first. The outcome record
+	 * does not count it as a call that may have changed files.
+	 */
+	notRun?: true
+	/** The call only started work that goes on after it returned; see `ToolResult.launched`. */
+	launched?: true
 	/** Opt-in execution evidence, never provider content or accepted output. */
 	structuredResultJson?: string
 	/** The tool asked for a person; see `ToolResult.handoff`. */
@@ -1854,7 +1869,8 @@ export class ToolExecutor {
 				// Per-call for the same reason: a pause has to be routed back
 				// to the call that raised it, and a batch can raise several.
 				...(this.config.toolPause ? { requestPause: this.config.toolPause(toolCall.id) } : {}),
-				report: (message: string, fraction?: number) => progress.report(message, fraction),
+				report: (message: string, fraction?: number, details?: ToolProgressDetails) =>
+					progress.report(message, fraction, details),
 			}
 			if (preparedCall) {
 				const cwd = this.preparedBashDirectories.get(preparedCall)
@@ -2347,7 +2363,8 @@ export class ToolExecutor {
 			// ephemeral child id; minting a pause route for `nestedId` makes the
 			// answer impossible to match after process restart. `...context`
 			// intentionally preserves the ancestor route here.
-			report: (message: string, fraction?: number) => progress.report(message, fraction),
+			report: (message: string, fraction?: number, details?: ToolProgressDetails) =>
+				progress.report(message, fraction, details),
 		}
 
 		const nestedCwd = this.preparedBashDirectories.get(preparedCall)
@@ -2773,7 +2790,7 @@ export class ToolExecutor {
 		// block had it discarded here — before the wire mapper that was
 		// built to carry it ever saw it.
 		let result: ToolResult = await this.runOnce(toolName, input, toolContext, prepared)
-		let post = await this.runPostToolHook(toolName, input, result)
+		let post = await this.runPostToolHook(toolName, input, result, toolCall.id)
 
 		// In-loop retry. A transient failure used to cost a full model round
 		// trip: the error went back as a `tool_result`, the model read it and
@@ -2856,7 +2873,7 @@ export class ToolExecutor {
 				break
 			}
 			result = await this.runOnce(toolName, input, toolContext, prepared)
-			post = await this.runPostToolHook(toolName, input, result)
+			post = await this.runPostToolHook(toolName, input, result, toolCall.id)
 		}
 		const durationMs = Date.now() - startMs
 
@@ -3113,6 +3130,7 @@ export class ToolExecutor {
 			...(result.handoff !== undefined && !this.config.abortSignal.aborted
 				? { handoff: result.handoff }
 				: {}),
+			...(result.launched === true && !effectiveIsError ? { launched: true as const } : {}),
 			...(revealedTools !== undefined ? { revealedTools } : {}),
 			...(result.facts !== undefined && !postOverride ? { facts: result.facts } : {}),
 		}
@@ -3497,6 +3515,7 @@ export class ToolExecutor {
 		toolName: string,
 		input: unknown,
 		toolResult: ToolResult,
+		toolCallId?: string,
 	): Promise<{
 		override: PostToolOverride | null
 		retry: boolean
@@ -3511,6 +3530,7 @@ export class ToolExecutor {
 					sessionId: this.config.sessionId,
 					turnId: this.config.turnId,
 					toolName,
+					...(toolCallId !== undefined ? { toolCallId } : {}),
 					toolInput: input,
 					toolResult,
 					signal: this.config.abortSignal,
@@ -3529,6 +3549,7 @@ export class ToolExecutor {
 							sessionId: this.config.sessionId,
 							turnId: this.config.turnId,
 							toolName,
+							...(toolCallId !== undefined ? { toolCallId } : {}),
 							toolInput: input,
 							toolResult,
 							signal: this.config.abortSignal,
@@ -3671,7 +3692,7 @@ export class ToolExecutor {
 			isError: true,
 		})
 
-		return { toolCallId: toolCall.id, toolName, output, isError: true }
+		return { toolCallId: toolCall.id, toolName, output, isError: true, notRun: true }
 	}
 
 	/**
@@ -3722,6 +3743,7 @@ export class ToolExecutor {
 		const reason = abortReasonText(this.config.abortSignal.reason)
 		return this.recordSyntheticHookOutcome(toolCallId, toolName, input, {
 			kind: 'error',
+			notRun: true,
 			output: `Tool "${toolName}" was not started because the turn was cancelled${reason ? `: ${reason}` : '.'}`,
 		})
 	}
@@ -3735,6 +3757,7 @@ export class ToolExecutor {
 			output: string
 			inputFailure?: ToolCallOutcome['inputFailure']
 			skipped?: true
+			notRun?: true
 			facts?: ToolFacts
 		},
 	): Promise<ToolCallOutcome> {
@@ -3779,12 +3802,14 @@ export class ToolExecutor {
 			...(outcome.facts ? { facts: outcome.facts } : {}),
 			...(outcome.inputFailure ? { inputFailure: outcome.inputFailure } : {}),
 			...(outcome.skipped ? { skipped: true as const } : {}),
+			...(outcome.notRun ? { notRun: true as const } : {}),
 		}
 	}
 
 	private recordSyntheticPreparation(call: Extract<PreparedDirectCall, { kind: 'synthetic' }>) {
 		return this.recordSyntheticHookOutcome(call.toolCall.id, call.toolName, call.input, {
 			kind: call.isError ? 'error' : 'skip',
+			...(call.isError ? { notRun: true as const } : {}),
 			output: call.message,
 			...(call.facts ? { facts: call.facts } : {}),
 			...(call.inputFailure ? { inputFailure: call.inputFailure } : {}),

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

@@ -8,7 +8,7 @@ import type { TurnContext } from './context.js'
 import type { EventTranslator } from './events.js'
 import { runOutputGuardrails } from './guardrails.js'
 import type { QueryParams } from './index.js'
-import { applyLifecycleHookResults } from './plugin-hooks.js'
+import { applyLifecycleHookResults, lastAssistantMessageField } from './plugin-hooks.js'
 import type { ResultAssembler } from './result.js'
 
 /**
@@ -86,7 +86,12 @@ export async function* finalizeTurn(
 	if (params.pluginManager && finalization.turnEndHooksFired?.() !== true) {
 		const hookResults = await params.pluginManager.executeHooks(
 			'turn_end',
-			{ sessionId: ctx.sessionId, turnId: ctx.turnId, signal: ctx.abortController.signal },
+			{
+				sessionId: ctx.sessionId,
+				turnId: ctx.turnId,
+				...lastAssistantMessageField(ctx.recorder.messages),
+				signal: ctx.abortController.signal,
+			},
 			eventTranslator.emitEvent,
 		)
 		applyLifecycleHookResults('turn_end', hookResults)
@@ -100,8 +105,10 @@ export async function* finalizeTurn(
 				{
 					sessionId: ctx.sessionId,
 					turnId: ctx.turnId,
+					...lastAssistantMessageField(ctx.recorder.messages),
 					parentSessionId: params.parentSessionId,
 					...(params.parentTurnId !== undefined ? { parentTurnId: params.parentTurnId } : {}),
+					agentType: params.agentType ?? params.agentName,
 					signal: ctx.abortController.signal,
 				},
 				eventTranslator.emitEvent,

package/src/runtime/query/iteration/index.ts

@@ -70,7 +70,7 @@ import { SandboxAcquisitionStopped } from '../deferred-sandbox.js'
 import { deliverDurableInbound } from '../durable-inbound.js'
 import type { ToolCallOutcome } from '../executor.js'
 import { projectObservationContext } from '../observation-context.js'
-import { applyLifecycleHookResults } from '../plugin-hooks.js'
+import { applyLifecycleHookResults, lastAssistantMessageField } from '../plugin-hooks.js'
 import {
 	type RequestContextSnapshot,
 	diffRequestContext,
@@ -419,6 +419,7 @@ export class IterationOrchestrator {
 					sessionId: recorder.sessionId,
 					turnId: recorder.turnId,
 					...extra,
+					...lastAssistantMessageField(recorder.messages),
 					...(this.stopHookActive ? { stopHookActive: true } : {}),
 					signal: this.ctx.abortController.signal,
 				},
@@ -3505,6 +3506,8 @@ export class IterationOrchestrator {
 					input,
 					isError: result.isError,
 					...(result.skipped ? { skipped: true } : {}),
+					...(result.notRun ? { notRun: true } : {}),
+					...(result.launched ? { launched: true } : {}),
 					readOnly: this.lookedOnly(result.toolName, input),
 					...(result.facts ? { facts: result.facts } : {}),
 				}

package/src/runtime/query/iteration/phases/compaction.ts

@@ -3,6 +3,7 @@ import {
 	resolveTriggerThreshold,
 } from '../../../../compaction/context-window.js'
 import { findDanglingMessages } from '../../../../compaction/dangling.js'
+import { askPreCompact, postCompactSummary } from '../../../../compaction/hooks.js'
 import {
 	LOADED_SKILLS_ENTRY_KEY,
 	type RenderedSkills,
@@ -781,6 +782,10 @@ async function recordShed(
 interface CompactionPass {
 	attempted: boolean
 	reason: 'threshold' | 'overflow'
+	/** What the `pre_compact` hooks said the summary should keep. */
+	hookInstructions?: string
+	/** The summary the pass installed, for `post_compact`. */
+	summary?: string
 	tokensBefore: number
 	contextWindowTokens: number
 }
@@ -807,9 +812,11 @@ export async function runCompactionCheck(
 					iteration: ctx.recorder.currentIteration,
 					compaction: {
 						reason: pass.reason,
+						trigger: 'auto',
 						tokensBefore: pass.tokensBefore,
 						tokensAfter: estimateTokens(ctx),
 						contextWindowTokens: pass.contextWindowTokens,
+						...postCompactSummary(pass.summary),
 					},
 					signal: ctx.abortController.signal,
 				},
@@ -903,24 +910,29 @@ async function runCompactionCheckInner(
 	pass.tokensBefore = estimatedTokens
 	pass.contextWindowTokens = budget
 	if (ctx.pluginManager) {
-		const results = await ctx.pluginManager.executeHooks(
-			'pre_compact',
+		const answer = await askPreCompact(
+			ctx.pluginManager,
 			{
 				sessionId: ctx.recorder.sessionId,
 				turnId: ctx.recorder.turnId,
 				iteration: ctx.recorder.currentIteration,
-				compaction: {
-					reason: pass.reason,
-					tokensBefore: estimatedTokens,
-					contextWindowTokens: budget,
-				},
 				signal: ctx.abortController.signal,
+				emitEvent: ctx.emitEvent,
+			},
+			{
+				reason: pass.reason,
+				trigger: 'auto',
+				instructions: null,
+				tokensBefore: estimatedTokens,
+				contextWindowTokens: budget,
 			},
-			ctx.emitEvent,
 		)
-		applyLifecycleHookResults('pre_compact', results)
-		const refusal = results.find((result) => result.action === 'skip')
-		if (refusal?.action === 'skip') {
+		// What the hooks said the summary should keep is heard even when a
+		// forced pass overrides a refusal. A reducer or the extracted state
+		// alone has no place for it (see `docs/sdk/hooks.md`).
+		if (answer.instructions !== undefined) pass.hookInstructions = answer.instructions
+		const refusal = answer.refusal !== undefined ? { reason: answer.refusal } : undefined
+		if (refusal) {
 			// A threshold pass is the context's own housekeeping and a hook may
 			// postpone it. A forced pass runs because the provider rejected the
 			// prompt: a context it will reject is not something a hook may insist
@@ -1130,6 +1142,7 @@ async function runCompactionCheckInner(
 				olderMessages,
 				previousSummaries: replaceableSummaries(systemMessages),
 				config,
+				...(pass.hookInstructions !== undefined ? { hookInstructions: pass.hookInstructions } : {}),
 				resolveRoute: async (signal) => {
 					const route = await ctx.compactionSummaryRoute?.(signal)
 					if (route) {
@@ -1162,7 +1175,10 @@ async function runCompactionCheckInner(
 
 	if (modelWritten !== undefined) {
 		compactedContent = modelWritten
-	} else if (config.llmVerification && manager.slotCount() < config.richStateThreshold) {
+	} else if (
+		pass.hookInstructions !== undefined ||
+		(config.llmVerification && manager.slotCount() < config.richStateThreshold)
+	) {
 		// Named once and used twice on purpose. The model the summariser is
 		// asked for is also the model its tokens are priced at, and computing
 		// the two separately is how they drift — a router that sends compaction
@@ -1188,6 +1204,8 @@ async function runCompactionCheckInner(
 				// was added, and nothing ever consulted it.
 				compactionModel,
 				ctx.abortController.signal,
+				undefined,
+				pass.hookInstructions,
 			)
 		} catch (error) {
 			// The model step only ADDS to the extracted state, so a failed one (a
@@ -1308,6 +1326,7 @@ async function runCompactionCheckInner(
 	await recordShed(ctx, [...live], newMessages, options?.force ? 'overflow' : 'threshold')
 
 	installMessages(live, newMessages)
+	pass.summary = compactedContent
 
 	const newEstimate = estimateTokens(ctx)
 

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

@@ -318,6 +318,7 @@ export async function* runToolReview(
 						sessionId: ctx.recorder.sessionId,
 						turnId: ctx.recorder.turnId,
 						toolName: summary.name,
+						toolCallId: summary.id,
 						toolInput: summary.input,
 						reason,
 						signal: ctx.abortController.signal,
@@ -854,6 +855,7 @@ export async function* runToolReview(
 					sessionId: ctx.recorder.sessionId,
 					turnId: ctx.recorder.turnId,
 					toolName: tc.name,
+					toolCallId: tc.id,
 					toolInput: tc.input,
 					signal: ctx.abortController.signal,
 				},

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

@@ -1,5 +1,31 @@
+import { boundLastAssistantMessage } from '../../plugin/hook-context.js'
 import { NamzuError } from '../../types/errors/index.js'
+import type { Message } from '../../types/message/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../../types/plugin/index.js'
+import { isOperatorUserMessage } from './steering.js'
+
+/**
+ * The model's last message of the turn, as a `turn_end` or `subagent_stop`
+ * hook receives it: the text of the last assistant message after the
+ * operator's latest prompt, bounded. A message that carries only tool calls,
+ * a turn that stopped before the model wrote anything, and a turn with no
+ * assistant message yet all give `undefined`: the field is then absent, and a
+ * hook never gets an earlier turn's words or an earlier step's narration in
+ * its place.
+ */
+export function lastAssistantMessageField(messages: readonly Message[]): {
+	lastAssistantMessage?: string
+} {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index]
+		if (!message) continue
+		if (isOperatorUserMessage(message)) return {}
+		if (message.role !== 'assistant') continue
+		const text = boundLastAssistantMessage(message.content)
+		return text === undefined ? {} : { lastAssistantMessage: text }
+	}
+	return {}
+}
 
 /**
  * Interpret hook results from non-tool lifecycle events (run_start, run_end,
@@ -19,9 +45,13 @@ export function applyLifecycleHookResults(
 			case 'continue':
 				continue
 			case 'annotate':
-				if (event !== 'user_prompt_submit' && event !== 'subagent_start') {
+				if (
+					event !== 'user_prompt_submit' &&
+					event !== 'subagent_start' &&
+					event !== 'pre_compact'
+				) {
 					throw new Error(
-						`Plugin hook ${event} returned 'annotate', which only user_prompt_submit and subagent_start accept`,
+						`Plugin hook ${event} returned 'annotate', which only user_prompt_submit, subagent_start and pre_compact accept`,
 					)
 				}
 				if (result.text.trim().length > 0) annotations.push(result.text.trim())

package/src/runtime/query/turn/outcome-ledger.ts

@@ -36,6 +36,10 @@ export interface OutcomeCall {
 	readonly isError?: boolean
 	/** A hook stopped it before it ran. */
 	readonly skipped?: boolean
+	/** It never ran: declined by the person, refused by a rule or by its own input, or the turn ended first. */
+	readonly notRun?: boolean
+	/** It only started work that goes on after it returned; the call itself changed nothing. */
+	readonly launched?: boolean
 	/** The tool declared this call read-only (or it only keeps the task list). */
 	readonly readOnly?: boolean
 	/** What the call did, as typed fields. Absent when a hook replaced the output. */
@@ -393,7 +397,8 @@ export class OutcomeLedger {
 		// answers for exactly the state they left.
 		let pending: CheckState[] = []
 		for (const call of calls) {
-			if (call.skipped === true) continue
+			// A call that did not run, or only started work elsewhere, changed nothing here.
+			if (call.skipped === true || call.notRun === true || call.launched === true) continue
 			const written = WRITING_TOOLS.has(call.toolName)
 			if (written && call.isError !== true) {
 				if (call.facts?.kind === 'write' && call.facts.operation === 'unchanged') continue

package/src/tools/builtins/bash.ts

@@ -205,14 +205,26 @@ function progressLine(value: string): string {
  * Reports stay synchronous: the executor owns coalescing and backpressure.
  * This projection adds neither an output log nor a queue of pending reports.
  */
-function shellProgress(report?: (message: string) => void) {
+function shellProgress(
+	report?: (
+		message: string,
+		fraction?: number,
+		details?: { readonly outputLines?: number },
+	) => void,
+) {
 	if (!report) return undefined
 	const partial = { stdout: '', stderr: '' }
 	let lastMessage = ''
+	// Lines of output so far, both streams: every line feed seen. Counted here, on
+	// every chunk, because the reports below are coalesced and a viewer counting
+	// the messages it received would undercount a fast command.
+	let outputLines = 0
+	let lastLines = 0
 	return ({ stream, data }: { stream: 'stdout' | 'stderr'; data: string }): void => {
 		let line = partial[stream]
 		let latest = ''
 		let start = 0
+		for (let at = data.indexOf('\n'); at >= 0; at = data.indexOf('\n', at + 1)) outputLines++
 		// Scan delimiters without allocating an array for arbitrarily chatty output.
 		for (const match of data.matchAll(/[\r\n]/g)) {
 			line = appendProgressTail(line, data, start, match.index)
@@ -223,10 +235,11 @@ function shellProgress(report?: (message: string) => void) {
 		line = appendProgressTail(line, data, start, data.length)
 		partial[stream] = line
 		const message = progressLine(line) || latest
-		if (!message || message === lastMessage) return
+		if (!message || (message === lastMessage && outputLines === lastLines)) return
 		lastMessage = message
+		lastLines = outputLines
 		try {
-			report(message)
+			report(message, undefined, { outputLines })
 		} catch {
 			// A diagnostic observer cannot break the process output reader.
 		}

package/src/tools/coordinator/index.ts

@@ -791,6 +791,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 						plan_task_id: resolvedPlanTaskId,
 						background: true,
 					},
+					launched: true,
 				}
 			}
 

package/src/types/agent/query.ts

@@ -25,6 +25,15 @@ export interface QueryAgentConfig extends BaseAgentConfig {
 
 	persona?: AgentPersona
 
+	/**
+	 * The name lifecycle hooks see for this agent (`agentType` on
+	 * `subagent_start` and `subagent_stop`, `agent_type` for a shell hook).
+	 * Absent, it is the agent's `type`, which for a host-defined class is the
+	 * class's marker rather than the agent's name: a host that names its
+	 * agents passes the name here.
+	 */
+	agentType?: string
+
 	/**
 	 * Channel a host uses to hand guidance to this turn's current turn.
 	 *