Merge pull request #2771 from MoerAI/fix/bash-file-read-guard

fix(hooks): add bash-file-read-guard to warn agents against cat/head/tail (fixes #2096)

src/hooks/bash-file-read-guard.ts

@@ -0,0 +1,44 @@
+import type { Hooks } from "@opencode-ai/plugin"
+
+import { log } from "../shared"
+
+const WARNING_MESSAGE = "Prefer the Read tool over `cat`/`head`/`tail` for reading file contents. The Read tool provides line numbers and hash anchors for precise editing."
+
+const FILE_READ_PATTERNS = [
+  /^\s*cat\s+(?!-)[^\s|&;]+\s*$/,
+  /^\s*head\s+(-n\s+\d+\s+)?(?!-)[^\s|&;]+\s*$/,
+  /^\s*tail\s+(-n\s+\d+\s+)?(?!-)[^\s|&;]+\s*$/,
+]
+
+function isSimpleFileReadCommand(command: string): boolean {
+  return FILE_READ_PATTERNS.some((pattern) => pattern.test(command))
+}
+
+export function createBashFileReadGuardHook(): Hooks {
+  return {
+    "tool.execute.before": async (
+      input: { tool: string; sessionID: string; callID: string },
+      output: { args: Record<string, unknown>; message?: string },
+    ): Promise<void> => {
+      if (input.tool.toLowerCase() !== "bash") {
+        return
+      }
+
+      const command = output.args.command
+      if (typeof command !== "string") {
+        return
+      }
+
+      if (!isSimpleFileReadCommand(command)) {
+        return
+      }
+
+      output.message = WARNING_MESSAGE
+
+      log("[bash-file-read-guard] warned on bash file read command", {
+        sessionID: input.sessionID,
+        command,
+      })
+    },
+  }
+}

src/hooks/index.ts

@@ -48,6 +48,7 @@ export { createPreemptiveCompactionHook } from "./preemptive-compaction";
 export { createTasksTodowriteDisablerHook } from "./tasks-todowrite-disabler";
 export { createRuntimeFallbackHook, type RuntimeFallbackHook, type RuntimeFallbackOptions } from "./runtime-fallback";
 export { createWriteExistingFileGuardHook } from "./write-existing-file-guard";
+export { createBashFileReadGuardHook } from "./bash-file-read-guard";
 export { createHashlineReadEnhancerHook } from "./hashline-read-enhancer";
 export { createJsonErrorRecoveryHook, JSON_ERROR_TOOL_EXCLUDE_LIST, JSON_ERROR_PATTERNS, JSON_ERROR_REMINDER } from "./json-error-recovery";
 export { createReadImageResizerHook } from "./read-image-resizer"