eklavya 1.14.0 → 1.15.0

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`.

package/dist/plugin/hooks/CLAUDE.md

@@ -30,11 +30,12 @@ triple in here, even in a comment, fails that test on purpose.
 `scripts/bump-version.sh` bumps `plugin.json` and `mcp/package.json`, nothing
 else.
 
-## The four hooks, out of `hooks.json`
+## The five hooks, out of `hooks.json`
 
 | Event | Matcher | Timeout | Script | Job |
 |---|---|---|---|---|
 | SessionStart | — | 10s | `session-start` | stamp `meta.current_session`, print the profile banner and the standing log directive |
+| UserPromptSubmit | — | 10s | `prompt-submit-nudge` | re-state the log directive in one line, but only for a session that has logged nothing after a grace window |
 | PreToolUse | `Bash` | 10s | `pre-tool-gate` | in `enforced` mode only, deny a `git commit` whose session gate has not passed |
 | PostToolUse | `mcp__.*log_session_concepts` | 10s | `checkpoint-quiz` | one mid-task question, `interleaved` cadence only |
 | Stop | — | 15s | `stop-quiz-check` | block the turn and demand a quiz |
@@ -54,10 +55,90 @@ stdin defensively, run the body, exit 0 silently on any throw. A new hook body
 goes inside `await run(async (input) => { ... })` and returns an exit code; it
 never calls `process.exit` itself. Helpers follow the same rule —
 `openExisting()` returns `null` rather than throwing on a missing or corrupt
-database, and deliberately does not migrate or seed (four hooks racing a
+database, and deliberately does not migrate or seed (several hooks racing a
 migration on session start is a corruption story). The one non-zero code is the
 Stop hook's `return 2`, which is how Stop blocks; the reason goes on stderr.
 
+## A hook must never *wait*, either
+
+Exiting 0 on a throw covers the loud failure. The quiet one is worse: a hook
+that blocks never errors, never logs, and stalls the session on every tool call
+that triggers it — with nothing for the developer to report except that Claude
+Code got slow.
+
+`readInput` used to be `for await (const chunk of process.stdin)`, which has
+exactly one exit: EOF. Ponytail's issue #443 reports Claude Code on Windows
+running a hook through a PowerShell block that swallows the piped JSON, so `end`
+never fires. **Nothing here verifies that mechanism** — there is no Windows
+machine in the loop — so what this defends against is the consequence, a stdin
+that never ends, which the tests reproduce directly. `run.mjs` is careful about
+everything else — Node version, four resolution candidates, a self-expiring heal
+claim, exit 0 on every throw — and this was the one gap.
+
+`mcp/src/stdin.ts` closes it, and `eklavya statusline` shares it: both read a
+JSON blob the host pipes in, both must degrade rather than hang, and two copies
+would be one copy getting the fix. Three things matter about it.
+
+**The primary bound is on silence, not on total time.** A flat cap truncates a
+payload still arriving when it fires, and truncated JSON does not fail loudly —
+it fails as `{}`, so the hook runs to completion having quietly decided the
+session has no cwd and no id. The idle timer resets on every chunk, so a payload
+is safe as long as it keeps making progress. The total cap behind it *can* still
+truncate, and claiming otherwise would be the same overclaim in the other
+direction — it is a deliberate trade, and `totalMs` is generous against how long
+a real payload takes.
+
+**It pauses the stream, not just the listeners.** This is the line the rest of
+it depends on. `setEncoding` puts stdin in flowing mode and a flowing stdin holds
+an active libuv handle, so removing the `data` listener resolves the read and
+leaves the process alive. The hooks hide that — `run()` ends in `process.exit` —
+but `eklavya statusline` just returns, and under exactly the no-EOF condition
+this exists for it printed the dials and then lingered forever, once per status
+bar refresh. `test/stdin.test.ts` spawns the statusline for that reason: it is
+the caller with no `process.exit` behind it, so it is the honest test of whether
+the read lets go.
+
+**Every timer is `unref`'d**, so a pending timer adds no latency to a hook that
+has already finished. On its own that does not let the process exit — see above.
+
+**There is an `error` handler.** A stream that errors never emits `end`, so
+without one the read waits on something that is not coming. It is also
+load-bearing beyond that: an unhandled `error` on `process.stdin` is an async
+exception `run()`'s `try`/`catch` could not have caught.
+
+**It costs something, and the cost is worth stating.** On a host that swallows
+the pipe this turns an infinite hang into `idleMs` per invocation, and PreToolUse
+matches every `Bash` call — so +2s per command until the host is fixed. Two
+seconds a command is bad; a frozen session is worse.
+
+`HOOK_STDIN` is 2s idle / 5s total, well under the 10s `hooks.json` grants (15
+for Stop) — a read that outlives its host timeout is a read the developer waits
+on, and `test/stdin.test.ts` asserts the relationship rather than the number.
+`STATUSLINE_STDIN` is 150ms / 250ms, and the total is pinned at or below the
+250ms flat cap the inline reader had before it: splitting one budget into idle
+plus total made the worst case four times worse for the one caller whose latency
+a human sees, which a test now prevents.
+
+That suite spawns a real hook, writes a payload, and **never closes stdin**;
+against the old code all three cases hang until the test kills them.
+
+`stripBom` runs before every `JSON.parse` here. Some Windows shells prepend a
+byte-order mark, and `JSON.parse` throws on input that looks perfectly
+well-formed in a terminal and in any editor — another silent nothing-happens.
+
+## `quiet` is not an off switch
+
+It suppresses the session-start banner and the status bar — things the developer
+looks at. It does **not** suppress the standing directive, and it does not gate
+the `UserPromptSubmit` nudge, because both are `additionalContext` the model
+reads rather than output anyone sees.
+
+That was a bug for a while, and a bad one: `session-start` returned before
+pushing the directive, so a developer who turned the greeting off logged
+nothing, was never quizzed, and saw `mode: ambient` in `get_config` the whole
+time. Two tests encoded it as intended behaviour. `mode: off` is the off switch,
+and it is the only one.
+
 ## The Stop hook blocks in `ambient` too
 
 Commonly got wrong. `ambient` is not "never interrupts" — `stop-quiz-check.ts`

package/dist/plugin/hooks/hooks.json

@@ -13,6 +13,18 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs", "prompt-submit-nudge"],
+            "timeout": 10
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Bash",

package/dist/plugin/hooks/run.mjs

@@ -11,8 +11,8 @@
  *
  *     "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs", "<name>"]
  *
- * and every platform-specific decision lives here instead of in four shell
- * scripts.
+ * and every platform-specific decision lives here instead of one shell script
+ * per hook.
  *
  * The second job is finding the runtime. The plugin payload is source and
  * manifests only — no `dist/`, no `node_modules/`, because a git-installed
@@ -88,7 +88,7 @@ function healInBackground() {
   const version = pinnedVersion();
   if (!version) return;
 
-  // Claim the attempt BEFORE spawning. Four hooks fire per session and the
+  // Claim the attempt BEFORE spawning. Every hook fires per session and the
   // check alone would let every one of them start its own npm — a spawn storm
   // on the machine of the person whose install is already struggling. An hour
   // makes the claim self-expiring, so a heal that dies still gets retried

package/dist/plugin/skills/CLAUDE.md

@@ -58,8 +58,9 @@ by what it is, not loaded by trigger.
   `eklavya` CLI and the read/write config tools; it does not teach or quiz.
 - **`agents/tutor.md`** is the subagent. It has the Eklavya MCP tools and
   read-only file access — and **no `AskUserQuestion`** — so it renders the four
-  options as lettered text. Any change to the *Multiple choice* section of
-  `skills/tutor/SKILL.md` has to hold for a plain-text renderer too.
+  options as lettered text. Any change to
+  `skills/tutor/references/writing-mcq.md` has to hold for a plain-text
+  renderer too.
 
 ## A skill is a prompt, but it is also an API client
 
@@ -148,23 +149,114 @@ cadence, so a tier there would sometimes name the previous question's
 difficulty, and a stale readout is worse than none. `level` covers what the tier
 was explaining: `easy` already means tiers 1-2.
 
-## `skills/tutor/SKILL.md` has two readers
-
-`mcp/scripts/copy-assets.mjs` bundles it to `mcp/dist/assets/tutor-skill.md`,
-and `eklavya export-rules` (`mcp/src/cli.ts`) strips the frontmatter and wraps
-it as a Cursor rules file. So that file is consumed by two editors.
-
-Consequence: **no Claude-Code-only instructions in its body.** Slash-command
-names, plugin paths and hook mechanics belong in the command skills, not in
-the pedagogy. `AskUserQuestion` is the one unavoidable exception, and
-`agents/tutor.md` already carries the fallback for renderers that lack it.
+## The tutor skill is an entry point plus references
+
+`skills/tutor/SKILL.md` was 5,296 words in one file, loaded whole whenever the
+model decided a task was non-trivial. It is now the part that decides *whether
+to act* — the log loop, checkpoint versus sweep, the shared budget, the tier
+ladder, the plan's authoritative fields, and a Red Flags table of the
+rationalizations that have each shipped a worse session — with the craft in
+three siblings:
+
+| File | Holds |
+|---|---|
+| `references/writing-mcq.md` | the four-option shape, `answer_position`, distractors, plain language, the second question about a concept, `prereqs_unmet`, and how to record a stem |
+| `references/grading.md` | both scales, the mcq cap, feedback length, the four-step sequence a blank earns, `already_taught` |
+| `references/focus-and-level.md` | the three focuses, the earned level bands, the cadence contract, the enforced-mode gate retry |
+
+Two rules keep that split working.
+
+**Mark a reference REQUIRED at the point of use, never as an `@`-link.** An
+`@`-path is resolved eagerly by the host, which pulls the whole file into
+context and undoes the split. "Read `references/grading.md` before you grade",
+written where grading comes up, is what makes the model open it exactly when it
+needs it.
+
+**The entry point does not grow back, and the pointers stay honest.**
+`test/packaging.test.ts` fails above 2,000 whitespace tokens, and asserts the
+set of files named in SKILL.md is *equal* to the set on disk. Both directions
+matter. A pointer with no file is the worse half — the model is told the rules
+are elsewhere, cannot find them, and improvises, while nothing errors. A file
+with no pointer is the quieter half: it ships, `export-rules` inlines it, and
+Claude Code is never told to read it, so the same pedagogy differs by surface.
+An earlier version of that test harvested pointers from SKILL.md *and*
+`agents/tutor.md` into one list and asserted the list was non-empty — which
+passed with no pointers in SKILL.md at all, the exact state it was written to
+catch.
+
+## Match the form to the failure
+
+Two failures need opposite wording, and using the wrong form measurably makes
+things worse. superpowers A/B tested this on their own dispatch-prompt
+guidance: the "don't do X" version produced **more** of the unwanted content
+than the "here is the shape" version — the distributions fully separated — and
+it did worse than giving no guidance at all.
+
+- **The model knows the rule and breaks it under pressure.** Discipline. Ban
+  it, and name the excuse next to it: that is what the Red Flags table at the
+  top of `SKILL.md` is, and what the shared budget, one-question and
+  spent-question rules live in.
+- **The model complies and produces the wrong shape.** Craft. Bans backfire
+  here. Describe the shape you want, in build order, and let the prohibitions
+  fall out of it as properties of the finished thing.
+
+Writing a good multiple-choice question is the second kind, and
+`references/writing-mcq.md` was written as the first kind — *never restate the
+answer, no double negatives, avoid "which is NOT", do not number the options*.
+It is now a six-part recipe in build order followed by a checklist of
+properties, so the same rules arrive as "the answer appears among the options
+and nowhere in the stem" rather than as separate bans to weigh.
+
+**No nuance clauses in the recipe.** superpowers measured this separately: one
+appended "unless it matters" turns a reliable recipe into a noisy one, because
+it reopens the negotiation the recipe had settled. `writing-mcq.md` carried
+exactly one — *"Save the precise term for when the precision is the point"* —
+and it is gone. If an exception is real, it belongs in the plan's `framing`,
+which is server-side and authoritative, not in a hedge the model gets to weigh.
+
+`references/grading.md` keeps its prohibitions on purpose. Inflating a grade
+and offering to stop because someone is blanking are pressure failures, not
+shape failures: the model knows what honest grading is.
+
+## The tutor skill has two readers
+
+`mcp/scripts/copy-assets.mjs` bundles the whole `skills/tutor/` directory to
+`mcp/dist/assets/tutor/`, and `eklavya export-rules` (`mcp/src/cli.ts`) strips
+the frontmatter and wraps it as a Cursor rules file. So the pedagogy is
+consumed by two editors.
+
+**Cursor has no progressive disclosure**, and that is the reason `export-rules`
+concatenates SKILL.md with every `references/*.md` in alphabetical order and
+says so in its preamble. A rules file is one document with `alwaysApply: true`,
+so "read `references/grading.md`" there is a pointer to nothing. Had the split
+shipped without the inlining, Cursor would have got the dispatch logic and none
+of the craft — and every test would still have passed. `test/cli.test.ts` now
+asserts a line from each reference reaches the output.
+
+Alphabetical rather than a hand-kept order: in an always-apply document the
+whole thing is in context at once, so order carries no meaning, and a listed
+order is one more place a new reference gets forgotten.
+
+**A missing reference is a hard failure there, not a warning.** `export-rules`
+reads the pointers out of SKILL.md and refuses to emit anything if one of them
+did not bundle, naming the file. It has to: the preamble promises the material
+is further down the document, so a half-bundled export is worse than none — the
+model is assured the rules are present and hunts for them instead of falling
+back on what it has. `copy-assets.mjs` only warns when a copy fails, so that
+state is reachable rather than hypothetical.
+
+Consequence of the two readers: **no Claude-Code-only instructions in any of
+the four files.** Slash-command names, plugin paths and hook mechanics belong
+in the command skills, not in the pedagogy. `AskUserQuestion` is the one
+unavoidable exception, and `agents/tutor.md` already carries the fallback for
+renderers that lack it.
 
 ## Consistency
 
 The same behaviour described in two skills has drifted apart before — that is
 how `focus: project` got into three files. The four dials appear in
 `skills/mode/SKILL.md` and `user-skill/eklavya/SKILL.md`; the level bands
-appear in `skills/level/SKILL.md` and the *Level* section of `tutor`; the
-cadence cap appears in `mode`, `quiz` and `tutor`. **When you change one, grep
-the others for the same claim.** Where any of them disagrees with the code,
+appear in `skills/level/SKILL.md` and `tutor/references/focus-and-level.md`;
+the cadence cap appears in `mode`, `quiz` and that same reference. **When you
+change one, grep the others for the same claim.** Where any of them disagrees with the code,
 `mcp/src/config.ts` and the tool file are right and the skill is wrong.

package/dist/plugin/skills/setup/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Get Eklavya working on this machine. Be brief; this should take one exchange.
 
-**1. Check prerequisites.** Run `node --version`. That is the whole list — the server, the CLI and all four hooks are Node, so nothing else has to be on `PATH`. Node must be 22+; below that the SQLite driver has no prebuilt binary and would need a C++ toolchain to install. If it is older, say so and how to upgrade on this platform, and stop: the rest of setup will not work.
+**1. Check prerequisites.** Run `node --version`. That is the whole list — the server, the CLI and all five hooks are Node, so nothing else has to be on `PATH`. Node must be 22+; below that the SQLite driver has no prebuilt binary and would need a C++ toolchain to install. If it is older, say so and how to upgrade on this platform, and stop: the rest of setup will not work.
 
 Optionally run `eklavya doctor`, which reports the same thing plus the runtime, the SQLite driver, the plugin's registration, the chat skill, the database and the effective config. It exits non-zero and names the repair — `eklavya install` — if any of those has broken. That is also the command to reach for later, whenever Eklavya has gone quiet: the hooks never fail loudly, so a broken install looks exactly like a quiet one.