@tinoy/pi-canon 0.1.0

package/canon.ts

@@ -0,0 +1,1751 @@
+/**
+ * Canon Extension
+ *
+ * Tool-managed binding system-prompt lines (rules + learned facts), scoped by
+ * model (global | <model-id>) and audience (all | parent | foreman | subagent).
+ * An entry's audience is a MEMBERSHIP test against the audience set its session
+ * belongs to, not a single session kind: a foreman session is {parent, foreman}.
+ * Injected into every matching session's system prompt at session start via
+ * before_agent_start AND guaranteed on every provider request by the
+ * normalization in before_provider_request (see the block comment there). The
+ * injected block is a session-start snapshot — the system prompt is
+ * prompt-cache-frozen, so runtime edits NEVER change a running session's
+ * block; new sessions get the current full list, running sessions learn of
+ * changes via canon notices (and the user's /canon-dump).
+ * Edited at runtime via canon_add / canon_remove / canon_edit (plus
+ * the /canon and /canon-dump commands). Changes are broadcast to peer sessions
+ * over the pi-intercom extension bus (namespace "canon"); each receiver matches
+ * the entry scope against its own model + audience before showing a notice.
+ *
+ * Replaces APPEND_SYSTEM.md (global/parent) and FLASH.md (global/subagent).
+ * Audience detection is one per-process set, read once at load (sessionAudiences).
+ * A child session is recognised by EITHER of two markers, because there are two
+ * launch paths: PI_SUBAGENT=1, exported by ~/.local/bin/pi-subagent and inherited
+ * by the pi processes it starts, and PI_SUBAGENT_CHILD=1, set in process.env by
+ * the pi-subagents async runner at module load, before the child session it hosts
+ * loads any extension. Either marker means {subagent}; otherwise {parent}, plus
+ * {foreman} when PI_FOREMAN=1, the value the pi-foreman launcher exports for the
+ * session it execs. The environment is the only signal present before the block
+ * renders, and it cannot change within a session, so the block is fixed for that
+ * session's life.
+ *
+ * Store: ~/.pi/agent/canon/canon.json — { entries: [{id, text, model, audience, reason?, category?}], categories: [{id, title, description?}] }
+ * Categories are un-ordered; entries reference them by id. They render as sub-headings
+ * inside scope groups (store insertion order), with uncategorized entries last.
+ * canon_add REQUIRES a category and canon_edit can only CHANGE one: every refusal
+ * lists the valid ids with their titles, so a retry costs no lookup call. The
+ * injected block renders titles only, so the refusal is also the only place an id
+ * reaches the model. The store validator counts entries that are uncategorized or
+ * carry a category id the store no longer holds (both render as Uncategorized) and
+ * reports the count to the hook log once per distinct state.
+ * Both the injected block and /canon-dump group entries under scope headers (model ×
+ * audience) — scope is NEVER repeated per line. Lines keep their [id] handle (the
+ * model needs it for canon_remove/canon_edit and to correlate notices/dump).
+ * Handles: opaque 6-char base36 ids generated by this extension, never reused.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	argText,
+	canonicalSystemPrompt,
+	clip,
+	type HeaderPart,
+	hookLog,
+	PROMPT_APPEND_SEP,
+	safeToolHeader,
+	systemPromptSlot,
+} from "@tinoy/pi-ext-lib";
+
+const AGENT_DIR =
+	process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+const DATA_DIR = path.join(AGENT_DIR, "canon");
+const STORE_PATH = path.join(DATA_DIR, "canon.json");
+const NAMESPACE = "canon";
+const HANDLE_LEN = 6;
+const REASON_MAX = 120;
+
+type Audience = "all" | "parent" | "foreman" | "subagent";
+
+/** Every audience value, in group-render order (also the label order). ONE list:
+ *  the store validator, the scope-group rank and the tool validators all read it,
+ *  so a new audience is added here and nowhere else. */
+const AUDIENCE_ORDER: readonly Audience[] = [
+	"all",
+	"parent",
+	"foreman",
+	"subagent",
+];
+
+/** Is this string one of the audience values? */
+function isAudience(value: string): value is Audience {
+	return (AUDIENCE_ORDER as readonly string[]).includes(value);
+}
+
+interface CanonScope {
+	model: string; // "global" | bare model id (provider prefix stripped)
+	/** Matched against the session's audience set; "all" matches every set. */
+	audience: Audience;
+}
+
+interface CanonEntry extends CanonScope {
+	id: string;
+	text: string;
+	reason?: string;
+	category?: string; // id of a category in store.categories; dangling -> Uncategorized
+}
+
+interface CanonCategory {
+	id: string;
+	title: string;
+	description?: string;
+}
+
+interface Store {
+	entries: CanonEntry[];
+	categories: CanonCategory[];
+}
+
+interface CanonNotice {
+	type: "canon";
+	op:
+		| "add"
+		| "remove"
+		| "edit"
+		| "category_add"
+		| "category_edit"
+		| "category_remove";
+	scope: CanonScope;
+	id: string;
+	text: string;
+	reason?: string;
+	sender?: string;
+}
+
+interface CanonChannel {
+	publish(
+		payload: unknown,
+		options?: { audience?: "owner" | "capable" },
+	): Promise<void>;
+	listSessions(): Promise<Array<{ id: string; name?: string }>>;
+}
+
+interface CanonRegistration {
+	namespace: string;
+	ownerEligible: boolean;
+	onEvent(event: {
+		type: string;
+		fromSessionId?: string;
+		payload?: unknown;
+	}): void;
+	onReady(channel: CanonChannel): void;
+}
+
+// ---------- pure store helpers ----------
+
+function normalizeModel(model: string): string {
+	const bare = model.includes("/")
+		? model.slice(model.lastIndexOf("/") + 1)
+		: model;
+	return bare.trim().toLowerCase();
+}
+
+/** Entry ids with no category, and entry ids whose category id the store does not
+ *  hold. Both render as Uncategorized, so the counts are the only signal that the
+ *  store has drifted away from its own categories. */
+function categoryDrift(store: Store): {
+	uncategorized: string[];
+	dangling: string[];
+} {
+	const known = new Set(store.categories.map((c) => c.id));
+	const uncategorized: string[] = [];
+	const dangling: string[] = [];
+	for (const e of store.entries) {
+		if (!e.category) uncategorized.push(e.id);
+		else if (!known.has(e.category)) dangling.push(e.id);
+	}
+	return { uncategorized, dangling };
+}
+
+/** Ids logged per drift kind. The count is the signal; the ids are where a repair
+ *  starts, and the store holds entries by the hundred. */
+const DRIFT_SAMPLE = 20;
+
+/** Drift signature last logged by this process: loadStore runs on every canon call
+ *  and on every block render, so the line is written once per distinct state rather
+ *  than once per load — one line, never one per entry. */
+let driftLogged: string | null = null;
+
+/** Report categorisation drift to the hook log. Reaches no session's prompt: a
+ *  dynamic line in the injected block would rewrite the cached prefix on every
+ *  load, so the count belongs in the log and in /canon-dump. */
+function logCategoryDrift(store: Store): void {
+	const drift = categoryDrift(store);
+	const signature = `${drift.uncategorized.length}/${drift.dangling.length}/${store.entries.length}`;
+	if (signature === driftLogged) return;
+	driftLogged = signature;
+	hookLog("canon", "category-drift", {
+		entries: store.entries.length,
+		categories: store.categories.length,
+		uncategorized: drift.uncategorized.length,
+		dangling: drift.dangling.length,
+		uncategorizedSample: drift.uncategorized.slice(0, DRIFT_SAMPLE),
+		danglingSample: drift.dangling.slice(0, DRIFT_SAMPLE),
+		truncated:
+			drift.uncategorized.length + drift.dangling.length > DRIFT_SAMPLE,
+	});
+}
+
+function loadStore(): Store {
+	try {
+		const raw = JSON.parse(fs.readFileSync(STORE_PATH, "utf8")) as Store;
+		if (Array.isArray(raw.entries)) {
+			raw.entries = raw.entries.filter(
+				(e): e is CanonEntry =>
+					typeof e?.id === "string" &&
+					typeof e?.text === "string" &&
+					typeof e?.model === "string" &&
+					isAudience(e.audience) &&
+					(e?.reason === undefined || typeof e?.reason === "string") &&
+					(e?.category === undefined || typeof e?.category === "string"),
+			);
+			raw.categories = Array.isArray(raw.categories)
+				? raw.categories.filter(
+						(c): c is CanonCategory =>
+							typeof c?.id === "string" &&
+							typeof c?.title === "string" &&
+							(c?.description === undefined || typeof c?.description === "string"),
+					)
+				: [];
+			logCategoryDrift(raw);
+			return raw;
+		}
+	} catch {
+		// missing or corrupt store -> start empty
+	}
+	return { entries: [], categories: [] };
+}
+
+function saveStore(store: Store): void {
+	fs.mkdirSync(DATA_DIR, { recursive: true });
+	const tmp = `${STORE_PATH}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", "utf8");
+	fs.renameSync(tmp, STORE_PATH);
+}
+
+function genId(store: Store): string {
+	let id: string;
+	do {
+		id = crypto
+			.randomBytes(4)
+			.readUInt32BE(0)
+			.toString(36)
+			.padStart(HANDLE_LEN, "0")
+			.slice(0, HANDLE_LEN);
+	} while (
+		store.entries.some((e) => e.id === id) ||
+		store.categories.some((c) => c.id === id)
+	);
+	return id;
+}
+
+/**
+ * The audiences a session belongs to, fixed at process start: PI_SUBAGENT=1 (the
+ * pi-subagent wrapper's marker) OR PI_SUBAGENT_CHILD=1 (the pi-subagents async
+ * runner's marker) -> {subagent}; otherwise {parent}, plus {foreman} when
+ * PI_FOREMAN=1 (the value the pi-foreman launcher exports for the session it
+ * execs). PI_FOREMAN is inherited by child processes, so a subagent is reduced to
+ * {subagent} — a foreman's worker is not a foreman. Called once per process and
+ * never re-read: the rendered block sits in the system-prompt prefix, so a set
+ * that varied mid-session would re-bill the tools array and the whole
+ * conversation.
+ */
+function sessionAudiences(isSubagent: boolean): Set<Audience> {
+	if (isSubagent) return new Set<Audience>(["subagent"]);
+	const audiences = new Set<Audience>(["parent"]);
+	if (process.env.PI_FOREMAN === "1") audiences.add("foreman");
+	return audiences;
+}
+
+/** This session's audience set as a label: "parent", "parent, foreman", "subagent". */
+function sessionLabel(audiences: ReadonlySet<Audience>): string {
+	return AUDIENCE_ORDER.filter((a) => a !== "all" && audiences.has(a)).join(
+		", ",
+	);
+}
+
+/** Does an entry apply to a session with the given active model + audiences? */
+function matches(
+	scope: CanonScope,
+	model: string,
+	audiences: ReadonlySet<Audience>,
+): boolean {
+	if (scope.model !== "global" && scope.model !== model) return false;
+	if (scope.audience === "all") return true;
+	return audiences.has(scope.audience);
+}
+
+/** Audience label appended to scope headings (all is implied by the bare model part). */
+const AUDIENCE_HEADING: Record<Audience, string> = {
+	all: "all sessions",
+	parent: "parent only",
+	foreman: "foreman only",
+	subagent: "subagent only",
+};
+
+/** Scope heading: model part, plus audience part only when it narrows. */
+function groupHeading(entryScope: CanonScope): string {
+	const modelPart =
+		entryScope.model === "global"
+			? "All models"
+			: `This model (${entryScope.model})`;
+	if (entryScope.audience === "all") return modelPart;
+	return `${modelPart} — ${AUDIENCE_HEADING[entryScope.audience]}`;
+}
+
+interface ScopeGroup {
+	scope: CanonScope;
+	rank: [number, number, string];
+	entries: CanonEntry[];
+}
+
+/** Bucket entries into scope groups: global first, then models; audiences in
+ *  AUDIENCE_ORDER (all → parent → foreman → subagent). */
+function scopeGroups(entries: CanonEntry[]): ScopeGroup[] {
+	const modelRank = (m: string) => (m === "global" ? 0 : 1);
+	const audienceRank = (a: Audience) => AUDIENCE_ORDER.indexOf(a);
+	const groups = new Map<string, ScopeGroup>();
+	for (const e of entries) {
+		const key = `${e.model} / ${e.audience}`;
+		let g = groups.get(key);
+		if (!g) {
+			g = {
+				scope: { model: e.model, audience: e.audience },
+				rank: [modelRank(e.model), audienceRank(e.audience), e.model],
+				entries: [],
+			};
+			groups.set(key, g);
+		}
+		g.entries.push(e);
+	}
+	return [...groups.values()].sort(
+		(a, b) =>
+			a.rank[0] - b.rank[0] ||
+			a.rank[1] - b.rank[1] ||
+			a.rank[2].localeCompare(b.rank[2]),
+	);
+}
+
+/** Render the injected block: header, scope groups, category sub-headings inside. */
+function render(
+	store: Store,
+	model: string,
+	audiences: ReadonlySet<Audience>,
+): string {
+	const matching = store.entries.filter((e) => matches(e, model, audiences));
+	const audienceLabel = sessionLabel(audiences);
+	let block = `## Canon — binding system-prompt rules\n\nThe rules below are authoritative standing instructions. They are part of your system prompt, persist for the entire session, and apply to every turn without exception. They override conflicting guidance from tool descriptions, examples, and any lower-precedence text. Follow them strictly.\n\nRuntime canon edits (canon_add / canon_edit / canon_remove) and peer canon notices reach this session as \`canon_notice\` messages; each notice is a live update to these rules and must be followed from the turn it is applied. A notice does not wake an idle session — it is applied on the next turn and remains in force.\n\nActive model: ${model} (this session: ${audienceLabel})`;
+	if (matching.length === 0) return block;
+
+	const catById = new Map(store.categories.map((c) => [c.id, c.title]));
+	for (const g of scopeGroups(matching)) {
+		block += `\n\n### ${groupHeading(g.scope)}`;
+		// bucket lines by category: store insertion order, uncategorized last
+		const buckets = new Map<string, CanonEntry[]>();
+		const uncat: CanonEntry[] = [];
+		for (const e of g.entries) {
+			if (e.category && catById.has(e.category)) {
+				const b = buckets.get(e.category);
+				if (b) b.push(e);
+				else buckets.set(e.category, [e]);
+			} else uncat.push(e);
+		}
+		const orderedCats = store.categories.filter((c) => buckets.has(c.id));
+		// only show category sub-headings when a scope group actually splits
+		const showCatHeadings = orderedCats.length + (uncat.length ? 1 : 0) >= 2;
+		for (const c of orderedCats) {
+			if (showCatHeadings) block += `\n\n#### ${c.title}`;
+			block += `\n${buckets
+				.get(c.id)!
+				.map((e) => `[${e.id}] ${e.text}`)
+				.join("\n")}`;
+		}
+		if (uncat.length) {
+			if (showCatHeadings) block += `\n\n#### Uncategorized`;
+			block += `\n${uncat.map((e) => `[${e.id}] ${e.text}`).join("\n")}`;
+		}
+	}
+	return block;
+}
+
+/** Render /canon-dump body: scope groups (model × audience), category sub-headings inside. */
+function renderDump(
+	entries: CanonEntry[],
+	categories: CanonCategory[],
+): string {
+	const lines: string[] = [];
+	for (const g of scopeGroups(entries)) {
+		lines.push(`## ${groupHeading(g.scope)}`);
+		const buckets = new Map<string, CanonEntry[]>();
+		const uncat: CanonEntry[] = [];
+		for (const e of g.entries) {
+			if (e.category && categories.some((c) => c.id === e.category)) {
+				const b = buckets.get(e.category!);
+				if (b) b.push(e);
+				else buckets.set(e.category!, [e]);
+			} else uncat.push(e);
+		}
+		for (const c of categories.filter((x) => buckets.has(x.id))) {
+			lines.push(`### ${c.title}${c.description ? ` — ${c.description}` : ""}`);
+			for (const e of buckets.get(c.id)!) {
+				lines.push(`[${e.id}] ${e.text}${e.reason ? ` — ${e.reason}` : ""}`);
+			}
+		}
+		if (uncat.length) {
+			lines.push("### Uncategorized");
+			for (const e of uncat) {
+				lines.push(`[${e.id}] ${e.text}${e.reason ? ` — ${e.reason}` : ""}`);
+			}
+		}
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Resolve a category reference to its id.
+ *
+ * The injected canon block shows category TITLES as sub-headings (`#### System
+ * Knowledge`) and never shows an id, so a model naturally passes the title back to
+ * canon_add — refusing that costs a call and teaches nothing. An exact id wins; a
+ * title matches case-insensitively; anything else fails with a short reason that
+ * the caller turns into a refusal.
+ */
+function lookupCategory(
+	store: Store,
+	input: string,
+): { ok: true; id: string } | { ok: false; detail: string } {
+	const want = input.trim();
+	if (!want) return { ok: false, detail: "empty value" };
+	const byId = store.categories.find((c) => c.id === want);
+	if (byId) return { ok: true, id: byId.id };
+	const lower = want.toLowerCase();
+	const byTitle = store.categories.filter(
+		(c) => c.title.trim().toLowerCase() === lower,
+	);
+	if (byTitle.length === 1) return { ok: true, id: byTitle[0].id };
+	if (byTitle.length > 1) {
+		return {
+			ok: false,
+			detail: `title "${want}" matches ${byTitle.map((c) => c.id).join(", ")}`,
+		};
+	}
+	return { ok: false, detail: `no category "${want}"` };
+}
+
+/**
+ * The refusal for every rejected category value: what failed, then every valid id
+ * with its title so a retry needs no lookup call of its own, then the one
+ * instruction that answers it. Terse by construction — it lands in a model's
+ * context, and the listing is the only place a category id is ever shown (the
+ * injected block renders titles).
+ */
+function categoryRefusal(
+	store: Store,
+	tool: string,
+	reason: string,
+	detail?: string,
+): string {
+	const listing = store.categories.length
+		? store.categories.map((c) => `${c.id} = ${c.title}`).join("; ")
+		: "(none defined — create one with canon_category op add)";
+	return `${tool}: ${reason}${detail ? ` (${detail})` : ""}. Valid categories: ${listing}. Pick the closest existing category.`;
+}
+
+function modelExists(
+	model: string,
+	ctx: { modelRegistry?: { getAvailable?: () => unknown } },
+): boolean {
+	if (model === "global") return true;
+	try {
+		const available = ctx.modelRegistry?.getAvailable?.() as
+			| Array<{ id?: string; modelId?: string }>
+			| undefined;
+		if (!Array.isArray(available)) return true; // registry unavailable -> don't block
+		const ids = new Set(
+			available.flatMap((m) => [m.id, m.modelId]).filter(Boolean),
+		);
+		return (
+			ids.has(model) ||
+			ids.has(`/${model}`) ||
+			[...ids].some((i) => i?.endsWith(`/${model}`))
+		);
+	} catch {
+		return true;
+	}
+}
+
+// ---------- tail sections ----------
+
+/**
+ * Registered tail sections, id -> text. Filled over the extension EVENT BUS, never
+ * by module import: pi evaluates every extension through its own jiti instance with
+ * `moduleCache: false` (dist/core/extensions/loader.js, `loadExtensionModule`), so
+ * another extension importing this file gets a DIFFERENT module instance and its
+ * registration would land in a map nothing renders from — silently, with no error
+ * and no log. The bus is created once per runtime and handed to every extension,
+ * and a handler's synchronous part runs before `emit` returns, so a section set at
+ * activation is composed into the very next request.
+ */
+const sections = new Map<string, string>();
+
+/** Section text cap. The tail sits in the prefix of EVERY request, so an
+ *  accidental megabyte would be paid for on every call for the session's life. */
+const SECTION_MAX_CHARS = 16_384;
+
+/**
+ * Set — or, with an empty string, clear — a tail section. Not an extension-facing
+ * API: another extension reaches this through the `canon:section` event, because
+ * an exported function is unreachable across the loader's module isolation.
+ */
+export function setTailSection(id: string, text: string): void {
+	const key = id.trim();
+	if (!key) return;
+	if (!text) {
+		if (sections.delete(key)) hookLog("canon", "section-cleared", { id: key });
+		return;
+	}
+	if (text.length > SECTION_MAX_CHARS) {
+		hookLog("canon", "section-too-long", { id: key, chars: text.length, cap: SECTION_MAX_CHARS });
+		return;
+	}
+	if (sections.get(key) === text) return;
+	sections.set(key, text);
+	// A section change rewrites the frozen prefix, so it is always attributable.
+	hookLog("canon", "section-set", {
+		id: key,
+		chars: text.length,
+		ids: registeredSectionIds().join(","),
+	});
+}
+
+/** Ids of every registered section, in the fixed order they compose in. */
+export function registeredSectionIds(): string[] {
+	return [...sections.keys()].sort();
+}
+
+// ---------- extension ----------
+
+export default function (pi: ExtensionAPI) {
+	let channel: CanonChannel | null = null;
+	let mySessionId: string | null = null;
+	let activeModel: string | null = null;
+	// Session-start snapshot: rendered once, reused verbatim every turn so the
+	// system prompt never changes mid-session (keeps the prompt cache intact).
+	// Runtime canon edits reach running sessions only via intercom notices.
+	let canonBlock: string | null = null;
+	/** Did before_agent_start fire since the previous provider request? Read (and
+	 *  cleared) by the payload repair to attribute a repair: false = the request
+	 *  came from a run-start path that never fires the hook (wake), true = the
+	 *  block was present in state but missing from the payload (anomaly). */
+	let hookFiredSinceLastRequest = false;
+	// Both child markers are read here, once, and never re-read: a crew worker
+	// arrives through the pi-subagents async runner (PI_SUBAGENT_CHILD, set by that
+	// runner before this module loads) while a pi-subagent wrapper launch carries
+	// PI_SUBAGENT. A worker whose foreman exported PI_FOREMAN is still a child.
+	const isSubagent =
+		process.env.PI_SUBAGENT === "1" || process.env.PI_SUBAGENT_CHILD === "1";
+	// Fixed for the process, like isSubagent: the block is a system-prompt prefix.
+	const audiences = sessionAudiences(isSubagent);
+
+	function currentModel(): string {
+		if (activeModel) return activeModel;
+		const env = process.env.PI_MODEL;
+		return env ? normalizeModel(env) : "unknown";
+	}
+
+	/** The block for this session, rendered at most once per process: a mid-session
+	 *  canon edit must never churn the prefix. Seeding the model from the hook ctx
+	 *  keeps the per-model filtering right when the FIRST request to need the block
+	 *  is routed by a path that never fired before_agent_start. */
+	function canonText(ctx?: { model?: unknown }): string {
+		const m =
+			(ctx?.model as { id?: string } | undefined)?.id ??
+			(ctx?.model as string | undefined);
+		if (m) activeModel = normalizeModel(String(m));
+		if (canonBlock === null) {
+			canonBlock = render(loadStore(), currentModel(), audiences);
+		}
+		return canonBlock;
+	}
+
+	/** The whole tail: the canon block, then every registered section. Composed in
+	 *  one place so the strip marker stays the canon block's first line and the
+	 *  canonicalizer needs no knowledge of what registered. Sections are plain
+	 *  strings, so composing cannot throw. */
+	function tailText(ctx?: { model?: unknown }): string {
+		let text = canonText(ctx);
+		for (const id of registeredSectionIds()) {
+			const section = sections.get(id);
+			if (section) text += `${PROMPT_APPEND_SEP}${section}`;
+		}
+		return text;
+	}
+
+	// The one channel another extension can reach the registry through. Kept
+	// synchronous deliberately: the bus wraps handlers in an async function, but the
+	// synchronous part runs before `emit` returns, so a section set during the
+	// activation command is already composed into the request that follows it.
+	pi.events.on("canon:section", (payload: unknown) => {
+		const p = payload as { id?: unknown; text?: unknown } | null;
+		if (!p || typeof p.id !== "string" || typeof p.text !== "string") return;
+		setTailSection(p.id, p.text);
+		// Announce the EFFECTIVE set, never the requested one. A section canon refused
+		// (an over-long text) must not be reported as present by anything that watches
+		// this channel — the cache log uses exactly that to prove a section reached the
+		// prompt, and a false positive there is indistinguishable from a success.
+		pi.events.emit("canon:sections", { ids: registeredSectionIds() });
+	});
+
+	// keep the cached model fresh for notification filtering
+	pi.on("before_agent_start", async (event, ctx) => {
+		hookFiredSinceLastRequest = true;
+		return { systemPrompt: event.systemPrompt + PROMPT_APPEND_SEP + tailText(ctx) };
+	});
+
+	// ── prompt-cache invariance: the block must not depend on the run-start path ──
+	//
+	// pi emits before_agent_start ONLY from the interactive prompt() path (pi
+	// 0.85.1: emitBeforeAgentStart has a single call site). A run started by an
+	// injected message — pi.sendMessage(msg, { triggerTurn: true }) while idle,
+	// which is how an async subagent completion, an intercom delivery or a
+	// delivered answer wakes a session — calls agent.prompt() directly, so it
+	// carries the UNMODIFIED base prompt and the block above never lands. The
+	// provider prefix is [system, tools, messages], so a block that moves inside
+	// the system prompt re-bills every token after it (the whole tools array plus
+	// the whole conversation) as a cache miss. Measured 2026-09-12: sys
+	// 134,308 -> 71,949 chars with the tools hash unchanged and 28,694 re-billed
+	// input tokens, reported as "Cache miss after 9m idle" (rows in
+	// ~/.local/state/pi/cache-prefix-log.jsonl).
+	//
+	// before_provider_request fires for every agent provider request on every
+	// run-start path (the miss rows above were written from this hook), so the
+	// payload is normalized here instead: every request leaves with
+	// canonicalSystemPrompt()'s bytes, appended exactly once at the same position.
+	// Compaction and branch summaries never reach this hook — they call the model
+	// runtime directly (completeSimple) with their own summarization prompt — so
+	// their prefix is untouched. The payload is mutated IN PLACE and no value is
+	// returned, so the bytes sent cannot depend on the handler order (the
+	// extension directory is read unsorted).
+	pi.on("before_provider_request", (event, ctx) => {
+		try {
+			const slot = systemPromptSlot((event as { payload?: unknown })?.payload);
+			if (!slot) return undefined;
+			const fired = hookFiredSinceLastRequest;
+			hookFiredSinceLastRequest = false;
+			const before = slot.get();
+			const { text, hadBlock } = canonicalSystemPrompt(before, tailText(ctx));
+			if (text === before) {
+				wakeRepairLogged = false; // canonical request: the next repair is a new event
+				return undefined; // already canonical: no write, no log
+			}
+			slot.set(text);
+			// A repair means the payload lacked the block. The HONEST attribution
+			// matters more than the repair itself: `wake` is the expected path (and
+			// the fix working, logged once per repaired run); `prompt` means
+			// before_agent_start DID fire since the last request and the block was
+			// stripped or replaced in between — a regression by another layer, which
+			// must never be silent, so it is logged every time.
+			if (fired || !wakeRepairLogged) {
+				wakeRepairLogged = true;
+				hookLog(
+					"canon",
+					fired ? "prompt-repair-after-hook" : "prompt-normalized",
+					{
+						model: currentModel(),
+						audience: isSubagent ? "subagent" : "parent",
+						staleBlock: hadBlock,
+						baseChars: before.length,
+						canonicalChars: text.length,
+					},
+				);
+			}
+		} catch {
+			/* a canonicalization fault must never break a provider request */
+		}
+		return undefined;
+	});
+
+	pi.on("model_select", (event) => {
+		const m =
+			(event.model as { id?: string } | undefined)?.id ??
+			(event.model as unknown as string | undefined);
+		if (m) activeModel = normalizeModel(String(m));
+	});
+
+	// Guard, not repair: a payload whose system prompt has a shape we cannot
+	// rewrite would silently keep the path-dependent asymmetry. One line per
+	// process is enough to make that visible; the request itself is untouched.
+	let unrepairableLogged = false;
+	/** Suppresses repeats of the expected wake-path repair line: a wake run's
+	 *  every request arrives base-only and is normalized, but one line names the
+	 *  run. An anomaly (fired === true) is never suppressed. */
+	let wakeRepairLogged = false;
+	pi.on("before_provider_request", (event) => {
+		try {
+			if (unrepairableLogged) return undefined;
+			const payload = (event as { payload?: unknown })?.payload as
+				| Record<string, unknown>
+				| undefined;
+			if (!payload || typeof payload !== "object") return undefined;
+			if (systemPromptSlot(payload)) return undefined;
+			unrepairableLogged = true;
+			hookLog("canon", "prompt-unrepairable", {
+				keys: Object.keys(payload).slice(0, 24),
+			});
+		} catch {
+			/* diagnostics must never break a provider request */
+		}
+		return undefined;
+	});
+
+	// Best-effort peer notice: the store write has already landed when this runs,
+	// so EVERY failure mode of the channel call is swallowed here and logged:
+	//   - pi-intercom 0.12.1's channel.publish is SYNCHRONOUS and throws
+	//     "Intercom is not connected" when the broker client is down;
+	//   - it returns void, so .catch must only ever be reached through the
+	//     optional call (chaining it directly was the TypeError that escaped);
+	//   - a promise-returning build rejects instead of throwing — the guarded
+	//     handler logs that too, so it can not become an unhandled rejection.
+	// A lost notice is NOT surfaced in the tool result: the result reports the
+	// STORE outcome (see the call sites), while the notice is ancillary — a
+	// failed announcement must never turn a successful edit into a failure.
+	function publishNotice(notice: Omit<CanonNotice, "type" | "sender">): void {
+		if (!channel) return;
+		try {
+			const payload: CanonNotice = {
+				...notice,
+				type: "canon",
+				sender: pi.getSessionName() || undefined,
+			};
+			const result = channel.publish(payload, { audience: "capable" });
+			result?.catch?.(() => {
+				hookLog("canon", "notice-failed", {
+					op: notice.op,
+					id: notice.id,
+					reason: "publish rejected",
+				});
+			});
+		} catch (err) {
+			hookLog("canon", "notice-failed", {
+				op: notice.op,
+				id: notice.id,
+				reason: err instanceof Error ? err.message : String(err),
+			});
+		}
+	}
+
+	// ---------- intercom channel (mirrors intercom-broadcast.ts) ----------
+
+	const registration: CanonRegistration = {
+		namespace: NAMESPACE,
+		ownerEligible: false,
+		onEvent(event: {
+			type: string;
+			fromSessionId?: string;
+			payload?: unknown;
+		}): void {
+			if (event.type !== "message" || typeof event.fromSessionId !== "string")
+				return;
+			if (mySessionId !== null && event.fromSessionId === mySessionId) return;
+			const payload = event.payload as Partial<CanonNotice> | null;
+			if (!payload || payload.type !== "canon" || !payload.scope || !payload.id)
+				return;
+			if (!matches(payload.scope, currentModel(), audiences)) return;
+			const sender = payload.sender?.trim() || event.fromSessionId.slice(0, 8);
+			const verb =
+				payload.op === "remove" || payload.op === "category_remove"
+					? "removed"
+					: payload.op === "edit" || payload.op === "category_edit"
+						? "edited"
+						: "added";
+			pi.sendMessage(
+				{
+					customType: "canon_notice",
+					content: `**Canon ${verb} (${payload.scope.model} / ${payload.scope.audience})**\n[${payload.id}] ${payload.text}${payload.reason ? `\nreason: ${payload.reason}` : ""}\n— from ${sender}`,
+					display: true,
+					details: { fromSessionId: event.fromSessionId, canonId: payload.id },
+				},
+				// PASSIVE (user 2026-09-01): "steer" wakes idle sessions like a
+				// prompt; "nextTurn" queues for the next user turn, no wake-up.
+				{ deliverAs: "nextTurn" },
+			);
+		},
+		onReady(readyChannel: CanonChannel): void {
+			channel = readyChannel;
+		},
+	};
+
+	function register() {
+		pi.events.emit("intercom:extension-register", registration);
+	}
+
+	// pi-intercom may load after this extension; re-emit once its registry is
+	// reported ready. First successful registration wins (duplicate namespace
+	// is rejected, not thrown).
+	pi.events.on("intercom:extension-registry-ready", () => {
+		if (!channel) register();
+	});
+	register();
+
+	// ---------- tools ----------
+
+	const canonAddTool = defineTool({
+		name: "canon_add",
+		label: "Add canon line",
+		description:
+			'Add a binding system-prompt line (rule or learned fact) to the canon store. ALWAYS pass BOTH model AND audience explicitly — never omit them. model scopes to one model ("global" = every model, or a bare id like "glm-5.3-flash"); audience scopes to "parent" (interactive sessions), "foreman" (foreman-mode sessions — a foreman also receives every "parent" entry), "subagent" (child sessions only), or "all". Passing both keeps each rule OUT of sessions where it is false/noise — a line left at "global"/"all" lands in every model\'s system prompt, and one at "global"/"parent" in every interactive session\'s, bloating and confusing unrelated sessions. category is MANDATORY and must be an id that already exists: a call that omits it, or names one the store does not hold, is REFUSED with the list of valid ids — that refusal is the discovery channel, so no lookup call is needed, and a category is NEVER created implicitly. Pick the closest existing category, or create one first with canon_category op add when none fits. Injected into matching sessions\' system prompts next turn; peers are notified. Optionally pass a short reason why the line exists — shown in /canon-dump and peer notices. Write ONE rule per entry, and cross-reference another entry by its id instead of restating it.',
+		promptSnippet: "Add a durable rule/fact to the canon (system-prompt lines)",
+		promptGuidelines: [
+			"Use canon_add when the user states a durable behavioural preference, corrects the model about behaviour, or the session learns a durable system fact. This is the replacement for editing APPEND_SYSTEM.md/FLASH.md: update canon FIRST, before any other action.",
+			"ALWAYS pass BOTH model AND audience explicitly on every canon_add (and canon_edit when re-scoping) — do NOT omit them. Decide scope before writing: which model does this concern (one bare id, or \"global\" for every model)? which audience (\"parent\" = interactive sessions, \"foreman\" = foreman-mode sessions, \"subagent\" = child sessions only, \"all\")?",
+			"Foreman/fleet workflow wisdom (spawn timeouts, crew survival, wake behaviour, foreman discipline) takes audience \"foreman\", never \"global\"/\"parent\": it is true only while the foreman mode is on, and filed as \"parent\" it lands in every interactive session's system prompt.",
+			"Categorize by TRUTH-SCOPE, not convenience (user 2026-09-01 — common failure): a rule that references or only applies to one model (a model-specific capability/quirk, e.g. a vision rule for deepseek-flash) MUST be model-scoped, never global. Only genuinely every-session rules (cross-cutting tool preferences, machine-wide facts) are global/all. Over-broad scope lands unrelated instructions in unrelated sessions' system prompts → bloat + confusion.",
+			"If you are about to write a canon line and have not picked model + audience, STOP and pick them explicitly first. Omitting them is the failure to avoid.",
+			"Reason is optional on canon_add/canon_edit/canon_remove: omit it by default, and never let one exceed 120 chars (that fails the whole call).",
+		],
+		parameters: Type.Object({
+			text: Type.String({ description: "The line text (rule or fact) to add" }),
+			model: Type.String({
+				description:
+					'Scope model: "global" for every model, or a bare model id like "glm-5.3-flash". REQUIRED — pick explicitly. Scope follows what the entry IS, never coverage: a model/provider quirk stays on its model, and a general rule filed under one belongs on "global".',
+			}),
+			audience: Type.String({
+				description:
+					'Audience: "parent" (interactive sessions), "foreman" (foreman-mode sessions only), "subagent" (child sessions only), or "all". REQUIRED — pick explicitly.',
+			}),
+			category: Type.Optional(
+				Type.String({
+					description:
+						"Category to file this entry under — an id (or exact title) that already exists. REQUIRED: omitting it, or naming a category the store does not hold, is refused with the list of valid ids (canon_category op list also shows them).",
+				}),
+			),
+			reason: Type.Optional(
+				Type.String({
+					description:
+						"Optional — omit it by default, and pass one only when it genuinely helps. Max 120 chars: a longer reason fails the whole call. Shown in /canon-dump and peer notices, never in the injected prompt.",
+				}),
+			),
+		}),
+		renderCall(args, theme) {
+			return safeToolHeader(theme, "canon_add", () => {
+				const parts: HeaderPart[] = [["accent", ` ${argText(args, "category") ?? "category?"}`]];
+				const text = argText(args, "text");
+				if (text) parts.push(["muted", " — "], ["dim", clip(text)]);
+				return parts;
+			});
+		},
+		async execute(
+			_toolCallId,
+			params: {
+				text: string;
+				model: string;
+				audience: string;
+				category?: string;
+				reason?: string;
+			},
+			_signal,
+			_onUpdate,
+			ctx,
+		) {
+			const model = normalizeModel(params.model ?? "global");
+			const audience = params.audience ?? "all";
+			if (!isAudience(audience)) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Invalid audience "${audience}": use one of ${AUDIENCE_ORDER.join(", ")}.`,
+						},
+					],
+					details: { ok: false },
+				};
+			}
+			if (!modelExists(model, ctx)) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Unknown model "${model}". Omit model for global scope, or use a model id from the registry.`,
+						},
+					],
+					details: { ok: false },
+				};
+			}
+			let categoryId: string;
+			const store = loadStore();
+			if (params.category === undefined) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: categoryRefusal(store, "canon_add", "category is required"),
+						},
+					],
+					details: { ok: false },
+				};
+			}
+			const category = lookupCategory(store, params.category);
+			if (!category.ok) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: categoryRefusal(
+								store,
+								"canon_add",
+								"unknown category",
+								category.detail,
+							),
+						},
+					],
+					details: { ok: false },
+				};
+			}
+			categoryId = category.id;
+			if (
+				params.reason !== undefined &&
+				(typeof params.reason !== "string" || params.reason.length > REASON_MAX)
+			) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Reason too long: max ${REASON_MAX} chars.`,
+						},
+					],
+					details: { ok: false },
+				};
+			}
+			const id = genId(store);
+			const reason = params.reason?.trim() || undefined;
+			store.entries.push({
+				id,
+				text: params.text,
+				model,
+				audience,
+				category: categoryId,
+				...(reason ? { reason } : {}),
+			});
+			saveStore(store);
+			mySessionId = ctx.sessionManager?.getSessionId() ?? mySessionId;
+			publishNotice({
+				op: "add",
+				scope: { model, audience },
+				id,
+				text: params.text,
+				...(reason ? { reason } : {}),
+			});
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Added canon [${id}] (${model} / ${audience}): ${params.text}${reason ? ` — ${reason}` : ""}`,
+					},
+				],
+				details: {
+					ok: true,
+					id,
+					scope: { model, audience },
+					...(reason ? { reason } : {}),
+				},
+			};
+		},
+	});
+
+	const canonRemoveTool = defineTool({
+		name: "canon_remove",
+		label: "Remove canon line",
+		description:
+			"Remove a canon line by its handle id (see /canon-dump for ids). Peers are notified. When testing a removal, remove ONLY ids your own canon_add calls created in this session — an id picked from a listing can be a real rule.",
+		promptSnippet: "Remove a canon line by id",
+		parameters: Type.Object({
+			id: Type.String({
+				description: "Handle id of the canon line to remove (see /canon-dump)",
+			}),
+			reason: Type.Optional(
+				Type.String({
+					description:
+						"Optional — omit it by default. Max 120 chars: a longer reason fails the whole call. Shown in peer notices.",
+				}),
+			),
+		}),
+		renderCall(args, theme) {
+			return safeToolHeader(theme, "canon_remove", () => {
+				const parts: HeaderPart[] = [["accent", ` ${argText(args, "id") ?? "id?"}`]];
+				const reason = argText(args, "reason");
+				if (reason) parts.push(["muted", " — "], ["dim", clip(reason)]);
+				return parts;
+			});
+		},
+		async execute(
+			_toolCallId,
+			params: { id: string; reason?: string },
+			_signal,
+			_onUpdate,
+			ctx,
+		) {
+			if (
+				params.reason !== undefined &&
+				(typeof params.reason !== "string" || params.reason.length > REASON_MAX)
+			) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Reason too long: max ${REASON_MAX} chars.`,
+						},
+					],
+					details: { ok: false },
+				};
+			}
+			const store = loadStore();
+			const idx = store.entries.findIndex((e) => e.id === params.id);
+			if (idx === -1) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `No canon line with id "${params.id}". Use /canon-dump to see current ids.`,
+						},
+					],
+					details: { ok: false },
+				};
+			}
+			const [removed] = store.entries.splice(idx, 1);
+			const reason = params.reason?.trim() || undefined;
+			saveStore(store);
+			mySessionId = ctx.sessionManager?.getSessionId() ?? mySessionId;
+			publishNotice({
+				op: "remove",
+				scope: { model: removed.model, audience: removed.audience },
+				id: removed.id,
+				text: removed.text,
+				...(reason ? { reason } : {}),
+			});
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Removed canon [${removed.id}] (${removed.model} / ${removed.audience}): ${removed.text}`,
+					},
+				],
+				details: { ok: true, id: removed.id },
+			};
+		},
+	});
+
+	const canonEditTool = defineTool({
+		name: "canon_edit",
+		label: "Edit canon line",
+		description:
+			"Replace the text, category, or scope of an existing canon line by its handle id — the id is kept. Peers are notified. The category may be CHANGED but never CLEARED: every edit has to leave the entry filed under a category that exists in the store. An empty category, or an omitted one on an entry that is uncategorised or carries a category the store no longer holds, is REFUSED with the list of valid ids. Omitting category on an entry that already has one keeps it — that is the way to edit text only. When re-scoping, set BOTH model AND audience explicitly — an over-broad scope pushes the rule into sessions where it does not apply (bloat/confusion); see canon_add.",
+		promptSnippet: "Edit a canon line (text, category, scope) by id",
+		parameters: Type.Object({
+			id: Type.String({
+				description: "Handle id of the canon line to edit (see /canon-dump)",
+			}),
+			text: Type.String({ description: "New line text" }),
+			model: Type.Optional(
+				Type.String({
+					description:
+						'New scope model: "global" or a bare model id, e.g. "glm-5.3-flash". Omit to keep unchanged. Scope follows what the entry IS, never coverage: a quirk stays on its model, a general rule belongs on "global".',
+				}),
+			),
+			audience: Type.Optional(
+				Type.String({
+					description:
+						'New audience: "parent", "foreman", "subagent", or "all". Omit to keep unchanged.',
+				}),
+			),
+			category: Type.Optional(
+				Type.String({
+					description:
+						"Category to re-file this entry under — an id (or exact title) that exists. Omit to keep the entry's current category; omitting is NOT a clear, but it is refused when the entry has no valid category to keep. An empty string (a clear) is always refused with the list of valid ids.",
+				}),
+			),
+			reason: Type.Optional(
+				Type.String({
+					description:
+						"Optional — omit it by default. Replaces the stored reason; an empty string clears it. Max 120 chars: a longer reason fails the whole call. Shown in /canon-dump and peer notices.",
+				}),
+			),
+		}),
+		renderCall(args, theme) {
+			return safeToolHeader(theme, "canon_edit", () => {
+				const parts: HeaderPart[] = [["accent", ` ${argText(args, "id") ?? "id?"}`]];
+				const text = argText(args, "text");
+				if (text) parts.push(["muted", " — "], ["dim", clip(text)]);
+				return parts;
+			});
+		},
+		async execute(
+			_toolCallId,
+			params: {
+				id: string;
+				text: string;
+				model?: string;
+				audience?: Audience;
+				category?: string;
+				reason?: string;
+			},
+			_signal,
+			_onUpdate,
+			ctx,
+		) {
+			const store = loadStore();
+			const entry = store.entries.find((e) => e.id === params.id);
+			if (!entry) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `No canon line with id "${params.id}". Use /canon-dump to see current ids.`,
+						},
+					],
+					details: { ok: false },
+				};
+			}
+			const old = entry.text;
+			// The category fence: an edit may CHANGE the category, never remove it, and
+			// the entry must end the call filed under an id the store holds. The three
+			// cases share one refusal shape so the caller always learns the valid ids:
+			//   - omitted on an entry that has a valid category -> kept, unchanged;
+			//   - omitted on an uncategorised (or dangling) entry -> refused, because
+			//     that call is the one that would leave the entry uncategorised;
+			//   - empty, unknown or ambiguous value -> refused.
+			// Refusal comes first, before any other field is touched.
+			if (params.category === undefined) {
+				const current = entry.category;
+				const kept = current ? lookupCategory(store, current) : null;
+				if (!kept?.ok) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: categoryRefusal(
+									store,
+									"canon_edit",
+									current
+										? `entry [${entry.id}] carries category "${current}", which the store does not hold`
+										: `entry [${entry.id}] is uncategorised and this edit would leave it so`,
+								),
+							},
+						],
+						details: { ok: false },
+					};
+				}
+			} else {
+				const next = lookupCategory(store, params.category);
+				if (!next.ok) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: categoryRefusal(
+									store,
+									"canon_edit",
+									params.category === ""
+										? "a category cannot be cleared"
+										: "unknown category",
+									next.detail,
+								),
+							},
+						],
+						details: { ok: false },
+					};
+				}
+				entry.category = next.id;
+			}
+			if (params.audience !== undefined) {
+				if (!isAudience(params.audience)) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Invalid audience "${params.audience}": use one of ${AUDIENCE_ORDER.join(", ")}.`,
+							},
+						],
+						details: { ok: false },
+					};
+				}
+				entry.audience = params.audience;
+			}
+			if (params.model !== undefined) {
+				const model = normalizeModel(params.model);
+				if (!modelExists(model, ctx)) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Unknown model "${model}". Omit model for global scope, or use a model id from the registry.`,
+							},
+						],
+						details: { ok: false },
+					};
+				}
+				entry.model = model;
+			}
+			entry.text = params.text;
+			if (params.reason !== undefined) {
+				const r = params.reason.trim();
+				if (r === "") delete entry.reason;
+				else if (r.length > REASON_MAX) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Reason too long: max ${REASON_MAX} chars.`,
+							},
+						],
+						details: { ok: false },
+					};
+				} else entry.reason = r;
+			}
+			saveStore(store);
+			mySessionId = ctx.sessionManager?.getSessionId() ?? mySessionId;
+			publishNotice({
+				op: "edit",
+				scope: { model: entry.model, audience: entry.audience },
+				id: entry.id,
+				text: params.text,
+				...(entry.reason ? { reason: entry.reason } : {}),
+			});
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Edited canon [${entry.id}] (${entry.model} / ${entry.audience}): "${old}" -> "${params.text}"`,
+					},
+				],
+				details: {
+					ok: true,
+					id: entry.id,
+					scope: { model: entry.model, audience: entry.audience },
+				},
+			};
+		},
+	});
+
+	const canonCategoryTool = defineTool({
+		name: "canon_category",
+		label: "Manage canon categories",
+		description:
+			"Manage canon categories: op add (title, description?) creates one; op edit (id, title?, description?) updates it; op remove (id) deletes it and detaches its entries to Uncategorized; op list shows all. Categories are un-ordered and render as sub-headings inside scope groups in store insertion order.",
+		promptSnippet: "Manage canon categories (add/edit/remove/list)",
+		parameters: Type.Object({
+			op: Type.String({ description: "add | edit | remove | list" }),
+			title: Type.Optional(
+				Type.String({ description: "Category title (add/edit)" }),
+			),
+			description: Type.Optional(
+				Type.String({
+					description:
+						"Category description (add/edit); empty string clears. Shown in /canon-dump only.",
+				}),
+			),
+			id: Type.Optional(Type.String({ description: "Category id (edit/remove)" })),
+		}),
+		renderCall(args, theme) {
+			return safeToolHeader(theme, "canon_category", () => {
+				const parts: HeaderPart[] = [["accent", ` ${argText(args, "op") ?? "op?"}`]];
+				const target = argText(args, "title") ?? argText(args, "id");
+				if (target) parts.push(["dim", ` ${clip(target, 60)}`]);
+				return parts;
+			});
+		},
+		async execute(
+			_toolCallId,
+			params: {
+				op: string;
+				title?: string;
+				description?: string;
+				id?: string;
+			},
+			_signal,
+			_onUpdate,
+			ctx,
+		) {
+			const store = loadStore();
+			if (params.op === "list") {
+				return {
+					content: [
+						{
+							type: "text",
+							text: store.categories.length
+								? store.categories
+										.map(
+											(c) =>
+												`[${c.id}] ${c.title}${c.description ? ` — ${c.description}` : ""}`,
+										)
+										.join("\n")
+								: "(no categories)",
+						},
+					],
+					details: { ok: true, count: store.categories.length },
+				};
+			}
+			if (params.op === "add") {
+				if (!params.title?.trim()) {
+					return {
+						content: [{ type: "text", text: "Title required for category add." }],
+						details: { ok: false },
+					};
+				}
+				const id = genId(store);
+				const title = params.title.trim();
+				const description = params.description?.trim() || undefined;
+				store.categories.push({
+					id,
+					title,
+					...(description ? { description } : {}),
+				});
+				saveStore(store);
+				mySessionId = ctx.sessionManager?.getSessionId() ?? mySessionId;
+				publishNotice({
+					op: "category_add",
+					scope: { model: "global", audience: "all" },
+					id,
+					text: title,
+					...(description ? { reason: description } : {}),
+				});
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Added category [${id}] ${title}`,
+						},
+					],
+					details: { ok: true, id, title },
+				};
+			}
+			if (params.op === "edit") {
+				const cat = store.categories.find((c) => c.id === params.id);
+				if (!cat) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `No category with id "${params.id ?? ""}".`,
+							},
+						],
+						details: { ok: false },
+					};
+				}
+				if (params.title !== undefined && params.title.trim())
+					cat.title = params.title.trim();
+				if (params.description !== undefined) {
+					const d = params.description.trim();
+					if (d === "") delete cat.description;
+					else cat.description = d;
+				}
+				saveStore(store);
+				mySessionId = ctx.sessionManager?.getSessionId() ?? mySessionId;
+				publishNotice({
+					op: "category_edit",
+					scope: { model: "global", audience: "all" },
+					id: cat.id,
+					text: cat.title,
+					...(cat.description ? { reason: cat.description } : {}),
+				});
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Edited category [${cat.id}] ${cat.title}`,
+						},
+					],
+					details: { ok: true, id: cat.id },
+				};
+			}
+			if (params.op === "remove") {
+				const idx = store.categories.findIndex((c) => c.id === params.id);
+				if (idx === -1) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `No category with id "${params.id ?? ""}".`,
+							},
+						],
+						details: { ok: false },
+					};
+				}
+				const [removed] = store.categories.splice(idx, 1);
+				let detached = 0;
+				for (const e of store.entries) {
+					if (e.category === removed.id) {
+						delete e.category;
+						detached++;
+					}
+				}
+				saveStore(store);
+				mySessionId = ctx.sessionManager?.getSessionId() ?? mySessionId;
+				publishNotice({
+					op: "category_remove",
+					scope: { model: "global", audience: "all" },
+					id: removed.id,
+					text: removed.title,
+					...(detached
+						? { reason: `${detached} entries detached to Uncategorized` }
+						: {}),
+				});
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Removed category [${removed.id}] ${removed.title}${detached ? ` (${detached} entries detached to Uncategorized)` : ""}`,
+						},
+					],
+					details: { ok: true, id: removed.id, detached },
+				};
+			}
+			return {
+				content: [
+					{
+						type: "text",
+						text: "Invalid op: use add, edit, remove, or list.",
+					},
+				],
+				details: { ok: false },
+			};
+		},
+	});
+
+	pi.registerTool(canonAddTool);
+	pi.registerTool(canonRemoveTool);
+	pi.registerTool(canonEditTool);
+	pi.registerTool(canonCategoryTool);
+
+	// ---------- /canon-dump command ----------
+
+	pi.registerCommand("canon-dump", {
+		description:
+			"Dump the canon store into this conversation. Optional filter: all | parent | foreman | subagent (audience) or a model id. No filter = full store.",
+		handler: async (args, _ctx) => {
+			const store = loadStore();
+			const filter = (args ?? "").trim().toLowerCase();
+			let entries = store.entries;
+			if (isAudience(filter)) {
+				entries = entries.filter((e) => e.audience === filter);
+			} else if (filter) {
+				const m = normalizeModel(filter);
+				entries = entries.filter((e) => e.model === m || e.model === filter);
+			}
+			const body = entries.length
+				? renderDump(entries, store.categories)
+				: "(empty)";
+			// The drift count, so a store that has lost its categorisation is visible
+			// here as well as in the hook log — reachable without reading the store.
+			const drift = categoryDrift(store);
+			pi.sendMessage(
+				{
+					customType: "canon_dump",
+					content: `## Canon dump${filter ? ` (${filter})` : ""} — ${entries.length}/${store.entries.length} entries · ${drift.uncategorized.length} uncategorised · ${drift.dangling.length} dangling\n\n${body}`,
+					display: true,
+					details: {
+						count: entries.length,
+						filter: filter || undefined,
+						uncategorized: drift.uncategorized.length,
+						dangling: drift.dangling.length,
+					},
+				},
+				{ deliverAs: "steer" },
+			);
+		},
+	});
+
+	// ---------- /canon command ----------
+
+	pi.registerCommand("canon", {
+		description:
+			"Manage canon lines: list | add [--model M] [--audience A] <text> [--reason <why>] | remove <id> [--reason <why>] | edit <id> <text> [--reason <why>] | category list|add|edit|remove",
+		handler: async (args, ctx) => {
+			const tokens = (args ?? "").trim().split(/\s+/).filter(Boolean);
+			const verb = tokens[0] ?? "list";
+			try {
+				if (verb === "list") {
+					const store = loadStore();
+					const model = currentModel();
+					const audienceLabel = sessionLabel(audiences);
+					const body = store.entries.length
+						? renderDump(store.entries, store.categories)
+						: "(empty)";
+					ctx.ui.notify(
+						`Canon — active model: ${model} (${audienceLabel})\n\n${body}`,
+						"info",
+					);
+					return;
+				}
+				const store = loadStore();
+				if (verb === "category") {
+					const sub = tokens[1];
+					if (sub === "list") {
+						ctx.ui.notify(
+							store.categories.length
+								? store.categories
+										.map(
+											(c) =>
+												`[${c.id}] ${c.title}${c.description ? ` — ${c.description}` : ""}`,
+										)
+										.join("\n")
+								: "(no categories)",
+							"info",
+						);
+						return;
+					}
+					if (sub === "add") {
+						const di = tokens.indexOf("--desc");
+						const title = tokens
+							.slice(2, di === -1 ? undefined : di)
+							.join(" ")
+							.trim();
+						const description =
+							di === -1 ? undefined : tokens.slice(di + 1).join(" ");
+						if (!title) {
+							ctx.ui.notify(
+								"Usage: /canon category add <title> [--desc <description>]",
+								"error",
+							);
+							return;
+						}
+						if (description && description.length > REASON_MAX) {
+							ctx.ui.notify(`Description too long: max ${REASON_MAX} chars`, "error");
+							return;
+						}
+						const id = genId(store);
+						store.categories.push({
+							id,
+							title,
+							...(description ? { description } : {}),
+						});
+						saveStore(store);
+						publishNotice({
+							op: "category_add",
+							scope: { model: "global", audience: "all" },
+							id,
+							text: title,
+							...(description ? { reason: description } : {}),
+						});
+						ctx.ui.notify(`Added category [${id}] ${title}`, "info");
+						return;
+					}
+					if (sub === "edit") {
+						const id = tokens[2];
+						const cat = store.categories.find((c) => c.id === id);
+						if (!cat) {
+							ctx.ui.notify(`No category with id "${id ?? ""}"`, "error");
+							return;
+						}
+						const di = tokens.indexOf("--desc");
+						const newTitle = tokens
+							.slice(3, di === -1 ? undefined : di)
+							.join(" ")
+							.trim();
+						if (newTitle) cat.title = newTitle;
+						if (di !== -1) {
+							const description = tokens.slice(di + 1).join(" ");
+							if (description.length > REASON_MAX) {
+								ctx.ui.notify(`Description too long: max ${REASON_MAX} chars`, "error");
+								return;
+							}
+							if (description === "") delete cat.description;
+							else cat.description = description;
+						}
+						saveStore(store);
+						publishNotice({
+							op: "category_edit",
+							scope: { model: "global", audience: "all" },
+							id: cat.id,
+							text: cat.title,
+							...(cat.description ? { reason: cat.description } : {}),
+						});
+						ctx.ui.notify(`Edited category [${cat.id}] ${cat.title}`, "info");
+						return;
+					}
+					if (sub === "remove" || sub === "rm") {
+						const id = tokens[2];
+						const idx = store.categories.findIndex((c) => c.id === id);
+						if (!id || idx === -1) {
+							ctx.ui.notify(`No category with id "${id ?? ""}"`, "error");
+							return;
+						}
+						const [removed] = store.categories.splice(idx, 1);
+						let detached = 0;
+						for (const e of store.entries) {
+							if (e.category === removed.id) {
+								delete e.category;
+								detached++;
+							}
+						}
+						saveStore(store);
+						publishNotice({
+							op: "category_remove",
+							scope: { model: "global", audience: "all" },
+							id: removed.id,
+							text: removed.title,
+							...(detached
+								? { reason: `${detached} entries detached to Uncategorized` }
+								: {}),
+						});
+						ctx.ui.notify(
+							`Removed category [${removed.id}]${detached ? ` (${detached} detached)` : ""}`,
+							"info",
+						);
+						return;
+					}
+					ctx.ui.notify(
+						"Usage: /canon category list | add <title> [--desc <d>] | edit <id> [<title>] [--desc <d>] | remove <id>",
+						"error",
+					);
+					return;
+				}
+				if (verb === "add") {
+					let model = "global";
+					let audience: Audience = "all";
+					let reason: string | undefined;
+					const rest: string[] = [];
+					for (let i = 1; i < tokens.length; i++) {
+						if (tokens[i] === "--model" && tokens[i + 1])
+							model = normalizeModel(tokens[++i]);
+						else if (tokens[i] === "--audience" && tokens[i + 1]) {
+							const a = tokens[++i];
+							if (isAudience(a)) audience = a;
+							else {
+								ctx.ui.notify(
+									`Invalid audience "${a}": use one of ${AUDIENCE_ORDER.join(", ")}`,
+									"error",
+								);
+								return;
+							}
+						} else if (tokens[i] === "--reason") {
+							reason = tokens.slice(i + 1).join(" ");
+							break;
+						} else rest.push(tokens[i]);
+					}
+					const text = rest.join(" ");
+					if (!text) {
+						ctx.ui.notify(
+							"Usage: /canon add [--model M] [--audience A] <text> [--reason <why>]",
+							"error",
+						);
+						return;
+					}
+					if (reason && reason.length > REASON_MAX) {
+						ctx.ui.notify(`Reason too long: max ${REASON_MAX} chars`, "error");
+						return;
+					}
+					const id = genId(store);
+					store.entries.push({
+						id,
+						text,
+						model,
+						audience,
+						...(reason ? { reason } : {}),
+					});
+					saveStore(store);
+					publishNotice({
+						op: "add",
+						scope: { model, audience },
+						id,
+						text,
+						...(reason ? { reason } : {}),
+					});
+					ctx.ui.notify(
+						`Added canon [${id}] (${model} / ${audience})${reason ? ` — ${reason}` : ""}`,
+						"info",
+					);
+					return;
+				}
+				if (verb === "remove" || verb === "rm") {
+					const id = tokens[1];
+					const reason =
+						tokens
+							.slice(2)
+							.join(" ")
+							.replace(/^--reason\s*/, "") || undefined;
+					if (reason && reason.length > REASON_MAX) {
+						ctx.ui.notify(`Reason too long: max ${REASON_MAX} chars`, "error");
+						return;
+					}
+					const idx = store.entries.findIndex((e) => e.id === id);
+					if (!id || idx === -1) {
+						ctx.ui.notify(`No canon line with id "${id ?? ""}"`, "error");
+						return;
+					}
+					const [removed] = store.entries.splice(idx, 1);
+					saveStore(store);
+					publishNotice({
+						op: "remove",
+						scope: { model: removed.model, audience: removed.audience },
+						id: removed.id,
+						text: removed.text,
+						...(reason ? { reason } : {}),
+					});
+					ctx.ui.notify(`Removed canon [${removed.id}]`, "info");
+					return;
+				}
+				if (verb === "edit") {
+					const id = tokens[1];
+					let text: string;
+					let reason: string | undefined;
+					const ri = tokens.indexOf("--reason");
+					if (ri === -1) {
+						text = tokens.slice(2).join(" ");
+					} else {
+						text = tokens.slice(2, ri).join(" ");
+						reason = tokens.slice(ri + 1).join(" ");
+					}
+					const entry = store.entries.find((e) => e.id === id);
+					if (!id || !entry || !text) {
+						ctx.ui.notify(
+							"Usage: /canon edit <id> <new text> [--reason <why>]",
+							"error",
+						);
+						return;
+					}
+					entry.text = text;
+					if (reason !== undefined) {
+						if (reason.length > REASON_MAX) {
+							ctx.ui.notify(`Reason too long: max ${REASON_MAX} chars`, "error");
+							return;
+						}
+						if (reason === "") delete entry.reason;
+						else entry.reason = reason;
+					}
+					saveStore(store);
+					publishNotice({
+						op: "edit",
+						scope: { model: entry.model, audience: entry.audience },
+						id: entry.id,
+						text,
+						...(entry.reason ? { reason: entry.reason } : {}),
+					});
+					ctx.ui.notify(`Edited canon [${entry.id}]`, "info");
+					return;
+				}
+				ctx.ui.notify(
+					"Usage: /canon list | add [--model M] [--audience A] <text> [--reason <why>] | remove <id> [--reason <why>] | edit <id> <text> [--reason <why>]",
+					"error",
+				);
+			} catch (err) {
+				ctx.ui.notify(
+					`canon: ${err instanceof Error ? err.message : String(err)}`,
+					"error",
+				);
+			}
+		},
+	});
+}