ccgx-workflow 2.4.1 → 2.5.0

package/templates/hooks/ccg-subagent-context.cjs

@@ -0,0 +1,505 @@
+#!/usr/bin/env node
+// ccg-hook: subagent-context
+// PreToolUse Hook (matcher: Task|Agent) — inject the active phase spec into a
+// subagent's prompt via hookSpecificOutput.updatedInput.
+//
+// Problem this solves (fork adaptation of upstream subagent-context.js):
+//   PreToolUse `additionalContext` only reaches the CALLING (lead) session —
+//   the subagent does not exist yet when the hook fires, so it never sees it.
+//   `updatedInput` replaces the tool input itself, which means the injected
+//   spec lands inside the subagent's prompt. We spread the original tool_input
+//   so subagent_type / description / model / team_name / name survive intact.
+//
+// Fork-specific hardening over upstream:
+//   - injection source is .context/ (CONTEXT.md / SUMMARY.md frontmatter) +
+//     .ccg/roadmap.md + the P1-4 task container .context/tasks/ — not the
+//     upstream .ccg/tasks layout
+//   - <ccg-phase-context> marker makes the injection idempotent (an
+//     orchestrator re-forwarding an already-injected prompt does not stack)
+//   - hard total budget MAX_INJECTION_CHARS (closing tag is never truncated)
+//   - non-CCG projects short-circuit with ZERO stdout (no output at all)
+//
+// Hook contract (Claude Code PreToolUse event):
+//   stdin  : JSON { session_id, cwd, hook_event_name, tool_name, tool_input }
+//   stdout : { hookSpecificOutput: { hookEventName: 'PreToolUse',
+//                                    updatedInput: { ...tool_input, prompt } } }
+//            Deliberately NO permissionDecision — updatedInput works on its
+//            own and we must not change permission-approval semantics.
+//
+// Failure policy: never throw, never block a spawn. Any parse/read error
+// degrades to a smaller injection or to a silent no-op (exit 0, no stdout).
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ---------------------------------------------------------------------------
+// Constants (all exported for tests)
+// ---------------------------------------------------------------------------
+
+const INJECTION_MARKER = '<ccg-phase-context>';
+const INJECTION_END = '</ccg-phase-context>';
+
+/** Hard total budget for the composed injection, tags + header included. */
+const MAX_INJECTION_CHARS = 2048;
+
+/** Per-section cap; over-long frontmatter is truncated with a marker. */
+const MAX_SECTION_CHARS = 1400;
+
+/** Claude Code 2.x historical name `Task`, current name `Agent` — both. */
+const AGENT_TOOL_NAMES = new Set(['Task', 'Agent']);
+
+/**
+ * Agents exempt from injection (substring match):
+ *   - get-current-datetime: trivial, not worth a 2KB prompt tax
+ *   - phase-runner: its prompt is baked by /ccg:autonomous and already
+ *     carries the full phase context (injection is pure redundancy); P1-5
+ *     additionally requires the exemption so `--resume` workflow runs keep
+ *     deterministic `agent()` cache keys (no resumeFromRunId drift).
+ */
+const SUBAGENT_DENYLIST = ['get-current-datetime', 'phase-runner'];
+
+/**
+ * Read-side terminal synonyms — must mirror task-store.cjs
+ * TERMINAL_STATUS_SYNONYMS (the P1-4 write side is canonical; readers are
+ * tolerant because the status field is model-written free text in practice).
+ */
+const TERMINAL_TASK_STATUSES = new Set([
+  'completed', 'complete', 'done', 'finished', 'closed',
+  'archived', 'cancelled', 'canceled', 'abandoned', 'failed',
+]);
+
+/**
+ * Size guards on the JSON files this hook reads. The STATE.json projection is
+ * a handful of fields (mirrors ccg-statusline.js STATE_MAX_BYTES); a task.json
+ * is a record plus an artifacts list. Anything bigger is corrupt/abusive and
+ * is treated like unreadable JSON (null / skip).
+ */
+const MAX_STATE_BYTES = 16384;
+const MAX_TASK_BYTES = 65536;
+
+// ---------------------------------------------------------------------------
+// CCG project detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Path-normalized directory equality. Windows paths are case-insensitive
+ * (C:\Users\X vs c:\users\x), so the $HOME stop guard must not compare raw
+ * strings — aligned with ccg-statusline.js.
+ */
+function isSameDir(a, b) {
+  if (!a || !b) return false;
+  try {
+    const na = path.resolve(a);
+    const nb = path.resolve(b);
+    if (process.platform === 'win32') return na.toLowerCase() === nb.toLowerCase();
+    return na === nb;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Walk up from startDir (max 10 levels, stopping at $HOME / fs root) looking
+ * for a CCG project root: a directory containing .ccg/roadmap.md or a
+ * .context/ dir. Returns the directory path or null. Non-CCG projects
+ * short-circuit here, so the hook costs ~nothing outside CCG repos.
+ */
+function findCcgRoot(startDir) {
+  let dir;
+  try {
+    dir = path.resolve(startDir || '.');
+  } catch {
+    return null;
+  }
+  let home = '';
+  try {
+    home = os.homedir();
+  } catch {
+    home = '';
+  }
+  for (let i = 0; i < 10; i++) {
+    try {
+      if (
+        fs.existsSync(path.join(dir, '.ccg', 'roadmap.md'))
+        || fs.existsSync(path.join(dir, '.context'))
+      ) {
+        return dir;
+      }
+    } catch {
+      return null;
+    }
+    // $HOME stop guard (checked AFTER the candidate test, so a CCG root at
+    // $HOME itself still resolves) — aligned with ccg-statusline.js.
+    if (home && isSameDir(dir, home)) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Roadmap / phase resolution (reuses ccg-session-state.cjs parsers — sibling
+// require; its require.main guard ensures importing never runs its main()).
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the active phase from <root>/.ccg/roadmap.md. Returns
+ * { project?, n, title, status, dirName, total, completed } or null when the
+ * roadmap is missing, unparseable, or has no active (in_progress/pending)
+ * phase. Never throws — a stale sibling hook without exports degrades to null.
+ */
+function getActivePhaseInfo(root) {
+  let ss;
+  try {
+    ss = require(path.join(__dirname, 'ccg-session-state.cjs'));
+  } catch {
+    return null;
+  }
+  let text;
+  try {
+    text = fs.readFileSync(path.join(root, '.ccg', 'roadmap.md'), 'utf-8');
+  } catch {
+    return null;
+  }
+  try {
+    const head = ss.parseRoadmapHead(text);
+    const phases = ss.parsePhases(text);
+    const active = ss.pickActivePhase(phases);
+    if (!active) return null;
+    return {
+      project: head && head.project ? head.project : undefined,
+      n: active.n,
+      title: active.title,
+      status: active.status,
+      dirName: ss.phaseDirName(active),
+      total: phases.length,
+      completed: phases.filter(p => p.status === 'completed').length,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return the raw frontmatter block (between the leading `---` fences) of a
+ * file, trimmed, or null when the file is missing or has no frontmatter.
+ * We inject the RAW text — the subagent parses it itself; the hook must not
+ * re-serialize (it cannot import src/utils/phase-context.ts).
+ */
+function readFrontmatterBlock(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const block = m[1].trim();
+  return block || null;
+}
+
+// ---------------------------------------------------------------------------
+// Active task (P1-4 seam — read-only consumer of the .context/tasks container)
+// ---------------------------------------------------------------------------
+
+function isTerminalTaskStatus(status) {
+  if (typeof status !== 'string') return false;
+  return TERMINAL_TASK_STATUSES.has(status.trim().toLowerCase());
+}
+
+/**
+ * Hard cap on the number of `.context/tasks/` entries the fallback scan may
+ * inspect (hook performance budget — every entry costs a readFileSync +
+ * JSON.parse). Oversized containers are sorted then truncated so the kept
+ * window is deterministic across platforms.
+ */
+const MAX_TASK_DIRS = 24;
+
+/** Shape a raw task.json record into the injection contract. */
+function shapeTask(dirId, task) {
+  const id = typeof task.id === 'string' && task.id ? task.id : dirId;
+  return {
+    id,
+    title: typeof task.title === 'string' && task.title ? task.title : id,
+    status: String(task.status || 'unknown'),
+    phase: typeof task.active_phase === 'string' && task.active_phase
+      ? task.active_phase
+      : undefined,
+  };
+}
+
+/**
+ * Read + parse a JSON file with a statSync size guard. Returns the parsed
+ * object, or null on any failure (missing, not a file, oversized, corrupt
+ * JSON, non-object). Never throws.
+ */
+function readJsonBounded(filePath, maxBytes) {
+  try {
+    const st = fs.statSync(filePath);
+    if (!st.isFile() || st.size > maxBytes) return null;
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * O(1) fast path: `.context/STATE.json` is the task-store derived projection
+ * (P1-4); its `active_task_id` points at the active task without scanning the
+ * container. Returns the shaped task, or null when STATE.json is missing /
+ * invalid / oversized / from a foreign schema version, the pointed task.json
+ * is unreadable, or the pointed task is terminal (stale projection) — callers
+ * then fall back to the bounded scan.
+ */
+function readActiveTaskFromState(root) {
+  const state = readJsonBounded(path.join(root, '.context', 'STATE.json'), MAX_STATE_BYTES);
+  if (!state) return null;
+  // Frozen projection schema v1 — an unknown newer schema degrades cleanly to
+  // the fallback scan instead of trusting fields whose semantics may differ.
+  if (state.schema_version !== undefined && state.schema_version !== 1) return null;
+  const id = state.active_task_id;
+  if (typeof id !== 'string' || !id) return null;
+  const task = readJsonBounded(path.join(root, '.context', 'tasks', id, 'task.json'), MAX_TASK_BYTES);
+  if (!task) return null;
+  if (isTerminalTaskStatus(task.status)) return null;
+  return shapeTask(id, task);
+}
+
+/**
+ * Read the active task from <root>/.context/tasks/.
+ * Two tiers (W2 — hook performance budget):
+ *   1. Fast path: STATE.json `active_task_id` (O(1), see above).
+ *   2. Fallback scan — a read-only mirror of task-store.cjs getActiveTask():
+ *      skip the archive/ subtree, tolerate corrupt task.json, newest
+ *      non-terminal by created_at wins; capped at MAX_TASK_DIRS entries.
+ * Returns { id, title, status, phase? } or null. Zero cost when the container
+ * does not exist yet (single failed readdir).
+ */
+function readActiveTask(root) {
+  const fast = readActiveTaskFromState(root);
+  if (fast) return fast;
+
+  const tasksDir = path.join(root, '.context', 'tasks');
+  let entries;
+  try {
+    entries = fs.readdirSync(tasksDir);
+  } catch {
+    return null;
+  }
+  if (entries.length > MAX_TASK_DIRS) {
+    entries = entries.slice().sort().slice(0, MAX_TASK_DIRS);
+  }
+  const tasks = [];
+  for (const id of entries) {
+    if (id === 'archive') continue;
+    // missing / corrupt / oversized task.json — skip, never throw
+    const task = readJsonBounded(path.join(tasksDir, id, 'task.json'), MAX_TASK_BYTES);
+    if (!task) continue;
+    if (typeof task.id !== 'string' || !task.id) task.id = id;
+    if (typeof task.created_at !== 'string') task.created_at = '';
+    tasks.push(task);
+  }
+  tasks.sort((a, b) => b.created_at.localeCompare(a.created_at));
+  for (const task of tasks) {
+    if (isTerminalTaskStatus(task.status)) continue;
+    return shapeTask(task.id, task);
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Injection composition
+// ---------------------------------------------------------------------------
+
+function truncateSection(text) {
+  if (text.length <= MAX_SECTION_CHARS) return text;
+  return `${text.slice(0, MAX_SECTION_CHARS)}\n...(truncated)`;
+}
+
+/**
+ * Compose the injection block, greedily packing sections by priority within
+ * the MAX_INJECTION_CHARS hard budget (a section that does not fit is skipped
+ * and later, shorter sections are still tried):
+ *   (a) roadmap position line
+ *   (b) CONTEXT.md frontmatter (frozen decisions)
+ *   (c) active task line (P1-4 container)
+ *   (d) SUMMARY.md frontmatter (progress — rerun/resume scenarios)
+ * Returns null when no section is available. Hard invariant: the returned
+ * string length is <= MAX_INJECTION_CHARS and ends with INJECTION_END.
+ */
+function composeInjection(root) {
+  const candidates = [];
+  const info = getActivePhaseInfo(root);
+
+  if (info) {
+    const project = info.project || path.basename(root);
+    candidates.push(
+      `Roadmap: ${project} | phases ${info.completed}/${info.total} completed`
+      + ` | active: Phase ${info.n} ${info.title} (${info.status})`,
+    );
+    const contextFm = readFrontmatterBlock(
+      path.join(root, '.context', info.dirName, 'CONTEXT.md'),
+    );
+    if (contextFm) {
+      candidates.push(
+        `--- .context/${info.dirName}/CONTEXT.md (frozen decisions) ---\n${truncateSection(contextFm)}`,
+      );
+    }
+  }
+
+  const task = readActiveTask(root);
+  if (task) {
+    let line = `Task: ${task.title} (${task.status})`;
+    if (task.phase) line += ` | phase: ${task.phase}`;
+    line += ` — .context/tasks/${task.id}`;
+    candidates.push(line);
+  }
+
+  if (info) {
+    const summaryFm = readFrontmatterBlock(
+      path.join(root, '.context', info.dirName, 'SUMMARY.md'),
+    );
+    if (summaryFm) {
+      candidates.push(
+        `--- .context/${info.dirName}/SUMMARY.md (progress) ---\n${truncateSection(summaryFm)}`,
+      );
+    }
+  }
+
+  if (candidates.length === 0) return null;
+
+  const header = '[CCG] Auto-injected phase spec (source: .context/ + .ccg/).'
+    + ' Honor the decisions/constraints below; do not re-litigate them.';
+  // Joined shape: MARKER \n header \n seg1 \n ... \n segN \n END
+  // Fixed overhead = marker + header + end + 2 joining newlines; each chosen
+  // segment then costs its own length + 1 joining newline.
+  let budget = MAX_INJECTION_CHARS
+    - (INJECTION_MARKER.length + header.length + INJECTION_END.length + 2);
+  const chosen = [];
+  for (const seg of candidates) {
+    const cost = seg.length + 1;
+    if (cost <= budget) {
+      chosen.push(seg);
+      budget -= cost;
+    }
+  }
+  if (chosen.length === 0) return null;
+
+  return [INJECTION_MARKER, header, ...chosen, INJECTION_END].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Decision (pure function — primary test entry)
+// ---------------------------------------------------------------------------
+
+/**
+ * decide(stdinJson) → { action: 'skip' } | { action: 'inject', updatedInput }.
+ * Skip conditions (any one):
+ *   - tool_name outside Task|Agent (defense in depth behind the matcher)
+ *   - tool_input.prompt is not a non-empty string
+ *   - subagent_type hits SUBAGENT_DENYLIST
+ *   - prompt already carries INJECTION_MARKER (idempotency)
+ *   - cwd is not inside a CCG project
+ *   - nothing to inject (no roadmap phase, no CONTEXT/SUMMARY, no task)
+ * On inject, updatedInput spreads the original tool_input so every other
+ * field (subagent_type / description / model / team_name / name) survives.
+ */
+function decide(input) {
+  const data = input && typeof input === 'object' ? input : {};
+  const toolInput = data.tool_input && typeof data.tool_input === 'object'
+    ? data.tool_input
+    : {};
+
+  if (!AGENT_TOOL_NAMES.has(data.tool_name)) return { action: 'skip' };
+  if (typeof toolInput.prompt !== 'string' || !toolInput.prompt) return { action: 'skip' };
+
+  const subagentType = String(toolInput.subagent_type || '');
+  if (SUBAGENT_DENYLIST.some(d => subagentType.includes(d))) return { action: 'skip' };
+  if (toolInput.prompt.includes(INJECTION_MARKER)) return { action: 'skip' };
+
+  const cwd = typeof data.cwd === 'string' && data.cwd
+    ? data.cwd
+    : (process.env.CLAUDE_PROJECT_DIR || process.cwd());
+  const root = findCcgRoot(cwd);
+  if (!root) return { action: 'skip' };
+
+  const injection = composeInjection(root);
+  if (!injection) return { action: 'skip' };
+
+  return {
+    action: 'inject',
+    updatedInput: Object.assign({}, toolInput, {
+      prompt: `${injection}\n\n---\n\n${toolInput.prompt}`,
+    }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Entry point — only runs when invoked directly (not when required by tests
+// or by a sibling hook).
+// ---------------------------------------------------------------------------
+
+function main() {
+  try {
+    let raw;
+    try {
+      raw = fs.readFileSync(0, 'utf-8');
+    } catch {
+      process.exit(0);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw || '{}');
+    } catch {
+      process.exit(0);
+    }
+    const d = decide(parsed);
+    if (d.action === 'inject') {
+      // Deliberately no permissionDecision: updatedInput is valid standalone
+      // and omitting it keeps the user's permission-approval flow untouched.
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          updatedInput: d.updatedInput,
+        },
+      }));
+    }
+    // skip → zero stdout: non-CCG projects pay nothing, Claude Code treats
+    // empty output as "no changes".
+    process.exit(0);
+  } catch {
+    process.exit(0);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+// Test surface — consumed by src/utils/__tests__/subagentContext.test.ts.
+module.exports = {
+  findCcgRoot,
+  getActivePhaseInfo,
+  readFrontmatterBlock,
+  readActiveTask,
+  readActiveTaskFromState,
+  composeInjection,
+  decide,
+  INJECTION_MARKER,
+  INJECTION_END,
+  MAX_INJECTION_CHARS,
+  MAX_SECTION_CHARS,
+  MAX_TASK_DIRS,
+  MAX_STATE_BYTES,
+  MAX_TASK_BYTES,
+  AGENT_TOOL_NAMES,
+  SUBAGENT_DENYLIST,
+  TERMINAL_TASK_STATUSES,
+};