ccgx-workflow 2.3.1 → 2.4.1

package/templates/hooks/ccg-loop-detector.cjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// CCG Loop Detector Hook — UserPromptSubmit
+//
+// Detects when the user is stuck describing the same problem turn after turn
+// (typical signs: model gave a wrong answer, user re-phrases the question,
+// model gives a similar wrong answer, repeat). Emits a `LOOP DETECTED` warning
+// into the model's additionalContext along with a break-loop protocol, so the
+// next reply is forced to step back rather than re-attempt the same approach.
+//
+// Why this hook lives in fork-land (not just porting upstream's workflow-state.js):
+//   - Upstream binds loop detection to .ccg/tasks/{id}/task.json — the V3
+//     intent-driven engine that fork does not adopt.
+//   - Fork's task state lives in .ccg/roadmap.md (milestone) + .ccg/state.md
+//     (wave). Those are coarse — they don't change per-turn.
+//   - The actual signal we can read every turn is the user's own prompt.
+//     Repeated near-identical prompts within a short window are a strong loop
+//     indicator regardless of what the orchestrator is doing internally.
+//
+// State file: <workdir>/.ccg/.turns.json   (kept tiny: last 5 turns only)
+//
+// Performance budget: <50 ms hot path. Hook fires every UserPromptSubmit; if
+// anything throws we exit 0 silently so the user message is never blocked.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const STATE_FILE = path.join('.ccg', '.turns.json');
+const MAX_TURNS = 5;             // sliding window
+const LOOP_THRESHOLD = 3;        // 3 similar in a row → loop
+// Bound the state-file read. .turns.json holds at most MAX_TURNS rows of
+// fp+ts (~280B each), so anything beyond 64KB is corrupt or malicious.
+// Matches the budget used by ccg-stop-gate.cjs for the same reason.
+const MAX_STATE_FILE_BYTES = 64 * 1024;
+// Threshold tuned for character-bigram Jaccard. Empirically:
+//   "fix login bug"  vs "fix login bug please" → ~0.67
+//   "fix login bug"  vs "fix login bug now"    → ~0.69
+//   "帮我修登录的错误" vs "帮我修一下登录的错误" → ~0.60
+//   unrelated English prompts                  → < 0.15
+//   unrelated CJK prompts                      → < 0.20
+// 0.55 catches re-phrasings of the same ask in both scripts while staying
+// well above the unrelated-pair floor.
+const SIMILARITY_THRESHOLD = 0.55;
+const WINDOW_MS = 10 * 60 * 1000;// ignore matches > 10 min apart
+const PROMPT_FINGERPRINT_LEN = 240;
+
+function readJsonSafe(p) {
+  try {
+    // Bounded read so a corrupt 100MB .turns.json doesn't wedge the prompt path.
+    const st = fs.statSync(p);
+    if (!st.isFile() || st.size > MAX_STATE_FILE_BYTES) return null;
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  }
+  catch {
+    return null;
+  }
+}
+
+function writeJsonSafe(p, data) {
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(data), 'utf-8');
+  }
+  catch {
+    // Hook must never fail loudly.
+  }
+}
+
+// Cheap fingerprint: lowercased, whitespace-collapsed, truncated.
+// Long enough to capture meaningful overlap; short enough to keep .turns.json tiny.
+function fingerprint(prompt) {
+  if (typeof prompt !== 'string') return '';
+  return prompt.toLowerCase().replace(/\s+/g, ' ').trim().slice(0, PROMPT_FINGERPRINT_LEN);
+}
+
+// Character-bigram set. Works across scripts:
+//   - English: "fix login bug" → {"fi","ix","x ", " l", ...}
+//   - CJK:     "帮我修登录"     → {"帮我","我修","修登","登录"}
+// Word-level tokenization is a non-starter for CJK (no whitespace separators).
+// Bigrams give us a script-agnostic signal at the cost of a slightly noisier
+// floor (~0.15 for unrelated English, ~0.20 for unrelated CJK) which we
+// absorbed when tuning SIMILARITY_THRESHOLD.
+function bigrams(s) {
+  const out = new Set();
+  if (!s || s.length < 2) return out;
+  for (let i = 0; i < s.length - 1; i++) {
+    out.add(s.slice(i, i + 2));
+  }
+  return out;
+}
+
+function jaccard(a, b) {
+  if (!a || !b) return 0;
+  const A = bigrams(a);
+  const B = bigrams(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let intersection = 0;
+  for (const t of A) if (B.has(t)) intersection++;
+  const union = A.size + B.size - intersection;
+  return intersection / union;
+}
+
+function detectLoop(turns) {
+  if (turns.length < LOOP_THRESHOLD) return null;
+  const recent = turns.slice(-LOOP_THRESHOLD);
+  const oldest = recent[0];
+  const newest = recent[recent.length - 1];
+  if (newest.ts - oldest.ts > WINDOW_MS) return null;
+
+  // Pairwise similarity must clear threshold for every consecutive pair.
+  // This is stricter than "average" — one outlier breaks the loop call,
+  // which is what we want (avoids false-positives on "good question, follow-up").
+  for (let i = 1; i < recent.length; i++) {
+    if (jaccard(recent[i - 1].fp, recent[i].fp) < SIMILARITY_THRESHOLD) {
+      return null;
+    }
+  }
+
+  return {
+    count: recent.length,
+    elapsedSec: Math.round((newest.ts - oldest.ts) / 1000),
+    fingerprint: oldest.fp.slice(0, 80),
+  };
+}
+
+// Compose the additionalContext payload. The 5-step break-loop protocol is
+// adapted from upstream's workflow-state.js but oriented at the user-prompt
+// signal instead of phase+nextAction state.
+function composeWarning(loop) {
+  return [
+    '<ccg-loop-warning>',
+    `⚠️ LOOP DETECTED — same/similar user prompt repeated ${loop.count} turns within ${loop.elapsedSec}s.`,
+    `Sample: "${loop.fingerprint}..."`,
+    '',
+    '🔄 BREAK-LOOP PROTOCOL (apply before answering this turn):',
+    '  1. STOP. Do not re-attempt the previous approach.',
+    '  2. Re-read the user message looking for what you missed (a constraint? a file path? a "no" you treated as "maybe"?).',
+    '  3. State, in one sentence, why your previous answer did not satisfy the user.',
+    '  4. Pick a different approach OR ask one specific clarifying question (not "what do you mean") if you cannot diagnose the miss.',
+    '  5. If you suspect an external blocker (missing creds, broken tool, unsupported feature), say so explicitly — do not loop on it.',
+    '</ccg-loop-warning>',
+  ].join('\n');
+}
+
+function readInput() {
+  // SessionStart / UserPromptSubmit pass JSON on stdin. We only need .prompt
+  // and .cwd. Failing to read is fine — we exit 0 silently.
+  let raw = '';
+  try {
+    raw = fs.readFileSync(0, 'utf-8');
+  }
+  catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw || '{}');
+  }
+  catch {
+    return null;
+  }
+}
+
+function main() {
+  const input = readInput();
+  if (!input) {
+    process.exit(0);
+    return;
+  }
+
+  const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+  if (!prompt) {
+    process.exit(0);
+    return;
+  }
+
+  // CCG state lives under the project root. Use the cwd Claude Code passed in;
+  // fall back to process.cwd() (which Claude Code sets for the hook anyway).
+  const cwd = typeof input.cwd === 'string' && input.cwd ? input.cwd : process.cwd();
+  const statePath = path.join(cwd, STATE_FILE);
+
+  const fp = fingerprint(prompt);
+  if (!fp) {
+    process.exit(0);
+    return;
+  }
+
+  const existing = readJsonSafe(statePath);
+  // Filter out malformed turn objects (e.g. corrupted via hand edit, partial
+  // write). Without this a missing/non-numeric ts becomes NaN inside detectLoop
+  // and produces silent false negatives instead of just dropping the bad row.
+  const turns = (Array.isArray(existing) ? existing : []).filter(
+    (t) => t && typeof t.fp === 'string' && typeof t.ts === 'number' && Number.isFinite(t.ts),
+  );
+  turns.push({ fp, ts: Date.now() });
+  if (turns.length > MAX_TURNS) {
+    turns.splice(0, turns.length - MAX_TURNS);
+  }
+  writeJsonSafe(statePath, turns);
+
+  const loop = detectLoop(turns);
+  if (!loop) {
+    process.exit(0);
+    return;
+  }
+
+  // Emit the warning. Same envelope shape as other CCG hooks.
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: composeWarning(loop),
+    },
+  }));
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+// Exported for unit tests (loaded via createRequire from .ts).
+module.exports = {
+  fingerprint,
+  jaccard,
+  detectLoop,
+  composeWarning,
+  // Constants exported so tests can document the contract.
+  LOOP_THRESHOLD,
+  WINDOW_MS,
+  SIMILARITY_THRESHOLD,
+  MAX_TURNS,
+};

package/templates/hooks/ccg-skill-router.cjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+// CCG Skill Router Hook — UserPromptSubmit
+//
+// When the user's message contains domain keywords (e.g. "SQLi", "Kubernetes",
+// "RAG"), inject a short additionalContext that names the relevant skill file
+// the model should Read before answering.
+//
+// Why this is a hook rather than relying on rules/ccg-skill-routing.md alone:
+//   - The rules file is a passive document. The model has to remember to
+//     consult it, and in practice it often answers from training data without
+//     reading the domain skill (false-positives in security/architecture/AI
+//     advice are the typical failure mode).
+//   - This hook runs deterministically on every prompt and surfaces the exact
+//     path inline, so the model doesn't have to find it. Token cost is ~50
+//     per match — much cheaper than the wrong answer it prevents.
+//
+// Design choices that diverge from upstream skill-router.js:
+//   - We DO NOT inject the file content. Upstream slices the first ~120 lines
+//     and ships them in context. That bloats every prompt that matches a
+//     keyword. We just point at the path and let the model Read on demand.
+//   - We DO NOT spawn external models from this hook. Upstream uses keyword
+//     phrases like "用 codex 审查" to autoexecute the codeagent-wrapper.
+//     Fork's plugin-spawn architecture would conflict with that path.
+//
+// Performance budget: <30 ms. Hook fires every UserPromptSubmit.
+
+'use strict';
+
+const fs = require('node:fs');
+
+// Routing table mirrors templates/rules/ccg-skill-routing.md. Keep them in
+// sync — the rules file is for human reference, this hook is what actually
+// fires. Keywords are matched case-insensitively as substrings.
+//
+// Match shape: { keywords: [...], skill: '<relative path under skills/ccg/>', label: '<human-readable>' }
+const ROUTES = [
+  // ── Security ──
+  { keywords: ['pentest', 'red team', '红队', '渗透', 'exploit', 'c2', 'lateral movement', 'privilege escalation', '提权', 'evasion', 'persistence', '免杀', '持久化'],
+    skill: 'domains/security/red-team.md', label: 'Red Team' },
+  { keywords: ['blue team', '蓝队', 'incident response', '应急', 'ioc', 'siem', 'edr', '取证', 'forensics', 'containment'],
+    skill: 'domains/security/blue-team.md', label: 'Blue Team' },
+  { keywords: ['sqli', 'sql injection', 'xss', 'ssrf', 'rce', 'owasp', 'web pentest', 'api security', 'injection'],
+    skill: 'domains/security/pentest.md', label: 'Web Pentest' },
+  { keywords: ['code audit', '代码审计', 'taint analysis', '污点分析', 'sink', 'dangerous function', '危险函数'],
+    skill: 'domains/security/code-audit.md', label: 'Code Audit' },
+  { keywords: ['binary', 'reversing', '逆向', 'pwn', 'fuzzing', 'stack overflow', 'heap overflow', '栈溢出', '堆溢出', 'rop'],
+    skill: 'domains/security/vuln-research.md', label: 'Vuln Research' },
+  { keywords: ['osint', 'threat intelligence', '威胁情报', 'threat modeling', '威胁建模', 'att&ck', 'threat hunting'],
+    skill: 'domains/security/threat-intel.md', label: 'Threat Intel' },
+
+  // ── Architecture ──
+  { keywords: ['api design', 'api 设计', 'rest', 'graphql', 'grpc', 'endpoint', 'versioning'],
+    skill: 'domains/architecture/api-design.md', label: 'API Design' },
+  { keywords: ['caching', '缓存', 'redis', 'memcached', 'cache invalidation', 'cdn'],
+    skill: 'domains/architecture/caching.md', label: 'Caching' },
+  { keywords: ['cloud native', '云原生', 'kubernetes', 'k8s', 'docker', 'microservice', '微服务', 'service mesh'],
+    skill: 'domains/architecture/cloud-native.md', label: 'Cloud Native' },
+  { keywords: ['message queue', '消息队列', 'kafka', 'rabbitmq', 'event driven', 'pub/sub'],
+    skill: 'domains/architecture/message-queue.md', label: 'Message Queue' },
+  { keywords: ['security architecture', '安全架构', 'zero trust', 'defense in depth', 'iam'],
+    skill: 'domains/architecture/security-arch.md', label: 'Security Arch' },
+
+  // ── AI / MLOps ──
+  { keywords: ['rag', 'retrieval augmented', '检索增强', 'vector database', 'embedding', 'chunking'],
+    skill: 'domains/ai/rag-system.md', label: 'RAG System' },
+  { keywords: ['ai agent', 'tool use', 'function calling', 'agent framework', 'orchestration'],
+    skill: 'domains/ai/agent-dev.md', label: 'Agent Dev' },
+  { keywords: ['llm security', 'prompt injection', 'jailbreak', 'guardrail'],
+    skill: 'domains/ai/llm-security.md', label: 'LLM Security' },
+  { keywords: ['prompt engineering', 'model evaluation', 'benchmark', 'fine-tuning'],
+    skill: 'domains/ai/prompt-and-eval.md', label: 'Prompt & Eval' },
+
+  // ── DevOps ──
+  { keywords: ['git workflow', 'branching strategy', 'trunk-based', 'gitflow'],
+    skill: 'domains/devops/git-workflow.md', label: 'Git Workflow' },
+  { keywords: ['testing strategy', 'unit test', 'integration test', 'e2e', 'test pyramid'],
+    skill: 'domains/devops/testing.md', label: 'Testing' },
+  { keywords: ['database migration', 'schema design', 'indexing', 'query optimization'],
+    skill: 'domains/devops/database.md', label: 'Database' },
+  { keywords: ['profiling', 'load test', 'latency', 'throughput', 'performance tuning'],
+    skill: 'domains/devops/performance.md', label: 'Performance' },
+  { keywords: ['observability', 'logging', 'tracing', 'metrics', 'prometheus', 'grafana'],
+    skill: 'domains/devops/observability.md', label: 'Observability' },
+  { keywords: ['devsecops', 'ci security', 'sast', 'dast', 'supply chain'],
+    skill: 'domains/devops/devsecops.md', label: 'DevSecOps' },
+  { keywords: ['cost optimization', 'cloud cost', 'finops', 'right-sizing'],
+    skill: 'domains/devops/cost-optimization.md', label: 'Cost Optimization' },
+
+  // ── Frontend Design (only style packs; basic UI is too noisy to match) ──
+  { keywords: ['claymorphism'], skill: 'domains/frontend-design/claymorphism/SKILL.md', label: 'Claymorphism' },
+  { keywords: ['glassmorphism'], skill: 'domains/frontend-design/glassmorphism/SKILL.md', label: 'Glassmorphism' },
+  { keywords: ['liquid glass'], skill: 'domains/frontend-design/liquid-glass/SKILL.md', label: 'Liquid Glass' },
+  { keywords: ['neubrutalism'], skill: 'domains/frontend-design/neubrutalism/SKILL.md', label: 'Neubrutalism' },
+];
+
+const MAX_INJECTIONS = 2; // cap on matched skills per prompt to keep context tight
+
+// Short keyword cutoff (ASCII). ASCII keywords shorter than this length MUST
+// use a word-boundary regex to avoid catastrophic false positives. Empirically:
+//   'rag'  → "drag/fragment/Bragg"           (3 chars)
+//   'rest' → "restart/rest assured/interest" (4 chars)
+//   'rce'  → "service/source"                (3 chars)
+//   'route' → "rerouted"                     (5 chars but unambiguous as a word)
+// Cutoff = 5 catches all the painful ones while letting actual nouns ('route',
+// 'redis', 'cache', etc.) take the cheap substring path.
+const SHORT_KW_CUTOFF = 5;
+
+// CJK keywords are a different problem space. There is no formal word
+// boundary in CJK writing — '红队' next to '员' produces '红队员' (a real
+// compound noun), but the user query '我想做一次红队演练' also has '红队'
+// next to a CJK char ('次' before, '演' after). A boundary regex anchored on
+// \P{L} would reject BOTH cases identically, killing legitimate matches.
+//
+// We accept the cost: CJK keywords always take the substring path. In
+// practice CJK queries are more topical and less likely to produce ASCII-style
+// homograph collisions, so substring false-positive rate on CJK stays low.
+function hasCjk(s) {
+  return /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u.test(s);
+}
+
+/**
+ * Returns true iff `kw` appears in `prompt` as a stand-alone token (ASCII)
+ * or as a substring (CJK).
+ *
+ * Regex objects are cached per keyword — the hook runs on every
+ * UserPromptSubmit and building these on the hot path would be wasteful.
+ */
+const KW_REGEX_CACHE = new Map();
+function matchKeyword(prompt, kw) {
+  if (!kw) return false;
+  const lowerPrompt = prompt.toLowerCase();
+  const lowerKw = kw.toLowerCase();
+  // CJK short keywords: substring path (boundary makes no sense — see above).
+  // Long keywords (>= cutoff): substring is safe enough.
+  if (hasCjk(lowerKw) || lowerKw.length >= SHORT_KW_CUTOFF) {
+    return lowerPrompt.includes(lowerKw);
+  }
+  // ASCII short keyword: word-boundary regex.
+  let re = KW_REGEX_CACHE.get(lowerKw);
+  if (!re) {
+    // Escape regex metachars in the keyword (handles 'c2', 'pub/sub', etc.).
+    const esc = lowerKw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // Boundary = position whose neighboring char is NOT a letter or digit
+    // (Unicode-aware). Start/end of string are also valid boundaries.
+    re = new RegExp(`(?:^|[^\\p{L}\\p{N}])${esc}(?:$|[^\\p{L}\\p{N}])`, 'iu');
+    KW_REGEX_CACHE.set(lowerKw, re);
+  }
+  return re.test(lowerPrompt);
+}
+
+function readInput() {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(0, 'utf-8');
+  }
+  catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw || '{}');
+  }
+  catch {
+    return null;
+  }
+}
+
+function findMatches(prompt) {
+  const text = prompt || '';
+  if (text.length < 5) return [];
+  const seen = new Set();
+  const matches = [];
+  for (const route of ROUTES) {
+    if (seen.has(route.skill)) continue;
+    if (route.keywords.some(kw => matchKeyword(text, kw))) {
+      matches.push(route);
+      seen.add(route.skill);
+      if (matches.length >= MAX_INJECTIONS) break;
+    }
+  }
+  return matches;
+}
+
+function composePointer(matches, skillsBase) {
+  // Output format intentionally short. The model only needs the path; reading
+  // the file is its job, not the hook's.
+  const lines = ['<ccg-domain-routing>'];
+  lines.push('The user\'s prompt mentions a domain that CCG has authoritative reference material for.');
+  lines.push('Read the file(s) below BEFORE answering — do not rely on training-data recall for these topics.');
+  lines.push('');
+  for (const m of matches) {
+    lines.push(`- ${m.label}: ${skillsBase}/${m.skill}`);
+  }
+  lines.push('</ccg-domain-routing>');
+  return lines.join('\n');
+}
+
+function main() {
+  const input = readInput();
+  if (!input) {
+    process.exit(0);
+    return;
+  }
+  const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+  if (!prompt) {
+    process.exit(0);
+    return;
+  }
+
+  const matches = findMatches(prompt);
+  if (matches.length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  // Resolve skills directory once. We point at the user-facing install path
+  // (~/.claude/skills/ccg) rather than checking it exists — if the user
+  // uninstalled the skills, the model's Read will fail loudly and we surface
+  // that, which is preferable to silently swallowing the routing.
+  const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+  if (!homeDir) {
+    // Stripped CI container / minimal Docker image with no HOME or USERPROFILE.
+    // Skip the injection entirely — pointing at '/.claude/skills/ccg' would be
+    // worse than nothing (the model would Read a path that cannot exist).
+    process.exit(0);
+    return;
+  }
+  const skillsBase = `${homeDir.replace(/\\/g, '/')}/.claude/skills/ccg`;
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: composePointer(matches, skillsBase),
+    },
+  }));
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  findMatches,
+  composePointer,
+  matchKeyword,
+  ROUTES,
+  MAX_INJECTIONS,
+  SHORT_KW_CUTOFF,
+};

package/templates/hooks/ccg-stop-gate.cjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// CCG Stop Gate Hook — Stop / SubagentStop
+//
+// When Claude is about to end its turn, check whether there are still
+// active background tasks the user expects to finish. Emit a warning into
+// additionalContext so the model does not falsely claim "done" while:
+//   - a CCG job (.context/jobs/<id>/state.json) is still queued/running
+//   - Claude Code's own harness reports background_tasks (added in 2.1.145)
+//
+// Why this matters: fork's async trio (status/result/cancel) and
+// phase-runner-launcher wrap codex/gemini calls in long-lived OS subprocesses.
+// Without this hook, the main thread frequently said "✅ complete" while a
+// launcher was still mid-task. Users had to keep checking /ccg:status.
+//
+// Design choices:
+//   - Warn, never block. Setting `decision: "block"` would force the model to
+//     keep working, which is the wrong tool when the user explicitly said
+//     "stop" or when the model finished its main answer and the background
+//     task is fire-and-forget. We surface the info; the model decides.
+//   - Source-of-truth merge: harness-reported background_tasks ∪ CCG jobs.
+//     The two sets overlap heavily but neither is a superset. Harness sees
+//     bash run_in_background processes; CCG sees its own job registry.
+//   - Bounded scan: list the .context/jobs/ directory but never read a file
+//     bigger than 64 KB. Performance must not regress.
+//
+// Performance budget: <100 ms even with many jobs. Hook runs on every Stop.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const JOBS_SUBDIR = path.join('.context', 'jobs');
+const ACTIVE_STATUSES = new Set(['queued', 'running']);
+const MAX_STATE_FILE_BYTES = 64 * 1024;
+const MAX_REPORT_JOBS = 5; // truncate to keep additionalContext tight
+
+function readInput() {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(0, 'utf-8');
+  }
+  catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw || '{}');
+  }
+  catch {
+    return null;
+  }
+}
+
+function readJobState(stateFile) {
+  try {
+    const stat = fs.statSync(stateFile);
+    if (!stat.isFile() || stat.size > MAX_STATE_FILE_BYTES) return null;
+    const raw = fs.readFileSync(stateFile, 'utf-8');
+    return JSON.parse(raw);
+  }
+  catch {
+    return null;
+  }
+}
+
+// Returns array of { jobId, status, phase, summary, sourcedFrom: 'ccg-jobs' }.
+function scanCcgJobs(cwd) {
+  const jobsDir = path.join(cwd, JOBS_SUBDIR);
+  let entries;
+  try {
+    entries = fs.readdirSync(jobsDir, { withFileTypes: true });
+  }
+  catch {
+    return [];
+  }
+  const active = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const jobId = entry.name;
+    const state = readJobState(path.join(jobsDir, jobId, 'state.json'));
+    if (!state || typeof state.status !== 'string') continue;
+    if (!ACTIVE_STATUSES.has(state.status)) continue;
+    active.push({
+      jobId,
+      status: state.status,
+      phase: typeof state.phase === 'string' ? state.phase : null,
+      summary: typeof state.summary === 'string' ? state.summary.slice(0, 120) : null,
+      sourcedFrom: 'ccg-jobs',
+    });
+  }
+  return active;
+}
+
+// Normalize harness-supplied background_tasks (field shape added in CC 2.1.145).
+// Shape is best-effort: we accept either an array of strings (task ids) or an
+// array of objects with at minimum a `task_id` or `id` field.
+function normalizeHarnessTasks(input) {
+  const raw = input && input.background_tasks;
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const item of raw) {
+    if (typeof item === 'string') {
+      out.push({ jobId: item, status: 'unknown', phase: null, summary: null, sourcedFrom: 'harness' });
+    }
+    else if (item && typeof item === 'object') {
+      const jobId = item.task_id || item.id || item.name || '(unnamed)';
+      const status = typeof item.status === 'string' ? item.status : 'unknown';
+      out.push({
+        jobId,
+        status,
+        phase: typeof item.phase === 'string' ? item.phase : null,
+        summary: typeof item.description === 'string' ? item.description.slice(0, 120) : null,
+        sourcedFrom: 'harness',
+      });
+    }
+  }
+  return out;
+}
+
+function mergeTasks(ccgJobs, harnessTasks) {
+  // Dedupe by jobId across the two sources (CCG jobs win on conflict because
+  // their status is authoritative — harness only knows "active").
+  const seen = new Set();
+  const merged = [];
+  for (const j of ccgJobs) {
+    seen.add(j.jobId);
+    merged.push(j);
+  }
+  for (const h of harnessTasks) {
+    if (seen.has(h.jobId)) continue;
+    merged.push(h);
+  }
+  return merged;
+}
+
+function composeWarning(eventName, tasks) {
+  const limited = tasks.slice(0, MAX_REPORT_JOBS);
+  const omitted = tasks.length - limited.length;
+  const lines = ['<ccg-stop-gate>'];
+  lines.push(`⚠️ ${tasks.length} background task(s) still active at ${eventName}.`);
+  lines.push('Do not declare the user-facing work "complete" until these settle.');
+  lines.push('Options: tell the user "background X is still running, check /ccg:status <id>", or wait and re-summarize.');
+  lines.push('');
+  for (const t of limited) {
+    const phase = t.phase ? ` phase=${t.phase}` : '';
+    const summary = t.summary ? ` — ${t.summary}` : '';
+    lines.push(`- ${t.jobId} [${t.status}, ${t.sourcedFrom}]${phase}${summary}`);
+  }
+  if (omitted > 0) {
+    lines.push(`- ... ${omitted} more (truncated)`);
+  }
+  lines.push('</ccg-stop-gate>');
+  return lines.join('\n');
+}
+
+function detectEvent(input) {
+  // Claude Code Stop/SubagentStop payloads carry the event name in
+  // `hook_event_name`. Default to 'Stop' if absent — the model treats the two
+  // identically, this only affects the echoed hookEventName field in our
+  // response envelope.
+  if (input && typeof input.hook_event_name === 'string') {
+    if (input.hook_event_name === 'SubagentStop') return 'SubagentStop';
+  }
+  return 'Stop';
+}
+
+function main() {
+  const input = readInput();
+  const cwd = (input && typeof input.cwd === 'string' && input.cwd) ? input.cwd : process.cwd();
+  const eventName = detectEvent(input);
+
+  const ccgJobs = scanCcgJobs(cwd);
+  const harnessTasks = normalizeHarnessTasks(input);
+  const merged = mergeTasks(ccgJobs, harnessTasks);
+
+  if (merged.length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext: composeWarning(eventName, merged),
+    },
+  }));
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  scanCcgJobs,
+  normalizeHarnessTasks,
+  mergeTasks,
+  composeWarning,
+  detectEvent,
+  ACTIVE_STATUSES,
+  MAX_REPORT_JOBS,
+};