W5: probe/teach phases — divider + collapsed teach checks

src/agent/prompts/30-phases.md

@@ -0,0 +1,18 @@
+# The two phases
+
+Every session has two phases, and the learner's UI marks the seam. Know which phase you're in — it changes how your questions arrive.
+
+## Probe
+
+From the first message until you call `plan_init`. Your questions here are the substance of the session: they **open instantly** in the learner's dock, front and center — that immediacy is exactly what probing needs. Ask freely (one at a time), follow up on every answer, and chase the edges of what he knows. The probe is working when the questions are getting sharper, not easier.
+
+## Teach
+
+The moment you call `plan_init`, a quiet divider appears in the learner's transcript — probing above, teaching below — and from that point on you are teaching. Every question you ask is now a **check**: it arrives collapsed behind a "Check your understanding" button, and the learner opens it when he's ready. Nothing interrupts him mid-reading — which puts the burden on you:
+
+- **Teach first, check second — in that order, in the transcript.** The explanation, the diagram, the worked example: all of it above the check. A check with no prose before it is a failed check — he opens the button and finds a question about teaching that never happened.
+- **Finish the thought before you fire.** Never call a check mid-explanation. If the teaching of a node needs three paragraphs and a demo, it gets all three before the check lands.
+- **One node, one check.** `plan_set_current` when you start teaching the node, teach it completely, then check it (`nodeId` set, so the outcome lands on the graph).
+- **A wrong answer means resume teaching** — diagnose, repair, re-teach — before the next check. The button is a gate, not a quiz-show buzzer.
+
+This applies to `ask_user_question` too: once teaching has begun, every question arrives behind the button. An open question mid-teaching is fine — but write the prose it belongs to first.

src/core/phases.ts

@@ -0,0 +1,47 @@
+/**
+ * Probe/teach phase derivation (vision §2 "Two phases, clearly separated").
+ *
+ * The session's phase is DERIVED, never stored: `plan_init` IS the transition
+ * marker — the call already fires exactly once at the seam (verified live in
+ * Gate 1), so no new agent tool exists. Phase = "probe" until the first
+ * message containing a `plan_init` tool part; from that message onward,
+ * phase = "teach". Everything after it (checks, follow-up asks) is teaching.
+ *
+ * Pure: no imports, no runtime deps — safe on server, client, and in tests.
+ */
+
+/** The two phases of a session. */
+export type Phase = "probe" | "teach";
+
+/** Minimal structural slice of a UI message — anything with typed parts. */
+export interface PhaseMessage {
+	parts: ReadonlyArray<{ type: string }>;
+}
+
+const PLAN_INIT_PART = "tool-plan_init";
+
+/**
+ * The phase at `upToIndex` (inclusive; default: the last message).
+ *
+ * Scans messages[0..upToIndex] for the FIRST message containing a
+ * `tool-plan_init` part — any part state counts (the call itself is the
+ * transition; teaching has begun even while the call's input streams). The
+ * message that contains plan_init is already teach: the divider renders
+ * exactly there, so probe content sits above it, teaching below.
+ *
+ * Boundary semantics:
+ * - no plan_init anywhere → "probe" at every index (pre-plan sessions keep
+ *   the old auto-open behavior for every question — backward compatible).
+ * - first plan_init in message i → phaseAt(m, i-1) === "probe",
+ *   phaseAt(m, i) === "teach", and every index after.
+ * - multiple plan_init parts → the FIRST wins (a re-init attempt later in
+ *   the transcript never moves the seam; the tool refuses re-init anyway).
+ */
+export function phaseAt(messages: readonly PhaseMessage[], upToIndex?: number): Phase {
+	const last = Math.min(upToIndex ?? messages.length - 1, messages.length - 1);
+	for (let i = 0; i <= last; i++) {
+		const parts = messages[i]?.parts;
+		if (parts?.some((p) => p.type === PLAN_INIT_PART)) return "teach";
+	}
+	return "probe";
+}