eagle-mem 4.10.13 → 4.12.0

package/integrations/opencode_eagle_mem_plugin.js

@@ -0,0 +1,387 @@
+// EAGLE_MEM_OPENCODE_PLUGIN
+// OpenCode local plugin bridge for Eagle Mem.
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+const HOOK_TIMEOUT_MS = 30000;
+const STOP_TIMEOUT_MS = 60000;
+
+function eagleHome() {
+  return process.env.EAGLE_MEM_DIR || join(homedir(), ".eagle-mem");
+}
+
+function hookPath(name) {
+  return join(eagleHome(), "hooks", `${name}.sh`);
+}
+
+function safeString(value) {
+  return typeof value === "string" ? value : "";
+}
+
+function projectName(input, directory) {
+  return safeString(input?.project?.name) || basename(directory || process.cwd()) || "unknown";
+}
+
+function normalizeToolName(tool) {
+  switch (safeString(tool).toLowerCase()) {
+    case "bash":
+    case "shell":
+      return "Bash";
+    case "read":
+      return "Read";
+    case "write":
+      return "Write";
+    case "edit":
+      return "Edit";
+    case "patch":
+    case "apply_patch":
+      return "apply_patch";
+    default:
+      return safeString(tool);
+  }
+}
+
+function toEagleToolInput(toolName, args = {}) {
+  const input = { ...args };
+  if (args.filePath !== undefined && input.file_path === undefined) {
+    input.file_path = args.filePath;
+  }
+  if (args.path !== undefined && input.file_path === undefined) {
+    input.file_path = args.path;
+  }
+  if (args.command !== undefined && input.command === undefined) {
+    input.command = args.command;
+  }
+  if (toolName === "apply_patch" && args.patch !== undefined && input.command === undefined) {
+    input.command = args.patch;
+  }
+  return input;
+}
+
+function fromEagleToolInput(updatedInput, originalArgs = {}) {
+  const next = { ...originalArgs };
+  for (const [key, value] of Object.entries(updatedInput || {})) {
+    if (key === "file_path") {
+      next.filePath = value;
+      continue;
+    }
+    next[key] = value;
+  }
+  return next;
+}
+
+function textFromParts(parts = []) {
+  return parts
+    .filter((part) => part && part.type === "text" && typeof part.text === "string")
+    .map((part) => part.text)
+    .join("\n")
+    .trim();
+}
+
+function parseHookSpecificOutput(stdout) {
+  const lines = safeString(stdout).split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    try {
+      const parsed = JSON.parse(lines[i]);
+      return parsed.hookSpecificOutput || parsed;
+    } catch {
+      // Keep scanning for the last JSON line.
+    }
+  }
+  return {};
+}
+
+function appendTextPart(output, text) {
+  const context = safeString(text).trim();
+  if (!context) return;
+
+  const message = output?.message || {};
+  if (!Array.isArray(output.parts)) output.parts = [];
+  output.parts.push({
+    id: `eagle-mem-${Date.now()}`,
+    sessionID: safeString(message.sessionID),
+    messageID: safeString(message.id),
+    type: "text",
+    text: `\n\n${context}`,
+    synthetic: true,
+    time: { start: Date.now() },
+    metadata: { source: "eagle-mem" },
+  });
+}
+
+function appendToolContext(output, text) {
+  const context = safeString(text).trim();
+  if (!context) return;
+
+  output.metadata = {
+    ...(output.metadata || {}),
+    eagleMemContext: context,
+  };
+  output.output = `${safeString(output.output)}\n\n${context}`.trim();
+}
+
+function runHook(name, payload, timeoutMs = HOOK_TIMEOUT_MS) {
+  const script = hookPath(name);
+  if (!existsSync(script)) {
+    return Promise.resolve({ stdout: "", stderr: "", code: 0, skipped: true });
+  }
+
+  return new Promise((resolve) => {
+    const child = spawn("bash", [script], {
+      env: {
+        ...process.env,
+        EAGLE_AGENT_SOURCE: "opencode",
+      },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let finished = false;
+    const timer = setTimeout(() => {
+      if (finished) return;
+      finished = true;
+      child.kill("SIGTERM");
+      resolve({ stdout, stderr: `${stderr}\nHook timed out: ${name}`.trim(), code: 124 });
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("close", (code) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      resolve({ stdout, stderr, code: code ?? 0 });
+    });
+    child.on("error", (error) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      resolve({ stdout, stderr: `${stderr}\n${error.message}`.trim(), code: 1 });
+    });
+
+    child.stdin.end(JSON.stringify(payload));
+  });
+}
+
+function baseHookPayload(ctx, sessionID, extra = {}) {
+  return {
+    session_id: sessionID,
+    cwd: ctx.directory,
+    workspace: {
+      current_dir: ctx.directory,
+      project_dir: ctx.directory,
+    },
+    project: projectName(ctx, ctx.directory),
+    agent: "opencode",
+    ...extra,
+  };
+}
+
+function taskID(sessionID, todo) {
+  return `opencode-${createHash("sha256")
+    .update(`${sessionID}:${todo?.content || ""}`)
+    .digest("hex")
+    .slice(0, 16)}`;
+}
+
+function normalizeTodoStatus(status) {
+  switch (safeString(status)) {
+    case "completed":
+    case "cancelled":
+    case "in_progress":
+    case "pending":
+      return status;
+    default:
+      return "pending";
+  }
+}
+
+export const EagleMemPlugin = async (ctx) => {
+  const startedSessions = new Set();
+  const messageRoles = new Map();
+  const textPartsByMessage = new Map();
+  const latestAssistantMessageBySession = new Map();
+
+  async function ensureSessionStarted(sessionID, source = "startup") {
+    if (!sessionID) return "";
+    const key = `${sessionID}:${source}`;
+    if (source === "startup" && startedSessions.has(key)) return "";
+    startedSessions.add(key);
+
+    const result = await runHook("session-start", baseHookPayload(ctx, sessionID, {
+      hook_event_name: "SessionStart",
+      source,
+      model: "opencode",
+    }));
+    const hookOutput = parseHookSpecificOutput(result.stdout);
+    return safeString(hookOutput.additionalContext);
+  }
+
+  async function runUserPromptSubmit(sessionID, prompt) {
+    if (!sessionID || !prompt) return "";
+    const result = await runHook("user-prompt-submit", baseHookPayload(ctx, sessionID, {
+      hook_event_name: "UserPromptSubmit",
+      prompt,
+    }));
+    const hookOutput = parseHookSpecificOutput(result.stdout);
+    return safeString(hookOutput.additionalContext);
+  }
+
+  async function mirrorTodos(sessionID, todos = []) {
+    for (const todo of todos) {
+      const sourceTaskID = taskID(sessionID, todo);
+      const subject = safeString(todo?.content).trim();
+      if (!subject) continue;
+
+      const status = normalizeTodoStatus(todo?.status);
+      const description = JSON.stringify({
+        priority: safeString(todo?.priority) || "medium",
+        status,
+        source: "opencode.todo.updated",
+      });
+
+      await runHook("post-tool-use", baseHookPayload(ctx, sessionID, {
+        hook_event_name: status === "completed" ? "TaskCompleted" : "TaskCreated",
+        task_id: sourceTaskID,
+        task_subject: subject,
+        task_description: description,
+      }));
+
+      await runHook("post-tool-use", baseHookPayload(ctx, sessionID, {
+        hook_event_name: "PostToolUse",
+        tool_name: "TaskUpdate",
+        tool_input: {
+          taskId: sourceTaskID,
+          status,
+        },
+      }));
+    }
+  }
+
+  function rememberMessage(message) {
+    if (!message?.id) return;
+    messageRoles.set(message.id, message.role);
+    const text = safeString(textPartsByMessage.get(message.id));
+    if (message.role === "assistant" && text) {
+      latestAssistantMessageBySession.set(message.sessionID, text);
+    }
+  }
+
+  function rememberPart(part) {
+    if (!part?.messageID || part.type !== "text") return;
+    textPartsByMessage.set(part.messageID, safeString(part.text));
+    if (messageRoles.get(part.messageID) === "assistant") {
+      latestAssistantMessageBySession.set(part.sessionID, safeString(part.text));
+    }
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (!event?.type) return;
+      const props = event.properties || {};
+      const sessionID = props.sessionID || props.info?.id;
+
+      if (event.type === "session.created") {
+        await ensureSessionStarted(sessionID, "startup");
+      }
+      if (event.type === "message.updated") {
+        rememberMessage(props.info);
+      }
+      if (event.type === "message.part.updated") {
+        rememberPart(props.part);
+      }
+      if (event.type === "todo.updated") {
+        await mirrorTodos(sessionID, props.todos || []);
+      }
+      if (event.type === "session.compacted") {
+        await ensureSessionStarted(sessionID, "compact");
+      }
+      if (event.type === "session.idle") {
+        await runHook("stop", baseHookPayload(ctx, sessionID, {
+          hook_event_name: "Stop",
+          agent_type: "main",
+          last_assistant_message: safeString(latestAssistantMessageBySession.get(sessionID)),
+        }), STOP_TIMEOUT_MS);
+      }
+      if (event.type === "session.deleted") {
+        await runHook("session-end", baseHookPayload(ctx, sessionID, {
+          hook_event_name: "SessionEnd",
+        }));
+      }
+    },
+
+    "chat.message": async (input, output) => {
+      const sessionID = input?.sessionID || output?.message?.sessionID;
+      const prompt = textFromParts(output?.parts || []);
+      const startupContext = await ensureSessionStarted(sessionID, "startup");
+      appendTextPart(output, startupContext);
+
+      const recallContext = await runUserPromptSubmit(sessionID, prompt);
+      appendTextPart(output, recallContext);
+    },
+
+    "tool.execute.before": async (input, output) => {
+      const sessionID = input?.sessionID;
+      const toolName = normalizeToolName(input?.tool);
+      await ensureSessionStarted(sessionID, "startup");
+
+      const payload = baseHookPayload(ctx, sessionID, {
+        hook_event_name: "PreToolUse",
+        tool_name: toolName,
+        tool_input: toEagleToolInput(toolName, output?.args || {}),
+      });
+      const result = await runHook("pre-tool-use", payload);
+      const hookOutput = parseHookSpecificOutput(result.stdout);
+      if (hookOutput.permissionDecision === "deny") {
+        throw new Error(hookOutput.permissionDecisionReason || "Eagle Mem denied this tool call");
+      }
+      if (hookOutput.updatedInput && output) {
+        output.args = fromEagleToolInput(hookOutput.updatedInput, output.args || {});
+      }
+    },
+
+    "tool.execute.after": async (input, output) => {
+      const sessionID = input?.sessionID;
+      const toolName = normalizeToolName(input?.tool);
+      const result = await runHook("post-tool-use", baseHookPayload(ctx, sessionID, {
+        hook_event_name: "PostToolUse",
+        tool_name: toolName,
+        tool_input: toEagleToolInput(toolName, input?.args || {}),
+        tool_response: {
+          stdout: safeString(output?.output),
+          metadata: output?.metadata || {},
+          title: safeString(output?.title),
+        },
+      }));
+      const hookOutput = parseHookSpecificOutput(result.stdout);
+      appendToolContext(output, hookOutput.additionalContext);
+    },
+
+    "shell.env": async (_input, output) => {
+      output.env = {
+        ...(output.env || {}),
+        EAGLE_AGENT_SOURCE: "opencode",
+        EAGLE_MEM_DIR: eagleHome(),
+      };
+    },
+
+    "experimental.session.compacting": async (input, output) => {
+      const sessionID = input?.sessionID;
+      const compactContext = await ensureSessionStarted(sessionID, "compact");
+      if (compactContext) {
+        if (!Array.isArray(output.context)) output.context = [];
+        output.context.push(`## Eagle Mem Compaction Context\n\n${compactContext}`);
+      }
+    },
+  };
+};
+
+export default EagleMemPlugin;

package/lib/codex-hooks.sh

@@ -27,7 +27,7 @@ eagle_enable_codex_hooks() {
     if [ ! -f "$config" ]; then
         cat > "$config" << 'TOML'
 [features]
-codex_hooks = true
+hooks = true
 TOML
         chmod 600 "$config" 2>/dev/null || true
         return 0
@@ -45,26 +45,33 @@ TOML
         }
         /^[[:space:]]*\[/ && in_features {
             if (!saw_flag && !inserted) {
-                print "codex_hooks = true"
+                print "hooks = true"
                 inserted=1
             }
             in_features=0
         }
-        in_features && /^[[:space:]]*codex_hooks[[:space:]]*=/ {
-            print "codex_hooks = true"
+        in_features && /^[[:space:]]*hooks[[:space:]]*=/ {
+            print "hooks = true"
             saw_flag=1
             next
         }
+        in_features && /^[[:space:]]*codex_hooks[[:space:]]*=/ {
+            if (!saw_flag && !inserted) {
+                print "hooks = true"
+                saw_flag=1
+            }
+            next
+        }
         { print }
         END {
             if (in_features && !saw_flag && !inserted) {
-                print "codex_hooks = true"
+                print "hooks = true"
                 inserted=1
             }
             if (!saw_features) {
                 print ""
                 print "[features]"
-                print "codex_hooks = true"
+                print "hooks = true"
             }
         }
     ' "$config" > "$tmp" && mv "$tmp" "$config"

package/lib/common.sh

@@ -21,6 +21,11 @@ EAGLE_CODEX_SKILLS_DIR="${EAGLE_CODEX_SKILLS_DIR:-$EAGLE_CODEX_DIR/skills}"
 EAGLE_CODEX_MEMORIES_DIR="${EAGLE_CODEX_MEMORIES_DIR:-$EAGLE_CODEX_DIR/memories}"
 EAGLE_GROK_DIR="${EAGLE_GROK_DIR:-$HOME/.grok}"
 EAGLE_GROK_SKILLS_DIR="${EAGLE_GROK_SKILLS_DIR:-$HOME/.grok/skills}"
+EAGLE_OPENCODE_DIR="${EAGLE_OPENCODE_DIR:-$HOME/.config/opencode}"
+EAGLE_OPENCODE_CONFIG="${EAGLE_OPENCODE_CONFIG:-$EAGLE_OPENCODE_DIR/opencode.json}"
+EAGLE_OPENCODE_PLUGINS_DIR="${EAGLE_OPENCODE_PLUGINS_DIR:-$EAGLE_OPENCODE_DIR/plugins}"
+EAGLE_OPENCODE_PLUGIN="${EAGLE_OPENCODE_PLUGIN:-$EAGLE_OPENCODE_PLUGINS_DIR/eagle-mem.js}"
+EAGLE_OPENCODE_SKILLS_DIR="${EAGLE_OPENCODE_SKILLS_DIR:-$EAGLE_OPENCODE_DIR/skills}"
 EAGLE_RAW_BASH_UNLOCK="${EAGLE_RAW_BASH_UNLOCK:-/tmp/eagle-mem-raw-bash-unlock}"
 
 _eagle_sqlite_candidate_paths() {
@@ -103,6 +108,50 @@ eagle_require_sqlite_fts5() {
     return 1
 }
 
+eagle_squash_ws() {
+    tr '\n' ' ' | sed 's/[[:space:]][[:space:]]*/ /g; s/^ //; s/ $//'
+}
+
+eagle_db_integrity_status() {
+    local db_path="${1:-$EAGLE_MEM_DB}"
+    local sqlite_bin output rc detail first_line
+
+    if [ ! -f "$db_path" ]; then
+        printf 'missing|database file not found\n'
+        return 1
+    fi
+
+    sqlite_bin=$(eagle_sqlite_path)
+    if [ -z "$sqlite_bin" ]; then
+        printf 'unavailable|sqlite3 with FTS5 not found\n'
+        return 1
+    fi
+
+    output=$({
+        echo ".output /dev/null"
+        echo "PRAGMA busy_timeout=5000;"
+        echo ".output stdout"
+        echo "PRAGMA quick_check;"
+    } | "$sqlite_bin" "$db_path" 2>&1)
+    rc=$?
+    detail=$(printf '%s' "$output" | eagle_squash_ws)
+    [ -n "$detail" ] || detail="no integrity output"
+
+    if [ "$rc" -ne 0 ]; then
+        printf 'error|%s\n' "$detail"
+        return "$rc"
+    fi
+
+    first_line=$(printf '%s\n' "$output" | awk 'NF { print; exit }')
+    if [ "$first_line" = "ok" ]; then
+        printf 'ok|ok\n'
+        return 0
+    fi
+
+    printf 'failed|%s\n' "$detail"
+    return 1
+}
+
 eagle_log() {
     local level="$1"
     shift
@@ -895,6 +944,7 @@ eagle_agent_source_from_json() {
 
     case "$agent_field" in
         antigravity*) echo "antigravity"; return ;;
+        opencode*) echo "opencode"; return ;;
     esac
 
     case "$transcript_path" in
@@ -911,6 +961,7 @@ eagle_agent_label() {
     case "${1:-$(eagle_agent_source)}" in
         codex) echo "Codex" ;;
         antigravity*) echo "Antigravity" ;;
+        opencode) echo "OpenCode" ;;
         *) echo "Claude Code" ;;
     esac
 }
@@ -1516,6 +1567,7 @@ eagle_runtime_change_plan() {
     local package_dir="${2:-}"
     local claude_found="${3:-false}"
     local codex_found="${4:-false}"
+    local opencode_found="${5:-false}"
 
     echo ""
     echo -e "  ${BOLD:-}What will change${RESET:-}"
@@ -1549,6 +1601,15 @@ eagle_runtime_change_plan() {
         echo -e "    ${DIM:-}-> Codex not detected; Codex hooks/skills skipped${RESET:-}"
     fi
 
+    if [ "$opencode_found" = true ]; then
+        echo -e "    ${CYAN:-}->${RESET:-} Update OpenCode"
+        echo -e "       ${DIM:-}plugin:${RESET:-} $EAGLE_OPENCODE_PLUGIN"
+        echo -e "       ${DIM:-}skills:${RESET:-} $EAGLE_OPENCODE_SKILLS_DIR/eagle-mem-*"
+        echo -e "       ${DIM:-}mode:  ${RESET:-} global local plugin; OpenCode --pure disables external plugins"
+    else
+        echo -e "    ${DIM:-}-> OpenCode not detected; OpenCode plugin/skills skipped${RESET:-}"
+    fi
+
     if [ "$action" = "update" ]; then
         echo -e "    ${CYAN:-}->${RESET:-} Refresh installed version metadata"
     fi
@@ -1562,9 +1623,11 @@ eagle_uninstall_change_plan() {
     echo ""
     echo -e "    ${CYAN:-}->${RESET:-} Remove Claude hooks from $EAGLE_SETTINGS"
     echo -e "    ${CYAN:-}->${RESET:-} Remove Codex hooks from $EAGLE_CODEX_HOOKS"
+    echo -e "    ${CYAN:-}->${RESET:-} Remove Eagle Mem OpenCode plugin from $EAGLE_OPENCODE_PLUGIN"
     echo -e "    ${CYAN:-}->${RESET:-} Remove Eagle Mem skill links from:"
     echo -e "       ${DIM:-}$EAGLE_SKILLS_DIR${RESET:-}"
     echo -e "       ${DIM:-}$EAGLE_CODEX_SKILLS_DIR${RESET:-}"
+    echo -e "       ${DIM:-}$EAGLE_OPENCODE_SKILLS_DIR${RESET:-}"
     echo -e "    ${CYAN:-}->${RESET:-} Remove Eagle Mem instruction blocks from:"
     echo -e "       ${DIM:-}$HOME/.claude/CLAUDE.md${RESET:-}"
     echo -e "       ${DIM:-}$EAGLE_CODEX_AGENTS_MD${RESET:-}"
@@ -1830,16 +1893,19 @@ The person reading this transcript should experience natural, thoughtful, human
 
 The rich structured data still gets saved (so future sessions get excellent context and the anti-regression system keeps working), but it happens without making the transcript feel like you are reading a debug dump.
 
-**Recommended capture approaches (in order of preference):**
-- Best: Use `eagle-mem session save --summary "..."` or the equivalent capture skill/tool. The CLI writes the structured record cleanly; you only show the nice prose to the user.
-- Strong alternative: Put any machine block inside a collapsed `<details>` element so it is available for debugging but invisible by default.
-- Only as last resort: Emit the raw block at all — and only when the user has explicitly asked for technical output.
+**How to capture (clean, no raw blocks):**
+- When you wrap up substantive work, run this once via the shell — it is pre-approved and prints only a short confirmation. Fill the flags you have; omit the rest:
+  `eagle-mem session save --session-id <id> --request "..." --completed "..." --learned "..." --decisions "choice — why; choice — why" --gotchas "..." --next-steps "..." --key-files "path — role" --files-modified "a.ts,b.ts" --affected-features "..." --verified-features "..." --regression-risks "..."`
+  Your session id is injected by SessionStart; use it verbatim so the capture merges into the live session.
+- Then end with a short, human recap in prose, followed by one line: `**Eagle Mem** | Session captured — N decisions, M gotchas`.
+- NEVER print `<eagle-summary>` tags, XML, or raw field lists (`request:`/`completed:`/...) in the visible reply.
+- If you never run the CLI, the Stop hook still captures a summary automatically as a lower-fidelity fallback — so capture is never lost, it is just richer when you run the command.
 
 **Why this rule exists:** Every single session ends with a summary. If it looks technical, the entire conversation history slowly becomes unpleasant to read. The memory layer should make the experience of working with agents *more* human, not less.
 
 **How to apply:**
 - Write the visible recap in clear, narrative prose first.
-- Persist the structured details via tool or collapsed element — never as raw tags in the main reply.
+- Persist the structured details via the `session save` command — never as raw tags in the main reply.
 - Keep durable task descriptions truthful and up to date; they often carry more value across compactions than any one summary.
 - When Eagle Mem context appears, attribute it naturally.
 - Protect secrets. Update the durable record if you change direction.
@@ -1853,8 +1919,11 @@ eagle_patch_claude_md() {
     mkdir -p "$HOME/.claude"
 
     if [ -f "$claude_md" ] && grep -qF "$marker" "$claude_md" 2>/dev/null; then
-        # Check if section has outdated pipe-separated format
-        if grep -qF 'request: \[what user asked\] | completed:' "$claude_md" 2>/dev/null; then
+        # Rewrite when the section uses an outdated capture doctrine:
+        #   - the old pipe-separated <eagle-summary> template, or
+        #   - the superseded "collapsed <details>" recommendation (pre-CLI-first).
+        if grep -qF 'request: \[what user asked\] | completed:' "$claude_md" 2>/dev/null \
+            || grep -qF 'collapsed `<details>` element' "$claude_md" 2>/dev/null; then
             # Replace the outdated section: remove old, append new
             local tmp_md
             tmp_md=$(mktemp)
@@ -1902,6 +1971,7 @@ Eagle Mem hooks are active for Codex in this project. SessionStart and UserPromp
 - For broad multi-agent work, YOU run `eagle-mem orchestrate`; do not ask the user to run these commands
 - Codex does not currently expose a persistent custom statusline like Claude Code; if the user asks for Eagle Mem status, run `eagle-mem statusline`
 - For important decisions, preferences, gotchas, or durable project facts, include them briefly in normal prose. Eagle Mem will extract them from the transcript.
+- To persist a richer structured capture without printing anything raw, run once at wrap-up: `eagle-mem session save --agent codex --completed "..." --decisions "choice — why" --gotchas "..." --files-modified "a.ts,b.ts"` (fill what applies)
 - Do not revert Eagle Mem-surfaced decisions without asking the user
 - If Eagle Mem reports pending feature verification, verify or waive it before push/PR/publish
 - Never put raw secrets in summaries

package/lib/db-events.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Eagle Mem event log helpers.
+
+eagle_insert_event() {
+    local project="$1"
+    local session_id="$2"
+    local agent="$3"
+    local event_type="$4"
+    local command="${5:-}"
+    local hook_event_name="${6:-}"
+    local status="${7:-ok}"
+    local detail_json="${8:-}"
+    [ -n "$detail_json" ] || detail_json="{}"
+
+    [ -n "$event_type" ] || return 0
+    [ -f "$EAGLE_MEM_DB" ] || return 0
+
+    if [ -z "$(eagle_db "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'eagle_events' LIMIT 1;" 2>/dev/null || true)" ]; then
+        return 0
+    fi
+
+    detail_json=$(printf '%s' "$detail_json" | jq -c . 2>/dev/null || printf '{}')
+
+    local p_sql sid_sql agent_sql type_sql command_sql hook_sql status_sql detail_sql
+    p_sql=$(eagle_sql_escape "$project")
+    sid_sql=$(eagle_sql_escape "$session_id")
+    agent_sql=$(eagle_sql_escape "$agent")
+    type_sql=$(eagle_sql_escape "$event_type")
+    command_sql=$(eagle_sql_escape "$command")
+    hook_sql=$(eagle_sql_escape "$hook_event_name")
+    status_sql=$(eagle_sql_escape "$status")
+    detail_sql=$(eagle_sql_escape "$detail_json")
+
+    eagle_db "INSERT INTO eagle_events (
+                  project, session_id, agent, event_type, command,
+                  hook_event_name, status, detail_json
+              )
+              VALUES (
+                  '$p_sql', '$sid_sql', '$agent_sql', '$type_sql', '$command_sql',
+                  '$hook_sql', '$status_sql', '$detail_sql'
+              );" >/dev/null 2>&1 || true
+}
+
+eagle_hook_observability_begin() {
+    local input="$1"
+    local default_hook="$2"
+
+    EAGLE_EVENT_HOOK_NAME=$(printf '%s' "$input" | jq -r '.hook_event_name // empty' 2>/dev/null)
+    [ -n "$EAGLE_EVENT_HOOK_NAME" ] || EAGLE_EVENT_HOOK_NAME="$default_hook"
+    EAGLE_EVENT_SESSION_ID=$(printf '%s' "$input" | jq -r '.session_id // empty' 2>/dev/null)
+    EAGLE_EVENT_CWD=$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null)
+    EAGLE_EVENT_TOOL_NAME=$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null)
+    EAGLE_EVENT_AGENT=$(eagle_agent_source_from_json "$input")
+    EAGLE_EVENT_PROJECT=$(eagle_project_from_hook_input "$input")
+    EAGLE_EVENT_COMPLETION_DETAIL="{}"
+
+    [ -n "$EAGLE_EVENT_PROJECT" ] || return 0
+
+    local detail
+    detail=$(jq -nc \
+        --arg cwd "$EAGLE_EVENT_CWD" \
+        --arg tool "$EAGLE_EVENT_TOOL_NAME" \
+        '{cwd:$cwd, tool_name:$tool}')
+    eagle_insert_event "$EAGLE_EVENT_PROJECT" "$EAGLE_EVENT_SESSION_ID" "$EAGLE_EVENT_AGENT" "hook_started" "" "$EAGLE_EVENT_HOOK_NAME" "ok" "$detail"
+}
+
+eagle_hook_observability_set_detail() {
+    local detail_json="${1:-}"
+    [ -n "$detail_json" ] || detail_json="{}"
+    EAGLE_EVENT_COMPLETION_DETAIL=$(printf '%s' "$detail_json" | jq -c . 2>/dev/null || printf '{}')
+}
+
+eagle_hook_observability_complete() {
+    local rc="${1:-0}"
+    [ -n "${EAGLE_EVENT_PROJECT:-}" ] || return 0
+
+    local status="ok"
+    [ "$rc" -ne 0 ] 2>/dev/null && status="error"
+
+    eagle_insert_event \
+        "$EAGLE_EVENT_PROJECT" \
+        "${EAGLE_EVENT_SESSION_ID:-}" \
+        "${EAGLE_EVENT_AGENT:-}" \
+        "hook_completed" \
+        "" \
+        "${EAGLE_EVENT_HOOK_NAME:-}" \
+        "$status" \
+        "${EAGLE_EVENT_COMPLETION_DETAIL:-}"
+}