feat: suppress lessons in plan mode + drop the per-line blockquote from the card

Two determinism fixes for lesson delivery, both observed failing in a real session
(lesson fired during plan mode → couldn't save; card body fell out of the blockquote
with code blocks):

- The Stop hook now reads permission_mode from the payload (refactor parseStopHookActive
  -> parseHookPayload, stopHookContinuation -> readHookPayload + shouldSuppressHook) and
  stays silent when it is 'plan', for both onboard-hook and lesson-ready. No lesson fires
  while the model can't deliver or save it. The redundant 'Plan-mode suppression' section
  is dropped from SKILL.md.
- The card is now plain markdown between the two ### bands instead of a per-line '>'
  blockquote, which broke on multi-paragraph bodies and fenced code (even on Sonnet).

No code-side body strip (kept the model + simpler format instead).

Author: UltimaPhoenix

assets/SKILL.md

@@ -22,14 +22,6 @@ by teaching one thing at a time, at the right moment, based on what they actuall
 
 ---
 
-## Plan-mode suppression
-
-If you are currently in **plan mode** (plan mode is active and `ExitPlanMode` has not
-yet been called in this session), **exit this skill immediately** — do not read any
-devcoach MCP resources, do not run onboarding, do not deliver or log any lesson.
-
----
-
 ## Onboarding flow
 
 The onboarding flow runs inline, immediately before delivering a lesson, whenever
@@ -353,21 +345,17 @@ it is central to the task and no applicable profile topic exists.
 
 ## 4. Lesson format
 
-Append the lesson **at the bottom of the response**, rendered as a card: a titled
-top band, the content **indented as a blockquote**, and a bottom band echoing the
-topic and level.
+Append the lesson **at the bottom of the response**, rendered as a card: a titled top
+band, the lesson as **plain markdown**, and a bottom band echoing the topic and level.
 
 ```
 ### ──────── 🎓 devcoach ────────
-> [Category] · Level: [Junior|Mid|Senior]
->
-> **[Lesson title]**
->
-> [Body: 3–6 paragraphs. Concise, practical, with a code example if useful.
-> Explain the WHY, not just the what. Connect it to the task just completed.]
->
-> 💡 *Senior tip:* [One sentence a senior would say to a junior on this topic]
+**[Lesson title]** · [Category] · [Junior|Mid|Senior]
+
+[Body: 3–6 paragraphs. Concise, practical, with a code example if useful.
+Explain the WHY, not just the what. Connect it to the task just completed.]
 
+💡 *Senior tip:* [One sentence a senior would say to a junior on this topic]
 ### ──────── [topic] · [level] ────────
 ```
 
@@ -376,8 +364,8 @@ Card rules:
   U+2500) around a centered title — the heading makes Claude Code colour the whole
   line. Do **not** use `---` (a real rule can't carry a title). Aim for a band
   width of ~34 characters and keep the top and bottom bands the same width.
-- Every content line is prefixed with `> ` (blank separators become a bare `>`).
-- Leave **one blank line before the bottom band** so the blockquote closes cleanly.
+- The body is **plain markdown** between the bands — do **not** prefix lines with `> `
+  (a per-line blockquote breaks on multi-paragraph bodies and fenced code blocks).
 
 **Display vs storage:** the card above is for chat only. When you call `log_lesson`,
 the `body` is **clean markdown** — no bands, no `> ` blockquote, and no title/`Category ·

plugin/skills/devcoach/SKILL.md

@@ -22,14 +22,6 @@ by teaching one thing at a time, at the right moment, based on what they actuall
 
 ---
 
-## Plan-mode suppression
-
-If you are currently in **plan mode** (plan mode is active and `ExitPlanMode` has not
-yet been called in this session), **exit this skill immediately** — do not read any
-devcoach MCP resources, do not run onboarding, do not deliver or log any lesson.
-
----
-
 ## Onboarding flow
 
 The onboarding flow runs inline, immediately before delivering a lesson, whenever
@@ -353,21 +345,17 @@ it is central to the task and no applicable profile topic exists.
 
 ## 4. Lesson format
 
-Append the lesson **at the bottom of the response**, rendered as a card: a titled
-top band, the content **indented as a blockquote**, and a bottom band echoing the
-topic and level.
+Append the lesson **at the bottom of the response**, rendered as a card: a titled top
+band, the lesson as **plain markdown**, and a bottom band echoing the topic and level.
 
 ```
 ### ──────── 🎓 devcoach ────────
-> [Category] · Level: [Junior|Mid|Senior]
->
-> **[Lesson title]**
->
-> [Body: 3–6 paragraphs. Concise, practical, with a code example if useful.
-> Explain the WHY, not just the what. Connect it to the task just completed.]
->
-> 💡 *Senior tip:* [One sentence a senior would say to a junior on this topic]
+**[Lesson title]** · [Category] · [Junior|Mid|Senior]
+
+[Body: 3–6 paragraphs. Concise, practical, with a code example if useful.
+Explain the WHY, not just the what. Connect it to the task just completed.]
 
+💡 *Senior tip:* [One sentence a senior would say to a junior on this topic]
 ### ──────── [topic] · [level] ────────
 ```
 
@@ -376,8 +364,8 @@ Card rules:
   U+2500) around a centered title — the heading makes Claude Code colour the whole
   line. Do **not** use `---` (a real rule can't carry a title). Aim for a band
   width of ~34 characters and keep the top and bottom bands the same width.
-- Every content line is prefixed with `> ` (blank separators become a bare `>`).
-- Leave **one blank line before the bottom band** so the blockquote closes cleanly.
+- The body is **plain markdown** between the bands — do **not** prefix lines with `> `
+  (a per-line blockquote breaks on multi-paragraph bodies and fenced code blocks).
 
 **Display vs storage:** the card above is for chat only. When you call `log_lesson`,
 the `body` is **clean markdown** — no bands, no `> ` blockquote, and no title/`Category ·

src/cli/commands.ts

@@ -719,39 +719,50 @@ async function cmdSetup(): Promise<void> {
 // ── Stop hooks ───────────────────────────────────────────────────────────────
 
 /**
- * Claude Code passes the Stop-hook payload as JSON on stdin. `stop_hook_active`
- * is true when the current stop is itself the result of a Stop hook forcing the
- * agent to continue — re-blocking then would loop forever. Returns true only for
- * a well-formed payload with the flag set; empty/garbage input is treated as a
- * fresh stop.
+ * Claude Code passes the Stop-hook payload as JSON on stdin. We use two fields:
+ * `stop_hook_active` (true when this stop is itself a hook-forced continuation —
+ * re-blocking then would loop forever) and `permission_mode` (`"plan"` while the user
+ * is planning, when the model cannot deliver or save a lesson). Empty/garbage input is
+ * treated as a fresh, non-plan stop.
  */
-export function parseStopHookActive(raw: string): boolean {
+export interface HookPayload {
+  stop_hook_active: boolean;
+  permission_mode: string | null;
+}
+
+export function parseHookPayload(raw: string): HookPayload {
   try {
-    const parsed = JSON.parse(raw);
-    return parsed?.stop_hook_active === true;
+    const p = JSON.parse(raw);
+    return {
+      stop_hook_active: p?.stop_hook_active === true,
+      permission_mode: typeof p?.permission_mode === "string" ? p.permission_mode : null,
+    };
   } catch {
-    return false;
+    return { stop_hook_active: false, permission_mode: null };
   }
 }
 
 /**
- * Read the Stop-hook payload from stdin, but only when it is actually piped
- * (a FIFO or a redirected file). On a TTY or any other source we skip the read
- * entirely so an interactive run — or a test — never blocks waiting for EOF.
+ * Read the Stop-hook payload from stdin, but only when it is actually piped (Claude
+ * Code delivers it over a SOCKET; a FIFO or a redirected file carry it too). Skip a
+ * TTY/character device, where a blocking read would hang an interactive run or a test.
  */
-function stopHookContinuation(): boolean {
+function readHookPayload(): HookPayload {
+  const empty: HookPayload = { stop_hook_active: false, permission_mode: null };
   try {
     const st = fstatSync(0);
-    // Claude Code delivers the Stop-hook payload over a SOCKET; a piped FIFO or a
-    // redirected file carry it too. Read all three. Skip only a TTY/character device,
-    // where a blocking read would hang an interactive run or a test.
-    if (!st.isFIFO() && !st.isFile() && !st.isSocket()) return false;
-    return parseStopHookActive(readFileSync(0, "utf8"));
+    if (!st.isFIFO() && !st.isFile() && !st.isSocket()) return empty;
+    return parseHookPayload(readFileSync(0, "utf8"));
   } catch {
-    return false;
+    return empty;
   }
 }
 
+/** A Stop hook stays silent on a hook-forced continuation, or while in plan mode. */
+function shouldSuppressHook(p: HookPayload): boolean {
+  return p.stop_hook_active || p.permission_mode === "plan";
+}
+
 /**
  * Block the stop without the non-zero "Stop hook error" framing. Claude Code reads
  * `{decision:"block", reason}` from stdout (exit 0), blocks the stop, and feeds
@@ -764,7 +775,7 @@ function emitBlock(reason: string): never {
 }
 
 function cmdOnboardHook(): void {
-  if (stopHookContinuation()) process.exit(0);
+  if (shouldSuppressHook(readHookPayload())) process.exit(0);
   // No DB yet → onboarding has not run. Cue WITHOUT creating coaching.db or any
   // marker file, so an interrupted onboarding leaves nothing behind and re-cues on
   // the next task. The artifacts appear only when complete_onboarding actually runs.
@@ -793,7 +804,7 @@ function cmdOnboardHook(): void {
 const NOTEBOOK_UPDATE_EVERY = 10;
 
 function cmdLessonReady(): void {
-  if (stopHookContinuation()) process.exit(0);
+  if (shouldSuppressHook(readHookPayload())) process.exit(0);
   // No DB → no profile yet. Stay silent without creating coaching.db.
   if (!existsSync(db.DB_PATH)) process.exit(0);
   let result: { allowed: boolean; nextLessonNumber: number };
@@ -837,12 +848,12 @@ function cmdLessonReady(): void {
       "its 'Recommended focus', calibrate depth from 'Recurring patterns', and watch its 'Open " +
       "hypotheses'. Pick ONE devcoach://profile topic NOT already in devcoach://taught-topics, " +
       "pitched at or above the user's confidence band.\n" +
-      "4. FIRST write the lesson as your visible reply — a card in EXACTLY this format:\n\n" +
+      "4. FIRST write the lesson as your visible reply — in EXACTLY this format. It is plain " +
+      "markdown between two band headings; do NOT prefix lines with '>' (no blockquote):\n\n" +
       "### ──────── 🎓 devcoach ────────\n" +
-      "> [Category] · Level: [Junior|Mid|Senior]\n" +
-      "> **[Title]**\n" +
-      "> [3–6 short paragraphs: explain the why, tie it to the task; fenced code if useful]\n" +
-      "> 💡 *Senior tip:* [one line]\n" +
+      "**[Title]** · [Category] · [Junior|Mid|Senior]\n\n" +
+      "[3–6 short paragraphs: explain the why, tie it to the task; fenced code if useful]\n\n" +
+      "💡 *Senior tip:* [one line]\n" +
       "### ──────── [topic] · [level] ────────\n\n" +
       "5. ONLY AFTER the card is written, call log_lesson. Put title/topic_id/categories/level/" +
       "summary in their own fields; body = ONLY the prose + the 💡 tip as CLEAN markdown (no " +

tests/cli.test.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { describe, expect, it, vi } from "vitest";
-import { parseStopHookActive, runCli } from "../src/cli/commands";
+import { parseHookPayload, runCli } from "../src/cli/commands";
 import * as db from "../src/core/db";
 import { parseLesson } from "../src/core/models";
 import { VERSION } from "../src/version";
@@ -116,12 +116,22 @@ describe("cli", () => {
     expect(due.out).toContain("call update_notebook");
   });
 
-  it("parseStopHookActive: only a payload with stop_hook_active=true short-circuits", () => {
-    expect(parseStopHookActive(JSON.stringify({ stop_hook_active: true }))).toBe(true);
-    expect(parseStopHookActive(JSON.stringify({ stop_hook_active: false }))).toBe(false);
-    expect(parseStopHookActive(JSON.stringify({ hook_event_name: "Stop" }))).toBe(false);
-    expect(parseStopHookActive("")).toBe(false);
-    expect(parseStopHookActive("not json")).toBe(false);
+  it("parseHookPayload: extracts stop_hook_active and permission_mode", () => {
+    expect(parseHookPayload(JSON.stringify({ stop_hook_active: true })).stop_hook_active).toBe(
+      true,
+    );
+    expect(parseHookPayload(JSON.stringify({ stop_hook_active: false })).stop_hook_active).toBe(
+      false,
+    );
+    expect(parseHookPayload(JSON.stringify({ permission_mode: "plan" })).permission_mode).toBe(
+      "plan",
+    );
+    expect(parseHookPayload(JSON.stringify({ permission_mode: "default" })).permission_mode).toBe(
+      "default",
+    );
+    const empty = parseHookPayload("not json");
+    expect(empty.stop_hook_active).toBe(false);
+    expect(empty.permission_mode).toBe(null);
   });
 
   it("knowledge + group + settings commands", async () => {