@possumtech/rummy 0.3.1 → 0.5.0

package/src/plugins/ask_user/ask_user.js

@@ -7,8 +7,8 @@ export default class AskUser {
 		this.#core = core;
 		core.registerScheme();
 		core.on("handler", this.handler.bind(this));
-		core.on("full", this.full.bind(this));
-		core.on("summary", this.summary.bind(this));
+		core.on("promoted", this.full.bind(this));
+		core.on("demoted", this.summary.bind(this));
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.ask_user = docs;
 			return docsMap;

package/src/plugins/ask_user/ask_userDoc.js

@@ -2,27 +2,24 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: question attr + options in body
-	['## <ask_user question="[Question?]">[option1; option2; ...]</ask_user>'],
-
-	// --- Constraints FIRST: frames correct usage before examples
+	[
+		'## <ask_user question="[Question?]">[option1; option2; ...]</ask_user> - Ask the user a question',
+	],
 	[
 		"* YOU SHOULD use for decisions, preferences, or approvals the user must make",
-		"Positive framing. Shows what ask_user IS for, not just what it isn't.",
+		"Positive framing. Shows what ask_user IS for.",
 	],
 	[
-		"* YOU SHOULD use <get> to find information before asking the user",
-		"Gentle redirect. Encourages self-sufficiency without forbidding interaction.",
+		"* YOU SHOULD use <get></get> to find information before asking the user",
+		"Gentle redirect. Encourages self-sufficiency.",
 	],
-
-	// --- Examples: genuine decision points where user input is valuable
 	[
 		'Example: <ask_user question="Which test framework?">Mocha; Jest; Node Native</ask_user>',
 		"Preference decision. Model truly cannot know this without asking.",
 	],
 	[
 		'Example: <ask_user question="Deploy to staging or production?">staging; production</ask_user>',
-		"Consequential action. Shows ask_user for high-stakes choices.",
+		"Consequential action. High-stakes choice.",
 	],
 ];
 

package/src/plugins/budget/README.md

@@ -2,30 +2,40 @@
 
 Context ceiling enforcement.
 
-## Files
+## Design
 
-- **budget.js** — Plugin. Pre-LLM enforce, BudgetGuard activation.
-- **BudgetGuard.js** — Write-layer gate. Installed on KnownStore during
-  dispatch. Checks token delta on every upsert, promote, and body update.
+Ceiling = `floor(contextSize × 0.9)`. The 10% headroom is the system's
+operating room for graceful overflow handling. No per-write gating —
+tools run uninterrupted. Enforcement happens at boundaries.
 
-## Registration
+## Enforcement Points
 
-- **Hook**: `hooks.budget.enforce` — pre-LLM ceiling check.
-- **Hook**: `hooks.budget.activate(store, contextSize, assembledTokens)` — install guard.
-- **Hook**: `hooks.budget.deactivate(store)` — remove guard.
+1. **Pre-LLM enforce** (`budget.enforce`): checks assembled context
+   before the LLM call. If over ceiling → Prompt Demotion (summarize
+   the incoming prompt). Model runs in the headroom.
 
-## Budget Contract
+2. **Post-dispatch Turn Demotion**: after all tools dispatch, check
+   context. If over ceiling → demote ALL entries from this turn
+   (every scheme except `budget`/`system`/`prompt`/`instructions`,
+   and 4xx error states stay promoted). Write `budget://` entry with
+   directive to demote irrelevant entries and promote fewer next time.
+   Model sees it next turn and adapts.
 
-`contextSize` is the ceiling. `countTokens()` is the measurement.
-Over = 413. Under = 200. No margins.
+3. **LLM rejection** (`isContextExceeded`): turn-1 token estimate
+   drift causes LLM to reject. Same demotion pattern.
 
-## BudgetGuard
+4. **AgentLoop recovery**: pre-LLM 413 that Prompt Demotion can't
+   resolve. Batch-demote all full entries, budget entry, model gets
+   recovery turns. 3 strikes without progress → hard 413 to client.
+   Only path where 413 reaches the client.
 
-Installed on KnownStore by TurnExecutor before dispatch, cleared in
-`finally`. Gates `upsert()`, `promoteByPattern()`, `updateBodyByPattern()`.
+## Files
 
-Exemptions: `status >= 400` (error entries), `model_visible = 0` (audit),
-`fidelity = "archive"` (not in context).
+- **budget.js** — Plugin. Pre-LLM enforce hook.
+- **BudgetGuard.js** — `BudgetExceeded` error type, `delta` utility.
 
-On first violation: `BudgetExceeded` thrown, guard trips, all subsequent
-writes fail. TurnExecutor catches per-tool, writes 413 result entry.
+## Registration
+
+- **Hook**: `hooks.budget.enforce` — pre-LLM ceiling check.
+- **Scheme**: `budget://` — logging category, model-visible. `onView`
+  renders body at all fidelity levels (demoted shows full content).

package/src/plugins/budget/budget.js

@@ -1,5 +1,8 @@
 import { countTokens } from "../../agent/tokens.js";
 
+const CEILING_RATIO = Number(process.env.RUMMY_BUDGET_CEILING);
+if (!CEILING_RATIO) throw new Error("RUMMY_BUDGET_CEILING must be set");
+
 function measureMessages(messages) {
 	return messages.reduce((sum, m) => sum + countTokens(m.content), 0);
 }
@@ -17,6 +20,7 @@ export default class Budget {
 		core.hooks.tools.onView("budget", (entry) => entry.body);
 		core.hooks.budget = {
 			enforce: this.enforce.bind(this),
+			postDispatch: this.postDispatch.bind(this),
 		};
 	}
 
@@ -25,8 +29,6 @@ export default class Budget {
 			return { messages, rows, demoted: [], assembledTokens: 0, status: 200 };
 		}
 
-		// Prefer actual prompt_tokens from the last API response — the estimate
-		// from measureMessages can be wildly off for structured/XML-heavy content.
 		const assembledTokens =
 			lastPromptTokens > 0 ? lastPromptTokens : measureMessages(messages);
 
@@ -34,7 +36,7 @@ export default class Budget {
 			`[RUMMY] Budget enforce: ${assembledTokens} tokens (${lastPromptTokens > 0 ? "actual" : "estimated"}), ceiling ${contextSize}, ${rows.length} rows`,
 		);
 
-		const ceiling = Math.floor(contextSize * 0.9);
+		const ceiling = Math.floor(contextSize * CEILING_RATIO);
 		if (assembledTokens > ceiling) {
 			const overflow = assembledTokens - ceiling;
 			console.warn(
@@ -52,4 +54,79 @@ export default class Budget {
 
 		return { messages, rows, demoted: [], assembledTokens, status: 200 };
 	}
+
+	async postDispatch({
+		contextSize,
+		messages,
+		rows,
+		runId,
+		loopId,
+		turn,
+		db,
+		store,
+	}) {
+		if (!contextSize) return null;
+
+		const postBudget = await this.enforce({
+			contextSize,
+			messages,
+			rows,
+			lastPromptTokens: 0,
+		});
+
+		if (postBudget.status !== 413) return null;
+
+		// Demote this turn's entries
+		const demotedEntries = await db.demote_turn_entries.all({
+			run_id: runId,
+			turn,
+		});
+
+		// Also demote the prompt
+		const promptRow = rows.find((r) => r.scheme === "prompt");
+		if (promptRow) {
+			await store.setFidelity(runId, promptRow.path, "demoted");
+		}
+
+		// Rewrite get-result bodies — the get handler claimed "promoted" success
+		// before this panic ran. Without rewriting, the model reads conflicting
+		// signals next turn (status=413 but body says "promoted").
+		for (const entry of demotedEntries) {
+			if (!entry.path.startsWith("get://")) continue;
+			await db.resolve_known_entry.run({
+				run_id: runId,
+				path: entry.path,
+				body: `Demoted by budget. See budget://${loopId}/${turn}.`,
+				status: 413,
+			});
+		}
+
+		// Write budget entry — terse, actionable. Path list dropped since
+		// demoted entries already render at fidelity="demoted" in <knowns>/<files>.
+		// "tokens remaining" dropped too — the number was over-optimistic (it
+		// treated re-demoted files as freeing their full-body tokens when their
+		// demoted-view renderings return to baseline). Model reads the truthful
+		// remaining in next turn's progress line.
+		//
+		// The 50% rule is the key directive: it forces the model to sum
+		// promotion costs (which is the behavior we want), and the threshold
+		// gives a concrete ceiling for the next try. Twofer — abiding by the
+		// rule requires budget awareness as a side effect.
+		const ceiling = Math.floor(contextSize * CEILING_RATIO);
+		const totalDemoted = demotedEntries.reduce((s, r) => s + r.tokens, 0);
+		const body = [
+			`413 Token Budget Error: overflowed by ${postBudget.overflow} tokens. Token Budget: ${ceiling}.`,
+			`Your ${demotedEntries.length} promotions from last turn (${totalDemoted} tokens total) were demoted to fit.`,
+			`Required: sum the tokens="N" of your promotions and new entries before emitting. A single turn must add no more than 50% of remaining Token Budget.`,
+		].join("\n");
+
+		await store.upsert(runId, turn, `budget://${loopId}/${turn}`, body, 413, {
+			loopId,
+		});
+
+		return {
+			target: ceiling,
+			promptPath: promptRow?.path ?? null,
+		};
+	}
 }

package/src/plugins/budget/recovery.js

@@ -0,0 +1,47 @@
+/**
+ * Pure recovery state transition — exported for testing.
+ *
+ * @param {object|null} recovery  Current recovery state.
+ * @param {{ assembledTokens: number, budgetRecovery?: { target: number, promptPath: string|null } }} result
+ * @returns {{ next: object|null, action: null|'restore'|'hard413', promptPath: string|null }}
+ */
+export function advanceRecovery(recovery, result) {
+	// Initialise or update recovery state from a new Turn Demotion event.
+	if (result.budgetRecovery) {
+		if (!recovery) {
+			recovery = {
+				target: result.budgetRecovery.target,
+				promptPath: result.budgetRecovery.promptPath,
+				strikes: 0,
+				lastTokens: result.assembledTokens,
+			};
+		} else {
+			// Re-overflow during recovery: tighten target, don't count as strike.
+			recovery = {
+				...recovery,
+				target: Math.min(recovery.target, result.budgetRecovery.target),
+			};
+		}
+	}
+
+	if (recovery === null) return { next: null, action: null, promptPath: null };
+
+	const current = result.assembledTokens;
+
+	if (current <= recovery.target) {
+		return { next: null, action: "restore", promptPath: recovery.promptPath };
+	}
+
+	const noProgress = current >= recovery.lastTokens && !result.budgetRecovery;
+	const strikes = noProgress ? recovery.strikes + 1 : 0;
+
+	if (strikes >= 3) {
+		return { next: null, action: "hard413", promptPath: null };
+	}
+
+	return {
+		next: { ...recovery, strikes, lastTokens: current },
+		action: null,
+		promptPath: null,
+	};
+}

package/src/plugins/cp/cp.js

@@ -8,8 +8,8 @@ export default class Cp {
 		this.#core = core;
 		core.registerScheme();
 		core.on("handler", this.handler.bind(this));
-		core.on("full", this.full.bind(this));
-		core.on("summary", this.summary.bind(this));
+		core.on("promoted", this.full.bind(this));
+		core.on("demoted", this.summary.bind(this));
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.cp = docs;
 			return docsMap;
@@ -19,7 +19,7 @@ export default class Cp {
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const { path, to } = entry.attributes;
-		const VALID = { stored: 1, summary: 1, index: 1, full: 1, archive: 1 };
+		const VALID = { promoted: 1, demoted: 1, archived: 1 };
 		const fidelity = VALID[entry.attributes.fidelity]
 			? entry.attributes.fidelity
 			: undefined;
@@ -53,7 +53,7 @@ export default class Cp {
 		return `# cp ${entry.attributes.from || ""} ${entry.attributes.to || ""}`;
 	}
 
-	summary(entry) {
-		return this.full(entry);
+	summary() {
+		return "";
 	}
 }

package/src/plugins/cp/cpDoc.js

@@ -2,27 +2,14 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: path attr = source, body = destination
 	['## <cp path="[source]">[destination]</cp> - Copy a file or entry'],
-
-	// --- Examples: single copy, glob batch, cross-scheme
 	[
 		'Example: <cp path="src/config.js">src/config.backup.js</cp>',
 		"Simple file copy. Path = source, body = destination.",
 	],
 	[
 		'Example: <cp path="known://plan_*">known://archive_</cp>',
-		"Glob batch copy across known entries. Shows pattern operations on cp.",
-	],
-
-	// --- Constraints
-	[
-		"* Source path accepts patterns: `src/*.js`, `known://draft_*`",
-		"Pattern support. Distributes glob teaching beyond get.",
-	],
-	[
-		"* Use `preview` to check matches before bulk copy",
-		"Safety pattern consistent with get and rm preview.",
+		"Glob batch copy across known entries.",
 	],
 ];
 

package/src/plugins/engine/engine.sql

@@ -6,7 +6,7 @@ FROM known_entries AS ke
 JOIN schemes AS s ON s.name = COALESCE(ke.scheme, 'file')
 WHERE
 	ke.run_id = :run_id
-	AND ke.fidelity IN ('full', 'summary')
+	AND ke.fidelity IN ('promoted', 'demoted')
 	AND s.model_visible = 1
 ORDER BY ke.turn, ke.refs, ke.tokens DESC;
 

package/src/plugins/env/env.js

@@ -7,8 +7,8 @@ export default class Env {
 		this.#core = core;
 		core.registerScheme();
 		core.on("handler", this.handler.bind(this));
-		core.on("full", this.full.bind(this));
-		core.on("summary", this.summary.bind(this));
+		core.on("promoted", this.full.bind(this));
+		core.on("demoted", this.summary.bind(this));
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.env = docs;
 			return docsMap;
@@ -27,7 +27,7 @@ export default class Env {
 		return `# env ${entry.attributes.command || ""}\n${entry.body}`;
 	}
 
-	summary(entry) {
-		return entry.attributes.command || "";
+	summary() {
+		return "";
 	}
 }

package/src/plugins/env/envDoc.js

@@ -2,10 +2,7 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax
 	["## <env>[command]</env> - Run an exploratory shell command"],
-
-	// --- Examples: version check and git status — safe, read-only commands
 	[
 		"Example: <env>npm --version</env>",
 		"Version check. Safe, no side effects.",
@@ -14,15 +11,13 @@ const LINES = [
 		"Example: <env>git log --oneline -5</env>",
 		"Git history. Shows env for read-only investigation.",
 	],
-
-	// --- Constraints: hard boundaries
 	[
-		'* YOU MUST NOT use <env/> to read or list files — use <get path="*" preview/> instead',
-		"Prevents cat/ls through shell. Forces file access through get for proper tracking.",
+		'* YOU MUST NOT use <env></env> to read or list files — use <get path="*"/> instead',
+		"Prevents cat/ls through shell. Forces file access through get.",
 	],
 	[
-		"* YOU MUST use <sh/> for commands with side effects",
-		"Separates exploration from action. env = observe, sh = mutate.",
+		"* YOU MUST NOT use <env></env> for commands with side effects",
+		"Separates exploration from action. env = observe only.",
 	],
 ];
 

package/src/plugins/file/file.js

@@ -16,13 +16,8 @@ export default class File {
 		this.#core = core;
 		// "file" scheme covers bare paths (scheme IS NULL in DB)
 		core.registerScheme({ category: "data" });
-		core.registerScheme({ name: "http", category: "data" });
-		core.registerScheme({ name: "https", category: "data" });
-		core.on("full", this.full.bind(this));
-		core.on("summary", this.summary.bind(this));
-		// Default identity views for http/https — rummy.web overrides these
-		core.hooks.tools.onView("http", (entry) => entry.body);
-		core.hooks.tools.onView("https", (entry) => entry.body);
+		core.on("promoted", this.full.bind(this));
+		core.on("demoted", this.summary.bind(this));
 	}
 
 	full(entry) {

package/src/plugins/get/get.js

@@ -9,8 +9,8 @@ export default class Get {
 		this.#core = core;
 		core.registerScheme();
 		core.on("handler", this.handler.bind(this));
-		core.on("full", this.full.bind(this));
-		core.on("summary", this.summary.bind(this));
+		core.on("promoted", this.full.bind(this));
+		core.on("demoted", this.summary.bind(this));
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.get = docs;
 			return docsMap;
@@ -29,6 +29,7 @@ export default class Get {
 		}
 		const normalized = KnownStore.normalizePath(target);
 		const bodyFilter = entry.attributes.body || null;
+		const preview = entry.attributes.preview !== undefined;
 		const isPattern = bodyFilter || normalized.includes("*");
 
 		const line =
@@ -46,6 +47,25 @@ export default class Get {
 			bodyFilter,
 		);
 
+		// Preview — list matches with their full-body token costs. No promotion,
+		// no fidelity change, no Token Budget spent. Model uses this to plan
+		// which entries to actually promote. getDoc promises this behavior; the
+		// prior implementation silently promoted anyway, burning the Token Budget
+		// on entries the model thought it was only inspecting.
+		if (preview) {
+			await storePatternResult(
+				store,
+				runId,
+				turn,
+				"get",
+				target,
+				bodyFilter,
+				matches,
+				{ preview: true, loopId, attributes: { path: target } },
+			);
+			return;
+		}
+
 		// Partial read — no fidelity promotion, returns a line slice as the log item.
 		if (line !== null || limit !== null) {
 			if (isPattern) {
@@ -55,7 +75,7 @@ export default class Get {
 					entry.resultPath,
 					"line/limit requires a single path, not a glob or body filter",
 					400,
-					{ loopId },
+					{ loopId, attributes: { path: target } },
 				);
 				return;
 			}
@@ -66,7 +86,7 @@ export default class Get {
 					entry.resultPath,
 					`${target} not found`,
 					200,
-					{ loopId },
+					{ loopId, attributes: { path: target } },
 				);
 				return;
 			}
@@ -84,17 +104,15 @@ export default class Get {
 				entry.resultPath,
 				`${header}\n${slice}`,
 				200,
-				{ loopId },
+				{ loopId, attributes: { path: target } },
 			);
 			return;
 		}
 
 		const VALID_FIDELITY = {
-			stored: 1,
-			summary: 1,
-			index: 1,
-			full: 1,
-			archive: 1,
+			demoted: 1,
+			promoted: 1,
+			archived: 1,
 		};
 		const fidelityAttr = VALID_FIDELITY[entry.attributes.fidelity]
 			? entry.attributes.fidelity
@@ -115,17 +133,18 @@ export default class Get {
 				target,
 				bodyFilter,
 				matches,
-				{ loopId },
+				{ loopId, attributes: { path: target } },
 			);
 		} else {
-			const total = matches.reduce((s, m) => s + m.tokens_full, 0);
+			const total = matches.reduce((s, m) => s + m.tokens, 0);
 			const paths = matches.map((m) => m.path).join(", ");
 			const body =
 				matches.length > 0
-					? `${paths} loaded into <knowns> (${total} tokens)`
+					? `${paths} promoted (${total} tokens)`
 					: `${target} not found`;
 			await store.upsert(runId, turn, entry.resultPath, body, 200, {
 				loopId,
+				attributes: { path: target },
 			});
 		}
 	}

package/src/plugins/get/getDoc.js

@@ -2,50 +2,32 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: body-form is the primary invocation (simplest)
-	["## <get>[path/to/file]</get> - Load a file or entry into context"],
-
-	// --- Examples: 3 examples covering single file, known recall, and content search
-	[
-		"Example: <get>src/app.js</get>",
-		"Simplest form. Body = path. Teaches that get is the default read tool.",
-	],
-	[
-		'Example: <get path="known://*">auth</get>',
-		"Keyword recall: glob in path, search term in body. Cross-scheme hedberg pattern.",
-	],
-	[
-		'Example: <get path="src/**/*.js" preview>authentication</get>',
-		"Full pattern: recursive glob + preview + content filter. Shows all 3 features at once. Body is a filter keyword, never file content.",
-	],
-
-	// --- Partial read: line/limit — show before constraints so model sees it as a first-class pattern
-	[
-		'Example: <get path="src/agent/AgentLoop.js" line="644" limit="80"/>',
-		"Partial read. Returns lines 644–723 as the log item without promoting the entry to full. Use summary fidelity to find line numbers, then target the symbol directly.",
-	],
-
-	// --- Constraints: RFC-style. Each prevents a specific failure mode.
-	[
-		"* Paths accept patterns: `src/**/*.js`, `known://api_*`",
-		"Reinforces picomatch patterns work everywhere, not just in examples.",
-	],
-	[
-		"* `preview` shows matches without loading into context",
-		"Budget-awareness. Without this, models load everything and blow context.",
-	],
-	[
-		"* Body text filters results by content match",
-		"Generalizes examples 2-3. Body = filter, not just path.",
-	],
-	[
-		"* `line` and `limit` read a slice without promoting — patterns not allowed",
-		"The no-promotion constraint is what makes partial read safe: context budget is unaffected.",
-	],
-	[
-		'* Use <set path="..." fidelity="archive"/> to remove loaded content from context',
-		"Lifecycle: get→set. Load, read, archive. Prevents context hoarding.",
-	],
+  ["## <get>[path/to/file]</get> - Promote an entry"],
+  ["Example: <get>src/app.js</get>", "Simplest form. Body = path."],
+  [
+    'Example: <get path="known://*">auth</get>',
+    "Keyword recall: glob in path, search term in body.",
+  ],
+  [
+    'Example: <get path="src/**/*.js">authentication</get>',
+    "Full pattern: recursive glob + content filter.",
+  ],
+  [
+    'Example: <get path="src/agent/AgentLoop.js" line="644" limit="80"/>',
+    "Partial read. Returns lines 644–723 without promoting.",
+  ],
+  [
+    "* Paths accept patterns: `src/**/*.js`, `known://api_*`",
+    "Reinforces picomatch patterns work everywhere.",
+  ],
+  [
+    "* Body text filters results by content match",
+    "Body = filter, not just path.",
+  ],
+  [
+    "* `line` and `limit` read a slice without promoting the entry, which costs as many tokens as the slice contains.",
+    "Partial read is safe: context budget unaffected.",
+  ],
 ];
 
 export default LINES.map(([text]) => text).join("\n");

package/src/plugins/helpers.js

@@ -10,13 +10,13 @@ export async function storePatternResult(
 	path,
 	bodyFilter,
 	matches,
-	{ preview = false, loopId = null } = {},
+	{ preview = false, loopId = null, attributes = null } = {},
 ) {
 	const slug = await store.slugPath(runId, scheme, path);
 	const filter = bodyFilter ? ` body="${bodyFilter}"` : "";
-	const total = matches.reduce((s, m) => s + m.tokens_full, 0);
-	const listing = matches.map((m) => `${m.path} (${m.tokens_full})`).join("\n");
+	const total = matches.reduce((s, m) => s + m.tokens, 0);
+	const listing = matches.map((m) => `${m.path} (${m.tokens})`).join("\n");
 	const prefix = preview ? "PREVIEW " : "";
 	const body = `${prefix}${scheme} path="${path}"${filter}: ${matches.length} matched (${total} tokens)\n${listing}`;
-	await store.upsert(runId, turn, slug, body, 200, { loopId });
+	await store.upsert(runId, turn, slug, body, 200, { loopId, attributes });
 }

package/src/plugins/instructions/instructions.js

@@ -10,7 +10,7 @@ export default class Instructions {
 
 	constructor(core) {
 		this.#core = core;
-		core.on("full", this.full.bind(this));
+		core.on("promoted", this.full.bind(this));
 		core.on("turn.started", this.onTurnStarted.bind(this));
 	}
 
@@ -33,20 +33,22 @@ export default class Instructions {
 		const activeTools = attrs.toolSet
 			? new Set(attrs.toolSet)
 			: new Set(this.#core.hooks.tools.names);
-		const sorted = this.#core.hooks.tools.names.filter((n) =>
-			activeTools.has(n),
-		);
-		const tools = sorted.join(", ");
-		let prompt = preamble.replace("[%TOOLS%]", tools);
 		const toolDocs = await this.#core.hooks.instructions.toolDocs.filter(
 			{},
 			{ toolSet: activeTools },
 		);
+		// Hidden tools are excluded at the registry level (see ToolRegistry).
+		const sorted = this.#core.hooks.tools.advertisedNames.filter((n) =>
+			activeTools.has(n),
+		);
+		const tools = sorted.join(", ");
 		const docsText = sorted
 			.filter((key) => toolDocs[key])
 			.map((key) => toolDocs[key])
 			.join("\n\n");
-		if (docsText) prompt += `\n\n${docsText}`;
+		let prompt = preamble
+			.replace("[%TOOLS%]", tools)
+			.replace("[%TOOLDOCS%]", docsText);
 		if (attrs.persona) prompt += `\n\n## Persona\n\n${attrs.persona}`;
 		return prompt;
 	}