@namzu/sdk 62.14.0 → 63.0.0

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,
@@ -1428,6 +1434,20 @@ export {
 	loadEvalReportFile,
 	summarizeRun,
 	withEvalRunOptions,
+	currentEvalSettings,
+	evalSetting,
+	DEFAULT_SETTINGS_NAME,
+	buildSettingsSnapshot,
+	defaultSettingsSnapshot,
+	diffSettings,
+	validateSettingsName,
+	HELD_OUT_FRACTION,
+	SPLIT_FILTERS,
+	TASK_SPLIT_SEED,
+	assignSplit,
+	hashedSplit,
+	taskId,
+	validateSplitFilter,
 	compareHarnessTrials,
 	reviewHarnessCandidate,
 	claimMismatchScorer,
@@ -1931,6 +1951,7 @@ export {
 	MAX_PEER_CONNECTIONS,
 	MAX_PEER_MESSAGE_TEXT_BYTES,
 	MAX_PEER_REQUEST_BYTES,
+	NoticeOutcomeSchema,
 	NoticeRequestSchema,
 	NoticeResponseSchema,
 	OUTSTANDING_EXPIRY_MS,
@@ -1958,6 +1979,7 @@ export {
 	createPeerEndpoint,
 	derivePeerRef,
 	formatPeerMessage,
+	formatPersonMessage,
 	formatPeerNotice,
 	hardenPeerRuntimeDir,
 	isPeerRecordLive,
@@ -1973,6 +1995,11 @@ export {
 	udsPeerAddress,
 	writePeerRecord,
 } from './peers/index.js'
+export {
+	SESSION_CHILD_ENV,
+	startedBySession,
+	withSessionChildMarker,
+} from './process/session-child.js'
 export {
 	ACCOUNTS_FILE_NAME,
 	ACCOUNTS_FILE_VERSION,

package/src/public-types.ts

@@ -244,6 +244,7 @@ export type {
 	ShellHookOnFailure,
 	ShellHookInput,
 	ShellHookOptions,
+	ShellHookPathFilter,
 	ShellHookOutcome,
 	ShellHooksConfig,
 } from './plugin/shell-hook.js'
@@ -737,6 +738,7 @@ export type {
 	DeliverRequest,
 	DeliverResponse,
 	DeliverStatus,
+	NoticeOutcome,
 	NoticeRequest,
 	NoticeResponse,
 	PeerFrom,

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

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/system-events.ts

@@ -54,13 +54,14 @@ const SYSTEM_EVENT_STATUSES_LIST = [
 	'refused',
 	'idle',
 	'exited',
+	'delivered',
 ] as const
 
 /**
  * The closed set of outcomes this envelope may report.
  *
  * Not every status applies to every kind: `completed`/`failed`/`cancelled`/
- * `killed`/`interim` describe an `agent` or `job`; `queued`/`held`/`refused`
+ * `killed`/`interim` describe an `agent` or `job`; `queued`/`held`/`refused`/`delivered`
  * describe a peer message or its delivery notice; `idle`/`exited` describe a
  * peer's status notice. `formatSystemEvent` does not cross-check kind against
  * status — the caller owns that pairing — because the two closed sets belong

package/src/sandbox/provider/local.ts

@@ -27,6 +27,7 @@ import {
 // registry needs the same one, and a near-copy would reproduce in the copy
 // every bug the original's comment was written to record.
 import { killTree } from '../../process/kill-tree.js'
+import { SESSION_CHILD_ENV } from '../../process/session-child.js'
 import { resolveWithinAny, resolveWithinAnyReal } from '../../tools/paths.js'
 import type { SandboxId } from '../../types/ids/index.js'
 import type {
@@ -52,6 +53,7 @@ import {
 	WINDOWS_CORE_ENV_KEYS,
 	applyEnvironmentOverrides,
 	pickEnvironmentEntries,
+	setEnvironmentEntry,
 } from '../../utils/process-environment.js'
 import { createTempDir, resolveTempBase } from '../../utils/temp.js'
 import { walkFilesLocally } from '../file-walk.js'
@@ -586,7 +588,7 @@ function buildSeatbeltArgs(
 // Environment building
 // ---------------------------------------------------------------------------
 
-function buildSafeEnv(
+export function buildSafeEnv(
 	configEnv?: Record<string, string>,
 	optsEnv?: Record<string, string>,
 ): Record<string, string> {
@@ -598,6 +600,8 @@ function buildSafeEnv(
 
 	applyEnvironmentOverrides(env, configEnv)
 	applyEnvironmentOverrides(env, optsEnv)
+	// Last: a command in a sandbox is still a command a session started.
+	setEnvironmentEntry(env, SESSION_CHILD_ENV, '1')
 
 	return env
 }

package/src/sandbox/terminal.ts

@@ -26,6 +26,8 @@
  * make teardown await every process it owns before using this primitive.
  */
 
+import { withSessionChildMarker } from '../process/session-child.js'
+
 export interface TerminalSize {
 	readonly cols: number
 	readonly rows: number
@@ -172,7 +174,7 @@ export function openTerminalWith(
 		cols: options.size.cols,
 		rows: options.size.rows,
 		cwd: options.cwd ?? defaults.cwd,
-		...(options.env ? { env: { ...options.env } } : {}),
+		env: withSessionChildMarker({ ...(options.env ?? process.env) }) as Record<string, string>,
 	})
 
 	const dataSub = child.onData((chunk) => {

package/src/tools/command-shell.ts

@@ -56,6 +56,7 @@ import { constants, accessSync, existsSync } from 'node:fs'
 import { delimiter, isAbsolute, join, win32 } from 'node:path'
 
 import { MSYS_TAG_VARIABLE, registerMsysShell, registerProcessTag } from '../process/kill-tree.js'
+import { withSessionChildMarker } from '../process/session-child.js'
 import type { ShellDialect } from '../types/tool/index.js'
 
 /** The shell a host-side command runs in. */
@@ -460,8 +461,13 @@ export function spawnHostShell(
 	const windowsBash = shell.windows === true && shell.path !== undefined
 	const tag =
 		windowsBash || (shell.windows !== true && platform === 'linux') ? randomUUID() : undefined
+	// Every command the kernel runs on a session's behalf says so in its environment, and a program
+	// that must not be run by a model (`namzu send`) reads it. See `process/session-child.ts`.
+	const marked = withSessionChildMarker(spawned.env, platform)
 	const resolved =
-		tag === undefined ? spawned : { ...spawned, env: { ...spawned.env, [MSYS_TAG_VARIABLE]: tag } }
+		tag === undefined
+			? { ...spawned, env: marked }
+			: { ...spawned, env: { ...marked, [MSYS_TAG_VARIABLE]: tag } }
 	const common: SpawnOptions = {
 		cwd: options.cwd,
 		env: resolved.env,

package/src/types/message/index.ts

@@ -365,6 +365,7 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'limit-finalization',
 	'peer-message',
 	'peer-notice',
+	'person-message',
 	'progress-nudge',
 	'reminder',
 	'repeat-call',

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> =