forgedock 1.1.1 → 1.1.2

package/bin/settings-hook.mjs

@@ -12,13 +12,34 @@
 import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "fs";
 import { dirname } from "path";
 
-/** Substring identifying ForgeDock's own hook entry. */
+/** 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 {
@@ -110,3 +131,216 @@ export function removeSessionStartHook(settingsPath) {
   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/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. -->
 
 ---
 

package/commands/audit-agents.md

@@ -1,6 +1,7 @@
 ---
 description: Audit agent outputs from an orchestration run — timeline analysis, stall detection, active vs idle time breakdown
 argument-hint: [session-id | latest | <agent-id>]
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -48,20 +49,49 @@ fi
 
 ### Step 1A: Find the session
 
-Agent outputs live in `/tmp/claude-1000/` as symlinks to JSONL files in `~/.claude/projects/*/subagents/`.
+Agent outputs live in `~/.claude/projects/{munged-project-path}/subagents/agent-{agentId}.jsonl`.
+The project path munging rule: both `/` and `.` are replaced with `-`
+(e.g. `/home/user/projects/myproject` → `-home-user-projects-myproject`).
 
-```bash
-# List recent sessions
-ls -lt /tmp/claude-1000/ 2>/dev/null | head -10
-
-# For each session dir, list agent output files
-for DIR in /tmp/claude-1000/*/; do
-  TASKS_DIR="${DIR}*/tasks/"
-  AGENT_COUNT=$(find $TASKS_DIR -name "a*.output" -type l 2>/dev/null | wc -l)
-  if [ "$AGENT_COUNT" -gt 0 ]; then
-    echo "$(stat -c %Y "$DIR" 2>/dev/null) $DIR ($AGENT_COUNT agents)"
-  fi
-done | sort -rn | head -5
+```python
+import os, sys
+from pathlib import Path
+
+def _session_project_dir(project_path):
+    """Convert a Claude Code project path to its ~/.claude/projects/ directory name.
+    Rule: both '/' and '.' are replaced with '-'.
+    Matches pipeline-health.md _session_project_dir() exactly.
+    """
+    import re
+    return re.sub(r'[/.]', '-', project_path)
+
+CLAUDE_PROJECTS_DIR = Path.home() / ".claude" / "projects"
+
+# Discover all subagent JSONL files under ~/.claude/projects/
+# Each subagent file: ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl
+subagent_files = []
+if CLAUDE_PROJECTS_DIR.exists():
+    for jsonl_path in sorted(CLAUDE_PROJECTS_DIR.rglob("subagents/agent-*.jsonl"),
+                             key=lambda p: p.stat().st_mtime, reverse=True):
+        # Only process files with actual content (> 10 lines / non-empty)
+        try:
+            size = jsonl_path.stat().st_size
+            if size < 200:  # 200 bytes ≈ fewer than 10 minimal JSONL lines
+                continue
+            # Count lines portably without wc -l
+            with open(jsonl_path, 'rb') as fh:
+                line_count = sum(1 for _ in fh)
+            if line_count > 10:
+                subagent_files.append(jsonl_path)
+        except OSError:
+            continue
+
+if not subagent_files:
+    print("SKIPPED — transcripts unreadable on this platform")
+    print("  ~/.claude/projects/ not found or contains no subagent JSONL files.")
+    sys.exit(0)
+
+print(f"Found {len(subagent_files)} subagent JSONL file(s) under {CLAUDE_PROJECTS_DIR}")
 ```
 
 **Input resolution:**
@@ -72,20 +102,47 @@ done | sort -rn | head -5
 
 ### Step 1B: Collect agent JSONL files
 
-```bash
-SESSION_DIR="/tmp/claude-1000/{PROJECT_PATH}/{SESSION_ID}"
-TASKS_DIR="${SESSION_DIR}/tasks"
-
-# Agent files are symlinks starting with 'a' pointing to .jsonl files
-for LINK in ${TASKS_DIR}/a*.output; do
-  AGENT_ID=$(basename "$LINK" .output)
-  TARGET=$(readlink -f "$LINK")
-  LINES=$(wc -l < "$TARGET" 2>/dev/null || echo 0)
-  echo "$AGENT_ID $LINES $TARGET"
-done
+```python
+import os
+from pathlib import Path
+
+# Filter subagent_files by $ARGUMENTS (session UUID, agent ID, project fragment, or "latest")
+ARGUMENT = "$ARGUMENTS".strip()
+
+if not ARGUMENT or ARGUMENT.lower() == "latest":
+    # Use the most recent session — take the most recently modified subagent directory
+    # Group by parent session dir (grandparent of the subagent file)
+    by_session = {}
+    for p in subagent_files:
+        session_dir = p.parent.parent  # .../projects/{project}/{sessionId}/
+        mtime = session_dir.stat().st_mtime if session_dir.exists() else 0
+        if session_dir not in by_session or mtime > by_session[session_dir][0]:
+            by_session[session_dir] = (mtime, [])
+        by_session[session_dir][1].append(p)
+    if by_session:
+        latest_session_dir = max(by_session, key=lambda d: by_session[d][0])
+        agent_files = by_session[latest_session_dir][1]
+    else:
+        agent_files = []
+else:
+    # Filter by session UUID, agent ID, or project path fragment
+    agent_files = [
+        p for p in subagent_files
+        if ARGUMENT in str(p)
+    ]
+
+if not agent_files:
+    print(f"SKIPPED — no matching agent JSONL files found for argument: {ARGUMENT!r}")
+    import sys; sys.exit(0)
+
+print(f"Processing {len(agent_files)} agent file(s)")
+for p in agent_files:
+    agent_id = p.stem.replace("agent-", "", 1)
+    print(f"  {agent_id}  {p}")
 ```
 
 Only process files with `> 10` lines (smaller files are helper/polling agents, not work-on agents).
+Line count is computed in Python from the actual JSONL bytes — not from a symlink stub.
 
 ---
 
@@ -189,17 +246,43 @@ def parse_agent(filepath, agent_id):
     max_replays = max(ts_counts.values()) if ts_counts else 1
     resume_cycles = max_replays - 1  # first occurrence is original, rest are replays
 
-    # Build phase timeline from unique skill invocations
+    # Build phase timeline from unique skill invocations.
+    # Stall detection: a gap is a TRUE STALL only when it is >120s AND contains zero
+    # tool_use events (i.e. ends in end_turn with no tool calls in the window).
+    # Gaps that contain any tool_use block (Bash, Edit, Read, Grep, …) are ACTIVE work —
+    # the agent was building; only Skill() calls were sparse.
+    #
+    # To detect tool activity between consecutive Skill() calls we collect all
+    # tool_use timestamps from the raw lines and check whether any fall in the gap.
+    all_tool_use_ts = []
+    for raw_line in lines:
+        raw = json.loads(raw_line)
+        raw_msg = raw.get('message', {})
+        raw_content = raw_msg.get('content', [])
+        raw_ts_str = raw.get('timestamp', '')
+        if raw_ts_str and isinstance(raw_content, list):
+            for c in raw_content:
+                if c.get('type') == 'tool_use':
+                    try:
+                        all_tool_use_ts.append(
+                            datetime.fromisoformat(raw_ts_str.replace('Z', '+00:00'))
+                        )
+                    except ValueError:
+                        pass
+
     phases = []
     prev_ts = first_ts
     for si in skill_invocations:
         gap_sec = (si['ts'] - prev_ts).total_seconds()
+        # Any tool_use event inside the gap window means the agent was active
+        has_tool_use_in_gap = any(prev_ts < t <= si['ts'] for t in all_tool_use_ts)
+        is_stall = gap_sec > 120 and not has_tool_use_in_gap
         phases.append({
             'ts': si['ts'],
             'skill': si['skill'],
             'args': si['args'],
             'gap_from_prev_sec': gap_sec,
-            'is_stall': gap_sec > 120  # > 2 min = stall
+            'is_stall': is_stall,  # True only when >2 min AND zero tool calls in gap
         })
         prev_ts = si['ts']
 
@@ -433,6 +516,6 @@ This enables tracking whether orchestrator/prompt changes actually improved thro
 ## Notes
 
 - **File format**: Agent outputs are JSONL (one JSON object per line). Each line has `type` (user/assistant), `timestamp`, `message` (with `content` array and optional `stop_reason`).
-- **Symlinks**: Files in `/tmp/claude-1000/*/tasks/a*.output` are symlinks to `~/.claude/projects/*/subagents/agent-*.jsonl`.
+- **Subagent files**: Located at `~/.claude/projects/{munged-project-path}/{sessionId}/subagents/agent-{agentId}.jsonl`. The munging rule: both `/` and `.` in the project path are replaced with `-` (e.g. `/home/user/projects/myapp` → `-home-user-projects-myapp`). There are no platform-specific temp paths or symlinks involved.
 - **Size filtering**: Only analyze files > 10 lines. Small files are helper/polling agents spawned by the orchestrator for status checks.
 - **Resume detection**: When an agent is resumed, the full conversation is replayed. Duplicate `(timestamp, skill_name)` pairs indicate replay cycles. `max(duplicates) - 1 = resume_cycles`.

package/commands/audit.md

@@ -1,6 +1,7 @@
 ---
 description: Trace a production issue or pipeline failure end-to-end through GitHub artifacts, then file a detailed improvement issue to the Forge repo
 argument-hint: <description of what went wrong> [--issue N] [--pr N] [--repo prefix]
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -13,7 +14,7 @@ You are Forge's post-mortem auditor. When something reaches production that shou
 
 **This command ALWAYS files issues to `{FORGE_REPO}`.** The target project is read-only — you only read its GitHub artifacts as evidence.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**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).**
 
@@ -286,6 +287,24 @@ Create a detailed, actionable issue in the **Forge repository**.
 
 ### 4B: Create the issue
 
+**Before creating, run the deterministic dedup check:** <!-- Added: forge#1335 -->
+
+```bash
+AUDIT_TITLE="fix(pipeline): {one-line description of what the pipeline missed}"
+DEDUP_RESULT=$(scripts/issue-dedup.sh "$AUDIT_TITLE" -R {FORGE_REPO} 2>&1)
+DEDUP_EXIT=$?
+if [ "$DEDUP_EXIT" -eq 1 ]; then
+  echo "DEDUP: Audit finding near-duplicate — $DEDUP_RESULT"
+  echo "Skipping creation. Comment on the existing issue with new evidence instead."
+  # Do NOT call gh issue create for this audit finding
+elif [ "$DEDUP_EXIT" -eq 2 ]; then
+  echo "DEDUP: Usage error — $DEDUP_RESULT"
+  # Do NOT call gh issue create for this audit finding — fix the invocation and retry
+fi
+```
+
+Only call `gh issue create` when the dedup script exits 0:
+
 ```bash
 gh issue create -R {FORGE_REPO} \
   --title "fix(pipeline): {one-line description of what the pipeline missed}" \