@sayknow-cli/coding-agent 0.3.7 → 0.3.8

package/dist/types/system-prompt.d.ts

@@ -17,9 +17,12 @@ export interface LoadContextFilesOptions {
     cwd?: string;
 }
 /**
- * Load all project context files using the capability API.
+ * Load all context files using the capability API.
  * Returns {path, content, depth} entries for all discovered context files.
- * Files are sorted by depth (descending) so files closer to cwd appear last/more prominent.
+ * Native user-global files (`~/.skc/agent/AGENTS.md`) come first, then project
+ * files sorted by depth (descending) so files closer to cwd appear last/more
+ * prominent. User-home files from foreign providers (`~/.claude/CLAUDE.md`,
+ * `~/.codex/AGENTS.md`, …) stay excluded — only skc's own user config applies.
  */
 export declare function loadProjectContextFiles(options?: LoadContextFilesOptions): Promise<Array<{
     path: string;
@@ -91,12 +94,25 @@ export interface BuildSystemPromptOptions {
     secretsEnabled?: boolean;
     /** Pre-loaded workspace tree (skips discovery if provided). May be a Promise to allow early kick-off. */
     workspaceTree?: WorkspaceTree | Promise<WorkspaceTree>;
+    /**
+     * Render a trimmed role-agent base prompt for subagent sessions: omits the
+     * workflow-surface/routing/self-awareness (`<skc-runtime>`) and `<soul>` blocks
+     * that only apply to the top-level interactive/print agent. Tool safety, repo
+     * safety, and the completion contract are retained. Default: false.
+     */
+    subagent?: boolean;
 }
 /** Result of building provider-facing system prompt messages. */
 export interface BuildSystemPromptResult {
     /** Ordered system prompt blocks. Providers should preserve entries as distinct messages/blocks. */
     systemPrompt: string[];
 }
+export interface BuildVolatileProjectContextOptions {
+    cwd?: string;
+    date?: string;
+    workspaceTree?: WorkspaceTree;
+}
+export declare function buildVolatileProjectContext(options?: BuildVolatileProjectContextOptions): string;
 /** Build the system prompt with tools, guidelines, and context */
 export declare function buildSystemPrompt(options?: BuildSystemPromptOptions): Promise<BuildSystemPromptResult>;
 export {};

package/dist/types/task/executor.d.ts

@@ -51,6 +51,8 @@ export interface ExecutorOptions {
     artifactsDir?: string;
     /** Path to parent conversation context file */
     contextFile?: string;
+    /** Whether the parent runtime actually exposes IRC coordination. */
+    ircAvailable?: boolean;
     eventBus?: EventBus;
     contextFiles?: ContextFileEntry[];
     skills?: Skill[];
@@ -112,6 +114,7 @@ interface FinalizeSubprocessOutputResult {
 }
 export declare const SUBAGENT_WARNING_NULL_YIELD = "SYSTEM WARNING: Subagent called yield with null data.";
 export declare const SUBAGENT_WARNING_MISSING_YIELD = "SYSTEM WARNING: Subagent exited without calling yield tool after 3 reminders.";
+export declare const SUBAGENT_WARNING_PLACEHOLDER_YIELD = "SYSTEM WARNING: Subagent yield data contains a placeholder instead of the actual result.";
 export declare function finalizeSubprocessOutput(args: FinalizeSubprocessOutputArgs): FinalizeSubprocessOutputResult;
 export declare function createSubagentSettings(baseSettings: Settings, inheritedServiceTier?: ServiceTier): Settings;
 /**

package/dist/types/task/fork-context-budget.d.ts

@@ -0,0 +1,7 @@
+export declare const FORK_CONTEXT_TOKEN_BUDGET_BY_MODE: {
+    readonly none: 0;
+    readonly receipt: 2000;
+    readonly "last-turn": 4000;
+    readonly bounded: 8000;
+    readonly full: 15000;
+};

package/dist/types/task/token-log.d.ts

@@ -0,0 +1,30 @@
+import type { ChatUsageSnapshot, CostEstimate } from "@sayknow-cli/agent-core";
+import type { TaskTokenLog, TaskTokenMetrics } from "./types";
+export interface TaskTokenLogChatBuckets {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cachedInputTokens: number;
+    readonly cacheWriteTokens: number;
+    readonly costUsd?: number;
+}
+export interface TaskTokenLogSessionManager {
+    getSessionId(): string;
+}
+export interface TaskTokenLogContext {
+    readonly subagentId: string;
+    readonly agent?: string;
+    readonly turn: number;
+    readonly at: string;
+    readonly model?: string;
+}
+export declare function taskTokenLogFromChat(chat: TaskTokenLogChatBuckets, ctx: TaskTokenLogContext): TaskTokenLog;
+export declare function taskTokenLogFromUsage(usage: ChatUsageSnapshot, ctx: TaskTokenLogContext & {
+    readonly cost?: CostEstimate;
+}): TaskTokenLog;
+export declare function resolveTaskTokenLogDir(cwd: string, sessionManager: TaskTokenLogSessionManager | undefined, envSessionId?: string | undefined): Promise<string | undefined>;
+export declare function persistTaskTokenLog(entry: TaskTokenLog, opts: {
+    dir: string;
+}): Promise<void>;
+export declare function readTaskTokenLogs(dir: string): Promise<TaskTokenLog[]>;
+export declare function computeTaskTokenMetrics(logs: readonly TaskTokenLog[]): TaskTokenMetrics;
+export declare function computeCacheHitRate(input: number, cacheRead: number): number;

package/dist/types/task/token-log.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,81 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@sayknow-cli/agent-core";
+import * as z from "zod/v4";
+import type { ToolSession } from ".";
+import type { OutputMeta } from "./output-meta";
+declare const bisectSchema: z.ZodObject<{
+    good: z.ZodString;
+    bad: z.ZodDefault<z.ZodString>;
+    run: z.ZodString;
+    invert: z.ZodDefault<z.ZodBoolean>;
+    maxSteps: z.ZodDefault<z.ZodNumber>;
+    stepTimeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type BisectParams = z.infer<typeof bisectSchema>;
+export type BisectVerdict = "good" | "bad" | "skip";
+export interface BisectStep {
+    rev: string;
+    verdict: BisectVerdict;
+}
+export interface BisectMarkResult {
+    exitCode: number;
+    output: string;
+}
+export interface BisectControllerDeps {
+    maxSteps: number;
+    /** SHA of the revision git currently has checked out. */
+    currentRev: () => Promise<string>;
+    /** Evaluate the predicate at the checked-out revision. */
+    evaluate: (rev: string) => Promise<BisectVerdict>;
+    /** Apply the verdict via `git bisect good|bad|skip` and return the raw result. */
+    mark: (verdict: BisectVerdict) => Promise<BisectMarkResult>;
+}
+export interface BisectOutcome {
+    culprit: string | null;
+    steps: BisectStep[];
+    concluded: boolean;
+    reason?: string;
+}
+export interface BisectToolDetails {
+    meta?: OutputMeta;
+    culprit: string | null;
+    invert: boolean;
+    concluded: boolean;
+    steps: BisectStep[];
+    author?: string;
+    date?: string;
+    subject?: string;
+    reason?: string;
+}
+/** Parse the culprit SHA from `git bisect good|bad` output, or null when not yet converged. */
+export declare function parseFirstBadCommit(output: string): string | null;
+/**
+ * Map a predicate exit code to a bisect verdict. `invert` swaps the good/bad
+ * mapping (to hunt for a fixing commit) but never reinterprets a skip.
+ */
+export declare function classifyExit(exitCode: number, invert: boolean): BisectVerdict;
+/**
+ * Drive the bisect loop. Pure orchestration — every git/predicate effect is
+ * injected — so it can be exercised deterministically without a real repo.
+ */
+export declare function runBisectController(deps: BisectControllerDeps, signal?: AbortSignal): Promise<BisectOutcome>;
+export declare class BisectTool implements AgentTool<typeof bisectSchema, BisectToolDetails> {
+    private readonly session;
+    readonly name = "bisect";
+    readonly label = "Bisect";
+    readonly summary = "Find the commit that introduced a regression by driving git bisect with a shell predicate";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        good: z.ZodString;
+        bad: z.ZodDefault<z.ZodString>;
+        run: z.ZodString;
+        invert: z.ZodDefault<z.ZodBoolean>;
+        maxSteps: z.ZodDefault<z.ZodNumber>;
+        stepTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    readonly intent: (args: Partial<BisectParams>) => string;
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: BisectParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<BisectToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<BisectToolDetails>>;
+}
+export {};

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

@@ -238,7 +238,7 @@ export interface ComputerScreenshotDetails {
     scaleY?: number;
     originX?: number;
     originY?: number;
-    displayEpoch?: string;
+    displayEpoch?: number;
     captureId?: string;
     pngBytes?: number;
     path?: string;
@@ -281,7 +281,7 @@ type NativeScreenshot = {
     scaleY?: number;
     originX?: number;
     originY?: number;
-    displayEpoch?: string;
+    displayEpoch?: number;
     captureId?: string;
 };
 export type ComputerControllerFactory = () => NativeController;

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

@@ -31,6 +31,7 @@ export * from "./ask";
 export * from "./ast-edit";
 export * from "./ast-grep";
 export * from "./bash";
+export * from "./bisect";
 export * from "./browser";
 export * from "./calculator";
 export * from "./checkpoint";

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

@@ -8,7 +8,7 @@ import type { ToolSession } from ".";
 import { type OutputMeta } from "./output-meta";
 declare const searchSchema: z.ZodObject<{
     pattern: z.ZodString;
-    paths: z.ZodArray<z.ZodString>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     i: z.ZodOptional<z.ZodBoolean>;
     gitignore: z.ZodOptional<z.ZodBoolean>;
     skip: z.ZodOptional<z.ZodNumber>;
@@ -61,7 +61,7 @@ export declare class SearchTool implements AgentTool<typeof searchSchema, Search
     readonly description: string;
     readonly parameters: z.ZodObject<{
         pattern: z.ZodString;
-        paths: z.ZodArray<z.ZodString>;
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
         i: z.ZodOptional<z.ZodBoolean>;
         gitignore: z.ZodOptional<z.ZodBoolean>;
         skip: z.ZodOptional<z.ZodNumber>;

package/dist/types/tools/ultragoal-ask-guard.d.ts

@@ -1,5 +1,12 @@
 import type { AgentTool } from "@sayknow-cli/agent-core";
 import { type UltragoalAskBlockDiagnostic } from "../skc-runtime/ultragoal-guard";
+export interface UltragoalAskGuardContext {
+    activeSkillState?: {
+        skill?: string;
+        session_id?: string;
+    } | null;
+    sessionId?: string | null;
+}
 export declare function formatUltragoalAskBlockMessage(diagnostic: UltragoalAskBlockDiagnostic): string;
-export declare function assertUltragoalAskAllowed(cwd: string): Promise<void>;
-export declare function guardToolForUltragoalAsk<T extends AgentTool>(tool: T, getCwd: () => string): T;
+export declare function assertUltragoalAskAllowed(cwd: string, context?: UltragoalAskGuardContext): Promise<void>;
+export declare function guardToolForUltragoalAsk<T extends AgentTool>(tool: T, getCwd: () => string, getContext?: () => UltragoalAskGuardContext): T;

package/dist/types/utils/file-mentions.d.ts

@@ -1,4 +1,10 @@
 import type { AgentMessage } from "@sayknow-cli/agent-core";
+/**
+ * Default inline cap for auto-read file mentions, deliberately below the
+ * read-tool cap (`DEFAULT_MAX_BYTES`, 50KB) so an incidental `@path` mention
+ * injects a smaller snippet than an explicit `read`. Overridable per call.
+ */
+export declare const DEFAULT_FILE_MENTION_INLINE_BYTES: number;
 /** Extract all @filepath mentions from text */
 export declare function extractFileMentions(text: string): string[];
 /**
@@ -8,4 +14,12 @@ export declare function extractFileMentions(text: string): string[];
 export declare function generateFileMentionMessages(filePaths: string[], cwd: string, options?: {
     autoResizeImages?: boolean;
     useHashLines?: boolean;
+    /** Inline byte cap for auto-read text. Default: DEFAULT_FILE_MENTION_INLINE_BYTES. */
+    maxInlineBytes?: number;
+    /**
+     * Resolved paths already shown (read or mentioned) recently in the
+     * conversation. A mention of one of these emits a compact duplicate note
+     * instead of re-injecting the full body.
+     */
+    recentlyShownPaths?: ReadonlySet<string>;
 }): Promise<AgentMessage[]>;

package/dist/types/utils/git.d.ts

@@ -307,6 +307,38 @@ export declare function clean(cwd: string, options?: {
     paths?: readonly string[];
     signal?: AbortSignal;
 }): Promise<void>;
+export interface BisectCommitInfo {
+    sha: string;
+    author: string;
+    date: string;
+    subject: string;
+    stat: string;
+}
+/**
+ * Thin wrappers over `git bisect`. The marking commands (`good`/`bad`/`skip`)
+ * return the raw {@link GitCommandResult} without throwing so callers can both
+ * detect a genuine failure (non-zero exit) and scan the output for the
+ * "<sha> is the first bad commit" conclusion. `reset` is best-effort and never
+ * throws so it is safe to call from a `finally` block to restore the worktree.
+ */
+export declare const bisect: {
+    /** Begin a bisect session (does not seed good/bad endpoints). */
+    start(cwd: string, signal?: AbortSignal): Promise<void>;
+    /** Mark a revision (or current HEAD when omitted) good. Returns raw output. */
+    good(cwd: string, ref?: string, signal?: AbortSignal): Promise<GitCommandResult>;
+    /** Mark a revision (or current HEAD when omitted) bad. Returns raw output. */
+    bad(cwd: string, ref?: string, signal?: AbortSignal): Promise<GitCommandResult>;
+    /** Skip the current (untestable) revision. Returns raw output. */
+    skip(cwd: string, signal?: AbortSignal): Promise<GitCommandResult>;
+    /** Read the replayable bisect log for the current session. */
+    log(cwd: string, signal?: AbortSignal): Promise<string>;
+    /** End the bisect session, restoring the original HEAD. Never throws. */
+    reset(cwd: string, signal?: AbortSignal): Promise<void>;
+    /** True when `ancestor` is a first-parent-or-merge ancestor of `descendant`. */
+    isAncestor(cwd: string, ancestor: string, descendant: string, signal?: AbortSignal): Promise<boolean>;
+    /** Resolve author/date/subject and a diffstat for a commit (for the receipt). */
+    describe(cwd: string, sha: string, signal?: AbortSignal): Promise<BisectCommitInfo>;
+};
 export declare const ls: {
     /** List files tracked or untracked by git. */
     files(cwd: string, options?: {

package/dist/types/web/scrapers/youtube.d.ts

@@ -1,4 +1,12 @@
 import type { SpecialHandler } from "./types";
+export interface YouTubeUrl {
+    videoId: string;
+    playlistId?: string;
+}
+/**
+ * Parse YouTube URL into components
+ */
+export declare function parseYouTubeUrl(url: string): YouTubeUrl | null;
 /**
  * Handle YouTube URLs - fetch metadata and transcript
  */

package/dist/types/workflow/workflow-intent-diff.d.ts

@@ -1,5 +1,9 @@
+import { type WorkflowClaimsLedger, type WorkflowConsensusReport } from "./workflow-intent-report";
 export declare const WORKFLOW_INTENT_DIFF_CUSTOM_TYPE = "workflow-intent-diff";
-export type WorkflowIntentRoute = "direct" | "deep-interview" | "ralplan" | "ultragoal" | "team";
+export declare const WORKFLOW_INTENT_ROUTES: readonly ["direct", "deep-interview", "ralplan", "ultragoal", "team"];
+export declare const WORKFLOW_ESCALATION_ROUTES: readonly ["deep-interview", "ralplan", "ultragoal", "team"];
+export type WorkflowIntentRoute = (typeof WORKFLOW_INTENT_ROUTES)[number];
+export type WorkflowEscalationRoute = (typeof WORKFLOW_ESCALATION_ROUTES)[number];
 export type DirectTrackingMode = "custom-entry-only" | "not-direct";
 export type RootCausePhaseStatus = "active" | "inactive";
 export interface WorkflowIntentDiff {
@@ -7,13 +11,15 @@ export interface WorkflowIntentDiff {
     readonly route: WorkflowIntentRoute;
     readonly reason: string;
     readonly directTracking: DirectTrackingMode;
-    readonly recommendedSkill?: Exclude<WorkflowIntentRoute, "direct">;
+    readonly recommendedSkill?: WorkflowEscalationRoute;
     readonly recommendedInvocation?: string;
     readonly triggers: readonly string[];
     readonly rootCausePhase: {
         readonly status: RootCausePhaseStatus;
         readonly triggers: readonly string[];
     };
+    readonly claimsLedger: WorkflowClaimsLedger;
+    readonly consensusReport: WorkflowConsensusReport;
     readonly promptPreview: string;
 }
 export declare function buildWorkflowIntentDiff(text: string): WorkflowIntentDiff | null;

package/dist/types/workflow/workflow-intent-report-consumer.d.ts

@@ -0,0 +1,50 @@
+import type { SessionEntry } from "../session/session-manager";
+import { type WorkflowIntentDiff, type WorkflowIntentRoute } from "./workflow-intent-diff";
+import type { WorkflowSignalObserver } from "./workflow-intent-report";
+export type WorkflowConsumerConfidence = "none" | "low" | "medium" | "high";
+export interface WorkflowRouteCounts {
+    readonly direct: number;
+    readonly "deep-interview": number;
+    readonly ralplan: number;
+    readonly ultragoal: number;
+    readonly team: number;
+}
+export interface WorkflowIntentReportEntry {
+    readonly entryId: string;
+    readonly timestamp: string;
+    readonly intent: WorkflowIntentDiff;
+}
+export interface WorkflowIntentReportTotals {
+    readonly total: number;
+    readonly byRoute: WorkflowRouteCounts;
+    readonly escalationRequired: number;
+    readonly rootCauseActive: number;
+}
+export interface WorkflowIntentReportCollection {
+    readonly entries: readonly WorkflowIntentReportEntry[];
+    readonly latest: WorkflowIntentReportEntry | undefined;
+    readonly totals: WorkflowIntentReportTotals;
+}
+export interface WorkflowObserverSignalSummary {
+    readonly observer: WorkflowSignalObserver;
+    readonly conclusion: string;
+    readonly count: number;
+}
+export interface WorkflowConsensusSummary {
+    readonly total: number;
+    readonly dominantRoute: WorkflowIntentRoute | undefined;
+    readonly confidence: WorkflowConsumerConfidence;
+    readonly escalationGate: {
+        readonly required: boolean;
+        readonly count: number;
+        readonly latestReason: string | undefined;
+    };
+    readonly rootCausePhase: {
+        readonly active: boolean;
+        readonly count: number;
+        readonly triggers: readonly string[];
+    };
+    readonly observerSignals: readonly WorkflowObserverSignalSummary[];
+}
+export declare function collectWorkflowIntentReports(entries: readonly SessionEntry[]): WorkflowIntentReportCollection;
+export declare function summarizeWorkflowConsensus(intents: readonly WorkflowIntentDiff[]): WorkflowConsensusSummary;

package/dist/types/workflow/workflow-intent-report-schema.d.ts

@@ -0,0 +1,2 @@
+import { type WorkflowIntentDiff } from "./workflow-intent-diff";
+export declare function parseWorkflowIntentDiffPayload(value: unknown): WorkflowIntentDiff | undefined;

package/dist/types/workflow/workflow-intent-report.d.ts

@@ -0,0 +1,48 @@
+import type { RootCausePhaseStatus, WorkflowIntentRoute } from "./workflow-intent-diff";
+export type WorkflowConfidence = "high";
+export type WorkflowClaimStatus = "confirmed";
+export type WorkflowEscalationGateStatus = "required" | "not-required";
+export type WorkflowSignalObserver = "intent-router" | "root-cause-schema" | "escalation-gate";
+export interface WorkflowClaim {
+    readonly id: "workflow-route" | "root-cause-phase" | "escalation-gate";
+    readonly statement: string;
+    readonly status: WorkflowClaimStatus;
+    readonly confidence: WorkflowConfidence;
+    readonly evidence: readonly string[];
+}
+export interface WorkflowClaimsLedger {
+    readonly version: 1;
+    readonly claims: readonly WorkflowClaim[];
+}
+export interface WorkflowObserverSignal {
+    readonly observer: WorkflowSignalObserver;
+    readonly conclusion: string;
+    readonly evidence: readonly string[];
+}
+export interface WorkflowConsensusReport {
+    readonly version: 1;
+    readonly route: WorkflowIntentRoute;
+    readonly confidence: WorkflowConfidence;
+    readonly summary: string;
+    readonly observerSignals: readonly WorkflowObserverSignal[];
+    readonly escalationGate: {
+        readonly status: WorkflowEscalationGateStatus;
+        readonly reason: string;
+    };
+}
+export interface WorkflowIntentReport {
+    readonly claimsLedger: WorkflowClaimsLedger;
+    readonly consensusReport: WorkflowConsensusReport;
+}
+export interface WorkflowIntentReportInput {
+    readonly route: WorkflowIntentRoute;
+    readonly reason: string;
+    readonly direct: boolean;
+    readonly recommendedInvocation?: string;
+    readonly triggers: readonly string[];
+    readonly rootCausePhase: {
+        readonly status: RootCausePhaseStatus;
+        readonly triggers: readonly string[];
+    };
+}
+export declare function buildWorkflowIntentReport(input: WorkflowIntentReportInput): WorkflowIntentReport;

package/package.json

@@ -1,9 +1,9 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/coding-agent",
-	"version": "0.3.7",
+	"version": "0.3.8",
 	"description": "Sayknow-CLI CLI with read, bash, edit, write tools and session management",
-	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
+	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
 	"contributors": [
 		"Mario Zechner"
@@ -52,12 +52,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@sayknow-cli/stats": "0.3.7",
-		"@sayknow-cli/agent-core": "0.3.7",
-		"@sayknow-cli/ai": "0.3.7",
-		"@sayknow-cli/natives": "0.3.7",
-		"@sayknow-cli/tui": "0.3.7",
-		"@sayknow-cli/utils": "0.3.7",
+		"@sayknow-cli/stats": "0.3.8",
+		"@sayknow-cli/agent-core": "0.3.8",
+		"@sayknow-cli/ai": "0.3.8",
+		"@sayknow-cli/natives": "0.3.8",
+		"@sayknow-cli/tui": "0.3.8",
+		"@sayknow-cli/utils": "0.3.8",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/append-only-mode.ts

@@ -0,0 +1,58 @@
+/**
+ * Single source of truth for append-only context-mode resolution and manager
+ * construction. Both the initial session build (`sdk.ts`) and the runtime
+ * model/setting-change path (`agent-session.ts`), plus the status UI, resolve
+ * through here so the auto allowlist and prefix-reset diagnostics never drift.
+ */
+
+import { AppendOnlyContextManager } from "@sayknow-cli/agent-core";
+import { logger } from "@sayknow-cli/utils";
+
+/**
+ * Providers for which append-only context auto-enables. Exact provider-string
+ * match only: `anthropic` reached via a gateway/aggregator provider string
+ * (e.g. `openrouter`, a custom gateway) does NOT match and stays opt-in via
+ * `provider.appendOnlyContext: "on"`, because those transports can rewrite or
+ * renormalize the request in ways that have not been validated for append-only
+ * prefix stability.
+ */
+export function providerSupportsAppendOnlyAuto(provider: string): boolean {
+	return provider === "deepseek" || provider === "anthropic";
+}
+
+/**
+ * Resolve whether to enable append-only context mode based on the setting and provider.
+ *
+ * - `"on"` → always enable
+ * - `"off"` → never enable
+ * - `"auto"` → enable for providers with strong prompt-prefix caching that this
+ *   harness has validated (see {@link providerSupportsAppendOnlyAuto})
+ */
+export function resolveAppendOnlyMode(setting: "auto" | "on" | "off" | undefined, provider: string): boolean {
+	switch (setting ?? "auto") {
+		case "on":
+			return true;
+		case "off":
+			return false;
+		default:
+			return providerSupportsAppendOnlyAuto(provider);
+	}
+}
+
+/**
+ * Construct an {@link AppendOnlyContextManager} wired to emit per-session
+ * stable-prefix reset diagnostics. Use this at every creation site so the
+ * telemetry is uniform.
+ */
+export function createAppendOnlyContextManager(provider: string | undefined): AppendOnlyContextManager {
+	return new AppendOnlyContextManager({
+		onPrefixChange: info =>
+			logger.debug("append-only stable prefix changed (cache prefix reset)", {
+				provider,
+				from: info.from,
+				to: info.to,
+				version: info.version,
+				reason: info.from === "<unbuilt>" ? "initial-build" : "prefix-mutation",
+			}),
+	});
+}

package/src/autoresearch/prompt.md

@@ -22,7 +22,7 @@ You are running an autonomous experiment loop. Keep iterating until the user int
 ### Available tools
 - `init_experiment` — open or reconfigure the session. Pass `new_segment: true` to start a fresh baseline within the current session.
 - `run_experiment` — run the benchmark (`bash autoresearch.sh`). Output is captured automatically and `METRIC name=value` / `ASI key=value` lines printed by the harness are parsed back to you. The command is fixed; if you need a different workload, edit `autoresearch.sh` and bump segment via `init_experiment new_segment: true`.
-- `log_experiment` — record the result. On `keep`, modified files are committed for you; on `discard`/`crash`/`checks_failed`, the worktree is reverted. Pass `flag_runs` to mark earlier runs as suspect; flagged runs are excluded from baseline and best-metric math.
+- `log_experiment` — record the result. On `keep`, changes are committed only on a dedicated `autoresearch/*` branch; otherwise the tool warns and leaves files in the worktree. On `discard`/`crash`/`checks_failed`, the worktree is reverted. Pass `flag_runs` to mark earlier runs as suspect; flagged runs are excluded from baseline and best-metric math.
 - `update_notes` — replace the durable session playbook (`body`) or append to the ideas backlog (`append_idea`). The notes are injected into your system prompt every iteration.
 
 ### Operating protocol

package/src/autoresearch/tools/log-experiment.ts

@@ -62,7 +62,7 @@ export function createLogExperimentTool(
 		name: "log_experiment",
 		label: "Log Experiment",
 		description:
-			"Log the result of the latest run_experiment. Records the metric, optional ASI metadata, modified paths, and scope deviations. On `keep`, modified files are committed; on `discard`/`crash`/`checks_failed`, the worktree is reverted. Pass `flag_runs` to mark earlier runs as suspect; flagged runs are excluded from baseline and best-metric math.",
+			"Log the result of the latest run_experiment. Records the metric, optional ASI metadata, modified paths, and scope deviations. On `keep`, modified files are committed only on a dedicated `autoresearch/*` branch; otherwise the tool warns and leaves them in the worktree. On `discard`/`crash`/`checks_failed`, the worktree is reverted. Pass `flag_runs` to mark earlier runs as suspect; flagged runs are excluded from baseline and best-metric math.",
 		parameters: logExperimentSchema,
 		defaultInactive: true,
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/src/capability/rule.ts

@@ -22,6 +22,11 @@ export interface RuleFrontmatter {
 	scope?: string | string[];
 	/** Per-rule TTSR interrupt mode override. */
 	interruptMode?: "never" | "prose-only" | "tool-only" | "always";
+	/** Per-rule TTSR repeat mode override. */
+	repeatMode?: "once" | "after-gap";
+	/** Per-rule TTSR repeat gap override. */
+	repeatGap?: number;
+
 	[key: string]: unknown;
 }
 
@@ -47,6 +52,10 @@ export interface Rule {
 	scope?: string[];
 	/** Per-rule TTSR interrupt mode override (falls back to global ttsr.interruptMode). */
 	interruptMode?: "never" | "prose-only" | "tool-only" | "always";
+	/** Per-rule TTSR repeat mode override (falls back to global ttsr.repeatMode). */
+	repeatMode?: "once" | "after-gap";
+	/** Per-rule TTSR repeat gap override (falls back to global ttsr.repeatGap). */
+	repeatGap?: number;
 	/** Source metadata */
 	_source: SourceMeta;
 }