Roo-Code/PHASE_3_INTEGRATION_GUIDE.md

Phase 3 Integration Guide: Wiring Post-Hook

This guide covers integrating TraceLogger into the tool dispatcher to enable automatic trace logging for all write operations.

Current State

• Gatekeeper (Pre-Hook): ✅ Active in presentAssistantMessage.ts
  • Blocks restricted tools without active intent
  • Returns XML context block
• TraceLogger (Utility): ✅ Ready in src/core/intent/TraceLogger.ts
  • All methods implemented and tested
  • Requires integration point to be triggered
• Write Tool Schema: ✅ Updated with intent_id and mutation_class parameters
  • Tools now include required fields for trace context

Integration Points

Option 1: Direct Integration in presentAssistantMessage.ts

1. Import TraceLogger:

import { TraceLogger } from "@/core/intent/TraceLogger"
const traceLogger = new TraceLogger()

2. Add Post-Hook After Tool Execution: After successful tool result processing (around line where pushToolResult() is called):

// Extract tool parameters
const toolParams = block.input
const intentId = toolParams.intent_id || intentHookEngine.getCurrentSessionIntent()
const mutationClass = toolParams.mutation_class

// For write_to_file tools specifically:
if (block.name === "write_to_file") {
	const filePath = toolParams.path
	const content = toolParams.content

	// Log to trace
	traceLogger.logTrace(
		intentId,
		filePath,
		content,
		mutationClass,
		messageInfo.id.requestId, // if available
	)
}

3. Location: After the tool result is successfully pushed, before moving to next tool block

Option 2: Centralized Tool Dispatcher

Create a new module src/core/tools/toolDispatcher.ts:

import { TraceLogger } from "@/core/intent/TraceLogger"
import { IntentHookEngine } from "@/core/intent/IntentHookEngine"

export class ToolDispatcher {
	private traceLogger: TraceLogger
	private intentHookEngine: IntentHookEngine

	constructor(intentHookEngine: IntentHookEngine) {
		this.traceLogger = new TraceLogger()
		this.intentHookEngine = intentHookEngine
	}

	async executeTool(toolName: string, toolParams: Record<string, any>) {
		// Pre-hook: gatekeeper validation
		const gate = this.intentHookEngine.gatekeeper(toolName)
		if (!gate.allowed) {
			throw new Error(gate.message)
		}

		// Execute tool...
		const result = await this.executeToolImpl(toolName, toolParams)

		// Post-hook: trace logging
		if (toolName === "write_to_file" && result.success) {
			this.traceLogger.logTrace(
				toolParams.intent_id,
				toolParams.path,
				toolParams.content,
				toolParams.mutation_class,
				this.getRequestId(),
			)
		}

		return result
	}

	private async executeToolImpl(toolName: string, toolParams: Record<string, any>) {
		// ... existing tool execution logic
	}
}

Testing Integration

Once integrated, test with:

# Run integration test to verify trace logging
pnpm -w exec vitest run tests/phase3-integration.test.ts --run

# Check generated trace file
cat .orchestration/agent_trace.jsonl | jq '.'

# Query traces for specific intent
pnpm -w exec node -e "
  const { TraceLogger } = require('./src/core/intent/TraceLogger');
  const tl = new TraceLogger();
  console.log(JSON.stringify(tl.getTracesByIntent('intent-123'), null, 2))
"

Verification Checklist

• TraceLogger imported without errors
• Post-hook executes after write_to_file completes
• Trace entries appear in .orchestration/agent_trace.jsonl
• content_hash matches SHA-256 of written content
• intent_id correctly populated from active session
• mutation_class correctly extracted from tool params
• Multiple entries append without overwriting
• Read/query methods work on generated files
• req_id optional parameter captured when available

Minimal Integration (Quick Win)

If full dispatcher refactoring is too large, add this snippet to presentAssistantMessage.ts right after tool execution:

// Add at top of file
import { TraceLogger } from "@/core/intent/TraceLogger"
const traceLogger = new TraceLogger()

// Add in tool block processing loop
if (toolName === "write_to_file" && success) {
	const params = block.input
	traceLogger.logTrace(params.intent_id, params.path, params.content, params.mutation_class)
}

Schema Validation

Ensure tool schema is enforced before dispatch:

// Validate intent_id and mutation_class are present
if (!toolParams.intent_id) {
	throw new Error("write_to_file requires intent_id parameter")
}
if (!["AST_REFACTOR", "INTENT_EVOLUTION"].includes(toolParams.mutation_class)) {
	throw new Error("write_to_file requires valid mutation_class")
}

Performance Considerations

• TraceLogger uses synchronous file I/O (fs.appendFileSync)
• For high-volume writes, consider batching trace entries
• JSONL format doesn't require database; scales to millions of entries
• Consider async variant using fs.promises for I/O performance

Rollback Plan

If issues arise:

1. Disable trace logging: Comment out traceLogger.logTrace() call
2. Archive trace file: mv .orchestration/agent_trace.jsonl .orchestration/agent_trace.jsonl.bak
3. Verify gatekeeper still works (it's independent of tracing)

Future Enhancements

• Async file I/O for better performance
• Trace batching and flushing
• Integration with git hooks for verification
• Dashboard visualization of mutation timeline
• Trace encryption for sensitive operations