@entelligentsia/forgecli 0.11.3 → 0.19.0

package/dist/forge-payload/hooks/forge-permissions.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// Forge permission auto-approver — runs on PermissionRequest events.
+//
+// Purpose: eliminate the permission prompt storm (BUG-014) by auto-approving
+// known Forge tool patterns and persisting allow rules to localSettings.
+//
+// Protocol (Claude Code PermissionRequest hook):
+//   - stdin: JSON envelope { tool_name, tool_input, permission_suggestions }
+//   - stdout: { hookSpecificOutput: { hookEventName, decision: { behavior,
+//     updatedPermissions } } } to allow and persist rules
+//   - exit 0 with no output: let normal permission flow proceed
+//   - exit 2 with stderr: block the tool call
+//
+// Security model:
+//   - This hook can only ALLOW, never DENY
+//   - User deny rules always take precedence over hook allows
+//   - Rules persist to .claude/settings.local.json (gitignored, per-project)
+//   - Users can inspect/remove rules via /permissions
+
+'use strict';
+
+process.on('uncaughtException', (err) => {
+  try { process.stderr.write(`forge-permissions: internal error (fail-open): ${err.message}\n`); } catch (_) {}
+  process.exit(0);
+});
+
+// ── Pattern registry ──────────────────────────────────────────────
+// Each entry: { pattern: RegExp, rule: string }
+// pattern matches against the tool input string (Bash command, file path, or URL)
+// rule is the allow rule content to persist via updatedPermissions
+//
+// Forge-command patterns within BASH_PATTERNS overlap with FORGE_COMMAND_PATTERNS.
+// Canonical source for forge command recognition: hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS
+// (H-1d, FORGE-S25-T08). This file intentionally does NOT require hooks/lib/common.cjs
+// because build-payload.cjs bundles hooks/*.js but excludes hooks/lib/ (forge-cli bundle gap).
+// When adding a new forge command, update BOTH this list AND hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS.
+
+const BASH_PATTERNS = [
+  // Node tool invocations — covers $FORGE_ROOT/tools/*.cjs and $CLAUDE_PLUGIN_ROOT
+  { pattern: /^node\s+.*\/tools\/[\w-]+\.(cjs|js)\b/, rule: 'node ~/.claude/plugins/cache/forge/forge/*/tools/*' },
+  // NOTE: node -e and node -p removed — arbitrary code execution must not be auto-approved.
+  // Forge workflows use node .../tools/*.cjs for tool invocations; inline node -e/p requires
+  // explicit user approval each time.
+  // Shell commands used by Forge workflows
+  { pattern: /^mkdir\s+-p\s+/, rule: 'mkdir -p .forge/*' },
+  { pattern: /^mkdir\s+-p\s+\S+/, rule: 'mkdir -p .forge/*' },
+  { pattern: /^cp\s+/, rule: 'cp */schemas/*.schema.json .forge/schemas/' },
+  { pattern: /^ls\s+/, rule: 'ls *' },
+  { pattern: /^cat\s+/, rule: 'cat .forge/*' },
+  { pattern: /^date\s+-u\s+/, rule: 'date -u *' },
+  { pattern: /^date\s+/, rule: 'date -u *' },
+  { pattern: /^jq\s+/, rule: 'jq *' },
+  { pattern: /^touch\s+/, rule: 'touch .forge/*' },
+  { pattern: /^uname\s+/, rule: 'uname *' },
+  { pattern: /^rm\s+\.forge/, rule: 'rm .forge/*' },
+  { pattern: /^rm\s+-rf\s+\.forge/, rule: 'rm -rf .forge/*' },
+  { pattern: /^rmdir\s+/, rule: 'rmdir .forge/*' },
+  { pattern: /^gh\s+auth\s+/, rule: 'gh auth status *' },
+  { pattern: /^gh\s+issue\s+/, rule: 'gh issue create *' },
+  // git read-only commands (already auto-approved by Claude Code, but belt-and-suspenders)
+  { pattern: /^git\s+status\b/, rule: 'git status *' },
+  { pattern: /^git\s+log\b/, rule: 'git log *' },
+  { pattern: /^git\s+diff\b/, rule: 'git diff *' },
+  { pattern: /^git\s+add\s+/, rule: 'git add *' },
+  { pattern: /^git\s+commit\s+-m\s+/, rule: 'git commit -m *' },
+  { pattern: /^git\s+push\b/, rule: 'git push *' },
+  { pattern: /^git\s+checkout\s+/, rule: 'git checkout *' },
+  { pattern: /^git\s+branch\s+/, rule: 'git branch *' },
+  { pattern: /^git\s+stash\b/, rule: 'git stash *' },
+  { pattern: /^git\s+worktree\s+/, rule: 'git worktree *' },
+];
+
+const WRITE_PATTERNS = [
+  { pattern: /^\.forge\//, rule: '.forge/**' },
+  { pattern: /^\.claude\/commands\//, rule: '.claude/commands/**' },
+  { pattern: /^engineering\//, rule: 'engineering/**' },
+  { pattern: /^CLAUDE\.md$/i, rule: 'CLAUDE.md' },
+  { pattern: /^AGENTS\.md$/i, rule: 'AGENTS.md' },
+  { pattern: /^\.gitignore$/, rule: '.gitignore' },
+];
+
+const EDIT_PATTERNS = [
+  { pattern: /^\.forge\//, rule: '.forge/**' },
+  { pattern: /^\.claude\/commands\//, rule: '.claude/commands/**' },
+  { pattern: /^engineering\//, rule: 'engineering/**' },
+  { pattern: /^CLAUDE\.md$/i, rule: 'CLAUDE.md' },
+  { pattern: /^AGENTS\.md$/i, rule: 'AGENTS.md' },
+];
+
+const WEBFETCH_PATTERNS = [
+  { pattern: /^https:\/\/raw\.githubusercontent\.com\/Entelligentsia\/forge\//, rule: 'domain:raw.githubusercontent.com' },
+];
+
+const PATTERN_MAP = {
+  Bash: BASH_PATTERNS,
+  Write: WRITE_PATTERNS,
+  Edit: EDIT_PATTERNS,
+  MultiEdit: EDIT_PATTERNS,
+  WebFetch: WEBFETCH_PATTERNS,
+};
+
+// ── Core logic ─────────────────────────────────────────────────────
+
+function matchTool(toolName, toolInput) {
+  const patterns = PATTERN_MAP[toolName];
+  if (!patterns) return null;
+
+  const input = toolName === 'Bash' ? (toolInput.command || '')
+    : (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') ? (toolInput.file_path || '')
+    : toolName === 'WebFetch' ? (toolInput.url || '')
+    : '';
+
+  for (const { pattern, rule } of patterns) {
+    if (pattern.test(input)) return rule;
+  }
+  return null;
+}
+
+// ── Export for testing ─────────────────────────────────────────────
+module.exports = { matchTool, BASH_PATTERNS, WRITE_PATTERNS, EDIT_PATTERNS, WEBFETCH_PATTERNS };
+
+// ── Main (hook runner) ────────────────────────────────────────────
+if (require.main === module) {
+let input = '';
+process.stdin.on('data', (d) => { input += d; });
+process.stdin.on('end', () => {
+  let event;
+  try {
+    event = JSON.parse(input);
+  } catch (_) {
+    // Unparseable input — fail open, let normal permission flow handle it
+    process.exit(0);
+  }
+
+  const { tool_name, tool_input } = event;
+  if (!tool_name || !tool_input) {
+    process.exit(0);
+  }
+
+  const matchedRule = matchTool(tool_name, tool_input || {});
+  if (matchedRule) {
+    // Persist only the matched rule — never bulk-approve all rules at once.
+    const response = {
+      hookSpecificOutput: {
+        hookEventName: 'PermissionRequest',
+        decision: {
+          behavior: 'allow',
+          updatedPermissions: [{
+            type: 'addRules',
+            rules: [{ toolName: tool_name, ruleContent: matchedRule }],
+            behavior: 'allow',
+            destination: 'localSettings',
+          }],
+        },
+      },
+    };
+    process.stdout.write(JSON.stringify(response));
+    process.exit(0);
+  }
+
+  // Not a Forge pattern — exit 0 with no output to let normal permission flow proceed
+  process.exit(0);
+});
+} // end require.main === module

package/dist/forge-payload/hooks/post-init.cjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+'use strict';
+
+// Forge hook: post-init
+// PostToolUse hook that fires once at the END of a successful /forge:init
+// Phase 4 (NOT on Resume "start over" or stale-checkpoint cleanup) and
+// invokes /forge:enhance --phase 1 --auto.
+//
+// Trigger detection uses a positive end-of-flow signal: the hook matches
+// `rm -f .forge/init-progress.json` AND requires `.forge/structure-versions.json`
+// to exist (T05 writes it just before the terminal rm in Phase 4).
+//
+// Idempotency: a sentinel file under .forge/cache/ is the SOLE idempotency
+// guard. The mtime check (H-5c) has been removed — it was redundant and
+// fragile; the sentinel file is reliable enough. Because cache/ lives inside
+// .forge/, a manual `rm -rf .forge/` followed by re-init naturally clears
+// the sentinel.
+//
+// Fail-open: any internal error → stderr warning + exit 0. Hook failure must
+// never block /forge:init.
+
+process.on('uncaughtException', (err) => {
+  try { process.stderr.write(`forge post-init: internal error (fail-open): ${err.message}\n`); } catch (_) {}
+  process.exit(0);
+});
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { resolveForgePaths, logSwallowedError } = require('./lib/common.cjs');
+
+let raw = '';
+try { raw = fs.readFileSync(0, 'utf8'); } catch (_) { process.exit(0); }
+
+let envelope;
+try { envelope = JSON.parse(raw); } catch (_) { process.exit(0); }
+
+if (!envelope || envelope.tool_name !== 'Bash') process.exit(0);
+
+const exitCode = envelope.tool_response && envelope.tool_response.exitCode;
+if (exitCode !== 0 && exitCode !== undefined) process.exit(0);
+
+const command = (envelope.tool_input && envelope.tool_input.command) || '';
+
+// Primary trigger: terminal rm of init-progress.json.
+const TRIGGER_RX = /\brm\s+-f\s+\.forge\/init-progress\.json\b/;
+if (!TRIGGER_RX.test(command)) process.exit(0);
+
+const paths = resolveForgePaths();
+if (!paths) process.exit(0);
+
+// Secondary positive signal: structure-versions.json must exist. T05 writes
+// it just before the terminal rm in Phase 4. Resume "start over" /
+// stale-checkpoint cleanup branches do NOT touch structure-versions.json.
+// (H-5c: mtime check removed — sentinel file is the sole idempotency guard.)
+if (!fs.existsSync(paths.structureVersionsPath)) process.exit(0);
+
+// Idempotency: sentinel under .forge/cache/.
+try { fs.mkdirSync(paths.cacheDir, { recursive: true }); } catch (_) {}
+const sentinel = path.join(paths.cacheDir, 'post-init-enhancement-triggered');
+if (fs.existsSync(sentinel)) process.exit(0);
+
+// Build a unique eventId — pid + hrtime guards against same-second collisions
+// when two firings occur in the same wall-clock second.
+const iso = new Date().toISOString().replace(/[:.]/g, '');
+const eventId = `${iso}_enhance_trigger_phase1_${process.pid}_${process.hrtime.bigint()}`;
+
+const now = new Date().toISOString();
+const event = {
+  eventId,
+  taskId: 'enhancement',
+  sprintId: 'enhancement',
+  role: 'hook',
+  action: 'enhancement-trigger',
+  phase: 'post-init',
+  iteration: 1,
+  startTimestamp: now,
+  endTimestamp: now,
+  durationMinutes: 0,
+  model: 'n/a',
+  notes: JSON.stringify({
+    triggerSource: 'post-init',
+    targetPhase: 1,
+    detectedSprintId: 'n/a',
+  }),
+};
+
+// Emit via store-cli.cjs when forgeRoot is known. spawnSync timeout of 3s
+// caps the impact of a hung child process — outer hook timeout is 10s.
+try {
+  if (paths.forgeRoot) {
+    const eventsBucket = path.join(paths.eventsRoot, 'enhancement');
+    fs.mkdirSync(eventsBucket, { recursive: true });
+    const cli = path.join(paths.forgeRoot, 'tools', 'store-cli.cjs');
+    if (fs.existsSync(cli)) {
+      spawnSync('node', [cli, 'emit', 'enhancement', JSON.stringify(event)], {
+        cwd: process.cwd(),
+        timeout: 3000,
+        encoding: 'utf8',
+      });
+    }
+  }
+} catch (emitErr) { logSwallowedError('post-init:emit', emitErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+// Write sentinel AFTER emit so a crash during emit allows a retry on next
+// firing (the user can re-run init if the first attempt failed).
+try { fs.writeFileSync(sentinel, '', 'utf8'); } catch (sentinelErr) { logSwallowedError('post-init:sentinel', sentinelErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+// Inject the slash-command request into the next assistant turn.
+try {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext:
+        'Forge: /forge:init has completed Phase 4. Run /forge:enhance --phase 1 --auto to materialise project-specific starter-pack content from the freshly captured structural snapshot.',
+    },
+  }) + '\n');
+} catch (outputErr) { logSwallowedError('post-init:output', outputErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+process.exit(0);

package/dist/forge-payload/hooks/post-sprint.cjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+// Forge hook: post-sprint
+// PostToolUse hook that fires after a sprint retrospective completes
+// (`collate.cjs <SPRINT_ID> --purge-events` where the ID matches the
+// `*-S\d+` shape) and invokes /forge:enhance --phase 2.
+//
+// The sprint-ID shape gate ensures bug-fix invocations like
+// `collate.cjs FORGE-B07 --purge-events` (which run after every successful
+// bug fix) do NOT trigger sprint-level enhancement.
+//
+// Idempotency: a sprint-specific sentinel file under .forge/cache/ prevents
+// a second firing for the same sprint. Different sprints fire independently.
+//
+// Fail-open: any internal error → stderr warning + exit 0. Hook failure
+// must never block sprint completion.
+
+process.on('uncaughtException', (err) => {
+  try { process.stderr.write(`forge post-sprint: internal error (fail-open): ${err.message}\n`); } catch (_) {}
+  process.exit(0);
+});
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { resolveForgePaths, logSwallowedError } = require('./lib/common.cjs');
+
+let raw = '';
+try { raw = fs.readFileSync(0, 'utf8'); } catch (_) { process.exit(0); }
+
+let envelope;
+try { envelope = JSON.parse(raw); } catch (_) { process.exit(0); }
+
+if (!envelope || envelope.tool_name !== 'Bash') process.exit(0);
+
+const exitCode = envelope.tool_response && envelope.tool_response.exitCode;
+if (exitCode !== 0 && exitCode !== undefined) process.exit(0);
+
+const command = (envelope.tool_input && envelope.tool_input.command) || '';
+
+// Trigger: collate.cjs <PREFIX-S\d+> --purge-events. The capture group
+// extracts the sprint ID for the sentinel and event payload. The
+// `*-S\d+` shape rules out bug IDs like FORGE-B07.
+const TRIGGER_RX = /\bcollate\.cjs\s+(\S*-S\d+)\s+--purge-events\b/;
+const m = command.match(TRIGGER_RX);
+if (!m) process.exit(0);
+
+const detectedSprintId = m[1];
+
+const paths = resolveForgePaths();
+if (!paths) process.exit(0);
+
+try { fs.mkdirSync(paths.cacheDir, { recursive: true }); } catch (_) {}
+const sentinel = path.join(paths.cacheDir, `post-sprint-${detectedSprintId}-enhancement-triggered`);
+if (fs.existsSync(sentinel)) process.exit(0);
+
+const iso = new Date().toISOString().replace(/[:.]/g, '');
+const eventId = `${iso}_enhance_trigger_phase2_${process.pid}_${process.hrtime.bigint()}`;
+
+const now = new Date().toISOString();
+const event = {
+  eventId,
+  taskId: 'enhancement',
+  sprintId: 'enhancement',
+  role: 'hook',
+  action: 'enhancement-trigger',
+  phase: 'post-sprint',
+  iteration: 1,
+  startTimestamp: now,
+  endTimestamp: now,
+  durationMinutes: 0,
+  model: 'n/a',
+  notes: JSON.stringify({
+    triggerSource: 'post-sprint',
+    targetPhase: 2,
+    detectedSprintId,
+  }),
+};
+
+try {
+  if (paths.forgeRoot) {
+    const eventsBucket = path.join(paths.eventsRoot, 'enhancement');
+    fs.mkdirSync(eventsBucket, { recursive: true });
+    const cli = path.join(paths.forgeRoot, 'tools', 'store-cli.cjs');
+    if (fs.existsSync(cli)) {
+      spawnSync('node', [cli, 'emit', 'enhancement', JSON.stringify(event)], {
+        cwd: process.cwd(),
+        timeout: 3000,
+        encoding: 'utf8',
+      });
+    }
+  }
+} catch (emitErr) { logSwallowedError('post-sprint:emit', emitErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+try { fs.writeFileSync(sentinel, '', 'utf8'); } catch (sentinelErr) { logSwallowedError('post-sprint:sentinel', sentinelErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+try {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext:
+        `Forge: sprint ${detectedSprintId} retrospective has completed. Run /forge:enhance --phase 2 to propose KB enhancements derived from the sprint's lessons (proposals are written for review, not auto-applied).`,
+    },
+  }) + '\n');
+} catch (outputErr) { logSwallowedError('post-sprint:output', outputErr, process.env.CLAUDE_PLUGIN_DATA); }
+
+process.exit(0);

package/dist/forge-payload/hooks/triage-error.cjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// Forge PostToolUse hook — error triage
+//
+// Fires after every Bash tool call. If the command is Forge-related and
+// exits non-zero, injects an additionalContext prompt asking Claude to offer
+// the user the option to file a bug via /forge:report-bug.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+
+'use strict';
+
+// FORGE_PATTERNS — inline copy of forge command recognition patterns.
+// Canonical source: hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS (H-1d, FORGE-S25-T08).
+// This file intentionally does NOT require hooks/lib/common.cjs because
+// build-payload.cjs bundles hooks/*.cjs but excludes hooks/lib/ (forge-cli
+// bundle gap). When adding a new forge command, update BOTH this list AND
+// hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS.
+const FORGE_PATTERNS = [
+  /manage-config/,
+  /\.forge\//,
+  /CLAUDE_PLUGIN_ROOT/,
+  /FORGE_ROOT/,
+  /MANAGE_CONFIG/,
+  /engineering\/tools\//,
+  /forge:init/,
+  /forge:health/,
+  /forge:regenerate/,
+  /forge:update/,
+  /forge:add-pipeline/,
+  /forge:add-task/,
+  /forge:plan/,
+  /forge:implement/,
+  /forge:approve/,
+  /forge:commit/,
+  /forge:review/,
+  /forge:sprint/,
+  /forge:run-task/,
+  /forge:run-sprint/,
+  /forge:fix-bug/,
+  /forge:retrospective/,
+  /forge:quiz-agent/,
+  /forge:report-bug/,
+  /forge:enhance/,
+  /forge:collate/,
+  /forge:validate/,
+  /forge:calibrate/,
+  /forge:materialize/,
+  /forge:remove/,
+  /forge:store-query/,
+  /forge:store-repair/,
+  /forge:store-custodian/,
+  /forge:config/,
+  /forge:ask/,
+  /forge:refresh-kb-links/,
+  /store-cli\.cjs/,
+  /validate-store\.cjs/,
+];
+
+function isForgeRelated(command) {
+  return FORGE_PATTERNS.some(p => p.test(command));
+}
+
+// The hook must never exit non-zero — a hook failure would surface as noise to
+// the user and defeat the purpose of silent triage. Wrap everything so that any
+// unexpected error causes a clean no-op exit instead of a crash report.
+process.on('uncaughtException', () => process.exit(0));
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { raw += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const event = JSON.parse(raw);
+
+    if (event.tool_name !== 'Bash') return;
+
+    const command = event.tool_input?.command || '';
+    const exitCode = event.tool_response?.exitCode;
+
+    // Only act on non-zero exits for Forge-related commands.
+    if (!isForgeRelated(command)) return;
+    if (exitCode === 0 || exitCode === undefined) return;
+
+    const stderr = event.tool_response?.stderr || '';
+    const output = event.tool_response?.output || '';
+    const errorSnippet = (stderr || output).split('\n').slice(0, 3).join(' ').trim();
+
+    const context =
+      `FORGE_ERROR_TRIAGE: A Forge command just failed (exit ${exitCode}). ` +
+      (errorSnippet ? `First error line: "${errorSnippet}". ` : '') +
+      `Tell the user what went wrong, then ask: ` +
+      `"Would you like to file this as a Forge bug to help improve the tool? ` +
+      `Run /forge:report-bug and I will pre-fill the report from this conversation."`;
+
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: context,
+      },
+    }) + '\n');
+  } catch {
+    // Swallow all errors — this hook must never become the problem.
+  }
+});

package/dist/forge-payload/hooks/triage-error.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Forge PostToolUse hook — error triage
+//
+// Fires after every Bash tool call. If the command is Forge-related and
+// exits non-zero, injects an additionalContext prompt asking Claude to offer
+// the user the option to file a bug via /forge:report-bug.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+
+'use strict';
+
+// FORGE_PATTERNS — inline copy of forge command recognition patterns.
+// Canonical source: hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS (H-1d, FORGE-S25-T08).
+// This file intentionally does NOT require hooks/lib/common.cjs because
+// build-payload.cjs bundles hooks/*.js but excludes hooks/lib/ (forge-cli
+// bundle gap). When adding a new forge command, update BOTH this list AND
+// hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS.
+const FORGE_PATTERNS = [
+  /manage-config/,
+  /\.forge\//,
+  /CLAUDE_PLUGIN_ROOT/,
+  /FORGE_ROOT/,
+  /MANAGE_CONFIG/,
+  /engineering\/tools\//,
+  /forge:init/,
+  /forge:health/,
+  /forge:regenerate/,
+  /forge:update/,
+  /forge:add-pipeline/,
+];
+
+function isForgeRelated(command) {
+  return FORGE_PATTERNS.some(p => p.test(command));
+}
+
+// The hook must never exit non-zero — a hook failure would surface as noise to
+// the user and defeat the purpose of silent triage. Wrap everything so that any
+// unexpected error causes a clean no-op exit instead of a crash report.
+process.on('uncaughtException', () => process.exit(0));
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { raw += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const event = JSON.parse(raw);
+
+    if (event.tool_name !== 'Bash') return;
+
+    const command = event.tool_input?.command || '';
+    const exitCode = event.tool_response?.exitCode;
+
+    // Only act on non-zero exits for Forge-related commands.
+    if (!isForgeRelated(command)) return;
+    if (exitCode === 0 || exitCode === undefined) return;
+
+    const stderr = event.tool_response?.stderr || '';
+    const output = event.tool_response?.output || '';
+    const errorSnippet = (stderr || output).split('\n').slice(0, 3).join(' ').trim();
+
+    const context =
+      `FORGE_ERROR_TRIAGE: A Forge command just failed (exit ${exitCode}). ` +
+      (errorSnippet ? `First error line: "${errorSnippet}". ` : '') +
+      `Tell the user what went wrong, then ask: ` +
+      `"Would you like to file this as a Forge bug to help improve the tool? ` +
+      `Run /forge:report-bug and I will pre-fill the report from this conversation."`;
+
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: context,
+      },
+    }) + '\n');
+  } catch {
+    // Swallow all errors — this hook must never become the problem.
+  }
+});