@namzu/sdk 62.14.0 → 63.0.0

package/dist/plugin/shell-hook.d.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
@@ -117,8 +122,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`. */
@@ -138,10 +145,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. */
 export interface ShellHookEntry extends ShellHookEntryBase {
@@ -202,10 +218,29 @@ export declare const MAX_SHELL_HOOK_TIMEOUT_MS: number;
  * 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 declare function shellHookMatches(matcher: string | undefined, toolName: string | undefined): boolean;
+export declare function shellHookMatches(matcher: string | undefined, toolName: string | undefined, options?: {
+    readonly tool?: boolean;
+}): boolean;
 /**
  * A hook's `if` against one tool call: `Tool` or `Tool(pattern)`. The tool
  * part is case-insensitive and takes the names skills write (`Bash`,
@@ -213,13 +248,23 @@ export declare function shellHookMatches(matcher: string | undefined, toolName:
  * there; for a tool with no command line the filter cannot be read, which
  * runs the hook.
  */
-export declare function shellHookIfMatches(filter: string | undefined, toolName: string | undefined, toolInput: unknown): boolean;
+export declare function shellHookIfMatches(filter: string | undefined, toolName: string | undefined, toolInput: unknown, pathFilter?: ShellHookPathFilter): boolean;
+/**
+ * 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;
 }
@@ -230,6 +275,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`. */
@@ -299,11 +350,35 @@ 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. */
 export declare const DEFAULT_PROMPT_HOOK_TIMEOUT_MS = 30000;
 /** One entry as a hook definition the lifecycle manager accepts. */
-export declare function createShellHook(event: ShellHookEvent, entry: ShellHookHandler, options: ShellHookOptions): PluginHookDefinition;
+export declare function createShellHook(event: ShellHookEvent, configured: ShellHookHandler, options: ShellHookOptions): PluginHookDefinition;
 /**
  * Register every entry on the manager, in file order within an event. The
  * manager starts all of an event's hooks together and reads their answers in

package/dist/plugin/shell-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shell-hook.d.ts","sourceRoot":"","sources":["../../src/plugin/shell-hook.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"shell-hook.d.ts","sourceRoot":"","sources":["../../src/plugin/shell-hook.ts"],"names":[],"mappings":"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"}

package/dist/plugin/shell-hook.js

@@ -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
@@ -101,10 +106,12 @@
 import { spawn } from 'node:child_process';
 import { decodedCommands, decomposeCommandLine } from '../authorization/command-line.js';
 import { SKILL_TOOL_NAME_ALIASES, permissionPatternToRegExpSource, } from '../authorization/skill-grant.js';
+import { withSessionChildMarker } from '../process/session-child.js';
 import { spawnHostShell } from '../tools/command-shell.js';
 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 { boundHookReplacement } from './hook-context.js';
 import { postHookJson } from './shell-hook-http.js';
 export const SHELL_HOOK_EVENTS = [
     'user_prompt_submit',
@@ -131,6 +138,51 @@ export const DEFAULT_SHELL_HOOK_TIMEOUT_MS = 600_000;
 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 = 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) {
+    const lower = toolName.toLowerCase();
+    const names = [];
+    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).
  *
@@ -138,22 +190,56 @@ 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, toolName) {
+export function shellHookMatches(matcher, toolName, options = {}) {
     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;
@@ -166,7 +252,7 @@ export function shellHookMatches(matcher, toolName) {
  * there; for a tool with no command line the filter cannot be read, which
  * runs the hook.
  */
-export function shellHookIfMatches(filter, toolName, toolInput) {
+export function shellHookIfMatches(filter, toolName, toolInput, pathFilter) {
     if (filter === undefined || filter.trim() === '')
         return true;
     if (toolName === undefined)
@@ -176,10 +262,18 @@ export function shellHookIfMatches(filter, toolName, toolInput) {
         return true;
     const written = (shape[1] ?? '').toLowerCase();
     const tool = SKILL_TOOL_NAME_ALIASES[written] ?? written;
+    const specifier = shape[2]?.trim();
+    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;
-    const specifier = shape[2]?.trim();
-    if (specifier === undefined || specifier === '' || specifier.replaceAll('*', '') === '')
+    if (!hasPattern)
         return true;
     if (tool !== 'bash')
         return true;
@@ -214,6 +308,7 @@ export function shellHookPayload(input) {
         ...(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
@@ -240,7 +335,11 @@ export function shellHookPayload(input) {
                 })),
             }
             : {}),
-        ...(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
             ? {
@@ -266,6 +365,7 @@ export function runShellHook(entry, input, signal) {
                 ...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 } : {}),
@@ -282,7 +382,7 @@ export function runShellHook(entry, input, signal) {
                     ? // The exec form: no shell reads `command` or any argument.
                         spawn(entry.command, [...entry.args], {
                             cwd: input.cwd,
-                            env,
+                            env: withSessionChildMarker(env),
                             stdio: ['pipe', 'pipe', 'pipe'],
                             detached,
                         })
@@ -311,16 +411,26 @@ export function runShellHook(entry, input, signal) {
         }
         let stdout = '';
         let stderr = '';
+        let stdoutTruncated = false;
         let timedOut = false;
         let settled = false;
-        const capture = (current, chunk) => current.length >= MAX_CAPTURE_BYTES
-            ? current
-            : (current + chunk.toString('utf8')).slice(0, MAX_CAPTURE_BYTES);
+        const capture = (current, chunk) => {
+            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) => {
-            stdout = capture(stdout, chunk);
+            const next = capture(stdout, chunk);
+            stdout = next.text;
+            if (next.cut)
+                stdoutTruncated = true;
         });
         child.stderr?.on('data', (chunk) => {
-            stderr = capture(stderr, chunk);
+            stderr = capture(stderr, chunk).text;
         });
         const finish = (outcome) => {
             if (settled)
@@ -355,11 +465,18 @@ export function runShellHook(entry, input, signal) {
                 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
@@ -518,6 +635,12 @@ function readShellHookJson(event, stdout) {
             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)) {
@@ -552,9 +675,25 @@ export function shellHookVerdict(event, entry, outcome, log = NOOP_LOGGER) {
     };
     // 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) => 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, shown = reason) => {
+        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,
@@ -602,12 +741,17 @@ export function shellHookVerdict(event, entry, outcome, log = NOOP_LOGGER) {
     }
     // Exit 0.
     const text = outcome.stdout.trim();
-    const reading = readShellHookJson(event, outcome.stdout);
+    const reading = 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' };
     }
@@ -616,7 +760,9 @@ export function shellHookVerdict(event, entry, outcome, log = NOOP_LOGGER) {
             ...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', {
@@ -667,11 +813,34 @@ export function shellHookVerdict(event, entry, outcome, log = NOOP_LOGGER) {
             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 } : {}),
@@ -817,8 +986,17 @@ function readJudgement(reply) {
     }
 }
 /** One entry as a hook definition the lifecycle manager accepts. */
-export function createShellHook(event, entry, options) {
+export function createShellHook(event, configured, options) {
     const log = options.log ?? NOOP_LOGGER;
+    const eventDefault = options.defaultTimeoutMs?.[event];
+    const entry = configured.timeoutMs === undefined && eventDefault !== undefined
+        ? { ...configured, timeoutMs: eventDefault }
+        : configured;
+    const reportTimeout = (timedOut) => {
+        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;
@@ -831,14 +1009,23 @@ export function createShellHook(event, entry, options) {
             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))
+                    : 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)) {
+            if (!shellHookIfMatches(entry.if, context.toolName, context.toolInput, options.pathFilter)) {
                 return { action: 'continue' };
             }
             if (entry.once === true)
@@ -848,7 +1035,10 @@ export function createShellHook(event, entry, options) {
             const hookInput = {
                 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) }
@@ -889,6 +1079,7 @@ export function createShellHook(event, entry, options) {
                     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, entry, {
                     exitCode: ok ? 0 : (response.status ?? null),
@@ -912,6 +1103,7 @@ export function createShellHook(event, entry, options) {
                 return { action: 'continue' };
             }
             const outcome = await runShellHook(entry, hookInput, context.signal);
+            reportTimeout(outcome.timedOut);
             return shellHookVerdict(event, entry, outcome, log);
         },
     };