eklavya 1.14.0 → 1.16.0

package/dist/hooks/prompt-submit-nudge.js

@@ -0,0 +1,155 @@
+/**
+ * UserPromptSubmit: say the standing instruction again, once, when a session
+ * has plainly stopped hearing it.
+ *
+ * `session-start.ts` injects the directive that starts the whole loop -- call
+ * `log_session_concepts` with what this task exercises -- and its own comment
+ * explains why it lives in a hook rather than only in the tutor skill: the skill
+ * is model-invocable, it competes with every other skill on the machine, and it
+ * may never load. The same argument applies one level up. A directive injected
+ * once is the oldest thing in the context window by turn forty, competing with
+ * everything that arrived after it.
+ *
+ * That failure is the worst-shaped one Eklavya has, because nothing errors.
+ * Nothing gets logged, so `session_concepts` stays empty, so the Stop hook finds
+ * no candidates and exits silently. From the outside it reads as *Eklavya is
+ * broken* -- which is unreportable, and the reason both comparable plugins
+ * (ponytail, claude-mem) re-inject on every prompt rather than once per session.
+ *
+ * Where this deliberately differs from them: they re-emit their whole ruleset
+ * every turn. This emits ONE line, and only when it has been earned. A hook that
+ * spends tokens on every prompt to repeat something the model is already doing
+ * is a hook that makes every session more expensive to no end -- and a nudge
+ * that arrives while logging is working teaches the model to ignore nudges.
+ *
+ * So the predicate is narrow, and it is the one case worth catching: this
+ * session has logged **nothing at all**, and it has been going long enough that
+ * the session-start directive can no longer be blamed on not having had a chance.
+ * A session that logged once and then went quiet for a while is *not* nudged --
+ * concepts are logged per task and a task can legitimately run long, so that
+ * signal is noise.
+ *
+ * State lives in `meta` rather than a table of its own: one row per session,
+ * `prompt_nudge:<sid>` -> `<first-seen>|<last-nudge>|<count>`, pipe-delimited so
+ * the prune below is one statement and needs no JSON parsing in SQL. A
+ * migration for a rate limiter would be a schema change for a comment.
+ * `session-start` deletes the row when it reprints the directive, which is what
+ * re-arms the grace window on a resume or after a compaction.
+ *
+ * Failure is silent, as everywhere here: exit 0, no output. This runs on every
+ * prompt the developer types, so it is also the hook with the least right to be
+ * slow -- the common case (a session that is logging) is one COUNT and out.
+ */
+import { run, openExisting, config, cwdOf, sessionId, minutesSince, NUDGE_KEY_PREFIX, } from './lib.js';
+/**
+ * Long enough that the session-start directive has had a fair chance, short
+ * enough to still be the same piece of work. Not configurable on purpose: a
+ * knob for this would be a config key, a schema entry, a CLI line and four doc
+ * updates to tune something nobody can feel.
+ */
+const GRACE_MINUTES = 12;
+/** And having said it once, do not say it again this soon. */
+const COOLDOWN_MINUTES = 25;
+/**
+ * And having said it three times, stop.
+ *
+ * The cooldown alone is not a bound. "This session has logged nothing at all"
+ * is not only the signature of a model that forgot the directive -- it is also
+ * exactly what a dead MCP server looks like from here, and that state never
+ * resolves. Without a cap an eight-hour session against an unreachable server
+ * gets nineteen injections telling the model to call a tool that is not
+ * registered, each one likely drawing a visible failure in the transcript.
+ *
+ * `max_stop_blocks_per_session` is the same kind of backstop for the Stop hook,
+ * for the same reason. A constant rather than a config key: the difference
+ * between three nudges and four is not something anyone needs to tune.
+ */
+const MAX_NUDGES = 3;
+/**
+ * `<first-seen ISO>|<last-nudge ISO or empty>|<nudges so far>`
+ *
+ * The count was appended rather than inserted, so a row written by the previous
+ * shape reads back as count 0 instead of throwing. It buys such a row at most
+ * MAX_NUDGES extra nudges, once, which is cheaper than a migration.
+ */
+function readState(db, key) {
+    const row = db.prepare('SELECT value FROM meta WHERE key = ?').get(key);
+    if (!row)
+        return null;
+    const [first, nudged, count] = row.value.split('|');
+    if (!first)
+        return null;
+    return { first, nudged: nudged || null, count: Number(count) || 0 };
+}
+function writeState(db, key, first, nudged, count) {
+    db.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, `${first}|${nudged ?? ''}|${count}`);
+}
+/**
+ * One row per session would otherwise be one row per session forever. The value
+ * starts with an ISO date, which compares lexicographically, so a week's cutoff
+ * is a substring comparison rather than a parse.
+ */
+function prune(db) {
+    db.prepare(`DELETE FROM meta
+      WHERE key LIKE ?
+        AND substr(value, 1, 10) < date('now', '-7 day')`).run(`${NUDGE_KEY_PREFIX}%`);
+}
+await run(async (input) => {
+    // A subagent's prompts are not the developer's, and the parent is the thread
+    // that logs. Nudging here would spend context inside a transcript nobody is
+    // reading. Same reasoning as checkpoint-quiz.ts.
+    if (input.agent_id)
+        return 0;
+    // Config before the database, unlike the other hooks: this one runs on every
+    // prompt the developer types, so a dormant or quiet session should not pay to
+    // open SQLite before finding out it had nothing to do. Reading one or two
+    // small JSON files is the cheaper question, so it is asked first.
+    const { mode } = config(cwdOf(input)).config;
+    if (mode === 'off')
+        return 0;
+    // `quiet` is deliberately NOT consulted. It suppresses the banner and the
+    // status bar -- things the developer looks at -- and this is an
+    // additionalContext line the model reads, exactly like the session-start
+    // directive it restates. Honouring it here used to be defended as consistency
+    // with that directive, which was itself being dropped under `quiet`: between
+    // them they turned a preference about greetings into a silent off switch.
+    // `mode: off` is the off switch.
+    const db = openExisting();
+    if (!db)
+        return 0;
+    const sid = sessionId(input, db);
+    if (!sid)
+        return 0;
+    // The fast path, and the one that runs on almost every prompt: a session that
+    // is logging needs nothing said to it.
+    const logged = db
+        .prepare('SELECT count(*) AS n FROM session_concepts WHERE session_id = ?')
+        .get(sid);
+    if ((logged?.n ?? 0) > 0)
+        return 0;
+    const key = `${NUDGE_KEY_PREFIX}${sid}`;
+    const now = new Date().toISOString();
+    const state = readState(db, key);
+    // First prompt we have seen for this session. The directive was injected
+    // seconds ago; repeating it now would be noise. Start the clock instead.
+    if (!state) {
+        prune(db);
+        writeState(db, key, now, null, 0);
+        return 0;
+    }
+    if (state.count >= MAX_NUDGES)
+        return 0;
+    if (minutesSince(state.first) < GRACE_MINUTES)
+        return 0;
+    if (state.nudged && minutesSince(state.nudged) < COOLDOWN_MINUTES)
+        return 0;
+    writeState(db, key, state.first, now, state.count + 1);
+    process.stdout.write(`${JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'UserPromptSubmit',
+            additionalContext: '[Eklavya] Nothing logged this session. Once you know what the current task involves, call log_session_concepts with the 3-8 concepts it genuinely exercises, each with a context line naming the real code — without it there is nothing to quiz on.',
+        },
+    })}\n`);
+    return 0;
+});
+//# sourceMappingURL=prompt-submit-nudge.js.map

package/dist/hooks/prompt-submit-nudge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-submit-nudge.js","sourceRoot":"","sources":["../../src/hooks/prompt-submit-nudge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EACL,GAAG,EACH,YAAY,EACZ,MAAM,EACN,KAAK,EACL,SAAS,EACT,YAAY,EACZ,gBAAgB,GAEjB,MAAM,UAAU,CAAC;AAElB;;;;;GAKG;AACH,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,8DAA8D;AAC9D,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAE5B;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,GAAG,CAAC,CAAC;AAErB;;;;;;GAMG;AACH,SAAS,SAAS,CAAC,EAAM,EAAE,GAAW;IACpC,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,sCAAsC,CAAC,CAAC,GAAG,CAAC,GAAG,CAEzD,CAAC;IACd,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;AACtE,CAAC;AAED,SAAS,UAAU,CAAC,EAAM,EAAE,GAAW,EAAE,KAAa,EAAE,MAAqB,EAAE,KAAa;IAC1F,EAAE,CAAC,OAAO,CAAC,mGAAmG,CAAC,CAAC,GAAG,CACjH,GAAG,EACH,GAAG,KAAK,IAAI,MAAM,IAAI,EAAE,IAAI,KAAK,EAAE,CACpC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,KAAK,CAAC,EAAM;IACnB,EAAE,CAAC,OAAO,CACR;;yDAEqD,CACtD,CAAC,GAAG,CAAC,GAAG,gBAAgB,GAAG,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;IACxB,6EAA6E;IAC7E,4EAA4E;IAC5E,iDAAiD;IACjD,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,CAAC,CAAC;IAE7B,6EAA6E;IAC7E,8EAA8E;IAC9E,0EAA0E;IAC1E,kEAAkE;IAClE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IAC7C,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,CAAC,CAAC;IAC7B,0EAA0E;IAC1E,gEAAgE;IAChE,yEAAyE;IACzE,8EAA8E;IAC9E,6EAA6E;IAC7E,0EAA0E;IAC1E,iCAAiC;IAEjC,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,CAAC;IAElB,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACjC,IAAI,CAAC,GAAG;QAAE,OAAO,CAAC,CAAC;IAEnB,8EAA8E;IAC9E,uCAAuC;IACvC,MAAM,MAAM,GAAG,EAAE;SACd,OAAO,CAAC,iEAAiE,CAAC;SAC1E,GAAG,CAAC,GAAG,CAA8B,CAAC;IACzC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IAEnC,MAAM,GAAG,GAAG,GAAG,gBAAgB,GAAG,GAAG,EAAE,CAAC;IACxC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAEjC,yEAAyE;IACzE,yEAAyE;IACzE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,CAAC,EAAE,CAAC,CAAC;QACV,UAAU,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAClC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,KAAK,CAAC,KAAK,IAAI,UAAU;QAAE,OAAO,CAAC,CAAC;IACxC,IAAI,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,aAAa;QAAE,OAAO,CAAC,CAAC;IACxD,IAAI,KAAK,CAAC,MAAM,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,gBAAgB;QAAE,OAAO,CAAC,CAAC;IAE5E,UAAU,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAEvD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CAAC;QAChB,kBAAkB,EAAE;YAClB,aAAa,EAAE,kBAAkB;YACjC,iBAAiB,EACf,sPAAsP;SACzP;KACF,CAAC,IAAI,CACP,CAAC;IACF,OAAO,CAAC,CAAC;AACX,CAAC,CAAC,CAAC"}

package/dist/hooks/session-start.js

@@ -6,7 +6,7 @@
  */
 import { setCurrentSession } from '../session.js';
 import { levelStanding } from '../store.js';
-import { run, openExisting, config, cwdOf, sessionId } from './lib.js';
+import { run, openExisting, config, cwdOf, sessionId, clearNudgeState } from './lib.js';
 /**
  * The whole tutoring loop starts at log_session_concepts: it is the only writer
  * of session_concepts, and the Stop hook quizzes from nothing else. An unlogged
@@ -94,15 +94,36 @@ await run(async (input) => {
     // `levelStanding` is the server's own function, so the banner cannot drift
     // from what the quiz planner actually does — the shell version reimplemented
     // this query and had to keep it in step by hand.
-    let levelLabel = `${difficulty} (pinned)`;
-    if (difficulty === 'auto') {
-        const standing = levelStanding(db, resolved.config, resolved.repoRoot);
-        levelLabel = `${standing.level} (${standing.counts.passed}/${standing.needed.answers} on this project)`;
+    const out = [];
+    // `quiet` suppresses the banner, and only the banner. It used to return here,
+    // which also dropped the directive below -- so a developer who turned the
+    // greeting off silently turned the whole product off: nothing was logged, so
+    // the Stop hook found no candidates, so no question was ever asked, while
+    // `get_config` went on reporting `mode: ambient`. The manual has always said
+    // this key "suppresses the session-start banner and the statusline output",
+    // and `mode: off` is the documented way to stop Eklavya doing anything.
+    if (!quiet) {
+        let levelLabel = `${difficulty} (pinned)`;
+        if (difficulty === 'auto') {
+            const standing = levelStanding(db, resolved.config, resolved.repoRoot);
+            levelLabel = `${standing.level} (${standing.counts.passed}/${standing.needed.answers} on this project)`;
+        }
+        banner(db, out, { mode, focusLabel, cadence, levelLabel, overrides: resolved.overrides });
     }
-    if (quiet)
-        return 0;
+    // The directive is on screen again, so the nudge's clock starts again. This
+    // hook fires on resume and after a compaction, not only at startup, and both
+    // reuse the session id -- without this the first prompt of a resumed session
+    // restates what was printed seconds ago.
+    if (sid)
+        clearNudgeState(db, sid);
+    out.push(DIRECTIVE);
+    process.stdout.write(`${out.join('\n')}\n`);
+    return 0;
+});
+/** The developer-facing greeting. Everything `quiet` is about. */
+function banner(db, out, parts) {
+    const { mode, focusLabel, cadence, levelLabel, overrides } = parts;
     const domains = domainSummary(db);
-    const out = [];
     if (!domains) {
         // Nothing learned yet — say the useful thing instead of an empty scoreboard.
         out.push(`[Eklavya] No learning history yet. Mode: ${mode}. Focus: ${focusLabel}. Cadence: ${cadence}. Level: ${levelLabel}.`);
@@ -117,11 +138,8 @@ await run(async (input) => {
             line += ` ${due} concept(s) due for review.`;
         out.push(`${line} Mode: ${mode}. Focus: ${focusLabel}. Cadence: ${cadence}. Level: ${levelLabel}.`);
     }
-    if (resolved.overrides.length > 0) {
-        out.push(`[Eklavya] This repo overrides your global setting for: ${resolved.overrides.join(' ')} (.eklavya.json wins).`);
+    if (overrides.length > 0) {
+        out.push(`[Eklavya] This repo overrides your global setting for: ${overrides.join(' ')} (.eklavya.json wins).`);
     }
-    out.push(DIRECTIVE);
-    process.stdout.write(`${out.join('\n')}\n`);
-    return 0;
-});
+}
 //# sourceMappingURL=session-start.js.map

package/dist/hooks/session-start.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-start.js","sourceRoot":"","sources":["../../src/hooks/session-start.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-start.js","sourceRoot":"","sources":["../../src/hooks/session-start.ts"],"names":[],"mappings":"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"}

package/dist/hooks/stop-quiz-check.js

@@ -27,6 +27,16 @@
  */
 import { run, openExisting, config, cwdOf, sessionId, minutesSince, framingFor } from './lib.js';
 await run(async (input) => {
+    // Same fast path as checkpoint-quiz.ts, and for a stronger reason: this hook
+    // blocks with exit 2. `Stop` is believed to be parent-only -- `SubagentStop`
+    // is a separate event -- but nothing in this repo has verified that, and the
+    // cost of being wrong is a subagent told to run a quiz it has no
+    // AskUserQuestion to ask, in a transcript nobody reads, up to
+    // max_stop_blocks_per_session times. subagent-start.ts is what made that
+    // reachable: before it, a subagent logged nothing, so the `logged > last_logged`
+    // predicate below could never arm.
+    if (input.agent_id)
+        return 0;
     const db = openExisting();
     if (!db)
         return 0;
@@ -158,12 +168,13 @@ Concepts: ${concepts}
 ${ask}
 
 Ask each question as MULTIPLE CHOICE via the AskUserQuestion tool: four options,
-one correct and three plausible, header "Eklavya" so it is clear who is asking.
+one correct and three plausible, the correct one in the slot answer_position
+names, header "Eklavya" so it is clear who is asking.
 The tool's own "Other" choice is the escape hatch for "I don't know". They are
 mid-task -- a blank prompt gets skipped whether or not they knew the answer.
 Ask the stem on its own. The dials that pitched it -- mode, focus, cadence,
-level -- are in the status bar, so never prepend a settings line to the
-question.
+level -- are in the status bar, so what you ask is the question and nothing
+else.
 Record with format "mcq", the labels in "options", and only the stem in
 "question".
 ${framing}

package/dist/hooks/stop-quiz-check.js.map

@@ -1 +1 @@
-{"version":3,"file":"stop-quiz-check.js","sourceRoot":"","sources":["../../src/hooks/stop-quiz-check.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stop-quiz-check.js","sourceRoot":"","sources":["../../src/hooks/stop-quiz-check.ts"],"names":[],"mappings":"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"}

package/dist/hooks/subagent-start.js

@@ -0,0 +1,87 @@
+/**
+ * SubagentStart: tell a delegated agent to log the concepts it exercises.
+ *
+ * `SessionStart` fires once, in the parent thread, and its standing directive
+ * never reaches a subagent — a subagent opens with a fresh context and the
+ * agent file it was defined by. So the agent that most often knows what the
+ * code touched is the one agent never told to say so, and a session that
+ * delegates its implementation logs nothing at all. From the outside that is
+ * indistinguishable from Eklavya being broken: nothing is logged, so the Stop
+ * hook finds no candidates and exits without a word.
+ *
+ * Two things make this different from `session-start.ts` rather than a copy of
+ * it.
+ *
+ * **The output form.** `SessionStart` accepts raw stdout as context.
+ * `SubagentStart` does not — it needs the `hookSpecificOutput.additionalContext`
+ * JSON, and text printed here is dropped silently, which is the failure this
+ * comment exists to stop someone rediscovering.
+ *
+ * **Not every subagent should hear it.** `eklavya-tutor` (`agents/tutor.md`) is
+ * deliberately not given `log_session_concepts` — it teaches what the builder
+ * logged. Telling it to log would be an instruction to call a tool it does not
+ * have. `docs/subagent-policy.md` is the whole policy: who logs, who quizzes,
+ * who stays silent.
+ *
+ * Nothing here asks a question. A subagent has no `AskUserQuestion` and no
+ * audience, and `checkpoint-quiz.ts` already returns on `agent_id` for that
+ * reason; this hook must not undo it by asking for one in prose.
+ */
+import { run, config, cwdOf } from './lib.js';
+/**
+ * Two sentences, because a subagent's context is its whole budget and this is
+ * spent before it has read its task.
+ *
+ * `session_id` is not mentioned: `log_session_concepts` resolves it from
+ * `meta.current_session`, which `session-start.ts` stamped, so a subagent lands
+ * in the parent's session without being told how. Nor is there an "if the tool
+ * is available" hedge — `skills/CLAUDE.md` measured that shape of clause
+ * turning a reliable recipe into a noisy one, and the exemption that matters is
+ * the guard's job below, not a condition the model is invited to weigh.
+ */
+const DIRECTIVE = `[Eklavya] Call log_session_concepts once you know what this task involves — the 3-8 concepts the code genuinely exercises, each with a context line naming the real code you wrote.
+Do not ask the developer anything here: nobody is watching this transcript, and the parent session is what asks the questions.`;
+/**
+ * The tutor, whichever way it was installed.
+ *
+ * Not because it lacks `log_session_concepts` — so do `Explore` and `Plan`, and
+ * they are told anyway; a subagent without the tool simply does not call it.
+ * The harm is the *second* sentence. `agents/tutor.md` exists to quiz from
+ * inside a subagent (`docs/parallel-tutoring.md`, Option A), and "do not ask
+ * the developer anything here" is a direct order not to do the only thing it
+ * does. Delivering it silently disables parallel tutoring.
+ *
+ * Substring rather than equality: an agent is namespaced `<plugin>:<name>` when
+ * installed through `/plugin` and bare when it is a user-level agent, so both
+ * `eklavya-tutor` and `eklavya:eklavya-tutor` have to match.
+ */
+function isTutor(agentType) {
+    return typeof agentType === 'string' && agentType.includes('eklavya-tutor');
+}
+await run(async (input) => {
+    // No database read at all. Whether to speak depends only on `mode`, and a
+    // subagent may well be the first thing in a session to touch Eklavya — a hook
+    // that bailed on a missing database would stay silent on exactly the fresh
+    // install that most needs the directive. (`lib.js` still pulls in the SQLite
+    // driver at import, so this is one query fewer, not a free hook.)
+    if (config(cwdOf(input)).config.mode === 'off')
+        return 0;
+    // Fail OPEN on an absent or unrecognised agent_type: speak. A host that does
+    // not send the field is a host where failing closed would kill the feature
+    // silently — the failure this repo keeps rediscovering — while the cost of
+    // this direction is one tutor session that logs instead of quizzing, in a
+    // subagent the developer asked for by name and is watching for.
+    if (isTutor(input.agent_type))
+        return 0;
+    // `quiet` is not consulted, deliberately: it suppresses what the developer
+    // looks at — the banner and the status bar — and this is context the model
+    // reads. See hooks/CLAUDE.md, "`quiet` is not an off switch".
+    process.stdout.write(`${JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'SubagentStart',
+            additionalContext: DIRECTIVE,
+        },
+    })}\n`);
+    return 0;
+});
+//# sourceMappingURL=subagent-start.js.map

package/dist/hooks/subagent-start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-start.js","sourceRoot":"","sources":["../../src/hooks/subagent-start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,SAAS,GAAG;+HAC6G,CAAC;AAEhI;;;;;;;;;;;;;GAaG;AACH,SAAS,OAAO,CAAC,SAA6B;IAC5C,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;IACxB,0EAA0E;IAC1E,8EAA8E;IAC9E,2EAA2E;IAC3E,6EAA6E;IAC7E,kEAAkE;IAClE,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,KAAK;QAAE,OAAO,CAAC,CAAC;IAEzD,6EAA6E;IAC7E,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,gEAAgE;IAChE,IAAI,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC;QAAE,OAAO,CAAC,CAAC;IAExC,2EAA2E;IAC3E,2EAA2E;IAC3E,8DAA8D;IAC9D,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CAAC;QAChB,kBAAkB,EAAE;YAClB,aAAa,EAAE,eAAe;YAC9B,iBAAiB,EAAE,SAAS;SAC7B;KACF,CAAC,IAAI,CACP,CAAC;IACF,OAAO,CAAC,CAAC;AACX,CAAC,CAAC,CAAC"}

package/dist/packs.js

@@ -0,0 +1,177 @@
+/**
+ * Concept packs: the graph as data someone else can write.
+ *
+ * The shipped catalogue in `src/seed/` is already JSON rather than code, but it
+ * is *ours*: four graphs — git, node-backend, react, web-auth — and the only way
+ * to add a fifth was a pull request to this repository. Everything else a
+ * developer actually works in arrives only as whatever `upsert_concepts` minted
+ * mid-session. A pack is the same file shape, loaded from two places Eklavya
+ * does not own:
+ *
+ *   ~/.eklavya/packs/*.json        the learner's own, and anything installed
+ *   <repo>/.eklavya/packs/*.json   a team's, versioned with the codebase
+ *
+ * The second is the interesting one. A repository that ships its own concepts
+ * and prerequisites is describing itself to a new joiner, which is onboarding
+ * rather than quizzing.
+ *
+ * Packs are applied AFTER the seed and merged over it, so a pack may retier or
+ * rename a shipped concept, and a repo pack wins over a global one. Nothing
+ * here touches `mastery`: the seed's rule is the pack's rule, and a learner's
+ * history survives any pack being installed, edited or deleted.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { eklavyaHome } from './paths.js';
+import { findRepoConfig } from './config.js';
+import { applySeedGraph, validateSeedGraph, SEED_VERSION } from './seed.js';
+/**
+ * One row per set of pack directories, not one row for the install.
+ *
+ * The pack set depends on the working directory, so a single global row made
+ * two repositories fight over it: every `openDb()` in repo A saw repo B's hash,
+ * re-applied, and stored its own — a write on every CLI invocation for anyone
+ * with a repo pack and more than one project.
+ */
+export function packFingerprintKey(dirs) {
+    return `packs_fingerprint:${crypto.createHash('sha256').update(dirs.join('\n')).digest('hex').slice(0, 16)}`;
+}
+/**
+ * Global first, repo second, because later wins. `packs/` under both, so the
+ * rule is one sentence: packs live in a `packs/` directory next to Eklavya's
+ * state, whether that state is yours or the repository's.
+ */
+export function packDirs(cwd = process.cwd()) {
+    const dirs = [
+        { dir: path.join(eklavyaHome(), 'packs'), scope: 'global' },
+    ];
+    const { repoRoot } = findRepoConfig(cwd);
+    if (repoRoot)
+        dirs.push({ dir: path.join(repoRoot, '.eklavya', 'packs'), scope: 'repo' });
+    return dirs;
+}
+function listPackFiles(dir) {
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.json'))
+            .sort()
+            .map((f) => path.join(dir, f));
+    }
+    catch {
+        // A missing packs directory is the normal case, not an error.
+        return [];
+    }
+}
+/**
+ * Reads every pack, and never throws.
+ *
+ * A malformed pack must not take the database down with it: `openDb()` is on
+ * the path of every CLI command and the server's own start, so one bad file in
+ * `~/.eklavya/packs/` would otherwise make Eklavya unusable rather than making
+ * one pack unavailable. The error is carried on the result instead, and
+ * `eklavya doctor` is where a learner reads it.
+ */
+export function loadPacks(cwd = process.cwd()) {
+    const out = [];
+    for (const { dir, scope } of packDirs(cwd)) {
+        for (const file of listPackFiles(dir)) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (typeof parsed.pack !== 'string' || !parsed.pack) {
+                    throw new Error('missing "pack" — a pack has to say who it is, as a string');
+                }
+                // Edges may leave the file, unlike a seed graph's: a pack extending a
+                // shipped domain wants `prerequisite_of` pointing at a seeded concept.
+                // An endpoint naming nothing is dropped at apply time and counted, so a
+                // typo is visible in `doctor` rather than failing the whole pack.
+                validateSeedGraph(parsed, path.basename(file), { allowExternalEdges: true });
+                out.push({ file, scope, pack: parsed });
+            }
+            catch (err) {
+                out.push({ file, scope, error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Identity of the pack set as it is on disk right now.
+ *
+ * Path, size and mtime rather than content: applying packs is a write, and
+ * doing it on every `openDb()` would churn the WAL on every CLI invocation for
+ * a set of files that changes about never. Editing a pack changes its mtime and
+ * its size in almost every real case, and the one that slips through is fixed
+ * by the next edit or by `eklavya doctor`, which applies unconditionally.
+ */
+export function packFingerprint(files, seedVersion = SEED_VERSION) {
+    const h = crypto.createHash('sha256');
+    // The seed version is part of a pack's identity, because a re-seed upserts
+    // every shipped concept back to its shipped tier and undoes whatever a pack
+    // had merged over it. Folding it in here means a bumped SEED_VERSION marks
+    // EVERY scope stale, so each repository re-applies its own packs the next
+    // time it is opened — not only the one the learner happened to be in when
+    // the re-seed ran.
+    h.update(`seed:${seedVersion}\n`);
+    for (const file of files) {
+        let stat = null;
+        try {
+            stat = fs.statSync(file);
+        }
+        catch {
+            /* raced with a delete; the path alone still changes the hash */
+        }
+        h.update(`${file}:${stat?.size ?? -1}:${stat?.mtimeMs ?? -1}\n`);
+    }
+    return h.digest('hex');
+}
+/** Applies every readable pack, global then repo, so the repo's wins. */
+export function applyPacks(db, cwd = process.cwd()) {
+    return applyLoaded(db, loadPacks(cwd), packDirs(cwd).map((d) => d.dir));
+}
+function applyLoaded(db, loaded, dirs) {
+    const summary = { applied: 0, concepts: 0, edges: 0, edgesDropped: 0, errors: [] };
+    for (const entry of loaded) {
+        if (!entry.pack) {
+            summary.errors.push({ file: entry.file, error: entry.error ?? 'unreadable' });
+            continue;
+        }
+        const s = applySeedGraph(db, entry.pack, 'pack');
+        summary.applied += 1;
+        summary.concepts += s.concepts;
+        summary.edges += s.edges;
+        summary.edgesDropped += (entry.pack.edges?.length ?? 0) - s.edges;
+    }
+    db.prepare(`INSERT INTO meta (key, value) VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(packFingerprintKey(dirs), packFingerprint(loaded.map((l) => l.file)));
+    return summary;
+}
+/**
+ * Applies packs when the set on disk has changed since this scope last saw it.
+ *
+ * "Changed" includes a bumped `SEED_VERSION`, which is folded into the hash:
+ * seeding upserts every shipped concept back to its shipped name and tier, so a
+ * pack that had merged over one is undone by a re-seed and has to land again.
+ * That is why there is no separate `force` — the seed version *is* part of what
+ * the fingerprint is fingerprinting.
+ *
+ * The write on the way out matters even when nothing was applied. It is what
+ * records "this scope has seen this state", and dropping it for the empty set
+ * loses a pack's override for good: a re-seed that happens while the learner is
+ * in some other repository would otherwise never be noticed by the repository
+ * whose pack it undid.
+ *
+ * Removing a pack does NOT remove its concepts. `mastery` and `attempts`
+ * reference them, so deleting the rows would delete the learner's history along
+ * with them — the same rule that keeps seeding away from `mastery`.
+ */
+export function applyPacksIfNeeded(db, cwd = process.cwd()) {
+    const dirs = packDirs(cwd).map((d) => d.dir);
+    const loaded = loadPacks(cwd);
+    const row = db.prepare('SELECT value FROM meta WHERE key = ?').get(packFingerprintKey(dirs));
+    if (row?.value === packFingerprint(loaded.map((l) => l.file)))
+        return null;
+    return applyLoaded(db, loaded, dirs);
+}
+//# sourceMappingURL=packs.js.map

package/dist/packs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packs.js","sourceRoot":"","sources":["../src/packs.ts"],"names":[],"mappings":"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"}

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "eklavya",
   "displayName": "Eklavya",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Learn while your agent works. Turns coding-agent generation time into adaptive, Socratic learning grounded in the code being written.",
   "author": {
     "name": "Ajay Kumar"

package/dist/plugin/agents/tutor.md

@@ -30,15 +30,29 @@ The main session asks quiz questions as multiple choice through the `AskUserQues
 ```
 Which of these does `httpOnly` actually prevent?
 
-  A) JavaScript reading the cookie via document.cookie
-  B) The cookie being sent to a different origin
-  C) The cookie surviving a browser restart
+  A) The cookie being sent to a different origin
+  B) The cookie surviving a browser restart
+  C) JavaScript reading the cookie via document.cookie
   D) The cookie being read over plain HTTP
 
 Reply with a letter, or "teach me" if you'd rather I explain it.
 ```
 
-Same rules as the skill's *Multiple choice* section: four options, three plausible distractors, the stem alone in `record_attempt`'s `question`, the labels in `options`, `format: "mcq"`, and the grade capped at 4. The only thing that changes is who draws the box.
+The answer is at C there because the plan said `answer_position: 3`, and
+**`answer_position` matters more here than anywhere else**: in the main session
+a tool draws the options, and here you letter them yourself, so nothing but you
+enforces the slot. Left to instinct the right answer lands at A nearly every
+time, and a learner needs only a handful of questions to notice that and start
+replying "A" without reading.
+
+"teach me" is this renderer's version of the tool's "Other" choice. Treat it as
+a blank, not a decline: grade 0 with `outcome: "dont_know"`, then teach.
+
+Same rules as the tutor skill's `skills/tutor/references/writing-mcq.md`: four
+options, three plausible distractors, the correct one at `answer_position`, the
+stem alone in `record_attempt`'s `question`, the labels in `options`,
+`format: "mcq"`, and the grade capped at 4. The only thing that changes is who
+draws the box.
 
 ## You do not write code
 
@@ -60,4 +74,4 @@ You are competing for attention with an agent that is producing code. Ask one qu
 
 Never record a grade for a question that was not answered. Record a decline (`outcome: "declined"`) only when they actually say so.
 
-"I don't know" is not silence and not a decline — it is a request. Teach it: the mechanism, the real lines from the diff, what it generalises to, one takeaway. Then record grade 0 with `outcome: "dont_know"` and move on. See the `tutor` skill for the full shape.
+"I don't know" is not silence and not a decline — it is a request. Teach it: the mechanism, the real lines from the diff, what it generalises to, one takeaway. Then record grade 0 with `outcome: "dont_know"` and move on. The full shape is in the tutor skill's `skills/tutor/references/grading.md`.