byterover-cli 3.10.0 → 3.10.2

package/dist/agent/infra/map/abstract-queue.js

@@ -1,7 +1,16 @@
 import { appendFileSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { generateFileAbstracts } from './abstract-generator.js';
+import { isAbsolute, join } from 'node:path';
+import { generateFileAbstractsBatch } from './abstract-generator.js';
+/**
+ * Maximum files combined into a single batched L0/L1 LLM call.
+ *
+ * Two parallel calls fire per cycle: one L0 batch (~80 tok output × N files +
+ * tags), one L1 batch (~1500 tok output × N files + tags). At N=5 the L1
+ * output budget caps at ~8K tokens; raising N further risks output truncation
+ * on smaller-context models. Lowering N reduces savings without quality gain.
+ */
+const BATCH_SIZE_CAP = 5;
 const QUEUE_TRACE_ENABLED = process.env.BRV_QUEUE_TRACE === '1';
 const LOG_PATH = process.env.BRV_SESSION_LOG;
 function queueLog(message) {
@@ -26,6 +35,13 @@ function queueLog(message) {
 export class AbstractGenerationQueue {
     projectRoot;
     maxAttempts;
+    /**
+     * When true, scheduleNext fires the next batch even if pending is below
+     * BATCH_SIZE_CAP. Set by drain(); reset once the queue is fully idle.
+     * Without this, items below the cap would be buffered indefinitely with
+     * no flush trigger when a curate writes fewer files than the cap.
+     */
+    drainRequested = false;
     drainResolvers = [];
     failed = 0;
     generator;
@@ -48,7 +64,12 @@ export class AbstractGenerationQueue {
      */
     async drain() {
         queueLog(`drain:start idle=${this.isIdle()} pending=${this.pending.length} retrying=${this.retrying} processing=${this.processing}`);
+        // Force any buffered (below-cap) pending items to fire as a final batch.
+        // scheduleNext respects drainRequested even when pending < BATCH_SIZE_CAP.
+        this.drainRequested = true;
+        this.scheduleNext();
         if (this.isIdle()) {
+            this.drainRequested = false;
             await this.statusWritePromise.catch(() => { });
             queueLog('drain:resolved-immediate');
             return;
@@ -63,6 +84,17 @@ export class AbstractGenerationQueue {
      * Add a file to the abstract generation queue.
      */
     enqueue(item) {
+        // Background batch writes derive .abstract.md / .overview.md from
+        // contextPath via raw `writeFile`. A relative path would resolve under
+        // process.cwd() rather than the intended context-tree location, and the
+        // failure would be invisible because batch errors are catch-suppressed.
+        // Drop misconfigured items at the entry point with a trace breadcrumb
+        // rather than failing loudly — callers are internal and treat the queue
+        // as fail-open.
+        if (!isAbsolute(item.contextPath)) {
+            queueLog(`enqueue:dropped non-absolute path=${item.contextPath}`);
+            return;
+        }
         // Guard against paths that must never trigger abstract generation:
         // - derived artifacts (.abstract.md, .overview.md) — would produce .abstract.abstract.md
         // - summary index files (_index.md) — domain/topic summaries, not knowledge nodes
@@ -77,7 +109,13 @@ export class AbstractGenerationQueue {
         this.pending.push({ attempts: 0, contextPath: item.contextPath, fullContent: item.fullContent });
         queueLog(`enqueue path=${item.contextPath} pending=${this.pending.length} retrying=${this.retrying} processing=${this.processing}`);
         this.queueStatusWrite();
-        this.scheduleNext();
+        // Buffer until cap is reached; drain() will trigger the final flush
+        // for partial batches at curate-end. Without this gating, the first
+        // enqueue starts a 1-item batch before the curate finishes writing
+        // the rest of its files.
+        if (this.pending.length >= BATCH_SIZE_CAP || this.drainRequested) {
+            this.scheduleNext();
+        }
     }
     /**
      * Return current queue status snapshot.
@@ -110,14 +148,25 @@ export class AbstractGenerationQueue {
         return this.pending.length === 0 && !this.processing && this.retrying === 0;
     }
     async processNext() {
-        if (!this.generator || this.processing || this.pending.length === 0) {
+        // Capture the generator in a local const so type narrowing survives the
+        // `await` boundary below — TS won't keep `this.generator` narrow across
+        // suspensions because another async path could reassign the property.
+        const { generator } = this;
+        if (!generator || this.processing || this.pending.length === 0) {
             this.resolveDrainersIfIdle();
             return;
         }
         this.processing = true;
         this.queueStatusWrite();
-        const item = this.pending.shift();
-        queueLog(`process:start path=${item.contextPath} remaining=${this.pending.length} retrying=${this.retrying}`);
+        // Drain up to BATCH_SIZE_CAP items into a single batch. Items beyond the
+        // cap stay pending for the next cycle. Note: `maxAttempts` counts BATCH
+        // attempts for this item, not individual-call attempts — a transient
+        // failure on attempt 1 consumes one retry token for every item in the
+        // batch, including ones whose content was unrelated to the failure.
+        // Acceptable: batches are small (cap=5) and the per-item re-enqueue on
+        // batch failure preserves attempts independently across cycles.
+        const batch = this.pending.splice(0, BATCH_SIZE_CAP);
+        queueLog(`process:start batchSize=${batch.length} remaining=${this.pending.length} retrying=${this.retrying}`);
         try {
             // Refresh credentials before each generation (OAuth tokens may expire)
             try {
@@ -127,23 +176,40 @@ export class AbstractGenerationQueue {
                 const msg = error instanceof Error ? error.message : String(error);
                 console.debug(`[AbstractQueue] token refresh failed, proceeding with existing generator: ${msg}`);
             }
-            const { abstractContent, overviewContent } = await generateFileAbstracts(item.fullContent, this.generator);
-            // Derive sibling paths: replace .md with .abstract.md and .overview.md
-            const abstractPath = item.contextPath.replace(/\.md$/, '.abstract.md');
-            const overviewPath = item.contextPath.replace(/\.md$/, '.overview.md');
-            await Promise.all([
-                writeFile(abstractPath, abstractContent, 'utf8'),
-                writeFile(overviewPath, overviewContent, 'utf8'),
-            ]);
-            this.processed++;
-            queueLog(`process:success path=${item.contextPath} processed=${this.processed}`);
+            const results = await generateFileAbstractsBatch(batch.map((it) => ({ contextPath: it.contextPath, fullContent: it.fullContent })), generator);
+            // Write all batched outputs in parallel. Empty strings are valid (model
+            // produced no content for that path) — preserves existing fail-open.
+            await Promise.all(results.flatMap((r) => {
+                const abstractPath = r.contextPath.replace(/\.md$/, '.abstract.md');
+                const overviewPath = r.contextPath.replace(/\.md$/, '.overview.md');
+                return [
+                    writeFile(abstractPath, r.abstractContent, 'utf8'),
+                    writeFile(overviewPath, r.overviewContent, 'utf8'),
+                ];
+            }));
+            this.processed += batch.length;
+            queueLog(`process:success batchSize=${batch.length} processed=${this.processed}`);
         }
         catch (error) {
+            // Batch-level failure → re-enqueue each item individually with its own
+            // attempts counter, mirroring per-item retry semantics. Items past
+            // maxAttempts count as failed.
             const msg = error instanceof Error ? error.message : String(error);
-            console.debug(`[AbstractQueue] ${item.contextPath} attempt ${item.attempts + 1}/${this.maxAttempts}: ${msg}`);
-            item.attempts++;
-            if (item.attempts < this.maxAttempts) {
-                // Exponential backoff: 500ms, 1000ms, 2000ms, ...
+            const failedThisCycle = [];
+            const retryThisCycle = [];
+            for (const item of batch) {
+                item.attempts++;
+                if (item.attempts < this.maxAttempts) {
+                    retryThisCycle.push(item);
+                }
+                else {
+                    this.failed++;
+                    failedThisCycle.push(item);
+                    queueLog(`process:failed path=${item.contextPath} failed=${this.failed}`);
+                }
+            }
+            console.debug(`[AbstractQueue] batch attempt failed (${msg}); retrying=${retryThisCycle.length}, exhausted=${failedThisCycle.length}`);
+            for (const item of retryThisCycle) {
                 const delay = 500 * 2 ** (item.attempts - 1);
                 this.retrying++;
                 this.queueStatusWrite();
@@ -155,14 +221,10 @@ export class AbstractGenerationQueue {
                     this.scheduleNext();
                 }, delay);
             }
-            else {
-                this.failed++;
-                queueLog(`process:failed path=${item.contextPath} failed=${this.failed}`);
-            }
         }
         finally {
             this.processing = false;
-            queueLog(`process:finally path=${item.contextPath} pending=${this.pending.length} retrying=${this.retrying} processed=${this.processed} failed=${this.failed}`);
+            queueLog(`process:finally batchSize=${batch.length} pending=${this.pending.length} retrying=${this.retrying} processed=${this.processed} failed=${this.failed}`);
             this.queueStatusWrite();
         }
         this.scheduleNext();
@@ -177,6 +239,9 @@ export class AbstractGenerationQueue {
         if (!this.isIdle() || this.drainResolvers.length === 0) {
             return;
         }
+        // Reset drain state once the queue settles — next curate's enqueue burst
+        // should buffer normally up to BATCH_SIZE_CAP again.
+        this.drainRequested = false;
         queueLog(`drain:idle pending=${this.pending.length} retrying=${this.retrying} processed=${this.processed} failed=${this.failed}`);
         const resolvers = this.drainResolvers.splice(0);
         const settledStatusWrite = this.statusWritePromise.catch(() => { });
@@ -185,10 +250,19 @@ export class AbstractGenerationQueue {
         }
     }
     scheduleNext() {
-        if (!this.generator || this.processing || this.pending.length === 0) {
+        if (!this.generator || this.processing) {
+            return;
+        }
+        if (this.pending.length === 0) {
             this.resolveDrainersIfIdle();
             return;
         }
+        // Buffer items below the cap unless drain has been requested (curate-end
+        // signal). This keeps the queue from firing partial 1-item batches in the
+        // middle of a multi-file curate.
+        if (this.pending.length < BATCH_SIZE_CAP && !this.drainRequested) {
+            return;
+        }
         // eslint-disable-next-line no-void
         setImmediate(() => { void this.processNext(); });
     }

package/dist/agent/infra/system-prompt/contributors/file-contributor.js

@@ -110,12 +110,16 @@ export class FileContributor {
      */
     renderTemplateVariables(template, context) {
         let result = template;
-        // Build variables from context
+        // Build variables from context.
+        // Note: a `datetime` template variable is intentionally NOT exposed here.
+        // Per-call timestamps must never enter the system prompt — they would
+        // poison the prefix cache from that byte onward. The current date/time
+        // is injected once into the iter-0 user message instead (see
+        // agent-llm-service.ts).
         /* eslint-disable camelcase */
         const variables = {
             available_markers: context.availableMarkers ? Object.keys(context.availableMarkers).join(', ') : '',
             available_tools: context.availableTools?.join(', ') ?? '',
-            datetime: `<dateTime>Current date and time: ${new Date().toISOString()}</dateTime>`,
         };
         /* eslint-enable camelcase */
         // Replace {{variable}} with values

package/dist/agent/infra/tools/implementations/curate-tool-task-context.d.ts

@@ -0,0 +1,2 @@
+export declare function runWithReviewDisabled<T>(reviewDisabled: boolean, fn: () => Promise<T>): Promise<T>;
+export declare function getCurrentReviewDisabled(): boolean | undefined;

package/dist/agent/infra/tools/implementations/curate-tool-task-context.js

@@ -0,0 +1,28 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Async-context scope for the daemon-stamped `reviewDisabled` value.
+ *
+ * The daemon snapshots the project's reviewDisabled flag once at task-create
+ * and forwards it via TaskExecute. The agent process opens an
+ * `AsyncLocalStorage` scope around the task body so any descendant async
+ * callsite — direct curate-tool invocation, sandbox `tools.curate(...)` via
+ * CurateService, or anything else awaiting under the same chain — observes the
+ * single snapshot value instead of re-reading `.brv/config.json` (which can
+ * race with mid-task user toggles).
+ *
+ * Same propagation pattern as `CurateResultCollector`
+ * (src/agent/infra/sandbox/curate-result-collector.ts): AsyncLocalStorage flows
+ * through the LLM streaming pipeline and the in-process sandbox, so callers
+ * without an explicit taskId still see the right value.
+ *
+ * Outside any scope, `getCurrentReviewDisabled()` returns `undefined` and the
+ * caller falls back to its own resolution path (currently a `.brv/config.json`
+ * read in `executeCurate`).
+ */
+const reviewDisabledStorage = new AsyncLocalStorage();
+export function runWithReviewDisabled(reviewDisabled, fn) {
+    return reviewDisabledStorage.run(reviewDisabled, fn);
+}
+export function getCurrentReviewDisabled() {
+    return reviewDisabledStorage.getStore();
+}

package/dist/agent/infra/tools/implementations/curate-tool.js

@@ -10,6 +10,7 @@ import { toSnakeCase } from '../../../../server/utils/file-helpers.js';
 import { deriveImpactFromLoss, detectStructuralLoss } from '../../../core/domain/knowledge/conflict-detector.js';
 import { resolveStructuralLoss } from '../../../core/domain/knowledge/conflict-resolver.js';
 import { ToolName } from '../../../core/domain/tools/constants.js';
+import { getCurrentReviewDisabled } from './curate-tool-task-context.js';
 /**
  * Derive the sidecar relPath (forward-slash, relative to the context tree
  * root) from an absolute context-file path and the operation basePath.
@@ -323,7 +324,13 @@ function deriveReviewMetadata(type, confidence, impact) {
  * @param filePath - Absolute path to the context tree file being modified
  * @param basePath - Context tree base path (e.g., '.brv/context-tree')
  */
-async function backupBeforeWrite(filePath, basePath) {
+async function backupBeforeWrite(filePath, basePath, reviewDisabled) {
+    // Honor `brv review --disable`: backups exist solely to support review rejection
+    // (restore from backup). With reviews disabled, they are dead state — skip creation
+    // so review-backups/ stays empty. Snapshot taken once at executeCurate top so all
+    // ops in this tool call observe a consistent value even if the user toggles mid-task.
+    if (reviewDisabled)
+        return;
     try {
         const brvDir = dirname(resolve(basePath));
         const relativePath = relative(resolve(basePath), resolve(filePath));
@@ -340,6 +347,29 @@ async function backupBeforeWrite(filePath, basePath) {
         // Best-effort: backup failure must never block curate operations
     }
 }
+/**
+ * Type guard: narrows an unknown JSON value to a shape that may carry the
+ * `reviewDisabled` flag. Used as the fallback when the agent process has no
+ * AsyncLocalStorage scope (direct sandbox callers without a TaskExecute).
+ */
+function hasReviewDisabledField(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Reads `<brvDir>/config.json` and returns the `reviewDisabled` flag.
+ * Returns false (review enabled) on any error so a missing/corrupt config never
+ * silently swallows backups that protect the rejection path.
+ */
+async function isReviewDisabledForBrvDir(brvDir) {
+    try {
+        const raw = await DirectoryManager.readFile(join(brvDir, 'config.json'));
+        const parsed = JSON.parse(raw);
+        return hasReviewDisabledField(parsed) && parsed.reviewDisabled === true;
+    }
+    catch {
+        return false;
+    }
+}
 function generateDomainContextMarkdown(domainName, context) {
     const sections = [`# Domain: ${domainName}`, '', '## Purpose', context.purpose, '', '## Scope'];
     if (context.scope.included.length > 0) {
@@ -636,7 +666,7 @@ function maxImpact(a, b) {
 /**
  * Execute UPDATE operation - modify existing {title}.md
  */
-async function executeUpdate(basePath, operation, onAfterWrite, runtimeSignalStore, logger) {
+async function executeUpdate(basePath, operation, reviewDisabled, onAfterWrite, runtimeSignalStore, logger) {
     const { confidence, content, domainContext, impact, path, reason, subtopicContext, summary, title, topicContext } = operation;
     // Used for early-exit validation failures (before structural loss can be assessed)
     const baseReviewMeta = deriveReviewMetadata('UPDATE', confidence, impact);
@@ -727,7 +757,7 @@ async function executeUpdate(basePath, operation, onAfterWrite, runtimeSignalSto
             summary,
             timestamps,
         });
-        await backupBeforeWrite(contextPath, basePath);
+        await backupBeforeWrite(contextPath, basePath, reviewDisabled);
         await DirectoryManager.writeFileAtomic(contextPath, contextContent);
         onAfterWrite?.(contextPath, contextContent);
         // Dual-write: mirror the curate-update bumps (importance +5, recency=1,
@@ -762,7 +792,7 @@ async function executeUpdate(basePath, operation, onAfterWrite, runtimeSignalSto
  * Execute UPSERT operation - automatically creates or updates based on file existence
  * This is the recommended operation type as it eliminates the need for pre-checks.
  */
-async function executeUpsert(basePath, operation, onAfterWrite, runtimeSignalStore, logger) {
+async function executeUpsert(basePath, operation, reviewDisabled, onAfterWrite, runtimeSignalStore, logger) {
     const { path, reason, title } = operation;
     const reviewMeta = deriveReviewMetadata('UPSERT', operation.confidence, operation.impact);
     if (!title) {
@@ -804,7 +834,7 @@ async function executeUpsert(basePath, operation, onAfterWrite, runtimeSignalSto
         const exists = await DirectoryManager.fileExists(contextPath);
         if (exists) {
             // File exists - delegate to UPDATE logic
-            const result = await executeUpdate(basePath, { ...operation, type: 'UPDATE' }, onAfterWrite, runtimeSignalStore, logger);
+            const result = await executeUpdate(basePath, { ...operation, type: 'UPDATE' }, reviewDisabled, onAfterWrite, runtimeSignalStore, logger);
             // Return with UPSERT type but indicate it was an update
             return {
                 ...result,
@@ -835,7 +865,7 @@ async function executeUpsert(basePath, operation, onAfterWrite, runtimeSignalSto
 /**
  * Execute MERGE operation - combine source file into target file, delete source file
  */
-async function executeMerge(basePath, operation, onAfterWrite, runtimeSignalStore, logger) {
+async function executeMerge(basePath, operation, reviewDisabled, onAfterWrite, runtimeSignalStore, logger) {
     const { confidence, domainContext, impact, mergeTarget, mergeTargetTitle, path, reason, subtopicContext, summary, title, topicContext, } = operation;
     const reviewMeta = deriveReviewMetadata('MERGE', confidence, impact);
     if (!title) {
@@ -917,8 +947,8 @@ async function executeMerge(basePath, operation, onAfterWrite, runtimeSignalStor
         const targetParsedContent = MarkdownWriter.parseContent(targetContent, mergeTargetTitle);
         const previousSummary = targetParsedContent.summary;
         // Backup both files before merge modifies target and deletes source
-        await backupBeforeWrite(targetContextPath, basePath);
-        await backupBeforeWrite(sourceContextPath, basePath);
+        await backupBeforeWrite(targetContextPath, basePath, reviewDisabled);
+        await backupBeforeWrite(sourceContextPath, basePath, reviewDisabled);
         // Capture source sidecar signals BEFORE any destructive operation so a
         // mid-flow crash cannot leave the target unmerged with an orphaned
         // source entry. The sidecar merge happens after the markdown writes
@@ -1001,7 +1031,7 @@ async function executeMerge(basePath, operation, onAfterWrite, runtimeSignalStor
  * Execute DELETE operation - remove specific file or entire folder
  * If title is provided, deletes specific file; if omitted, deletes entire folder
  */
-async function executeDelete(basePath, operation, runtimeSignalStore, logger) {
+async function executeDelete(basePath, operation, reviewDisabled, runtimeSignalStore, logger) {
     const { path, reason, title } = operation;
     const reviewMeta = deriveReviewMetadata('DELETE', operation.confidence, operation.impact);
     try {
@@ -1032,7 +1062,7 @@ async function executeDelete(basePath, operation, runtimeSignalStore, logger) {
             catch {
                 // Best-effort: summary extraction failure must never block delete
             }
-            await backupBeforeWrite(filePath, basePath);
+            await backupBeforeWrite(filePath, basePath, reviewDisabled);
             await DirectoryManager.deleteFile(filePath);
             await deleteDerivedSiblings(filePath);
             // Dual-write: drop the deleted file's sidecar entry so it does not
@@ -1083,7 +1113,7 @@ async function executeDelete(basePath, operation, runtimeSignalStore, logger) {
         catch {
             // Best-effort: summary extraction failure must never block delete
         }
-        await Promise.all(mdFiles.map((f) => backupBeforeWrite(f, basePath)));
+        await Promise.all(mdFiles.map((f) => backupBeforeWrite(f, basePath, reviewDisabled)));
         await DirectoryManager.deleteTopicRecursive(fullPath);
         // Dual-write: drop sidecar entries for every markdown file that was
         // deleted. Without this, folder deletes leak orphan signal entries.
@@ -1144,8 +1174,19 @@ export async function executeCurate(input, _context, abstractQueue, runtimeSigna
         };
     }
     const { basePath, operations } = parseResult.data;
+    // Prefer the daemon-stamped value (snapshotted at task-create on the daemon side,
+    // forwarded via TaskExecute, opened as an AsyncLocalStorage scope in agent-process so
+    // it propagates through any async chain — direct tool call, sandbox `tools.curate(...)`
+    // via CurateService, or ingest-resource-tool). The `.brv/config.json` read is the
+    // fall-back for callers outside any scope. Sharing one value across daemon
+    // (CurateLogHandler) and agent (this tool) keeps reviewStatus and backups consistent:
+    // without it, a user toggle mid-task could mark ops as pending review (daemon snapshot
+    // held) while skipping backups (agent re-read picks up new value), making rejection
+    // un-restorable.
+    const scopedReviewDisabled = getCurrentReviewDisabled();
+    const reviewDisabled = scopedReviewDisabled ?? (await isReviewDisabledForBrvDir(dirname(resolve(basePath))));
     const onAfterWrite = abstractQueue
-        ? (contextPath, content) => { abstractQueue.enqueue({ contextPath, fullContent: content }); }
+        ? (contextPath, content) => abstractQueue.enqueue({ contextPath, fullContent: content })
         : undefined;
     const applied = [];
     const summary = {
@@ -1166,25 +1207,25 @@ export async function executeCurate(input, _context, abstractQueue, runtimeSigna
                 break;
             }
             case 'DELETE': {
-                result = await executeDelete(basePath, operation, runtimeSignalStore, logger);
+                result = await executeDelete(basePath, operation, reviewDisabled, runtimeSignalStore, logger);
                 if (result.status === 'success')
                     summary.deleted++;
                 break;
             }
             case 'MERGE': {
-                result = await executeMerge(basePath, operation, onAfterWrite, runtimeSignalStore, logger);
+                result = await executeMerge(basePath, operation, reviewDisabled, onAfterWrite, runtimeSignalStore, logger);
                 if (result.status === 'success')
                     summary.merged++;
                 break;
             }
             case 'UPDATE': {
-                result = await executeUpdate(basePath, operation, onAfterWrite, runtimeSignalStore, logger);
+                result = await executeUpdate(basePath, operation, reviewDisabled, onAfterWrite, runtimeSignalStore, logger);
                 if (result.status === 'success')
                     summary.updated++;
                 break;
             }
             case 'UPSERT': {
-                result = await executeUpsert(basePath, operation, onAfterWrite, runtimeSignalStore, logger);
+                result = await executeUpsert(basePath, operation, reviewDisabled, onAfterWrite, runtimeSignalStore, logger);
                 // UPSERT counts as either added or updated based on what happened
                 if (result.status === 'success') {
                     if (result.message?.includes('created new')) {

package/dist/agent/infra/tools/tool-manager.d.ts

@@ -31,12 +31,21 @@ export declare class ToolManager {
     /**
      * Tools allowed for curate operations.
      * Uses code_exec only - curate operations available via tools.curate() in sandbox.
+     *
+     * NOTE: Insertion order is load-bearing for Anthropic prompt caching.
+     * `toAiSdkTools` attaches `cacheControl: ephemeral` to the LAST tool in
+     * iteration order, which becomes the cache breakpoint. Reordering this
+     * list (or the per-call sort in `filterToolsForCommand`) silently shifts
+     * the breakpoint and can halve cache hit-rate. Append new tools at the end.
      */
     private static readonly CURATE_TOOL_NAMES;
     /**
      * Tools allowed for query operations - only code_exec for programmatic search
      * All search operations (searchKnowledge, glob, grep, readFile) are available
-     * via tools.* SDK inside the sandbox
+     * via tools.* SDK inside the sandbox.
+     *
+     * Same insertion-order contract as CURATE_TOOL_NAMES (Anthropic cache
+     * breakpoint lands on the last tool).
      */
     private static readonly QUERY_TOOL_NAMES;
     private cacheValid;

package/dist/agent/infra/tools/tool-manager.js

@@ -27,6 +27,12 @@ export class ToolManager {
     /**
      * Tools allowed for curate operations.
      * Uses code_exec only - curate operations available via tools.curate() in sandbox.
+     *
+     * NOTE: Insertion order is load-bearing for Anthropic prompt caching.
+     * `toAiSdkTools` attaches `cacheControl: ephemeral` to the LAST tool in
+     * iteration order, which becomes the cache breakpoint. Reordering this
+     * list (or the per-call sort in `filterToolsForCommand`) silently shifts
+     * the breakpoint and can halve cache hit-rate. Append new tools at the end.
      */
     static CURATE_TOOL_NAMES = [
         'agentic_map',
@@ -37,7 +43,10 @@ export class ToolManager {
     /**
      * Tools allowed for query operations - only code_exec for programmatic search
      * All search operations (searchKnowledge, glob, grep, readFile) are available
-     * via tools.* SDK inside the sandbox
+     * via tools.* SDK inside the sandbox.
+     *
+     * Same insertion-order contract as CURATE_TOOL_NAMES (Anthropic cache
+     * breakpoint lands on the last tool).
      */
     static QUERY_TOOL_NAMES = [
         'code_exec',

package/dist/oclif/commands/review.d.ts

@@ -0,0 +1,16 @@
+import { Command } from '@oclif/core';
+import { type DaemonClientOptions } from '../lib/daemon-client.js';
+export default class Review extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        disable: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        enable: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    protected getDaemonClientOptions(): DaemonClientOptions;
+    run(): Promise<void>;
+    private reportError;
+    private reportStatus;
+    private reportToggle;
+}

package/dist/oclif/commands/review.js

@@ -0,0 +1,96 @@
+import { Command, Flags } from '@oclif/core';
+import { ReviewEvents, } from '../../shared/transport/events/review-events.js';
+import { formatConnectionError, withDaemonRetry } from '../lib/daemon-client.js';
+import { writeJsonResponse } from '../lib/json-response.js';
+export default class Review extends Command {
+    static description = `Toggle the HITL review log for the current project
+
+When disabled:
+- 'brv curate' (sync mode) no longer prints the "X operations require review" prompt
+- Curate-log entries written in '--detach' mode no longer carry the per-operation review marker
+- 'brv dream' no longer surfaces its own needsReview operations as pending reviews
+- 'brv review pending' will not list any new entries until re-enabled`;
+    static examples = [
+        '# Show current state',
+        '<%= config.bin %> <%= command.id %>',
+        '',
+        '# Disable the review log for this project',
+        '<%= config.bin %> <%= command.id %> --disable',
+        '',
+        '# Re-enable the review log',
+        '<%= config.bin %> <%= command.id %> --enable',
+    ];
+    static flags = {
+        disable: Flags.boolean({
+            default: false,
+            description: 'Disable the HITL review log for this project',
+            exclusive: ['enable'],
+        }),
+        enable: Flags.boolean({
+            default: false,
+            description: 'Re-enable the HITL review log for this project',
+            exclusive: ['disable'],
+        }),
+        format: Flags.string({
+            default: 'text',
+            description: 'Output format (text or json)',
+            options: ['text', 'json'],
+        }),
+    };
+    getDaemonClientOptions() {
+        return {};
+    }
+    async run() {
+        const { flags } = await this.parse(Review);
+        const format = flags.format === 'json' ? 'json' : 'text';
+        try {
+            if (flags.disable || flags.enable) {
+                const target = flags.disable;
+                const response = await withDaemonRetry((client) => client.requestWithAck(ReviewEvents.SET_DISABLED, { reviewDisabled: target }), this.getDaemonClientOptions());
+                this.reportToggle(response.reviewDisabled, format);
+                return;
+            }
+            const response = await withDaemonRetry((client) => client.requestWithAck(ReviewEvents.GET_DISABLED, {}), this.getDaemonClientOptions());
+            this.reportStatus(response.reviewDisabled, format);
+        }
+        catch (error) {
+            this.reportError(error, format);
+        }
+    }
+    reportError(error, format) {
+        const message = error instanceof Error ? error.message : 'Review failed';
+        if (format === 'json') {
+            writeJsonResponse({
+                command: 'review',
+                data: { error: message, status: 'error' },
+                success: false,
+            });
+            return;
+        }
+        this.log(formatConnectionError(error));
+    }
+    reportStatus(disabled, format) {
+        if (format === 'json') {
+            writeJsonResponse({
+                command: 'review',
+                data: { reviewDisabled: disabled, status: 'success' },
+                success: true,
+            });
+            return;
+        }
+        this.log(disabled ? 'Review log is disabled.' : 'Review log is enabled.');
+    }
+    reportToggle(disabled, format) {
+        if (format === 'json') {
+            writeJsonResponse({
+                command: 'review',
+                data: { reviewDisabled: disabled, status: 'success' },
+                success: true,
+            });
+            return;
+        }
+        this.log(disabled
+            ? `Review log disabled. To re-enable: ${this.config.bin} review --enable`
+            : `Review log enabled. To disable: ${this.config.bin} review --disable`);
+    }
+}

package/dist/server/core/domain/entities/brv-config.d.ts

@@ -13,6 +13,7 @@ export type BrvConfigParams = {
     createdAt: string;
     cwd?: string;
     ide?: Agent;
+    reviewDisabled?: boolean;
     spaceId?: string;
     spaceName?: string;
     teamId?: string;
@@ -47,6 +48,7 @@ export declare class BrvConfig {
     readonly createdAt: string;
     readonly cwd?: string;
     readonly ide?: Agent;
+    readonly reviewDisabled?: boolean;
     readonly spaceId?: string;
     readonly spaceName?: string;
     readonly teamId?: string;
@@ -89,6 +91,10 @@ export declare class BrvConfig {
      * Creates a new BrvConfig with space fields cleared, preserving all other fields.
      */
     withoutSpace(): BrvConfig;
+    /**
+     * Creates a new BrvConfig with the reviewDisabled flag updated, preserving all other fields.
+     */
+    withReviewDisabled(reviewDisabled: boolean): BrvConfig;
     /**
      * Creates a new BrvConfig with space fields replaced, preserving all other fields.
      */