@possumtech/rummy 2.0.0 → 2.1.0

package/src/agent/budget.js

@@ -1,46 +1,23 @@
+import config from "./config.js";
 import { countTokens } from "./tokens.js";
 
-const CEILING_RATIO = Number(process.env.RUMMY_BUDGET_CEILING);
-if (!CEILING_RATIO) throw new Error("RUMMY_BUDGET_CEILING must be set");
+const CEILING_RATIO = config.BUDGET_CEILING;
 
 export function ceiling(contextSize) {
 	return Math.floor(contextSize * CEILING_RATIO);
 }
 
-/**
- * Sum assembled-message token counts.
- * Used by the budget enforce gate, which has the real messages.
- */
+// Sum assembled-message token counts; used by the budget enforce gate.
 export function measureMessages(messages) {
 	return messages.reduce((sum, m) => sum + countTokens(m.content), 0);
 }
 
-/**
- * Sum projected row body token counts — what's actually in the packet
- * for each entry at its current visibility. Used by prompt.js while
- * generating the <prompt> tag (before assembly completes).
- */
+// Sum projected row body token counts; used by prompt.js pre-assembly.
 export function measureRows(rows) {
 	return rows.reduce((sum, r) => sum + countTokens(r.body), 0);
 }
 
-/**
- * Single source of truth for budget numbers. Every caller — prompt.js
- * generating the <prompt> tag, budget.js enforcing the ceiling,
- * AgentLoop emitting telemetry — passes in its own measured totalTokens
- * and reads the same object back. No fallbacks: callers produce the
- * measurement they have.
- *
- * Returns:
- *   ceiling     — floor(contextSize × CEILING_RATIO), the hard wall
- *   totalTokens — echoed back (the full packet size the caller measured)
- *   tokenUsage  — same as totalTokens. Kept under this name for the
- *                 `<prompt tokenUsage="N">` attribute on the wire. Must
- *                 agree with totalTokens so the model's math is honest.
- *   tokensFree  — ceiling − totalTokens (floor 0)
- *   overflow    — max(0, totalTokens − ceiling)
- *   ok          — overflow === 0
- */
+// Single source of truth for budget numbers; tokenUsage echoes totalTokens for the wire attribute.
 export function computeBudget({ contextSize, totalTokens }) {
 	const cap = ceiling(contextSize);
 	const tokensFree = Math.max(0, cap - totalTokens);

package/src/agent/config.js

@@ -0,0 +1,38 @@
+// Validates required RUMMY_* env at module load; defaults in .env.example.
+
+const REQUIRED = {
+	BUDGET_CEILING: { env: "RUMMY_BUDGET_CEILING", parse: Number },
+	LLM_DEADLINE: { env: "RUMMY_LLM_DEADLINE", parse: Number },
+	LLM_MAX_BACKOFF: { env: "RUMMY_LLM_MAX_BACKOFF", parse: Number },
+	FETCH_TIMEOUT: { env: "RUMMY_FETCH_TIMEOUT", parse: Number },
+	MAX_STRIKES: { env: "RUMMY_MAX_STRIKES", parse: Number },
+	MIN_CYCLES: { env: "RUMMY_MIN_CYCLES", parse: Number },
+	MAX_CYCLE_PERIOD: { env: "RUMMY_MAX_CYCLE_PERIOD", parse: Number },
+	RUN_TIMEOUT: { env: "RUMMY_RUN_TIMEOUT", parse: Number },
+	PLUGINS_LOAD_TIMEOUT: { env: "RUMMY_PLUGINS_LOAD_TIMEOUT", parse: Number },
+	THINK: { env: "RUMMY_THINK", parse: (v) => v },
+};
+
+const config = {};
+const missing = [];
+for (const [key, spec] of Object.entries(REQUIRED)) {
+	const raw = process.env[spec.env];
+	if (raw === undefined || raw === "") {
+		missing.push(spec.env);
+		continue;
+	}
+	const parsed = spec.parse(raw);
+	if (typeof parsed === "number" && Number.isNaN(parsed)) {
+		missing.push(`${spec.env} (got "${raw}", expected number)`);
+		continue;
+	}
+	config[key] = parsed;
+}
+if (missing.length > 0) {
+	throw new Error(
+		`RUMMY config missing or invalid: ${missing.join(", ")}. ` +
+			"Set in .env, .env.example, or shell env.",
+	);
+}
+
+export default Object.freeze(config);

package/src/agent/errors.js

@@ -1,21 +1,15 @@
-/**
- * Typed errors for the agent/Entries layer. Callers catch by type,
- * not by regex.
- */
-
-/**
- * Thrown when a writer tier isn't permitted to write to a scheme.
- * See SPEC writer_tiers: schemes declare writable_by = subset of
- * {system, plugin, client, model}. A write from an excluded tier
- * rejects with this error.
- */
+// Writer tier excluded from scheme.writable_by; see SPEC writer_tiers.
 export class PermissionError extends Error {
 	constructor(scheme, writer, allowed) {
+		// Paths without `://` have a null scheme. Report null verbatim
+		// rather than substituting a plausible-sounding "file" — there is
+		// no scheme called "file" and the error must reflect actual state.
+		const schemeLabel = scheme === null ? "(none)" : scheme;
 		super(
-			`403: writer "${writer}" not permitted for scheme "${scheme ?? "file"}" (allowed: ${allowed.join(", ")})`,
+			`403: writer "${writer}" not permitted for scheme "${schemeLabel}" (allowed: ${allowed.join(", ")})`,
 		);
 		this.name = "PermissionError";
-		this.scheme = scheme ?? "file";
+		this.scheme = scheme;
 		this.writer = writer;
 		this.allowed = [...allowed];
 	}

package/src/agent/httpStatus.js

@@ -1,22 +1,4 @@
-/**
- * Map the entry-layer (state, outcome) tuple to an HTTP status number for
- * model-facing tag rendering.
- *
- * Model-facing tags still carry `status="NNN"` because the model's
- * vocabulary (instructions + tooldocs + training) is HTTP-shaped. The DB
- * stores categorical state + textual outcome (see SPEC entries); this helper
- * is the one-way translation for rendering.
- *
- * Outcome strings prefixed with a 3-digit HTTP code (e.g.
- * `"overflow:413:..."` or `"permission:403:..."`) extract the code
- * verbatim. Otherwise state maps to a canonical HTTP:
- *
- *   resolved   → 200
- *   proposed   → 202
- *   streaming  → 102
- *   cancelled  → 499
- *   failed     → 500 (unless outcome carries a code)
- */
+// (state, outcome) → HTTP status for model-facing tags; outcome's 3-digit prefix wins.
 export function stateToStatus(state, outcome = null) {
 	if (outcome) {
 		const match = /(\d{3})/.exec(outcome);

package/src/agent/known_queries.sql

@@ -1,7 +1,7 @@
 -- PREP: get_known_entries
 SELECT
 	path, scheme, state, outcome, visibility, body, turn, hash
-	, attributes, countTokens(body) AS tokens, scope
+	, attributes, countTokens(body) AS tokens, scope, loop_id
 FROM known_entries
 WHERE run_id = :run_id
 ORDER BY path;

package/src/agent/known_store.sql

@@ -223,16 +223,26 @@ WHERE run_id = :run_id AND entry_id IN (
 );
 
 -- PREP: get_entries_by_pattern
+-- Default excludes audit schemes (system://, reasoning://, model://, user://,
+-- assistant://, content://, instructions://) so model-facing tools never leak
+-- internal entries. Internal callers that need them pass include_audit_schemes=1.
+-- :since filters to entries created after a given id; when set, results order
+-- by id (insertion order) for streaming consumers; otherwise by path.
 SELECT
-	e.path, e.body, e.scheme, rv.state, rv.outcome, rv.visibility
+	e.id, e.path, e.body, e.scheme, rv.state, rv.outcome, rv.visibility, rv.turn
 	, countTokens(e.body) AS tokens, e.attributes
 FROM run_views AS rv
 JOIN entries AS e ON e.id = rv.entry_id
+JOIN schemes AS s ON s.name = COALESCE(e.scheme, 'file')
 WHERE
 	rv.run_id = :run_id
 	AND hedmatch(:path, e.path)
 	AND (:body IS NULL OR hedsearch(:body, e.body))
-ORDER BY e.path
+	AND (:include_audit_schemes IS NOT NULL OR s.model_visible = 1)
+	AND (:since IS NULL OR e.id > :since)
+ORDER BY
+	CASE WHEN :since IS NOT NULL THEN e.id ELSE 0 END,
+	e.path
 LIMIT
 	COALESCE(:limit, -1)
 	OFFSET COALESCE(:offset, 0);

package/src/agent/materializeContext.js

@@ -1,11 +1,7 @@
 import ContextAssembler from "./ContextAssembler.js";
-import { countTokens } from "./tokens.js";
+import { countLines, countTokens } from "./tokens.js";
 
-/**
- * Rebuild turn_context from v_model_context, then assemble messages.
- * Called at turn start and again by the budget plugin when it needs a
- * fresh measurement after mutating visibility.
- */
+// Rebuild turn_context from v_model_context and assemble messages.
 export default async function materializeContext({
 	db,
 	hooks,
@@ -16,22 +12,15 @@ export default async function materializeContext({
 	mode,
 	toolSet,
 	contextSize,
-	demoted,
 }) {
 	await db.clear_turn_context.run({ run_id: runId, turn });
 	const viewRows = await db.get_model_context.all({ run_id: runId });
-	// Per-entry token accounting (see SPEC @token_accounting): captured
-	// here while we still have the raw body, then merged onto rows after
-	// the read-back roundtrip through turn_context.
+	// Per-entry token accounting; merged back after the turn_context roundtrip.
 	const tokenAccounting = new Map();
 	for (const row of viewRows) {
-		// schemeOf() yields NULL (or "") for bare file paths — translate
-		// to "file" so the view lookup finds the file scheme handler.
 		const scheme = row.scheme ? row.scheme : "file";
 		const attrs = row.attributes ? JSON.parse(row.attributes) : null;
-		// Log entries live at log://turn_N/action/slug. Dispatch projection
-		// to the action plugin's view (set, update, search, etc.) by
-		// extracting the action segment from the path.
+		// Dispatch log entries to their action plugin's view via path segment.
 		let projectionKey = scheme;
 		if (scheme === "log") {
 			const m = row.path.match(/^log:\/\/turn_\d+\/([^/]+)\//);
@@ -54,7 +43,14 @@ export default async function materializeContext({
 		});
 		const vTokens = countTokens(visibleProjection);
 		const sTokens = countTokens(summarizedProjection);
-		tokenAccounting.set(row.path, { vTokens, sTokens });
+		const vLines = countLines(visibleProjection);
+		tokenAccounting.set(row.path, {
+			vTokens,
+			sTokens,
+			vLines,
+			vBody: visibleProjection,
+			sBody: summarizedProjection,
+		});
 		const projectedBody =
 			row.visibility === "visible" ? visibleProjection : summarizedProjection;
 		await db.insert_turn_context.run({
@@ -79,9 +75,11 @@ export default async function materializeContext({
 		row.vTokens = t.vTokens;
 		row.sTokens = t.sTokens;
 		row.aTokens = t.vTokens - t.sTokens;
+		row.vLines = t.vLines;
+		row.vBody = t.vBody;
+		row.sBody = t.sBody;
 	}
 	const lastCtx = await db.get_last_context_tokens.get({ run_id: runId });
-	// First turn of a new run has no prior context.
 	let lastContextTokens = 0;
 	if (lastCtx) lastContextTokens = lastCtx.context_tokens;
 
@@ -91,7 +89,6 @@ export default async function materializeContext({
 			type: mode,
 			systemPrompt,
 			contextSize,
-			demoted,
 			toolSet,
 			lastContextTokens,
 			turn,

package/src/agent/pathEncode.js

@@ -0,0 +1,5 @@
+// Single source of truth for path-segment encoding: spaces → _, then URL-encode.
+// Used by slugify (for summary-derived slugs) and Entries (for normalize/dedup/logPath).
+export default function encodeSegment(s) {
+	return encodeURIComponent(String(s).replace(/ /g, "_"));
+}

package/src/agent/rummyHome.js

@@ -0,0 +1,9 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// RUMMY_HOME default per README §Installation; resolved here because
+// entrypoints run before env files load.
+export default function resolveRummyHome() {
+	if (process.env.RUMMY_HOME) return process.env.RUMMY_HOME;
+	return join(homedir(), ".rummy");
+}

package/src/agent/runs.sql

@@ -56,6 +56,24 @@ LIMIT
 	OFFSET
 	COALESCE(:offset, 0);
 
+-- PREP: get_run_summary
+-- Per-run aggregation across all turns. LEFT JOIN: a run with zero
+-- recorded turns (e.g. signal abort before first turn) returns 0s,
+-- not NULL.
+SELECT
+	r.model AS model
+	, COUNT(t.id) AS turns
+	, COALESCE(SUM(t.cost), 0) AS cost
+	, COALESCE(SUM(t.prompt_tokens), 0) AS prompt_tokens
+	, COALESCE(SUM(t.cached_tokens), 0) AS cached_tokens
+	, COALESCE(SUM(t.completion_tokens), 0) AS completion_tokens
+	, COALESCE(SUM(t.reasoning_tokens), 0) AS reasoning_tokens
+	, COALESCE(SUM(t.total_tokens), 0) AS total_tokens
+FROM runs AS r
+LEFT JOIN turns AS t ON t.run_id = r.id
+WHERE r.id = :id
+GROUP BY r.id;
+
 -- PREP: rename_run
 UPDATE runs
 SET alias = :new_alias
@@ -92,6 +110,25 @@ SELECT
 FROM run_views
 WHERE run_id = :parent_run_id;
 
+-- PREP: archive_prior_prompt_artifacts
+-- Multi-prompt sessions accumulate artifacts from prior prompt cycles
+-- (consumed prompts, their per-turn logs). These pollute the validator's
+-- prior-prompts check on subsequent Deployment landings. Archive all
+-- prior prompt:// entries and prior-turn log:// entries when a new
+-- prompt arrives. Knowns/unknowns/file entries are untouched — they
+-- carry persistent knowledge across cycles. The loop_id IS NULL clause
+-- catches forked-in views from a parent run (per fork_known_entries),
+-- which represent prior cycles' artifacts inherited into a clean child.
+UPDATE run_views
+SET visibility = 'archived'
+WHERE run_id = :run_id
+	AND visibility != 'archived'
+	AND (turn < :current_turn OR loop_id IS NULL)
+	AND entry_id IN (
+		SELECT id FROM entries
+		WHERE scheme IN ('prompt', 'log')
+	);
+
 -- PREP: get_active_runs
 SELECT r.id
 FROM runs AS r

package/src/agent/tokens.js

@@ -1,10 +1,4 @@
-/**
- * Token estimation. Conservative character-based approximation.
- * RUMMY_TOKEN_DIVISOR controls characters per token.
- * No external dependencies. The budget contract is exact.
- * contextSize is the ceiling. countTokens is the measurement.
- */
-
+// Conservative chars/token approximation; RUMMY_TOKEN_DIVISOR controls the divisor.
 const DIVISOR = Number(process.env.RUMMY_TOKEN_DIVISOR);
 if (!DIVISOR) throw new Error("RUMMY_TOKEN_DIVISOR must be a non-zero number");
 
@@ -12,3 +6,9 @@ export function countTokens(text) {
 	if (!text) return 0;
 	return Math.ceil(text.length / DIVISOR);
 }
+
+export function countLines(text) {
+	if (!text) return 0;
+	const newlines = text.split("\n").length - 1;
+	return text.endsWith("\n") ? newlines : newlines + 1;
+}

package/src/hooks/HookRegistry.js

@@ -1,7 +1,4 @@
-/**
- * HookRegistry manages a simple, priority-ordered pipeline of processors.
- * It also supports basic event emitters for side-effects.
- */
+// Priority-ordered processors + filters + events.
 export default class HookRegistry {
 	#processors = [];
 	#events = new Map();
@@ -12,17 +9,11 @@ export default class HookRegistry {
 		this.#debug = debug;
 	}
 
-	/**
-	 * Register a processor for the Turn XML Document.
-	 */
 	onTurn(callback, priority = 10) {
 		this.#processors.push({ callback, priority });
 		this.#processors.sort((a, b) => a.priority - b.priority);
 	}
 
-	/**
-	 * Run all registered Turn processors.
-	 */
 	async processTurn(rummy) {
 		for (const p of this.#processors) {
 			const start = performance.now();
@@ -35,9 +26,6 @@ export default class HookRegistry {
 		}
 	}
 
-	/**
-	 * Standard WordPress-style Filters for non-DOM data.
-	 */
 	addFilter(tag, callback, priority = 10) {
 		if (!this.#filters.has(tag)) this.#filters.set(tag, []);
 		this.#filters.get(tag).push({ callback, priority });
@@ -54,9 +42,6 @@ export default class HookRegistry {
 		return result;
 	}
 
-	/**
-	 * Standard WordPress-style Events for side-effects.
-	 */
 	addEvent(tag, callback, priority = 10) {
 		if (!this.#events.has(tag)) this.#events.set(tag, []);
 		this.#events.get(tag).push({ callback, priority });

package/src/hooks/Hooks.js

@@ -2,10 +2,7 @@ import HookRegistry from "./HookRegistry.js";
 import RpcRegistry from "./RpcRegistry.js";
 import ToolRegistry from "./ToolRegistry.js";
 
-/**
- * createHooks returns a structured, strictly-typed API for registering
- * and emitting hooks, removing the dynamic stringly-typed Proxy magic.
- */
+// Strictly-typed hook surface; replaces the previous Proxy magic.
 export default function createHooks(debug = false) {
 	const registry = new HookRegistry(debug);
 	const tools = new ToolRegistry();
@@ -28,6 +25,10 @@ export default function createHooks(debug = false) {
 		processTurn: registry.processTurn.bind(registry),
 
 		// Explicit Hook Schema
+		boot: {
+			// Post-init, pre-accept-connections; one-shot post-init actions subscribe here.
+			completed: createEvent("boot.completed"),
+		},
 		project: {
 			init: {
 				started: createEvent("project.init.started"),
@@ -43,8 +44,6 @@ export default function createHooks(debug = false) {
 		run: {
 			created: createEvent("run.created"),
 			started: createEvent("run.started"),
-			progress: createEvent("run.progress"),
-			state: createEvent("run.state"),
 			config: createFilter("run.config"),
 			step: {
 				completed: createEvent("run.step.completed"),
@@ -59,21 +58,13 @@ export default function createHooks(debug = false) {
 			response: createEvent("turn.response"),
 			completed: createEvent("turn.completed"),
 		},
+		// SPEC #resolution covers the proposal hook chain.
 		proposal: {
 			prepare: createEvent("proposal.prepare"),
 			pending: createEvent("proposal.pending"),
-			// Plugins veto acceptance by returning {allow:false, outcome, body}.
-			// Used e.g. by set plugin's readonly constraint check.
 			accepting: createFilter("proposal.accepting"),
-			// Plugins compose the resolved body based on path/action. Default
-			// is output || "". Used e.g. by set plugin to preserve the
-			// model's proposed content as the resolved body.
 			content: createFilter("proposal.content"),
-			// Fires after a proposal resolves with action="accept". Plugins
-			// perform their side effects (file materialize, unlink, stream
-			// setup, etc.) here — NOT in AgentLoop.resolve.
 			accepted: createEvent("proposal.accepted"),
-			// Fires after a proposal resolves with action="error" or "reject".
 			rejected: createEvent("proposal.rejected"),
 		},
 		assembly: {
@@ -98,24 +89,9 @@ export default function createHooks(debug = false) {
 			},
 			messages: createFilter("llm.messages"),
 			response: createFilter("llm.response"),
-			// Reasoning merge filter. Subscribers contribute per-tag
-			// reasoning text (e.g. the think plugin's <think>…</think>)
-			// to the model's reasoning_content field. Fires between parse
-			// and turn.response.
+			// Plugins contribute reasoning text into reasoning_content; fires between parse and turn.response.
 			reasoning: createFilter("llm.reasoning"),
-			// LLM provider registry. Plugins contribute entries shaped:
-			//   {
-			//     name: string,
-			//     matches: (modelAlias) => boolean,
-			//     completion: (messages, modelAlias, options) => Promise<response>,
-			//     getContextSize: (modelAlias) => Promise<number>,
-			//   }
-			// Each provider owns a prefix namespace (e.g. "openai/", "ollama/",
-			// "openrouter/"). LlmProvider picks the first provider whose
-			// matches() returns true. No catchall — if a model alias doesn't
-			// match any registered provider, the request fails with a clear
-			// "no provider registered" error. External plugins add new
-			// prefixes without namespace collision.
+			// Provider entries: { name, matches, completion, getContextSize }.
 			providers: [],
 		},
 		file: {},
@@ -163,7 +139,6 @@ export default function createHooks(debug = false) {
 		agent: {},
 		tools,
 
-		// Utility to add raw filters/events directly if needed for tests
 		addFilter: registry.addFilter.bind(registry),
 		applyFilters: registry.applyFilters.bind(registry),
 		addEvent: registry.addEvent.bind(registry),

package/src/hooks/PluginContext.js

@@ -1,12 +1,4 @@
-/**
- * PluginContext is the plugin-only interface to the rummy system.
- * Available as `rummy.core` on the per-turn RummyContext, and as the
- * direct object passed to plugin constructors at startup.
- *
- * Carries plugin identity, hook registration, and infrastructure access.
- * The unified API (tool verbs, queries) lives on RummyContext.
- * This is the tier boundary: clients can't reach core.
- */
+// Plugin-only registration interface; tool verbs live on RummyContext. PLUGINS.md.
 export default class PluginContext {
 	#name;
 	#hooks;
@@ -77,19 +69,12 @@ export default class PluginContext {
 		this.#hooks.tools.ensureTool(this.#name);
 	}
 
-	// Mark this plugin's tool as hidden from model-facing tool lists.
-	// Handler still dispatches if the model emits the tag.
+	// Hide from tool lists; handler still dispatches if the model emits the tag.
 	markHidden() {
 		this.#hooks.tools.markHidden(this.#name);
 	}
 
-	/**
-	 * Register a named callback for this plugin.
-	 * "handler" registers the tool handler.
-	 * "visible"/"summarized" register visibility projections.
-	 * "docs" sets tool documentation.
-	 * Everything else resolves to a hook event.
-	 */
+	// "handler" / "visible" / "summarized" are special; everything else is a hook event name.
 	on(event, callback, priority = 10) {
 		if (event === "handler") {
 			this.#hooks.tools.ensureTool(this.#name);
@@ -104,9 +89,6 @@ export default class PluginContext {
 		if (hook) hook.on(callback, priority);
 	}
 
-	/**
-	 * Register a filter callback.
-	 */
 	filter(name, callback, priority = 10) {
 		const hook = this.#resolveFilter(name);
 		if (hook) hook.addFilter(callback, priority);

package/src/hooks/RpcRegistry.js

@@ -26,10 +26,7 @@ export default class RpcRegistry {
 
 	#toolFallback = null;
 
-	/**
-	 * Set a fallback that auto-dispatches any registered tool via RPC.
-	 * Checked at request time — tools registered after this call still work.
-	 */
+	// Late-binding tool dispatcher; resolved per request.
 	setToolFallback(hooks, buildRunContext, dispatchTool) {
 		this.#toolFallback = { hooks, buildRunContext, dispatchTool };
 	}

package/src/hooks/RummyContext.js

@@ -1,15 +1,6 @@
-/**
- * RummyContext provides a unified, semantic API for plugins to interact with
- * the Turn node tree and core resources like the Database and Project metadata.
- */
-// Entries write verbs that should automatically carry the caller's
-// writer identity. Handler-issued writes on behalf of the model default
-// to writer=model; plugin background writes (set via rummy from a hook
-// with writer: "plugin" or "system" in ctx) get the context's writer.
+// Per-turn plugin API (see PLUGINS.md); write verbs auto-carry writer identity.
 const WRITE_VERBS = new Set(["set", "rm", "cp", "mv", "update"]);
 
-// Defaults applied at construction so every plugin-facing getter
-// returns a predictable shape without per-access fallbacks.
 const CONTEXT_DEFAULTS = Object.freeze({
 	hooks: null,
 	activeFiles: [],
@@ -106,6 +97,10 @@ export default class RummyContext {
 		return this.#context.noProposals === true;
 	}
 
+	get yolo() {
+		return this.#context.yolo === true;
+	}
+
 	get toolSet() {
 		return this.#context.toolSet;
 	}
@@ -122,12 +117,7 @@ export default class RummyContext {
 		return this.#context.loopPrompt;
 	}
 
-	/**
-	 * Writer identity for Entries permission checks. Defaults to
-	 * 'model' — handlers write on behalf of the model's emitted command.
-	 * Non-handler plugin code (streaming callbacks, background emissions)
-	 * passes `writer: 'plugin'` or `'system'` explicitly.
-	 */
+	// Default 'model' (handlers write on the model's behalf); plugins pass writer explicitly.
 	get writer() {
 		return this.#context.writer;
 	}

package/src/hooks/ToolRegistry.js

@@ -1,6 +1,4 @@
-// Tool display order: gather → reason → act → communicate.
-// Position in the list implies priority to the model.
-// `update` is pinned last — it's the turn-closer, not an action.
+// gather → reason → act → communicate; update pinned last (turn-closer).
 const TOOL_ORDER = [
 	"think",
 	"unknown",
@@ -40,9 +38,7 @@ export default class ToolRegistry {
 		this.#tools.set(scheme, Object.freeze({}));
 	}
 
-	// Hidden tools dispatch on direct emission but don't appear in any
-	// model-facing tool list. Internal schemes (e.g. <known>, <unknown>)
-	// the model writes via <set path="scheme://..."> instead.
+	// Hidden tools dispatch on direct emission but never appear in tool lists.
 	markHidden(scheme) {
 		this.#hidden.add(scheme);
 	}
@@ -82,9 +78,7 @@ export default class ToolRegistry {
 		if (!fn) return "";
 
 		const body = await fn(entry);
-		// View handlers MAY return undefined or null to mean "no projected
-		// body at this visibility" — normalize at this boundary so callers
-		// get a predictable string.
+		// undefined/null = "no projected body at this visibility"; normalize to "".
 		return body == null ? "" : body;
 	}
 
@@ -106,18 +100,14 @@ export default class ToolRegistry {
 		return sortByPriority([...this.#tools.keys()]);
 	}
 
-	// Names advertised to the model — registered tools minus hidden ones.
-	// Use this anywhere a tool list is shown to the model.
+	// Registered tools minus hidden; use anywhere a list reaches the model.
 	get advertisedNames() {
 		return sortByPriority(
 			[...this.#tools.keys()].filter((n) => !this.#hidden.has(n)),
 		);
 	}
 
-	/**
-	 * Compute the active tool set for a loop.
-	 * All exclusions — mode, flags, hidden — handled here. One mechanism.
-	 */
+	// Single source of truth for active-tool exclusions; SPEC #mode_enforcement.
 	resolveForLoop(
 		mode,
 		{ noInteraction = false, noWeb = false, noProposals = false } = {},