Feature Request: Add Agent Lifecycle Hook Events

Summary

Add hook events for agent message lifecycle (agent:response, message:sent, tool:complete) to enable automatic logging and automation workflows.

Motivation

The current hook system supports command events (command:new, command:reset) and bootstrap events (agent:bootstrap), but lacks events for the agent response lifecycle. This prevents automation use cases like:

• Automatic interaction logging - Track what the agent did, which tools were used, and outcomes
• Pattern detection - Analyze repeated workflows to suggest optimizations or create new skills
• Audit trails - Log all agent actions for debugging and compliance
• Post-response automation - Trigger follow-up actions after agent completes a task

Proposed Events

1. agent:response

Triggered after the agent completes a response but before it's sent to the user.

Event context:

{
  type: 'agent',
  action: 'response',
  sessionKey: string,
  timestamp: Date,
  context: {
    sessionEntry?: SessionEntry,
    responseText: string,
    toolCalls: Array<{
      tool: string,
      args: any,
      result: any,
      success: boolean
    }>,
    tokenUsage: {
      input: number,
      output: number
    }
  }
}

2. message:sent

Triggered after a message is successfully sent to the channel.

Event context:

{
  type: 'message',
  action: 'sent',
  sessionKey: string,
  timestamp: Date,
  context: {
    channel: string, // 'telegram', 'whatsapp', etc.
    messageId?: string,
    recipientId: string
  }
}

3. tool:complete (optional)

Triggered after each individual tool call completes.

Event context:

{
  type: 'tool',
  action: 'complete',
  sessionKey: string,
  timestamp: Date,
  context: {
    toolName: string,
    args: any,
    result: any,
    success: boolean,
    durationMs: number
  }
}

Use Case Example

Automatic Interaction Logger Hook:

// hooks/auto-logger/handler.ts
import type { HookHandler } from '../../src/hooks/hooks.js';

const autoLogger: HookHandler = async (event) => {
  if (event.type !== 'agent' || event.action !== 'response') {
    return;
  }

  const interaction = {
    timestamp: event.timestamp.toISOString(),
    sessionKey: event.sessionKey,
    tools: event.context.toolCalls?.map(t => t.tool) || [],
    outcome: event.context.toolCalls?.every(t => t.success) ? 'success' : 'partial',
    tokens: event.context.tokenUsage
  };

  // Append to interactions.jsonl
  await fs.appendFile('data/interactions.jsonl', JSON.stringify(interaction) + '\n');
};

export default autoLogger;

Benefits

1. Zero user intervention - Logging happens automatically without manual commands
2. Extensibility - Enables community to build powerful automation workflows
3. Consistency - Follows existing hook patterns (command:*, agent:bootstrap)
4. Backward compatibility - New events, existing hooks unaffected

Alternative Considered

Plugin API tool_result_persist - Already exists but:

• Only works in plugins, not standalone hooks
• Requires more complex setup
• Synchronous only

Adding proper lifecycle events would complement the plugin API and enable simpler use cases.

Questions

1. Should agent:response fire before or after message queueing?
2. Should there be separate events for streaming vs non-streaming responses?
3. Should tool errors trigger tool:error or just include success: false in tool:complete?

Related: Docs mention planned events like session:start, session:end, message:received - this request aligns with that roadmap.