Let the reflection guard stand down instead of stranding the turn

The reflection guard escalated a second unreflected tool call to a
permanent tool ban for the rest of the turn. The assistant could no
longer act even after producing the reflection it was asked for, so a
turn that ended in "Let me try reading those files now." stopped there,
never reading anything.

Replace the permanent `force_final` escalation with a single reminder:
the first violation still demands reflection, the second stands down
with `proceed_unreflected` so the announced work can proceed. Repetition
and blind retries remain covered by ToolLoopGuard and the tool-result
integrity check.

Also wire `responseCompletionHooks` onto the real react-loop host so an
announced-but-unexecuted action is rejected and retried instead of being
presented as the final answer, and skip that policing on recovery turns
where tools were deliberately withheld.

Co-authored-by: Autohand Evolve <code-noreply@autohand.ai>

Author: igorcosta

src/core/agent.ts

@@ -129,6 +129,7 @@ import {
   type ReactLoopControl,
   type ReactLoopResult,
 } from './agent/ReactLoopRunner.js';
+import { DEFAULT_RESPONSE_COMPLETION_HOOKS } from './agent/ResponseCompletionClassifier.js';
 import { initializeAgentDependencies, type AgentDependencyHost } from './agent/AgentDependencyComposer.js';
 import {
   InstructionRunner,
@@ -1220,6 +1221,7 @@ export class AutohandAgent {
       get contextPercentLeft() { return agent.contextPercentLeft; },
       conversation: agent.conversation,
       get inkRenderer() { return agent.inkRenderer as AgentReactLoopHost['inkRenderer']; },
+      responseCompletionHooks: DEFAULT_RESPONSE_COMPLETION_HOOKS,
       get lastAssistantResponseForNotification() { return agent.lastAssistantResponseForNotification; },
       set lastAssistantResponseForNotification(value) { agent.lastAssistantResponseForNotification = value; },
       llm: agent.llm,

src/core/agent/ReactLoopRunner.ts

@@ -531,8 +531,13 @@ export async function runAgentReactLoop(
         }
       }
 
+      // Set whenever the loop deliberately removes tools for a recovery turn:
+      // the assistant physically cannot emit a tool call, so announcing a next
+      // step is narration rather than a deferred action worth rejecting.
+      let toolsWithheldForRecovery = false;
       if (loopGuard.isForcingFinalResponse()) {
         tools = [];
+        toolsWithheldForRecovery = true;
       }
 
       // Use ContextOrchestrator for smart auto-compaction
@@ -571,6 +576,7 @@ export async function runAgentReactLoop(
         if (!integrity.ok) {
           loopGuard.forceFinalResponse();
           tools = [];
+          toolsWithheldForRecovery = true;
           const integrityNote =
             '[Tool Result Integrity] One or more prior tool results were not available in the outbound provider payload. ' +
             'Tools have been disabled for this recovery response. Do not retry the calls; explain the integrity failure ' +
@@ -715,7 +721,7 @@ export async function runAgentReactLoop(
         completion,
         payload,
         cleanupModelResponse: host.cleanupModelResponse,
-        responseCompletionHooks: host.responseCompletionHooks,
+        responseCompletionHooks: toolsWithheldForRecovery ? undefined : host.responseCompletionHooks,
       });
 
       if (turnOutcome.type === 'repair') {
@@ -858,18 +864,8 @@ export async function runAgentReactLoop(
         continue;
       }
 
-      if (reflectionDecision.type === 'force_final' && payload.toolCalls?.length) {
-        loopGuard.forceFinalResponse();
-        await recordRejectedNativeToolCalls(
-          payload.toolCalls,
-          'Tool call not executed: repeated missing reflection forced a final response.',
-        );
-        host.conversation.addSystemNote(
-          '[Critical Reflection Guard] The assistant attempted another tool call without analyzing prior results. ' +
-          'The call was not executed. Do not call tools again; provide a finalResponse from the available evidence.'
-        );
-        expectedOutboundToolResultIds = currentAssistantToolCallIds;
-        continue;
+      if (reflectionDecision.type === 'proceed_unreflected' && debugMode) {
+        host.writeDebugLine('[AGENT DEBUG] Reflection guard exhausted its reminder; letting the tool call proceed');
       }
 
       if (payload.toolCalls && payload.toolCalls.length > 0) {

src/core/agent/ToolLoopPolicy.ts

@@ -30,7 +30,7 @@ export interface ToolLoopResultDecision {
 export type ToolReflectionDecision =
   | { type: 'allow' }
   | { type: 'require_reflection' }
-  | { type: 'force_final' }
+  | { type: 'proceed_unreflected' }
   | { type: 'integrity_failure' };
 
 export interface ToolLoopGuardOptions {
@@ -204,9 +204,14 @@ export class ToolReflectionGuard {
       return { type: 'require_reflection' };
     }
 
+    // The reminder was already delivered once. Blocking again would strand the
+    // turn: the assistant loses tool access, cannot perform the work it just
+    // announced, and the user gets a progress note instead of an answer.
+    // Repetition and blind retries stay covered by ToolLoopGuard and the
+    // tool-result integrity check, so step aside and let the work proceed.
     this.awaitingReflection = false;
     this.violationCount = 0;
-    return { type: 'force_final' };
+    return { type: 'proceed_unreflected' };
   }
 }
 

src/core/agents/SubAgent.ts

@@ -329,19 +329,6 @@ export class SubAgent {
                     continue;
                 }
 
-                if (reflectionDecision.type === 'force_final') {
-                    loopGuard.forceFinalResponse();
-                    this.recordRejectedNativeToolCalls(
-                        payload.toolCalls,
-                        'Tool call not executed: repeated missing reflection forced a final response.',
-                    );
-                    this.conversation.addSystemNote(
-                        '[Critical Reflection Guard] Another tool call was attempted without analyzing prior results. '
-                        + 'The call was not executed. Do not call tools again; provide the final answer.'
-                    );
-                    continue;
-                }
-
                 const decision = loopGuard.observeCalls(payload.toolCalls);
                 if (decision.type !== 'allow') {
                     this.recordRejectedNativeToolCalls(

tests/core/agent.reflection.spec.ts

@@ -14,6 +14,10 @@ import { AutohandAgent } from '../../src/core/agent.js';
 import { ReactionParser } from '../../src/core/agent/ReactionParser.js';
 import { runAgentReactLoop } from '../../src/core/agent/ReactLoopRunner.js';
 import { ToolReflectionGuard } from '../../src/core/agent/ToolLoopPolicy.js';
+import {
+  DEFAULT_RESPONSE_COMPLETION_HOOKS,
+  type ResponseCompletionHook,
+} from '../../src/core/agent/ResponseCompletionClassifier.js';
 import type {
   AgentRuntime,
   AssistantReactPayload,
@@ -45,7 +49,10 @@ function createNativeToolCall(id: string, name = 'read_file', args: Record<strin
   };
 }
 
-function createReactLoopHarness(completions: LLMResponse[]) {
+function createReactLoopHarness(
+  completions: LLMResponse[],
+  harnessOptions: { responseCompletionHooks?: readonly ResponseCompletionHook[] } = {},
+) {
   const parser = createParser();
   const messages: LLMMessage[] = [{ role: 'user', content: 'check reflection' }];
   const systemNotes: string[] = [];
@@ -69,6 +76,9 @@ function createReactLoopHarness(completions: LLMResponse[]) {
 
   const host = {
     activeProvider: 'openai' as const,
+    ...(harnessOptions.responseCompletionHooks
+      ? { responseCompletionHooks: harnessOptions.responseCompletionHooks }
+      : {}),
     autoReportManager: { reportError: vi.fn(async () => {}) },
     consecutiveCancellations: 0,
     contextOrchestrator: {
@@ -383,15 +393,29 @@ describe('Reflection loop guard logic', () => {
     expect(needsReflection).toBe(false);
   });
 
-  it('forces a final response after the reflection violation limit is exceeded', () => {
+  it('stops blocking after one reminder instead of stranding the turn', () => {
     const guard = new ToolReflectionGuard();
     const payload: AssistantReactPayload = {
       toolCalls: [{ tool: 'read_file', args: { path: 'a.ts' } }]
     };
     guard.expectReflection();
 
     expect(guard.evaluate(payload)).toEqual({ type: 'require_reflection' });
-    expect(guard.evaluate(payload)).toEqual({ type: 'force_final' });
+    expect(guard.evaluate(payload)).toEqual({ type: 'proceed_unreflected' });
+  });
+
+  it('resets after standing down so a later reminder still fires once', () => {
+    const guard = new ToolReflectionGuard();
+    const payload: AssistantReactPayload = {
+      toolCalls: [{ tool: 'read_file', args: { path: 'a.ts' } }]
+    };
+
+    guard.expectReflection();
+    expect(guard.evaluate(payload)).toEqual({ type: 'require_reflection' });
+    expect(guard.evaluate(payload)).toEqual({ type: 'proceed_unreflected' });
+
+    guard.expectReflection();
+    expect(guard.evaluate(payload)).toEqual({ type: 'require_reflection' });
   });
 
   it('does not trigger guard on first iteration (no prior tool results)', () => {
@@ -505,7 +529,7 @@ describe('Reflection guard integration', () => {
     expect(emittedMessages).toContain('Stopped after reminder.');
   });
 
-  it('forces a tool-free response after a second unreflected follow-up attempt', async () => {
+  it('blocks the follow-up call once and then lets the next attempt through', async () => {
     const { host, systemNotes, executedCalls, emittedMessages, complete } = createReactLoopHarness([
       {
         content: 'Initial lookup',
@@ -517,19 +541,20 @@ describe('Reflection guard integration', () => {
       },
       {
         content: 'still short',
-        toolCalls: [createNativeToolCall('call_3', 'read_file', { path: 'blocked-twice.ts' })],
+        toolCalls: [createNativeToolCall('call_3', 'read_file', { path: 'allowed-after-reminder.ts' })],
       },
       {
-        content: '{"finalResponse":"Stopped after two missing reflections."}',
+        content: '{"finalResponse":"Finished after one reflection reminder."}',
       },
     ]);
 
     await runAgentReactLoop(host, new AbortController());
 
-    expect(executedCalls.map((call) => call.id)).toEqual(['call_1']);
-    expect(systemNotes.some((note) => note.startsWith('[Critical Reflection Guard]'))).toBe(true);
-    expect(complete.mock.calls[3]?.[0]?.tools).toBeUndefined();
-    expect(emittedMessages).toContain('Stopped after two missing reflections.');
+    expect(executedCalls.map((call) => call.id)).toEqual(['call_1', 'call_3']);
+    expect(systemNotes.some((note) => note.startsWith('[Reflection Required]'))).toBe(true);
+    expect(systemNotes.some((note) => note.startsWith('[Critical Reflection Guard]'))).toBe(false);
+    expect(complete.mock.calls[3]?.[0]?.tools).toBeDefined();
+    expect(emittedMessages).toContain('Finished after one reflection reminder.');
   });
 
   it('treats a missing-tool-output reflection as an integrity failure instead of re-running tools', async () => {
@@ -634,3 +659,140 @@ describe('System prompt includes reflection instructions', () => {
     expect(prompt).toContain('Reason + Reflect + Act');
   });
 });
+
+/* ── Regression: reflection guard must not strand a turn ──── */
+
+/**
+ * Reported symptom: the agent printed a reflection ending in "Let me try
+ * reading those files now." and then stopped, never reading anything.
+ *
+ * Two independent defects produced it:
+ *  1. The reflection guard escalated to a permanent tool ban, so the assistant
+ *     could no longer act even after it produced the reflection it was asked
+ *     for.
+ *  2. `responseCompletionHooks` was never wired onto the real react-loop host,
+ *     so an announced-but-unexecuted action was rendered as the final answer
+ *     instead of being rejected and retried.
+ */
+describe('Reflection guard dead-end regression', () => {
+  it('lets the assistant keep working after a second unreflected tool call', async () => {
+    const { host, systemNotes, executedCalls, emittedMessages, complete } = createReactLoopHarness([
+      {
+        content: 'Initial lookup',
+        toolCalls: [createNativeToolCall('call_1', 'read_file', { path: 'first.ts' })],
+      },
+      {
+        content: 'short',
+        toolCalls: [createNativeToolCall('call_2', 'read_file', { path: 'reminded.ts' })],
+      },
+      {
+        content: 'still short',
+        toolCalls: [createNativeToolCall('call_3', 'read_file', { path: 'recovered.ts' })],
+      },
+      {
+        content: '{"finalResponse":"Both files read."}',
+      },
+    ]);
+
+    await runAgentReactLoop(host, new AbortController());
+
+    expect(executedCalls.map((call) => call.args?.path)).toEqual(['first.ts', 'recovered.ts']);
+    expect(systemNotes.some((note) => note.startsWith('[Reflection Required]'))).toBe(true);
+    expect(systemNotes.some((note) => note.startsWith('[Critical Reflection Guard]'))).toBe(false);
+    expect(complete.mock.calls[2]?.[0]?.tools).toBeDefined();
+    expect(emittedMessages).toContain('Both files read.');
+  });
+
+  it('does not ban tools for the rest of the turn once a reminder is ignored', async () => {
+    const { host, complete, emittedMessages } = createReactLoopHarness([
+      {
+        content: 'Initial lookup',
+        toolCalls: [createNativeToolCall('call_1', 'read_file', { path: 'first.ts' })],
+      },
+      {
+        content: 'short',
+        toolCalls: [createNativeToolCall('call_2', 'read_file', { path: 'reminded.ts' })],
+      },
+      {
+        content: 'still short',
+        toolCalls: [createNativeToolCall('call_3', 'read_file', { path: 'recovered.ts' })],
+      },
+      {
+        content: '{"reflection":"Both files described the delegator.","thought":"Now I can answer."}',
+        toolCalls: [createNativeToolCall('call_4', 'read_file', { path: 'follow-up.ts' })],
+      },
+      {
+        content: '{"finalResponse":"Answered after recovering."}',
+      },
+    ]);
+
+    await runAgentReactLoop(host, new AbortController());
+
+    for (const call of complete.mock.calls) {
+      expect(call[0]?.tools).toBeDefined();
+    }
+    expect(emittedMessages).toContain('Answered after recovering.');
+  });
+
+  it('rejects an announced-but-unexecuted action instead of presenting it as the answer', async () => {
+    const announcement = [
+      "I need to stop and reflect on what I've gathered so far before proceeding.",
+      '',
+      'I was trying to read the actual implementation files but the tool calls were blocked.',
+      'I need to read `src/commands/agents.ts` and `src/core/agents/AgentDelegator.ts` implementation',
+      'before I can plan the "kill/stop" feature.',
+      '',
+      'Let me try reading those files now.',
+    ].join('\n');
+
+    const { host, systemNotes, executedCalls, emittedMessages } = createReactLoopHarness(
+      [
+        { content: announcement },
+        {
+          content: 'Reading the delegator now.',
+          toolCalls: [createNativeToolCall('call_1', 'read_file', { path: 'AgentDelegator.ts' })],
+        },
+        { content: '{"finalResponse":"`/agents` delegates through AgentDelegator."}' },
+      ],
+      { responseCompletionHooks: DEFAULT_RESPONSE_COMPLETION_HOOKS },
+    );
+
+    await runAgentReactLoop(host, new AbortController());
+
+    expect(systemNotes.some((note) => note.includes('announced an action but emitted no tool calls'))).toBe(true);
+    expect(executedCalls.map((call) => call.args?.path)).toEqual(['AgentDelegator.ts']);
+    expect(emittedMessages).toContain('`/agents` delegates through AgentDelegator.');
+    expect(emittedMessages).not.toContain(announcement);
+  });
+
+  it('does not police announced actions on a turn where tools were withheld', async () => {
+    const { host, systemNotes, emittedMessages } = createReactLoopHarness(
+      [
+        {
+          content: 'Initial lookup',
+          toolCalls: [createNativeToolCall('call_1', 'read_file', { path: 'same.ts' })],
+        },
+        {
+          content: '{"reflection":"The previous tool outputs weren\'t visible in my context.","thought":"I should retry."}',
+          toolCalls: [createNativeToolCall('call_2', 'read_file', { path: 'same.ts' })],
+        },
+        { content: 'I need to read the file again before I can answer.' },
+      ],
+      { responseCompletionHooks: DEFAULT_RESPONSE_COMPLETION_HOOKS },
+    );
+
+    await runAgentReactLoop(host, new AbortController());
+
+    expect(systemNotes.some((note) => note.startsWith('[Tool Result Integrity]'))).toBe(true);
+    expect(systemNotes.some((note) => note.includes('announced an action but emitted no tool calls'))).toBe(false);
+    expect(emittedMessages).toContain('I need to read the file again before I can answer.');
+  });
+
+  it('wires the response-completion hooks onto the real react-loop host', () => {
+    const agent = createMinimalAgent();
+    const host = agent.createReactLoopHost();
+
+    expect(host.responseCompletionHooks).toEqual(DEFAULT_RESPONSE_COMPLETION_HOOKS);
+    expect(host.responseCompletionHooks.length).toBeGreaterThan(0);
+  });
+});

tests/core/agent/ResponseCompletionClassifier.test.ts

@@ -85,6 +85,18 @@ describe('ResponseCompletionClassifier', () => {
       'Promise to answer later',
       'I now have a comprehensive understanding of the repository. Let me provide a clear summary to the user.',
     ],
+    [
+      'Reflection that ends on an unexecuted read',
+      [
+        "I need to stop and reflect on what I've gathered so far before proceeding.",
+        '',
+        'I was trying to read the actual implementation files but the tool calls were blocked.',
+        'I need to read `src/commands/agents.ts` and `src/core/agents/AgentDelegator.ts` implementation',
+        'before I can plan the "kill/stop" feature.',
+        '',
+        'Let me try reading those files now.',
+      ].join('\n'),
+    ],
   ])('classifies %s as invalid deferred action', (_name, response) => {
     const result = classifyResponseCompletion({ response });