dd hook socket for reliable agent status via IPC

  - Introduce Unix socket server to receive agent status events
    directly, bypassing fragile PTY output scanning
  - Add hook client (--agent-event flag) to forward events from
    stdin to the socket
  - Auto-install Claude Code hooks on startup
  - Pass AIPILOT_HOOK_SOCKET env var to agent process
  - Upgrade ANSI escape parser to proper state machine (CSI/OSC)
  - Disable PTY scanning when hook socket is active

Author: hhfrancois

agent_status.go

@@ -16,6 +16,15 @@ const (
 	agentStatusBufSize = 256
 )
 
+// ANSI escape sequence parser states
+const (
+	escNone   = 0 // Normal text
+	escStart  = 1 // Just saw ESC (0x1b)
+	escCSI    = 2 // In CSI sequence: ESC [ ... letter
+	escOSC    = 3 // In OSC sequence: ESC ] ... (BEL or ST)
+	escOSCESC = 4 // In OSC, saw ESC (awaiting \ for ST terminator)
+)
+
 // busyPattern is the lowercase pattern to detect in PTY output
 var busyPattern = []byte("esc to ")
 
@@ -27,32 +36,73 @@ func (d *Daemon) initAgentStatus() {
 // scanAgentStatus scans PTY output for the busy pattern.
 // Called from startPTYReader on every read — must be fast.
 func (d *Daemon) scanAgentStatus(data []byte) {
-	// Append printable chars (lowercased) to rolling buffer, skip ANSI sequences
-	inEscape := d.agentStatusInEscape
+	// Skip PTY scanning when receiving status via hook socket
+	if d.agentStatusViaSocket {
+		return
+	}
+
+	state := d.agentEscState
 	buf := d.agentStatusBuf
 
 	for _, b := range data {
-		if inEscape {
-			// Inside ANSI escape: wait for terminating letter
+		switch state {
+		case escNone:
+			if b == 0x1b {
+				state = escStart
+				continue
+			}
+			// Only keep printable ASCII, lowercase on the fly
+			if b >= 0x20 && b <= 0x7e {
+				if b >= 'A' && b <= 'Z' {
+					b += 0x20
+				}
+				buf = append(buf, b)
+			}
+
+		case escStart:
+			// Byte right after ESC determines the sequence type
+			if b == '[' {
+				state = escCSI
+			} else if b == ']' {
+				state = escOSC
+			} else {
+				// Two-byte escape (e.g. ESC c, ESC M) — done
+				state = escNone
+			}
+
+		case escCSI:
+			// CSI: ESC [ (params) letter — letter terminates
 			if (b >= 'A' && b <= 'Z') || (b >= 'a' && b <= 'z') {
-				inEscape = false
+				state = escNone
 			}
-			continue
-		}
-		if b == 0x1b {
-			inEscape = true
-			continue
-		}
-		// Only keep printable ASCII
-		if b >= 0x20 && b <= 0x7e {
-			// Lowercase on the fly
-			if b >= 'A' && b <= 'Z' {
-				b += 0x20
+			// else: parameters (digits, ;, ?, etc.) — keep consuming
+
+		case escOSC:
+			// OSC: ESC ] ... terminated by BEL (0x07) or ST (ESC \)
+			if b == 0x07 {
+				state = escNone
+			} else if b == 0x1b {
+				state = escOSCESC
+			}
+			// else: OSC content — keep consuming
+
+		case escOSCESC:
+			// Inside OSC, saw ESC — if next is \, it's ST (end of OSC)
+			if b == '\\' {
+				state = escNone
+			} else {
+				// Not ST — treat as new escape sequence
+				if b == '[' {
+					state = escCSI
+				} else if b == ']' {
+					state = escOSC
+				} else {
+					state = escNone
+				}
 			}
-			buf = append(buf, b)
 		}
 	}
-	d.agentStatusInEscape = inEscape
+	d.agentEscState = state
 
 	// Trim buffer to max size (keep tail)
 	if len(buf) > agentStatusBufSize {

hook_claude.go

@@ -0,0 +1,151 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+// Claude Code specific hook installation.
+// This file contains only Claude-specific code. When another agent
+// supports hooks, create a similar hook_<agent>.go file.
+
+// claudeSettingsPath returns the path to Claude Code's settings.json
+func claudeSettingsPath() string {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return ""
+	}
+	return filepath.Join(home, ".claude", "settings.json")
+}
+
+// hookCommand is the command that Claude Code will execute for each hook event
+const hookCommand = "aipilot-cli --agent-event"
+
+// claudeHookEvents lists the Claude Code events we want to hook into
+var claudeHookEvents = []string{"UserPromptSubmit", "Stop", "StopFailure"}
+
+// ensureClaudeHooksInstalled reads ~/.claude/settings.json and adds
+// aipilot hook entries for agent status detection if not already present.
+func ensureClaudeHooksInstalled() {
+	settingsPath := claudeSettingsPath()
+	if settingsPath == "" {
+		return
+	}
+
+	// Read existing settings
+	settings, err := readClaudeSettings(settingsPath)
+	if err != nil {
+		fmt.Printf("%s[hook] Cannot read Claude settings: %v%s\n", dim, err, reset)
+		return
+	}
+
+	// Ensure hooks section exists
+	hooks, ok := settings["hooks"].(map[string]interface{})
+	if !ok {
+		hooks = make(map[string]interface{})
+		settings["hooks"] = hooks
+	}
+
+	modified := false
+	for _, eventName := range claudeHookEvents {
+		if addClaudeHookIfMissing(hooks, eventName) {
+			modified = true
+		}
+	}
+
+	if !modified {
+		return
+	}
+
+	// Write back
+	if err := writeClaudeSettings(settingsPath, settings); err != nil {
+		fmt.Printf("%s[hook] Cannot write Claude settings: %v%s\n", dim, err, reset)
+		return
+	}
+
+	fmt.Printf("%s[hook] Installed aipilot hooks in %s%s\n", dim, settingsPath, reset)
+}
+
+// addClaudeHookIfMissing adds an aipilot hook entry to the given event array
+// if one doesn't already exist. Returns true if the settings were modified.
+func addClaudeHookIfMissing(hooks map[string]interface{}, eventName string) bool {
+	// Get or create the event array
+	var eventEntries []interface{}
+	if existing, ok := hooks[eventName]; ok {
+		if arr, ok := existing.([]interface{}); ok {
+			eventEntries = arr
+		}
+	}
+
+	// Check if aipilot hook is already installed
+	for _, entry := range eventEntries {
+		entryMap, ok := entry.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		hooksList, ok := entryMap["hooks"].([]interface{})
+		if !ok {
+			continue
+		}
+		for _, h := range hooksList {
+			hookMap, ok := h.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			if cmd, ok := hookMap["command"].(string); ok && cmd == hookCommand {
+				return false // Already installed
+			}
+		}
+	}
+
+	// Add new entry
+	newEntry := map[string]interface{}{
+		"matcher": "",
+		"hooks": []interface{}{
+			map[string]interface{}{
+				"type":    "command",
+				"command": hookCommand,
+				"timeout": 5,
+				"async":   true,
+			},
+		},
+	}
+
+	hooks[eventName] = append(eventEntries, newEntry)
+	return true
+}
+
+// readClaudeSettings reads and parses Claude Code's settings.json
+func readClaudeSettings(path string) (map[string]interface{}, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			// No settings file yet — start fresh
+			return make(map[string]interface{}), nil
+		}
+		return nil, err
+	}
+
+	var settings map[string]interface{}
+	if err := json.Unmarshal(data, &settings); err != nil {
+		return nil, err
+	}
+	return settings, nil
+}
+
+// writeClaudeSettings writes settings back to Claude Code's settings.json
+func writeClaudeSettings(path string, settings map[string]interface{}) error {
+	// Ensure directory exists
+	if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+		return err
+	}
+
+	data, err := json.MarshalIndent(settings, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(path, append(data, '\n'), 0644)
+}

hook_client.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"os"
+)
+
+// agentEventMain is the entry point for --hook mode.
+// It reads a Claude Code hook payload from stdin, maps it to a generic
+// HookMessage, and sends it to the AIPILOT_HOOK_SOCKET Unix socket.
+// Exits silently with code 0 in all cases (must not block the agent).
+func agentEventMain() {
+	socketPath := os.Getenv("AIPILOT_HOOK_SOCKET")
+	if socketPath == "" {
+		// Not running under aipilot — exit silently
+		os.Exit(0)
+	}
+
+	// Read hook payload from stdin
+	input, err := io.ReadAll(os.Stdin)
+	if err != nil || len(input) == 0 {
+		os.Exit(0)
+	}
+
+	// Extract hook_event_name from the payload
+	var payload struct {
+		HookEventName string `json:"hook_event_name"`
+	}
+	if err := json.Unmarshal(input, &payload); err != nil {
+		os.Exit(0)
+	}
+
+	// Map agent-specific event to generic hook message
+	msg := mapHookEvent(payload.HookEventName)
+	if msg == nil {
+		// Unknown or unhandled event — ignore
+		os.Exit(0)
+	}
+
+	// Send to socket
+	data, err := json.Marshal(msg)
+	if err != nil {
+		os.Exit(0)
+	}
+
+	conn, err := net.Dial("unix", socketPath)
+	if err != nil {
+		// Socket not available (CLI may have exited) — exit silently
+		os.Exit(0)
+	}
+	defer conn.Close()
+
+	fmt.Fprintf(conn, "%s\n", data)
+}
+
+// mapHookEvent maps a hook event name to a generic HookMessage.
+// Currently supports Claude Code events. Add other agents here.
+func mapHookEvent(eventName string) *HookMessage {
+	switch eventName {
+	case "UserPromptSubmit":
+		return newAgentStatusMessage("busy")
+	case "Stop", "StopFailure":
+		return newAgentStatusMessage("idle")
+	default:
+		return nil
+	}
+}
+
+// newAgentStatusMessage creates a HookMessage for agent_status events
+func newAgentStatusMessage(status string) *HookMessage {
+	data, _ := json.Marshal(AgentStatusData{Status: status})
+	return &HookMessage{
+		Event: "agent_status",
+		Data:  data,
+	}
+}