@sienklogic/plan-build-run 2.19.0 → 2.19.1

package/plugins/pbr/scripts/lib/wiring-check.js

@@ -0,0 +1,196 @@
+'use strict';
+
+// STATUS: Standalone utility — tested but not auto-wired into gates. Referenced by build SKILL.md for confidence gate logic.
+
+/**
+ * lib/wiring-check.js -- Verify that SUMMARY key_files are actually imported/used
+ * by other files in the project. Used as a 4th confidence gate signal.
+ *
+ * Returns { imported: true/false, orphaned: string[] }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseYamlFrontmatter } = require('./core');
+
+/**
+ * File extensions and basenames to skip during wiring checks.
+ * These file types are not expected to be imported by other code.
+ */
+const SKIP_EXTENSIONS = new Set([
+  '.test.js', '.spec.js', '.test.ts', '.spec.ts',
+  '.test.cjs', '.spec.cjs', '.test.mjs', '.spec.mjs',
+  '.md', '.json', '.env', '.yaml', '.yml', '.toml', '.ini',
+  '.css', '.scss', '.html', '.svg', '.png', '.jpg', '.gif'
+]);
+
+const SKIP_BASENAMES = new Set([
+  'config.json', '.env', '.env.example', '.env.local',
+  'package.json', 'tsconfig.json', 'jest.config.js', 'jest.config.cjs',
+  'vite.config.js', 'vite.config.ts', '.eslintrc.json', '.prettierrc'
+]);
+
+/**
+ * Check if a file path should be skipped for wiring verification.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function shouldSkip(filePath) {
+  const basename = path.basename(filePath);
+  const ext = path.extname(filePath);
+
+  // Skip config files by basename
+  if (SKIP_BASENAMES.has(basename)) return true;
+
+  // Skip test files (check compound extensions like .test.js)
+  for (const skipExt of SKIP_EXTENSIONS) {
+    if (basename.endsWith(skipExt)) return true;
+  }
+
+  // Skip markdown and other non-code files by extension
+  if (['.md', '.json', '.env', '.yaml', '.yml', '.toml', '.ini',
+       '.css', '.scss', '.html', '.svg', '.png', '.jpg', '.gif'].includes(ext)) {
+    return true;
+  }
+
+  return false;
+}
+
+/** Code file extensions to search for import/require references. */
+const SEARCH_EXTENSIONS = new Set(['.js', '.cjs', '.mjs', '.ts', '.tsx', '.md']);
+
+/**
+ * Recursively collect files with matching extensions, skipping node_modules.
+ * @param {string} dir
+ * @param {string[]} results
+ * @returns {string[]}
+ */
+function collectFiles(dir, results = []) {
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        collectFiles(fullPath, results);
+      } else if (SEARCH_EXTENSIONS.has(path.extname(entry.name))) {
+        results.push(fullPath);
+      }
+    }
+  } catch (_e) {
+    // Permission errors or missing dirs — skip silently
+  }
+  return results;
+}
+
+/**
+ * Check if a key file is imported/required by at least one other file in the project.
+ * Uses pure Node.js file search for cross-platform compatibility (grep cwd issues on Windows).
+ *
+ * @param {string} keyFilePath - Path to the key file (relative to project root)
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {boolean} true if at least one import/require reference found
+ */
+function isFileImported(keyFilePath, projectRoot) {
+  const basename = path.basename(keyFilePath);
+  const nameNoExt = basename.replace(/\.[^.]+$/, '');
+
+  // Build regex: match require('...name') or import ... from '...name'
+  const pattern = new RegExp(`(require\\(|from\\s+).*${escapeRegex(nameNoExt)}`);
+
+  // Resolve the key file's absolute path for self-exclusion
+  const keyFileAbs = path.resolve(projectRoot, keyFilePath);
+
+  // Collect candidate files and search
+  const files = collectFiles(projectRoot);
+
+  for (const filePath of files) {
+    // Skip the key file itself
+    if (path.resolve(filePath) === keyFileAbs) continue;
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      if (pattern.test(content)) {
+        return true;
+      }
+    } catch (_e) {
+      // Unreadable file — skip
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Escape special regex characters in a string.
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Check that all key_files from SUMMARY.md files are actually imported/used
+ * by other files in the project.
+ *
+ * @param {string[]} summaryFiles - Array of absolute paths to SUMMARY.md files
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{ imported: boolean, orphaned: string[] }}
+ */
+function checkKeyFilesImported(summaryFiles, projectRoot) {
+  if (!summaryFiles || summaryFiles.length === 0) {
+    return { imported: true, orphaned: [] };
+  }
+
+  const allKeyFiles = [];
+
+  // Collect key_files from each SUMMARY.md frontmatter
+  for (const summaryPath of summaryFiles) {
+    try {
+      const content = fs.readFileSync(summaryPath, 'utf8');
+      const fm = parseYamlFrontmatter(content);
+
+      if (fm.key_files && Array.isArray(fm.key_files)) {
+        for (const entry of fm.key_files) {
+          // key_files entries can be "path: description" or just "path"
+          const filePath = typeof entry === 'string'
+            ? entry.split(':')[0].trim().replace(/^["']|["']$/g, '')
+            : entry;
+          if (filePath) allKeyFiles.push(filePath);
+        }
+      }
+    } catch (_e) {
+      // Skip unreadable summary files
+    }
+  }
+
+  if (allKeyFiles.length === 0) {
+    return { imported: true, orphaned: [] };
+  }
+
+  const orphaned = [];
+
+  for (const keyFile of allKeyFiles) {
+    if (shouldSkip(keyFile)) continue;
+
+    if (!isFileImported(keyFile, projectRoot)) {
+      orphaned.push(keyFile);
+    }
+  }
+
+  return {
+    imported: orphaned.length === 0,
+    orphaned
+  };
+}
+
+module.exports = {
+  checkKeyFilesImported,
+  isFileImported,
+  shouldSkip,
+  // Exported for testing
+  escapeRegex,
+  SKIP_EXTENSIONS,
+  SKIP_BASENAMES
+};

package/plugins/pbr/scripts/log-notification.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+/**
+ * Notification event hook: Logs notification events to the session log.
+ *
+ * Tracks when Claude Code fires notifications (e.g., background agent
+ * completions, tool results). Useful for understanding async workflow
+ * patterns and diagnosing missed notifications.
+ *
+ * Exit codes:
+ *   0 = always (logging only, never blocks)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+const { shouldThrottleDefault, isCriticalMessage } = require('./lib/notification-throttle');
+
+function isAutonomousMode(planningDir) {
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return cfg.mode === 'autonomous';
+  } catch (_e) { return false; }
+}
+
+function getThrottleConfig(planningDir) {
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const tc = (cfg.hooks && cfg.hooks.notification_throttle) || {};
+    return { windowMs: tc.window_ms || 60000, maxPerWindow: tc.max_per_window || 3 };
+  } catch (_e) { return { windowMs: 60000, maxPerWindow: 3 }; }
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = input ? JSON.parse(input) : {};
+      const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+      const planningDir = path.join(cwd, '.planning');
+
+      if (!fs.existsSync(planningDir)) {
+        process.exit(0);
+      }
+
+      const notificationType = data.notification_type || data.type || 'unknown';
+      const message = data.message || data.content || '';
+      const agentId = data.agent_id || null;
+      const sessionId = data.session_id || null;
+
+      // Throttle routine notifications in autonomous mode
+      const throttleKey = 'notification:' + notificationType;
+      const autonomous = isAutonomousMode(planningDir);
+      const critical = isCriticalMessage(message);
+      const tc = getThrottleConfig(planningDir);
+      if (shouldThrottleDefault(throttleKey, { isAutonomous: autonomous, isCritical: critical, windowMs: tc.windowMs, maxPerWindow: tc.maxPerWindow })) {
+        process.exit(0);
+      }
+
+      logHook('log-notification', 'Notification', 'received', {
+        type: notificationType,
+        agent_id: agentId,
+        message: message.substring(0, 100),
+        sessionId
+      });
+
+      logEvent('notification', notificationType, {
+        agent_id: agentId,
+        message: message.substring(0, 200),
+        sessionId
+      });
+
+      process.exit(0);
+    } catch (_e) {
+      process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] log-notification failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+/**
+ * HTTP handler for hook-server.js.
+ * @param {Object} reqBody - { event, tool, data, planningDir }
+ * @returns {null} - Logging only, no output
+ */
+function handleHttp(reqBody) {
+  try {
+    const data = reqBody.data || {};
+    const planningDir = reqBody.planningDir || '';
+    const notificationType = data.notification_type || data.type || 'unknown';
+    const message = data.message || data.content || '';
+    const agentId = data.agent_id || null;
+    const sessionId = data.session_id || null;
+
+    // Throttle routine notifications in autonomous mode
+    const throttleKey = 'notification:' + notificationType;
+    const autonomous = isAutonomousMode(planningDir);
+    const critical = isCriticalMessage(message);
+    const tc = getThrottleConfig(planningDir);
+    if (shouldThrottleDefault(throttleKey, { isAutonomous: autonomous, isCritical: critical, windowMs: tc.windowMs, maxPerWindow: tc.maxPerWindow })) {
+      return null;
+    }
+
+    logHook('log-notification', 'Notification', 'received', {
+      type: notificationType,
+      agent_id: agentId,
+      message: message.substring(0, 100),
+      sessionId
+    });
+
+    logEvent('notification', notificationType, {
+      agent_id: agentId,
+      message: message.substring(0, 200),
+      sessionId
+    });
+  } catch (_e) {
+    // Never propagate
+  }
+  return null;
+}
+
+module.exports = { handleHttp };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/log-subagent.js

@@ -17,7 +17,24 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
-const { configLoad } = require('./pbr-tools');
+
+// Lazy-loaded on demand — these modules do sync I/O at require() time
+let _configLoad = null;
+let _sessionLoad = null;
+let _resolveSessionPath = null;
+
+function getConfigLoad() {
+  if (!_configLoad) _configLoad = require('./lib/config').configLoad;
+  return _configLoad;
+}
+function getSessionLoad() {
+  if (!_sessionLoad) _sessionLoad = require('./lib/core').sessionLoad;
+  return _sessionLoad;
+}
+function getResolveSessionPath() {
+  if (!_resolveSessionPath) _resolveSessionPath = require('./lib/core').resolveSessionPath;
+  return _resolveSessionPath;
+}
 
 function readStdin() {
   try {
@@ -45,23 +62,27 @@ function main() {
   const data = readStdin();
   const agentType = resolveAgentType(data);
 
+  const sessionId = data.session_id || null;
+
   if (action === 'start') {
     logHook('log-subagent', 'SubagentStart', 'spawned', {
       agent_id: data.agent_id || null,
       agent_type: agentType,
-      description: data.description || null
+      description: data.description || null,
+      sessionId
     });
     logEvent('agent', 'spawn', {
       agent_id: data.agent_id || null,
       agent_type: agentType,
-      description: data.description || null
+      description: data.description || null,
+      sessionId
     });
 
     // Write .active-agent signal so other hooks know a subagent is running
     writeActiveAgent(agentType || 'unknown');
 
     // Inject project context into subagent
-    const context = buildAgentContext();
+    const context = buildAgentContext(sessionId);
     if (context) {
       const output = {
         hookSpecificOutput: {
@@ -77,13 +98,26 @@ function main() {
     logHook('log-subagent', 'SubagentStop', 'completed', {
       agent_id: data.agent_id || null,
       agent_type: agentType,
-      duration_ms: data.duration_ms || null
+      duration_ms: data.duration_ms || null,
+      sessionId
     });
     logEvent('agent', 'complete', {
       agent_id: data.agent_id || null,
       agent_type: agentType,
-      duration_ms: data.duration_ms || null
+      duration_ms: data.duration_ms || null,
+      sessionId
     });
+
+    // Track cumulative agent spawns — warn when excessive
+    const cwd = process.cwd();
+    const planningDir = path.join(cwd, '.planning');
+    const warning = trackAgentCost(planningDir, agentType, data.duration_ms, sessionId);
+    if (warning) {
+      process.stdout.write(JSON.stringify({ additionalContext: warning }));
+    } else {
+      // Emit stdout so Claude Code captures SubagentStop in session JSONL for audit visibility
+      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    }
   }
 
   process.exit(0);
@@ -113,7 +147,66 @@ function removeActiveAgent() {
   }
 }
 
-function buildAgentContext() {
+const AGENT_COST_FILE = '.agent-cost-tracker';
+const AGENT_SPAWN_WARN_THRESHOLD = 10;
+const AGENT_SPAWN_CRITICAL_THRESHOLD = 20;
+
+/**
+ * Track cumulative agent spawns per session. Returns warning string if threshold exceeded.
+ * Uses JSONL append for fast writes; only reads back on threshold checks.
+ * @param {string} planningDir
+ * @param {string|null} agentType
+ * @param {number|null} durationMs
+ * @param {string|null} sessionId
+ * @returns {string|null}
+ */
+function trackAgentCost(planningDir, agentType, durationMs, sessionId) {
+  try {
+    if (!fs.existsSync(planningDir)) return null;
+  } catch (_e) { return null; }
+
+  const resolveSessionPath = getResolveSessionPath();
+  const trackerPath = sessionId
+    ? resolveSessionPath(planningDir, AGENT_COST_FILE, sessionId)
+    : path.join(planningDir, AGENT_COST_FILE);
+
+  // Append a JSONL line — no read required on the hot path
+  const entry = { ts: Date.now(), type: agentType || 'unknown', ms: durationMs || 0 };
+  try { fs.appendFileSync(trackerPath, JSON.stringify(entry) + '\n', 'utf8'); } catch (_e) { /* best-effort */ }
+
+  // Count lines to check thresholds (cheaper than JSON parse of entire structure)
+  let lineCount = 0;
+  try {
+    const content = fs.readFileSync(trackerPath, 'utf8');
+    const lines = content.trim().split('\n');
+    lineCount = lines.length;
+
+    // Only compute detailed stats at threshold boundaries
+    if (lineCount === AGENT_SPAWN_WARN_THRESHOLD || lineCount === AGENT_SPAWN_CRITICAL_THRESHOLD) {
+      let totalMs = 0;
+      const byType = {};
+      for (const line of lines) {
+        try {
+          const rec = JSON.parse(line);
+          totalMs += rec.ms || 0;
+          byType[rec.type] = (byType[rec.type] || 0) + 1;
+        } catch (_e) { /* skip malformed lines */ }
+      }
+
+      if (lineCount === AGENT_SPAWN_CRITICAL_THRESHOLD) {
+        const topAgents = Object.entries(byType).sort((a, b) => b[1] - a[1]).slice(0, 3).map(([t, c]) => `${t}: ${c}`).join(', ');
+        return `[pbr] CRITICAL: ${lineCount} agents spawned this session (~${Math.round(totalMs / 1000)}s total). Top: ${topAgents}. Run /pbr:pause-work to cycle session and reclaim context.`;
+      }
+      if (lineCount === AGENT_SPAWN_WARN_THRESHOLD) {
+        return `[pbr] Advisory: ${lineCount} agents spawned this session (~${Math.round(totalMs / 1000)}s total). Consider /pbr:pause-work if context quality is degrading.`;
+      }
+    }
+  } catch (_e) { /* best-effort — threshold check is advisory */ }
+
+  return null;
+}
+
+function buildAgentContext(sessionId) {
   const cwd = process.cwd();
   const planningDir = path.join(cwd, '.planning');
 
@@ -136,19 +229,22 @@ function buildAgentContext() {
     }
   }
 
-  // Active skill context
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-  if (fs.existsSync(activeSkillFile)) {
-    try {
-      const skill = fs.readFileSync(activeSkillFile, 'utf8').trim();
-      if (skill) parts.push(`Active skill: /pbr:${skill}`);
-    } catch (_e) {
-      // skip
-    }
+  // Active skill context — session-scoped when sessionId available
+  let activeSkill = '';
+  try {
+    activeSkill = getSessionLoad()(planningDir, sessionId).activeSkill || '';
+  } catch (_e) { /* skip */ }
+  if (!activeSkill) {
+    const resolveSessionPath = getResolveSessionPath();
+    const skillPath = sessionId
+      ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+      : path.join(planningDir, '.active-skill');
+    try { activeSkill = fs.readFileSync(skillPath, 'utf8').trim(); } catch (_) { /* file missing */ }
   }
+  if (activeSkill) parts.push(`Active skill: /pbr:${activeSkill}`);
 
   // Config highlights
-  const config = configLoad(planningDir);
+  const config = getConfigLoad()(planningDir);
   if (config) {
     const configParts = [];
     if (config.depth) configParts.push(`depth=${config.depth}`);
@@ -160,5 +256,94 @@ function buildAgentContext() {
   return '[Plan-Build-Run Project Context] ' + parts.join(' | ');
 }
 
-module.exports = { buildAgentContext, resolveAgentType };
+/**
+ * HTTP handler for hook-server.js integration.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, ... }.
+ * Uses reqBody.event to distinguish SubagentStart vs SubagentStop.
+ * Must NOT call process.exit().
+ * @param {{ event: string, data: object, planningDir: string }} reqBody
+ * @returns {{ additionalContext: string }|null}
+ */
+function handleHttp(reqBody) {
+  const event = reqBody.event || '';
+  const data = reqBody.data || {};
+  const agentType = resolveAgentType(data);
+
+  const sessionId = data.session_id || null;
+
+  if (event === 'SubagentStart') {
+    logHook('log-subagent', 'SubagentStart', 'spawned', {
+      agent_id: data.agent_id || null,
+      agent_type: agentType,
+      description: data.description || null,
+      sessionId
+    });
+    logEvent('agent', 'spawn', {
+      agent_id: data.agent_id || null,
+      agent_type: agentType,
+      description: data.description || null,
+      sessionId
+    });
+
+    // Write .active-agent signal — use planningDir from reqBody if available
+    const planningDir = reqBody.planningDir;
+    if (planningDir) {
+      try {
+        const filePath = path.join(planningDir, '.active-agent');
+        if (fs.existsSync(planningDir)) {
+          fs.writeFileSync(filePath, agentType || 'unknown', 'utf8');
+        }
+      } catch (_e) { /* best-effort */ }
+    } else {
+      writeActiveAgent(agentType || 'unknown');
+    }
+
+    const httpSessionId = data.session_id || null;
+    const context = buildAgentContext(httpSessionId);
+    if (context) {
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'SubagentStart',
+          additionalContext: context
+        }
+      };
+    }
+    return null;
+  } else if (event === 'SubagentStop') {
+    // Remove .active-agent signal
+    const planningDir = reqBody.planningDir;
+    if (planningDir) {
+      try {
+        const filePath = path.join(planningDir, '.active-agent');
+        if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+      } catch (_e) { /* best-effort */ }
+    } else {
+      removeActiveAgent();
+    }
+    logHook('log-subagent', 'SubagentStop', 'completed', {
+      agent_id: data.agent_id || null,
+      agent_type: agentType,
+      duration_ms: data.duration_ms || null,
+      sessionId
+    });
+    logEvent('agent', 'complete', {
+      agent_id: data.agent_id || null,
+      agent_type: agentType,
+      duration_ms: data.duration_ms || null,
+      sessionId
+    });
+
+    // Track agent cost via HTTP path
+    const costPlanningDir = reqBody.planningDir || path.join(process.cwd(), '.planning');
+    const httpSessionId = data.session_id || null;
+    const costWarning = trackAgentCost(costPlanningDir, agentType, data.duration_ms, httpSessionId);
+    if (costWarning) {
+      return { additionalContext: costWarning };
+    }
+    return null;
+  }
+  return null;
+}
+
+module.exports = { buildAgentContext, resolveAgentType, handleHttp, trackAgentCost, AGENT_SPAWN_WARN_THRESHOLD, AGENT_SPAWN_CRITICAL_THRESHOLD };
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/log-tool-failure.js

@@ -52,14 +52,19 @@ async function main() {
     input_summary: summarizeInput(toolName, toolInput)
   });
 
-  // Provide recovery hints for Bash failures (most common actionable failure)
+  // Provide recovery hints for tool failures
+  let hint = null;
   if (toolName === 'Bash' && !isInterrupt) {
-    const output = {
-      hookSpecificOutput: {
-        hookEventName: 'PostToolUseFailure',
-        additionalContext: 'Bash command failed. If this is a recurring issue, consider using /pbr:debug for systematic investigation.'
-      }
-    };
+    hint = '[Tool Failure] Bash command failed. Check the error output above for permission/path issues. For recurring failures: /pbr:debug for systematic investigation.';
+  } else if (toolName === 'Write' || toolName === 'Edit') {
+    hint = `[Tool Failure] ${toolName} failed for ${(toolInput.file_path || 'unknown file')}. Check: (1) directory exists, (2) file is not read-only, (3) path uses forward slashes. For path issues: verify with Glob.`;
+  } else if (toolName === 'Read') {
+    hint = `[Tool Failure] Read failed for ${(toolInput.file_path || 'unknown file')}. Check: (1) file exists on disk, (2) path is absolute, (3) no typos in filename. Use Glob to find the correct path.`;
+  } else if (toolName === 'Task') {
+    hint = '[Tool Failure] Task (subagent) failed. Check: (1) subagent_type is valid (pbr:*), (2) prompt is not empty, (3) no circular spawning. Re-run the parent skill to retry.';
+  }
+  if (hint) {
+    const output = { additionalContext: hint };
     process.stdout.write(JSON.stringify(output));
   }
 
@@ -85,4 +90,51 @@ function summarizeInput(toolName, toolInput) {
   }
 }
 
-main().catch(() => {});
+if (require.main === module) {
+  main().catch(() => {});
+}
+
+/**
+ * HTTP handler for hook-server.js integration.
+ * Called as handleHttp(reqBody, cache) where reqBody = { data, planningDir, ... }.
+ * Must NOT call process.exit().
+ * @param {{ data: object }} reqBody
+ * @returns {{ additionalContext: string }|null}
+ */
+function handleHttp(reqBody) {
+  const data = reqBody.data || {};
+  const toolName = data.tool_name || 'unknown';
+  const error = data.error || 'unknown error';
+  const isInterrupt = data.is_interrupt || false;
+  const toolInput = data.tool_input || {};
+
+  logHook('log-tool-failure', 'PostToolUseFailure', 'logged', {
+    tool: toolName,
+    error: typeof error === 'string' ? error.substring(0, 200) : JSON.stringify(error).substring(0, 200),
+    interrupt: isInterrupt
+  });
+
+  logEvent('tool', 'failure', {
+    tool: toolName,
+    error: typeof error === 'string' ? error.substring(0, 500) : JSON.stringify(error).substring(0, 500),
+    interrupt: isInterrupt,
+    input_summary: summarizeInput(toolName, toolInput)
+  });
+
+  let hint = null;
+  if (toolName === 'Bash' && !isInterrupt) {
+    hint = '[Tool Failure] Bash command failed. Check the error output above for permission/path issues. For recurring failures: /pbr:debug for systematic investigation.';
+  } else if (toolName === 'Write' || toolName === 'Edit') {
+    hint = `[Tool Failure] ${toolName} failed for ${(toolInput.file_path || 'unknown file')}. Check: (1) directory exists, (2) file is not read-only, (3) path uses forward slashes. For path issues: verify with Glob.`;
+  } else if (toolName === 'Read') {
+    hint = `[Tool Failure] Read failed for ${(toolInput.file_path || 'unknown file')}. Check: (1) file exists on disk, (2) path is absolute, (3) no typos in filename. Use Glob to find the correct path.`;
+  } else if (toolName === 'Task') {
+    hint = '[Tool Failure] Task (subagent) failed. Check: (1) subagent_type is valid (pbr:*), (2) prompt is not empty, (3) no circular spawning. Re-run the parent skill to retry.';
+  }
+  if (hint) {
+    return { additionalContext: hint };
+  }
+  return null;
+}
+
+module.exports = { handleHttp, summarizeInput };