cclaw-cli 1.0.0 → 2.0.0

package/dist/runtime/run-hook.mjs

@@ -7715,6 +7715,10 @@ const EARLY_LOOP_ENABLED = ${JSON.stringify(earlyLoopEnabled)};
 const EARLY_LOOP_MAX_ITERATIONS = ${JSON.stringify(earlyLoopMaxIterations)};
 const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliRuntime.entrypoint)};
 const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
+const SESSION_DIGEST_SCHEMA_VERSION = 1;
+const SESSION_DIGEST_CACHE_FILE = "session-digest.json";
+const SESSION_DIGEST_REFRESH_MARKER_FILE = "session-digest.refresh.json";
+const SESSION_DIGEST_REFRESH_STALE_MS = 30000;
 
 ${SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS}
 ${SHARED_STAGE_SUPPORT_SNIPPETS}
@@ -8140,9 +8144,10 @@ function hookEventNameForOutput(hookName) {
   if (hookName === "session-start") return "SessionStart";
   if (hookName === "prompt-guard") return "PreToolUse";
   if (hookName === "workflow-guard") return "PreToolUse";
+  if (hookName === "pre-tool-pipeline") return "PreToolUse";
+  if (hookName === "prompt-pipeline") return "UserPromptSubmit";
   if (hookName === "context-monitor") return "PostToolUse";
   if (hookName === "stop-handoff") return "Stop";
-  if (hookName === "pre-compact") return "PreCompact";
   if (hookName === "verify-current-state") return "UserPromptSubmit";
   return "SessionStart";
 }
@@ -8551,78 +8556,55 @@ async function readFlowState(root) {
   };
 }
 
-
-async function buildKnowledgeDigest(root, currentStage, prereadRaw) {
-  const knowledgeFile = path.join(root, RUNTIME_ROOT, "knowledge.jsonl");
-  // Caller may supply pre-read raw bytes to avoid re-reading knowledge.jsonl.
-  // Falls back to a local read if nothing is passed in.
-  const raw = typeof prereadRaw === "string"
-    ? prereadRaw
-    : await readTextFile(knowledgeFile, "");
-  const digest = parseKnowledgeDigest(raw, currentStage, 6);
-  return {
-    digestLines: digest.lines,
-    learningsCount: digest.learningsCount
-  };
+async function readFileMtimeMs(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    if (!stat.isFile()) return 0;
+    return Math.trunc(stat.mtimeMs);
+  } catch {
+    return 0;
+  }
 }
 
-async function readStageSupportContext(root, currentStage) {
-  if (!isKnownStageId(currentStage)) return [];
-  const stage = currentStage;
-
-  const parts = [];
-  const contractPath = path.join(root, RUNTIME_ROOT, "templates", "state-contracts", stage + ".json");
-  const contract = (await readTextFile(contractPath, "")).trim();
-  if (contract.length > 0) {
-    parts.push(
-      "Current stage state contract (read before drafting or editing the stage artifact):\\n" +
-        contract
-    );
-  }
+function parseNumericMs(value) {
+  return typeof value === "number" && Number.isFinite(value)
+    ? Math.trunc(value)
+    : -1;
+}
 
-  const promptName = reviewPromptFileName(stage);
-  if (typeof promptName === "string") {
-    const promptPath = path.join(root, RUNTIME_ROOT, "skills", "review-prompts", promptName);
-    const prompt = (await readTextFile(promptPath, "")).trim();
-    if (prompt.length > 0) {
-      parts.push(
-        "Current stage calibrated review prompt (use before asking for approval/completion):\\n" +
-          prompt
-      );
-    }
+async function readSessionDigestLines(stateDir, state, flowStateMtimeMs) {
+  const cachePath = path.join(stateDir, SESSION_DIGEST_CACHE_FILE);
+  const cache = toObject(await readJsonFile(cachePath, {})) || {};
+  const cachedMtimeMs = parseNumericMs(cache.flowStateMtimeMs);
+  const sameStage = typeof cache.currentStage === "string" ? cache.currentStage === state.currentStage : true;
+  const sameRun = typeof cache.activeRunId === "string" ? cache.activeRunId === state.activeRunId : true;
+  const fresh = cachedMtimeMs === flowStateMtimeMs && sameStage && sameRun;
+  if (!fresh) {
+    return {
+      ralphLoopLine: "",
+      earlyLoopLine: "",
+      compoundReadinessLine: "",
+      fresh: false
+    };
   }
-
-  return parts;
+  return {
+    ralphLoopLine: typeof cache.ralphLoopLine === "string" ? cache.ralphLoopLine : "",
+    earlyLoopLine: typeof cache.earlyLoopLine === "string" ? cache.earlyLoopLine : "",
+    compoundReadinessLine: typeof cache.compoundReadinessLine === "string" ? cache.compoundReadinessLine : "",
+    fresh: true
+  };
 }
 
-async function handleSessionStart(runtime) {
-  const state = await readFlowState(runtime.root);
-  const stateDir = path.join(runtime.root, RUNTIME_ROOT, "state");
-  const ironLawsFile = path.join(stateDir, "iron-laws.json");
-  const metaSkillFile = path.join(runtime.root, RUNTIME_ROOT, "skills", "using-cclaw", "SKILL.md");
-
-
-  // Read knowledge.jsonl exactly once per session-start while holding the
-  // SAME lock CLI writers acquire in \`appendKnowledge\`. Guarantees we never
-  // see a partial (mid-write) snapshot. Both the digest and
-  // compound-readiness derive from this single read.
-  const knowledgeFilePath = path.join(runtime.root, RUNTIME_ROOT, "knowledge.jsonl");
-  const knowledgeRaw = await readTextFileLocked(
-    knowledgeLockPathInline(runtime.root),
-    knowledgeFilePath,
-    ""
-  );
-  const knowledge = await buildKnowledgeDigest(runtime.root, state.currentStage, knowledgeRaw);
-
-  // Refresh Ralph Loop status each session-start so /cc and the model
-  // both read a consistent "iter=N, acClosed=[...]" snapshot. Runs only when
-  // we are in tdd \u2014 other stages skip the write to keep the file stable.
+async function refreshSessionDigestCache(root, state, flowStateMtimeMs) {
+  const stateDir = path.join(root, RUNTIME_ROOT, "state");
   let ralphLoopLine = "";
   let earlyLoopLine = "";
+  let compoundReadinessLine = "";
+
   if (state.currentStage === "tdd") {
     try {
       const internalRalph = await runCclawInternal(
-        runtime.root,
+        root,
         ["tdd-loop-status", "--json", "--write"],
         { captureStdout: true }
       );
@@ -8635,12 +8617,8 @@ async function handleSessionStart(runtime) {
       }
       ralphLoopLine = formatRalphLoopStatusLineFromJson(ralphStatus);
     } catch (err) {
-      // Best-effort \u2014 a malformed cycle log should never break
-      // session-start. But we DO leave a breadcrumb in
-      // hook-errors.jsonl so \`npx cclaw-cli sync\` can surface chronic
-      // failures (previously this was a silent swallow).
       await recordHookError(
-        runtime.root,
+        root,
         "session-start:ralph-loop",
         err instanceof Error ? err.message : String(err)
       );
@@ -8652,7 +8630,7 @@ async function handleSessionStart(runtime) {
   ) {
     try {
       const internalEarly = await runCclawInternal(
-        runtime.root,
+        root,
         [
           "early-loop-status",
           "--json",
@@ -8674,21 +8652,17 @@ async function handleSessionStart(runtime) {
       earlyLoopLine = formatEarlyLoopStatusLineFromJson(earlyLoopStatus);
     } catch (err) {
       await recordHookError(
-        runtime.root,
+        root,
         "session-start:early-loop",
         err instanceof Error ? err.message : String(err)
       );
     }
   }
 
-  // Keep compound-readiness.json fresh on every session-start (cheap derived
-  // summary). Surface a one-line nudge only from review and ship stages
-  // where lifting becomes relevant; earlier stages update the file silently.
-  let compoundReadinessLine = "";
   try {
     const shouldShowReadiness = state.currentStage === "review" || state.currentStage === "ship";
     const internalReadiness = await runCclawInternal(
-      runtime.root,
+      root,
       shouldShowReadiness ? ["compound-readiness"] : ["compound-readiness", "--quiet"],
       { captureStdout: true }
     );
@@ -8699,17 +8673,169 @@ async function handleSessionStart(runtime) {
       compoundReadinessLine = firstStdoutLine(internalReadiness.stdout);
     }
   } catch (err) {
-    // Best-effort \u2014 a malformed knowledge.jsonl must never break
-    // session-start. But we DO leave a breadcrumb in
-    // hook-errors.jsonl so config/IO problems become visible in
-    // \`npx cclaw-cli sync\` instead of silently degrading readiness output.
     await recordHookError(
-      runtime.root,
+      root,
       "session-start:compound-readiness",
       err instanceof Error ? err.message : String(err)
     );
   }
 
+  const digestPath = path.join(stateDir, SESSION_DIGEST_CACHE_FILE);
+  await writeJsonFile(digestPath, {
+    schemaVersion: SESSION_DIGEST_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    flowStateMtimeMs,
+    currentStage: state.currentStage,
+    activeRunId: state.activeRunId,
+    ralphLoopLine,
+    earlyLoopLine,
+    compoundReadinessLine
+  });
+}
+
+async function scheduleSessionDigestRefresh(runtime, state, flowStateMtimeMs) {
+  if (flowStateMtimeMs <= 0) return;
+  const stateDir = path.join(runtime.root, RUNTIME_ROOT, "state");
+  const digestPath = path.join(stateDir, SESSION_DIGEST_CACHE_FILE);
+  const markerPath = path.join(stateDir, SESSION_DIGEST_REFRESH_MARKER_FILE);
+
+  const cache = toObject(await readJsonFile(digestPath, {})) || {};
+  const cachedMtimeMs = parseNumericMs(cache.flowStateMtimeMs);
+  if (cachedMtimeMs === flowStateMtimeMs) return;
+
+  const marker = toObject(await readJsonFile(markerPath, {})) || {};
+  const markerMtimeMs = parseNumericMs(marker.flowStateMtimeMs);
+  const markerStartedAtMs = parseNumericMs(marker.startedAtMs);
+  const markerFresh =
+    markerMtimeMs === flowStateMtimeMs &&
+    markerStartedAtMs > 0 &&
+    Date.now() - markerStartedAtMs < SESSION_DIGEST_REFRESH_STALE_MS;
+  if (markerFresh) return;
+
+  await writeJsonFile(markerPath, {
+    flowStateMtimeMs,
+    startedAtMs: Date.now(),
+    currentStage: state.currentStage,
+    activeRunId: state.activeRunId
+  });
+
+  try {
+    const child = spawn(process.execPath, [process.argv[1], "session-start-refresh"], {
+      cwd: runtime.root,
+      stdio: "ignore",
+      windowsHide: true,
+      detached: true,
+      env: {
+        ...process.env,
+        CCLAW_PROJECT_ROOT: runtime.root,
+        CCLAW_BG_WORKER: "1"
+      }
+    });
+    child.unref();
+  } catch (err) {
+    await fs.rm(markerPath, { force: true }).catch(() => undefined);
+    await recordHookError(
+      runtime.root,
+      "session-start:spawn-refresh",
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+
+async function handleSessionStartRefresh(runtime) {
+  const state = await readFlowState(runtime.root);
+  const stateDir = path.join(runtime.root, RUNTIME_ROOT, "state");
+  const markerPath = path.join(stateDir, SESSION_DIGEST_REFRESH_MARKER_FILE);
+  try {
+    const flowStateMtimeMs = await readFileMtimeMs(state.filePath);
+    await refreshSessionDigestCache(runtime.root, state, flowStateMtimeMs);
+  } finally {
+    await fs.rm(markerPath, { force: true }).catch(() => undefined);
+  }
+  return 0;
+}
+
+
+async function buildKnowledgeDigest(root, currentStage, prereadRaw) {
+  const knowledgeFile = path.join(root, RUNTIME_ROOT, "knowledge.jsonl");
+  // Caller may supply pre-read raw bytes to avoid re-reading knowledge.jsonl.
+  // Falls back to a local read if nothing is passed in.
+  const raw = typeof prereadRaw === "string"
+    ? prereadRaw
+    : await readTextFile(knowledgeFile, "");
+  const digest = parseKnowledgeDigest(raw, currentStage, 6);
+  return {
+    digestLines: digest.lines,
+    learningsCount: digest.learningsCount
+  };
+}
+
+async function readStageSupportContext(root, currentStage) {
+  if (!isKnownStageId(currentStage)) return [];
+  const stage = currentStage;
+
+  const parts = [];
+  const contractPath = path.join(root, RUNTIME_ROOT, "templates", "state-contracts", stage + ".json");
+  const contract = (await readTextFile(contractPath, "")).trim();
+  if (contract.length > 0) {
+    parts.push(
+      "Current stage state contract (read before drafting or editing the stage artifact):\\n" +
+        contract
+    );
+  }
+
+  const promptName = reviewPromptFileName(stage);
+  if (typeof promptName === "string") {
+    const promptPath = path.join(root, RUNTIME_ROOT, "skills", "review-prompts", promptName);
+    const prompt = (await readTextFile(promptPath, "")).trim();
+    if (prompt.length > 0) {
+      parts.push(
+        "Current stage calibrated review prompt (use before asking for approval/completion):\\n" +
+          prompt
+      );
+    }
+  }
+
+  return parts;
+}
+
+async function handleSessionStart(runtime) {
+  const state = await readFlowState(runtime.root);
+  const stateDir = path.join(runtime.root, RUNTIME_ROOT, "state");
+  const ironLawsFile = path.join(stateDir, "iron-laws.json");
+  const metaSkillFile = path.join(runtime.root, RUNTIME_ROOT, "skills", "using-cclaw", "SKILL.md");
+
+
+  // Read knowledge.jsonl exactly once per session-start while holding the
+  // SAME lock CLI writers acquire in \`appendKnowledge\`. Guarantees we never
+  // see a partial (mid-write) snapshot. Both the digest and
+  // compound-readiness derive from this single read.
+  const knowledgeFilePath = path.join(runtime.root, RUNTIME_ROOT, "knowledge.jsonl");
+  const knowledgeRaw = await readTextFileLocked(
+    knowledgeLockPathInline(runtime.root),
+    knowledgeFilePath,
+    ""
+  );
+  const knowledge = await buildKnowledgeDigest(runtime.root, state.currentStage, knowledgeRaw);
+
+  // Fast path: read precomputed status lines from session-digest cache.
+  // If cache is stale, schedule a debounced background refresh so this hook
+  // returns quickly inside harness startup.
+  const flowStateMtimeMs = await readFileMtimeMs(state.filePath);
+  const forceSyncRefresh =
+    normalizeText(process.env.CCLAW_SESSION_START_BG_SYNC).toLowerCase() === "1" ||
+    ["1", "true", "yes"].includes(normalizeText(process.env.VITEST).toLowerCase());
+  let sessionDigest = await readSessionDigestLines(stateDir, state, flowStateMtimeMs);
+  if (forceSyncRefresh && flowStateMtimeMs > 0) {
+    await refreshSessionDigestCache(runtime.root, state, flowStateMtimeMs);
+    sessionDigest = await readSessionDigestLines(stateDir, state, flowStateMtimeMs);
+  } else if (!sessionDigest.fresh) {
+    await scheduleSessionDigestRefresh(runtime, state, flowStateMtimeMs);
+  }
+  const ralphLoopLine = sessionDigest.ralphLoopLine;
+  const earlyLoopLine = sessionDigest.earlyLoopLine;
+  const compoundReadinessLine = sessionDigest.compoundReadinessLine;
+
   const ironLawsObj = toObject(await readJsonFile(ironLawsFile, {})) || {};
   const laws = Array.isArray(ironLawsObj.laws) ? ironLawsObj.laws : [];
   const ironLawLines = laws
@@ -8723,6 +8849,15 @@ async function handleSessionStart(runtime) {
     });
   const staleStages = toObject(state.raw.staleStages) || {};
   const staleStageNames = Object.keys(staleStages);
+  const interactionHints = toObject(state.raw.interactionHints) || {};
+  const stageInteractionHint = toObject(interactionHints[state.currentStage]);
+  const skipQuestionsHintActive = stageInteractionHint?.skipQuestions === true;
+  const skipQuestionsSource = typeof stageInteractionHint?.sourceStage === "string"
+    ? stageInteractionHint.sourceStage
+    : "";
+  const skipQuestionsRecordedAt = typeof stageInteractionHint?.recordedAt === "string"
+    ? stageInteractionHint.recordedAt
+    : "";
   const metaContent = (await readTextFile(metaSkillFile, "")).trim();
   const stageSupportContext = await readStageSupportContext(runtime.root, state.currentStage);
 
@@ -8755,6 +8890,14 @@ async function handleSessionStart(runtime) {
         " (use npx cclaw-cli internal rewind --ack <stage> after redo)."
     );
   }
+  if (skipQuestionsHintActive) {
+    parts.push(
+      "Adaptive elicitation hint: this stage inherits a prior user stop signal (--skip-questions" +
+        (skipQuestionsSource ? " from " + skipQuestionsSource : "") +
+        (skipQuestionsRecordedAt ? " at " + skipQuestionsRecordedAt : "") +
+        "). Draft with available context unless irreversible/security override checks still require explicit confirmation."
+    );
+  }
   if (knowledge.digestLines.length > 0) {
     parts.push(
       "Knowledge digest (top relevant entries):\\n" +
@@ -8867,10 +9010,6 @@ async function handleStopHandoff(runtime) {
   return 0;
 }
 
-async function handlePreCompact(_runtime) {
-  return 0;
-}
-
 async function handlePromptGuard(runtime) {
   const mode = resolveStrictness();
   const stateDir = path.join(runtime.root, RUNTIME_ROOT, "state");
@@ -9372,15 +9511,38 @@ async function handleVerifyCurrentState(runtime) {
   return 0;
 }
 
+async function handlePreToolPipeline(runtime) {
+  const promptExitCode = await handlePromptGuard(runtime);
+  if (promptExitCode !== 0) {
+    return promptExitCode;
+  }
+  return await handleWorkflowGuard(runtime);
+}
+
+async function handlePromptPipeline(runtime) {
+  const promptExitCode = await handlePromptGuard(runtime);
+  if (promptExitCode !== 0) {
+    return promptExitCode;
+  }
+  const verifyExitCode = await handleVerifyCurrentState(runtime);
+  if (verifyExitCode !== 0) {
+    return verifyExitCode;
+  }
+  runtime.writeJson({ ok: true });
+  return 0;
+}
+
 function normalizeHookName(rawName) {
   const value = normalizeText(rawName).toLowerCase();
   if (value === "session-start") return "session-start";
+  if (value === "session-start-refresh") return "session-start-refresh";
   if (value === "stop-handoff" || value === "stop") return "stop-handoff";
   if (value === "stop-checkpoint") return "stop-handoff";
-  if (value === "pre-compact" || value === "precompact") return "pre-compact";
   if (value === "session-rehydrate") return "session-start";
   if (value === "prompt-guard") return "prompt-guard";
   if (value === "workflow-guard") return "workflow-guard";
+  if (value === "pre-tool-pipeline" || value === "pretool-pipeline") return "pre-tool-pipeline";
+  if (value === "prompt-pipeline" || value === "promptpipeline") return "prompt-pipeline";
   if (value === "context-monitor") return "context-monitor";
   if (value === "verify-current-state") return "verify-current-state";
   return "";
@@ -9392,7 +9554,7 @@ async function main() {
     process.stderr.write(
       "[cclaw] run-hook: usage: node " +
         RUNTIME_ROOT +
-        "/hooks/run-hook.mjs <session-start|stop-handoff|pre-compact|prompt-guard|workflow-guard|context-monitor|verify-current-state>\\n"
+        "/hooks/run-hook.mjs <session-start|session-start-refresh|stop-handoff|prompt-guard|workflow-guard|pre-tool-pipeline|prompt-pipeline|context-monitor|verify-current-state>\\n"
     );
     process.exitCode = 1;
     return;
@@ -9424,12 +9586,12 @@ async function main() {
       process.exitCode = await handleSessionStart(runtime);
       return;
     }
-    if (hookName === "stop-handoff") {
-      process.exitCode = await handleStopHandoff(runtime);
+    if (hookName === "session-start-refresh") {
+      process.exitCode = await handleSessionStartRefresh(runtime);
       return;
     }
-    if (hookName === "pre-compact") {
-      process.exitCode = await handlePreCompact(runtime);
+    if (hookName === "stop-handoff") {
+      process.exitCode = await handleStopHandoff(runtime);
       return;
     }
     if (hookName === "prompt-guard") {
@@ -9440,6 +9602,14 @@ async function main() {
       process.exitCode = await handleWorkflowGuard(runtime);
       return;
     }
+    if (hookName === "pre-tool-pipeline") {
+      process.exitCode = await handlePreToolPipeline(runtime);
+      return;
+    }
+    if (hookName === "prompt-pipeline") {
+      process.exitCode = await handlePromptPipeline(runtime);
+      return;
+    }
     if (hookName === "context-monitor") {
       process.exitCode = await handleContextMonitor(runtime);
       return;

package/dist/track-heuristics.d.ts

@@ -1,4 +1,4 @@
-import type { FlowTrack, TrackHeuristicRule, TrackHeuristicsConfig } from "./types.js";
+import type { FlowStage, FlowTrack, TrackHeuristicRule, TrackHeuristicsConfig } from "./types.js";
 export interface TrackResolution {
     track: FlowTrack;
     reason: string;
@@ -6,6 +6,11 @@ export interface TrackResolution {
     confidence: "high" | "medium" | "low";
     overrideGuidance: string;
 }
+export interface QuestionBudgetHint {
+    min: number;
+    recommended: number;
+    hardCapWarning: number;
+}
 /**
  * Reference implementation of the track classifier the /cc skill prose
  * describes. Tests pin its behavior so the built-in defaults stay honest.
@@ -14,6 +19,7 @@ export interface TrackResolution {
  * "advisory" language.
  */
 export declare function resolveTrackFromPrompt(prompt: string, config: TrackHeuristicsConfig | undefined): TrackResolution;
+export declare function questionBudgetHint(track: FlowTrack, stage: FlowStage): QuestionBudgetHint;
 export declare const TRACK_HEURISTICS_DEFAULTS: {
     readonly fallback: "standard";
     readonly evaluationOrder: readonly ("quick" | "medium" | "standard")[];

package/dist/track-heuristics.js

@@ -54,6 +54,12 @@ const DEFAULT_RULES = {
 // into runtime, so cclaw stopped offering the knob in v0.38.0.
 const EVALUATION_ORDER = ["standard", "medium", "quick"];
 const DEFAULT_FALLBACK = "standard";
+const ADAPTIVE_ELICITATION_STAGES = new Set(["brainstorm", "scope", "design"]);
+const QUESTION_BUDGET_HINTS_BY_TRACK = {
+    quick: { min: 2, recommended: 3, hardCapWarning: 4 },
+    medium: { min: 5, recommended: 6, hardCapWarning: 8 },
+    standard: { min: 10, recommended: 12, hardCapWarning: 14 }
+};
 function hasToken(promptLower, token) {
     return promptLower.includes(token.toLowerCase());
 }
@@ -130,6 +136,12 @@ export function resolveTrackFromPrompt(prompt, config) {
         overrideGuidance: "Confirm or override before state is written; choose quick only for known low-blast-radius work, medium for known architecture with product framing, standard for uncertainty."
     };
 }
+export function questionBudgetHint(track, stage) {
+    if (!ADAPTIVE_ELICITATION_STAGES.has(stage)) {
+        return { min: 0, recommended: 0, hardCapWarning: 0 };
+    }
+    return QUESTION_BUDGET_HINTS_BY_TRACK[track];
+}
 export const TRACK_HEURISTICS_DEFAULTS = {
     fallback: DEFAULT_FALLBACK,
     evaluationOrder: EVALUATION_ORDER,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {