@oh-my-pi/pi-coding-agent 15.5.15 → 15.7.0

package/dist/types/tiny/title-protocol.d.ts

@@ -0,0 +1,74 @@
+import type { TinyLocalModelKey, TinyTitleLocalModelKey } from "./models";
+export type TinyTitleProgressStatus = "initiate" | "download" | "progress" | "progress_total" | "done" | "ready" | "error";
+export interface TinyTitleProgressFileState {
+    loaded: number;
+    total: number;
+}
+export interface TinyTitleProgressEvent {
+    modelKey: TinyLocalModelKey;
+    status: TinyTitleProgressStatus;
+    name?: string;
+    file?: string;
+    progress?: number;
+    loaded?: number;
+    total?: number;
+    files?: Record<string, TinyTitleProgressFileState>;
+    task?: string;
+    model?: string;
+}
+export type TinyTitleWorkerInbound = {
+    type: "ping";
+    id: string;
+} | {
+    type: "generate";
+    id: string;
+    modelKey: TinyTitleLocalModelKey;
+    message: string;
+} | {
+    type: "complete";
+    id: string;
+    modelKey: TinyLocalModelKey;
+    prompt: string;
+    maxTokens?: number;
+} | {
+    type: "download";
+    id: string;
+    modelKey: TinyLocalModelKey;
+} | {
+    type: "close";
+};
+export type TinyTitleWorkerOutbound = {
+    type: "pong";
+    id: string;
+} | {
+    type: "title";
+    id: string;
+    title: string | null;
+} | {
+    type: "completion";
+    id: string;
+    text: string | null;
+} | {
+    type: "downloaded";
+    id: string;
+} | {
+    type: "error";
+    id: string;
+    error: string;
+} | {
+    type: "progress";
+    id: string;
+    event: TinyTitleProgressEvent;
+} | {
+    type: "log";
+    level: "debug" | "warn" | "error";
+    msg: string;
+    meta?: Record<string, unknown>;
+} | {
+    type: "closed";
+};
+export interface TinyTitleTransport {
+    send(message: TinyTitleWorkerOutbound): void;
+    onMessage(handler: (message: TinyTitleWorkerInbound) => void): () => void;
+    close(): void;
+}

package/dist/types/tiny/worker.d.ts

@@ -0,0 +1,2 @@
+import type { TinyTitleTransport } from "./title-protocol";
+export declare function startTinyTitleWorker(transport: TinyTitleTransport): void;

package/dist/types/tools/bash.d.ts

@@ -43,6 +43,8 @@ export interface BashToolDetails {
     timeoutSeconds?: number;
     requestedTimeoutSeconds?: number;
     wallTimeMs?: number;
+    /** Exit code of a command that ran to completion but failed (non-zero). */
+    exitCode?: number;
     terminalId?: string;
     async?: {
         state: "running" | "completed" | "failed";
@@ -70,7 +72,7 @@ export declare class BashTool implements AgentTool<BashToolSchema, BashToolDetai
     readonly concurrency = "exclusive";
     readonly strict = true;
     constructor(session: ToolSession);
-    execute(_toolCallId: string, { command: rawCommand, env: rawEnv, timeout: rawTimeout, cwd, async: asyncRequested, pty }: BashToolInput, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<BashToolDetails>, ctx?: AgentToolContext): Promise<AgentToolResult<BashToolDetails>>;
+    execute(_toolCallId: string, { command: rawCommand, env: rawEnv, timeout: rawTimeout, cwd, async: asyncRequested, pty, }: BashToolInput, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<BashToolDetails>, ctx?: AgentToolContext): Promise<AgentToolResult<BashToolDetails>>;
 }
 export interface BashRenderArgs {
     command?: string;
@@ -99,7 +101,6 @@ export interface ShellRendererConfig<TArgs> {
     resolveEnv?: (args: TArgs | undefined) => Record<string, string> | undefined;
 }
 export declare function getBashEnvForDisplay(args: BashRenderArgs): Record<string, string> | undefined;
-export declare function formatBashCommand(args: BashRenderArgs): string;
 /**
  * Returns the bash command formatted for the result body: the dim `$ cd … &&`
  * prefix joined with syntax-highlighted command lines. The prefix is applied

package/dist/types/tools/eval.d.ts

@@ -94,7 +94,7 @@ interface EvalRenderContext {
     timeout?: number;
 }
 export declare const evalToolRenderer: {
-    renderCall(args: EvalRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderCall(args: EvalRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
     renderResult(result: {
         content: Array<{
             type: string;

package/dist/types/tools/index.d.ts

@@ -6,6 +6,7 @@ import type { Settings } from "../config/settings";
 import type { Skill } from "../extensibility/skills";
 import type { GoalModeState, GoalRuntime } from "../goals";
 import type { HindsightSessionState } from "../hindsight/state";
+import type { MnemosyneSessionState } from "../mnemosyne/state";
 import type { PlanModeState } from "../plan-mode/state";
 import { type AgentRegistry } from "../registry/agent-registry";
 import type { ArtifactManager } from "../session/artifacts";
@@ -36,15 +37,15 @@ export * from "./debug";
 export * from "./eval";
 export * from "./find";
 export * from "./gh";
-export * from "./hindsight-recall";
-export * from "./hindsight-reflect";
-export * from "./hindsight-retain";
 export * from "./image-gen";
 export * from "./inspect-image";
 export * from "./irc";
 export * from "./job";
+export * from "./memory-edit";
+export * from "./memory-recall";
+export * from "./memory-reflect";
+export * from "./memory-retain";
 export * from "./read";
-export * from "./recipe";
 export * from "./render-mermaid";
 export * from "./report-tool-issue";
 export * from "./resolve";
@@ -106,6 +107,8 @@ export interface ToolSession {
     getSessionId?: () => string | null;
     /** Get Hindsight runtime state for this agent session. */
     getHindsightSessionState?: () => HindsightSessionState | undefined;
+    /** Get Mnemosyne runtime state for this agent session. */
+    getMnemosyneSessionState?: () => MnemosyneSessionState | undefined;
     /** Agent identity used for IRC routing. Returns the registry id (e.g. "0-Main", "0-AuthLoader"). */
     getAgentId?: () => string | null;
     /** Look up a registered tool by name (used by the eval js backend's tool bridge). */

package/dist/types/tools/memory-edit.d.ts

@@ -0,0 +1,40 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import * as z from "zod/v4";
+import type { ToolSession } from ".";
+declare const memoryEditSchema: z.ZodObject<{
+    op: z.ZodEnum<{
+        forget: "forget";
+        invalidate: "invalidate";
+        update: "update";
+    }>;
+    id: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
+    importance: z.ZodOptional<z.ZodNumber>;
+    replacement_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MemoryEditParams = z.infer<typeof memoryEditSchema>;
+export declare class MemoryEditTool implements AgentTool<typeof memoryEditSchema> {
+    private readonly session;
+    readonly name = "memory_edit";
+    readonly approval: "read";
+    readonly label = "Memory Edit";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        op: z.ZodEnum<{
+            forget: "forget";
+            invalidate: "invalidate";
+            update: "update";
+        }>;
+        id: z.ZodString;
+        content: z.ZodOptional<z.ZodString>;
+        importance: z.ZodOptional<z.ZodNumber>;
+        replacement_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    readonly summary = "Update, forget, or invalidate Mnemosyne memories";
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): MemoryEditTool | null;
+    execute(_id: string, params: MemoryEditParams): Promise<AgentToolResult>;
+}
+export {};

package/dist/types/tools/{hindsight-recall.d.ts → memory-recall.d.ts}

@@ -1,11 +1,11 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import * as z from "zod/v4";
 import type { ToolSession } from ".";
-declare const hindsightRecallSchema: z.ZodObject<{
+declare const memoryRecallSchema: z.ZodObject<{
     query: z.ZodString;
 }, z.core.$strip>;
-export type HindsightRecallParams = z.infer<typeof hindsightRecallSchema>;
-export declare class HindsightRecallTool implements AgentTool<typeof hindsightRecallSchema> {
+export type MemoryRecallParams = z.infer<typeof memoryRecallSchema>;
+export declare class MemoryRecallTool implements AgentTool<typeof memoryRecallSchema> {
     private readonly session;
     readonly name = "recall";
     readonly approval: "read";
@@ -16,9 +16,9 @@ export declare class HindsightRecallTool implements AgentTool<typeof hindsightRe
     }, z.core.$strip>;
     readonly strict = true;
     readonly loadMode = "discoverable";
-    readonly summary = "Search hindsight memory for relevant prior context";
+    readonly summary = "Search memory for relevant prior context";
     constructor(session: ToolSession);
-    static createIf(session: ToolSession): HindsightRecallTool | null;
-    execute(_id: string, params: HindsightRecallParams, signal?: AbortSignal): Promise<AgentToolResult>;
+    static createIf(session: ToolSession): MemoryRecallTool | null;
+    execute(_id: string, params: MemoryRecallParams, signal?: AbortSignal): Promise<AgentToolResult>;
 }
 export {};

package/dist/types/tools/{hindsight-reflect.d.ts → memory-reflect.d.ts}

@@ -1,12 +1,12 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import * as z from "zod/v4";
 import type { ToolSession } from ".";
-declare const hindsightReflectSchema: z.ZodObject<{
+declare const memoryReflectSchema: z.ZodObject<{
     query: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export type HindsightReflectParams = z.infer<typeof hindsightReflectSchema>;
-export declare class HindsightReflectTool implements AgentTool<typeof hindsightReflectSchema> {
+export type MemoryReflectParams = z.infer<typeof memoryReflectSchema>;
+export declare class MemoryReflectTool implements AgentTool<typeof memoryReflectSchema> {
     private readonly session;
     readonly name = "reflect";
     readonly approval: "read";
@@ -18,9 +18,9 @@ export declare class HindsightReflectTool implements AgentTool<typeof hindsightR
     }, z.core.$strip>;
     readonly strict = true;
     readonly loadMode = "discoverable";
-    readonly summary = "Reflect on recent work and write hindsight memory";
+    readonly summary = "Synthesize an answer from long-term memory";
     constructor(session: ToolSession);
-    static createIf(session: ToolSession): HindsightReflectTool | null;
-    execute(_id: string, params: HindsightReflectParams, signal?: AbortSignal): Promise<AgentToolResult>;
+    static createIf(session: ToolSession): MemoryReflectTool | null;
+    execute(_id: string, params: MemoryReflectParams, signal?: AbortSignal): Promise<AgentToolResult>;
 }
 export {};

package/dist/types/tools/memory-render.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Inline TUI renderers for the long-term memory tools (`retain`, `recall`,
+ * `reflect`).
+ *
+ * These keep the transcript terse — one status line plus, for `retain`, one
+ * `Remember: …` line per stored item — instead of the generic JSON arg tree,
+ * which exploded multi-line memory blobs into an unreadable wall.
+ */
+import type { Component } from "@oh-my-pi/pi-tui";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+interface RetainRenderArgs {
+    items?: Array<{
+        content?: string;
+        context?: string;
+    }>;
+}
+interface QueryRenderArgs {
+    query?: string;
+}
+export declare const retainToolRenderer: {
+    inline: boolean;
+    mergeCallAndResult: boolean;
+    renderCall(args: RetainRenderArgs, options: RenderResultOptions, theme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: {
+            count?: number;
+        };
+        isError?: boolean;
+    }, options: RenderResultOptions, theme: Theme, args?: RetainRenderArgs): Component;
+};
+export declare const recallToolRenderer: {
+    inline: boolean;
+    mergeCallAndResult: boolean;
+    renderCall(args: QueryRenderArgs, _options: RenderResultOptions, theme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        isError?: boolean;
+    }, options: RenderResultOptions, theme: Theme, args?: QueryRenderArgs): Component;
+};
+export declare const reflectToolRenderer: {
+    inline: boolean;
+    mergeCallAndResult: boolean;
+    renderCall(args: QueryRenderArgs, _options: RenderResultOptions, theme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        isError?: boolean;
+    }, options: RenderResultOptions, theme: Theme, args?: QueryRenderArgs): Component;
+};
+export {};

package/dist/types/tools/{hindsight-retain.d.ts → memory-retain.d.ts}

@@ -1,14 +1,14 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import * as z from "zod/v4";
 import type { ToolSession } from ".";
-declare const hindsightRetainSchema: z.ZodObject<{
+declare const memoryRetainSchema: z.ZodObject<{
     items: z.ZodArray<z.ZodObject<{
         content: z.ZodString;
         context: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export type HindsightRetainParams = z.infer<typeof hindsightRetainSchema>;
-export declare class HindsightRetainTool implements AgentTool<typeof hindsightRetainSchema> {
+export type MemoryRetainParams = z.infer<typeof memoryRetainSchema>;
+export declare class MemoryRetainTool implements AgentTool<typeof memoryRetainSchema> {
     private readonly session;
     readonly name = "retain";
     readonly approval: "read";
@@ -22,9 +22,9 @@ export declare class HindsightRetainTool implements AgentTool<typeof hindsightRe
     }, z.core.$strip>;
     readonly strict = true;
     readonly loadMode = "discoverable";
-    readonly summary = "Store important facts in hindsight memory";
+    readonly summary = "Store important facts in long-term memory";
     constructor(session: ToolSession);
-    static createIf(session: ToolSession): HindsightRetainTool | null;
-    execute(_id: string, params: HindsightRetainParams): Promise<AgentToolResult>;
+    static createIf(session: ToolSession): MemoryRetainTool | null;
+    execute(_id: string, params: MemoryRetainParams): Promise<AgentToolResult>;
 }
 export {};

package/dist/types/tools/todo-write.d.ts

@@ -21,9 +21,14 @@ export interface TodoPhase {
     name: string;
     tasks: TodoItem[];
 }
+export interface TodoCompletionTransition {
+    phase: string;
+    content: string;
+}
 export interface TodoWriteToolDetails {
     phases: TodoPhase[];
     storage: "session" | "memory";
+    completedTasks?: TodoCompletionTransition[];
 }
 declare const todoWriteSchema: z.ZodObject<{
     ops: z.ZodArray<z.ZodObject<{
@@ -137,6 +142,9 @@ type TodoWriteRenderArgs = {
 export declare function phaseRomanNumeral(oneBasedIndex: number): string;
 /** Display-only phase header: `I. Foundation`. State and prompts never see this. */
 export declare function formatPhaseDisplayName(name: string, oneBasedIndex: number): string;
+export declare const TODO_WRITE_STRIKE_HOLD_FRAMES = 2;
+export declare const TODO_WRITE_STRIKE_REVEAL_FRAMES = 12;
+export declare const TODO_WRITE_STRIKE_TOTAL_FRAMES: number;
 export declare const todoWriteToolRenderer: {
     renderCall(args: TodoWriteRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
     renderResult(result: {

package/dist/types/tools/tool-result.d.ts

@@ -24,6 +24,8 @@ export declare class ToolResultBuilder<TDetails extends DetailsWithMeta> {
     sourcePath(value: string): this;
     sourceInternal(value: string): this;
     diagnostics(summary: string, messages: string[]): this;
+    /** Flag the result as a non-throwing failure (agent-loop surfaces it as a tool error). */
+    error(value?: boolean): this;
     done(): AgentToolResult<TDetails>;
 }
 export declare function toolResult<TDetails extends DetailsWithMeta>(details?: TDetails): ToolResultBuilder<TDetails>;

package/dist/types/tui/code-cell.d.ts

@@ -12,6 +12,8 @@ export interface CodeCellOptions {
     outputMaxLines?: number;
     codeMaxLines?: number;
     expanded?: boolean;
+    /** Animate the cell border with a sweeping segment while pending/running. */
+    animate?: boolean;
     width: number;
 }
 export declare function renderCodeCell(options: CodeCellOptions, theme: Theme): string[];

package/dist/types/tui/output-block.d.ts

@@ -10,7 +10,24 @@ export interface OutputBlockOptions {
     }>;
     width: number;
     applyBg?: boolean;
+    /** Animate the border with a sweeping dark segment (pending/running state). */
+    animate?: boolean;
 }
+/**
+ * Monotonic frame counter for animated borders. Quantized coarse enough to
+ * coalesce multiple render passes inside one frame, fine enough to advance on
+ * every spinner interval so cached blocks re-render while the segment travels.
+ */
+export declare function borderShimmerTick(): number;
+/**
+ * Perimeter index of the moving segment's head for a box of inner width `W` and
+ * height `H` at time `now`. The lap is split across the four edges in proportion
+ * to their length (so the average speed is uniform) and each edge is eased, for a
+ * deliberate, non-linear glide that slows at every corner. Position is derived
+ * from the wall clock against a fixed lap duration, so a perimeter change (new
+ * row / resize) shifts the head by at most a cell or two — no reset.
+ */
+export declare function borderSegmentHead(W: number, H: number, now: number): number;
 export declare function renderOutputBlock(options: OutputBlockOptions, theme: Theme): string[];
 /**
  * Cached wrapper around `renderOutputBlock`.

package/dist/types/utils/title-generator.d.ts

@@ -1,6 +1,8 @@
 import { type Api, type Model } from "@oh-my-pi/pi-ai";
 import type { ModelRegistry } from "../config/model-registry";
 import type { Settings } from "../config/settings";
+export declare const TITLE_LOCAL_FALLBACK_DELAY_MS = 10000;
+export declare function raceFirstNonNull<T>(primary: Promise<T | null>, startFallback: () => Promise<T | null>, delayMs?: number, onPrimaryWinAfterFallback?: () => void): Promise<T | null>;
 /**
  * Generate a title for a session based on the first user message.
  *
@@ -15,6 +17,7 @@ import type { Settings } from "../config/settings";
  *   reflects the credential actually selected for this request.
  */
 export declare function generateSessionTitle(firstMessage: string, registry: ModelRegistry, settings: Settings, sessionId?: string, currentModel?: Model<Api>, metadataResolver?: (provider: string) => Record<string, unknown> | undefined): Promise<string | null>;
+export declare function generateTitleOnline(firstMessage: string, registry: ModelRegistry, settings: Settings, sessionId?: string, currentModel?: Model<Api>, metadataResolver?: (provider: string) => Record<string, unknown> | undefined, signal?: AbortSignal): Promise<string | null>;
 export declare function formatSessionTerminalTitle(sessionName: string | undefined, cwd?: string): string;
 /**
  * Set the terminal title using OSC 0 (sets both tab and window title). Unsupported terminals ignore it.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "15.5.15",
+	"version": "15.7.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -44,31 +44,35 @@
 		"generate-template": "bun scripts/generate-template.ts"
 	},
 	"dependencies": {
-		"@agentclientprotocol/sdk": "0.21.0",
-		"@babel/parser": "^7.29.3",
+		"@agentclientprotocol/sdk": "0.22.1",
+		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "15.5.15",
-		"@oh-my-pi/omp-stats": "15.5.15",
-		"@oh-my-pi/pi-agent-core": "15.5.15",
-		"@oh-my-pi/pi-ai": "15.5.15",
-		"@oh-my-pi/pi-natives": "15.5.15",
-		"@oh-my-pi/pi-tui": "15.5.15",
-		"@oh-my-pi/pi-utils": "15.5.15",
-		"@puppeteer/browsers": "^2.13.0",
+		"@oh-my-pi/hashline": "15.7.0",
+		"@oh-my-pi/omp-stats": "15.7.0",
+		"@oh-my-pi/pi-agent-core": "15.7.0",
+		"@oh-my-pi/pi-ai": "15.7.0",
+		"@oh-my-pi/pi-mnemosyne": "15.7.0",
+		"@oh-my-pi/pi-natives": "15.7.0",
+		"@oh-my-pi/pi-tui": "15.7.0",
+		"@oh-my-pi/pi-utils": "15.7.0",
+		"@puppeteer/browsers": "^3.0.4",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",
 		"chalk": "^5.6.2",
 		"diff": "^9.0.0",
-		"fflate": "0.8.2",
+		"fflate": "0.8.3",
 		"handlebars": "^4.7.9",
 		"linkedom": "^0.18.12",
-		"lru-cache": "11.3.6",
+		"lru-cache": "11.5.1",
 		"markit-ai": "0.5.3",
-		"puppeteer-core": "^24.42.0",
+		"puppeteer-core": "^25.1.0",
 		"turndown": "7.2.4",
 		"turndown-plugin-gfm": "1.0.2",
 		"zod": "4.4.3"
 	},
+	"optionalDependencies": {
+		"@huggingface/transformers": "^4.2.0"
+	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"
 	},

package/scripts/build-binary.ts

@@ -56,6 +56,7 @@ async function main(): Promise<void> {
 					"../stats/src/sync-worker.ts",
 					"./src/tools/browser/tab-worker-entry.ts",
 					"./src/eval/js/worker-entry.ts",
+					"./src/tiny/worker.ts",
 					// Legacy pi-* extension compat entrypoints served by
 					// `legacy-pi-compat.ts`. These are reached via computed bunfs paths
 					// (which `--compile`'s static analyzer cannot trace), so each must be

package/src/capability/rule-buckets.ts

@@ -0,0 +1,64 @@
+/**
+ * Rule bucketing
+ *
+ * Single funnel that every discovered rule passes through on its way into a
+ * session. It applies the user's disable levers, registers TTSR rules with the
+ * manager, and splits the rest into the always-apply and rulebook buckets.
+ *
+ * Bucket precedence (matches docs/rulebook-matching-pipeline.md §5):
+ *   1. TTSR     — non-empty `condition` that `TtsrManager.addRule` accepts
+ *   2. always   — `alwaysApply === true`
+ *   3. rulebook — has a `description`
+ */
+import type { TtsrManager } from "../export/ttsr";
+import { BUILTIN_DEFAULTS_PROVIDER_ID, type Rule } from "./rule";
+
+export interface RuleBuckets {
+	rulebookRules: Rule[];
+	alwaysApplyRules: Rule[];
+}
+
+export interface BucketRulesOptions {
+	/** Rule names to drop entirely (bundled defaults and user rules alike). */
+	disabledRules?: readonly string[];
+	/** When false, drop every rule from the bundled `builtin-defaults` provider. */
+	builtinRules?: boolean;
+}
+
+/**
+ * Filter and bucket rules, registering TTSR rules on `ttsrManager` as a side
+ * effect. Disabled rules are dropped before any bucket assignment, so a
+ * disabled rule is neither matched as TTSR nor surfaced via `rule://`.
+ */
+export function bucketRules(
+	rules: readonly Rule[],
+	ttsrManager: TtsrManager,
+	options: BucketRulesOptions = {},
+): RuleBuckets {
+	const includeBuiltin = options.builtinRules !== false;
+	const disabled = new Set<string>();
+	for (const raw of options.disabledRules ?? []) {
+		const name = raw.trim();
+		if (name.length > 0) disabled.add(name);
+	}
+
+	const rulebookRules: Rule[] = [];
+	const alwaysApplyRules: Rule[] = [];
+
+	for (const rule of rules) {
+		if (disabled.has(rule.name)) continue;
+		if (!includeBuiltin && rule._source?.provider === BUILTIN_DEFAULTS_PROVIDER_ID) continue;
+
+		const isTtsrRule = rule.condition && rule.condition.length > 0 ? ttsrManager.addRule(rule) : false;
+		if (isTtsrRule) continue;
+		if (rule.alwaysApply === true) {
+			alwaysApplyRules.push(rule);
+			continue;
+		}
+		if (rule.description) {
+			rulebookRules.push(rule);
+		}
+	}
+
+	return { rulebookRules, alwaysApplyRules };
+}

package/src/capability/rule.ts

@@ -9,6 +9,14 @@ import type { SourceMeta } from "./types";
 
 const CONDITION_GLOB_SCOPE_TOOLS = ["edit", "write"] as const;
 
+/**
+ * Provider id for the bundled default rules shipped with the agent.
+ * Lowest priority, so any user/project/tool rule of the same name overrides
+ * a bundled default. Also used to gate the whole bundled set via
+ * `ttsr.builtinRules`.
+ */
+export const BUILTIN_DEFAULTS_PROVIDER_ID = "builtin-defaults";
+
 /**
  * Parsed frontmatter from rule files.
  */