@jmylchreest/aide-plugin 0.1.0 → 0.1.2

package/src/hooks/tool-observe.ts

@@ -1,18 +1,27 @@
 #!/usr/bin/env node
 /**
- * Tool Observe Hook (PostToolUse)
+ * Tool Observe Hook (PostToolUse + PostToolUseFailure)
  *
  * Single-purpose: record every Claude-native tool invocation as an
  * observe.KindToolCall event. Mirror image of the MCP middleware on the Go
  * side — together they give the dashboard complete tool-call coverage.
  *
+ * Claude Code fires PostToolUse only on success and PostToolUseFailure on
+ * failure (the latter carries top-level is_error/error/exit_code). This hook is
+ * registered for BOTH so failed tool calls are recorded with their error text —
+ * the signal the friction detector reads.
+ *
  * All taxonomy (tool → category/subtype) and the recording itself live in
  * src/core/tool-observe.ts so the OpenCode tool.execute.after handler can
  * reuse the same logic.
  */
 
-import { readStdin } from "../lib/hook-utils.js";
-import { findAideBinary } from "../core/aide-client.js";
+import {
+  readStdin,
+  emitHookResult,
+  installHookSafetyNet,
+  findAideBinary,
+} from "../lib/hook-utils.js";
 import { recordToolEvent } from "../core/tool-observe.js";
 import { debug } from "../lib/logger.js";
 
@@ -28,50 +37,46 @@ interface HookInput {
   // Claude Code passes the tool's actual output payload as tool_response.
   // Shape varies per tool (string for Bash, object for others).
   tool_response?: unknown;
-}
-
-function outputContinue(): void {
-  try {
-    console.log(JSON.stringify({ continue: true }));
-  } catch {
-    console.log('{"continue":true}');
-  }
+  // PostToolUseFailure-only fields: the harness flags the failure at the top
+  // level (PostToolUse never sets these — it only fires on success).
+  is_error?: boolean;
+  error?: string;
+  exit_code?: number;
 }
 
 async function main(): Promise<void> {
   try {
     const input = await readStdin();
     if (!input.trim()) {
-      outputContinue();
+      emitHookResult();
       return;
     }
     const data: HookInput = JSON.parse(input);
     const cwd = data.cwd || process.cwd();
     const toolName = data.tool_name;
     if (!toolName) {
-      outputContinue();
+      emitHookResult();
       return;
     }
-    const binary = findAideBinary({
-      cwd,
-      pluginRoot:
-        process.env.AIDE_PLUGIN_ROOT || process.env.CLAUDE_PLUGIN_ROOT,
-    });
+    const binary = findAideBinary(cwd);
     if (!binary) {
-      outputContinue();
+      emitHookResult();
       return;
     }
     recordToolEvent(binary, cwd, {
       toolName,
       toolInput: data.tool_input as ToolInput,
       toolResponse: data.tool_response,
-      success: data.tool_result?.success,
+      // PostToolUseFailure marks failure at the top level; PostToolUse omits
+      // these (success only). Map both into the shared recorder.
+      success: data.is_error === true ? false : data.tool_result?.success,
+      errorText: data.error,
       sessionId: data.session_id,
     });
   } catch (err) {
     debug(SOURCE, `Hook error: ${err}`);
   }
-  outputContinue();
+  emitHookResult();
 }
 
 type ToolInput = {
@@ -82,16 +87,6 @@ type ToolInput = {
   pattern?: string;
 };
 
-process.on("uncaughtException", (err) => {
-  debug(SOURCE, `UNCAUGHT EXCEPTION: ${err}`);
-  outputContinue();
-  process.exit(0);
-});
-
-process.on("unhandledRejection", (reason) => {
-  debug(SOURCE, `UNHANDLED REJECTION: ${reason}`);
-  outputContinue();
-  process.exit(0);
-});
+installHookSafetyNet(SOURCE);
 
 main();

package/src/hooks/tool-tracker.ts

@@ -6,9 +6,13 @@
  * Sets currentTool in aide-memory before tool execution.
  */
 
-import { readStdin } from "../lib/hook-utils.js";
+import {
+  readStdin,
+  emitHookResult,
+  installHookSafetyNet,
+  findAideBinary,
+} from "../lib/hook-utils.js";
 import { trackToolUse, formatToolDescription } from "../core/tool-tracking.js";
-import { findAideBinary } from "../core/aide-client.js";
 import { debug } from "../lib/logger.js";
 
 const SOURCE = "tool-tracker";
@@ -35,7 +39,7 @@ async function main(): Promise<void> {
   try {
     const input = await readStdin();
     if (!input.trim()) {
-      console.log(JSON.stringify({ continue: true }));
+      emitHookResult({ continue: true });
       return;
     }
 
@@ -45,11 +49,7 @@ async function main(): Promise<void> {
     const toolName = data.tool_name || "";
 
     if (agentId && toolName) {
-      const binary = findAideBinary({
-        cwd,
-        pluginRoot:
-          process.env.AIDE_PLUGIN_ROOT || process.env.CLAUDE_PLUGIN_ROOT,
-      });
+      const binary = findAideBinary(cwd);
 
       if (binary) {
         trackToolUse(binary, cwd, {
@@ -60,30 +60,13 @@ async function main(): Promise<void> {
       }
     }
 
-    console.log(JSON.stringify({ continue: true }));
+    emitHookResult({ continue: true });
   } catch (error) {
     debug(SOURCE, `Hook error: ${error}`);
-    console.log(JSON.stringify({ continue: true }));
+    emitHookResult({ continue: true });
   }
 }
 
-process.on("uncaughtException", (err) => {
-  debug(SOURCE, `UNCAUGHT EXCEPTION: ${err}`);
-  try {
-    console.log(JSON.stringify({ continue: true }));
-  } catch {
-    console.log('{"continue":true}');
-  }
-  process.exit(0);
-});
-process.on("unhandledRejection", (reason) => {
-  debug(SOURCE, `UNHANDLED REJECTION: ${reason}`);
-  try {
-    console.log(JSON.stringify({ continue: true }));
-  } catch {
-    console.log('{"continue":true}');
-  }
-  process.exit(0);
-});
+installHookSafetyNet(SOURCE);
 
 main();

package/src/hooks/write-guard.ts

@@ -9,10 +9,14 @@
  * Core logic is in src/core/write-guard.ts for cross-platform reuse.
  */
 
-import { readStdin } from "../lib/hook-utils.js";
+import {
+  readStdin,
+  emitHookResult,
+  installHookSafetyNet,
+  findAideBinary,
+} from "../lib/hook-utils.js";
 import { debug } from "../lib/logger.js";
 import { checkWriteGuard } from "../core/write-guard.js";
-import { findAideBinary } from "../core/aide-client.js";
 import { emitInjectionEvent } from "../core/read-tracking.js";
 
 const SOURCE = "write-guard";
@@ -42,7 +46,7 @@ async function main(): Promise<void> {
   try {
     const input = await readStdin();
     if (!input.trim()) {
-      console.log(JSON.stringify({ continue: true }));
+      emitHookResult({ continue: true });
       return;
     }
 
@@ -62,11 +66,7 @@ async function main(): Promise<void> {
         "";
       debug(SOURCE, `Advisory: Write to existing file: ${filePath}`);
       try {
-        const binary = findAideBinary({
-          cwd,
-          pluginRoot:
-            process.env.AIDE_PLUGIN_ROOT || process.env.CLAUDE_PLUGIN_ROOT,
-        });
+        const binary = findAideBinary(cwd);
         if (binary && result.message) {
           emitInjectionEvent(binary, cwd, {
             source: SOURCE,
@@ -86,33 +86,16 @@ async function main(): Promise<void> {
           additionalContext: result.message,
         },
       };
-      console.log(JSON.stringify(output));
+      emitHookResult(output);
     } else {
-      console.log(JSON.stringify({ continue: true }));
+      emitHookResult({ continue: true });
     }
   } catch (error) {
     debug(SOURCE, `Hook error: ${error}`);
-    console.log(JSON.stringify({ continue: true }));
+    emitHookResult({ continue: true });
   }
 }
 
-process.on("uncaughtException", (err) => {
-  debug(SOURCE, `UNCAUGHT EXCEPTION: ${err}`);
-  try {
-    console.log(JSON.stringify({ continue: true }));
-  } catch {
-    console.log('{"continue":true}');
-  }
-  process.exit(0);
-});
-process.on("unhandledRejection", (reason) => {
-  debug(SOURCE, `UNHANDLED REJECTION: ${reason}`);
-  try {
-    console.log(JSON.stringify({ continue: true }));
-  } catch {
-    console.log('{"continue":true}');
-  }
-  process.exit(0);
-});
+installHookSafetyNet(SOURCE);
 
 main();

package/src/lib/hook-utils.ts

@@ -16,9 +16,57 @@ import {
   sanitizeForLog,
   shellEscape,
 } from "../core/aide-client.js";
+import { debug } from "./logger.js";
 
 export { sanitizeForLog, shellEscape };
 
+/**
+ * A hook's JSON result object (printed to stdout for the harness). Typed as
+ * `object` rather than `Record<string, unknown>` so callers can pass their own
+ * named result interfaces (interfaces lack the implicit index signature
+ * `Record` requires).
+ */
+export type HookResult = object;
+
+/**
+ * Serialise and print a hook result as exactly one JSON line on stdout, with a
+ * raw-string fallback if serialisation itself throws. Defaults to
+ * `{continue:true}` — the fail-open result a hook emits when it has nothing
+ * specific to say. Callers needing a different shape (e.g. `{}` or a permission
+ * decision) pass it explicitly: the output decision stays with the caller, this
+ * helper only guarantees a single, always-valid line.
+ */
+export function emitHookResult(result: HookResult = { continue: true }): void {
+  try {
+    console.log(JSON.stringify(result));
+  } catch {
+    console.log('{"continue":true}');
+  }
+}
+
+/**
+ * Register process-level last-resort handlers so an uncaught error or rejection
+ * still emits a valid hook result (fail-open) instead of crashing with no
+ * output. `fallback` is the result emitted on crash (default `{continue:true}`).
+ * Replaces the identical uncaughtException/unhandledRejection block that was
+ * copy-pasted across every hook.
+ */
+export function installHookSafetyNet(
+  source: string,
+  fallback: HookResult = { continue: true },
+): void {
+  process.on("uncaughtException", (err) => {
+    debug(source, `UNCAUGHT EXCEPTION: ${err}`);
+    emitHookResult(fallback);
+    process.exit(0);
+  });
+  process.on("unhandledRejection", (reason) => {
+    debug(source, `UNHANDLED REJECTION: ${reason}`);
+    emitHookResult(fallback);
+    process.exit(0);
+  });
+}
+
 /** Maximum stdin payload size: 50 MiB. Prevents unbounded memory allocation. */
 const MAX_STDIN_BYTES = 50 * 1024 * 1024;
 

package/src/lib/project-root.ts

@@ -11,23 +11,24 @@
  *   1. AIDE_PROJECT_ROOT env override (must be an existing directory).
  *   2. Walk the full ancestry from cwd to /, collecting candidates, then
  *      prefer:
- *        a. Closest ancestor with BOTH .aide/ and a VCS marker
- *           (.git/.hg/.svn/.bzr/.fossil) — handles the common case where
- *           the canonical root sits at the git repo root.
- *        b. Closest ancestor with a VCS marker only — .aide/ will be
- *           created there if needed.
- *        c. Closest ancestor with .aide/ only — standalone projects with
+ *        a. Closest ancestor with a VCS marker (.git/.hg/.svn/.bzr/.fossil).
+ *           A VCS boundary — including a submodule, which is its own
+ *           repository — is the project boundary: starting inside a
+ *           submodule anchors the submodule, starting in the superproject
+ *           anchors the superproject. Worktree .git files resolve to the
+ *           main repo root (worktrees share one store); submodule .git
+ *           files anchor the submodule directory itself.
+ *        b. Closest ancestor with .aide/ only — standalone projects with
  *           no VCS.
  *      ~/.aide/ is skipped as a project marker unless cwd is $HOME.
  *   3. No marker found: return { root: cwd, hasMarker: false }.
  *
- * The "both markers wins" priority is what stops a stray child .aide/ from
- * shadowing the real project root: a sibling .aide/ created by an
- * accidental CLI invocation lives in a subdir with no .git/, so the walk
- * keeps going until it finds the parent that has both.
+ * A stray child .aide/ (created by an accidental CLI invocation from a
+ * subdir) cannot shadow the real project root: it has no VCS marker, so
+ * any real repository above it takes priority.
  */
 
-import { basename, dirname, join, resolve } from "path";
+import { basename, dirname, isAbsolute, join, resolve } from "path";
 import { existsSync, readFileSync, statSync } from "fs";
 import { homedir } from "os";
 
@@ -95,9 +96,6 @@ export function findProjectRoot(cwd: string): ProjectRootResult {
     dir = parent;
   }
 
-  for (const c of path) {
-    if (c.hasAide && c.hasVCS) return { root: c.vcsResolved, hasMarker: true };
-  }
   for (const c of path) {
     if (c.hasVCS) return { root: c.vcsResolved, hasMarker: true };
   }
@@ -141,12 +139,27 @@ export function walkUpForProjectRoot(startDir: string): string | null {
   return hasMarker ? root : null;
 }
 
+/**
+ * Reports whether a resolved gitdir path points into a superproject's
+ * .git/modules/ tree, i.e. the .git file belongs to a submodule checkout
+ * rather than a linked worktree.
+ */
+function isSubmoduleGitdir(gitdir: string): boolean {
+  const parts = gitdir.split(/[\\/]+/);
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (parts[i] === ".git" && parts[i + 1] === "modules") return true;
+  }
+  return false;
+}
+
 /**
  * Read a .git worktree file ("gitdir: <path>") and return the main repo root.
  *
  * Mirrors aide/cmd/aide/main.go:resolveWorktreeRoot(). The file's gitdir
  * normally points at "<main>/.git/worktrees/<name>"; we walk up that path
  * until we find a component named ".git" and return its parent.
+ * Submodule .git files (gitdir under .git/modules/) return null so the
+ * submodule directory itself becomes the root.
  */
 export function resolveWorktreeGitFile(gitFilePath: string): string | null {
   try {
@@ -154,10 +167,12 @@ export function resolveWorktreeGitFile(gitFilePath: string): string | null {
     if (!content.startsWith("gitdir:")) return null;
 
     let gitdir = content.slice("gitdir:".length).trim();
-    if (!gitdir.startsWith("/")) {
+    if (!isAbsolute(gitdir)) {
       gitdir = resolve(dirname(gitFilePath), gitdir);
     }
 
+    if (isSubmoduleGitdir(gitdir)) return null;
+
     let candidate = gitdir;
     for (;;) {
       const parent = dirname(candidate);