Roo-Code/ARCHITECTURE_NOTES.md

Architecture Notes - Roo Code Extension

Date: 2026-02-16
Phase: 0 - Archaeological Dig
Goal: Map the codebase structure for hook system injection

---

Executive Summary

This document maps the Roo Code extension architecture to identify injection points for the Intent-Code Traceability hook system. The hook system will enforce a two-stage state machine (Reasoning Loop) and maintain .orchestration/ directory for intent tracking.

---

1. Tool Execution Flow

1.1 Entry Point: presentAssistantMessage()

File: src/core/assistant-message/presentAssistantMessage.ts

Function: presentAssistantMessage(cline: Task) (line 61)

Flow:

1. LLM generates assistant message with tool calls
2. Function processes content blocks sequentially
3. For each ToolUse block, routes to specific tool handler via switch (block.name) (line 678)
4. Tools are executed with callbacks: askApproval, handleError, pushToolResult

Key Tool Handlers:

• write_to_file → WriteToFileTool.handle() (line 681)
• execute_command → ExecuteCommandTool.handle() (line 750)
• edit_file → EditFileTool.handle() (line 721)
• Custom tools → customToolRegistry.get(block.name) (line 419)

Hook Injection Point:

• Pre-Hook: Before tool.handle() call (line 681, 721, etc.)
• Post-Hook: After tool.execute() completes, before pushToolResult()

---

1.2 Tool Base Architecture

File: src/core/tools/BaseTool.ts

Class: BaseTool<TName extends ToolName> (line 29)

Key Methods:

• abstract execute(params, task, callbacks): Promise<void> - Main execution logic
• async handlePartial(task, block): Promise<void> - Streaming support
• resetPartialState(): void - Cleanup

Tool Instances: All tools are singleton instances imported at module level:

• writeToFileTool from WriteToFileTool.ts
• executeCommandTool from ExecuteCommandTool.ts
• editFileTool from EditFileTool.ts
• etc.

Hook Injection Strategy:

• Wrap execute() method calls
• Intercept in presentAssistantMessage() before tool.handle()
• Store active intent context in Task instance

---

1.3 Tool Registration

File: src/core/task/build-tools.ts

Function: buildNativeToolsArrayWithRestrictions() (line 82)

Process:

1. Filters native tools based on mode
2. Loads MCP tools from mcpHub
3. Loads custom tools from .roo/tools/ directories via customToolRegistry
4. Returns combined tool array for LLM

Custom Tool Registry:

• File: packages/core/src/custom-tools/custom-tool-registry.ts
• Class: CustomToolRegistry (line 31)
• Methods: register(), get(), has(), getAllSerialized()

Hook Injection Point:

• Add select_active_intent to native tools array
• Register via custom tool registry OR add to native tools list

---

2. System Prompt Construction

2.1 Prompt Builder

File: src/core/prompts/system.ts

Main Function: SYSTEM_PROMPT() (line 112)

Called From: Task.getSystemPrompt() (line 3745 in Task.ts)

Construction Flow:

1. Gets mode configuration and role definition
2. Builds sections: formatting, tool use, capabilities, modes, rules, system info
3. Adds custom instructions and rooignore rules
4. Returns complete prompt string

Key Sections:

• roleDefinition - Mode-specific role (line 65)
• getSharedToolUseSection() - Tool catalog
• getToolUseGuidelinesSection() - Tool usage rules
• getRulesSection() - Workspace rules
• getObjectiveSection() - Task objectives

Hook Injection Point:

• Modify getToolUseGuidelinesSection() or add new section
• Add Reasoning Loop instructions before tool guidelines
• Enforce: "You MUST call select_active_intent before writing code"

---

2.2 Prompt Usage

File: src/core/task/Task.ts

Method: getSystemPrompt() (line 3745)

Called During:

• Initial task creation
• Each LLM request (via recursivelyMakeClineRequests())

Hook Injection Point:

• Intercept prompt before sending to LLM
• Inject active intent context if select_active_intent was called
• Add <intent_context> XML block to prompt

---

3. Task Lifecycle

3.1 Task Class

File: src/core/task/Task.ts

Class: Task (line 163)

Key Properties:

• taskId: string - Unique task identifier
• cwd: string - Working directory
• providerRef: WeakRef<ClineProvider> - Extension provider reference
• api: ApiHandler - LLM API handler
• clineMessages: Anthropic.Message[] - Conversation history

Key Methods:

• startTask(text, images) - Initialize task
• recursivelyMakeClineRequests() - Main LLM request loop
• getSystemPrompt() - Get system prompt
• say(), ask() - User interaction methods

Hook Storage Point:

• Add activeIntentId?: string property to Task
• Store intent context loaded from .orchestration/active_intents.yaml

---

4. Extension Architecture

4.1 Extension Host

File: src/extension.ts

Function: activate(context: vscode.ExtensionContext) (line 120)

Initialization:

1. Creates ClineProvider instance
2. Registers commands and webview
3. Sets up MCP hub if enabled
4. Initializes code index manager

Provider:

• File: src/core/webview/ClineProvider.ts
• Class: ClineProvider
• Manages tasks, state, and webview communication

---

4.2 Webview Communication

Flow:

1. Webview (UI) sends messages via postMessage
2. webviewMessageHandler.ts routes messages
3. Provider creates/updates tasks
4. Tasks execute tools and send results back

Hook Injection Point:

• Intercept webview messages before task creation
• Validate intent selection before allowing tool execution

---

5. File System Operations

5.1 Write Operations

Tools:

• WriteToFileTool - Full file write
• EditFileTool - Partial file edits
• ApplyDiffTool - Diff-based edits
• SearchReplaceTool - Search/replace operations

Common Pattern:

1. Validate parameters
2. Check rooIgnoreController for access
3. Show diff view (if enabled)
4. Request approval via askApproval()
5. Save changes via diffViewProvider.saveChanges()
6. Track file context
7. Push tool result

Hook Injection Points:

• Pre-Hook: Before askApproval() - Check intent scope
• Post-Hook: After saveChanges() - Log to agent_trace.jsonl

---

6. Hook System Architecture (Planned)

6.1 Hook Engine Location

Proposed File: src/core/hooks/HookEngine.ts

Responsibilities:

• Intercept tool execution requests
• Enforce Pre-Hook and Post-Hook logic
• Manage intent context injection
• Validate scope and constraints

Integration Points:

1. Wrap tool execution in presentAssistantMessage()
2. Inject into BaseTool.execute() wrapper
3. Store hook state in Task instance

---

6.2 Orchestration Directory

Location: .orchestration/ in workspace root

Files:

• active_intents.yaml - Intent specifications
• agent_trace.jsonl - Append-only trace ledger
• intent_map.md - Spatial mapping
• AGENT.md - Shared knowledge base

Access:

• Read/write via Node.js fs APIs
• Initialize on first task creation
• Validate on extension activation

---

7. Implementation Strategy

7.1 Phase 1: The Handshake

Steps:

1. Create SelectActiveIntentTool extending BaseTool
2. Add tool to native tools array in build-tools.ts
3. Create HookEngine class with Pre-Hook/Post-Hook methods
4. Modify presentAssistantMessage() to call hooks
5. Create .orchestration/ directory structure
6. Implement OrchestrationDataModel for YAML/JSONL access
7. Modify system prompt to enforce Reasoning Loop
8. Implement context injection for select_active_intent

---

7.2 File Structure (Planned)

src/
  core/
    hooks/
      HookEngine.ts          # Main hook middleware
      PreHook.ts             # Pre-execution hooks
      PostHook.ts            # Post-execution hooks
      OrchestrationDataModel.ts  # Data model access
    tools/
      SelectActiveIntentTool.ts  # New intent selection tool
    orchestration/
      ActiveIntentsManager.ts    # YAML management
      AgentTraceLogger.ts        # JSONL logging
      IntentMapManager.ts         # Markdown mapping

---

8. Key Dependencies

8.1 External Libraries

• @anthropic-ai/sdk - LLM API
• yaml - YAML parsing (need to add)
• crypto - SHA-256 hashing (built-in)
• fs/promises - File system operations

8.2 Internal Dependencies

• @roo-code/types - Type definitions
• @roo-code/core - Core utilities
• Task class - Task lifecycle
• BaseTool - Tool base class

---

9. Testing Strategy

9.1 Unit Tests

• Hook engine interception logic
• Orchestration data model read/write
• Intent context injection
• Scope validation

9.2 Integration Tests

• End-to-end tool execution with hooks
• Intent selection → context injection → code write
• Trace logging verification
• Parallel agent collision detection

---

10. Open Questions

1. Tool Registration: Should select_active_intent be a native tool or custom tool?

   • Decision: Native tool (simpler, always available)

2. Hook Timing: Should hooks be synchronous or async?

   • Decision: Async (allows for file I/O and user prompts)

3. Error Handling: How to handle hook failures?

   • Decision: Fail-safe - log error, allow execution to continue with warning

4. State Persistence: Where to store active intent ID?

   • Decision: Task instance property + .orchestration/active_intents.yaml

---

11. Next Steps

1. ✅ Complete Phase 0 (this document)
2. ⏳ Implement Phase 1: The Handshake
   • Create SelectActiveIntentTool
   • Build HookEngine infrastructure
   • Implement .orchestration/ data models
   • Modify system prompt
3. ⏳ Implement Phase 2: Hook Middleware & Security
4. ⏳ Implement Phase 3: AI-Native Git Layer
5. ⏳ Implement Phase 4: Parallel Orchestration

---

Complete execution flow diagram ┌─────────────────────────────────────────────────────────────┐ │ 1. LLM Response (Streaming) │ │ Anthropic API → Task.recursivelyMakeClineRequests() │ └──────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 2. Tool Call Parsing │ │ Task.ts:2989-3016 │ │ - Receives "tool_call" chunk │ │ - Parses via NativeToolCallParser │ │ - Creates ToolUse object │ │ - Adds to assistantMessageContent[] │ └──────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 3. Message Presentation Router │ │ presentAssistantMessage.ts:63 │ │ - Checks lock (prevents concurrent execution) │ │ - Gets current block from assistantMessageContent │ │ - Routes by block.type → "tool_use" │ └──────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 4. Tool Routing (SWITCH STATEMENT) │ │ presentAssistantMessage.ts:691 │ │ switch (block.name) { │ │ case "write_to_file": │ │ case "execute_command": │ │ ... │ │ } │ └──────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 5. Tool Execution │ │ tool.handle(task, block, callbacks) │ │ BaseTool.ts:113 │ │ - Parses block.nativeArgs → params │ │ - Calls tool.execute(params, task, callbacks) │ └──────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 6. Actual Tool Logic │ │ WriteToFileTool.execute() or ExecuteCommandTool.execute()│ │ - Validates parameters │ │ - Checks permissions │ │ - Asks user approval │ │ - Performs operation │ │ - Calls pushToolResult() │ └──────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 7. Result Back to LLM │ │ pushToolResult() → task.pushToolResultToUserContent() │ │ - Creates tool_result block │ │ - Adds to userMessageContent[] │ │ - LLM receives result in next request │ └─────────────────────────────────────────────────────────────┘

End of Architecture Notes