@namzu/sdk 62.15.0 → 63.1.0

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(() => {})
 		}
 	}
@@ -564,8 +571,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`. */
@@ -599,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`. */
@@ -1848,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)
@@ -2341,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)
@@ -2944,9 +2967,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}`
@@ -3104,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 } : {}),
 		}
@@ -3562,8 +3589,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
@@ -3659,7 +3689,7 @@ export class ToolExecutor {
 			isError: true,
 		})
 
-		return { toolCallId: toolCall.id, toolName, output, isError: true }
+		return { toolCallId: toolCall.id, toolName, output, isError: true, notRun: true }
 	}
 
 	/**
@@ -3710,6 +3740,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}` : '.'}`,
 		})
 	}
@@ -3723,6 +3754,7 @@ export class ToolExecutor {
 			output: string
 			inputFailure?: ToolCallOutcome['inputFailure']
 			skipped?: true
+			notRun?: true
 			facts?: ToolFacts
 		},
 	): Promise<ToolCallOutcome> {
@@ -3767,12 +3799,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/index.ts

@@ -18,6 +18,7 @@ import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire
 import { type CompactionConfig, CompactionConfigSchema } from '../../config/runtime.js'
 import { childSessionLog } from '../../manager/agent/child-session.js'
 import { type TurnRecorder, recordedTurnStart } from '../../manager/session/turn-recorder.js'
+import { frameOperatorHookContext } from '../../plugin/hook-context.js'
 import { PromptContributionRegistry } from '../../prompt/contributions.js'
 import { resolveProviderCapabilities } from '../../provider/capabilities.js'
 import type { ProviderChainMember } from '../../provider/fallback.js'
@@ -2199,8 +2200,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 						promptContributions.replace({
 							id: 'hooks:subagent_start',
 							placement: 'context',
-							render: () =>
-								`Context from the operator's hooks:\n\n${startAnnotations.join('\n\n')}`,
+							render: () => frameOperatorHookContext(startAnnotations),
 						})
 					}
 					yield* eventTranslator.drainPending()
@@ -2226,7 +2226,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 						promptContributions.replace({
 							id: 'hooks:user_prompt_submit',
 							placement: 'context',
-							render: () => `Context from the operator's hooks:\n\n${annotations.join('\n\n')}`,
+							render: () => frameOperatorHookContext(annotations),
 						})
 					}
 					yield* eventTranslator.drainPending()

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

@@ -3505,6 +3505,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/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/plugin/index.ts

@@ -96,7 +96,13 @@ export type PluginHookEvent =
 	 * to what the model is told (`annotate`).
 	 */
 	| 'user_prompt_submit'
-	/** A host's session opened or closed. Carries `sessionId` and no `turnId`: these hooks run outside any turn. */
+	/**
+	 * A host's session opened or closed. Carries `sessionId` and no `turnId`:
+	 * these hooks run outside any turn. `session_start` carries `source`;
+	 * `session_end` carries `endReason`. A `session_start` hook may answer with
+	 * `context` (on `continue`) or `annotate`: text the model reads, from the
+	 * first turn of the session on.
+	 */
 	| 'session_start'
 	| 'session_end'
 	/** A compaction pass is about to run / has run. Carries `compaction`. */
@@ -110,11 +116,6 @@ export type PluginHookEvent =
 	| 'subagent_start'
 	/** A child session's turn ended. Fired after its own `turn_end`; carries `parentSessionId`, `parentTurnId` and `agentType`. */
 	| 'subagent_stop'
-	/**
-	 * A child session's turn is starting. Fired right after its own
-	 * `turn_start`; carries `parentSessionId` and `parentTurnId`. Observational.
-	 */
-	| 'subagent_start'
 	| 'turn_start'
 	| 'turn_end'
 	/**
@@ -273,6 +274,21 @@ export interface PluginNotificationInfo {
 	readonly message: string
 }
 
+/**
+ * Why a session started, on `session_start`: `startup` for a conversation
+ * with no earlier turn, `resume` for one that already had turns (a resumed
+ * conversation, a `--continue`, or a session rebuilt under a running one).
+ */
+export type PluginSessionSource = 'startup' | 'resume'
+
+/**
+ * Why a session closed, on `session_end`: `exit` when the host is finishing
+ * with it (the process ends, the person quits), `replaced` when the host
+ * builds another session in its place (a model or account switch, another
+ * conversation opened).
+ */
+export type PluginSessionEndReason = 'exit' | 'replaced'
+
 export interface PluginHookContext {
 	/** The turn the hook fired in. Absent on `session_start` and `session_end`. */
 	readonly turnId?: TurnId
@@ -286,6 +302,10 @@ export interface PluginHookContext {
 	readonly parentTurnId?: TurnId
 	/** The name of the agent the child runs, on `subagent_start` and `subagent_stop`. */
 	readonly agentType?: string
+	/** Why the session started, on `session_start`. */
+	readonly source?: PluginSessionSource
+	/** Why the session closed, on `session_end`. */
+	readonly endReason?: PluginSessionEndReason
 	/** The operator's prompt, on `user_prompt_submit`. */
 	readonly prompt?: string
 	/** The pass, on `pre_compact` and `post_compact`. */
@@ -437,7 +457,18 @@ export type PluginHookResult =
 	 * hook redacting a secret that also appears in an image must — this variant
 	 * cannot inspect what it is preserving.
 	 */
-	| { action: 'replace'; output: string; content?: ToolResultContent }
+	| ({
+			action: 'replace'
+			output: string
+			content?: ToolResultContent
+			/**
+			 * Say, beside the result the model and the record carry, that a hook
+			 * replaced it, so rewritten text is not passed off as the tool's own
+			 * words. Off by default: a plugin that redacts quietly keeps doing so.
+			 * A shell hook's replacement always sets it.
+			 */
+			disclose?: boolean
+	  } & PluginHookNotes)
 
 export function assertPluginHookResult(result: PluginHookResult): asserts result {
 	const action = result.action
@@ -472,15 +503,16 @@ export type PluginHookResultFor<E extends PluginHookEvent> = E extends 'user_pro
 						? Extract<PluginHookResult, { action: 'continue' | 'skip' }>
 						: E extends 'turn_end' | 'subagent_stop' | 'pre_compact'
 							? Extract<PluginHookResult, { action: 'continue' | 'skip' | 'error' }>
-							: E extends
-										| 'turn_interrupt'
-										| 'session_start'
-										| 'session_end'
-										| 'notification'
-										| 'turn_failure'
-										| 'permission_denied'
-								? Extract<PluginHookResult, { action: 'continue' }>
-								: Extract<PluginHookResult, { action: 'continue' | 'error' }>
+							: E extends 'session_start'
+								? Extract<PluginHookResult, { action: 'continue' | 'annotate' }>
+								: E extends
+											| 'turn_interrupt'
+											| 'session_end'
+											| 'notification'
+											| 'turn_failure'
+											| 'permission_denied'
+									? Extract<PluginHookResult, { action: 'continue' }>
+									: Extract<PluginHookResult, { action: 'continue' | 'error' }>
 
 /** The event and its handler verdict stay correlated, including in hook arrays. */
 export type PluginHookDefinition<E extends PluginHookEvent = PluginHookEvent> =

package/src/types/session/events.ts

@@ -435,6 +435,8 @@ type CoreSessionEvent =
 			message: string
 			/** Optional completion in [0,1] when the tool genuinely knows it. */
 			fraction?: number
+			/** Lines of output the call has produced so far, when the tool counts them (a shell command). Cumulative: the newest report wins. */
+			outputLines?: number
 	  }
 	/** Provider-executed activity, retained as evidence rather than a local tool request. */
 	| {

package/src/types/tool/index.ts

@@ -940,7 +940,13 @@ export interface ToolContext {
 	 *
 	 * Absent when the executing surface has no event stream to write to.
 	 */
-	report?: (message: string, fraction?: number) => void
+	report?: (message: string, fraction?: number, details?: ToolProgressDetails) => void
+}
+
+/** Facts a tool can attach to a progress report besides its words. */
+export interface ToolProgressDetails {
+	/** Lines of output the call has produced so far, counted by the tool itself (never by a renderer from what it was shown). */
+	readonly outputLines?: number
 }
 
 export interface ToolResult {
@@ -1009,6 +1015,13 @@ export interface ToolResult {
 	 * the child's turn fails with {@link ToolHandoff.reason} instead.
 	 */
 	handoff?: ToolHandoff
+	/**
+	 * This call only started work that goes on after it returned (a sub-agent
+	 * launched in the background, or one whose wait was released): the call itself
+	 * changed nothing. The turn's outcome record does not count it as a call that
+	 * may have changed files; what the started work does is its own record.
+	 */
+	launched?: true
 	/**
 	 * What this call did, as typed fields for the PERSON's view: the exit code
 	 * and the two streams of a command, the path and size of a read, whether a