forgedock 1.0.22 → 1.1.2

package/bin/runner.mjs

@@ -46,9 +46,9 @@ import {
 import { join, dirname, basename, relative, isAbsolute } from "path";
 import { execSync, spawnSync } from "child_process";
 
-const DEFAULT_MODEL = "claude-sonnet-4-5";
+const DEFAULT_MODEL = "claude-sonnet-5";
 const DEFAULT_MAX_ITERATIONS = 50;
-const DEFAULT_MAX_TOKENS = 8192;
+const DEFAULT_MAX_TOKENS = 16384;
 // Default wall-clock limit for a single run_bash command. Chosen to be
 // generous enough for CI steps (git clones, test suites) while bounding
 // the worst-case hang to 5 minutes. Override via FORGEDOCK_BASH_TIMEOUT (ms).
@@ -338,6 +338,31 @@ function resolveConfinedPath(cwd, p) {
     );
   }
 
+  // Residual TOCTOU assumption: we return the lexical `resolved` path rather
+  // than `realResolved` so that callers (readFileSync / writeFileSync) work
+  // correctly with not-yet-existing paths (where realResolved === resolved
+  // anyway, since there is nothing to dereference).  The check above verified
+  // confinement on the realpath of the nearest *existing* ancestor, but a
+  // concurrent actor that mutates the filesystem between this check and the
+  // caller's open() call could in theory introduce a symlink that evades the
+  // guard — a classic time-of-check / time-of-use (TOCTOU) window.
+  //
+  // This is acceptable under the current threat model because:
+  //   1. Tool calls are executed in a strictly sequential, synchronous
+  //      `for...of` loop (see the runLive tool-use loop).  There is no async
+  //      gap and no concurrent tool execution within the runner itself.
+  //   2. A prompt-injected model therefore cannot create this race — it would
+  //      need to schedule two tool calls simultaneously, which the loop
+  //      prevents.
+  //   3. Only an independent, external OS process running concurrently could
+  //      exploit the window, which is outside the stated single-shot
+  //      prompt-injection threat model.
+  //
+  // If the runner is ever refactored to execute tool calls concurrently or
+  // asynchronously, this assumption MUST be revisited.  Mitigations to
+  // consider at that point include: operating on `realResolved` directly
+  // (eliminating the lexical/realpath split), or opening the file with an
+  // O_NOFOLLOW-equivalent flag so the kernel rejects a symlink at open time.
   return resolved;
 }
 
@@ -539,31 +564,73 @@ export function getToolHandlers(cwd) {
       // available. `shell: shell || true` preserves execSync's implicit
       // "always run via a shell" behavior for compound commands (&&, pipes,
       // heredocs) when resolveBashShell() returns undefined.
+      // maxBuffer defaults to 50 MB. FORGEDOCK_MAX_BUFFER_BYTES overrides it so
+      // tests can trigger ENOBUFS with a small value without generating 50 MB of
+      // output.  Non-positive or non-finite values fall back to the default.
+      const rawMaxBuffer = parseInt(process.env.FORGEDOCK_MAX_BUFFER_BYTES, 10);
+      const maxBuffer =
+        Number.isFinite(rawMaxBuffer) && rawMaxBuffer > 0
+          ? rawMaxBuffer
+          : 50 * 1024 * 1024;
       const result = spawnSync(command, {
         cwd,
         encoding: "utf-8",
-        maxBuffer: 50 * 1024 * 1024,
+        maxBuffer,
         timeout: timeoutMs,
         env: childEnv,
         shell: shell || true,
       });
       const stdout = result.stdout ? String(result.stdout) : "";
       const stderr = result.stderr ? String(result.stderr) : "";
-      // Detect timeout: result.error.code === "ETIMEDOUT" and/or
-      // result.signal === "SIGTERM" are the primary indicators (set by
-      // Node.js when the timeout fires and the process is killed), but on
-      // Windows signal reporting may not be reliable. Fall back to elapsed
-      // wall time — if we spent at least as long as the timeout, the timer
-      // must have fired, since a voluntarily-exiting process would have
-      // returned before then. Gate all of this on `result.status === null`
-      // so a legitimately-completed process near the timeout boundary is
-      // never misreported as timed out.
+      // Check ENOBUFS BEFORE the timedOut fallback. When a command both exceeds
+      // maxBuffer AND runs past timeoutMs, both result.error.code === "ENOBUFS"
+      // and elapsedMs >= timeoutMs are simultaneously true. The elapsedMs
+      // fallback (check 2 below) is a heuristic catch-all that must not
+      // override a specific, authoritative error code. ENOBUFS is always the
+      // correct diagnosis when present — surface it first. (issue #1364)
+      if (result.error?.code === "ENOBUFS") {
+        // The process ran but produced more output than maxBuffer allows.
+        // spawnSync populates result.stdout/stderr up to the limit before
+        // setting result.error — surface what was captured so the agent has
+        // actionable context rather than a misleading "failed to start" error.
+        const partial = (stdout + stderr).trim();
+        const bufDisplay =
+          maxBuffer < 1024
+            ? `${maxBuffer} bytes`
+            : maxBuffer < 1024 * 1024
+              ? `${Math.round(maxBuffer / 1024)}KB`
+              : `${Math.round(maxBuffer / (1024 * 1024))}MB`;
+        throw new Error(
+          `Command output exceeded ${bufDisplay} buffer limit (output truncated).` +
+            (partial ? `\nPartial output:\n${partial}` : ""),
+        );
+      }
+      // Detect timeout. Two reliable indicators:
+      //   1. result.error.code === "ETIMEDOUT" — Node sets this on the error
+      //      object specifically when spawnSync's own `timeout` option fires
+      //      and it kills the child. This is the authoritative Node-initiated
+      //      kill signal.
+      //   2. elapsedMs >= timeoutMs — elapsed-wall-time fallback for platforms
+      //      (primarily Windows) where the ETIMEDOUT error code is unreliable.
+      //      If we spent at least as long as the timeout, the timer must have
+      //      fired, since a voluntarily-exiting process would have returned
+      //      before then.
+      //
+      // NOTE: `result.signal === "SIGTERM"` is intentionally NOT included.
+      // spawnSync sets result.signal for ANY signal that terminated the child —
+      // including SIGTERM from external sources (supervisors, orchestrators,
+      // `timeout(1)` wrappers, or the child self-signaling) that are entirely
+      // unrelated to this runner's timeout. Including it caused any externally-
+      // sent SIGTERM to be misreported as a ForgeDock timeout (issue #1240).
+      //
+      // Gate all of this on `result.status === null` so a legitimately-
+      // completed process near the timeout boundary is never misreported.
+      // ENOBUFS is excluded above — it is checked first so a command that both
+      // overflows the buffer AND exceeds the timeout gets the correct message.
       const elapsedMs = Date.now() - startMs;
       const timedOut =
         result.status === null &&
-        (result.error?.code === "ETIMEDOUT" ||
-          result.signal === "SIGTERM" ||
-          elapsedMs >= timeoutMs);
+        (result.error?.code === "ETIMEDOUT" || elapsedMs >= timeoutMs);
       if (timedOut) {
         const timeoutSecs = Math.round(timeoutMs / 1000);
         const partial = (stdout + stderr).trim();
@@ -622,20 +689,36 @@ export function renderDryRun(ctx) {
 
 /**
  * Render the pipeline summary card emitted on completion.
- * @param {{command: string, args: string[], iterations: number, stopReason: string}} ctx
+ * @param {{command: string, args: string[], iterations: number, stopReason: string, usage?: object|null}} ctx
  * @returns {string}
  */
 export function renderSummaryCard(ctx) {
-  const { command, args, iterations, stopReason } = ctx;
+  const { command, args, iterations, stopReason, usage = null } = ctx;
   const argStr = Array.isArray(args) ? args.join(" ") : String(args ?? "");
-  return [
+  const lines = [
     ``,
     `┌─ ForgeDock pipeline summary ────────────────────────────`,
     `│ command:    /${command} ${argStr}`.trimEnd(),
     `│ iterations: ${iterations}`,
     `│ stop:       ${stopReason}`,
+  ];
+  if (usage) {
+    lines.push(
+      `│ tokens:     ${usage.input_tokens} in / ${usage.output_tokens} out`,
+      `│ cache:      ${usage.cache_read_input_tokens} read / ${usage.cache_creation_input_tokens} write`,
+    );
+  } else {
+    lines.push(`│ tokens:     N/A`);
+  }
+  lines.push(
     `└─────────────────────────────────────────────────────────`,
-  ].join("\n");
+  );
+  if (usage) {
+    lines.push(
+      `FORGE:USAGE_JSON:${JSON.stringify(usage)}`,
+    );
+  }
+  return lines.join("\n");
 }
 
 // ---------------------------------------------------------------------------
@@ -701,9 +784,31 @@ export async function runCommand(opts = {}) {
   }
 
   const client = new Anthropic({ apiKey });
+  // NOTE on /proc/$PPID/environ (Linux): deleting from process.env calls
+  // unsetenv() at the C level, which does NOT update the kernel's
+  // /proc/<pid>/environ snapshot (that is fixed at execve() time). A
+  // run_bash payload can still read /proc/$PPID/environ and recover the
+  // key if it was set in the shell environment before the node process
+  // started. The only effective JavaScript-layer mitigation is the
+  // child-env scrub in run_bash: `childEnv = {...process.env}; delete
+  // childEnv.ANTHROPIC_API_KEY` — this prevents the child from inheriting
+  // the key in its own process.env, which is sufficient for
+  // `process.env.ANTHROPIC_API_KEY` access. The /proc/$PPID/environ vector
+  // is a known Linux limitation at the OS level; closing it would require
+  // a native module (e.g. prctl PR_SET_DUMPABLE) or process isolation.
+  // See: issue #1370 for tracking this known limitation.
   const handlers = getToolHandlers(cwd);
   const messages = [{ role: "user", content: userMessage }];
 
+  // Accumulate token usage across all messages.create() calls in this run.
+  // Field names match the Anthropic SDK's response.usage object exactly.
+  const usage = {
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_creation_input_tokens: 0,
+    cache_read_input_tokens: 0,
+  };
+
   let iterations = 0;
   while (iterations < maxIterations) {
     iterations++;
@@ -716,6 +821,14 @@ export async function runCommand(opts = {}) {
       messages,
     });
 
+    // Accumulate usage — guard each field for null/undefined (SDK omits
+    // cache fields when prompt caching is not active).
+    const ru = response.usage ?? {};
+    usage.input_tokens += ru.input_tokens ?? 0;
+    usage.output_tokens += ru.output_tokens ?? 0;
+    usage.cache_creation_input_tokens += ru.cache_creation_input_tokens ?? 0;
+    usage.cache_read_input_tokens += ru.cache_read_input_tokens ?? 0;
+
     messages.push({ role: "assistant", content: response.content });
 
     for (const block of response.content) {
@@ -735,6 +848,7 @@ export async function runCommand(opts = {}) {
           args,
           iterations,
           stopReason: response.stop_reason,
+          usage,
         }),
       );
       return {
@@ -742,6 +856,7 @@ export async function runCommand(opts = {}) {
         command: spec.name,
         iterations,
         stopReason: response.stop_reason,
+        usage,
       };
     }
 
@@ -774,7 +889,8 @@ export async function runCommand(opts = {}) {
       args,
       iterations,
       stopReason: "max_iterations",
+      usage,
     }),
   );
-  return { status: "max-iterations", command: spec.name, iterations };
+  return { status: "max-iterations", command: spec.name, iterations, usage };
 }

package/bin/settings-hook.mjs

@@ -0,0 +1,346 @@
+/**
+ * bin/settings-hook.mjs — Idempotent SessionStart hook registration in
+ * ~/.claude/settings.json.
+ *
+ * Contract (spec: "Hook wiring"):
+ *   - Read-modify-write; unrelated keys and hooks preserved verbatim
+ *   - Our entry identified by HOOK_MARKER in its command string
+ *   - Malformed JSON → skip and report, NEVER overwrite the file
+ *   - Absolute hook script path baked in at install time
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+/** Substring identifying ForgeDock's own SessionStart hook entry. */
+export const HOOK_MARKER = "session-start.mjs";
+
+/** Substring identifying ForgeDock's own SubagentStop hook entry (interactive engine adapter). */
+export const SUBAGENT_STOP_MARKER = "interactive-engine.mjs";
+
+/** Substring identifying ForgeDock's SubagentStop enforcement hook (annotation verification). */
+export const SUBAGENT_STOP_ENFORCE_MARKER = "subagent-stop-enforce.mjs";
+
+/** Substring identifying ForgeDock's own PreToolUse hook entry. */
+export const PRE_TOOL_USE_MARKER = "pre-tool-use.mjs";
+
+function isOurs(entry) {
+  return JSON.stringify(entry).includes(HOOK_MARKER);
+}
+
+function isOursSubagentStop(entry) {
+  return JSON.stringify(entry).includes(SUBAGENT_STOP_MARKER);
+}
+
+function isOursSubagentStopEnforce(entry) {
+  return JSON.stringify(entry).includes(SUBAGENT_STOP_ENFORCE_MARKER);
+}
+
+function isOursPreToolUse(entry) {
+  return JSON.stringify(entry).includes(PRE_TOOL_USE_MARKER);
+}
+
+function readSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return { settings: {}, fresh: true };
+  try {
+    const parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return { settings: parsed, fresh: false };
+  } catch {
+    return null; // malformed — caller must not write
+  }
+}
+
+function writeSettings(settingsPath, settings) {
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  const tmp = settingsPath + ".tmp";
+  writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+  renameSync(tmp, settingsPath);
+}
+
+/**
+ * Merge ForgeDock's SessionStart hook into settings.json.
+ * @param {string} settingsPath - Absolute path to ~/.claude/settings.json
+ * @param {string} hookScriptPath - Absolute path to bin/hooks/session-start.mjs
+ * @returns {{ status: 'installed'|'already'|'skipped-malformed' }}
+ */
+export function installSessionStartHook(settingsPath, hookScriptPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings } = read;
+
+  // Validate hooks shape: must be a plain object (not array, string, etc.)
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+    // Validate SessionStart if present: must be an array
+    if (settings.hooks.SessionStart !== undefined && !Array.isArray(settings.hooks.SessionStart)) {
+      return { status: "skipped-malformed" };
+    }
+  } else {
+    // hooks missing or null → initialize to fresh object
+    settings.hooks = {};
+  }
+
+  const list = Array.isArray(settings.hooks.SessionStart) ? settings.hooks.SessionStart : [];
+  if (list.some(isOurs)) return { status: "already" };
+
+  list.push({
+    hooks: [
+      {
+        type: "command",
+        command: `node "${hookScriptPath}"`,
+      },
+    ],
+  });
+  settings.hooks.SessionStart = list;
+  writeSettings(settingsPath, settings);
+  return { status: "installed" };
+}
+
+/**
+ * Remove ForgeDock's SessionStart hook entry; leaves everything else alone.
+ * @returns {{ status: 'removed'|'absent'|'skipped-malformed' }}
+ */
+export function removeSessionStartHook(settingsPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings, fresh } = read;
+  if (fresh) return { status: "absent" };
+
+  // Validate hooks shape: must be a plain object (not array, string, etc.)
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+  }
+
+  // Validate SessionStart shape if present: must be an array
+  if (settings.hooks && settings.hooks.SessionStart !== undefined && !Array.isArray(settings.hooks.SessionStart)) {
+    return { status: "skipped-malformed" };
+  }
+
+  const list = settings.hooks && Array.isArray(settings.hooks.SessionStart)
+    ? settings.hooks.SessionStart
+    : [];
+  const kept = list.filter((e) => !isOurs(e));
+  if (kept.length === list.length) return { status: "absent" };
+
+  settings.hooks.SessionStart = kept;
+  writeSettings(settingsPath, settings);
+  return { status: "removed" };
+}
+
+// ---------------------------------------------------------------------------
+// SubagentStop hook — interactive engine adapter (#1323)
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge ForgeDock's SubagentStop hook into settings.json.
+ * @param {string} settingsPath       - Absolute path to ~/.claude/settings.json
+ * @param {string} hookScriptPath     - Absolute path to bin/hooks/interactive-engine.mjs
+ * @returns {{ status: 'installed'|'already'|'skipped-malformed' }}
+ */
+export function installSubagentStopHook(settingsPath, hookScriptPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings } = read;
+
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+    if (settings.hooks.SubagentStop !== undefined && !Array.isArray(settings.hooks.SubagentStop)) {
+      return { status: "skipped-malformed" };
+    }
+  } else {
+    settings.hooks = {};
+  }
+
+  const list = Array.isArray(settings.hooks.SubagentStop) ? settings.hooks.SubagentStop : [];
+  if (list.some(isOursSubagentStop)) return { status: "already" };
+
+  list.push({
+    hooks: [{ type: "command", command: `node "${hookScriptPath}"` }],
+  });
+  settings.hooks.SubagentStop = list;
+  writeSettings(settingsPath, settings);
+  return { status: "installed" };
+}
+
+/**
+ * Remove ForgeDock's SubagentStop hook entry; leaves everything else alone.
+ * @returns {{ status: 'removed'|'absent'|'skipped-malformed' }}
+ */
+export function removeSubagentStopHook(settingsPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings, fresh } = read;
+  if (fresh) return { status: "absent" };
+
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+  }
+  if (settings.hooks && settings.hooks.SubagentStop !== undefined && !Array.isArray(settings.hooks.SubagentStop)) {
+    return { status: "skipped-malformed" };
+  }
+
+  const list = settings.hooks && Array.isArray(settings.hooks.SubagentStop)
+    ? settings.hooks.SubagentStop : [];
+  const kept = list.filter((e) => !isOursSubagentStop(e));
+  if (kept.length === list.length) return { status: "absent" };
+
+  settings.hooks.SubagentStop = kept;
+  writeSettings(settingsPath, settings);
+  return { status: "removed" };
+}
+
+// ---------------------------------------------------------------------------
+// PreToolUse hook — enforcement (#1250, #1323)
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge ForgeDock's PreToolUse hook into settings.json.
+ *
+ * The installed entry carries `matcher: "Bash"` so Claude Code's harness
+ * only invokes this hook for Bash tool calls — without it, Node spawns for
+ * every tool call (Read/Edit/Grep/Glob/...) just to exit 0 immediately
+ * (issue #1591).
+ *
+ * @param {string} settingsPath       - Absolute path to ~/.claude/settings.json
+ * @param {string} hookScriptPath     - Absolute path to bin/hooks/pre-tool-use.mjs
+ * @returns {{ status: 'installed'|'already'|'skipped-malformed' }}
+ */
+export function installPreToolUseHook(settingsPath, hookScriptPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings } = read;
+
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+    if (settings.hooks.PreToolUse !== undefined && !Array.isArray(settings.hooks.PreToolUse)) {
+      return { status: "skipped-malformed" };
+    }
+  } else {
+    settings.hooks = {};
+  }
+
+  const list = Array.isArray(settings.hooks.PreToolUse) ? settings.hooks.PreToolUse : [];
+  if (list.some(isOursPreToolUse)) return { status: "already" };
+
+  list.push({
+    matcher: "Bash",
+    hooks: [{ type: "command", command: `node "${hookScriptPath}"` }],
+  });
+  settings.hooks.PreToolUse = list;
+  writeSettings(settingsPath, settings);
+  return { status: "installed" };
+}
+
+/**
+ * Remove ForgeDock's PreToolUse hook entry; leaves everything else alone.
+ * @returns {{ status: 'removed'|'absent'|'skipped-malformed' }}
+ */
+export function removePreToolUseHook(settingsPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings, fresh } = read;
+  if (fresh) return { status: "absent" };
+
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+  }
+  if (settings.hooks && settings.hooks.PreToolUse !== undefined && !Array.isArray(settings.hooks.PreToolUse)) {
+    return { status: "skipped-malformed" };
+  }
+
+  const list = settings.hooks && Array.isArray(settings.hooks.PreToolUse)
+    ? settings.hooks.PreToolUse : [];
+  const kept = list.filter((e) => !isOursPreToolUse(e));
+  if (kept.length === list.length) return { status: "absent" };
+
+  settings.hooks.PreToolUse = kept;
+  writeSettings(settingsPath, settings);
+  return { status: "removed" };
+}
+
+// ---------------------------------------------------------------------------
+// SubagentStop enforcement hook — annotation verification (#1250)
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge ForgeDock's SubagentStop enforcement hook into settings.json.
+ *
+ * This hook (subagent-stop-enforce.mjs) is separate from the interactive
+ * engine adapter (interactive-engine.mjs): it verifies that each pipeline
+ * phase posted its FORGE: annotation before completion, and blocks (exit 2)
+ * if the annotation is missing.
+ *
+ * Version-gated: requires Claude Code v2.1.163+ (additionalContext injection).
+ *
+ * @param {string} settingsPath   - Absolute path to ~/.claude/settings.json
+ * @param {string} hookScriptPath - Absolute path to bin/hooks/subagent-stop-enforce.mjs
+ * @returns {{ status: 'installed'|'already'|'skipped-malformed' }}
+ */
+export function installSubagentStopEnforceHook(settingsPath, hookScriptPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings } = read;
+
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+    if (settings.hooks.SubagentStop !== undefined && !Array.isArray(settings.hooks.SubagentStop)) {
+      return { status: "skipped-malformed" };
+    }
+  } else {
+    settings.hooks = {};
+  }
+
+  const list = Array.isArray(settings.hooks.SubagentStop) ? settings.hooks.SubagentStop : [];
+  if (list.some(isOursSubagentStopEnforce)) return { status: "already" };
+
+  list.push({
+    hooks: [{ type: "command", command: `node "${hookScriptPath}"` }],
+  });
+  settings.hooks.SubagentStop = list;
+  writeSettings(settingsPath, settings);
+  return { status: "installed" };
+}
+
+/**
+ * Remove ForgeDock's SubagentStop enforcement hook entry; leaves everything else alone.
+ * @returns {{ status: 'removed'|'absent'|'skipped-malformed' }}
+ */
+export function removeSubagentStopEnforceHook(settingsPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings, fresh } = read;
+  if (fresh) return { status: "absent" };
+
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+  }
+  if (settings.hooks && settings.hooks.SubagentStop !== undefined && !Array.isArray(settings.hooks.SubagentStop)) {
+    return { status: "skipped-malformed" };
+  }
+
+  const list = settings.hooks && Array.isArray(settings.hooks.SubagentStop)
+    ? settings.hooks.SubagentStop : [];
+  const kept = list.filter((e) => !isOursSubagentStopEnforce(e));
+  if (kept.length === list.length) return { status: "absent" };
+
+  settings.hooks.SubagentStop = kept;
+  writeSettings(settingsPath, settings);
+  return { status: "removed" };
+}

package/bin/tui.mjs

@@ -837,7 +837,7 @@ const REVIEW_FIELDS = [
  */
 export async function annotatedReviewScreen(
   draft,
-  { hasExistingConfig = false, existingContent = "", showSources = false } = {},
+  { hasExistingConfig = false, existingContent = "", showSources = false, extraFields = {} } = {},
 ) {
   // Helper — pull a field from the draft by path, or return a low-confidence placeholder.
   function getField(draftPath) {
@@ -862,7 +862,10 @@ export async function annotatedReviewScreen(
   const whys = {};
 
   for (const fd of REVIEW_FIELDS) {
-    const field = getField(fd.draftPath);
+    const field =
+      fd.draftPath === null && extraFields[fd.key]
+        ? extraFields[fd.key]
+        : getField(fd.draftPath);
     values[fd.key] = field.value;
     confidences[fd.key] = field.confidence;
     sources[fd.key] = field.source;
@@ -987,7 +990,7 @@ export async function annotatedReviewScreen(
     }
 
     process.stdout.write(
-      `  ${dim("Press")} ${bold("Enter")} ${dim("to accept all values, or enter a field number to edit it.")}\n\n`,
+      `  ${dim("Press")} ${bold("Enter")} ${dim("to forge, or a number to edit a field")}\n\n`,
     );
   }
 

package/commands/adopt.md

@@ -1,6 +1,7 @@
 ---
 description: Bootstrap an existing repo for ForgeDock — triage open issues, apply labels, suggest a starter milestone, and identify first /work-on candidates
 argument-hint: [--dry-run | --limit <N> | --milestone | --no-milestone]
+install: extras
 ---
 
 # /adopt — Repo Bootstrap & Backlog Triage
@@ -11,9 +12,11 @@ You onboard an existing repo into the ForgeDock pipeline. Unlike `/forgedock-ini
 
 Run `/adopt` once after `npx forgedock init` + `/forgedock-init` to make a legacy backlog pipeline-ready without touching the issues themselves.
 
-**Agent model policy**: Default `model: "sonnet"`. Fallback: `model: "opus"` if Sonnet is rate-limited.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
+<!-- FORGE:SPEC_LOADED — adopt.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## Argument Parsing

package/commands/analytics.md

@@ -1,5 +1,6 @@
 ---
 description: Pull production analytics from GSC, Bing Webmaster, Clarity, Umami, Cloudflare, Stripe, and GA4 — generate insights and create actionable GitHub issues. Trigger when user says things like "check analytics", "look at prod analytics", "make issues from analytics", "what's happening on the site", "audit the site", "check revenue", etc.
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -12,7 +13,9 @@ You are the analytics orchestrator. Pull data from ALL available analytics platf
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`. User can override with `--model <name>`. Pass the resolved model in every `Agent` tool call. Each agent prompt includes specific queries, exact API endpoints, and the credentials file path so the model can execute without guessing.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. User can override with `--model <name>`. Pass model explicitly in every `Agent` tool call. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
+
+<!-- FORGE:SPEC_LOADED — analytics.md loaded and active. Agent is bound by this spec. -->
 
 ---