Summary

This PR adds a bridge that connects agent runtime tool events to the internal hooks system, enabling workspace hooks to react to tool execution lifecycle events.

Closes #2904

Problem

When an agent session is churning through tool calls (long-running exec, polling background processes, etc.), external UIs like Discord go silent even though the agent is actively working. There was no visibility into what the agent was doing.

Solution

Introduces a Tool Hook Bridge (src/infra/agent-hook-bridge.ts) that:

1. Subscribes to agent events via onAgentEvent()
2. Filters for stream: "tool" events
3. Translates them to internal hook events (type: "tool")
4. Triggers hooks with tool:start, tool:update, tool:result actions

Hook Event Structure

{
  type: "tool",
  action: "start" | "update" | "result",
  sessionKey: "agent:main:discord:channel:123456",
  timestamp: Date,
  context: {
    runId: string,
    toolName: string,
    toolCallId: string,
    args?: unknown,           // on start
    partialResult?: unknown,  // on update
    result?: unknown,         // on result
    isError?: boolean,        // on result
    meta: object,
    sessionMeta: {            // Parsed for convenience
      agentId: string,
      platform: string,       // discord, telegram, etc.
      channelType: string,
      channelId: string,
    }
  }
}

Key Design Decisions

1. Update events NOT throttled at bridge level — Hook scripts handle their own rate limiting. This allows both throttled Discord updates AND real-time WebSocket streaming.

2. Fire-and-forget — void triggerInternalHook() so tool execution isn't blocked by slow hooks.

3. Reuses existing utilities — Uses parseAgentSessionKey from session-key-utils.js

4. Dedicated module — Keeps gateway startup clean, follows existing patterns.

Changes

• NEW: src/infra/agent-hook-bridge.ts - The bridge implementation
• NEW: src/infra/agent-hook-bridge.test.ts - Comprehensive tests
• MODIFIED: src/hooks/internal-hooks.ts - Adds "tool" to InternalHookEventType
• MODIFIED: src/gateway/server-startup.ts - Starts bridge when hooks are enabled

Testing

Added tests for:

• tool:start, tool:update, tool:result events
• sessionMeta parsing (including colons in IDs like Matrix)
• Malformed/empty session keys
• Missing required fields (toolCallId, name)
• Non-tool streams ignored
• Unknown phases ignored
• Double-subscription prevention
• Stop functionality

Example Hook Script

// hooks/tool-visibility/handler.js
const activeTools = new Map();

export default async function(event) {
    if (event.type !== 'tool') return;
    
    const { sessionMeta, toolCallId, toolName } = event.context;
    if (sessionMeta.platform !== 'discord') return;
    
    if (event.action === 'start') {
        const msgId = await postEmbed({ title: `⚙️ ${toolName}` });
        activeTools.set(toolCallId, { msgId, startTime: Date.now() });
    }
    
    if (event.action === 'result') {
        const tracked = activeTools.get(toolCallId);
        if (tracked) {
            await updateEmbed(tracked.msgId, { title: `✅ ${toolName}` });
            activeTools.delete(toolCallId);
        }
    }
}

Review Notes

• Architecture reviewed by external agent (Gemini 3 Pro) - approved with minor suggestions which have been addressed
• This is a shallow clone, so diff against main might show false conflicts