@goodfoot/agent-hooks 1.0.0

package/dist/agents/claude-code/tool-helpers.js

@@ -0,0 +1,840 @@
+/**
+ * Type guards and helper functions for Claude Code tool inputs.
+ *
+ * Provides safe type narrowing for tool inputs and utility functions
+ * for common patterns like file path extraction and content inspection.
+ * @example
+ * ```typescript
+ * import {
+ *   preToolUseHook,
+ *   preToolUseOutput,
+ *   isWriteTool,
+ *   getFilePath,
+ *   isTsFile,
+ *   checkContentForPattern
+ * } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default preToolUseHook({ matcher: 'Write|Edit|MultiEdit' }, (input) => {
+ *   const filePath = getFilePath(input);
+ *   if (!filePath || !isTsFile(filePath)) return preToolUseOutput({});
+ *
+ *   const result = checkContentForPattern(input, /@ts-expect-error/g);
+ *   if (result?.isAddition) {
+ *     return preToolUseOutput({
+ *       hookSpecificOutput: {
+ *         permissionDecision: 'deny',
+ *         permissionDecisionReason: `Cannot add: ${result.matches.join(', ')}`
+ *       }
+ *     });
+ *   }
+ *
+ *   return preToolUseOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks
+ * @module
+ */
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard for Write tool inputs.
+ *
+ * Narrows the input type to include a typed WriteToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Write tool
+ * @example
+ * ```typescript
+ * if (isWriteTool(input)) {
+ *   // input.tool_input is now typed as WriteToolInput
+ *   console.log(input.tool_input.file_path);
+ *   console.log(input.tool_input.content);
+ * }
+ * ```
+ */
+export function isWriteTool(input) {
+    return input.tool_name === "Write";
+}
+/**
+ * Type guard for Edit tool inputs.
+ *
+ * Narrows the input type to include a typed EditToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for an Edit tool
+ * @example
+ * ```typescript
+ * if (isEditTool(input)) {
+ *   console.log(input.tool_input.old_string);
+ *   console.log(input.tool_input.new_string);
+ * }
+ * ```
+ */
+export function isEditTool(input) {
+    return input.tool_name === "Edit";
+}
+/**
+ * Type guard for MultiEdit tool inputs.
+ *
+ * Narrows the input type to include a typed MultiEditToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a MultiEdit tool
+ * @example
+ * ```typescript
+ * if (isMultiEditTool(input)) {
+ *   for (const edit of input.tool_input.edits) {
+ *     console.log(`${edit.old_string} -> ${edit.new_string}`);
+ *   }
+ * }
+ * ```
+ */
+export function isMultiEditTool(input) {
+    return input.tool_name === "MultiEdit";
+}
+/**
+ * Type guard for any file-modifying tool (Write, Edit, or MultiEdit).
+ *
+ * Use this when you need to handle all file modifications generically.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Write, Edit, or MultiEdit tool
+ * @example
+ * ```typescript
+ * if (isFileModifyingTool(input)) {
+ *   const filePath = getFilePath(input); // Works for all three types
+ * }
+ * ```
+ */
+export function isFileModifyingTool(input) {
+    return input.tool_name === "Write" || input.tool_name === "Edit" || input.tool_name === "MultiEdit";
+}
+/**
+ * Type guard for Read tool inputs.
+ *
+ * Narrows the input type to include a typed ReadToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Read tool
+ * @example
+ * ```typescript
+ * if (isReadTool(input)) {
+ *   console.log(input.tool_input.file_path);
+ *   console.log(input.tool_input.offset);
+ * }
+ * ```
+ */
+export function isReadTool(input) {
+    return input.tool_name === "Read";
+}
+/**
+ * Type guard for Bash tool inputs.
+ *
+ * Narrows the input type to include a typed BashToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Bash tool
+ * @example
+ * ```typescript
+ * if (isBashTool(input)) {
+ *   console.log(input.tool_input.command);
+ *   console.log(input.tool_input.timeout);
+ * }
+ * ```
+ */
+export function isBashTool(input) {
+    return input.tool_name === "Bash";
+}
+/**
+ * Type guard for Glob tool inputs.
+ *
+ * Narrows the input type to include a typed GlobToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Glob tool
+ * @example
+ * ```typescript
+ * if (isGlobTool(input)) {
+ *   console.log(input.tool_input.pattern);
+ *   console.log(input.tool_input.path);
+ * }
+ * ```
+ */
+export function isGlobTool(input) {
+    return input.tool_name === "Glob";
+}
+/**
+ * Type guard for Grep tool inputs.
+ *
+ * Narrows the input type to include a typed GrepToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Grep tool
+ * @example
+ * ```typescript
+ * if (isGrepTool(input)) {
+ *   console.log(input.tool_input.pattern);
+ *   console.log(input.tool_input.glob);
+ * }
+ * ```
+ */
+export function isGrepTool(input) {
+    return input.tool_name === "Grep";
+}
+/**
+ * Type guard for Agent tool inputs.
+ *
+ * Narrows the input type to include a typed AgentInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for an Agent tool
+ * @example
+ * ```typescript
+ * if (isTaskTool(input)) {
+ *   console.log(input.tool_input.prompt);
+ *   console.log(input.tool_input.subagent_type);
+ * }
+ * ```
+ */
+export function isTaskTool(input) {
+    return input.tool_name === "Agent";
+}
+/**
+ * Type guard for TaskOutput tool inputs.
+ *
+ * Narrows the input type to include a typed TaskOutputInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a TaskOutput tool
+ * @example
+ * ```typescript
+ * if (isTaskOutputTool(input)) {
+ *   console.log(input.tool_input.task_id);
+ * }
+ * ```
+ */
+export function isTaskOutputTool(input) {
+    return input.tool_name === "TaskOutput";
+}
+/**
+ * Type guard for ExitPlanMode tool inputs.
+ *
+ * Narrows the input type to include a typed ExitPlanModeInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for an ExitPlanMode tool
+ * @example
+ * ```typescript
+ * if (isExitPlanModeTool(input)) {
+ *   console.log(input.tool_input.allowedPrompts);
+ * }
+ * ```
+ */
+export function isExitPlanModeTool(input) {
+    return input.tool_name === "ExitPlanMode";
+}
+/**
+ * Type guard for KillShell tool inputs.
+ *
+ * Narrows the input type to include a typed KillShellInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a KillShell tool
+ * @example
+ * ```typescript
+ * if (isKillShellTool(input)) {
+ *   console.log(input.tool_input.shell_id);
+ * }
+ * ```
+ */
+export function isKillShellTool(input) {
+    return input.tool_name === "KillShell";
+}
+/**
+ * Type guard for NotebookEdit tool inputs.
+ *
+ * Narrows the input type to include a typed NotebookEditInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a NotebookEdit tool
+ * @example
+ * ```typescript
+ * if (isNotebookEditTool(input)) {
+ *   console.log(input.tool_input.notebook_path);
+ *   console.log(input.tool_input.new_source);
+ * }
+ * ```
+ */
+export function isNotebookEditTool(input) {
+    return input.tool_name === "NotebookEdit";
+}
+/**
+ * Type guard for TodoWrite tool inputs.
+ *
+ * Narrows the input type to include a typed TodoWriteInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a TodoWrite tool
+ * @example
+ * ```typescript
+ * if (isTodoWriteTool(input)) {
+ *   console.log(input.tool_input.todos);
+ * }
+ * ```
+ */
+export function isTodoWriteTool(input) {
+    return input.tool_name === "TodoWrite";
+}
+/**
+ * Type guard for WebFetch tool inputs.
+ *
+ * Narrows the input type to include a typed WebFetchInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a WebFetch tool
+ * @example
+ * ```typescript
+ * if (isWebFetchTool(input)) {
+ *   console.log(input.tool_input.url);
+ *   console.log(input.tool_input.prompt);
+ * }
+ * ```
+ */
+export function isWebFetchTool(input) {
+    return input.tool_name === "WebFetch";
+}
+/**
+ * Type guard for WebSearch tool inputs.
+ *
+ * Narrows the input type to include a typed WebSearchInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a WebSearch tool
+ * @example
+ * ```typescript
+ * if (isWebSearchTool(input)) {
+ *   console.log(input.tool_input.query);
+ * }
+ * ```
+ */
+export function isWebSearchTool(input) {
+    return input.tool_name === "WebSearch";
+}
+/**
+ * Type guard for AskUserQuestion tool inputs.
+ *
+ * Narrows the input type to include a typed AskUserQuestionInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for an AskUserQuestion tool
+ * @example
+ * ```typescript
+ * if (isAskUserQuestionTool(input)) {
+ *   console.log(input.tool_input.questions);
+ * }
+ * ```
+ */
+export function isAskUserQuestionTool(input) {
+    return input.tool_name === "AskUserQuestion";
+}
+/**
+ * Type guard for ListMcpResources tool inputs.
+ *
+ * Narrows the input type to include a typed ListMcpResourcesInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a ListMcpResources tool
+ * @example
+ * ```typescript
+ * if (isListMcpResourcesTool(input)) {
+ *   console.log(input.tool_input.server);
+ * }
+ * ```
+ */
+export function isListMcpResourcesTool(input) {
+    return input.tool_name === "ListMcpResources";
+}
+/**
+ * Type guard for Mcp tool inputs.
+ *
+ * Narrows the input type to include a typed McpInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for an Mcp tool
+ * @example
+ * ```typescript
+ * if (isMcpTool(input)) {
+ *   // input.tool_input is now typed as McpInput
+ * }
+ * ```
+ */
+export function isMcpTool(input) {
+    return input.tool_name === "Mcp";
+}
+/**
+ * Type guard for ReadMcpResource tool inputs.
+ *
+ * Narrows the input type to include a typed ReadMcpResourceInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a ReadMcpResource tool
+ * @example
+ * ```typescript
+ * if (isReadMcpResourceTool(input)) {
+ *   console.log(input.tool_input.server);
+ *   console.log(input.tool_input.uri);
+ * }
+ * ```
+ */
+export function isReadMcpResourceTool(input) {
+    return input.tool_name === "ReadMcpResource";
+}
+/**
+ * Type guard for Config tool inputs.
+ *
+ * Narrows the input type to include a typed ConfigInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Config tool
+ * @example
+ * ```typescript
+ * if (isConfigTool(input)) {
+ *   console.log(input.tool_input.setting);
+ *   console.log(input.tool_input.value);
+ * }
+ * ```
+ */
+export function isConfigTool(input) {
+    return input.tool_name === "Config";
+}
+/**
+ * Type guard for TaskCreate tool inputs.
+ *
+ * Narrows the input type to include a typed TaskCreateInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a TaskCreate tool
+ * @example
+ * ```typescript
+ * if (isTaskCreateTool(input)) {
+ *   console.log(input.tool_input.subject);
+ * }
+ * ```
+ */
+export function isTaskCreateTool(input) {
+    return input.tool_name === "TaskCreate";
+}
+/**
+ * Type guard for TaskGet tool inputs.
+ *
+ * Narrows the input type to include a typed TaskGetInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a TaskGet tool
+ * @example
+ * ```typescript
+ * if (isTaskGetTool(input)) {
+ *   console.log(input.tool_input.taskId);
+ * }
+ * ```
+ */
+export function isTaskGetTool(input) {
+    return input.tool_name === "TaskGet";
+}
+/**
+ * Type guard for TaskList tool inputs.
+ *
+ * Narrows the input type to include a typed TaskListInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a TaskList tool
+ * @example
+ * ```typescript
+ * if (isTaskListTool(input)) {
+ *   // input.tool_input is now typed as TaskListInput
+ * }
+ * ```
+ */
+export function isTaskListTool(input) {
+    return input.tool_name === "TaskList";
+}
+/**
+ * Type guard for TaskUpdate tool inputs.
+ *
+ * Narrows the input type to include a typed TaskUpdateInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a TaskUpdate tool
+ * @example
+ * ```typescript
+ * if (isTaskUpdateTool(input)) {
+ *   console.log(input.tool_input.taskId, input.tool_input.status);
+ * }
+ * ```
+ */
+export function isTaskUpdateTool(input) {
+    return input.tool_name === "TaskUpdate";
+}
+/**
+ * Type guard for CronCreate tool inputs.
+ *
+ * Narrows the input type to include a typed CronCreateInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a CronCreate tool
+ * @example
+ * ```typescript
+ * if (isCronCreateTool(input)) {
+ *   console.log(input.tool_input.cron, input.tool_input.prompt);
+ * }
+ * ```
+ */
+export function isCronCreateTool(input) {
+    return input.tool_name === "CronCreate";
+}
+/**
+ * Type guard for CronDelete tool inputs.
+ *
+ * Narrows the input type to include a typed CronDeleteInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a CronDelete tool
+ * @example
+ * ```typescript
+ * if (isCronDeleteTool(input)) {
+ *   console.log(input.tool_input.id);
+ * }
+ * ```
+ */
+export function isCronDeleteTool(input) {
+    return input.tool_name === "CronDelete";
+}
+/**
+ * Type guard for CronList tool inputs.
+ *
+ * Narrows the input type to include a typed CronListInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a CronList tool
+ * @example
+ * ```typescript
+ * if (isCronListTool(input)) {
+ *   // input.tool_input is now typed as CronListInput
+ * }
+ * ```
+ */
+export function isCronListTool(input) {
+    return input.tool_name === "CronList";
+}
+/**
+ * Type guard for ScheduleWakeup tool inputs.
+ *
+ * Narrows the input type to include a typed ScheduleWakeupInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a ScheduleWakeup tool
+ * @example
+ * ```typescript
+ * if (isScheduleWakeupTool(input)) {
+ *   console.log(input.tool_input.delaySeconds);
+ * }
+ * ```
+ */
+export function isScheduleWakeupTool(input) {
+    return input.tool_name === "ScheduleWakeup";
+}
+/**
+ * Type guard for Monitor tool inputs.
+ *
+ * Narrows the input type to include a typed MonitorInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Monitor tool
+ * @example
+ * ```typescript
+ * if (isMonitorTool(input)) {
+ *   console.log(input.tool_input.command);
+ * }
+ * ```
+ */
+export function isMonitorTool(input) {
+    return input.tool_name === "Monitor";
+}
+/**
+ * Type guard for RemoteTrigger tool inputs.
+ *
+ * Narrows the input type to include a typed RemoteTriggerInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a RemoteTrigger tool
+ * @example
+ * ```typescript
+ * if (isRemoteTriggerTool(input)) {
+ *   console.log(input.tool_input.action);
+ * }
+ * ```
+ */
+export function isRemoteTriggerTool(input) {
+    return input.tool_name === "RemoteTrigger";
+}
+/**
+ * Type guard for PushNotification tool inputs.
+ *
+ * Narrows the input type to include a typed PushNotificationInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a PushNotification tool
+ * @example
+ * ```typescript
+ * if (isPushNotificationTool(input)) {
+ *   console.log(input.tool_input.message);
+ * }
+ * ```
+ */
+export function isPushNotificationTool(input) {
+    return input.tool_name === "PushNotification";
+}
+/**
+ * Type guard for EnterPlanMode tool inputs.
+ *
+ * Narrows the input type to include a typed EnterPlanModeInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for an EnterPlanMode tool
+ * @example
+ * ```typescript
+ * if (isEnterPlanModeTool(input)) {
+ *   // input.tool_input is now typed as EnterPlanModeInput
+ * }
+ * ```
+ */
+export function isEnterPlanModeTool(input) {
+    return input.tool_name === "EnterPlanMode";
+}
+/**
+ * Type guard for EnterWorktree tool inputs.
+ *
+ * Narrows the input type to include a typed EnterWorktreeInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for an EnterWorktree tool
+ * @example
+ * ```typescript
+ * if (isEnterWorktreeTool(input)) {
+ *   console.log(input.tool_input.name);
+ * }
+ * ```
+ */
+export function isEnterWorktreeTool(input) {
+    return input.tool_name === "EnterWorktree";
+}
+/**
+ * Type guard for ExitWorktree tool inputs.
+ *
+ * Narrows the input type to include a typed ExitWorktreeInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for an ExitWorktree tool
+ * @example
+ * ```typescript
+ * if (isExitWorktreeTool(input)) {
+ *   console.log(input.tool_input.action);
+ * }
+ * ```
+ */
+export function isExitWorktreeTool(input) {
+    return input.tool_name === "ExitWorktree";
+}
+/**
+ * Type guard for REPL tool inputs.
+ *
+ * Narrows the input type to include a typed REPLInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a REPL tool
+ * @example
+ * ```typescript
+ * if (isReplTool(input)) {
+ *   console.log(input.tool_input.code);
+ * }
+ * ```
+ */
+export function isReplTool(input) {
+    return input.tool_name === "REPL";
+}
+/**
+ * Type guard for Workflow tool inputs.
+ *
+ * Narrows the input type to include a typed WorkflowInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Workflow tool
+ * @example
+ * ```typescript
+ * if (isWorkflowTool(input)) {
+ *   console.log(input.tool_input.name);
+ * }
+ * ```
+ */
+export function isWorkflowTool(input) {
+    return input.tool_name === "Workflow";
+}
+// ============================================================================
+// File Path Utilities
+// ============================================================================
+/**
+ * Extracts the file path from a tool input.
+ *
+ * Works with Write, Edit, MultiEdit, and Read tools.
+ * Returns null for other tools or if file_path is missing.
+ * @param input - The hook input to extract from
+ * @returns The file path, or null if not applicable
+ * @example
+ * ```typescript
+ * const filePath = getFilePath(input);
+ * if (filePath && isTsFile(filePath)) {
+ *   // Handle TypeScript file
+ * }
+ * ```
+ */
+export function getFilePath(input) {
+    const toolInput = input.tool_input;
+    if (toolInput && typeof toolInput === "object" && "file_path" in toolInput) {
+        const filePath = toolInput.file_path;
+        return typeof filePath === "string" ? filePath : null;
+    }
+    return null;
+}
+/**
+ * Checks if a file path is a JavaScript or TypeScript file.
+ *
+ * Matches .js, .jsx, .ts, .tsx, .mjs, .mts, .cjs, .cts extensions.
+ * @param filePath - The file path to check
+ * @returns True if the file is JavaScript or TypeScript
+ * @example
+ * ```typescript
+ * if (isJsTsFile(filePath)) {
+ *   // Check for TypeScript-specific patterns
+ * }
+ * ```
+ */
+export function isJsTsFile(filePath) {
+    return /\.[cm]?[jt]sx?$/.test(filePath);
+}
+/**
+ * Checks if a file path is a TypeScript file.
+ *
+ * Matches .ts, .tsx, .mts, .cts extensions.
+ * @param filePath - The file path to check
+ * @returns True if the file is TypeScript
+ * @example
+ * ```typescript
+ * if (isTsFile(filePath)) {
+ *   // Enforce TypeScript-specific rules
+ * }
+ * ```
+ */
+export function isTsFile(filePath) {
+    return /\.[cm]?tsx?$/.test(filePath);
+}
+/**
+ * Checks if a pattern exists in the content being written or edited.
+ *
+ * For Write: checks the content being written
+ * For Edit: checks new_string (and old_string to detect additions)
+ * For MultiEdit: checks all edits and aggregates results
+ * @param input - The PreToolUse hook input
+ * @param pattern - The regex pattern to search for (global flag will be used)
+ * @returns Result object, or null if not a file-modifying tool
+ * @example
+ * ```typescript
+ * // Block @ts-expect-error being added
+ * const result = checkContentForPattern(input, /@ts-expect-error/g);
+ * if (result?.isAddition) {
+ *   return preToolUseOutput({
+ *     hookSpecificOutput: {
+ *       permissionDecision: 'deny',
+ *       permissionDecisionReason: `Cannot add: ${result.matches.join(', ')}`
+ *     }
+ *   });
+ * }
+ * ```
+ */
+export function checkContentForPattern(input, pattern) {
+    // Ensure pattern has global flag for matchAll
+    const globalPattern = pattern.global ? pattern : new RegExp(pattern.source, `${pattern.flags}g`);
+    if (isWriteTool(input)) {
+        const matches = [...input.tool_input.content.matchAll(globalPattern)].map((m) => m[0]);
+        const uniqueMatches = [...new Set(matches)];
+        return {
+            found: uniqueMatches.length > 0,
+            isAddition: uniqueMatches.length > 0, // For Write, any match is an addition
+            matches: uniqueMatches,
+        };
+    }
+    if (isEditTool(input)) {
+        const newMatches = [...input.tool_input.new_string.matchAll(globalPattern)].map((m) => m[0]);
+        const oldMatches = [...input.tool_input.old_string.matchAll(globalPattern)].map((m) => m[0]);
+        const uniqueNewMatches = [...new Set(newMatches)];
+        const uniqueOldMatches = new Set(oldMatches);
+        // Addition = found in new but not in old
+        const additions = uniqueNewMatches.filter((m) => !uniqueOldMatches.has(m));
+        return {
+            found: uniqueNewMatches.length > 0,
+            isAddition: additions.length > 0,
+            matches: uniqueNewMatches,
+        };
+    }
+    if (isMultiEditTool(input)) {
+        const details = [];
+        const allMatches = new Set();
+        let anyFound = false;
+        let anyAddition = false;
+        for (let i = 0; i < input.tool_input.edits.length; i++) {
+            const edit = input.tool_input.edits[i];
+            const newMatches = [...edit.new_string.matchAll(globalPattern)].map((m) => m[0]);
+            const oldMatches = [...edit.old_string.matchAll(globalPattern)].map((m) => m[0]);
+            const uniqueNewMatches = [...new Set(newMatches)];
+            const uniqueOldMatches = new Set(oldMatches);
+            const additions = uniqueNewMatches.filter((m) => !uniqueOldMatches.has(m));
+            const found = uniqueNewMatches.length > 0;
+            const isAddition = additions.length > 0;
+            if (found)
+                anyFound = true;
+            if (isAddition)
+                anyAddition = true;
+            for (const m of uniqueNewMatches) {
+                allMatches.add(m);
+            }
+            details.push({
+                index: i,
+                found,
+                isAddition,
+                matches: uniqueNewMatches,
+            });
+        }
+        return {
+            found: anyFound,
+            isAddition: anyAddition,
+            matches: [...allMatches],
+            details,
+        };
+    }
+    return null;
+}
+/**
+ * Iterates over content in Write/Edit/MultiEdit operations.
+ *
+ * Provides a unified way to inspect content regardless of operation type.
+ * Return false from the callback to stop iteration early.
+ * @param input - The PreToolUse hook input
+ * @param callback - Function called for each content piece, return false to stop
+ * @returns True if all callbacks returned true, false if stopped early or not applicable
+ * @example
+ * ```typescript
+ * // Check all content for sensitive data
+ * const hasSensitive = !forEachContent(input, ({ newContent }) => {
+ *   if (/password|secret|api.?key/i.test(newContent)) {
+ *     return false; // Stop - found sensitive data
+ *   }
+ *   return true; // Continue
+ * });
+ * ```
+ */
+export function forEachContent(input, callback) {
+    if (isWriteTool(input)) {
+        return callback({
+            newContent: input.tool_input.content,
+            oldContent: null,
+            index: 0,
+            isWrite: true,
+        });
+    }
+    if (isEditTool(input)) {
+        return callback({
+            newContent: input.tool_input.new_string,
+            oldContent: input.tool_input.old_string,
+            index: 0,
+            isWrite: false,
+        });
+    }
+    if (isMultiEditTool(input)) {
+        for (let i = 0; i < input.tool_input.edits.length; i++) {
+            const edit = input.tool_input.edits[i];
+            const shouldContinue = callback({
+                newContent: edit.new_string,
+                oldContent: edit.old_string,
+                index: i,
+                isWrite: false,
+            });
+            if (!shouldContinue)
+                return false;
+        }
+        return true;
+    }
+    return false;
+}