fix(continuous-learning): deliver v1 Stop nudge via native Stop contract behind explicit opt-in

The v1 evaluator computed the learning signal but wrote it to stderr, which Claude Code never forwards to the model, so the learned-skills folder was never populated through this path.

Delivery now follows the maintainer-endorsed shape: an explicit stop_nudge_opt_in flag (default off, so existing installs are unchanged), the native Stop block contract (decision block plus reason) instead of plain stdout text, at most one delivery per session via a temp-dir marker, Stop-loop protection via stop_hook_active, and delivery only for sessions with a registered lease from SessionStart.

Tests: 7 new evaluator tests (opt-in off, no lease, one valid block then silence on repeat, stop_hook_active, short session, non-Stop event, missing session id). Evaluator suite 23/23 with the fix, failing on pristine; hooks suite 260/260; Stop stdout contract suite 48/48.

Limits stated plainly: end-to-end delivery in a live Claude Code session is not certified from this host (unit-level spawn plus parse only), and the fix ships inert by default until a user opts in.
This commit is contained in:
Muhammad Mirza Kurniawan committed 2026-10-31 22:40:13 +07:00
1 parent b38be6a7f6
commit f82eb1414b
5 files changed
+362 -6

No files matched your search

+107 -4
View File
@@ -19,8 +19,23 @@ const {
ensureDir,
readFile,
countInFile,
log
getTempDir,
log,
output
} = require('../lib/utils');
const { resolveHookSessionId } = require('../lib/hook-session');
const {
resolveProjectContext,
getAliasContexts,
listSessionLeases,
resolveSessionId
} = require('../lib/observer-sessions');
// Marker that records a delivered Stop nudge, one per session, in the OS
// temp dir (same per-session temp-file pattern as suggest-compact's
// counters). A marker is what makes delivery once-per-session: a later
// user stop in the same session must not block again.
const DELIVERY_MARKER_PREFIX = 'claude-continuous-learning-delivered-';
// Read hook input from stdin (Claude Code provides transcript_path via stdin JSON)
const MAX_STDIN = 1024 * 1024;
@@ -42,10 +57,12 @@ process.stdin.on('end', () => {
});
async function main() {
// Parse stdin JSON to get transcript_path
// Parse stdin JSON once; the parsed payload is reused by the delivery
// gates below (event name, stop_hook_active, cwd).
let input = null;
let transcriptPath = null;
try {
const input = JSON.parse(stdinData);
input = JSON.parse(stdinData);
transcriptPath = input.transcript_path;
} catch {
// Fallback: try env var for backwards compatibility
@@ -59,6 +76,10 @@ async function main() {
// Default configuration
let minSessionLength = 10;
let learnedSkillsPath = getLearnedSkillsDir();
// Delivery to the model is explicitly opt-in and off by default: a Stop
// hook that blocks the stop is user-visible behavior, so it must never
// turn on silently.
let stopNudgeOptIn = false;
// Load config if exists
const configContent = readFile(configFile);
@@ -66,6 +87,7 @@ async function main() {
try {
const config = JSON.parse(configContent);
minSessionLength = config.min_session_length ?? 10;
stopNudgeOptIn = config.stop_nudge_opt_in === true;
if (config.learned_skills_path) {
// Handle ~ in path
@@ -92,9 +114,90 @@ async function main() {
process.exit(0);
}
// Signal to Claude that session should be evaluated for extractable patterns
// Signal to Claude that session should be evaluated for extractable patterns.
// The log lines below go to stderr (the debug log) only. Whether the
// model ever sees the signal is decided by deliverStopNudge, which fails
// closed: any gate miss means stderr only, exit 0, no stdout.
log(`[ContinuousLearning] Session has ${messageCount} messages - evaluate for extractable patterns`);
log(`[ContinuousLearning] Save learned skills to: ${learnedSkillsPath}`);
deliverStopNudge({ input, stdinData, messageCount, learnedSkillsPath, stopNudgeOptIn });
process.exit(0);
}
/**
* Deliver the evaluation signal to the model, or deliver nothing.
*
* A Stop hook reaches the model only through the native Stop contract:
* decision "block" + reason, which continues the turn with the reason as
* context. Plain stdout text is not a delivery channel on Stop, so nothing
* else is ever written to stdout here. Every gate fails closed.
*/
function deliverStopNudge({ input, stdinData, messageCount, learnedSkillsPath, stopNudgeOptIn }) {
if (!stopNudgeOptIn) {
log('[ContinuousLearning] Stop nudge opt-in is off, skipping delivery');
return;
}
// A payload that names a different event means this script is running
// under the wrong registration; an absent field is tolerated (older
// harnesses omit it), a mismatched one is not.
if (input && input.hook_event_name && input.hook_event_name !== 'Stop') {
log(`[ContinuousLearning] Skipping delivery: hook event is ${input.hook_event_name}, not Stop`);
return;
}
// Stop-loop protection: when a previous Stop already continued this stop,
// the hook is re-firing and must pass through, never block again.
if (input && input.stop_hook_active === true) {
log('[ContinuousLearning] Skipping delivery: Stop hook already fired for this stop');
return;
}
// The payload session id identifies the harness conversation; env ids are
// only fallbacks, never preferred over it.
const sessionId = resolveSessionId(resolveHookSessionId(stdinData));
if (!sessionId) {
log('[ContinuousLearning] Skipping delivery: no session id available');
return;
}
if (!hasRegisteredSessionLease(input, sessionId)) {
log('[ContinuousLearning] Skipping delivery: no SessionStart lease for this session');
return;
}
const markerFile = path.join(getTempDir(), `${DELIVERY_MARKER_PREFIX}${sessionId}`);
if (fs.existsSync(markerFile)) {
log('[ContinuousLearning] Stop nudge already delivered for this session, skipping');
return;
}
try {
fs.writeFileSync(markerFile, `${new Date().toISOString()}\n`);
} catch (err) {
// The re-fired Stop (stop_hook_active) still bounds repeats to one extra
// turn, so deliver anyway rather than silently dropping the nudge.
log(`[ContinuousLearning] Warning: could not record delivery marker: ${err.message}`);
}
output({
decision: 'block',
reason: `[ContinuousLearning] Session has ${messageCount} messages - evaluate for extractable patterns. Save learned skills to: ${learnedSkillsPath}`
});
}
/**
* The registered-native-lifecycle check: the session must hold a lease
* written by SessionStart under the ECC project context (including alias
* contexts for roots that moved mid-session). A Stop payload for a session
* that never went through SessionStart is not a registered ECC session,
* and its nudge must not reach the model.
*/
function hasRegisteredSessionLease(input, sessionId) {
try {
const cwd = (input && typeof input.cwd === 'string' && input.cwd) || process.cwd();
const context = resolveProjectContext(cwd);
const contexts = [context, ...getAliasContexts(context)];
return contexts.some(ctx =>
listSessionLeases(ctx).some(file => path.basename(file) === `${sessionId}.json`)
);
} catch (err) {
log(`[ContinuousLearning] Session lease check failed: ${err.message}`);
return false;
}
}