feat(prompts): implement Topic-Action-Summary model for verbosity reduction (#21503)

packages/core/src/prompts/promptProvider.test.ts

@@ -60,6 +60,7 @@ describe('PromptProvider', () => {
       },
       isInteractive: vi.fn().mockReturnValue(true),
       isInteractiveShellEnabled: vi.fn().mockReturnValue(true),
+      isTopicUpdateNarrationEnabled: vi.fn().mockReturnValue(false),
       getSkillManager: vi.fn().mockReturnValue({
         getSkills: vi.fn().mockReturnValue([]),
       }),

packages/core/src/prompts/promptProvider.ts

@@ -124,6 +124,7 @@ export class PromptProvider {
           hasSkills: skills.length > 0,
           hasHierarchicalMemory,
           contextFilenames,
+          topicUpdateNarration: context.config.isTopicUpdateNarrationEnabled(),
         })),
         subAgents: this.withSection('agentContexts', () =>
           context.config
@@ -162,6 +163,8 @@ export class PromptProvider {
               ? { path: approvedPlanPath }
               : undefined,
             taskTracker: context.config.isTrackerEnabled(),
+            topicUpdateNarration:
+              context.config.isTopicUpdateNarrationEnabled(),
           }),
           !isPlanMode,
         ),
@@ -183,6 +186,8 @@ export class PromptProvider {
             enableShellEfficiency:
               context.config.getEnableShellOutputEfficiency(),
             interactiveShellEnabled: context.config.isInteractiveShellEnabled(),
+            topicUpdateNarration:
+              context.config.isTopicUpdateNarrationEnabled(),
           }),
         ),
         sandbox: this.withSection('sandbox', () => getSandboxMode()),

packages/core/src/prompts/snippets.ts

@@ -60,6 +60,7 @@ export interface CoreMandatesOptions {
   hasSkills: boolean;
   hasHierarchicalMemory: boolean;
   contextFilenames?: string[];
+  topicUpdateNarration: boolean;
 }
 
 export interface PrimaryWorkflowsOptions {
@@ -71,11 +72,13 @@ export interface PrimaryWorkflowsOptions {
   enableGlob: boolean;
   approvedPlan?: { path: string };
   taskTracker?: boolean;
+  topicUpdateNarration: boolean;
 }
 
 export interface OperationalGuidelinesOptions {
   interactive: boolean;
   interactiveShellEnabled: boolean;
+  topicUpdateNarration: boolean;
 }
 
 export type SandboxMode = 'macos-seatbelt' | 'generic' | 'outside';
@@ -223,10 +226,12 @@ Use the following guidelines to optimize your search and read patterns.
 - **Proactiveness:** When executing a Directive, persist through errors and obstacles by diagnosing failures in the execution phase and, if necessary, backtracking to the research or strategy phases to adjust your approach until a successful, verified outcome is achieved. Fulfill the user's request thoroughly, including adding tests when adding features or fixing bugs. Take reasonable liberties to fulfill broad goals while staying within the requested scope; however, prioritize simplicity and the removal of redundant logic over providing "just-in-case" alternatives that diverge from the established path.
 - **Testing:** ALWAYS search for and update related tests after making a code change. You must add a new test case to the existing test file (if one exists) or create a new test file to verify your changes.${mandateConflictResolution(options.hasHierarchicalMemory)}
 - **User Hints:** During execution, the user may provide real-time hints (marked as "User hint:" or "User hints:"). Treat these as high-priority but scope-preserving course corrections: apply the minimal plan change needed, keep unaffected user tasks active, and never cancel/skip tasks unless cancellation is explicit for those tasks. Hints may add new tasks, modify one or more tasks, cancel specific tasks, or provide extra context only. If scope is ambiguous, ask for clarification before dropping work.
-- ${mandateConfirm(options.interactive)}
-- **Explaining Changes:** After completing a code modification or file operation *do not* provide summaries unless asked.
-- **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.${mandateSkillGuidance(options.hasSkills)}
-- **Explain Before Acting:** Never call tools in silence. You MUST provide a concise, one-sentence explanation of your intent or strategy immediately before executing tool calls. This is essential for transparency, especially when confirming a request or answering a question. Silence is only acceptable for repetitive, low-level discovery operations (e.g., sequential file reads) where narration would be noisy.${mandateContinueWork(options.interactive)}
+- ${mandateConfirm(options.interactive)}${
+    options.topicUpdateNarration
+      ? mandateTopicUpdateModel()
+      : mandateExplainBeforeActing()
+  }
+- **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.${mandateSkillGuidance(options.hasSkills)}${mandateContinueWork(options.interactive)}
 `.trim();
 }
 
@@ -341,10 +346,18 @@ export function renderOperationalGuidelines(
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
-- **High-Signal Output:** Focus exclusively on **intent** and **technical rationale**. Avoid conversational filler, apologies, and mechanical tool-use narration (e.g., "I will now call...").
+- **High-Signal Output:** Focus exclusively on **intent** and **technical rationale**. Avoid conversational filler, apologies, and ${
+    options.topicUpdateNarration
+      ? 'per-tool explanations.'
+      : 'mechanical tool-use narration (e.g., "I will now call...").'
+  }
 - **Concise & Direct:** Adopt a professional, direct, and concise tone suitable for a CLI environment.
 - **Minimal Output:** Aim for fewer than 3 lines of text output (excluding tool use/code generation) per response whenever practical.
-- **No Chitchat:** Avoid conversational filler, preambles ("Okay, I will now..."), or postambles ("I have finished the changes...") unless they serve to explain intent as required by the 'Explain Before Acting' mandate.
+- **No Chitchat:** Avoid conversational filler, preambles ("Okay, I will now..."), or postambles ("I have finished the changes...") unless they are ${
+    options.topicUpdateNarration
+      ? 'part of the **Topic Model**.'
+      : "part of the 'Explain Before Acting' mandate."
+  }
 - **No Repetition:** Once you have provided a final synthesis of your work, do not repeat yourself or provide additional summaries. For simple or direct requests, prioritize extreme brevity.
 - **Formatting:** Use GitHub-flavored Markdown. Responses will be rendered in monospace.
 - **Tools vs. Text:** Use tools for actions, text output *only* for communication. Do not add explanatory comments within tool calls.
@@ -560,6 +573,56 @@ function mandateConfirm(interactive: boolean): string {
     : '**Handle Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request. If the user implies a change (e.g., reports a bug) without explicitly asking for a fix, do not perform it automatically.';
 }
 
+function mandateTopicUpdateModel(): string {
+  return `
+- **Protocol: Topic Model**
+  You are an agentic system. You must maintain a visible state log that tracks broad logical phases using a specific header format.
+
+- **1. Topic Initialization & Persistence:**
+  - **The Trigger:** You MUST issue a \`Topic: <Phase> : <Brief Summary>\` header ONLY when beginning a task or when the broad logical nature of the task changes (e.g., transitioning from research to implementation).
+  - **The Format:** Use exactly \`Topic: <Phase> : <Brief Summary>\` (e.g., \`Topic: <Research> : Researching Agent Skills in the repo\`).
+  - **Persistence:** Once a Topic is declared, do NOT repeat it for subsequent tool calls or in subsequent messages within that same phase. 
+  - **Start of Task:** Your very first tool execution must be preceded by a Topic header.
+
+- **2. Tool Execution Protocol (Zero-Noise):**
+  - **No Per-Tool Headers:** It is a violation of protocol to print "Topic:" before every tool call. 
+  - **Silent Mode:** No conversational filler, no "I will now...", and no summaries between tools. 
+  - Only the Topic header at the start of a broad phase is permitted to break the silence. Everything in between must be silent.
+
+- **3. Thinking Protocol:**
+  - Use internal thought blocks to keep track of what tools you have called, plan your next steps, and reason about the task.
+  - Without reasoning and tracking in thought blocks, you may lose context.
+  - Always use the required syntax for thought blocks to ensure they remain hidden from the user interface.
+
+- **4. Completion:**
+  - Only when the entire task is finalized do you provide a **Final Summary**.
+
+**IMPORTANT: Topic Headers vs. Thoughts**
+The \`Topic: <Phase> : <Brief Summary>\` header must **NOT** be placed inside a thought block. It must be standard text output so that it is properly rendered and displayed in the UI.
+
+**Correct State Log Example:**
+\`\`\`
+Topic: <Research> : Researching Agent Skills in the repo
+<tool_call 1>
+<tool_call 2>
+<tool_call 3>
+
+Topic: <Implementation> : Implementing the skill-creator logic
+<tool_call 1>
+<tool_call 2>
+
+The task is complete. [Final Summary]
+\`\`\`
+
+- **Constraint Enforcement:** If you repeat a "Topic:" line without a fundamental shift in work, or if you provide a Topic for every tool call, you have failed the system integrity protocol.`;
+}
+
+function mandateExplainBeforeActing(): string {
+  return `
+- **Explain Before Acting:** Never call tools in silence. You MUST provide a concise, one-sentence explanation of your intent or strategy immediately before executing tool calls. This is essential for transparency, especially when confirming a request or answering a question. Silence is only acceptable for repetitive, low-level discovery operations (e.g., sequential file reads) where narration would be noisy.
+- **Explaining Changes:** After completing a code modification or file operation *do not* provide summaries unless asked.`;
+}
+
 function mandateSkillGuidance(hasSkills: boolean): string {
   if (!hasSkills) return '';
   return `