@namzu/sdk 63.1.0 → 64.0.0

package/dist/plugin/shell-hook.js

@@ -24,8 +24,8 @@
  * 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_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` also sends `source` (`startup`, `resume` or `clear`) and
+ * `session_end` `reason` (`exit`, `replaced` or `clear`).
  *
  * `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
@@ -36,7 +36,8 @@
  * stdout. The exit codes:
  *
  * - `0` — carry on. On `user_prompt_submit`, `subagent_start` and
- *   `session_start`, plain (non-JSON) stdout becomes context for the model.
+ *   `session_start`, plain (non-JSON) stdout becomes context for the model;
+ *   on `pre_compact` it is instructions for the summariser.
  * - `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`
@@ -112,7 +113,9 @@ 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 { readHookCommand } from './shell-hook-command.js';
 import { postHookJson } from './shell-hook-http.js';
+import { shellHookToolName } from './shell-hook-tool-names.js';
 export const SHELL_HOOK_EVENTS = [
     'user_prompt_submit',
     'session_start',
@@ -169,12 +172,28 @@ const WRITTEN_TOOL_NAMES = Object.freeze({
     taskupdate: 'TaskUpdate',
     tasklist: 'TaskList',
 });
+/**
+ * The tools a written name stands for. The skill alias table sends `Task` and
+ * `Agent` to `create_task`, but the command line's sub-agent tool is named
+ * `Agent`, and a hook written for either spelling means it: both name it.
+ */
+function toolsNamedBy(written) {
+    const alias = SKILL_TOOL_NAME_ALIASES[written];
+    const names = alias !== undefined ? [alias] : [];
+    if (written === 'task' || written === 'agent')
+        names.push('agent');
+    return names;
+}
+/** A name with the separators dropped: `ViewImage` and `view_image` are one tool. */
+function squashed(name) {
+    return name.toLowerCase().replace(/[_-]/g, '');
+}
 /** 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)
+    for (const written of new Set([...Object.keys(SKILL_TOOL_NAME_ALIASES), 'agent', 'task'])) {
+        if (!toolsNamedBy(written).includes(lower))
             continue;
         names.push(written);
         const spelled = WRITTEN_TOOL_NAMES[written];
@@ -183,27 +202,74 @@ function writtenNamesFor(toolName) {
     }
     return names;
 }
+/** A glob over names: `*` matches any run of characters, the rest is literal. */
+function globMatches(pattern, subject) {
+    const source = pattern
+        .split('*')
+        .map((piece) => piece.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+        .join('.*');
+    return new RegExp(`^${source}$`, 'i').test(subject);
+}
+/**
+ * Whether a list part (`Edit`, `Web*`, `mcp__*__search`) names `subject`, as a
+ * tool name or not. A `*` at the end is a prefix; a `*` anywhere else is a
+ * glob. For a tool, a bare tool-server name (`mcp__github`) names every tool
+ * of that server.
+ */
+function listPartNames(part, subject, tool) {
+    const prefix = part.endsWith('*');
+    const core = prefix ? part.slice(0, -1) : part;
+    const written = core.toLowerCase();
+    const lower = subject.toLowerCase();
+    if (core.includes('*')) {
+        if (globMatches(part, subject))
+            return true;
+        return tool && writtenNamesFor(subject).some((name) => globMatches(part, name));
+    }
+    const spellings = [written];
+    if (tool)
+        spellings.push(...toolsNamedBy(written));
+    return spellings.some((name) => {
+        if (prefix ? lower.startsWith(name) : lower === name)
+            return true;
+        if (!tool)
+            return false;
+        // A tool's name also compares without its `_` and `-`.
+        if (prefix ? squashed(lower).startsWith(squashed(name)) : squashed(lower) === squashed(name)) {
+            return true;
+        }
+        return !prefix && name.startsWith('mcp__') && !name.slice(5).includes('__')
+            ? lower.startsWith(`${name}__`)
+            : false;
+    });
+}
+const MATCHER_LIST_PART = /^[A-Za-z0-9_.:*-]+$/;
 /**
  * `matcher` against a name (a tool's, or a notification's type).
  *
  * Empty or `*` matches everything. A list of names separated by `|` or `,`
  * 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. A matcher on an event that has no name (`turn_start`)
- * matches nothing unless it is `*`.
+ * expression, tested unanchored against the name. This function called with no
+ * name matches only `*`; a hook on an event that has no name (`turn_end`)
+ * ignores its matcher and fires (see `createShellHook`).
+ *
+ * A text that reads both ways (it is a list, and it holds a `.*`
+ * that a regular expression reads differently:  `Bash.*`,
+ * `mcp__.*__search`) fires when either reading matches. A pattern that does
+ * not compile cannot be read, and a guard that silently matches nothing is
+ * the failure to avoid, so it matches every name; `/hooks` and
+ * `namzu doctor` say that it cannot be read (`shellHookMatcherProblem`).
  *
  * 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.
+ * take the names skills write, the way an entry's `if` does, and a tool name
+ * compares without its `_` and `-`: `Bash` matches the tool `bash`,
+ * `MultiEdit` matches `edit`, `ViewImage` matches `view_image`, `Task` and
+ * `Agent` match the sub-agent tool `Agent`, and a prefix such as `Web*`
+ * matches `web_fetch`. 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.
  *
  * A regular expression is tested, case-sensitively as written, against the
  * real name and, with `tool: true`, against each name skills write for that
@@ -217,23 +283,13 @@ export function shellHookMatches(matcher, toolName, options = {}) {
         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))) {
-        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;
+    if (parts.every((part) => MATCHER_LIST_PART.test(part))) {
+        if (parts.some((part) => listPartNames(part, toolName, tool)))
+            return true;
+        // A list of names is exact (a `*` in it is a prefix or a glob). Only `.*` reads differently
+        // as a regular expression, so only then is the second reading tried.
+        if (!matcher.includes('.*'))
+            return false;
     }
     try {
         const expression = new RegExp(matcher);
@@ -242,41 +298,95 @@ export function shellHookMatches(matcher, toolName, options = {}) {
         return tool && writtenNamesFor(toolName).some((name) => expression.test(name));
     }
     catch {
-        return false;
+        return true;
     }
 }
+/**
+ * Why a `matcher` cannot be read, or `undefined` when it can. A matcher that
+ * is not a list of names and does not compile as a regular expression fires
+ * for every name (see {@link shellHookMatches}).
+ */
+export function shellHookMatcherProblem(matcher) {
+    if (matcher === undefined || matcher.trim() === '' || matcher.trim() === '*')
+        return undefined;
+    const parts = matcher.split(/[|,]/).map((part) => part.trim());
+    if (parts.every((part) => MATCHER_LIST_PART.test(part)))
+        return undefined;
+    // `Bash(git push *)` is a tool and a pattern, which is what an `if` reads. As a
+    // matcher it is a regular expression that no tool name satisfies, so the hook
+    // would never fire; say so, and name the `if`.
+    if (/^[A-Za-z0-9_.:*-]+\([\s\S]*\)$/.test(matcher.trim())) {
+        return `the matcher "${matcher}" is written as Tool(pattern), which is an if, not a matcher: as a matcher it matches no tool name and the hook never fires; put the tool in matcher and the pattern in if`;
+    }
+    try {
+        new RegExp(matcher);
+        return undefined;
+    }
+    catch (error) {
+        return `the matcher "${matcher}" is not a list of names and is not a regular expression (${error.message}), so it cannot be read and the hook fires for every call`;
+    }
+}
+const IF_SHAPE = /^([A-Za-z0-9_.:*|, -]+)(?:\(([\s\S]*)\))?$/;
+/**
+ * Why an `if` cannot be read, or `undefined` when it can. A filter that
+ * cannot be read runs the hook.
+ */
+export function shellHookIfProblem(filter) {
+    if (filter === undefined || filter.trim() === '')
+        return undefined;
+    return IF_SHAPE.test(filter.trim())
+        ? undefined
+        : `the if "${filter}" is not Tool or Tool(pattern), so it cannot be read and the hook runs for every call`;
+}
 /**
  * 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`,
- * `Read`). A pattern is matched against a shell tool's command line and only
- * there; for a tool with no command line the filter cannot be read, which
- * runs the hook.
+ * part takes every spelling a `matcher` takes as a list: names skills write
+ * (`Bash`, `Read`, `Agent`), separated by `|` or `,`, a prefix ending in `*`,
+ * case ignored; a regular expression is not read here (use `matcher`). A
+ * pattern is matched against a shell tool's command line (one command at a
+ * time) or, for a file tool, a path the host reads; for a tool with neither
+ * the filter cannot be read, which runs the hook.
  */
 export function shellHookIfMatches(filter, toolName, toolInput, pathFilter) {
     if (filter === undefined || filter.trim() === '')
         return true;
     if (toolName === undefined)
         return true;
-    const shape = /^([A-Za-z0-9_.-]+)(?:\(([\s\S]*)\))?$/.exec(filter.trim());
+    const shape = IF_SHAPE.exec(filter.trim());
     if (!shape)
         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;
-    if (!hasPattern)
+    const parts = (shape[1] ?? '')
+        .split(/[|,]/)
+        .map((part) => part.trim())
+        .filter((part) => part !== '');
+    if (parts.length === 0)
         return true;
-    if (tool !== 'bash')
+    if (parts.some((part) => part === '*'))
         return true;
+    const callTool = toolName.toLowerCase();
+    return parts.some((part) => {
+        const written = part.replace(/\*$/, '').toLowerCase();
+        const tool = SKILL_TOOL_NAME_ALIASES[written] ?? written;
+        // 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 && !part.endsWith('*')) {
+            const answer = pathFilter(tool, specifier, toolName, toolInput);
+            if (answer !== undefined)
+                return answer;
+        }
+        if (!listPartNames(part, toolName, true))
+            return false;
+        if (!hasPattern)
+            return true;
+        if (callTool !== 'bash')
+            return true;
+        return commandMatches(specifier, toolInput);
+    });
+}
+/** A shell tool's command line against a permission-rule pattern, per command. */
+function commandMatches(specifier, toolInput) {
     const line = toolInput !== null && typeof toolInput === 'object'
         ? toolInput.command
         : undefined;
@@ -291,7 +401,17 @@ export function shellHookIfMatches(filter, toolName, toolInput, pathFilter) {
         // whole line is visible and none of its commands matches.
         if (decomposed.opaque)
             return true;
-        const candidates = [...decomposed.segments, ...decodedCommands(line, 'sh')].map((each) => each.trim());
+        // Wrappers, a program's full path and git's global options do not change
+        // which command runs; a command whose name is only known at run time
+        // cannot be compared, so the hook runs.
+        const reading = readHookCommand(line);
+        if (reading.unknowable)
+            return true;
+        const candidates = [
+            ...decomposed.segments,
+            ...decodedCommands(line, 'sh'),
+            ...reading.candidates,
+        ].map((each) => each.trim());
         return candidates.some((each) => matcher.test(each));
     }
     catch {
@@ -302,7 +422,7 @@ export function shellHookIfMatches(filter, toolName, toolInput, pathFilter) {
 export function shellHookPayload(input) {
     return JSON.stringify({
         event: input.event,
-        hook_event_name: PASCAL_EVENT_NAMES[input.event] ?? input.event,
+        hook_event_name: SHELL_HOOK_PASCAL_EVENT_NAMES[input.event] ?? input.event,
         cwd: input.cwd,
         session_id: input.sessionId,
         ...(input.transcriptPath !== undefined ? { transcript_path: input.transcriptPath } : {}),
@@ -315,9 +435,14 @@ export function shellHookPayload(input) {
             ? { agent_id: input.sessionId, agent_type: input.agentType }
             : {}),
         ...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
-        ...(input.compaction !== undefined ? { compaction: input.compaction } : {}),
-        ...(input.toolName !== undefined ? { tool_name: input.toolName } : {}),
-        ...(input.toolInput !== undefined ? { tool_input: input.toolInput } : {}),
+        ...(input.compaction !== undefined ? compactionFields(input.event, input.compaction) : {}),
+        ...(input.toolName !== undefined
+            ? { tool_name: shellHookToolName(input.toolName, input.toolNames) }
+            : {}),
+        ...(input.toolCallId !== undefined ? { tool_use_id: input.toolCallId } : {}),
+        ...(input.toolInput !== undefined
+            ? { tool_input: withFilePathKey(input.toolName, input.toolInput) }
+            : {}),
         ...(input.toolResult !== undefined
             ? { tool_result: input.toolResult, tool_response: input.toolResult }
             : {}),
@@ -327,8 +452,8 @@ export function shellHookPayload(input) {
         ...(input.toolCalls !== undefined
             ? {
                 tool_calls: input.toolCalls.map((call) => ({
-                    tool_name: call.toolName,
-                    tool_input: call.toolInput,
+                    tool_name: shellHookToolName(call.toolName, input.toolNames),
+                    tool_input: withFilePathKey(call.toolName, call.toolInput),
                     tool_use_id: call.toolCallId,
                     tool_response: call.output,
                     is_error: call.isError,
@@ -348,8 +473,26 @@ export function shellHookPayload(input) {
             }
             : {}),
         ...(input.stopHookActive === true ? { stop_hook_active: true } : {}),
+        ...(input.lastAssistantMessage !== undefined
+            ? { last_assistant_message: input.lastAssistantMessage }
+            : {}),
     });
 }
+/**
+ * A compaction hook's fields. `compaction` keeps what it always had and gains
+ * `trigger`; the person's instructions and the summary are top-level
+ * (`custom_instructions`, null when there are none, and `compact_summary`),
+ * where a script reads them without opening the object.
+ */
+function compactionFields(event, compaction) {
+    const { instructions, summary, ...rest } = compaction;
+    return {
+        compaction: rest,
+        ...(compaction.trigger !== undefined ? { trigger: compaction.trigger } : {}),
+        ...(event === 'pre_compact' ? { custom_instructions: instructions ?? null } : {}),
+        ...(event === 'post_compact' && summary !== undefined ? { compact_summary: summary } : {}),
+    };
+}
 /** Run one hook command to completion, bounded by its deadline and capture. */
 export function runShellHook(entry, input, signal) {
     const timeoutMs = Math.min(MAX_SHELL_HOOK_TIMEOUT_MS, Math.max(1, entry.timeoutMs ?? DEFAULT_SHELL_HOOK_TIMEOUT_MS));
@@ -367,7 +510,9 @@ export function runShellHook(entry, input, signal) {
                 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 } : {}),
+                ...(input.toolName !== undefined
+                    ? { NAMZU_TOOL_NAME: shellHookToolName(input.toolName, input.toolNames) }
+                    : {}),
                 ...(toolPath !== undefined ? { NAMZU_TOOL_PATH: toolPath } : {}),
             };
             // Its own process group, so the deadline can kill everything the
@@ -492,6 +637,56 @@ export function runShellHook(entry, input, signal) {
         child.stdin?.end(payload);
     });
 }
+/**
+ * The tools whose input names a file or folder `path`. A moved script reads
+ * that file under the key `file_path`, so the input a hook receives carries
+ * both, with the same value.
+ */
+const FILE_PATH_TOOLS = new Set([
+    'read',
+    'write',
+    'edit',
+    'grep',
+    'glob',
+    'ls',
+    'view_image',
+    'lsp',
+]);
+/** `toolInput` as a hook receives it: a file tool's `path` is also `file_path`. */
+function withFilePathKey(toolName, toolInput) {
+    if (toolName === undefined || !FILE_PATH_TOOLS.has(toolName.toLowerCase()))
+        return toolInput;
+    if (!isRecord(toolInput))
+        return toolInput;
+    const path = toolInput.path;
+    if (typeof path !== 'string' || 'file_path' in toolInput)
+        return toolInput;
+    return { ...toolInput, file_path: path };
+}
+/**
+ * A rewritten input read back. An echoed `file_path` is never a reason to
+ * refuse the rewrite: when only one of the two keys was changed that change is
+ * the new path; when both were changed to different values the answer cannot be
+ * read (`undefined`). The tool never sees `file_path`.
+ */
+function readRewrittenInput(toolName, original, rewritten) {
+    if (toolName === undefined || !FILE_PATH_TOOLS.has(toolName.toLowerCase()))
+        return rewritten;
+    if (!('file_path' in rewritten))
+        return rewritten;
+    const { file_path: echoed, ...rest } = rewritten;
+    const before = isRecord(original) ? original.path : undefined;
+    const pathChanged = 'path' in rest && rest.path !== before;
+    const echoChanged = echoed !== before;
+    if (pathChanged && echoChanged && echoed !== rest.path)
+        return undefined;
+    if (!pathChanged && echoChanged) {
+        if (typeof echoed !== 'string')
+            return undefined;
+        return { ...rest, path: echoed };
+    }
+    return rest;
+}
 function pathOf(toolInput) {
     if (toolInput === null || typeof toolInput !== 'object')
         return undefined;
@@ -504,7 +699,7 @@ function pathOf(toolInput) {
     return undefined;
 }
 /** The PascalCase spelling of each event name, which a hook's JSON may use. */
-const PASCAL_EVENT_NAMES = {
+export const SHELL_HOOK_PASCAL_EVENT_NAMES = {
     user_prompt_submit: 'UserPromptSubmit',
     session_start: 'SessionStart',
     session_end: 'SessionEnd',
@@ -522,6 +717,31 @@ const PASCAL_EVENT_NAMES = {
     turn_failure: 'StopFailure',
     turn_end: 'Stop',
 };
+/** The keys that carry a replacement for a tool's result. */
+const REPLACEMENT_KEYS = ['updatedToolOutput', 'updatedMCPToolOutput'];
+/**
+ * A replacement for a tool's result, whatever its JSON type. A string is the
+ * text; an object that has the shape of the result object a hook is sent
+ * (`output` a string, `success` a boolean and `error` a string when present)
+ * is read as that; anything else (another object, an array, a number, a
+ * boolean) is shown as its JSON text. The call's own success is not changed.
+ */
+function replacementText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (isRecord(value) &&
+        typeof value.output === 'string' &&
+        (value.success === undefined || typeof value.success === 'boolean') &&
+        (value.error === undefined || typeof value.error === 'string')) {
+        if (value.success === false && typeof value.error === 'string' && value.error !== '') {
+            return value.output === ''
+                ? `Error: ${value.error}`
+                : `${value.output}\n\nError: ${value.error}`;
+        }
+        return value.output;
+    }
+    return JSON.stringify(value);
+}
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -531,7 +751,7 @@ function isRecord(value) {
  * sets the whole object aside rather than half-obeying it, so a typo in a
  * guard's `decision` is reported instead of silently becoming "continue".
  */
-function readShellHookJson(event, stdout) {
+function readShellHookJson(event, stdout, call = {}) {
     const text = stdout.trim();
     if (!text.startsWith('{'))
         return undefined;
@@ -570,6 +790,20 @@ function readShellHookJson(event, stdout) {
         parsed.decision !== 'block') {
         return { invalid: '`decision` must be "approve" or "block"' };
     }
+    // A replacement written where it is not read (at the top level of the answer
+    // instead of under `hookSpecificOutput`) is a hook that clearly tried to say
+    // something we cannot read: set the answer aside as unreadable, so
+    // `onFailure: block` withholds the result rather than showing the original.
+    if (event === 'post_tool_use' || event === 'post_tool_use_failure') {
+        const misplaced = REPLACEMENT_KEYS.find((key) => parsed[key] !== undefined);
+        const inSpecific = isRecord(parsed.hookSpecificOutput) &&
+            REPLACEMENT_KEYS.some((key) => parsed.hookSpecificOutput[key] !== undefined);
+        if (misplaced !== undefined && !inSpecific) {
+            return {
+                invalid: `\`${misplaced}\` is read under \`hookSpecificOutput\`, not at the top level of the answer`,
+            };
+        }
+    }
     const reading = {};
     if (parsed.suppressOutput === true)
         reading.suppressOutput = true;
@@ -595,7 +829,7 @@ function readShellHookJson(event, stdout) {
     if (typeof named !== 'string') {
         return { invalid: '`hookSpecificOutput` is missing its `hookEventName`' };
     }
-    if (named !== event && named !== PASCAL_EVENT_NAMES[event]) {
+    if (named !== event && named !== SHELL_HOOK_PASCAL_EVENT_NAMES[event]) {
         return {
             invalid: `\`hookSpecificOutput.hookEventName\` is "${named}" but this hook ran for ${event}`,
         };
@@ -632,14 +866,25 @@ function readShellHookJson(event, stdout) {
         if (specific.updatedInput !== undefined) {
             if (!isRecord(specific.updatedInput))
                 return { invalid: '`updatedInput` must be an object' };
-            reading.updatedInput = specific.updatedInput;
+            const rewritten = readRewrittenInput(call.toolName, call.toolInput, specific.updatedInput);
+            if (rewritten === undefined) {
+                return {
+                    invalid: '`updatedInput` changes both `path` and `file_path`, to different values: say which file is meant',
+                };
+            }
+            reading.updatedInput = rewritten;
         }
     }
-    if (event === 'post_tool_use' && specific.updatedToolOutput !== undefined) {
-        if (typeof specific.updatedToolOutput !== 'string') {
-            return { invalid: 'hookSpecificOutput: `updatedToolOutput` must be a string' };
+    if (event === 'post_tool_use' || event === 'post_tool_use_failure') {
+        // For a tool-server tool the common contract has a second field, read
+        // when `updatedToolOutput` is absent or null. `updatedToolOutput` wins when
+        // both carry a value: it is the field for every tool, so a script that
+        // sets both has said the general thing last.
+        const toolServer = call.toolName?.startsWith('mcp__') === true;
+        const chosen = specific.updatedToolOutput ?? (toolServer ? specific.updatedMCPToolOutput : undefined);
+        if (chosen !== undefined && chosen !== null) {
+            reading.replacement = boundHookReplacement(replacementText(chosen));
         }
-        reading.replacement = boundHookReplacement(specific.updatedToolOutput);
     }
     if (event === 'permission_request') {
         const decision = specific.decision;
@@ -667,7 +912,7 @@ function readShellHookJson(event, stdout) {
  * so the mapping — the part that decides what the model is told — is
  * testable without a process.
  */
-export function shellHookVerdict(event, entry, outcome, log = NOOP_LOGGER) {
+export function shellHookVerdict(event, entry, outcome, log = NOOP_LOGGER, call = {}) {
     const label = describeShellHook(entry);
     const attrs = {
         'namzu.hook.event': event,
@@ -692,7 +937,7 @@ export function shellHookVerdict(event, entry, outcome, log = NOOP_LOGGER) {
                 disclose: true,
             };
         }
-        return shellHookVerdict(event, { ...entry, onFailure: 'continue' }, { exitCode: 2, timedOut: false, stdout: '', stderr: `hook failed: ${reason}` }, log);
+        return shellHookVerdict(event, { ...entry, onFailure: 'continue' }, { exitCode: 2, timedOut: false, stdout: '', stderr: `hook failed: ${reason}` }, log, call);
     };
     if (outcome.spawnError !== undefined) {
         log.warn('hook could not start', {
@@ -745,12 +990,27 @@ export function shellHookVerdict(event, entry, outcome, log = NOOP_LOGGER) {
         ? {
             invalid: `answer is too large: the hook printed more than the ${MAX_CAPTURE_BYTES} characters of stdout that are read`,
         }
-        : readShellHookJson(event, outcome.stdout);
+        : readShellHookJson(event, outcome.stdout, call);
     if (reading === undefined) {
+        // A post-tool hook whose plain output (or whose stderr) names a replacement
+        // key tried to replace the result and put the answer where it is not read
+        // (a log line before the JSON, the JSON on stderr). That is an answer that
+        // does not read, so it follows `onFailure` like one.
+        if ((event === 'post_tool_use' || event === 'post_tool_use_failure') &&
+            REPLACEMENT_KEYS.some((key) => outcome.stdout.includes(key) || outcome.stderr.includes(key))) {
+            log.warn('hook output ignored', {
+                ...attrs,
+                'namzu.hook.problem': 'a replacement is named but the answer is not a JSON object on stdout',
+            });
+            return failed('its answer names a replacement but is not a JSON object that starts stdout');
+        }
         // 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' || event === 'session_start') &&
+        if ((event === 'user_prompt_submit' ||
+            event === 'subagent_start' ||
+            event === 'session_start' ||
+            event === 'pre_compact') &&
             text.length > 0)
             return { action: 'annotate', text };
         return { action: 'continue' };
@@ -871,6 +1131,8 @@ export function shellHookVerdict(event, entry, outcome, log = NOOP_LOGGER) {
                 };
         }
         case 'pre_compact':
+            // What the hook said is for the summariser: it rides as `context` on
+            // either answer (a refusal a forced pass overrides is still heard).
             return reading.block !== undefined
                 ? { action: 'skip', reason: reading.block, ...notes }
                 : { action: 'continue', ...notes };
@@ -1009,21 +1271,30 @@ export function createShellHook(event, configured, options) {
             if (spent)
                 return { action: 'continue' };
             // A notification is matched on its type; every other event on the tool.
-            const namesATool = !(event === 'notification' ||
+            const namesATool = !(event === 'pre_compact' ||
+                event === 'post_compact' ||
+                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
-                    : event === 'session_start'
-                        ? context.source
-                        : event === 'session_end'
-                            ? context.endReason
-                            : context.toolName;
-            if (!shellHookMatches(entry.matcher, subject, { tool: namesATool }))
+                : event === 'pre_compact' || event === 'post_compact'
+                    ? context.compaction?.trigger
+                    : event === 'subagent_start' || event === 'subagent_stop'
+                        ? context.agentType
+                        : event === 'session_start'
+                            ? context.source
+                            : event === 'session_end'
+                                ? context.endReason
+                                : context.toolName;
+            // An event that has no name to match (`turn_end`, `user_prompt_submit`,
+            // `turn_start`, `post_tool_batch`) ignores the matcher and the hook
+            // fires: a matcher cannot be read against a name that is not there, and
+            // a guard that never fires is the failure to avoid. The compaction
+            // events are matched on `trigger`.
+            if (subject !== undefined && !shellHookMatches(entry.matcher, subject, { tool: namesATool }))
                 return { action: 'continue' };
             if (!shellHookIfMatches(entry.if, context.toolName, context.toolInput, options.pathFilter)) {
                 return { action: 'continue' };
@@ -1050,6 +1321,8 @@ export function createShellHook(event, configured, options) {
                 ...(context.prompt !== undefined ? { prompt: context.prompt } : {}),
                 ...(context.compaction !== undefined ? { compaction: context.compaction } : {}),
                 ...(context.toolName !== undefined ? { toolName: context.toolName } : {}),
+                ...(entry.toolNames !== undefined ? { toolNames: entry.toolNames } : {}),
+                ...(context.toolCallId !== undefined ? { toolCallId: context.toolCallId } : {}),
                 ...(context.toolInput !== undefined ? { toolInput: context.toolInput } : {}),
                 ...(context.toolResult !== undefined
                     ? {
@@ -1067,9 +1340,16 @@ export function createShellHook(event, configured, options) {
                 ...(context.error !== undefined ? { error: context.error } : {}),
                 ...(context.notification !== undefined ? { notification: context.notification } : {}),
                 ...(context.stopHookActive === true ? { stopHookActive: true } : {}),
+                ...(context.lastAssistantMessage !== undefined
+                    ? { lastAssistantMessage: context.lastAssistantMessage }
+                    : {}),
                 ...(transcriptPath !== undefined ? { transcriptPath } : {}),
                 ...(permissionMode !== undefined ? { permissionMode } : {}),
             };
+            const verdictCall = {
+                ...(context.toolName !== undefined ? { toolName: context.toolName } : {}),
+                ...(context.toolInput !== undefined ? { toolInput: context.toolInput } : {}),
+            };
             if (entry.type === 'http') {
                 const response = await postHookJson({
                     url: entry.url,
@@ -1087,7 +1367,7 @@ export function createShellHook(event, configured, options) {
                     stdout: ok ? response.body : '',
                     stderr: ok ? '' : response.body.slice(0, 500),
                     ...(response.error !== undefined ? { spawnError: response.error } : {}),
-                }, log);
+                }, log, verdictCall);
             }
             if (entry.type === 'prompt') {
                 return judgePromptHook(event, entry, hookInput, options.judge, context.signal, log);
@@ -1097,14 +1377,21 @@ export function createShellHook(event, configured, options) {
                 // for it and its own failure is only written down.
                 void runShellHook(entry, hookInput)
                     .then((outcome) => {
-                    shellHookVerdict(event, entry, outcome, log);
+                    const verdict = shellHookVerdict(event, entry, outcome, log, verdictCall);
+                    if (verdict.action !== 'continue') {
+                        log.warn('an async hook answered, and its answer is not applied', {
+                            'namzu.hook.event': event,
+                            'namzu.hook.command': describeShellHook(entry),
+                            'namzu.hook.action': verdict.action,
+                        });
+                    }
                 })
                     .catch(() => undefined);
                 return { action: 'continue' };
             }
             const outcome = await runShellHook(entry, hookInput, context.signal);
             reportTimeout(outcome.timedOut);
-            return shellHookVerdict(event, entry, outcome, log);
+            return shellHookVerdict(event, entry, outcome, log, verdictCall);
         },
     };
 }