@entelligentsia/forgecli 0.11.3 → 0.15.0

package/dist/forge-payload/hooks/check-update.js

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+// Forge session-start hook — runs on SessionStart
+// 1. Injects Forge-awareness context if this project has a .forge/ directory.
+// 2. Checks once per day whether a newer version is available.
+// 3. Detects distribution switches (forge@forge ↔ forge@skillforge) and
+//    refreshes paths.forgeRoot in .forge/config.json so subagents always
+//    reference the correct installed plugin path.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+// Works on Linux, macOS, and Windows wherever Claude Code runs.
+
+'use strict';
+
+// This hook must never exit non-zero — a hook failure surfaces as noise to the
+// user and blocks session start context. Any uncaught exception exits 0.
+process.on('uncaughtException', () => process.exit(0));
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+
+const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || '.';
+const dataDir = process.env.CLAUDE_PLUGIN_DATA || path.join(os.tmpdir(), 'forge-plugin-data');
+// Plugin-level cache: throttle only (lastCheck, remoteVersion) — shared across all projects.
+const pluginCacheFile = path.join(dataDir, 'update-check-cache.json');
+// Project-level cache: migration state (migratedFrom, localVersion, distribution, forgeRoot) — per project.
+const forgeDir = '.forge';
+const hasForge = fs.existsSync(forgeDir) && fs.existsSync(path.join(forgeDir, 'config.json'));
+const projectCacheFile = path.join(forgeDir, 'update-check-cache.json');
+
+// Distribution detection — derived from plugin path at runtime.
+// The cache path encodes the marketplace name, making this more reliable than
+// reading fields from plugin.json (which may be stale after a switch).
+function detectDistribution(root) {
+  return root.includes('/cache/skillforge/forge/') || root.includes('/marketplaces/skillforge/forge/')
+    ? 'forge@skillforge' : 'forge@forge';
+}
+const currentDistribution = detectDistribution(pluginRoot);
+
+// --- Multi-plugin scanning ---
+// Scans all known plugin locations to detect multiple Forge installations.
+// Returns array of installation records with version, distribution, scope, enabled status.
+// Optional parameters for dependency injection (testing).
+function scanPluginInstallations(options) {
+  const installations = [];
+  const homeDir = (options && options.homeDir) || os.homedir();
+  const cwd = (options && options.cwd) || process.cwd();
+
+  // Candidate paths — user scope (global) and project scope (local)
+  // Also scan skillforge subdirectory variant (skillforge/forge/forge)
+  const basePaths = [
+    path.join(homeDir, '.claude', 'plugins'),
+    path.join(cwd, '.claude', 'plugins'),
+  ];
+  const variants = ['cache', 'marketplaces'];
+  const pluginNames = ['forge/forge', 'skillforge/forge/forge'];
+
+  const candidates = [];
+  for (const basePath of basePaths) {
+    for (const variant of variants) {
+      for (const pluginName of pluginNames) {
+        candidates.push(path.join(basePath, variant, pluginName));
+      }
+    }
+  }
+
+  for (const candidate of candidates) {
+    try {
+      const pluginJsonPath = path.join(candidate, '.claude-plugin', 'plugin.json');
+      if (!fs.existsSync(pluginJsonPath)) continue;
+
+      const manifest = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8'));
+      // Determine scope: user-scope paths start with homeDir/.claude, project-scope start with cwd/.claude
+      // Use cwd-relative check first to avoid false positives when cwd is subdir of homeDir
+      const isProjectScope = candidate.startsWith(path.join(cwd, '.claude'));
+      const isUserScope = candidate.startsWith(path.join(homeDir, '.claude'));
+      const scope = isProjectScope ? 'project' : (isUserScope ? 'user' : 'unknown');
+      const enabled = isPluginEnabled(candidate, scope, homeDir, cwd);
+
+      // Avoid duplicates — skip if same path already recorded
+      if (installations.some(i => i.path === candidate)) continue;
+
+      installations.push({
+        path: candidate,
+        version: manifest.version || 'unknown',
+        distribution: detectDistribution(candidate),
+        scope: scope,
+        enabled: enabled,
+      });
+    } catch (e) {
+      // Non-fatal — skip broken installations silently
+    }
+  }
+
+  return installations;
+}
+
+// Check if forge plugin is enabled in settings files.
+// Returns true if no explicit disable found, false if disabled.
+function isPluginEnabled(pluginPath, scope, homeDir, cwd) {
+  try {
+    // Check user settings: ~/.claude/settings.json
+    const userSettingsPath = path.join(homeDir, '.claude', 'settings.json');
+    if (fs.existsSync(userSettingsPath)) {
+      const userSettings = JSON.parse(fs.readFileSync(userSettingsPath, 'utf8'));
+      if (userSettings.disablePlugin === true) return false;
+      // Check for per-plugin disable (if supported in future)
+      if (userSettings.plugins && userSettings.plugins.forge === false) return false;
+    }
+
+    // Check project settings: ./.claude/settings.local.json
+    const projectSettingsPath = path.join(cwd, '.claude', 'settings.local.json');
+    if (fs.existsSync(projectSettingsPath)) {
+      const projectSettings = JSON.parse(fs.readFileSync(projectSettingsPath, 'utf8'));
+      if (projectSettings.disablePlugin === true) return false;
+      if (projectSettings.plugins && projectSettings.plugins.forge === false) return false;
+    }
+
+    return true; // Default: enabled
+  } catch (e) {
+    return true; // Non-fatal — assume enabled if cannot read settings
+  }
+}
+
+// Determine the correct update-check URL for this distribution.
+// Each distribution's plugin.json carries its own updateUrl pointing at the
+// branch it was installed from (main for forge@forge, release for forge@skillforge),
+// so we read it directly — no hardcoded per-distribution URLs needed.
+const FALLBACK_UPDATE_URL = 'https://raw.githubusercontent.com/Entelligentsia/forge/main/forge/.claude-plugin/plugin.json';
+
+const ALLOWED_DOMAINS = ['raw.githubusercontent.com'];
+
+function validateUpdateUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const hostname = parsed.hostname.toLowerCase();
+    if (!ALLOWED_DOMAINS.some(d => hostname === d || hostname.endsWith('.' + d))) {
+      process.stderr.write(`forge-update: rejected update URL with disallowed domain '${hostname}', falling back\n`);
+      return FALLBACK_UPDATE_URL;
+    }
+    return url;
+  } catch {
+    return FALLBACK_UPDATE_URL;
+  }
+}
+
+function getUpdateUrl() {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(pluginRoot, '.claude-plugin', 'plugin.json'), 'utf8'));
+    return validateUpdateUrl(manifest.updateUrl || FALLBACK_UPDATE_URL);
+  } catch { return FALLBACK_UPDATE_URL; }
+}
+const remoteUrl = getUpdateUrl();
+const checkInterval = 86400; // 24 hours in seconds
+
+fs.mkdirSync(dataDir, { recursive: true });
+
+// --- Forge-awareness context injection ---
+let forgeContext = '';
+if (fs.existsSync('.forge') && fs.existsSync(path.join('.forge', 'config.json'))) {
+  forgeContext =
+    'This project uses Forge AI-SDLC. Engineering knowledge base: engineering/. ' +
+    'Generated workflows: .forge/workflows/. Sprint and task store: .forge/store/. ' +
+    'Use the project slash commands (/plan, /implement, /sprint-plan) to drive development. ' +
+    'Run /forge:health to check knowledge base currency.';
+}
+
+// --- Update check helpers ---
+function localVersion() {
+  try {
+    const p = path.join(pluginRoot, '.claude-plugin', 'plugin.json');
+    return JSON.parse(fs.readFileSync(p, 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function fetchRemoteVersion(cb) {
+  https.get(remoteUrl, { timeout: 5000 }, (res) => {
+    let body = '';
+    res.on('data', chunk => { body += chunk; });
+    res.on('end', () => {
+      try { cb(JSON.parse(body).version || ''); } catch { cb(''); }
+    });
+  }).on('error', () => cb(''))
+    .on('timeout', function() { this.destroy(); cb(''); });
+}
+
+function buildUpdateMsg(remoteVersion, local) {
+  return remoteVersion && remoteVersion !== local
+    ? `Forge ${remoteVersion} available (you have ${local}). Run /forge:update to review changes and update.`
+    : '';
+}
+
+function emit(forgeCtx, updateMsg) {
+  if (!forgeCtx && !updateMsg) return;
+  const combined = [forgeCtx, updateMsg].filter(Boolean).join(' ');
+  const escaped = combined.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, ' ');
+  process.stdout.write(`{"additionalContext":"${escaped}"}\n`);
+}
+
+// --- Main logic (only runs when executed as script, not when required as module) ---
+if (require.main === module) {
+  const local = localVersion();
+  const now = Math.floor(Date.now() / 1000);
+
+  // Scan for all plugin installations — builds inventory for multi-plugin awareness.
+  const allInstallations = scanPluginInstallations();
+
+// Plugin-level cache: throttle (lastCheck, remoteVersion) — shared, not migration state.
+let pluginCache = null;
+if (fs.existsSync(pluginCacheFile)) {
+  try { pluginCache = JSON.parse(fs.readFileSync(pluginCacheFile, 'utf8')); } catch { pluginCache = null; }
+}
+
+// Project-level cache: migration state — per project.
+let projectCache = null;
+if (hasForge && fs.existsSync(projectCacheFile)) {
+  try { projectCache = JSON.parse(fs.readFileSync(projectCacheFile, 'utf8')); } catch { projectCache = null; }
+}
+
+// FR-010: Backfill forgeRef from localVersion if missing in existing cache.
+if (projectCache && !projectCache.forgeRef && projectCache.localVersion) {
+  projectCache.forgeRef = projectCache.localVersion;
+}
+
+// --- Distribution + forgeRoot/forgeRef sync (always runs before update-check logic) ---
+// Refreshes paths.forgeRoot and paths.forgeRef in config.json and the distribution/
+// forgeRoot/forgeRef fields in the project cache. Handles distribution switches
+// transparently — the user gets a clear message and all path references are
+// corrected before any command runs.
+let distributionSwitchMsg = '';
+if (hasForge && pluginRoot !== '.') {
+  // Keep paths.forgeRoot and paths.forgeRef in .forge/config.json in sync.
+  // Generated workflows read forgeRoot to invoke tools without needing CLAUDE_PLUGIN_ROOT.
+  // forgeRef is the version-based portable field (FR-010).
+  try {
+    const configPath = path.join(forgeDir, 'config.json');
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (!cfg.paths) cfg.paths = {};
+    let configChanged = false;
+    if (cfg.paths.forgeRoot !== pluginRoot) {
+      cfg.paths.forgeRoot = pluginRoot;
+      configChanged = true;
+    }
+    // FR-010: Write forgeRef from the local plugin version.
+    if (!cfg.paths.forgeRef || cfg.paths.forgeRef !== local) {
+      cfg.paths.forgeRef = local;
+      configChanged = true;
+    }
+    if (configChanged) {
+      fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n');
+    }
+  } catch { /* non-fatal */ }
+
+  if (projectCache) {
+    const storedRoot = projectCache.forgeRoot;
+    const storedDist = projectCache.distribution;
+    const switched = storedRoot && storedRoot !== pluginRoot;
+
+    // Build distribution switch message when the active plugin path changed and
+    // the distribution name is different (e.g. forge@skillforge → forge@forge).
+    if (switched && storedDist && storedDist !== currentDistribution) {
+      const versionNote = projectCache.localVersion && projectCache.localVersion !== local
+        ? ` Version: ${projectCache.localVersion} → ${local}.`
+        : '';
+      distributionSwitchMsg =
+        `Plugin distribution switched from ${storedDist} to ${currentDistribution}.${versionNote}` +
+        ` paths.forgeRoot updated. Run /forge:update to verify migration state.`;
+    }
+
+    // Sync distribution + forgeRoot + forgeRef into the project cache whenever they drift.
+    // FR-002: Preserve updateStatus, pendingReason, pendingMigrations if present.
+    if (storedRoot !== pluginRoot || storedDist !== currentDistribution) {
+      try {
+        const updated = { ...projectCache, distribution: currentDistribution, forgeRoot: pluginRoot, forgeRef: local };
+        fs.writeFileSync(projectCacheFile, JSON.stringify(updated, null, 2) + '\n');
+        projectCache = updated; // keep in-memory copy consistent
+      } catch { /* non-fatal */ }
+    }
+  }
+}
+
+// FR-002: Surface pending-state message to the user if update is incomplete.
+let pendingStateMsg = '';
+if (hasForge && projectCache && projectCache.updateStatus === 'pending') {
+  const pendingMigrations = Array.isArray(projectCache.pendingMigrations)
+    ? projectCache.pendingMigrations.join(', ')
+    : '(unknown)';
+  pendingStateMsg =
+    `Forge update is incomplete — pending migration(s): ${pendingMigrations}.` +
+    ` Run /forge:update to continue or /forge:migrate to complete.`;
+}
+
+const elapsed = pluginCache ? now - (pluginCache.lastCheck || 0) : Infinity;
+
+// Build multi-plugin awareness message if multiple installations found.
+let multiPluginMsg = '';
+if (allInstallations.length >= 2) {
+  const activeInst = allInstallations.find(i => i.path === pluginRoot) || allInstallations[0];
+  const otherInsts = allInstallations.filter(i => i.path !== activeInst.path);
+  if (otherInsts.length > 0) {
+    const otherDesc = otherInsts.map(i => `${i.version} (${i.distribution}, ${i.scope})`).join(', ');
+    multiPluginMsg = `Also installed: ${otherDesc}. `;
+  }
+}
+
+if (elapsed < checkInterval) {
+  // Plugin cache still fresh — use stored remote version.
+  // Detect post-install: if the project's recorded localVersion differs from
+  // the running plugin version, the plugin was updated since last migration.
+  let postInstallMsg = '';
+  if (hasForge && projectCache && projectCache.localVersion && projectCache.localVersion !== local) {
+    // Record the pre-install version as baseline, update localVersion.
+    // FR-010: Include forgeRef. FR-002: updateStatus/pendingReason/pendingMigrations
+    // are preserved via spread.
+    const updated = {
+      ...projectCache,
+      migratedFrom: projectCache.localVersion,
+      localVersion: local,
+      distribution: currentDistribution,
+      forgeRoot: pluginRoot,
+      forgeRef: local,
+    };
+    try { fs.writeFileSync(projectCacheFile, JSON.stringify(updated, null, 2) + '\n'); } catch { /* non-fatal */ }
+    // Reset plugin cache lastCheck so we fetch a fresh remote version next session.
+    try { fs.writeFileSync(pluginCacheFile, JSON.stringify({ ...pluginCache, lastCheck: 0 }, null, 2) + '\n'); } catch { /* non-fatal */ }
+    // Suppress post-install message when a distribution switch message already covers the event.
+    if (!distributionSwitchMsg) {
+      postInstallMsg = `Forge was updated to ${local} (was ${projectCache.localVersion}). Run /forge:update to review changes and update.`;
+    }
+  }
+  const baseMsg = distributionSwitchMsg || postInstallMsg || buildUpdateMsg((pluginCache && pluginCache.remoteVersion) || '', local);
+  // FR-002: Append pending-state message if present.
+  const updateMsg = baseMsg ? multiPluginMsg + baseMsg : baseMsg;
+  const pendingMsg = pendingStateMsg ? ' ' + pendingStateMsg : '';
+  emit(forgeContext, (updateMsg + pendingMsg).trim());
+} else {
+  // Plugin cache expired or missing — fetch fresh remote version.
+  fetchRemoteVersion((remoteVersion) => {
+    if (remoteVersion) {
+      // Update plugin-level throttle cache.
+      try { fs.writeFileSync(pluginCacheFile, JSON.stringify({ lastCheck: now, remoteVersion }, null, 2) + '\n'); } catch { /* non-fatal */ }
+      // Seed project-level cache on first run if not yet present.
+      // FR-010: Include forgeRef alongside forgeRoot.
+      if (hasForge && !projectCache) {
+        try {
+          fs.writeFileSync(projectCacheFile, JSON.stringify({
+            migratedFrom: local, localVersion: local,
+            distribution: currentDistribution, forgeRoot: pluginRoot,
+            forgeRef: local,
+            updateStatus: 'complete', pendingReason: null, pendingMigrations: [],
+          }, null, 2) + '\n');
+        } catch { /* non-fatal */ }
+      } else if (hasForge && projectCache && !projectCache.localVersion) {
+        // Backfill localVersion (and distribution/forgeRoot/forgeRef) if missing.
+        // FR-002: Preserve updateStatus/pendingReason/pendingMigrations via spread.
+        try {
+          fs.writeFileSync(projectCacheFile, JSON.stringify({
+            ...projectCache, localVersion: local,
+            distribution: currentDistribution, forgeRoot: pluginRoot,
+            forgeRef: local,
+          }, null, 2) + '\n');
+        } catch { /* non-fatal */ }
+      }
+    }
+    const baseMsg = distributionSwitchMsg || buildUpdateMsg(remoteVersion, local);
+    // FR-002: Append pending-state message if present.
+    const updateMsg = baseMsg ? multiPluginMsg + baseMsg : baseMsg;
+    const pendingMsg = pendingStateMsg ? ' ' + pendingStateMsg : '';
+    emit(forgeContext, (updateMsg + pendingMsg).trim());
+  });
+}
+}
+
+// Export functions for testing
+module.exports = { scanPluginInstallations, isPluginEnabled, detectDistribution, validateUpdateUrl };

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

@@ -0,0 +1,158 @@
+#!/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
+
+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/triage-error.js

@@ -0,0 +1,71 @@
+#!/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';
+
+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.
+  }
+});