forge-workflow 0.0.10 → 0.1.0-beta.2

package/lib/commands/export.js

@@ -0,0 +1,237 @@
+'use strict';
+
+const path = require('node:path');
+const {
+	runJsonlProjectionConsumer,
+	readProjection,
+	resolveProjectionDir,
+	writeProjection,
+	DEFAULT_PROJECTION_TARGET,
+} = require('../kernel/projection-jsonl-writer');
+
+// Full set the consumer may call — including the retry (recordProjectionFailure)
+// and dead-letter (deadLetterProjection) paths — so a partially-implemented
+// broker is skipped cleanly instead of failing mid-run.
+const PROJECTION_BROKER_METHODS = [
+	'listProjectionOutbox',
+	'loadProjectionModel',
+	'markProjectionDelivered',
+	'recordProjectionFailure',
+	'deadLetterProjection',
+];
+
+/**
+ * Parse `forge export` options from positional args (and a parsed flags object
+ * as a fallback). Supported: --import, --dry-run, --json, --dir=<path> / --dir <path>.
+ */
+function parseExportOptions(args = [], flags = {}) {
+	const options = {
+		import: Boolean(flags.import),
+		dryRun: Boolean(flags['dry-run'] || flags.dryRun),
+		json: Boolean(flags.json),
+		dir: flags.dir,
+	};
+
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === '--import') options.import = true;
+		else if (arg === '--dry-run') options.dryRun = true;
+		else if (arg === '--json') options.json = true;
+		else if (arg.startsWith('--dir=')) options.dir = arg.slice('--dir='.length);
+		else if (arg === '--dir') {
+			// only consume the next token when it is a real value, not another flag
+			const next = args[i + 1];
+			if (next && !next.startsWith('--')) {
+				options.dir = next;
+				i += 1;
+			}
+		}
+	}
+
+	return options;
+}
+
+function brokerSupportsProjection(broker) {
+	return Boolean(broker) && PROJECTION_BROKER_METHODS.every(method => typeof broker[method] === 'function');
+}
+
+function resolveDirArg(dirArg, projectRoot) {
+	if (!dirArg) return undefined;
+	return path.resolve(projectRoot || process.cwd(), dirArg);
+}
+
+function renderHuman(payload) {
+	if (payload.error) return `forge export failed: ${payload.error}`;
+	if (payload.imported === true) {
+		const { issues, comments, dependencies } = payload.counts;
+		const skipped = issues.skipped + comments.skipped + dependencies.skipped;
+		// Report "Imported N" ONLY for records actually written; a re-import that
+		// applies nothing (everything already present) must not claim it imported them.
+		if (payload.applied === 0) {
+			return `Kernel projection at ${payload.dir} is already hydrated — nothing new imported`
+				+ ` (${skipped} record${skipped === 1 ? '' : 's'} already present)`;
+		}
+		return `Imported Kernel projection from ${payload.dir}`
+			+ ` (${issues.inserted} issues, ${comments.inserted} comments, ${dependencies.inserted} dependencies`
+			+ (skipped ? `; ${skipped} already present` : '') + ')';
+	}
+	if (payload.imported === false) return payload.message;
+	if (payload.dryRun) return `${payload.pending} pending projection entr${payload.pending === 1 ? 'y' : 'ies'} → ${payload.dir} (dry run, nothing written)`;
+	if (payload.skipped) return payload.message;
+	if (payload.exported) return `Exported Kernel projection to ${payload.dir} (drained ${payload.drained})`;
+	return payload.message || 'Nothing to export';
+}
+
+function finalize(options, payload) {
+	const output = options.json ? JSON.stringify(payload, null, 2) : renderHuman(payload);
+	return { ...payload, output, json: Boolean(options.json) };
+}
+
+/**
+ * Forge Export Command (D16 — Kernel JSONL portability projection).
+ *
+ * Explicit, Kernel-owned projection of issues/comments/dependencies to
+ * deterministic git-tracked JSONL under `.forge/kernel/`. This is NOT auto-run on
+ * mutation/push (D16 forbids that); it is an on-demand portability/bootstrap
+ * surface. The `--import` path reads a committed snapshot back from disk (no
+ * broker required) and verifies its manifest integrity.
+ *
+ * @module commands/export
+ */
+module.exports = {
+	name: 'export',
+	description: 'Export the Kernel backlog to deterministic git-tracked JSONL (D16 portability projection)',
+	usage: 'forge export [--dir <path>] [--dry-run] [--json] [--import]',
+	flags: {},
+
+	/**
+	 * @param {string[]} args - Positional arguments / flags
+	 * @param {object} flags - Parsed CLI flags (fallback source)
+	 * @param {string} projectRoot - Project root path
+	 * @param {object} [opts] - Dependency injection: _broker, _writer, _now, _fs
+	 */
+	async handler(args = [], flags = {}, projectRoot, opts = {}) {
+		const options = parseExportOptions(args, flags || {});
+		const now = opts._now || new Date().toISOString();
+		const writer = opts._writer || writeProjection;
+		const fsImpl = opts._fs;
+		const projectionDir = resolveDirArg(options.dir, projectRoot);
+
+		// --- Import / hydrate (read committed JSONL → write kernel.sqlite) ---
+		// readProjection verifies snapshot integrity (sha256, per-file kind, manifest
+		// counts, and schema_version compatibility) and throws on any mismatch, so an
+		// incompatible/tampered snapshot never reaches the kernel writer.
+		if (options.import) {
+			try {
+				const snapshot = readProjection({ projectionDir, projectRoot, fsImpl });
+				if (!snapshot) {
+					return finalize(options, {
+						success: true,
+						imported: false,
+						dir: resolveProjectionDir(projectionDir, projectRoot),
+						message: 'No projection snapshot found to import',
+					});
+				}
+
+				const read = {
+					issues: snapshot.model.issues.length,
+					comments: snapshot.model.comments.length,
+					dependencies: snapshot.model.dependencies.length,
+				};
+
+				// Hydration requires a projection-capable Kernel broker (importIssues).
+				// The CLI injects one for `export` (a Kernel-tool command); without it we
+				// validated the snapshot but cannot write — say so instead of claiming an
+				// import happened.
+				const importBroker = opts._broker || null;
+				if (!importBroker || typeof importBroker.importIssues !== 'function') {
+					return finalize(options, {
+						success: true,
+						imported: false,
+						dir: snapshot.dir,
+						read,
+						message: `Read ${read.issues} issues from ${snapshot.dir} but no Kernel broker is `
+							+ 'available to import into — nothing was written',
+					});
+				}
+
+				// importIssues requires the schema/migrations to exist; the CLI broker is
+				// pre-initialized, but initialize() is idempotent so calling it is safe.
+				if (typeof importBroker.initialize === 'function') {
+					await importBroker.initialize();
+				}
+
+				// Idempotent + transactional upsert-by-id (ON CONFLICT DO NOTHING).
+				const summary = await importBroker.importIssues(snapshot.model, { now });
+				const applied = summary.issues.inserted + summary.comments.inserted + summary.dependencies.inserted;
+
+				return finalize(options, {
+					success: true,
+					imported: true,
+					dir: snapshot.dir,
+					counts: summary,
+					applied,
+				});
+			} catch (error) {
+				return finalize(options, { success: false, imported: false, error: error.message });
+			}
+		}
+
+		// --- Export (requires a projection-capable Kernel broker) ------------
+		const broker = opts._broker || null;
+		if (!brokerSupportsProjection(broker)) {
+			return finalize(options, {
+				success: true,
+				exported: false,
+				skipped: true,
+				message: 'No Kernel broker available — nothing to export',
+			});
+		}
+
+		if (options.dryRun) {
+			const pending = (await broker.listProjectionOutbox({
+				target: DEFAULT_PROJECTION_TARGET,
+				status: 'pending',
+				now,
+			})) || [];
+			return finalize(options, {
+				success: true,
+				exported: false,
+				dryRun: true,
+				pending: pending.length,
+				dir: resolveProjectionDir(projectionDir, projectRoot),
+			});
+		}
+
+		try {
+			const run = await runJsonlProjectionConsumer({ broker, projectionDir, projectRoot, now, writer });
+
+			// A write failure leaves entries retried/dead-lettered without a snapshot;
+			// surface it as a failure rather than silently reporting success.
+			if (!run.written && run.error) {
+				return finalize(options, {
+					success: false,
+					exported: false,
+					error: run.error,
+					drained: run.drained,
+					retried: run.retried,
+					dead: run.dead,
+					dir: resolveProjectionDir(projectionDir, projectRoot),
+				});
+			}
+
+			return finalize(options, {
+				success: true,
+				exported: run.written,
+				drained: run.drained,
+				delivered: run.delivered,
+				retried: run.retried,
+				dead: run.dead,
+				dir: run.write ? run.write.dir : resolveProjectionDir(projectionDir, projectRoot),
+				files: run.write ? run.write.files : [],
+			});
+		} catch (error) {
+			return finalize(options, { success: false, exported: false, error: error.message });
+		}
+	},
+};

package/lib/commands/gate.js

@@ -0,0 +1,192 @@
+'use strict';
+
+/**
+ * `forge gate <enable|disable|approve|reject|status|check> ...`
+ *
+ * Two families over the same known-gate set:
+ *
+ *  TOGGLE (config surface): `enable|disable <gate-id>` set
+ *  `workflow.gates.<gate-id>.enabled` true/false in `.forge/config.yaml`. The shipped
+ *  resolver (`applyEnabledConfig`) already consumes this field, so `forge options
+ *  gates --json` reflects the flip with zero new read code. Write-time validation:
+ *  an unknown gate id (or a locked gate being disabled) errors BEFORE anything is
+ *  written — never mid-run.
+ *
+ *  EVENTS (gates-as-kernel-events — Fable's insight): `approve|reject <issue> <gate>`
+ *  record a durable `gate.approved` / `gate.rejected` event on the issue; `status`
+ *  lists them (resume-safe after a compaction/crash); `check` exits 0 iff the gate is
+ *  DISABLED or an approval event exists — the reusable enforcement primitive a stage
+ *  skill calls. See lib/gate-events.js and docs/work/2026-07-04-kernel-native-skills/
+ *  decisions.md.
+ */
+
+const path = require('node:path');
+const { setConfigOverride } = require('../config-writer');
+const { getDefaultRuntimeGraph, getResolvedRuntimeGraph } = require('../core/runtime-graph');
+const {
+  recordGateEvent,
+  listGateEvents,
+  isGateApproved,
+} = require('../gate-events');
+
+const TOGGLE_ACTIONS = new Set(['enable', 'disable']);
+const EVENT_ACTIONS = new Set(['approve', 'reject', 'status', 'check']);
+
+function usage() {
+  return 'Usage: forge gate <enable|disable|approve|reject|status|check> [<issue-id>] <gate-id> [--reason <text>] [--json]';
+}
+
+// The known-toggle set is gates PLUS unlocked toggleable rails (e.g.
+// rail.kernel_tracking): both are governed through the same `forge gate
+// enable|disable` surface and the resolver's rail-aware workflow.gates loop.
+// The gate.* / rail.* id namespaces are disjoint, so one flat map is unambiguous.
+function knownGates() {
+  const graph = getDefaultRuntimeGraph();
+  return new Map([...graph.gates, ...graph.rails].map(primitive => [primitive.id, primitive]));
+}
+
+// Kernel deps + env are threaded through the command opts (4th handler arg) so tests
+// and the orchestrator can inject a shared, already-migrated kernel.
+function kernelDeps(opts = {}) {
+  return { kernelBroker: opts.kernelBroker, kernelDriver: opts.kernelDriver };
+}
+
+function validateKnownGate(gateId) {
+  const gates = knownGates();
+  const gate = gates.get(gateId);
+  if (!gate) {
+    return {
+      ok: false,
+      error: `Unknown gate '${gateId}'. Known gates: ${[...gates.keys()].join(', ')}`,
+    };
+  }
+  return { ok: true, gate };
+}
+
+function handleToggle(action, gateId, projectRoot) {
+  if (!gateId) {
+    return { success: false, error: `Missing gate id.\n${usage()}` };
+  }
+  const known = validateKnownGate(gateId);
+  if (!known.ok) return { success: false, error: known.error };
+  if (action === 'disable' && known.gate.locked === true) {
+    return { success: false, error: `Cannot disable locked gate '${gateId}'.` };
+  }
+
+  const enabled = action === 'enable';
+  const { configPath } = setConfigOverride(
+    projectRoot,
+    ['workflow', 'gates', gateId, 'enabled'],
+    enabled,
+  );
+  const where = path.relative(projectRoot, configPath) || configPath;
+  return {
+    success: true,
+    output: `${action}d gate '${gateId}' (workflow.gates.${gateId}.enabled=${enabled}) in ${where}`,
+  };
+}
+
+async function handleDecision(action, issueId, gateId, flags, projectRoot, opts) {
+  if (!issueId || !gateId) {
+    return { success: false, error: `Missing issue id or gate id.\n${usage()}` };
+  }
+  const known = validateKnownGate(gateId);
+  if (!known.ok) return { success: false, error: known.error };
+
+  const decision = action === 'approve' ? 'approved' : 'rejected';
+  const reason = typeof flags.reason === 'string' ? flags.reason : undefined;
+  const result = await recordGateEvent(projectRoot, {
+    issueId,
+    gateId,
+    decision,
+    reason,
+    env: opts.env,
+    deps: kernelDeps(opts),
+  });
+
+  if (result.issueMissing) {
+    return { success: false, error: `Issue '${issueId}' not found.` };
+  }
+
+  const verb = action === 'approve' ? 'approved' : 'rejected';
+  const suffix = result.duplicate ? ' (already recorded)' : '';
+  const reasonNote = reason ? ` — ${reason}` : '';
+  return {
+    success: true,
+    duplicate: result.duplicate === true,
+    actor: result.actor,
+    output: `${verb} gate '${gateId}' for ${issueId} (actor ${result.actor})${reasonNote}${suffix}`,
+  };
+}
+
+async function handleStatus(issueId, flags, projectRoot, opts) {
+  if (!issueId) {
+    return { success: false, error: `Missing issue id.\n${usage()}` };
+  }
+  const events = await listGateEvents(projectRoot, issueId, { deps: kernelDeps(opts) });
+
+  if (flags.json) {
+    return { success: true, output: JSON.stringify({ issue: issueId, events }, null, 2) };
+  }
+
+  if (events.length === 0) {
+    return { success: true, output: `No gate events for ${issueId}.` };
+  }
+  const lines = events.map(event => {
+    const label = event.event_type === 'gate.approved' ? 'APPROVED' : 'REJECTED';
+    const reason = event.reason ? ` — ${event.reason}` : '';
+    return `${label} ${event.gate} by ${event.actor} at ${event.created_at}${reason}`;
+  });
+  return { success: true, output: `Gate events for ${issueId}:\n${lines.join('\n')}` };
+}
+
+async function handleCheck(issueId, gateId, projectRoot, opts) {
+  if (!issueId || !gateId) {
+    return { success: false, error: `Missing issue id or gate id.\n${usage()}` };
+  }
+  const known = validateKnownGate(gateId);
+  if (!known.ok) return { success: false, error: known.error };
+
+  // Disabled gate/rail → satisfied without any approval event (read via the shipped
+  // resolver). Rails share the workflow.gates toggle surface, so check both collections.
+  const resolved = getResolvedRuntimeGraph({ projectRoot });
+  const resolvedGate = [...resolved.gates, ...resolved.rails].find(gate => gate.id === gateId);
+  if (resolvedGate && resolvedGate.enabled === false) {
+    return { success: true, output: `gate ${gateId} is disabled — satisfied for ${issueId}` };
+  }
+
+  const approved = await isGateApproved(projectRoot, issueId, gateId, { deps: kernelDeps(opts) });
+  if (approved) {
+    return { success: true, output: `gate ${gateId} approved for ${issueId}` };
+  }
+  return { success: false, error: `gate ${gateId} not approved for ${issueId}` };
+}
+
+async function handler(args, flags = {}, projectRoot = process.cwd(), opts = {}) {
+  const [action, ...rest] = args;
+
+  if (TOGGLE_ACTIONS.has(action)) {
+    return handleToggle(action, rest[0], projectRoot);
+  }
+  if (EVENT_ACTIONS.has(action)) {
+    if (action === 'status') {
+      return handleStatus(rest[0], flags, projectRoot, opts);
+    }
+    if (action === 'check') {
+      return handleCheck(rest[0], rest[1], projectRoot, opts);
+    }
+    return handleDecision(action, rest[0], rest[1], flags, projectRoot, opts);
+  }
+
+  return {
+    success: false,
+    error: `Expected 'enable', 'disable', 'approve', 'reject', 'status', or 'check'.\n${usage()}`,
+  };
+}
+
+module.exports = {
+  name: 'gate',
+  description: 'Toggle a workflow gate, or record/query human-gate approval events',
+  usage: usage(),
+  handler,
+};

package/lib/commands/hooks.js

@@ -0,0 +1,242 @@
+'use strict';
+
+/**
+ * `forge hooks install --global [--harness codex|hermes|all] [--dry-run]`
+ *
+ * The opt-in, CONSENT-GUARDED delivery path for the last native-hooks gap
+ * (kernel issue 66dd5a1f, epics 90f2f631 + 1390e1d1): Codex and Hermes have
+ * real native hook surfaces, but both live in GLOBAL (home-dir) config —
+ * `$CODEX_HOME/config.toml` and `~/.hermes/config.yaml` — which project
+ * `forge setup` intentionally never writes.
+ *
+ * Consent model:
+ *   - the explicit `--global` flag IS the consent — without it the command
+ *     refuses with guidance and writes nothing;
+ *   - the command prints exactly which files are written and the exact Forge
+ *     hook block merged into each, BEFORE reporting results;
+ *   - `--dry-run` shows the same plan without touching disk;
+ *   - existing user config is preserved (read → merge → write, idempotent via
+ *     the forge-native-hook.js marker); unmergeable config is backed up and
+ *     skipped, never overwritten.
+ *
+ * This command is deliberately NOT wired into project `forge setup`.
+ */
+
+const {
+  GLOBAL_HOOK_HARNESSES,
+  renderGlobalHookBlock,
+  installGlobalHooks,
+} = require('../hook-global-installer');
+const { sessionStartCapability, userPromptSubmitCapability } = require('../hook-renderer');
+const { collectDigestData, buildMemoryDigest } = require('../memory-digest');
+const { collectInbox, buildInboxNudge } = require('../inbox');
+
+function usage() {
+  return 'Usage: forge hooks install --global [--harness codex|hermes|all] [--dry-run]\n'
+    + '       forge hooks session-start --harness <claude> (machine-facing; emits SessionStart context)\n'
+    + '       forge hooks inbox-pickup --harness <claude> (machine-facing; emits UserPromptSubmit context)';
+}
+
+/** Parse `--harness <h>` (defaults to claude) from a session-start arg slice. */
+function parseHarness(rest) {
+  for (let i = 0; i < rest.length; i += 1) {
+    if (rest[i] === '--harness') return rest[i + 1] || 'claude';
+    if (rest[i].startsWith('--harness=')) return rest[i].slice('--harness='.length);
+  }
+  return 'claude';
+}
+
+/** Wrap a digest into a harness-native SessionStart payload, or '' when unsupported. */
+function formatSessionStart(harness, text) {
+  if (harness === 'claude') {
+    return JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: text },
+    });
+  }
+  // No other harness has a verified session-start context surface — emit nothing.
+  return '';
+}
+
+/**
+ * `forge hooks session-start --harness <h>` — the CONTEXT hook Forge PUSHES to an agent
+ * at session start. Machine-facing plumbing: emits harness-native SessionStart JSON on
+ * stdout (Claude: { hookSpecificOutput.additionalContext }). FAIL-OPEN by construction —
+ * any failure, an unsupported harness, or an empty digest yields '' (the harness then
+ * injects nothing). NEVER throws and NEVER emits malformed JSON.
+ *
+ * @param {string[]} rest - args after the `session-start` action.
+ * @param {string} projectRoot
+ * @param {object} [opts] - injectable digest fetchers ({ fetchNotes, fetchIssues }).
+ * @returns {Promise<{ success: boolean, output: string }>}
+ */
+async function handleSessionStart(rest, projectRoot, opts = {}) {
+  try {
+    const harness = parseHarness(rest);
+    if (!sessionStartCapability(harness).rendered) return { success: true, output: '' };
+    const data = await collectDigestData(projectRoot, opts);
+    const digest = buildMemoryDigest(data, opts);
+    if (digest.empty) return { success: true, output: '' };
+    return { success: true, output: formatSessionStart(harness, digest.text) };
+  } catch {
+    // Fail-open: a context hook must never break a session.
+    return { success: true, output: '' };
+  }
+}
+
+/** Wrap a digest into a harness-native UserPromptSubmit payload, or '' when unsupported. */
+function formatUserPromptSubmit(harness, text) {
+  if (harness === 'claude') {
+    return JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text },
+    });
+  }
+  // No other harness has a verified UserPromptSubmit context surface — emit nothing.
+  return '';
+}
+
+/**
+ * `forge hooks inbox-pickup --harness <h>` — the COMPLIANT comment-back CONTEXT hook. On each
+ * prompt it emits harness-native UserPromptSubmit JSON carrying a COMPACT count+pointer nudge
+ * (Claude: { hookSpecificOutput.additionalContext }). It deliberately does NOT re-emit the full
+ * fenced bodies: Claude APPENDS UserPromptSubmit additionalContext to history on every prompt
+ * (it does not replace prior injections — a documented context-bloat limitation), so a compact
+ * nudge keeps per-prompt accumulation negligible while still flagging "you have pending items,
+ * run `forge inbox`". The full fenced digest surfaces once at SessionStart and on demand via
+ * `forge inbox`. It reads the user's OWN kernel data via a supported hook — it NEVER injects
+ * into a running session's stdin and NEVER drives the agent programmatically (Anthropic Usage
+ * Policy, kernel issue 6d10c1a1). FAIL-OPEN: any failure, an unsupported harness, or nothing
+ * pending yields '' (the harness injects nothing). NEVER throws, NEVER emits malformed JSON.
+ *
+ * @param {string[]} rest - args after the `inbox-pickup` action.
+ * @param {string} projectRoot
+ * @param {object} [opts] - injectable inbox fetchers ({ fetchClaims, fetchComments, ... }).
+ * @returns {Promise<{ success: boolean, output: string }>}
+ */
+async function handleInboxPickup(rest, projectRoot, opts = {}) {
+  try {
+    const harness = parseHarness(rest);
+    if (!userPromptSubmitCapability(harness).rendered) return { success: true, output: '' };
+    const pending = await collectInbox(projectRoot, opts);
+    const nudge = buildInboxNudge(pending);
+    if (nudge.empty) return { success: true, output: '' };
+    return { success: true, output: formatUserPromptSubmit(harness, nudge.text) };
+  } catch {
+    // Fail-open: a context hook must never break a prompt.
+    return { success: true, output: '' };
+  }
+}
+
+function parseInstallArgs(rest) {
+  const parsed = { global: false, dryRun: false, harness: 'all', unknown: [] };
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === '--global') parsed.global = true;
+    else if (arg === '--dry-run') parsed.dryRun = true;
+    else if (arg === '--harness') { parsed.harness = rest[i + 1]; i += 1; }
+    else if (arg.startsWith('--harness=')) parsed.harness = arg.slice('--harness='.length);
+    else parsed.unknown.push(arg);
+  }
+  return parsed;
+}
+
+function indent(text, prefix) {
+  return String(text).replace(/\s+$/, '').split('\n').map(l => prefix + l).join('\n');
+}
+
+const GLOBAL_CONSENT_ERROR = [
+  'forge hooks install writes GLOBAL (home-directory) harness config:',
+  '  - Codex : $CODEX_HOME/config.toml (default ~/.codex/config.toml)',
+  '  - Hermes: ~/.hermes/config.yaml',
+  'Global config affects EVERY project on this machine, so Forge never writes it',
+  'silently — re-run with the explicit --global flag to consent, and add --dry-run',
+  'first to preview exactly what would be written.',
+  usage(),
+].join('\n');
+
+const INSTALL_FOOTER = [
+  '',
+  'Note: the hook commands invoke `node .forge/hooks/forge-native-hook.js` relative',
+  'to the workspace root (Codex and Hermes run hooks from there), so enforcement',
+  'applies inside Forge-initialized projects; elsewhere the adapter is absent and',
+  'the hook fails open (no deny decision is emitted), leaving tool calls untouched.',
+];
+
+/** Validate parsed install args; returns an error string or null when valid. */
+function validateInstallArgs(parsed) {
+  if (parsed.unknown.length > 0) return `Unknown argument(s): ${parsed.unknown.join(' ')}\n${usage()}`;
+  if (!parsed.global) return GLOBAL_CONSENT_ERROR;
+  const harnesses = parsed.harness === 'all' ? GLOBAL_HOOK_HARNESSES : [parsed.harness];
+  if (!harnesses.every(h => GLOBAL_HOOK_HARNESSES.includes(h))) {
+    return `Unknown --harness '${parsed.harness}'. Allowed: codex, hermes, all.\n${usage()}`;
+  }
+  return null;
+}
+
+/** Format the output lines for a single install result. */
+function renderInstallResult(res, dryRun) {
+  const lines = ['', `${res.harness} -> ${res.file}`];
+  if (res.skipped) {
+    lines.push(`  SKIPPED (left untouched): ${res.reason}`);
+    if (res.backup) lines.push(`  Backed up existing file to: ${res.backup} (.bak)`);
+    else if (dryRun) lines.push('  (dry-run: existing file would be backed up to a .bak and skipped)');
+    return lines;
+  }
+  lines.push(indent(renderGlobalHookBlock(res.harness), '    '));
+  if (dryRun) {
+    lines.push(res.changed === false
+      ? '  [dry-run] already up to date — a real run would change nothing'
+      : '  [dry-run] would merge the block above into this file');
+  } else {
+    lines.push(res.changed === false
+      ? '  Already up to date (no changes written).'
+      : `  Merged Forge hooks into ${res.existed ? 'existing' : 'new'} config.`);
+  }
+  return lines;
+}
+
+/** The `install` action — consent-guarded GLOBAL hook install (Codex/Hermes). */
+function handleInstall(args, flags, opts) {
+  const parsed = parseInstallArgs(args.slice(1));
+  const dryRun = parsed.dryRun || Boolean(flags.dryRun);
+
+  const validationError = validateInstallArgs(parsed);
+  if (validationError) return { success: false, error: validationError };
+
+  const harnesses = parsed.harness === 'all' ? GLOBAL_HOOK_HARNESSES : [parsed.harness];
+  // env/homeDir are injectable through the command opts so tests never touch the
+  // real home directory; real dispatch passes neither and gets the defaults.
+  const results = installGlobalHooks({ harnesses, dryRun, env: opts.env || process.env, homeDir: opts.homeDir });
+
+  const out = [
+    dryRun ? 'forge hooks install --global (dry-run — nothing will be written)' : 'forge hooks install --global',
+    '',
+    'This merges the following Forge hook block into each GLOBAL config,',
+    'preserving all existing user config (idempotent re-runs):',
+    ...results.flatMap(res => renderInstallResult(res, dryRun)),
+    ...INSTALL_FOOTER,
+  ];
+  return { success: true, output: out.join('\n'), results };
+}
+
+async function handler(args, flags = {}, projectRoot, opts = {}) {
+  const action = args[0];
+  if (action === 'session-start') return handleSessionStart(args.slice(1), projectRoot, opts);
+  if (action === 'inbox-pickup') return handleInboxPickup(args.slice(1), projectRoot, opts);
+  if (action === 'install') return handleInstall(args, flags, opts);
+  return {
+    success: false,
+    error: `forge hooks supports: install, session-start, inbox-pickup.\n${usage()}`,
+  };
+}
+
+module.exports = {
+  name: 'hooks',
+  description: 'Opt-in install of Forge native hooks into GLOBAL harness config (Codex/Hermes)',
+  usage: usage(),
+  flags: {
+    '--global': 'Required consent flag — this command writes home-directory config',
+    '--harness': 'codex | hermes | all (default: all)',
+    '--dry-run': 'Preview the merge without writing anything',
+  },
+  handler,
+};