Summary

Add hook events that fire when the agent invokes tools, enabling real-time UI feedback for tool usage.

Motivation

I'm building a visual dashboard (Trinity UI) that shows agent state in real-time. I want to light up icons when the agent uses specific tools (web search, file operations, browser, etc.).

Currently, hooks only fire on high-level events like agent:bootstrap, command:new, command:reset. There's no way to know when a tool is being invoked.

Proposed Events

• tool:start - fires when agent begins a tool call
  • Payload: { tool: string, parameters: object, timestamp: number }
• tool:end - fires when tool call completes
  • Payload: { tool: string, result: object, duration: number, success: boolean }

Optionally:

• thinking:start - when Claude begins generating a response
• thinking:end - when response generation completes
• stream:chunk - for real-time response streaming

Use Case

With these events, a hook could push updates to an external dashboard:

// In hook handler
export async function onToolStart({ tool, parameters }) {
  await fetch('https://my-dashboard/api/tool', {
    method: 'POST',
    body: JSON.stringify({ tool, active: true })
  });
}

Current Workaround

The only alternative is having the agent manually self-report tool usage via API calls, which adds latency and is error-prone.

Environment

• Clawdbot version: 2026.1.22
• Use case: Trinity UI dashboard for real-time agent monitoring

Thanks for considering!