@polygraph/claude-plugin 0.4.33 → 0.4.34

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.4.33",
+  "version": "0.4.34",
   "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
   "author": {
     "name": "Narwhal Technologies Inc",

package/hooks/record-session-mapping.mjs

@@ -18,17 +18,58 @@
 //     injects hook stdout into the model context); never exits non-zero.
 
 import {
+  appendFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
   realpathSync,
   renameSync,
+  statSync,
   writeFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
+
+// Append a one-line JSON record of a hook failure to ~/.polygraph/logs/hooks.log.
+// This hook swallows its errors silently and must never write to stdout (Claude
+// Code injects hook stdout into the model context), so this on-disk log is the
+// only record that something went wrong. The logger is itself failure-proof.
+function logHookFailure(
+  hook,
+  error,
+  meta = {},
+  home = process.env.HOME?.trim() || homedir()
+) {
+  try {
+    const logsDir = join(home, '.polygraph', 'logs');
+    mkdirSync(logsDir, { recursive: true });
+    const logFile = join(logsDir, 'hooks.log');
+
+    try {
+      if (statSync(logFile).size > HOOK_LOG_MAX_BYTES) {
+        renameSync(logFile, `${logFile}.1`);
+      }
+    } catch {
+      // no prior log, or rotation failed — ignore
+    }
+
+    const entry = {
+      time: new Date().toISOString(),
+      hook,
+      pid: process.pid,
+      ...meta,
+      error: error instanceof Error ? error.message : String(error),
+      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+    };
+    appendFileSync(logFile, JSON.stringify(entry) + '\n');
+  } catch {
+    // Logging must never throw — a failing logger must not break the hook.
+  }
+}
+
 function readStdin() {
   try {
     return readFileSync(0, 'utf8');
@@ -147,8 +188,10 @@ export function main() {
       // process.ppid is the harness pid when the hook is spawned as a child.
       pid: process.ppid,
     });
-  } catch {
-    // Silent — a broken hook must never break the agent session.
+  } catch (error) {
+    // Silent toward the agent — a broken hook must never break the session —
+    // but record it so failures are not invisible.
+    logHookFailure(`${process.argv[2] || 'unknown'}:record-session-mapping`, error);
   }
 }
 

package/hooks/reinject-polygraph-context.mjs

@@ -18,7 +18,16 @@
 //
 // Outside a Polygraph session (no matching sidecar) the hook is a silent no-op.
 
-import { readFileSync, readdirSync, existsSync, realpathSync } from 'node:fs';
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  statSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -27,6 +36,45 @@ export function polygraphRoot(home = homedir()) {
   return path.join(home, '.polygraph');
 }
 
+const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
+
+// Append a one-line JSON record of a hook failure to ~/.polygraph/logs/hooks.log.
+// This hook must never write to stdout except its hookSpecificOutput payload
+// (Claude Code injects hook stdout into the model context), so this on-disk log
+// is the only record that something went wrong. The logger is failure-proof.
+function logHookFailure(
+  hook,
+  error,
+  meta = {},
+  home = process.env.HOME?.trim() || homedir()
+) {
+  try {
+    const logsDir = path.join(home, '.polygraph', 'logs');
+    mkdirSync(logsDir, { recursive: true });
+    const logFile = path.join(logsDir, 'hooks.log');
+
+    try {
+      if (statSync(logFile).size > HOOK_LOG_MAX_BYTES) {
+        renameSync(logFile, `${logFile}.1`);
+      }
+    } catch {
+      // no prior log, or rotation failed — ignore
+    }
+
+    const entry = {
+      time: new Date().toISOString(),
+      hook,
+      pid: process.pid,
+      ...meta,
+      error: error instanceof Error ? error.message : String(error),
+      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+    };
+    appendFileSync(logFile, JSON.stringify(entry) + '\n');
+  } catch {
+    // Logging must never throw — a failing logger must not break the hook.
+  }
+}
+
 function readJson(file) {
   try {
     return JSON.parse(readFileSync(file, 'utf8'));
@@ -115,30 +163,36 @@ function readStdin() {
 }
 
 export function main() {
-  let payload = {};
-  const raw = readStdin();
-  if (raw) {
-    try {
-      payload = JSON.parse(raw);
-    } catch {
-      payload = {};
+  let agentSessionId = '';
+  try {
+    let payload = {};
+    const raw = readStdin();
+    if (raw) {
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        payload = {};
+      }
     }
-  }
 
-  const agentSessionId =
-    payload.session_id || process.env.CLAUDE_CODE_SESSION_ID || '';
+    agentSessionId =
+      payload.session_id || process.env.CLAUDE_CODE_SESSION_ID || '';
 
-  const context = buildPolygraphContext(agentSessionId);
-  if (!context) return; // not a Polygraph session — stay silent
+    const context = buildPolygraphContext(agentSessionId);
+    if (!context) return; // not a Polygraph session — stay silent
 
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'SessionStart',
-        additionalContext: context,
-      },
-    })
-  );
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'SessionStart',
+          additionalContext: context,
+        },
+      })
+    );
+  } catch (error) {
+    // Never let a hook failure surface to the agent; just record it.
+    logHookFailure('reinject-polygraph-context', error, { agentSessionId });
+  }
 }
 
 // Run only when executed directly as a hook, not when imported (e.g. by tests).

package/hooks/remind-subagents.mjs

@@ -1,17 +1,63 @@
 // Remind agents to use subagents for delegation and polling.
 // Outputs a non-blocking systemMessage — does not prevent the tool call.
+import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { stdin } from 'node:process';
 
-// Consume stdin (hook protocol requires it)
-stdin.resume();
-stdin.on('end', () => {});
+const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
 
-console.log(
-  JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      systemMessage:
-        'REMINDER: spawn_agent and show_agent should be called via background subagents (polygraph-delegate-subagent), not directly. Direct calls flood the context window with polling noise. If you are already inside a subagent, ignore this reminder.',
-    },
-  })
-);
+// Append a one-line JSON record of a hook failure to ~/.polygraph/logs/hooks.log.
+// This hook must never write anything to stdout except its hookSpecificOutput
+// payload, so this on-disk log is the only record that something went wrong.
+// The logger is itself failure-proof.
+function logHookFailure(
+  hook,
+  error,
+  meta = {},
+  home = process.env.HOME?.trim() || homedir()
+) {
+  try {
+    const logsDir = join(home, '.polygraph', 'logs');
+    mkdirSync(logsDir, { recursive: true });
+    const logFile = join(logsDir, 'hooks.log');
+
+    try {
+      if (statSync(logFile).size > HOOK_LOG_MAX_BYTES) {
+        renameSync(logFile, `${logFile}.1`);
+      }
+    } catch {
+      // no prior log, or rotation failed — ignore
+    }
+
+    const entry = {
+      time: new Date().toISOString(),
+      hook,
+      pid: process.pid,
+      ...meta,
+      error: error instanceof Error ? error.message : String(error),
+      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+    };
+    appendFileSync(logFile, JSON.stringify(entry) + '\n');
+  } catch {
+    // Logging must never throw — a failing logger must not break the hook.
+  }
+}
+
+try {
+  // Consume stdin (hook protocol requires it)
+  stdin.resume();
+  stdin.on('end', () => {});
+
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        systemMessage:
+          'REMINDER: spawn_agent and show_agent should be called via background subagents (polygraph-delegate-subagent), not directly. Direct calls flood the context window with polling noise. If you are already inside a subagent, ignore this reminder.',
+      },
+    })
+  );
+} catch (error) {
+  logHookFailure('remind-subagents', error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/claude-plugin",
-  "version": "0.4.33",
+  "version": "0.4.34",
   "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
   "license": "UNLICENSED",
   "private": false,