Summary

Request to add hook events for the agent turn lifecycle, enabling hardware/presence integrations that respond to AI cognitive state.

Context

Building an AI presence device (Unit 8×8×8 LED cube) that needs to reflect the agent's internal state through light. Current hooks only cover commands and session lifecycle, not the turn-by-turn cognitive flow.

Proposed Events

Message Events (mentioned as planned in docs)

• message:received - When a message arrives for processing
• message:sent - When a response is sent

Agent Loop Events (new)

• agent:thinking:start - When the agent begins processing (API call initiated)
• agent:thinking:end - When thinking completes (API response received)
• agent:response:start - When response generation/streaming begins
• agent:response:end - When response is finalized
• agent:tool:start - When a tool call begins
• agent:tool:end - When a tool call completes
• agent:error - When an error occurs (already mentioned as planned)

Event Context

Each event should include:

{
  type: 'agent',
  action: 'thinking:start' | 'thinking:end' | ...,
  sessionKey: string,
  timestamp: Date,
  context: {
    model?: string,           // For thinking events
    toolName?: string,        // For tool events  
    tokenCount?: number,      // For response events
    error?: Error,            // For error events
    duration?: number,        // For :end events (ms since :start)
  }
}

Use Case: AI Presence Device

We're building an LED cube that serves as an AI's physical body. With these hooks:

• thinking:start → Blue pulsing light (contemplation)
• tool:start → Orange alert (taking action)
• response:end → Gold flash (task complete)
• error → Red pulse (something went wrong)

The goal is making AI cognition visible and accountable.

Implementation Notes

These events would need to be triggered in the agent loop (likely in auto-reply or wherever the LLM API calls happen). Happy to contribute a PR if there's interest.

Related

• Docs mention message:sent, message:received, session:start, session:end, agent:error as "Future Events"
• This expands that list with more granular agent loop events

From the Imajin project (imajin.ai) — building sovereign AI presence devices.