Add parallel course correction agent with forced tool call

I want to add a new agent. But it's different from the rest. It runs in parallel to the main thread. on every inference:completed (either tool_use or or end_turn) it runs one forced tool call with gemini with the entire thread. The forced tool call is to a new tool we are adding called course_correct, course correct has a boolean field (if true we want to add a course correct), and an optional message to be sent to the agent to stear it. The message should be like a user message, but it should have some metadata so we can render it differently. You should use gemini 3 as the model. The system prompt should ask it to check whether the model has forgotten anything or whether the model is going too far off the plan (diverging) or too narrow (not doing enough) and then correct its course. Or whether anything was forgotten based on the AGENTS.md file (run lint, ...) We need to: 1. add the tool 2. add the logic to trigger the forced tool call (look at the handoff logic for this for how to force a tool call with a prompt) 3. Create a good system prompt for it (we want the custom system prompt, the messages from the original thread as markdown, which should hightlight the user messages and the AGENTS.md file read in). 4. Add the logic to send the user:message in the thread worker / thread delta based on the result. This should run in the background once an tool_use stop reason is here, so it completed with the rool results and it should be sent after the tool results have been added to the thread but before we send a new request. On stop reason end of turn, we run it and send it only if the user has not sent a message yet.

This is a complex feature request to add a "course correction" agent that runs in parallel to the main thread. Let me break down what's needed:

A new tool called course_correct with a boolean field and optional message
Logic to trigger forced tool calls using Gemini (similar to handoff logic)
A system prompt for the course correction agent
Logic to inject user messages based on the result

Let me start by understanding the codebase structure and finding relevant files.

I'll help you add a course correction agent. Let me first explore the codebase to understand the relevant patterns.

Updated TODOs

Find the handoff logic that forces tool calls with a prompt. Look for how handoff agent works, how it forces specific tool calls, and how it constructs prompts for sub-agents. Return file paths and relevant code patterns.

Perfect! Now I have all the information I need. Let me provide a comprehensive answer with all the relevant files and patterns:

Summary

I found the handoff logic and tool forcing mechanisms used in Amp. Here are the key files and code patterns:

Core Handoff Implementation Files:

/Users/nicolaygerold/code/amp/core/src/threads/thread-handoff.ts - Main handoff logic
- createHandoffPrompt() - Generates handoff prompt by calling model with forced tool
- callModelForHandoff() - Calls model with HANDOFF_TOOL forced via runToolWithModel()
- HANDOFF_TOOL definition - Tool spec for extracting relevant context and files
- Pattern: Uses runToolWithModel() to force a specific tool call
/Users/nicolaygerold/code/amp/core/src/plan/handoff.ts - Plan execution handoff
- validatePlanForHandoff() - Validates plan is ready
- createPlanExecutionPrompt() - Generates prompt for plan execution thread
- Pattern: Converts markdown file links to @ mentions for context
/Users/nicolaygerold/code/amp/core/src/inference/run-tool-with-model.ts - Unified tool forcing interface
- runToolWithModel() - Main entry point that forces a specific tool call
- Dispatches to provider-specific implementations
- Pattern: Only returns when the specified tool is called

Key Tool Forcing Patterns:

1. Anthropic (Line 271 in run-tool-with-model.ts):

tool_choice: { type: 'tool', name: toolSpec.name }

Forces Anthropic Claude to use a specific tool by setting tool_choice parameter.

2. XAI/OpenAI Style (Line 460 in run-tool-with-model.ts):

{ type: 'function', function: { name: toolSpec.name } }

Passed as toolChoice parameter to force tool selection.

3. Gemini (Line 194 in run-tool-with-model.ts):

toolConfig: {
  functionCallingConfig: {
    mode: FunctionCallingConfigMode.ANY,
  },
}

Uses Gemini's FunctionCallingConfigMode.ANY to allow tool calls.

4. OpenAI Responses API (Line 362-374):

Uses JSON schema format with strict validation to constrain model output.

Handoff Tool Specification (thread-handoff.ts, lines 418-461):

The HANDOFF_TOOL forces extraction of:

relevantInformation - Context from conversation in first-person
relevantFiles - Workspace-relative file paths (up to 20 items)

SubAgent Tool Forcing Pattern:

/Users/nicolaygerold/code/amp/core/src/tools/sub-agent.ts - Shows how subagents force tool execution:

runInference() (lines 172-205) - Calls runAnthropicSync() with tools
Loop pattern (lines 106-158): Model → tool calls → execute tools → add results → repeat
No explicit tool_choice forcing; allows model freedom to call tools naturally

Thread Service Handoff Flow:

/Users/nicolaygerold/code/amp/core/src/threads/thread-service.ts (lines 556-586):

createHandoffThread() - Creates new thread with handoff relationship
generateHandoffPrompt() - Preview generation before creating thread
Links parent/child threads with "handoff" relationship type

Prompt Construction Pattern:

The handoff prompt consists of:

Thread ID reference: "Continuing work from thread ${thread.id}..."
File mentions: @file1 @file2 ...
Relevant information: Extracted context from source thread
User goal: The new task to complete

Related Files:

/Users/nicolaygerold/code/amp/specs/tool-calling.md - Complete tool calling architecture
/Users/nicolaygerold/code/amp/core/src/inference/backends/anthropic.ts - toolSpecsToAnthropicTools() function
/Users/nicolaygerold/code/amp/core/src/plan/handoff.ts - Plan-to-execution handoff

Key Code Patterns:

Force tool via tool_choice: Set tool_choice: { type: 'tool', name: toolSpec.name } in Anthropic API calls
Prompt construction: Combine thread context + files + goal with \n\n separators
Validation: Ensure model returns expected tool (lines 287-293 in run-tool-with-model.ts)
Subagent loop: Iteratively invoke tools returned by model until no more tools are called

Find the thread worker and inference:completed event handling. Look for where tool_use and end_turn stop reasons are handled, and where tool results are added to threads. Return file paths and line numbers.

Perfect! Let me now compile all the key findings:

Summary

Based on my search through the codebase, here are the file paths and line numbers for thread worker, inference:completed event handling, and tool result handling:

Core Files:

Thread Worker Main Class
- /Users/nicolaygerold/code/amp/core/src/threads/thread-worker.ts
Thread Delta Handler (thread state mutation logic)
- /Users/nicolaygerold/code/amp/core/src/threads/thread-delta.ts

Key Locations:

inference:completed Event Handling:

thread-worker.ts:1084-1131 - Main case handler for 'inference:completed' in the handle() method
- Lines 1110-1113: Check for 'end_turn' stop reason
- Lines 1105-1107: Invokes tools via executeToolsWithPlan() when stop reason is 'tool_use'
thread-delta.ts:661-670 - Delta application for 'inference:completed' event

tool_use Stop Reason Handling:

thread-worker.ts:1105-1107 - Call to findToolUsesNeedingInvocation() and executeToolsWithPlan() when stop reason is 'tool_use'
thread-worker.ts:2403 - Check for stopReason !== 'tool_use'

end_turn Stop Reason Handling:

thread-worker.ts:1110-1128 - Handles 'end_turn' stop reason, dequeues messages or runs hooks

Tool Execution Flow:

thread-worker.ts:1174-1188 - executeToolsWithPlan() method - orchestrates tool execution
thread-worker.ts:1210-1243 - invokeToolAndWait() method - waits for individual tool completion
thread-worker.ts:1245-1460 - invokeTool() method - main tool invocation logic

Tool Result Addition to Threads:

thread-delta.ts:536-588 - 'tool:data' case handler which calls addToolData() at line 548
thread-delta.ts:853-899 - addToolData() function - creates/updates tool_result blocks in user messages
- Lines 887-897: Creates new tool_result block or updates existing one
- Adds block to user message (line 897)

Tool Data Updates Propagation:

thread-worker.ts:946-1030 - 'tool:data' case handler in worker
- Lines 1381-1388: Calls updateThread() with tool run data

thread-delta.ts:853 - core function that handles adding tool results to threads

core/src/threads/thread-worker.ts
core/src/threads/thread-delta.ts

Find how Gemini models are configured and used in the codebase. Look for model selection, Gemini-specific configurations, and how to make inference calls with specific models.

Excellent! Now I have comprehensive information about Gemini model configuration and usage. Let me compile the final list of relevant files:

Based on my comprehensive search of the codebase, here are the files that contain information about how Gemini models are configured and used:

Core Gemini Backend Implementation

core/src/inference/backends/gemini.ts - Main Gemini implementation with VertexAIProvider class, runGemini() streaming function, runGeminiSync() synchronous function, and model resolution logic
core/src/inference/backends/gemini.test.ts - Test cases showing Gemini usage patterns

Model Definitions

core/src/inference/models-core.ts - Defines all available Gemini models (2.5 Pro, 2.5 Flash, 2.5 Flash Lite, 3 Pro Preview) with their capabilities, context windows, and max output tokens

Configuration & Settings

core/src/configuration/settings.ts - Settings schema including gemini.thinkingLevel configuration option
vscode/src/config.ts - VS Code configuration for gemini.thinkingLevel with 'high' and 'low' options
cli/src/docs.ts - CLI documentation for Gemini thinking level settings

System Prompts

core/src/threads/system-prompts/gemini.ts - Gemini-specific system prompt with tool definitions and examples

Inference Backend Resolution

core/src/inference/backend.ts - Backend provider resolution that routes to VertexAIProvider for Gemini models

Server-side Google API Proxy

server/src/routes/api/provider/google/[...proxyPath]/proxy-google-request.ts - Handles proxying requests to Google's Vertex AI API, manages authentication, and processes streaming/non-streaming responses
server/src/routes/api/provider/google/[...proxyPath]/+server.ts - Server endpoint that validates requests, manages credits, and routes to the proxy

Usage Examples

core/src/threads/commit-message.ts - Example of using runGeminiSync() with GEMINI_2_5_FLASH_LITE for commit message generation
core/src/threads/thread-mention-extraction.ts - Example of using runGeminiSync() with GEMINI_2_5_FLASH_LITE_PREVIEW for content extraction
vscode/src/review/git.ts - Multiple examples using runGeminiSync() with GEMINI_2_5_FLASH_LITE
vscode/src/autoedit/debug-panel/gemini-handler.ts - API call to gemini-2.5-flash model
vscode/src/autoedit/review-panel/gemini-handler.ts - API call to gemini-2.5-flash-lite-preview-09-2025 model