Author-once plan protocol: single mermaid plan_init + derived statuses + live quiz nodeId validation

- plan_init is now the ONLY plan tool: a mermaid 'graph TD' block parsed by a
  constrained-subset parser (mermaid-plan.ts) with line-precise errors; the
  seven mutation/tracking tools are gone by design (2026-09-03 design pass).
- Re-call plan_init = sanctioned wholesale rewrite; slugs are permanent.
- derivePlanStatuses (contracts/plan.ts): done = passed check tagged with a
  quiz nodeId; current = open check's node else first topo-ready node — the
  tracking the teacher no longer declares by hand.
- questionToolsFor(ctx) (tools.ts): the quiz schema chains a dynamic plan-
  nodeId validation against the LIVE record — an invalid nodeId is rejected
  at the call boundary and the teacher retries mid-turn, before any UI.
  Static questionTools stay validator-less for the default path.
- Prompts rewritten for mermaid authoring + derived position.
- Out-of-lane surgical touches (flagged for master review):
  src/core/question-core.ts (quizInputObject export + nodeId description),
  src/core/contracts/plan.ts (derivePlanStatuses + doc).

src/agent/tools.ts

@@ -1,5 +1,5 @@
 import { tool, type ToolSet } from "ai";
-import { askInputSchema, quizInputSchema } from "../core/question-core.ts";
+import { askInputSchema, quizInputObject, quizInputProblems, quizInputSchema } from "../core/question-core.ts";
 import type { JobRecord } from "../core/contracts.ts";
 import type { JobStore } from "../core/ports.ts";
 import { jobTools, type DemoInput, type ResearchInput, type VisualInput } from "./tools/jobs.ts";
@@ -10,14 +10,20 @@ export { jobTools };
 /**
  * The teacher's tools, composed per request by createTeacherTools.
  *
- * - questionTools (quiz / ask_user_question): CLIENT-SIDE tools (no `execute`).
- *   The tool call streams to the browser in `input-available` state; the
- *   learner answers in the dock; the client grades via question-core and
- *   sends the verdict with addToolOutput. The input schemas live in
- *   core/question-core (the question contract) — parameter names mirror
- *   the prompt docs exactly; keep them in sync.
- * - planTools (src/agent/tools/plan.ts): SERVER-SIDE, mutate the chat's plan
- *   tree (needs the chatId closure — hence the per-request factory).
+ * - questionTools / questionToolsFor (quiz / ask_user_question): CLIENT-SIDE
+ *   tools (no `execute`). The tool call streams to the browser in
+ *   `input-available` state; the learner answers in the dock; the client
+ *   grades via question-core and sends the verdict with addToolOutput. The
+ *   input schemas live in core/question-core (the question contract) —
+ *   parameter names mirror the prompt docs exactly; keep them in sync.
+ *   questionToolsFor adds the per-session plan-nodeId validation: an invalid
+ *   nodeId NEVER reaches the learner — the SDK returns the validation error
+ *   to the teacher as a tool result and it retries (same loop as the
+ *   grading rules). It reads the LIVE record at validation time, so a
+ *   plan_init earlier in the same turn already counts.
+ * - planTools (src/agent/tools/plan.ts): SERVER-SIDE — the single author-once
+ *   plan_init (mermaid → structured tree; re-callable rewrite). Needs the
+ *   chatId closure — hence the per-request factory.
  * - jobTools (src/agent/tools/jobs.ts): SERVER-EXECUTED dispatch — the call
  *   resolves immediately with a fire-and-forget ack, the background runner
  *   does the work, and the result arrives later as a steer message
@@ -54,6 +60,49 @@ export const questionTools = {
 	ask_user_question: askUserQuestionTool,
 };
 
+/**
+ * Per-session question tools: the quiz schema gains the dynamic plan-nodeId
+ * validation on top of question-core's shared authoring rules (chained
+ * superRefines — the grading contract is untouched). The check reads the
+ * LIVE chat record, so rewrites mid-turn are honored, and with no tree yet
+ * (probe phase) every nodeId is rejected — ad-hoc checks must omit it.
+ * ask_user_question is untouched: it never carries nodeId (not a check).
+ */
+export function questionToolsFor(ctx: Pick<PlanToolContext, "chatId" | "chatStore">): ToolSet {
+	const quizInputWithNodeValidation = quizInputObject
+		.superRefine((input, add) => {
+			for (const problem of quizInputProblems(input)) {
+				add.addIssue({ code: "custom", message: problem });
+			}
+		})
+		.superRefine((input, add) => {
+			if (typeof input.nodeId !== "string" || input.nodeId.length === 0) return;
+			const record = ctx.chatStore.getChat(ctx.chatId);
+			const tree = record?.tree;
+			const known = tree?.nodes.map((n) => n.id) ?? [];
+			if (!known.includes(input.nodeId)) {
+				add.addIssue({
+					code: "custom",
+					message:
+					`nodeId "${input.nodeId}" matches no node in this session's plan map. ` +
+						(known.length > 0
+							? `Copy one of your plan_init slugs exactly (${known.slice(0, 5).join(", ")}${known.length > 5 ? ", …" : ""}), or omit nodeId for an ad-hoc check.`
+							: "No plan map exists yet — omit nodeId (ad-hoc checks only until you call plan_init)."),
+				});
+			}
+		});
+
+	const quizWithNodeValidation = tool({
+		description: quizTool.description,
+		inputSchema: quizInputWithNodeValidation,
+	});
+
+	return {
+		quiz: quizWithNodeValidation,
+		ask_user_question: askUserQuestionTool,
+	};
+}
+
 export interface TeacherToolContext extends PlanToolContext {
 	/** Job-tool wiring (sub-agent dispatch): the job store + the runner's
 	 *  spawn seam. The composition root injects both. */
@@ -65,13 +114,13 @@ export interface TeacherToolContext extends PlanToolContext {
 }
 
 /**
- * Per-request tool registry. Plan tools close over the ctx (chatId + the
- * injected ChatStore) for persistence; question tools are context-free;
- * job tools close over the job store + spawn seam.
+ * Per-request tool registry. Plan tools and question tools close over the
+ * ctx (chatId + the injected ChatStore — the latter also powers the quiz
+ * nodeId validation); job tools close over the job store + spawn seam.
  */
 export function createTeacherTools(ctx: TeacherToolContext): ToolSet {
 	return {
-		...questionTools,
+		...questionToolsFor(ctx),
 		...planTools(ctx),
 		...jobTools({ chatId: ctx.chatId, jobStore: ctx.jobStore, spawn: ctx.spawn }),
 	};