optimclaw/.claude/commands/trace.md

description, allowed-tools, argument-hint, model

description	allowed-tools	argument-hint	model
Trace a data flow or bug through the OptimClaw codebase end-to-end	Read, Glob, Grep, Bash(cargo test:*)	<symptom or feature name>	sonnet

Trace the flow of $ARGUMENTS through the OptimClaw codebase. Your job is to map every file and function involved, identify where data transforms or could break, and report the full chain.

Architecture Reference

OptimClaw has three main data flow paths. Identify which one(s) are relevant and trace through them:

Message Flow (user input to LLM response)

Channel (cli/web/wasm) → IncomingMessage
  → Agent::run() message loop (agent_loop.rs)
    → handle_message() dispatches by Submission type
      → SubmissionParser::parse() (submission.rs) classifies input
      → process_user_input() for new turns
      → process_approval() for tool approval responses
      → handle_command() for /commands
    → run_agentic_loop() iterates LLM calls
      → Reasoning::respond_with_tools() (reasoning.rs)
        → LlmProvider::complete_with_tools() (nearai_chat.rs or nearai.rs)
      → Tool execution with approval gating
      → Context message accumulation
    → Response flows back through Channel::send_response()

SSE Event Flow (backend status to web UI)

StatusUpdate variant (channel.rs)
  → Channel::send_status() trait method
    → WebChannel::send_status() (web/mod.rs) maps to SseEvent
      → broadcast via tokio::broadcast channel
    → SSE endpoint streams events (web/server.rs)
      → Browser EventSource listener (app.js)
        → DOM update function
        → CSS styling (style.css)

Tool Flow (tool definition to execution)

Tool trait impl (tools/builtin/*.rs or tools/mcp/client.rs or tools/wasm/wrapper.rs)
  → ToolRegistry::register() (tools/registry.rs)
  → tool_definitions() builds Vec<ToolDefinition> for LLM
    → ToolDefinition { name, description, parameters } (llm/provider.rs)
    → Serialized to ChatCompletionTool (nearai_chat.rs)
  → LLM returns ToolCall { id, name, arguments }
  → agent_loop.rs executes via execute_chat_tool()
    → Safety layer sanitizes output
    → Result added as ChatMessage::tool_result()

Tracing Instructions

1. Read each file in the relevant flow path, focusing on the functions that handle the data.
2. Identify transforms: Where does the data change shape? (e.g., McpTool.input_schema → ToolDefinition.parameters → ChatCompletionTool.function.parameters)
3. Identify failure points: Where could the data be lost, malformed, or misrouted?
4. Report the chain: List every file:line involved, what happens at each step, and where the issue (if any) is.

Key Files Quick Reference

Area	File	Key Functions
Message dispatch	src/agent/agent_loop.rs	handle_message, process_user_input, process_approval, run_agentic_loop
Input parsing	src/agent/submission.rs	SubmissionParser::parse
LLM reasoning	src/llm/reasoning.rs	respond_with_tools, select_tools, plan
Chat completions	src/llm/nearai_chat.rs	complete_with_tools, From<ChatMessage>
Responses API	src/llm/nearai.rs	complete_with_tools, split_messages
Channel trait	src/channels/channel.rs	Channel, StatusUpdate, IncomingMessage
Web gateway	src/channels/web/mod.rs	send_status, send_response
Web server	src/channels/web/server.rs	Route handlers, SSE endpoints
Web frontend	src/channels/web/static/app.js	SSE listeners, DOM builders
Tool registry	src/tools/registry.rs	tool_definitions, get, register
MCP tools	src/tools/mcp/client.rs	McpToolWrapper, list_tools, call_tool
MCP protocol	src/tools/mcp/protocol.rs	McpTool, inputSchema
Safety	src/safety/sanitizer.rs	sanitize_tool_output, wrap_for_llm
Session state	src/agent/session.rs	ThreadState, Turn, PendingApproval

Output Format

Report your findings as:

1. Flow path: The specific chain of files and functions involved
2. Data transforms: How the data changes at each step
3. Findings: Any bugs, missing data, or suspicious patterns
4. Recommendation: What to fix or investigate further