eklavya 1.14.0 → 1.16.0

package/dist/plugin/hooks/CLAUDE.md

@@ -30,11 +30,13 @@ 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 six 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 |
+| SubagentStart | — | 10s | `subagent-start` | give a delegated agent the log directive the parent's SessionStart never reached it with |
 | 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 |
@@ -46,6 +48,36 @@ the prefix depends on how the plugin was installed —
 catches both; anchoring it to one spelling silently disables the checkpoint for
 half the installs.
 
+## SubagentStart needs the JSON form, and skips the tutor
+
+`SessionStart` may print its context as raw stdout. `SubagentStart` may not: it
+reads `hookSpecificOutput.additionalContext` and drops anything else in silence,
+so the wrong form is a hook that runs, exits 0, and does nothing. That is the
+one thing `subagent-start.ts` cannot get wrong, and `mcp/test/hooks.test.ts`
+parses the envelope rather than asserting that something was printed.
+
+It also stays silent for `eklavya-tutor`, matched as a substring so both
+`eklavya-tutor` and `eklavya:eklavya-tutor` are caught. Not because the tutor
+lacks `log_session_concepts` — so do `Explore` and `Plan`, and they are told
+anyway. It is the directive's second sentence: *do not ask the developer
+anything here* is an order not to do the only thing `agents/tutor.md` exists
+for, so delivering it disables parallel tutoring in silence. An absent or
+unrecognised `agent_type` fails **open** — a host that does not send the field
+is a host where failing closed would turn the feature off with nothing to
+report. `docs/subagent-policy.md` is the policy in full; keep the two in step.
+
+`stop-quiz-check.ts` carries the same `agent_id` guard as `checkpoint-quiz.ts`,
+and for a stronger reason: it blocks with exit 2. `Stop` is believed to be
+parent-only, since `SubagentStop` is a separate event — but nothing here has
+verified that, and this hook is what made the path reachable, because before it
+a subagent logged nothing and the Stop hook's `logged > last_logged` predicate
+could never arm.
+
+**And it pays the stdin cost on every delegated task.** It needs `agent_type`,
+so it cannot keep ponytail's stdin-independent fast path; on a host that
+swallows the pipe that is `idleMs` — 2s — per subagent spawn, the same trade
+`PreToolUse` makes per `Bash` call.
+
 ## Every failure path exits 0
 
 A hook that throws breaks the user's session, and a learning tool that breaks
@@ -54,10 +86,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,30 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs", "prompt-submit-nudge"],
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs", "subagent-start"],
+            "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

@@ -11,9 +11,9 @@ One directory, one `SKILL.md`, YAML frontmatter with `name` and `description`.
 `/eklavya:<name>` slash command** — the model can no longer load it on its own,
 and the developer types it. Without that line the skill is model-invocable only.
 
-Seven have it, and they are the seven slash commands:
+Eight have it, and they are the eight slash commands:
 
-`gate`, `learn`, `level`, `mode`, `progress`, `quiz`, `setup`.
+`gate`, `learn`, `level`, `mode`, `pack`, `progress`, `quiz`, `setup`.
 
 `skills/tutor/SKILL.md` deliberately does not. It is the pedagogy — one
 question at a time, honest grading, never the same question twice — and every
@@ -40,7 +40,7 @@ So, for `tutor` and anything else without `disable-model-invocation`:
 number of questions, never the order of the tool calls, never the grading.
 Those live in the body, which is where the model has to go to get them.
 
-The seven slash commands are exempt, and it is not a technicality:
+The eight slash commands are exempt, and it is not a technicality:
 `disable-model-invocation: true` means the model never matches on their
 description at all. The developer types the command and the description is its
 one line of help, so those should say what they do. `agents/tutor.md` keeps one
@@ -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/pack/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: pack
+description: Write or edit an Eklavya concept pack — a JSON file of concepts, tiers and prerequisites that adds a domain, or a team's own codebase, to what Eklavya can quiz on.
+disable-model-invocation: true
+---
+
+# /eklavya:pack [domain or repo]
+
+Eklavya ships four graphs — git, node-backend, react, web-auth. A **pack** is the same file shape, written by someone else, merged over the shipped ones. It is how Rust or Kubernetes gets added without a pull request to Eklavya, and how a team teaches its own codebase.
+
+Two places, and the difference is the whole decision:
+
+| Where | Who it is for |
+|---|---|
+| `~/.eklavya/packs/*.json` | this developer, on every project |
+| `<repo>/.eklavya/packs/*.json` | everyone who works in this repository, versioned with it |
+
+The repo one is the interesting half. A codebase that ships its own concepts and prerequisites is describing itself to whoever joins next, and that is onboarding rather than quizzing. Ask which one they want before writing anything, and say what the repo scope means: it is committed, and it applies to every contributor.
+
+## Build the pack in this order
+
+1. **Read before you write.** `get_concept_graph` for the domain they named. If Eklavya already seeds it, the pack is an *extension* — new concepts, retiered old ones — not a replacement.
+2. **Name it.** `pack` is an identifier (`eklavya-pack-rust`, `acme-billing`), `version` is a string you bump when you edit it, `domain` is the one word that groups these concepts in a learner profile.
+3. **List the concepts, from the code.** For a repo pack, read the codebase: the modules, the invariants, the decisions someone new gets wrong. Each concept is `{ slug, name, tier, description }`. A slug is lowercase, hyphenated, and names the *idea* — `event-sourcing-replay`, not `fixed-the-replay-bug`.
+4. **Set each tier honestly.** 1 is what a thing is; 3 is why this choice here; 5 is when the architecture is wrong. A pack where everything is tier 3 teaches nothing about order.
+5. **Add the prerequisites.** `{ from, to, relation }`, relation one of `prerequisite_of`, `related_to`, `part_of`. An edge may point at a concept Eklavya already seeds — that is how a pack hangs itself off the shipped graph. `from` is the thing that comes first.
+6. **Write the file** into the directory the scope chose, and run `eklavya doctor`. It names every pack that loaded and every one that did not, with the reason.
+
+```json
+{
+  "pack": "acme-billing",
+  "version": "1.0.0",
+  "domain": "acme",
+  "concepts": [
+    { "slug": "idempotency-keys", "name": "Idempotency keys", "tier": 2,
+      "description": "Why every write endpoint in billing/ takes one, and what a retry does without it." },
+    { "slug": "ledger-append-only", "name": "The ledger is append-only", "tier": 3,
+      "description": "Corrections are new rows. Nothing in billing/ledger updates a posted entry." }
+  ],
+  "edges": [
+    { "from": "idempotency-keys", "to": "ledger-append-only", "relation": "prerequisite_of" }
+  ]
+}
+```
+
+## What a finished pack has
+
+- Every slug lowercase and hyphenated, every tier between 1 and 5, no slug twice.
+- A description on every concept that says something a question could be written from. `"Ownership"` is a name, not a description.
+- Between about 10 and 40 concepts. A pack of 200 is a syllabus nobody reaches the end of, and Eklavya asks about what the session touched, not about the list.
+- Concepts that are about the domain or the codebase, not about the tools. `webpack-config-splitting` is a concept; `we-use-webpack` is a fact.
+
+## Two things to say, and mean
+
+**A pack merges over the seed; it does not replace it.** Writing `jwt-structure` into a pack retiers the shipped concept rather than adding a second one. That is deliberate — it is how a team says "this is harder here" — but check `get_concept_graph` first, and say it out loud when a repo pack does it: there is one database and no repository column, so the override follows the developer into every other project and does not come back when they leave this one. New slugs are theirs alone; overriding a shipped one is the part worth a sentence before it is committed.
+
+**Removing a pack leaves its concepts behind.** They are what a learner's answers point at, so deleting them would delete the history with them. Uninstalling a pack stops it being re-applied; it does not undo it.
+
+## Then stop
+
+Report what was written, where, and what `eklavya doctor` said about it. Do not quiz on the new concepts — nothing has been logged, and `/eklavya:learn <domain>` is how someone asks to be taught them.

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