claude-recall 0.31.0 → 0.33.0

package/README.md

@@ -92,6 +92,8 @@ tail -5 ~/.claude-recall/hook-logs/cc-classifier.log   # which model ran, what w
 claude-recall search "something you said"
 ```
 
+Design details (the `claude -p` key-precedence gotcha, recursion guards, which features run on the subscription): [docs/cc-llm-capture.md](docs/cc-llm-capture.md).
+
 ### Pi
 
 ```bash
@@ -169,7 +171,7 @@ Once installed, Claude Recall works in the background (CC = Claude Code):
 | **Session exit** | An auto-checkpoint (`{completed, remaining, blockers}`) is saved for next time | ✓ | ✓ |  |
 | **End of session** | Failure patterns become candidate lessons; validated ones are promoted to rules | ✓ | ✓ |  |
 
-Classification runs on each runtime's **own** LLM — Claude Code via headless `claude -p` on your subscription; Kiro via `kiro-cli chat --no-interactive` on Kiro credits — with `ANTHROPIC_API_KEY` (if you exported one *and* opted in) and regex as fallbacks. No API key is ever required; no configuration needed.
+Classification runs on each runtime's **own** LLM — Claude Code via headless `claude -p` on your subscription; Kiro via `kiro-cli chat --no-interactive` on Kiro credits — with regex as the fallback. **An exported `ANTHROPIC_API_KEY` is never touched** unless you explicitly opt in with `CLAUDE_RECALL_PREFER_API_KEY=1`. No API key is ever required; no configuration needed.
 
 ```bash
 # Verify it's working
@@ -206,7 +208,7 @@ claude-recall checkpoint save --completed "API layer" --remaining "wire the UI"
 claude-recall checkpoint load
 ```
 
-Auto-checkpoints are also saved on session exit in Claude Code and Pi (Pi has no `--resume`, so this is its main recovery path). Extraction uses Haiku via `ANTHROPIC_API_KEY`; without a key, only manual checkpoints work. A quality gate refuses to overwrite a manual checkpoint with a fabricated one when the task was already complete.
+Auto-checkpoints are also saved on session exit in Claude Code and Pi (Pi has no `--resume`, so this is its main recovery path). Extraction runs on your **Claude subscription** (headless `claude -p`) — like capture, no API key needed and no key touched. The same applies to the other background LLM features (failure hindsight hints, end-of-session lesson extraction). Pi-only machines without the `claude` binary can opt in to an `ANTHROPIC_API_KEY` with `CLAUDE_RECALL_PREFER_API_KEY=1`. A quality gate refuses to overwrite a manual checkpoint with a fabricated one when the task was already complete.
 
 ### Troubleshooting
 
@@ -387,11 +389,11 @@ Defaults work out of the box; tune via environment variables as needed.
 | Variable                                 | Default | Effect                                                                                                   |
 | ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
 | `CLAUDE_RECALL_DB_PATH`                  | `~/.claude-recall/` | Database directory.                                                                          |
-| `ANTHROPIC_API_KEY`                      | _(unset)_ | Optional personal API key for Haiku-based classification. **Never required and never provided by Claude Code** — capture uses each runtime's own LLM first (Claude subscription via `claude -p`; Kiro credits via `kiro-cli`). A key you exported is only consulted as a fallback, or first with `CLAUDE_RECALL_PREFER_API_KEY=1`. Regex is the final fallback. |
+| `ANTHROPIC_API_KEY`                      | _(unset)_ | Optional personal API key for Haiku-based LLM features. **Never required, never provided by Claude Code, and never touched unless you opt in** with `CLAUDE_RECALL_PREFER_API_KEY=1` — capture, checkpoint extraction, hindsight hints, and session lessons all run on each runtime's own LLM (Claude subscription via `claude -p`; Kiro credits via `kiro-cli`), with regex as the fallback. |
 | `CLAUDE_RECALL_CC_MODEL`                 | `haiku` | Dedicated model for capture classification under Claude Code (passed to `claude -p --model`) — independent of your interactive session model. |
 | `CLAUDE_RECALL_CC_LLM_TIMEOUT_MS`        | `30000` | Hard cap on the headless `claude -p` classify call before the capture worker gives up and falls through. |
 | `CLAUDE_RECALL_KIRO_MODEL`               | `claude-haiku-4.5` | Dedicated model for Kiro-LLM capture classification — **independent of your interactive Kiro chat model**. Raise to `claude-sonnet-4.6` for steadier judgement at more credits. See [docs/kiro-llm-capture.md](docs/kiro-llm-capture.md). |
-| `CLAUDE_RECALL_PREFER_API_KEY`           | _(unset)_ | Force `ANTHROPIC_API_KEY`-based classification ahead of the runtime's included LLM (uses your Anthropic API credits — e.g. for a model you pay for). Applies under both Claude Code and Kiro. |
+| `CLAUDE_RECALL_PREFER_API_KEY`           | _(unset)_ | **The only switch that enables the `ANTHROPIC_API_KEY` backend** (and prefers it first). For Pi-only machines without the `claude` binary, or a stronger model you deliberately pay for. Applies to all LLM features, under Claude Code, Kiro, and Pi. |
 | `CLAUDE_RECALL_KIRO_LLM_TIMEOUT_MS`      | `30000` | Hard cap on the headless `kiro-cli` classify call before the capture worker gives up and falls back to regex. |
 | `CLAUDE_RECALL_LOAD_BUDGET_TOKENS`       | `2000`  | Token budget for the `load_rules` payload. Rules are emitted in priority order (corrections → preferences by citation → devops by citation → failures) and dropped rules surface via `search_memory`. |
 | `CLAUDE_RECALL_AUTO_DEMOTE`              | `false` | When `true`, auto-demote rules on MCP boot where `load_count >= CLAUDE_RECALL_DEMOTE_MIN_LOADS`, `cite_count = 0`, and age `> CLAUDE_RECALL_DEMOTE_MIN_AGE_DAYS`. Still reversible via `rules promote <id>`. |

package/dist/hooks/cc-capture.js

@@ -30,7 +30,9 @@ async function handleCcCapture(input) {
     // Recursion guard: if we're already inside a classifier's nested headless
     // session (claude -p or kiro-cli fired hooks of its own), do NOT spawn
     // another worker — that would classify the classify prompt, forever.
-    if (process.env.CLAUDE_RECALL_CC_CLASSIFIER || process.env.CLAUDE_RECALL_KIRO_CLASSIFIER) {
+    if (process.env.CLAUDE_RECALL_NESTED
+        || process.env.CLAUDE_RECALL_CC_CLASSIFIER
+        || process.env.CLAUDE_RECALL_KIRO_CLASSIFIER) {
         return;
     }
     const prompt = input?.prompt ?? '';

package/dist/hooks/cc-classifier.js

@@ -57,6 +57,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.completeWithClaudeCli = completeWithClaudeCli;
 exports.classifyWithClaudeCli = classifyWithClaudeCli;
 const child_process_1 = require("child_process");
 const os = __importStar(require("os"));
@@ -65,18 +66,28 @@ const kiro_classifier_1 = require("./kiro-classifier");
 const DEFAULT_MODEL = 'haiku';
 const DEFAULT_TIMEOUT_MS = 30000;
 /**
- * Classify a prompt by invoking Claude Code's headless mode. Returns null on
- * any failure (claude not on PATH, timeout, non-zero exit, unparseable output)
- * so the caller falls back to the next backend. Never throws.
+ * Run one headless `claude -p` completion on the user's Claude SUBSCRIPTION
+ * and return raw stdout, or null on any failure (claude not on PATH, timeout,
+ * non-zero exit). Never throws. This is the generic primitive: capture
+ * classification wraps it below, and llm-classifier routes its secondary
+ * features (hindsight hints, session extraction, checkpoint extraction,
+ * batch classification) through it so none of them require an API key either.
  */
-function classifyWithClaudeCli(text) {
+function completeWithClaudeCli(prompt, opts = {}) {
     const model = process.env.CLAUDE_RECALL_CC_MODEL || DEFAULT_MODEL;
-    const timeoutMs = parseInt(process.env.CLAUDE_RECALL_CC_LLM_TIMEOUT_MS || '', 10);
-    const timeout = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS;
+    const envTimeout = parseInt(process.env.CLAUDE_RECALL_CC_LLM_TIMEOUT_MS || '', 10);
+    const timeout = opts.timeoutMs
+        ?? (Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : DEFAULT_TIMEOUT_MS);
     // Force subscription auth: with ANTHROPIC_API_KEY set, `claude -p` bills the
-    // key instead of the login — the exact behavior this classifier exists to
-    // avoid. CLAUDE_RECALL_CC_CLASSIFIER rides along as the recursion guard.
-    const env = { ...process.env, CLAUDE_RECALL_CC_CLASSIFIER: '1' };
+    // key instead of the login — the exact behavior this backend exists to
+    // avoid. CLAUDE_RECALL_NESTED marks the child as a nested headless session
+    // (every CLI-backend consumer checks it before spawning — recursion guard);
+    // CLAUDE_RECALL_CC_CLASSIFIER rides along for the capture-hook guard too.
+    const env = {
+        ...process.env,
+        CLAUDE_RECALL_CC_CLASSIFIER: '1',
+        CLAUDE_RECALL_NESTED: '1',
+    };
     delete env.ANTHROPIC_API_KEY;
     return new Promise((resolve) => {
         let settled = false;
@@ -91,7 +102,7 @@ function classifyWithClaudeCli(text) {
             // args array (no shell) — the user's text is a single argv entry, so no
             // shell escaping or injection is possible. cwd is the temp dir so the
             // nested session loads no project settings or hooks.
-            child = (0, child_process_1.spawn)('claude', ['-p', '--model', model, (0, kiro_classifier_1.buildClassifyPrompt)(text)], { cwd: os.tmpdir(), env, stdio: ['ignore', 'pipe', 'ignore'] });
+            child = (0, child_process_1.spawn)('claude', ['-p', '--model', model, prompt], { cwd: os.tmpdir(), env, stdio: ['ignore', 'pipe', 'ignore'] });
         }
         catch (err) {
             (0, shared_1.hookLog)('cc-classifier', `spawn threw: ${(0, shared_1.safeErrorMessage)(err)}`);
@@ -121,22 +132,34 @@ function classifyWithClaudeCli(text) {
                 (0, shared_1.hookLog)('cc-classifier', `claude -p exited ${code}`);
                 return done(null);
             }
-            const result = (0, kiro_classifier_1.extractClassification)(stdout);
-            if (!result) {
-                // Distinguish a deliberate "none" verdict from unparseable output —
-                // "the model said not a rule" and "the call broke" are different
-                // diagnoses when reading the log.
-                (0, shared_1.hookLog)('cc-classifier', /"type"\s*:\s*"none"/.test(stdout)
-                    ? 'classified as none (not a durable rule)'
-                    : 'no parseable classification in claude -p output');
-            }
-            else {
-                // Same observability contract as kiro-classifier: spell out which
-                // backend ran and on whose account, so "which LLM classified this?"
-                // is always answerable from the log.
-                (0, shared_1.hookLog)('cc-classifier', `classified via claude -p (model=${model}, Claude subscription, no API key): ${result.type} — ${result.extract.slice(0, 60)}`);
-            }
-            done(result);
+            done(stdout);
         });
     });
 }
+/**
+ * Classify a prompt by invoking Claude Code's headless mode. Returns null on
+ * any failure (claude not on PATH, timeout, non-zero exit, unparseable output)
+ * so the caller falls back to the next backend. Never throws.
+ */
+async function classifyWithClaudeCli(text) {
+    const model = process.env.CLAUDE_RECALL_CC_MODEL || DEFAULT_MODEL;
+    const stdout = await completeWithClaudeCli((0, kiro_classifier_1.buildClassifyPrompt)(text));
+    if (stdout === null)
+        return null;
+    const result = (0, kiro_classifier_1.extractClassification)(stdout);
+    if (!result) {
+        // Distinguish a deliberate "none" verdict from unparseable output —
+        // "the model said not a rule" and "the call broke" are different
+        // diagnoses when reading the log.
+        (0, shared_1.hookLog)('cc-classifier', /"type"\s*:\s*"none"/.test(stdout)
+            ? 'classified as none (not a durable rule)'
+            : 'no parseable classification in claude -p output');
+    }
+    else {
+        // Same observability contract as kiro-classifier: spell out which
+        // backend ran and on whose account, so "which LLM classified this?"
+        // is always answerable from the log.
+        (0, shared_1.hookLog)('cc-classifier', `classified via claude -p (model=${model}, Claude subscription, no API key): ${result.type} — ${result.extract.slice(0, 60)}`);
+    }
+    return result;
+}

package/dist/hooks/llm-classifier.js

@@ -5,10 +5,10 @@
  * Requires ANTHROPIC_API_KEY in the environment — a personal pay-as-you-go
  * API key the user exported themselves. Claude Code does NOT mint one from
  * the user's subscription (hooks just inherit the user's environment), which
- * is why this is a FALLBACK backend: the capture workers prefer each
- * runtime's included LLM (claude -p / kiro-cli — see cc-classifier.ts and
- * kiro-classifier.ts) and only land here when a key is present. Falls back
- * gracefully (returns null) when unavailable.
+ * is why this backend is STRICTLY OPT-IN (CLAUDE_RECALL_PREFER_API_KEY): the
+ * default chains use each runtime's included LLM only (claude -p / kiro-cli —
+ * see cc-classifier.ts and kiro-classifier.ts), and an exported key is never
+ * spent silently. Falls back gracefully (returns null) when unavailable.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyWithLLM = classifyWithLLM;
@@ -16,9 +16,17 @@ exports.extractHindsightHint = extractHindsightHint;
 exports.extractSessionLearningsWithLLM = extractSessionLearningsWithLLM;
 exports.extractCheckpointWithLLM = extractCheckpointWithLLM;
 exports.classifyBatchWithLLM = classifyBatchWithLLM;
+const cc_classifier_1 = require("./cc-classifier");
 // Lazy singleton — avoid import cost when API key is absent
 let clientInstance; // undefined = not yet checked
 const MODEL = 'claude-haiku-4-5-20251001';
+/**
+ * Per-call cap for `claude -p` in these SECONDARY features. Unlike capture
+ * (detached worker, 30s budget), hindsight hints / session extraction / batch
+ * classification run INLINE in the Stop hook (~40s total budget, possibly
+ * several calls) — a hung CLI must not eat the whole hook.
+ */
+const SECONDARY_CLI_TIMEOUT_MS = 10000;
 const SYSTEM_PROMPT = `You are a memory classifier for a developer tool. Classify user text into one of these types:
 
 - correction: User durably correcting how something should ALWAYS be done ("no, use X not Y", "wrong, it should be..."). Correcting a one-off action in the current task is NOT durable — only store it if the rule generalizes beyond this moment.
@@ -113,11 +121,75 @@ function getClient() {
     }
 }
 /**
- * Parse a JSON response, stripping markdown fences if present.
+ * Parse a JSON response, stripping markdown fences if present. Falls back to
+ * slicing the first balanced-looking JSON region — `claude -p` occasionally
+ * wraps output in prose or a trailing fence the strict strip misses.
  */
 function parseJSON(text) {
     const cleaned = text.trim().replace(/^```(?:json)?\s*/, '').replace(/\s*```$/, '');
-    return JSON.parse(cleaned);
+    try {
+        return JSON.parse(cleaned);
+    }
+    catch (err) {
+        const starts = [cleaned.indexOf('{'), cleaned.indexOf('[')].filter((i) => i !== -1);
+        if (starts.length === 0)
+            throw err;
+        const start = Math.min(...starts);
+        const end = Math.max(cleaned.lastIndexOf('}'), cleaned.lastIndexOf(']'));
+        if (end <= start)
+            throw err;
+        return JSON.parse(cleaned.slice(start, end + 1));
+    }
+}
+/**
+ * Run one completion for the SECONDARY LLM features (hindsight hints, session
+ * extraction, checkpoint extraction, batch classification) and return raw
+ * text, or null when no backend is available.
+ *
+ * Backend policy matches capture: the user's Claude SUBSCRIPTION (headless
+ * `claude -p`) is the only default backend — a personally-exported
+ * ANTHROPIC_API_KEY is STRICTLY OPT-IN via CLAUDE_RECALL_PREFER_API_KEY and
+ * never consulted otherwise, not even as a fallback. The opt-in exists for
+ * Pi-only users (no `claude` binary; their key is how they run Pi itself)
+ * and anyone deliberately paying for a stronger model.
+ *
+ * The CLI backend is skipped inside a nested headless session
+ * (CLAUDE_RECALL_NESTED): if `claude -p` fires user-scope hooks of its own,
+ * those hooks must not spawn further `claude -p` calls.
+ */
+async function completeText(systemPrompt, userContent, maxTokens) {
+    const viaApi = async () => {
+        const client = getClient();
+        if (!client)
+            return null;
+        try {
+            const response = await client.messages.create({
+                model: MODEL,
+                max_tokens: maxTokens,
+                system: systemPrompt,
+                messages: [{ role: 'user', content: userContent }],
+            });
+            const content = response.content?.[0];
+            return content?.type === 'text' ? content.text : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // `claude -p` takes a single argument (no system-prompt channel), so
+    // instruction and payload are combined — same shape as the Kiro backend.
+    const viaCli = () => process.env.CLAUDE_RECALL_NESTED
+        ? Promise.resolve(null)
+        : (0, cc_classifier_1.completeWithClaudeCli)(`${systemPrompt}\n\n${userContent}`, { timeoutMs: SECONDARY_CLI_TIMEOUT_MS });
+    const backends = process.env.CLAUDE_RECALL_PREFER_API_KEY
+        ? [viaApi, viaCli]
+        : [viaCli];
+    for (const backend of backends) {
+        const text = await backend();
+        if (text !== null && text.trim().length > 0)
+            return text;
+    }
+    return null;
 }
 /**
  * Classify a single text using Claude Haiku.
@@ -159,20 +231,11 @@ async function classifyWithLLM(text) {
  * callers fall back to grounding the detector's generic remedy text.
  */
 async function extractHindsightHint(failureDescription, context) {
-    const client = getClient();
-    if (!client)
+    const text = await completeText('You extract actionable hindsight lessons from failures. Given a failure description and context, produce a JSON object with: hint_text (imperative rule to prevent recurrence), hint_kind (one of: rule, preference, anti_pattern, workflow, debug_fix, failure_preventer), applies_when (array of 1-3 situation tags). Respond with ONLY valid JSON.', `Failure: ${failureDescription}\nContext: ${context}`, 300);
+    if (!text)
         return null;
     try {
-        const response = await client.messages.create({
-            model: MODEL,
-            max_tokens: 300,
-            system: 'You extract actionable hindsight lessons from failures. Given a failure description and context, produce a JSON object with: hint_text (imperative rule to prevent recurrence), hint_kind (one of: rule, preference, anti_pattern, workflow, debug_fix, failure_preventer), applies_when (array of 1-3 situation tags). Respond with ONLY valid JSON.',
-            messages: [{ role: 'user', content: `Failure: ${failureDescription}\nContext: ${context}` }],
-        });
-        const content = response.content?.[0];
-        if (content?.type !== 'text')
-            return null;
-        const result = parseJSON(content.text);
+        const result = parseJSON(text);
         if (!result.hint_text || !result.hint_kind)
             return null;
         return {
@@ -220,24 +283,15 @@ Return [] if nothing durable was learned. Max 10 items. Each content should be a
  * Returns null if no API key or on any failure.
  */
 async function extractSessionLearningsWithLLM(summary, existingMemories) {
-    const client = getClient();
-    if (!client)
+    const memList = existingMemories.length > 0
+        ? existingMemories.map(m => `- ${m}`).join('\n')
+        : '(none)';
+    const systemPrompt = SESSION_EXTRACTION_PROMPT + `\n\nEXISTING MEMORIES (do not duplicate):\n${memList}`;
+    const text = await completeText(systemPrompt, summary, 1000);
+    if (!text)
         return null;
     try {
-        const memList = existingMemories.length > 0
-            ? existingMemories.map(m => `- ${m}`).join('\n')
-            : '(none)';
-        const systemPrompt = SESSION_EXTRACTION_PROMPT + `\n\nEXISTING MEMORIES (do not duplicate):\n${memList}`;
-        const response = await client.messages.create({
-            model: MODEL,
-            max_tokens: 1000,
-            system: systemPrompt,
-            messages: [{ role: 'user', content: summary }],
-        });
-        const content = response.content?.[0];
-        if (content?.type !== 'text')
-            return null;
-        const results = parseJSON(content.text);
+        const results = parseJSON(text);
         if (!Array.isArray(results))
             return null;
         const validTypes = ['project-knowledge', 'preference', 'devops', 'failure'];
@@ -304,23 +358,14 @@ Examples of BAD output (DO NOT DO THIS):
 {"completed":"explored architecture","remaining":"document findings","blockers":"none"} # FABRICATED — there was no documentation task
 {"completed":"finished everything","remaining":"finish everything","blockers":"none"}   # nonsense filler`;
 async function extractCheckpointWithLLM(conversationSummary) {
-    const client = getClient();
-    if (!client)
-        return null;
     if (!conversationSummary || conversationSummary.trim().length < 30) {
         return null;
     }
+    const text = await completeText(CHECKPOINT_EXTRACTION_PROMPT, conversationSummary, 600);
+    if (!text)
+        return null;
     try {
-        const response = await client.messages.create({
-            model: MODEL,
-            max_tokens: 600,
-            system: CHECKPOINT_EXTRACTION_PROMPT,
-            messages: [{ role: 'user', content: conversationSummary }],
-        });
-        const content = response.content?.[0];
-        if (content?.type !== 'text')
-            return null;
-        const result = parseJSON(content.text);
+        const result = parseJSON(text);
         if (typeof result !== 'object' || result === null)
             return null;
         return {
@@ -336,25 +381,16 @@ async function extractCheckpointWithLLM(conversationSummary) {
 async function classifyBatchWithLLM(texts) {
     if (texts.length === 0)
         return [];
-    const client = getClient();
-    if (!client)
+    // JSON array, not delimiter-joined text: a user message that happened to
+    // contain the old "---ITEM---" marker desynced item counts and silently
+    // dropped the entire batch to the regex fallback. JSON boundaries can't
+    // be forged by content.
+    const joined = JSON.stringify(texts);
+    const text = await completeText(BATCH_SYSTEM_PROMPT, joined, texts.length * 200);
+    if (!text)
         return null;
     try {
-        // JSON array, not delimiter-joined text: a user message that happened to
-        // contain the old "---ITEM---" marker desynced item counts and silently
-        // dropped the entire batch to the regex fallback. JSON boundaries can't
-        // be forged by content.
-        const joined = JSON.stringify(texts);
-        const response = await client.messages.create({
-            model: MODEL,
-            max_tokens: texts.length * 200,
-            system: BATCH_SYSTEM_PROMPT,
-            messages: [{ role: 'user', content: joined }],
-        });
-        const content = response.content?.[0];
-        if (content?.type !== 'text')
-            return null;
-        const results = parseJSON(content.text);
+        const results = parseJSON(text);
         if (!Array.isArray(results) || results.length !== texts.length)
             return null;
         return results.map((r) => {

package/dist/hooks/memory-stop-hook.js

@@ -448,13 +448,17 @@ const VALID_LESSON_KINDS = new Set([
 async function generateCandidateLessons(failures, episodeId, projectId) {
     try {
         const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
+        // Each hint is an LLM call (via the subscription CLI it can take seconds),
+        // and this loop runs INLINE in the Stop hook's ~40s budget — cap the LLM
+        // calls per run; failures past the cap keep the grounded generic lesson.
+        let hintBudget = 5;
         for (const f of failures) {
             if (f.confidence < 0.7)
                 continue;
             let lessonText = `${f.content.what_should_do} (failure: ${f.content.what_failed})`;
             let lessonKind = 'failure_preventer';
             let appliesWhen = extractTagsFromContext(f.content.context);
-            const hint = await (0, llm_classifier_1.extractHindsightHint)(`${f.content.what_failed}${f.content.why_failed ? ` — ${f.content.why_failed}` : ''}`, f.content.context || '');
+            const hint = hintBudget-- > 0 ? await (0, llm_classifier_1.extractHindsightHint)(`${f.content.what_failed}${f.content.why_failed ? ` — ${f.content.why_failed}` : ''}`, f.content.context || '') : null;
             if (hint) {
                 lessonText = hint.hint_text;
                 if (VALID_LESSON_KINDS.has(hint.hint_kind)) {

package/dist/hooks/shared.js

@@ -166,18 +166,17 @@ function classifyContentRegex(text) {
  * workers, which set the *_CLASSIFIER env vars — a ~4s CLI call can't run
  * inline on a turn):
  *   - Under Claude Code (CLAUDE_RECALL_CC_CLASSIFIER set by cc-capture-worker):
- *     headless `claude -p` on the user's Claude SUBSCRIPTION → ANTHROPIC_API_KEY
- *     if present → regex.
+ *     headless `claude -p` on the user's Claude SUBSCRIPTION → regex.
  *   - Under Kiro (CLAUDE_RECALL_KIRO_CLASSIFIER set by kiro-capture-worker):
  *     Kiro's own headless LLM (`kiro-cli chat --no-interactive`, Kiro credits)
- *     → ANTHROPIC_API_KEY if present → regex.
- *   - Inline callers (memory-stop batch, etc.): ANTHROPIC_API_KEY → regex.
+ *     → regex.
+ *   - Inline callers: straight to regex.
  *
- * The included LLM is preferred so a stray exported key doesn't silently
- * spend the user's Anthropic API credits; CLAUDE_RECALL_PREFER_API_KEY flips
- * the order. NOTE: ANTHROPIC_API_KEY is always a personal key the user
- * exported — Claude Code does NOT provide one from the subscription.
- * See docs/kiro-llm-capture.md.
+ * The ANTHROPIC_API_KEY path is STRICTLY OPT-IN via
+ * CLAUDE_RECALL_PREFER_API_KEY — an exported key is never consulted
+ * otherwise, not even as a fallback. (It is always a personal key the user
+ * exported — Claude Code does NOT provide one from the subscription.)
+ * See docs/cc-llm-capture.md and docs/kiro-llm-capture.md.
  */
 async function classifyContent(text) {
     // Guard the LLM paths the same way the regex path is guarded: a question or
@@ -202,30 +201,25 @@ async function classifyContentInner(text) {
     // module graph for hook invocations that don't run in a capture worker.
     const tryKiro = async () => (await Promise.resolve().then(() => __importStar(require('./kiro-classifier')))).classifyWithKiro(text);
     const tryCc = async () => (await Promise.resolve().then(() => __importStar(require('./cc-classifier')))).classifyWithClaudeCli(text);
-    // Order the LLM backends. Each runtime's INCLUDED LLM comes before a stray
-    // ANTHROPIC_API_KEY: a key exported for other tools should not silently
-    // spend the user's Anthropic API credits when the runtime already provides
-    // an LLM — Kiro via `kiro-cli chat --no-interactive` (Kiro credits), Claude
-    // Code via `claude -p` (the user's Claude subscription). Set
-    // CLAUDE_RECALL_PREFER_API_KEY to force the key first (e.g. to use a
-    // stronger model you pay for). The CLI backends only run inside their
-    // detached capture workers (which set the *_CLASSIFIER env vars) — inline
-    // hook paths stay key → regex, since a ~4s CLI call can't block a turn.
+    // Pick the LLM backends. The ANTHROPIC_API_KEY path is STRICTLY OPT-IN
+    // (CLAUDE_RECALL_PREFER_API_KEY): claude-recall was built for runtimes that
+    // bring their own LLM — Kiro via `kiro-cli chat --no-interactive` (Kiro
+    // credits), Claude Code via `claude -p` (the user's Claude subscription) —
+    // and a key exported for other tools must NEVER be spent silently, not even
+    // as a fallback. Without the opt-in, the chain is included LLM → regex.
+    // The opt-in exists for Pi-only users (no `claude` binary; their key is how
+    // they run Pi itself) and anyone deliberately paying for a stronger model.
+    // The CLI backends only run inside their detached capture workers (which
+    // set the *_CLASSIFIER env vars) — inline hook paths go straight to regex,
+    // since a ~4s CLI call can't block a turn.
     const backends = [];
-    if (underKiro && !preferApiKey) {
-        backends.push(tryKiro, tryApiKey);
-    }
-    else if (underKiro) {
-        backends.push(tryApiKey, tryKiro);
-    }
-    else if (underCc && !preferApiKey) {
-        backends.push(tryCc, tryApiKey);
+    if (preferApiKey)
+        backends.push(tryApiKey);
+    if (underKiro) {
+        backends.push(tryKiro);
     }
     else if (underCc) {
-        backends.push(tryApiKey, tryCc);
-    }
-    else {
-        backends.push(tryApiKey);
+        backends.push(tryCc);
     }
     for (const backend of backends) {
         const result = await backend();

package/docs/cc-llm-capture.md

@@ -0,0 +1,147 @@
+# Using your Claude subscription for memory capture (no API key)
+
+The Claude Code counterpart to [kiro-llm-capture.md](kiro-llm-capture.md): how
+claude-recall's LLM features run on the user's **Claude subscription** — the
+same login that powers their interactive session — instead of a personal
+`ANTHROPIC_API_KEY`.
+
+## The problem
+
+Claude Recall's LLM classifier originally called Claude Haiku through the
+Anthropic SDK, which needs `ANTHROPIC_API_KEY` — a **personal pay-as-you-go
+key**. For a long time the docs claimed Claude Code "provides the key to its
+hooks." That was false: Claude Code does not mint a key from the user's
+subscription; hooks merely inherit the user's environment. So the key path
+only ever worked for users who had exported their own key, and it silently
+spent **their API credits** — a separate wallet from the Claude subscription
+they were already paying for.
+
+The failure mode that exposed all of this: a user's exported key ran out of
+credits. Every SDK call failed silently, capture degraded to the regex
+fallback, and the regex promptly stored four junk memories in one session —
+while the user reasonably believed "the LLM" was doing the classifying.
+
+## The finding
+
+**`claude -p "<prompt>"` is a headless one-shot completion that runs on the
+user's Claude Code login** — the direct analogue of the earlier
+`kiro-cli chat --no-interactive` discovery. A background worker can shell out
+to it to classify text with no API key and no extra cost beyond the
+subscription usage the user already has.
+
+One gotcha made this non-trivial, and it's the most important line in the
+implementation:
+
+> **`claude -p` prefers `ANTHROPIC_API_KEY` over subscription auth when the
+> key is present in the environment.**
+
+So a stray exported key — possibly dead, possibly billing a wallet the user
+forgot about — would silently hijack every headless call. The fix:
+`completeWithClaudeCli()` **strips `ANTHROPIC_API_KEY` from the child env**,
+forcing subscription auth unconditionally. (Verified live: with a
+credits-exhausted key in the env, `claude -p` returned
+`Credit balance is too low`; with the key stripped, the same call succeeded on
+the login.)
+
+## The design
+
+```
+Claude Code UserPromptSubmit
+        │
+        ▼
+  hook run correction-detector      (name unchanged in settings.json;
+        │                            returns in <100 ms)
+        │  spawn detached, pipe payload via stdin
+        ▼
+  hook run cc-capture-worker        (background, survives parent exit)
+        │  sets CLAUDE_RECALL_CC_CLASSIFIER=1
+        ▼
+  handleCorrectionDetector → classifyContent()
+        │
+        ├─ classifyWithClaudeCli()  → claude -p --model haiku "<prompt>"
+        │                             (subscription auth, key stripped)
+        └─ regex fallback
+
+  (classifyWithLLM() / ANTHROPIC_API_KEY exists but is OPT-IN only —
+   see below; it is never in the default chain)
+```
+
+Precedence mirrors Kiro: **the runtime's included LLM → regex.** An exported
+`ANTHROPIC_API_KEY` is **never consulted by default — not even as a
+fallback**; `CLAUDE_RECALL_PREFER_API_KEY=1` is the one switch that enables
+(and prefers) it. The registered hook name (`hook run correction-detector`)
+was deliberately kept, so existing `settings.json` files work with no
+re-setup — only the dispatch behind it changed.
+
+**Trade-off:** the synchronous `📌 Recall: auto-captured …` echo is gone.
+A cold `claude -p` takes ~4 s, far too slow to block the user's prompt, so
+capture is silent and lands a few seconds later — the same contract Kiro has
+always had. Verify via `~/.claude-recall/hook-logs/cc-classifier.log`
+(`classified via claude -p (model=…, Claude subscription, no API key)`) or
+`claude-recall search`.
+
+### Recursion guard
+
+The nested headless session is itself a Claude Code session. If the user has
+claude-recall hooks registered at **user scope** (`~/.claude/settings.json`),
+the classify call would fire those hooks, which would spawn another worker,
+which would run another `claude -p` — forever. Two layers prevent this:
+
+1. `claude -p` children run with `cwd = os.tmpdir()`, so **project**
+   settings/hooks never load.
+2. Children are marked with `CLAUDE_RECALL_NESTED=1` (plus the legacy
+   `CLAUDE_RECALL_CC_CLASSIFIER=1`). The capture hook refuses to spawn a
+   worker, and the secondary-feature backend refuses to invoke the CLI, when
+   either marker is present.
+
+### Beyond capture: the secondary features (0.32.0)
+
+`completeWithClaudeCli()` is a generic completion primitive, and the four
+features that previously knew only the key path now route through it with the
+same precedence:
+
+| Feature | Runs in | Without any key, now |
+| --- | --- | --- |
+| Auto-checkpoint extraction | Session-exit worker (CC + **Pi** — Pi's only recovery path, it has no `--resume`) | Works via `claude -p` |
+| Failure hindsight hints | Stop hook, inline | Works via `claude -p` |
+| End-of-session lesson extraction | Stop hook, inline | Works via `claude -p` |
+| Batch classification | Stop hook, inline | Works via `claude -p` |
+
+Two budget rules keep the inline ones inside the Stop hook's ~40 s window
+(capture doesn't need them — it runs in a detached worker):
+
+- each secondary CLI call is capped at **10 s** (vs the worker's 30 s), and
+- hindsight-hint generation is capped at **5 LLM calls per run** (the loop
+  over detected failures is otherwise unbounded; failures past the cap keep
+  the grounded generic lesson text).
+
+Under **Pi** these functions run in-process, so Pi benefits automatically on
+any machine with the `claude` binary installed alongside. Under **Kiro** the
+Stop-hook features mostly don't run (no transcript in its hooks), and capture
+uses the Kiro backend.
+
+### Configuration
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `CLAUDE_RECALL_CC_MODEL` | `haiku` | Model passed to `claude -p --model` — a dedicated classifier model, independent of the user's interactive session model. |
+| `CLAUDE_RECALL_CC_LLM_TIMEOUT_MS` | `30000` | Hard cap on the capture worker's `claude -p` call. (Secondary features use a fixed 10 s per call.) |
+| `CLAUDE_RECALL_PREFER_API_KEY` | *(unset)* | **The only switch that enables the `ANTHROPIC_API_KEY` backend** (and prefers it first) — without it an exported key is never touched, not even as a fallback. For Pi-only machines without the `claude` binary, or a stronger model you deliberately pay for. Applies to capture and the secondary features, on every runtime. |
+| `CLAUDE_RECALL_NESTED` | *(set on `claude -p` children)* | Recursion marker — never set it by hand. |
+
+## Caveats
+
+- **Requires the `claude` binary on `PATH`.** Absent (e.g. a bare CI box, or a
+  Pi-only machine), the CLI backend errors out and the chain falls through to
+  regex — or to an `ANTHROPIC_API_KEY` if you opted in with
+  `CLAUDE_RECALL_PREFER_API_KEY=1`. No crash, no exception.
+- **Subscription usage.** Each classified prompt is one small Haiku call
+  against the user's Claude plan limits. That is the deliberate trade — the
+  user's existing plan instead of a second wallet.
+- **Latency.** ~4 s cold per call. Fine in a detached worker; the reason the
+  inline features carry the 10 s cap and hint budget.
+- **Consistency.** Same probabilistic caveat as the Kiro backend: the
+  classifier is an LLM judgement call. The classify prompt carries a
+  "standalone rule" test with negative examples precisely because early
+  versions stored one-off task instructions ("first fix the sentence") as
+  corrections.

package/docs/kiro-llm-capture.md

@@ -9,7 +9,7 @@ Claude Haiku through `ANTHROPIC_API_KEY` — a personal API key the user had
 exported themselves. (Claude Code does **not** mint a key from the user's
 subscription; hooks merely inherit the environment. The headless-CLI approach
 documented here was later applied back to Claude Code via `claude -p` on
-subscription auth — see `src/hooks/cc-classifier.ts`.)
+subscription auth — see [cc-llm-capture.md](cc-llm-capture.md).)
 
 Kiro CLI does **not** set `ANTHROPIC_API_KEY`. So under Kiro the classifier fell
 back to a conservative regex that only fires on explicit phrasings
@@ -89,20 +89,24 @@ Kiro userPromptSubmit
         ▼
   handleCorrectionDetector → classifyContent()
         │
-        ├─ classifyWithLLM()   → ANTHROPIC_API_KEY (unset under Kiro) → null
         ├─ classifyWithKiro()  → kiro-cli chat --no-interactive --agent
         │                         claude-recall-classifier --model claude-haiku-4.5
         │                         → {"type","confidence","extract"}
-        └─ regex fallback       (only if both above yield nothing)
+        └─ regex fallback       (only if the above yields nothing)
+
+  (classifyWithLLM() / ANTHROPIC_API_KEY exists but is OPT-IN only —
+   never in the default chain)
 ```
 
-Capture precedence under Kiro: **Kiro's included LLM → `ANTHROPIC_API_KEY` if
-present → regex as a last resort.** The Kiro LLM comes first *even when a key is
-set*, so a key exported for other tools never silently spends the user's
-Anthropic credits — Kiro already ships an LLM. `CLAUDE_RECALL_PREFER_API_KEY=1`
-flips the order back to key-first for anyone who deliberately wants to pay for a
-stronger model. (Under Claude Code the same pattern applies with `claude -p` on
-the user's subscription as the included LLM — see `src/hooks/cc-classifier.ts`.)
+Capture precedence under Kiro: **Kiro's included LLM → regex as a last
+resort.** An exported `ANTHROPIC_API_KEY` is **never consulted by default —
+not even as a fallback** — so a key exported for other tools never silently
+spends the user's Anthropic credits; Kiro already ships an LLM.
+`CLAUDE_RECALL_PREFER_API_KEY=1` is the one explicit switch that enables (and
+prefers) the key, for anyone who deliberately wants to pay for a stronger
+model. (Under Claude Code the same pattern applies with `claude -p` on the
+user's subscription as the included LLM — see
+[cc-llm-capture.md](cc-llm-capture.md).)
 
 ### Output parsing
 
@@ -119,7 +123,7 @@ returns `null`, degrading to regex — a hook must never throw.
 | `CLAUDE_RECALL_KIRO_CLASSIFIER` | *(set by the worker)* | Enables the Kiro-LLM path in `classifyContent`. Set automatically by `kiro-capture-worker`; never needed by hand. |
 | `CLAUDE_RECALL_KIRO_MODEL` | `claude-haiku-4.5` | Model for the classify call, passed explicitly as `--model`. This is a **dedicated classifier model, independent of the user's interactive Kiro chat model** (e.g. `auto`) — the headless call always uses this value. Raise to `claude-sonnet-4.6` for steadier judgement at ~3× the credits. |
 | `CLAUDE_RECALL_KIRO_LLM_TIMEOUT_MS` | `30000` | Hard cap on the headless call before the worker gives up and falls back to regex. |
-| `CLAUDE_RECALL_PREFER_API_KEY` | *(unset)* | Force `ANTHROPIC_API_KEY`-based classification ahead of Kiro's included LLM (opt-in; uses your Anthropic credits). |
+| `CLAUDE_RECALL_PREFER_API_KEY` | *(unset)* | **The only switch that enables the `ANTHROPIC_API_KEY` backend** — without it an exported key is never touched, not even as a fallback. |
 
 ## Caveats
 

package/docs/kiro.md

@@ -74,7 +74,7 @@ To decide what's worth remembering, the capture hook classifies each prompt via
 
 **The classifier uses a dedicated, fixed model — not your chat model.** It always runs the model in `CLAUDE_RECALL_KIRO_MODEL` (default `claude-haiku-4.5`, chosen because classification is cheap and high-volume), **independent of your interactive Kiro chat model** (e.g. `auto`). This keeps classification cost predictable no matter what your chat is set to. Set `CLAUDE_RECALL_KIRO_MODEL` to any model from `kiro-cli chat --list-models` to change it. Every successful classification is logged to `~/.claude-recall/hook-logs/kiro-classifier.log` as `classified via kiro-cli (model=…, Kiro credits, no API key)`, so you can always see which model ran.
 
-**Under Kiro the included LLM is used first even if you happen to have `ANTHROPIC_API_KEY` set** — so a key exported for other tools won't quietly spend your Anthropic credits. Order: Kiro's LLM → `ANTHROPIC_API_KEY` (if present) → regex; set `CLAUDE_RECALL_PREFER_API_KEY=1` to force your key first (e.g. for a stronger model you pay for).
+**An exported `ANTHROPIC_API_KEY` is never touched** — a key exported for other tools won't quietly spend your Anthropic credits, not even as a fallback. Order: Kiro's LLM → regex. Setting `CLAUDE_RECALL_PREFER_API_KEY=1` is the one explicit switch that enables (and prefers) your key, e.g. for a stronger model you pay for.
 
 Design details, latency measurements, and output-parsing internals: [kiro-llm-capture.md](kiro-llm-capture.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-recall",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Persistent memory for Claude Code and Pi with native Skills integration, automatic capture, failure learning, and project scoping",
   "main": "dist/index.js",
   "bin": {