yt-briefing 0.14.2 → 0.15.0

package/.claude/skills/yt/SKILL.md

@@ -34,7 +34,7 @@ while true:
 **On `rating_needed` — literally:**
 
 - **A.** Take `out.summary` (markdown) and `out.pending` (metadata).
-- **B.** In the same turn, as **your chat text** (NOT command output — the UI does not show it), paste `summary` **verbatim**: no paraphrase, no shortening, no comment, no "see above". The user must see it before the popup. B is **unconditional** — it does not depend on there being anything else to write, so an iteration that returns no `skipped` line still opens with the pasted summary, never straight with the tool call. _(If the user says "I don't see the summary" — you skipped B. In Claude Code a PreToolUse gate blocks the popup when the pending video's id is missing from your chat text; if it fires, paste the summary and ask again.)_
+- **B.** In the same turn, as **your chat text** (NOT command output — the UI does not show it), paste `summary` **verbatim**: no paraphrase, no shortening, no comment, no "see above". The user must see it before the popup. B is **unconditional** — it does not depend on there being anything else to write, so an iteration that returns no `skipped` line still opens with the pasted summary, never straight with the tool call. _(If the user says "I don't see the summary" — you skipped B. In Claude Code a PreToolUse gate refuses to record the rating in step D when the pending video's id is missing from your chat text; if it fires, paste the summary, ask for the rating again, then record it.)_
 - **C.** In the same message call `AskUserQuestion` — **1 call, 1 question** (everything in one step), phrased in `output_lang`:
   - The question (e.g. "Rating?") with three options whose descriptions explain: **OK** = neutral (no effect on the filter), **Weak** = worthless (teach the filter to skip such titles), **Research** = break the loop and dig into this video's content together. The digits never appear in the popup — internally map to `--rating`: **OK → 1, Weak → 0**; Research maps to no digit, it exits the loop (see Research mode). There is **no positive rating** — keeping the channel is the implicit positive; you only down-rate noise (`0`) or steer with a comment.
   - **Other** is the comment / stop / research channel (no second question): the user types free text. If it equals `stop` (case-insensitive, trimmed) — or the popup is dismissed (✕) — **end the loop**. If it **starts with `?`**, the text after the `?` is a **research question** → Research mode. Otherwise it is a **comment**: **distill** the user's raw text into a clean, generalizable rule, and infer the rating — clearly negative → `0`, otherwise → `1`.

package/README.md

@@ -139,21 +139,29 @@ session. To install the skills again for another tool or project, run
 The loop only works if you see the summary *before* you rate it, and that is the one step an
 agent can silently drop — the popup still appears, you still answer, and the rating is recorded
 against a summary nobody read. On Claude Code the installer wires a `PreToolUse` hook into your
-project's `.claude/settings.json` that refuses the rating popup unless the video's summary is in
-the chat. It merges with your existing hooks and updates itself on reinstall. If that file isn't
-valid JSON the installer leaves it alone and says so — add the entry yourself:
+project's `.claude/settings.json` that refuses to *record* a rating unless the video's summary is
+in the chat. It merges with your existing hooks and updates itself on reinstall. If that file
+isn't valid JSON the installer leaves it alone and says so — add the entry yourself:
 
 ```json
 {
   "hooks": {
     "PreToolUse": [
-      { "matcher": "AskUserQuestion",
+      { "matcher": "Bash",
         "hooks": [ { "type": "command", "command": "node \"${CLAUDE_PROJECT_DIR}/node_modules/yt-briefing/dist/yt-summary-gate.js\"" } ] }
     ]
   }
 }
 ```
 
+It watches the rating write rather than the popup, because the popup cannot be gated: the agent
+pastes the summary and opens the popup in one message, and the harness only writes a message to
+the transcript once that message is complete — so the evidence does not exist yet at popup time.
+The rating write is a separate call in the next message, where it does. The matcher is `Bash`, so
+the hook is invoked on ordinary shell commands too; it reads the command line and exits before
+touching anything. The tradeoff: a genuinely skipped paste is caught after you have answered, so
+that one answer is wasted — but nothing reaches the channel profile unseen.
+
 Other agents have no equivalent hook, so there the instruction in `SKILL.md` is what holds.
 
 ## Providers

package/dist/lib/skill-install.js

@@ -111,7 +111,7 @@ const GATE_ID = 'yt-summary-gate';
  * How settings.json must invoke the gate. Like the skill's engine commands it bakes nothing
  * machine-absolute, but a hook may NOT assume its cwd — Claude Code's hooks reference states the
  * working directory can vary, so a bare relative path would fail open, silently and invisibly
- * (the popup appears ungated, which is exactly the bug the gate exists to catch). Hence the
+ * (the rating is written ungated, which is exactly the bug the gate exists to catch). Hence the
  * `$CLAUDE_PROJECT_DIR` prefix: still just a placeholder string in the committed JSON, resolved
  * to the project root at hook time.
  */
@@ -119,14 +119,16 @@ export const gateCommand = (dist = false) => dist
     ? `${isBun ? 'bun' : 'node'} "\${CLAUDE_PROJECT_DIR}/${toProjectRel(join(DIST_DIR, GATE_ID + '.js'))}"`
     : `bun run src/${GATE_ID}.ts`;
 /**
- * Put the gate into a settings object: a PreToolUse hook on AskUserQuestion. Merges — every other
- * setting and hook is left as found, and our own entry is updated in place, so reinstalling (or
- * moving the package, which changes the baked path) never duplicates or clobbers anything.
+ * Put the gate into a settings object: a PreToolUse hook on Bash, which is where the rating is
+ * written (gating the popup instead cannot work — see src/yt-summary-gate.ts). Merges — every
+ * other setting and hook is left as found, and our own entry is updated in place, so
+ * reinstalling (or upgrading from the pre-0.15.0 AskUserQuestion matcher) never duplicates or
+ * clobbers anything.
  */
 export function withGateHook(settings, command) {
     const preToolUse = ((settings.hooks ??= {}).PreToolUse ??= []);
     const mine = preToolUse.find((e) => e.hooks?.some((h) => h.command?.includes(GATE_ID)));
-    const entry = { matcher: 'AskUserQuestion', hooks: [{ type: 'command', command }] };
+    const entry = { matcher: 'Bash', hooks: [{ type: 'command', command }] };
     if (mine)
         Object.assign(mine, entry);
     else

package/dist/lib/summary-gate.js

@@ -2,18 +2,21 @@
  * Decision logic for the /yt summary gate — kept separate from the hook script so it is
  * runtime-agnostic and unit-testable: pure functions over a payload and a transcript.
  *
- * See `src/yt-summary-gate.ts` for why the gate exists and how the hook wires it up.
+ * See `src/yt-summary-gate.ts` for why the gate exists and where it had to move to work at all.
  */
+/** Substring identifying the rating writer; the skill always invokes it by this script name. */
+const RATING_SCRIPT = 'yt-rating';
 /**
- * Is this the /yt rating popup? Identified by its fixed option labels, which SKILL.md pins in
- * English across every `output_lang` (only the question text and descriptions are localised).
- * Anything else — including /yt-search's keep/skip — is none of the gate's business.
+ * Is this the call that writes a rating? The skill records every rating by running
+ * `yt-rating(.ts|.js) --rating <1|0>` through Bash, so the command line is the signal. Anything
+ * else — a sweep, a transcript pull, unrelated shell work — is none of the gate's business, and
+ * is waved through before this module does any I/O at all.
  */
-export function isRatingPopup(payload) {
-    const labels = (payload.tool_input?.questions ?? [])
-        .flatMap((q) => q.options ?? [])
-        .map((o) => (o.label ?? '').trim().toLowerCase());
-    return labels.includes('research') && labels.includes('weak');
+export function isRatingWrite(payload) {
+    if (payload.tool_name !== 'Bash')
+        return false;
+    const command = payload.tool_input?.command ?? '';
+    return command.includes(RATING_SCRIPT) && command.includes('--rating');
 }
 /**
  * Did the agent actually paste the summary? The summary carries the video's watch URL, so its id
@@ -38,31 +41,3 @@ export function summaryWasPasted(transcript, videoId) {
     }
     return false;
 }
-/**
- * Same question as `summaryWasPasted`, but tolerant of the harness writing the transcript late.
- *
- * The agent pastes the summary and calls the popup in one turn, so the text block and the tool
- * call are separate JSONL entries written by the harness asynchronously — the hook can run
- * while only the tool call has reached disk. A single read then reports "not pasted" for a turn
- * that did paste, and the block fires on every single video (observed 2026-08-30: the same
- * transcript and pending file that blocked, replayed seconds later, allowed).
- *
- * So poll instead of guessing: re-read until the id shows up or the window closes. A turn that
- * genuinely skipped the paste never produces the line, so the gate still blocks — just later.
- * `read` returning null (a torn read mid-write) counts as "not yet", not as proof of absence.
- */
-export async function waitForSummary(read, videoId, opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? 5000;
-    const intervalMs = opts.intervalMs ?? 200;
-    const now = opts.now ?? (() => Date.now());
-    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-    const deadline = now() + timeoutMs;
-    for (;;) {
-        const transcript = read();
-        if (transcript !== null && summaryWasPasted(transcript, videoId))
-            return true;
-        if (now() >= deadline)
-            return false;
-        await sleep(intervalMs);
-    }
-}

package/dist/yt-summary-gate.js

@@ -1,29 +1,38 @@
 #!/usr/bin/env node
 /**
- * yt-summary-gate — PreToolUse gate for Claude Code: refuses the /yt rating popup until the
+ * yt-summary-gate — PreToolUse gate for Claude Code: refuses to RECORD a rating until the
  * video's summary has actually been pasted into the chat.
  *
  * Step B of the rating loop (paste `out.summary` verbatim, THEN ask) is the one instruction the
  * agent can drop with no visible symptom: the popup still appears, the user still answers, and
- * the rating is recorded against a summary nobody saw. Observed failure mode — the paste happens
- * reliably while the sweep also returns a `skipped` list (there is other prose to write) and gets
- * dropped in iterations that return none, where the turn can open straight with a tool call. A
- * blind rating is worse than no rating: it teaches the title filter from noise.
+ * the rating is recorded against a summary nobody saw. A blind rating is worse than no rating:
+ * it teaches the title filter from noise.
  *
- * The engine cannot enforce this — `yt-sweep` only emits the summary, `yt-rating` only reads
- * `pending.json`, and neither can see the conversation. The transcript is the one place the
- * evidence exists and only the agent harness exposes it, so the check has to run as a hook.
+ * WHY IT GATES THE WRITE AND NOT THE POPUP. Until 0.15.0 this hook ran on `AskUserQuestion` and
+ * blocked the popup. That could never work: the harness writes an assistant message's entries to
+ * the transcript only once the message is COMPLETE — i.e. after its tool calls have returned —
+ * and the skill pastes the summary and opens the popup in a single message. So the gate asked
+ * the transcript for text that could not be there yet, and the write it was waiting on could not
+ * happen until the gate returned. It blocked every video and cleared on a blind retry (measured
+ * 2026-08-30: a marker in a long text block was absent from the transcript during its own
+ * message's tool call, and present in the next message immediately). 0.14.2's 5s poll treated
+ * that as a timing lag and so only made the block slower.
  *
- * The transcript is polled for a few seconds rather than read once: the paste and the popup are
- * a single turn and the harness flushes the JSONL asynchronously, so a single read can miss a
- * text block that is merely still in flight.
+ * The rating write is a separate Bash call in the FOLLOWING message, by which point the message
+ * carrying the summary is closed and on disk — the evidence exists exactly when this hook needs
+ * it. The tradeoff is honest: a genuinely skipped paste is now caught after the user has already
+ * answered the popup, so that one answer is wasted and the agent has to paste and re-ask. That
+ * costs nothing on the happy path, and it guards the thing that actually matters — what gets
+ * written into the channel profile.
  *
  * Reads the PreToolUse payload on stdin; exit 0 allows, exit 2 blocks and feeds stderr back to
  * the agent. Anything unexpected — foreign tool, unreadable transcript, no pending video —
- * allows: a gate that misfires on unrelated work would be worse than the bug it guards.
+ * allows: a gate that misfires on unrelated work would be worse than the bug it guards. This
+ * hook is matched on Bash, so it runs on ordinary shell work too: it must decide from the
+ * command string and exit before touching the disk.
  */
 import { readFileSync, existsSync } from 'node:fs';
-import { isRatingPopup, waitForSummary } from "./lib/summary-gate.js";
+import { isRatingWrite, summaryWasPasted } from "./lib/summary-gate.js";
 const ALLOW = 0;
 const BLOCK = 2;
 const allow = () => process.exit(ALLOW);
@@ -34,7 +43,7 @@ try {
 catch {
     allow();
 }
-if (payload.tool_name !== 'AskUserQuestion' || !isRatingPopup(payload))
+if (!isRatingWrite(payload))
     allow();
 // paths.ts derives the data dir from the cwd, which for a hook is the agent's, not ours — so the
 // import has to wait until we've moved there.
@@ -53,18 +62,16 @@ if (!pending.videoId)
 const transcript = payload.transcript_path;
 if (!transcript || !existsSync(transcript))
     allow();
-// Poll rather than read once: the paste and this popup are one turn, and the harness writes the
-// transcript asynchronously, so the text block can still be in flight while the hook runs.
-const seen = await waitForSummary(() => {
-    try {
-        return readFileSync(transcript, 'utf8');
-    }
-    catch {
-        return null; // transient (file being written) — treat as "not yet", keep waiting
-    }
-}, pending.videoId);
+let seen = false;
+try {
+    seen = summaryWasPasted(readFileSync(transcript, 'utf8'), pending.videoId);
+}
+catch {
+    allow();
+}
 if (seen)
     allow();
-process.stderr.write(`/yt step B not done: the summary for ${pending.videoId} ("${pending.title ?? '?'}") is not in your chat text.\n` +
-    `Paste out.summary verbatim as your reply first, then ask for the rating — the user rates what they can see.\n`);
+process.stderr.write(`/yt step B not done: the summary for ${pending.videoId} ("${pending.title ?? '?'}") never appeared in your chat text, ` +
+    `so this rating would be recorded against a summary the user never saw.\n` +
+    `Paste out.summary verbatim as your reply, ask for the rating again, then record it.\n`);
 process.exit(BLOCK);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yt-briefing",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "description": "A self-learning YouTube briefing engine: it sweeps the channels you follow, filters noise in two stages (title, then transcript), summarizes the rest in your language, and adapts to your ratings — one video at a time.",
   "type": "module",
   "bin": {