voyage/hooks/scripts/pre-agent-cap.mjs

#!/usr/bin/env node
// Hook: pre-agent-cap.mjs
// Event: PreToolUse (WebSearch | WebFetch | Task)
// Purpose: Enforce the /trekresearch Phase 5 loop bound at the harness level,
//   so the cap is a reader that fells rather than prose the model obeys.
//
// Why this exists: the Phase 5 budget gate (lib/util/research-loop-cap.mjs) is
// invoked BY the loop. A gate the caller chooses to consult is advice. The
// spike in docs/spike-pretooluse-subagent-reach.md (RESULT: FIRES) established
// that a plugin PreToolUse hook does observe tool calls made INSIDE sub-agents
// on CC 2.1.226, which is what makes a second, non-optional gate possible.
//
// Two limits carried over from that spike, neither of which changes the design:
//   - Reach was measured on one CC version and regressed once before (#34692),
//     so this hook is defence in depth, never the only gate. research-loop-cap
//     must stay correct if this hook silently stops firing.
//   - Whether a blocking (exit 2) decision from inside a sub-agent propagates
//     usefully was NOT measured — the probe always exited 0 by design.
//
// Scope key — the property that makes this safe to wire globally:
//   session_id + a scope marker file that only the Phase 5 loop writes, at
//   ${CLAUDE_PLUGIN_DATA}/trekresearch-loop-scope/<session_id>.json:
//       { "runId": "<run id>", "startedAt": "<ISO-8601>" }
//   No marker for this session => out of scope => allow, unconditionally. An
//   unrelated session must never be denied because some other run spent its
//   budget; a PreToolUse hook that over-blocks breaks every session on the box.
//
// Fail-open vs fail-closed, deliberately split:
//   - Out of scope (no marker, no session_id, unparsable stdin, stale marker,
//     kill switch, STORM off) => exit 0. Fail OPEN.
//   - In scope but the ledger cannot be read (CLAUDE_PLUGIN_DATA absent) =>
//     exit 2. Fail CLOSED, mirroring research-loop-cap.mjs's own stance: a
//     budget control that cannot count must not grant.
//
// Counting is read-only. The ledger is append-only and written solely by
// research-loop-cap.mjs's allowTurn(); if this hook appended, the cap would
// count its own enforcement.
//
// Kill switch: VOYAGE_DISABLE_CAP_HOOK=1 disables enforcement entirely.

import { readFileSync, existsSync, rmSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const HERE = dirname(fileURLToPath(import.meta.url));
const { resolveLedgerPath, resolveMaxConvTurns, isStormEnabled, MAX_TOTAL_DIMENSIONS } =
  await import(join(HERE, '..', '..', 'lib', 'util', 'research-loop-cap.mjs'));

const SCOPE_DIRNAME = 'trekresearch-loop-scope';
const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000; // 6h — longer than any real research run

const env = process.env;

function allow() {
  process.exit(0);
}

function deny(message) {
  process.stderr.write(`[voyage] BLOCKED: trekresearch loop cap\n${message}\n`);
  process.exit(2);
}

// 1. Kill switch.
if (env.VOYAGE_DISABLE_CAP_HOOK === '1') allow();

// 2. Default-off: no loop runs unless STORM is enabled, so nothing to enforce.
if (!isStormEnabled(env)) allow();

// 3. Parse stdin. Unparsable input is not evidence of a loop turn.
let input;
try {
  input = JSON.parse(readFileSync(0, 'utf-8'));
} catch {
  allow();
}

const sessionId = input?.session_id;
if (!sessionId || typeof sessionId !== 'string') allow();

// 4. Resolve the scope marker. VOYAGE_CAP_SCOPE_DIR exists so the marker
//    location stays addressable when CLAUDE_PLUGIN_DATA is being tested as
//    absent; in production both point at the same plugin data directory.
const scopeDir = env.VOYAGE_CAP_SCOPE_DIR || env.CLAUDE_PLUGIN_DATA;
if (!scopeDir) allow();

const markerPath = join(scopeDir, SCOPE_DIRNAME, `${sessionId}.json`);
if (!existsSync(markerPath)) allow();

let marker;
try {
  marker = JSON.parse(readFileSync(markerPath, 'utf-8'));
} catch {
  allow(); // A marker we cannot read cannot tell us which run we are in.
}

if (!marker?.runId) allow();

// 5. TTL / auto-reset. A marker left behind by a crashed run must not deny
//    tool calls for the rest of the machine's life.
const ttlRaw = Number(env.VOYAGE_CAP_SCOPE_TTL_MS);
const ttlMs = Number.isFinite(ttlRaw) && ttlRaw > 0 ? ttlRaw : DEFAULT_TTL_MS;
const startedAt = Date.parse(marker.startedAt ?? '');
if (!Number.isFinite(startedAt) || Date.now() - startedAt > ttlMs) {
  try { rmSync(markerPath, { force: true }); } catch { /* best effort */ }
  allow();
}

// --- In scope from here on. ---

// 6. The ledger is the only source of truth for turns spent.
const ledgerPath = resolveLedgerPath(env);
if (!ledgerPath) {
  deny(
    `  Session ${sessionId} is inside a Phase 5 research loop (run ${marker.runId}),\n` +
    `  but CLAUDE_PLUGIN_DATA is not set, so the turn ledger cannot be read.\n` +
    `  A budget control that cannot count does not grant. Set CLAUDE_PLUGIN_DATA,\n` +
    `  or set VOYAGE_DISABLE_CAP_HOOK=1 to disable this hook.`,
  );
}

function countTurns(path, runId) {
  if (!existsSync(path)) return 0;
  let text;
  try { text = readFileSync(path, 'utf-8'); } catch { return 0; }
  let count = 0;
  for (const line of text.split('\n')) {
    if (!line) continue;
    try {
      if (JSON.parse(line).runId === runId) count++;
    } catch { /* skip malformed lines */ }
  }
  return count;
}

// 7. Same bound the primitive uses: turns-per-dimension × the whole dimension
//    list under settings.json:16's maxDimensions ceiling.
const budget = resolveMaxConvTurns(env) * MAX_TOTAL_DIMENSIONS;
const used = countTurns(ledgerPath, marker.runId);

if (used >= budget) {
  deny(
    `  Run ${marker.runId} has spent ${used}/${budget} loop turns.\n` +
    `  Tool: ${input?.tool_name ?? 'unknown'}${input?.agent_type ? ` (agent: ${input.agent_type})` : ''}\n` +
    `  Remaining gaps belong in the brief as open questions, not in another turn.\n` +
    `  Raise TREKRESEARCH_MAX_CONV_TURNS deliberately, or set VOYAGE_DISABLE_CAP_HOOK=1.`,
  );
}

allow();