Skip to content

A tiny friend in your Mac's notch and on your iPhone that keeps an eye on your AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, Antigravity and more. Approve from the notch or your Lock Screen.

202 KB
Raw Blame
import Foundation
import Darwin
import AppKit
import SwiftUI
import CryptoKit

// MARK: - HookServer
// Listens on a Unix domain socket for events from nb-hook (Claude Code hooks).
// Thread-safe: socket I/O on background threads, state updates dispatched to main queue.

final class HookServer: @unchecked Sendable {
    static let shared = HookServer()

    // Support directory paths
    static var supportDir: URL {
        FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
            .appendingPathComponent("NotchBuddy")
    }
    static var socketPath: String {
        #if APPSTORE
        // Container home root keeps path ≤ 103 bytes (sun_path limit on macOS is 104 incl. NUL)
        // /Users/louis/Library/Containers/fr.louisraille.Coucou/Data/nb.sock = 66 bytes ✓
        return NSHomeDirectory() + "/nb.sock"
        #else
        return supportDir.appendingPathComponent("nb.sock").path
        #endif
    }
    // hookScriptPath is only used by the non-App Store build.
    // App Store build derives the command from the panel-selected claudeURL in buildHooksData(claudeURL:).
    static var hookScriptPath: String { supportDir.appendingPathComponent("nb-hook").path }

    // No approval blocking state — notch is notification-only, user answers in VS Code

    private static let maxPayload = 1_048_576          // 1 MB — reject oversized messages
    private static let receiveTimeoutSeconds: Int = 5   // SO_RCVTIMEO on client sockets
    private static let maxConnections = 32              // concurrent connection ceiling

    private var serverFD: Int32 = -1
    private let connectionLock = NSLock()
    private var connectionCount = 0
    /// Permission requests waiting for a click, oldest first; the head is on the card.
    /// Each one holds its nb-hook connection open until it is answered or dropped.
    private var approvals = ApprovalQueue()
    /// One read source per queued request: it notices the client hanging up, and its
    /// cancel handler is the only place the request's fd is closed.
    private var approvalSources: [UUID: any DispatchSourceRead] = [:]
    /// AskUserQuestions waiting for an answer, oldest first, one per session; the head is on
    /// the card. Each one holds its nb-hook connection open until it is answered or dropped.
    private var questions = QuestionQueue()
    /// One read source per waiting question: it notices the client hanging up, and its
    /// cancel handler is the only place the question's fd is closed.
    private var questionSources: [UUID: any DispatchSourceRead] = [:]
    private var shownQuestion: UUID? = nil            // the question the card shows

    /// True when a real nb-hook connection is holding the approval fd open.
    @MainActor var hasRealPendingApproval: Bool { !approvals.isEmpty }
    /// True when a real nb-hook connection is holding a question fd open.
    @MainActor var hasRealPendingQuestion: Bool { !questions.isEmpty }
    private var focusBeforeQuestion: String? = nil    // saved focus to restore after question
    private var activeSessionId: String? = nil        // current Claude Code session
    private var focusBeforeApproval: String? = nil    // saved focus to restore after approval
    private var focusBeforeAlert: String? = nil       // saved focus while another pill's card shows
    private var alertPill: String? = nil              // the pill that took the focus for its alert
    private var sessions = PillSessionRegistry()      // live sessions behind each pill
    private var board = SessionBoard()                // what each of those sessions shows

    private init() {}

    // MARK: - Approval queue helpers

    /// Note shown when a request was answered outside Coucou.
    @MainActor
    private func handledNote(pill: String) -> String {
        switch PillCatalog.basePillId(pill) {
        case "agent_cursor":  return "Handled in Cursor."
        case "agent_codex":   return "Handled in Codex."
        case "agent_copilot": return "Handled in Copilot CLI."
        case "agent_muse":    return "Handled in Muse Code."
        case "agent_hermes":  return "Handled in Hermes."
        default:              return "Handled in \(claudeHostName(pill: pill))."
        }
    }

    /// Note shown when a request waited too long and went back to the agent.
    @MainActor
    private func waitingNote(pill: String) -> String {
        switch PillCatalog.basePillId(pill) {
        case "agent_cursor":  return "Still waiting in Cursor."
        case "agent_codex":   return "Still waiting in Codex."
        case "agent_copilot": return "Still waiting in Copilot CLI."
        case "agent_muse":    return "Still waiting in Muse Code."
        case "agent_hermes":  return "Still waiting in Hermes."
        default:              return "Still waiting in \(claudeHostName(pill: pill))."
        }
    }

    /// Puts the oldest waiting request on the card. When the card already shows it, only
    /// its "n waiting" count is refreshed (no sound, no focus change).
    @MainActor
    private func showApprovalHead() {
        let state = AppState.shared
        guard let head = approvals.head else { return }
        if let shown = state.pendingApproval, shown.id == head.id {
            if shown.queueCount != approvals.count { state.pendingApproval?.queueCount = approvals.count }
            return
        }
        syncPill(head.pillId)
        state.pendingApproval = ApprovalInfo(sessionId: head.sessionId, tool: head.tool,
                                              command: head.command, inputKey: head.inputKey,
                                              pillId: head.displayPill, id: head.id,
                                              queueCount: approvals.count,
                                              projectName: head.projectName)
        state.isPinned = true
        // Approval always forces the island open — the user must be able to respond.
        // Save the focus once, so it comes back when the last request is gone.
        if focusBeforeApproval == nil { focusBeforeApproval = state.focusId }
        withAnimation(.spring(response: 0.5, dampingFraction: 0.72)) { state.focusId = head.displayPill }
        expandIfNeeded(to: .approval)
    }

    /// Takes one request out of the queue. With `answer`, the decision is written to its
    /// nb-hook first; without, the connection just closes and the agent asks again itself.
    /// The cancel handler of its source closes the fd — never close it directly.
    /// The next request in line then takes the card; when none is left the card closes,
    /// with `note` for three seconds if one is given.
    @MainActor
    private func removeApproval(id: UUID, answer json: String? = nil, note: String? = nil) {
        guard let entry = approvals.remove(id: id) else { return }
        let age = Int(Date().timeIntervalSince(entry.received))
        nbLog("Approval \(entry.tool) closed after \(age) s: \(json.map { _ in "answered from Coucou" } ?? note ?? "dropped")")
        let source = approvalSources.removeValue(forKey: id)
        if let json {
            let fd = entry.fd
            Task.detached { [weak self] in
                // Write while the fd is still valid, then cancel → the cancel handler closes it.
                self?.sendLine(fd: fd, text: json)
                DispatchQueue.main.async { source?.cancel() }
            }
        } else {
            source?.cancel()
        }

        let state = AppState.shared
        // The session's pill leaves its approval state; a popped-out one folds back soon after.
        syncPill(entry.pillId)
        if !approvals.entries.contains(where: { $0.displayPill == entry.displayPill }) {
            clearPillBadge(id: entry.displayPill)
        }
        if approvals.head != nil {
            showApprovalHead()
            return
        }
        // Last request gone: close the card and give the focus back.
        state.pendingApproval = nil
        state.isPinned = false
        if let prev = focusBeforeApproval {
            focusBeforeApproval = nil
            if state.focusId == entry.displayPill, state.tasks.contains(where: { $0.id == prev }) {
                withAnimation(.spring(response: 0.5, dampingFraction: 0.72)) { state.focusId = prev }
            }
        }
        if questions.head != nil {
            showQuestionHead()
            return
        }
        if let note {
            state.noteMessage = note
            state.view = .note
            DispatchQueue.main.asyncAfter(deadline: .now() + 3) {
                NotificationCenter.default.post(name: .islandCollapse, object: nil)
            }
        } else {
            state.view = state.tasks.isEmpty ? .empty : .overview
        }
    }

    // MARK: - Sessions on the board

    /// A session's key on the board: its id, or for one that sends none its pill and folder
    /// (the same key the recap and the question queue use).
    private static func boardKey(_ session: String, pill: String, cwd: String) -> String {
        (session == "unknown" || session.isEmpty) ? "\(pill)+\(cwd)" : session
    }

    /// Records what an event says about a session of `pill` on the board.
    @MainActor
    private func record(pill: String, session key: String, raw: String, title: String,
                        _ change: (inout BoardSession) -> Void = { _ in }) {
        board.update(pill: pill, session: key, rawSession: raw, title: title, now: Date(), change)
    }

    /// The sessions of `pill` waiting for you, with what they wait for (a permission first).
    @MainActor
    private func waitingSessions(pill: String) -> [String: BotState] {
        var waiting: [String: BotState] = [:]
        for q in questions.entries where q.pillId == pill { waiting[q.sessionId] = .question }
        for a in approvals.entries where a.pillId == pill {
            waiting[Self.boardKey(a.sessionId, pill: pill, cwd: a.cwd)] = .approval
        }
        return waiting
    }

    /// A session that starts waiting while it shares `pill` with another pops out into a pill
    /// of its own. Returns that pill, nil when the session stays (it is alone in its pill).
    @MainActor
    private func popOutIfShared(pill: String, session key: String, raw: String, title: String) -> String? {
        record(pill: pill, session: key, raw: raw, title: title)
        let popped = board.popOut(pill: pill, session: key, now: Date())
        if let popped { nbLog("\(key.prefix(8)) waits: out of \(pill) into \(popped)") }
        return popped
    }

    /// Writes the board to `pill` and to the pills popped out of it: the session the pill
    /// shows (name, steps, state, last message, terminal), the list the open card shows when
    /// several share it, each popped-out session's own pill, and the folding back of those
    /// no longer waiting.
    @MainActor
    private func syncPill(_ pill: String) {
        let state = AppState.shared
        let now = Date()
        var gone = board.keep(pill: pill) { sessions.display(pill: pill, session: $0.rawSession) != nil }
        let waiting = waitingSessions(pill: pill)
        let (folded, recheck) = board.fold(pill: pill, waiting: Set(waiting.keys), now: now)
        gone += folded
        for id in gone where state.tasks.contains(where: { $0.id == id }) {
            if state.focusId == id { state.focusId = pill }
            withAnimation(.spring(response: 0.5, dampingFraction: 0.72)) { state.removeTask(id: id) }
        }
        if let recheck {
            DispatchQueue.main.asyncAfter(deadline: .now() + max(0.05, recheck.timeIntervalSince(now))) { [weak self] in
                self?.syncPill(pill)
            }
        }
        guard let client = state.tasks.first(where: { $0.id == pill }) else { return }
        for (session, popped) in board.poppedOut(pill: pill) {
            showPoppedOut(popped, of: client, session: session, waiting: waiting[session])
        }
        guard let index = state.tasks.firstIndex(where: { $0.id == pill }) else { return }
        guard let shown = board.shown(pill: pill, waiting: Set(waiting.keys), now: now),
              let session = board.session(pill: pill, session: shown) else {
            if !state.tasks[index].sessionLines.isEmpty { state.tasks[index].sessionLines = [] }
            return
        }
        write(session, waiting: waiting[shown], client: pill, to: index)
        let lines = board.lines(pill: pill).map { line in
            SessionLine(id: line.session, title: line.value.title,
                        state: waiting[line.session] ?? line.value.state,
                        lastStep: Self.readableStep(line.value.steps.last ?? ""),
                        isShown: line.session == shown)
        }
        if state.tasks[index].sessionLines != lines { state.tasks[index].sessionLines = lines }
    }

    /// Puts one session's state, steps, last message, title and terminal on the task at `index`.
    @MainActor
    private func write(_ session: BoardSession, waiting: BotState?, client: String, to index: Int) {
        let state = AppState.shared
        var task = state.tasks[index]
        task.state = waiting ?? session.state
        if task.steps != session.steps {
            task.steps = session.steps
            task.stepIndex = max(0, session.steps.count - 1)
        }
        task.finalLine = session.finalLine
        // A third-party agent's pill keeps the agent's name; Claude Code's and Codex's take the session's.
        if !session.title.isEmpty, task.isIntegration || task.pill == "agent_claude-desktop" || task.id != task.pill {
            task.name = session.title
        }
        if let display = sessions.display(pill: client, session: session.rawSession) {
            if !display.cwd.isEmpty { task.sessionCwd = display.cwd }
            if task.pill == "integration_claude" { task.hostApp = display.hostApp }
            if !display.bundleId.isEmpty { task.sessionBundleId = display.bundleId }
        }
        if state.tasks[index] != task { state.tasks[index] = task }
    }

    /// Creates or refreshes the pill a waiting session popped out into, right after its
    /// client's pills, in the client's color.
    @MainActor
    private func showPoppedOut(_ id: String, of client: AgentTask, session: String, waiting: BotState?) {
        guard let value = board.session(pill: client.id, session: session) else { return }
        let state = AppState.shared
        if !state.tasks.contains(where: { $0.id == id }) {
            var task = AgentTask(id: id, name: value.title, color: client.color, state: waiting ?? value.state,
                                 steps: [], source: client.source, isIntegration: client.isIntegration)
            task.hostApp = client.hostApp
            let at = (state.tasks.lastIndex(where: { $0.pill == client.pill }) ?? state.tasks.count - 1) + 1
            withAnimation(.spring(response: 0.5, dampingFraction: 0.72)) { state.tasks.insert(task, at: at) }
        }
        guard let index = state.tasks.firstIndex(where: { $0.id == id }) else { return }
        write(value, waiting: waiting, client: client.id, to: index)
    }

    /// A step as the open card lists it: a file edit reads "name +3 −1".
    private static func readableStep(_ step: String) -> String {
        guard let diff = step.parseDiffStep() else { return step }
        return "\(diff.filename) +\(diff.added) −\(diff.removed)"
    }

    // MARK: - Question queue helpers

    /// Puts the oldest waiting question on the card. When the card already shows it, only
    /// the list the card and the iPhone read is refreshed (no sound, no focus change).
    @MainActor
    private func showQuestionHead() {
        let state = AppState.shared
        state.waitingQuestions = questions.entries
        guard let head = questions.head else { return }
        let needsDisplay = shownQuestion != head.id || state.view != .question
        guard needsDisplay else { return }
        shownQuestion = head.id
        state.pendingQuestion = head.question
        state.isPinned = true
        if focusBeforeQuestion == nil { focusBeforeQuestion = state.focusId }
        withAnimation(.spring(response: 0.5, dampingFraction: 0.72)) { state.focusId = head.displayPill }
        expandIfNeeded(to: .question)
    }

    /// Takes one question out of the queue. With `answer`, the line is written to its nb-hook
    /// first; without, the connection just closes and the agent asks again itself. The cancel
    /// handler of its source closes the fd — never close it directly. The next question then
    /// takes the card; when none is left the card closes.
    @MainActor
    private func removeQuestion(id: UUID, answer json: String? = nil) {
        guard let entry = questions.remove(id: id) else { return }
        let source = questionSources.removeValue(forKey: id)
        if let json {
            let fd = entry.fd
            Task.detached { [weak self] in
                // Write while the fd is still valid, then cancel → the cancel handler closes it.
                self?.sendLine(fd: fd, text: json)
                DispatchQueue.main.async { source?.cancel() }
            }
        } else {
            source?.cancel()
        }

        let state = AppState.shared
        // The session's pill leaves its question state; a popped-out one folds back soon after.
        syncPill(entry.pillId)
        if !questions.entries.contains(where: { $0.displayPill == entry.displayPill })
            && !approvals.entries.contains(where: { $0.displayPill == entry.displayPill }) {
            clearPillBadge(id: entry.displayPill)
        }
        if questions.head != nil {
            showQuestionHead()
            return
        }
        state.waitingQuestions = []
        closeQuestionCard(pill: entry.displayPill)
    }

    /// No question left: close the card and give the focus back, or return to
    /// an approval waiting behind it (#851).
    @MainActor
    private func closeQuestionCard(pill: String?) {
        let state = AppState.shared
        shownQuestion = nil
        state.pendingQuestion = nil
        state.isPinned = false
        if let prev = focusBeforeQuestion {
            focusBeforeQuestion = nil
            if let pill, state.focusId == pill, state.tasks.contains(where: { $0.id == prev }) {
                withAnimation(.spring(response: 0.5, dampingFraction: 0.72)) { state.focusId = prev }
            }
        }
        if let head = approvals.head {
            state.pendingApproval = ApprovalInfo(sessionId: head.sessionId, tool: head.tool,
                                                  command: head.command, inputKey: head.inputKey,
                                                  pillId: head.displayPill, id: head.id,
                                                  queueCount: approvals.count,
                                                  projectName: head.projectName)
            state.isPinned = true
            withAnimation(.spring(response: 0.5, dampingFraction: 0.72)) { state.focusId = head.displayPill }
            expandIfNeeded(to: .approval)
            return
        }
        state.view = state.tasks.isEmpty ? .empty : .overview
    }

    /// The question `id` (the one the card or the iPhone showed), else the card's.
    /// nil when that question no longer waits.
    @MainActor
    private func waitingQuestion(_ id: UUID?) -> QueuedQuestion? {
        guard let id else { return questions.head }
        guard let entry = questions.entry(id: id) else {
            nbLog("Answer for a question no longer waiting, ignored")
            return nil
        }
        return entry
    }

    /// Called by QuestionView and the iPhone. Sends the answers to the session that asked
    /// question `id` (the card's when nil), then the next question takes the card.
    @MainActor
    func sendQuestionAnswers(_ answers: [String: Any], for id: UUID? = nil) {
        // Only intercept a demo question — real questions always have a live fd.
        if DemoEngine.shared.isActive, questions.isEmpty {
            AppState.shared.pendingQuestion = nil
            AppState.shared.isPinned = false
            AppState.shared.view = AppState.shared.tasks.isEmpty ? .empty : .overview
            DemoEngine.shared.handleQuestionAnswered(answers: answers)
            return
        }
        guard !questions.isEmpty else { closeQuestionCard(pill: nil); return }
        guard let entry = waitingQuestion(id) else { return }
        guard let data = try? JSONSerialization.data(withJSONObject: ["permissionDecision": "answer", "answers": answers], options: .withoutEscapingSlashes),
              let json = String(data: data, encoding: .utf8) else {
            removeQuestion(id: entry.id)
            return
        }
        RecapStore.shared.recordQuestionAnswered(sessionId: entry.sessionId)
        removeQuestion(id: entry.id, answer: json)
    }

    /// Called by QuestionView.onDisappear — the card left the screen without an answer.
    /// Every waiting question goes back to its terminal ("ask") at once, since none of them
    /// is on screen any more; does NOT navigate (view already changed).
    @MainActor
    func releaseQuestionFD() {
        guard !questions.isEmpty else { return }
        let state = AppState.shared
        let gone = questions.removeAll()
        for entry in gone {
            let source = questionSources.removeValue(forKey: entry.id)
            let fd = entry.fd
            Task.detached { [weak self] in
                self?.sendLine(fd: fd, text: #"{"permissionDecision":"ask"}"#)
                DispatchQueue.main.async { source?.cancel() }
            }
        }
        shownQuestion = nil
        focusBeforeQuestion = nil
        state.waitingQuestions = []
        state.pendingQuestion = nil
        for pill in Set(gone.map(\.pillId)) {
            syncPill(pill)
            clearPillBadge(id: pill)
        }
    }

    /// Called by QuestionView "Reply in terminal" button: question `id` (the card's when nil)
    /// goes back to its terminal.
    @MainActor
    func sendQuestionAsk(for id: UUID? = nil) {
        guard !questions.isEmpty else { closeQuestionCard(pill: nil); return }
        guard let entry = waitingQuestion(id) else { return }
        removeQuestion(id: entry.id, answer: #"{"permissionDecision":"ask"}"#)
    }

    /// Returns the tool_input serialized as sorted-keys JSON, "" if absent or empty.
    /// Same computation used in processPermissionRequest and processEvent to match PostToolUse.
    private static func approvalInputKey(_ input: [String: Any]) -> String {
        guard !input.isEmpty,
              let data = try? JSONSerialization.data(withJSONObject: input, options: .sortedKeys),
              let str = String(data: data, encoding: .utf8) else { return "" }
        return str
    }

    // MARK: - Start

    func start() {
        // Ensure support directory exists (mode 0700 — not world-readable)
        let dir = Self.supportDir
        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
        try? FileManager.default.setAttributes([.posixPermissions: 0o700 as NSNumber], ofItemAtPath: dir.path)
        #if !APPSTORE
        installHookScript()
        #endif
        Thread.detachNewThread { self.serverThread() }
    }

    // MARK: - Socket server (background thread)

    private func serverThread() {
        let path = Self.socketPath
        // sun_path on macOS is 104 bytes including the NUL terminator → max 103 usable bytes
        let maxSunPathBytes = MemoryLayout<sockaddr_un>.size - MemoryLayout<sa_family_t>.size - 1
        guard path.utf8.count <= maxSunPathBytes else {
            NSLog("HookServer: socket path too long (\(path.utf8.count) bytes, max \(maxSunPathBytes)): \(path)")
            return
        }
        try? FileManager.default.removeItem(atPath: path)

        let fd = socket(AF_UNIX, SOCK_STREAM, 0)
        guard fd >= 0 else { return }
        serverFD = fd

        var addr = sockaddr_un()
        addr.sun_family = sa_family_t(AF_UNIX)
        let cpath = Array(path.utf8CString)
        withUnsafeMutableBytes(of: &addr.sun_path) { raw in
            for (i, c) in cpath.enumerated() where i < raw.count { raw[i] = UInt8(bitPattern: c) }
        }

        let bindRC = withUnsafePointer(to: &addr) { ptr in
            ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { Darwin.bind(fd, $0, socklen_t(MemoryLayout<sockaddr_un>.size)) }
        }
        guard bindRC == 0 else { close(fd); return }
        // Restrict socket to owner only
        chmod(path, 0o600)
        guard Darwin.listen(fd, 32) == 0 else { close(fd); return }

        while true {
            let clientFD = Darwin.accept(fd, nil, nil)
            guard clientFD >= 0 else {
                // Never end the server on a failed accept (#853); pause unless it was transient.
                // A listening socket that is gone for good (closed, not a socket) ends the loop.
                let err = errno
                if err == EBADF || err == EINVAL || err == ENOTSOCK { break }
                if err != EINTR && err != ECONNABORTED { usleep(100_000) }
                continue
            }
            // Reject connections from other users (same-UID check)
            var euid: uid_t = 0
            var egid: gid_t = 0
            guard getpeereid(clientFD, &euid, &egid) == 0, euid == getuid() else {
                close(clientFD)
                continue
            }
            // Enforce concurrent connection ceiling
            connectionLock.lock()
            let count = connectionCount
            if count < Self.maxConnections { connectionCount += 1 }
            connectionLock.unlock()
            guard count < Self.maxConnections else {
                close(clientFD)
                continue
            }
            Thread.detachNewThread { self.handleClient(fd: clientFD) }
        }
    }

    // MARK: - Client handler (background thread)

    private func handleClient(fd: Int32) {
        defer {
            connectionLock.lock(); connectionCount -= 1; connectionLock.unlock()
        }
        // 5-second receive timeout — unresponsive clients don't hold threads forever
        var tv = timeval(tv_sec: Self.receiveTimeoutSeconds, tv_usec: 0)
        setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &tv, socklen_t(MemoryLayout<timeval>.size))

        // Read newline-delimited JSON
        var raw = Data()
        var buf = [UInt8](repeating: 0, count: 4096)
        outer: while true {
            let n = recv(fd, &buf, buf.count, 0)
            if n <= 0 { break }
            for i in 0..<n {
                if buf[i] == UInt8(ascii: "\n") { break outer }
                raw.append(buf[i])
            }
            if raw.count > Self.maxPayload { break }
        }

        guard !raw.isEmpty,
              let payload = try? JSONSerialization.jsonObject(with: raw) as? [String: Any] else {
            sendLine(fd: fd, text: #"{"ok":true}"#)
            close(fd)
            return
        }

        let coucouKind = payload["coucou_kind"] as? String ?? ""

        // statusline payloads are handled separately — no session, no reveal, no sound
        if coucouKind == "statusline" {
            Task { @MainActor in self.processStatusLine(payload: payload) }
            sendLine(fd: fd, text: #"{"ok":true}"#)
            close(fd)
            return
        }

        // AskUserQuestion via --ask PreToolUse hook — hold fd open like PermissionRequest
        if coucouKind == "ask_user_question" {
            let toolInput = payload["tool_input"] as? [String: Any] ?? [:]
            if let parsed = AskQuestion.parse(toolInput: toolInput) {
                Task { @MainActor in self.processQuestionRequest(fd: fd, parsed: parsed, payload: payload) }
            } else {
                // Malformed payload — fall back: send ask so Claude Code re-asks in terminal
                sendLine(fd: fd, text: #"{"permissionDecision":"ask"}"#)
                close(fd)
            }
            return
        }

        let eventName = payload["hook_event_name"] as? String ?? ""

        if eventName == "PermissionRequest" {
            // Hold fd open — Claude Code waits for our decision (up to 120s)
            Task { @MainActor in self.processPermissionRequest(fd: fd, payload: payload) }
        } else {
            Task { @MainActor in self.processEvent(name: eventName, payload: payload) }
            sendLine(fd: fd, text: #"{"ok":true}"#)
            close(fd)
        }
    }


    // MARK: - Event → AppState
    // Claude Code events route to the permanent "integration_claude" task.
    // Events tagged with a valid coucou_agent route to a dynamic "integration_<agent>" task.
    // View switches only happen if VS Code (or the agent pill) is currently focused.
    // When not focused: state updates animate the mini bot in the pill; badge shown for alerts.

    @MainActor
    private func processEvent(name: String, payload: [String: Any]) {
        let state = AppState.shared
        let sessionId = payload["session_id"] as? String
                     ?? payload["conversation_id"] as? String
                     ?? "unknown"
        let cwd = payload["cwd"] as? String ?? ""
        let projectName = sessionName(payload, cwd: cwd)

        // Determine which pill this event belongs to.
        // coucou_agent must be lowercase, digits and hyphens, ≤ 24 chars.
        let rawAgent = payload["coucou_agent"] as? String ?? ""
        let validAgent = Self.validateAgent(rawAgent)

        let termProgram = payload["term_program"] as? String ?? ""
        let bundleId    = payload["bundle_id"]    as? String ?? ""

        // Cursor identified solely by its stable Electron bundle ID.
        // ToDesktop builds other apps too — do not match on "todesktop" alone.
        let isCursorEditor = bundleId.lowercased() == "com.todesktop.230313mzl4w4u92"
        let isVSCodeEditor = !isCursorEditor && (
            termProgram.lowercased().contains("vscode") ||
            bundleId.lowercased().contains("vscode"))

        // Routing:
        // • "codex" → agent_codex (GitHub build only: workspace pill, approvals in the notch)
        // • other valid coucou_agent → external pill (fire-and-forget, no approval card)
        // • Cursor bundle ID → agent_cursor
        // • VS Code → integration_claude
        // • a known terminal (Warp, Terminal, iTerm…) → integration_claude, host recorded on the task
        #if !APPSTORE
        let isCodexEvent = rawAgent == "codex"
        #else
        let isCodexEvent = false
        #endif
        let agentId: String
        let isExternalAgent: Bool
        var hostApp: String? = nil
        if isCodexEvent {
            agentId = "agent_codex"
            isExternalAgent = false
        } else if let agent = validAgent {
            agentId = "agent_\(agent)"
            isExternalAgent = true
        } else if isCursorEditor {
            agentId = "agent_cursor"
            isExternalAgent = false
        } else if isVSCodeEditor {
            agentId = "integration_claude"
            isExternalAgent = false
        } else if let host = ClaudeHost.terminal(termProgram: termProgram, bundleId: bundleId) {
            agentId = "integration_claude"
            isExternalAgent = false
            hostApp = host.bundleId
        } else {
            nbLog("Ignored \(name) from \(termProgram.isEmpty ? bundleId : termProgram) (\(projectName))")
            return
        }

        // The user is looking at the session's terminal: a finish or an error is already in
        // front of them, so the pill only takes a badge (no sound, no reveal). Warp exposes
        // no active tab, so a sibling session in another tab of the same terminal is quiet too.
        let terminalInFront = hostApp != nil
            && NSWorkspace.shared.frontmostApplication?.bundleIdentifier == hostApp
        // Several sessions can share one pill (it is chosen from the client, not from the
        // session). The registry tells a turn-ending event whether it may touch the pill,
        // and which session owns the project name shown on it.
        let display = PillSessionRegistry.Display(
            session: sessionId,
            projectName: isExternalAgent ? (validAgent ?? projectName) : projectName,
            cwd: isExternalAgent ? "" : cwd,
            hostApp: hostApp, bundleId: bundleId)
        // For sessions that carry no id, derive a unique key from pill + cwd so that
        // concurrent anonymous sessions are tracked independently in RecapStore.
        let recapSessionId = (sessionId == "unknown" || sessionId.isEmpty)
            ? "\(agentId)+\(cwd)"
            : sessionId

        #if PHONE_LINK
        // The iPhone's "last turn" (prompt, actions, diffs, answer).
        if !isExternalAgent { TurnRecorder.shared.record(event: name, payload: payload, pillId: agentId) }
        #endif

        // Waiting permission requests: an event that settles one (its tool finished, or its
        // turn ended) takes it off the card, then is processed normally.
        if !approvals.isEmpty {
            let eventTool = payload["tool_name"] as? String ?? ""
            let eventKey = Self.approvalInputKey(payload["tool_input"] as? [String: Any] ?? [:])
            for entry in approvals.resolved(byEvent: name, sessionId: sessionId, pillId: agentId,
                                            tool: eventTool, inputKey: eventKey) {
                removeApproval(id: entry.id, note: handledNote(pill: entry.displayPill))
            }
            // A session still waiting on a decision is held back (its parallel tool calls
            // would pull the pill out of its approval state). Other sessions go through.
            if approvals.entries.contains(where: { $0.pillId == agentId && $0.sessionId == sessionId }) {
                return
            }
        }
        // What the event says goes to its session on the board, and the pill shows the board:
        // the session it shows, its steps and state; a session waiting for you keeps that state.
        let key = recapSessionId
        let now = Date()
        func note(_ change: (inout BoardSession) -> Void = { _ in }) {
            record(pill: agentId, session: key, raw: sessionId, title: projectName, change)
        }
        func step(_ text: String) { note { $0.appendStep(text) } }
        defer { syncPill(agentId) }

        switch name {

        case "SessionStart":
            activeSessionId = sessionId
            upsertTask(pill: agentId, display: display, working: false,
                       externalAgent: isExternalAgent ? validAgent : nil)
            note { $0.finalLine = nil }
            nbLog("SessionStart \(isExternalAgent ? agentId : projectName) (\(sessionId.prefix(8)))")
            NotificationCenter.default.post(name: .checkMondayRecap, object: nil)
            if state.isPresent { expandIfNeeded(to: .overview) }
            SoundEngine.shared.play("work")
            if agentId == "agent_hermes", let platform = payload["platform"] as? String,
               !platform.isEmpty, platform != "cli" {
                let capitalized = platform.prefix(1).uppercased() + platform.dropFirst()
                step(String(capitalized))
            }

        case "UserPromptSubmit":
            activeSessionId = sessionId
            upsertTask(pill: agentId, display: display, working: true,
                       externalAgent: isExternalAgent ? validAgent : nil)
            note {
                $0.state = .thinking
                $0.finalLine = nil
                $0.endedAt = nil
                if let prompt = payload["prompt"] as? String, !prompt.isEmpty { $0.appendStep(String(prompt.prefix(60))) }
            }
            RecapStore.shared.userPromptSubmit(sessionId: recapSessionId, pillId: agentId, project: projectName)
            NotificationCenter.default.post(name: .checkMondayRecap, object: nil)
            if state.isPresent { expandIfNeeded(to: .overview) }

        case "PreToolUse":
            activeSessionId = sessionId
            let tool = payload["tool_name"] as? String ?? "Tool"
            note { $0.finalLine = nil }
            RecapStore.shared.preToolUse(sessionId: recapSessionId, tool: tool)
            // AskUserQuestion is handled via the dedicated --ask hook.
            // Skip state/step update here to avoid flickering over the question card.
            guard tool != "AskUserQuestion" else { break }
            upsertTask(pill: agentId, display: display, working: true,
                       externalAgent: isExternalAgent ? validAgent : nil)
            let isQuestion = tool == "ask_question" || tool.hasSuffix(":ask_question")
            let input = payload["tool_input"] as? [String: Any] ?? [:]
            let label = localizedStep(tool: tool, input: input)
            note {
                $0.state = isQuestion ? .question : .working
                $0.endedAt = nil
                $0.appendStep(label)
            }
            if isQuestion {
                SoundEngine.shared.play("question")
                if state.isPresent { expandIfNeeded(to: .overview) }
            }
            nbLog("PreToolUse \(tool)")

        case "PostToolUse":
            sessions.note(pill: agentId, display: display, working: true)
            note { $0.state = .working }
            // Live diff for Edit / MultiEdit / Write
            let diffTool = payload["tool_name"] as? String ?? ""
            let diffInput = payload["tool_input"] as? [String: Any] ?? [:]
            if let diff = buildFileDiff(tool: diffTool, input: diffInput, pillId: agentId) {
                let idx = state.appendSessionDiff(diff, for: agentId)
                step(String.makeDiffStep(filename: diff.name, added: diff.added, removed: diff.removed, diffId: idx))
                RecapStore.shared.recordFileDiff(sessionId: recapSessionId, path: diff.name, added: diff.added, removed: diff.removed)
            }

        case "PostToolUseFailure":
            sessions.note(pill: agentId, display: display, working: true)
            note {
                $0.state = .working
                $0.appendStep("⚠ failed")
            }

        case "Notification":
            sessions.note(pill: agentId, display: display, working: false)
            let message = payload["message"] as? String ?? ""
            let lower = message.lowercased()
            if lower.contains("rate limit") || lower.contains("limite d") {
                note { $0.state = .ratelimit }
                SoundEngine.shared.play("rate")
            } else if message.hasSuffix("?") {
                note {
                    $0.state = .question
                    $0.appendStep(message)
                }
            }

        case "Stop":
            // Each session finishes on its own: its sound, its "finished", its last message,
            // even while a sibling behind the same pill is still working. For a moment the pill
            // shows the session that finished (SessionBoard.finishMoment), then the busy one again.
            _ = sessions.endTurn(pill: agentId, session: sessionId)
            let rawFinal = (payload["last_assistant_message"] as? String)
                ?? (payload["message"] as? String) ?? ""
            let finalText = DiffEngine.toOneLine(rawFinal)
            note {
                $0.state = .finished
                $0.endedAt = now
                if !finalText.isEmpty {
                    $0.finalLine = finalText
                    $0.appendStep(finalText)
                }
            }
            RecapStore.shared.stop(sessionId: recapSessionId)
            let working = sessions.workingCount(pill: agentId)
            if working > 0 { nbLog("Stop \(sessionId.prefix(8)) — \(working) other session(s) still working on \(agentId)") }
            syncPill(agentId)
            let finished = board.poppedPill(pill: agentId, session: key) ?? agentId
            if !terminalInFront { SoundEngine.shared.play("finish") }
            if !terminalInFront && showsAlert(for: finished, focused: state.focusId == finished) {
                expandIfNeeded(to: .finished)
            } else {
                setPillBadge(id: finished, badge: .finished)
            }
            DispatchQueue.main.asyncAfter(deadline: .now() + SessionBoard.finishMoment) {
                // The session (or a sibling) may have started a new turn meanwhile.
                self.board.amend(pill: agentId, session: key) { if $0.state == .finished && $0.endedAt == now { $0.state = .idle } }
                self.syncPill(agentId)
                guard self.sessions.workingCount(pill: agentId) == 0 else { return }
                if isExternalAgent {
                    AppState.shared.removeTask(id: agentId)
                } else {
                    self.clearPillBadge(id: agentId)
                }
            }

        case "StopFailure":
            RecapStore.shared.stop(sessionId: recapSessionId)
            _ = sessions.endTurn(pill: agentId, session: sessionId)
            nbLog("StopFailure \(sessionId.prefix(8)) — \(payload.keys.sorted().joined(separator: ", ")): \(Self.stopFailureDetail(payload) ?? "no detail")")
            // The error view shows what went wrong (finalLine), not the last thing said before it.
            note {
                $0.state = .error
                $0.endedAt = now
                $0.finalLine = Self.stopFailureDetail(payload)
            }
            syncPill(agentId)
            let failed = board.poppedPill(pill: agentId, session: key) ?? agentId
            if !terminalInFront { SoundEngine.shared.play("error") }
            if !terminalInFront && showsAlert(for: failed, focused: state.focusId == failed) {
                expandIfNeeded(to: .error)
            } else {
                setPillBadge(id: failed, badge: .error)
            }
            // After the error moment a sibling's work takes the pill again.
            DispatchQueue.main.asyncAfter(deadline: .now() + SessionBoard.errorMoment + 0.1) { self.syncPill(agentId) }

        case "Interrupt":
            // Codex: user stopped the turn
            RecapStore.shared.stop(sessionId: recapSessionId)
            let interruptScope = sessions.endTurn(pill: agentId, session: sessionId)
            note { $0.state = .idle }
            guard interruptScope == .pill else { break }
            activeSessionId = nil
            clearPillBadge(id: agentId)

        case "SessionEnd":
            // A popped-out session that ends takes its own pill down; the client's pill goes
            // only with the last session behind it.
            if let popped = board.remove(pill: agentId, session: key),
               state.tasks.contains(where: { $0.id == popped }) {
                if state.focusId == popped { state.focusId = agentId }
                withAnimation(.spring(response: 0.5, dampingFraction: 0.72)) { state.removeTask(id: popped) }
            }
            guard sessions.endSession(pill: agentId, session: sessionId) == .pill else {
                RecapStore.shared.sessionEnd(sessionId: recapSessionId)
                nbLog("SessionEnd \(sessionId.prefix(8)) — \(sessions.liveCount(pill: agentId)) session(s) left on \(agentId)")
                break
            }
            activeSessionId = nil
            if let idx = state.tasks.firstIndex(where: { $0.id == agentId }) { state.tasks[idx].finalLine = nil }
            state.clearSessionDiffs(for: agentId)
            state.removeTask(id: agentId)
            RecapStore.shared.sessionEnd(sessionId: recapSessionId)

        case "SubagentStart":
            step("+ subagent")

        case "SubagentStop":
            step("• subagent done")

        default:
            break
        }
    }

    // MARK: - Agent validation + dynamic pill

    /// Validates a coucou_agent name: lowercase, digits and hyphens, 1–24 chars.
    /// "claude" is reserved and rejected so it cannot impersonate the Claude Code pill.
    /// Returns the name unchanged if valid, nil otherwise.
    private static func validateAgent(_ raw: String) -> String? {
        guard !raw.isEmpty, raw.count <= 24, raw != "claude" else { return nil }
        for scalar in raw.unicodeScalars {
            let v = scalar.value
            let ok = (v >= 0x61 && v <= 0x7A)  // a-z
                  || (v >= 0x30 && v <= 0x39)   // 0-9
                  || v == 0x2D                   // -
            guard ok else { return nil }
        }
        return raw
    }

    /// Creates a dynamic pill for a third-party agent on first event, then no-ops.
    /// ID format: "agent_<name>" — never collides with "integration_*" pills.
    /// Inserted right after integration_claude so it appears in the visible prefix(4).
    @MainActor
    private func upsertExternalAgent(id: String, name: String) {
        let state = AppState.shared
        guard state.tasks.firstIndex(where: { $0.id == id }) == nil else { return }
        let color: String
        if let def = PillCatalog.definition(for: id) {
            color = def.color
        } else {
            color = IslandConst.colorForProject(name)
        }
        let task = AgentTask(id: id, name: name, color: color, state: .idle, steps: [], source: .agent)
        if let claudeIdx = state.tasks.firstIndex(where: { $0.id == "integration_claude" }) {
            state.tasks.insert(task, at: claudeIdx + 1)
        } else {
            state.tasks.append(task)
        }
        if state.focusId == nil { state.focusId = id }
        state.syncMode()
    }

    // MARK: - Helpers

    /// Whether a finish or an error opens the island. The pill shown always does; another pill
    /// does too with "Show alerts from every pill" (#683): it takes the focus for its card, and
    /// the pill that was shown comes back when the island closes. Never over an approval, a
    /// question, or a card the user is busy in (chat, mail, settings…).
    @MainActor
    private func showsAlert(for pill: String, focused: Bool) -> Bool {
        if focused { return true }
        let state = AppState.shared
        guard state.alertsFromAllPills, state.pendingApproval == nil, state.pendingQuestion == nil else { return false }
        if state.mode == .expanded, ![IslandView.overview, .finished, .error, .empty].contains(state.view) { return false }
        if focusBeforeAlert == nil { focusBeforeAlert = state.focusId }
        alertPill = pill
        withAnimation(.spring(response: 0.5, dampingFraction: 0.72)) { state.focusId = pill }
        return true
    }

    /// The island closed: the pill that was shown before another pill's alert comes back.
    @MainActor
    func restoreAlertFocus() {
        guard let prev = focusBeforeAlert else { return }
        let borrowed = alertPill
        focusBeforeAlert = nil
        alertPill = nil
        let state = AppState.shared
        // Only if the alert's pill is still the one shown (the user may have picked another).
        guard state.pendingApproval == nil, state.focusId == borrowed, borrowed != prev,
              state.tasks.contains(where: { $0.id == prev }) else { return }
        withAnimation(.spring(response: 0.5, dampingFraction: 0.72)) { state.focusId = prev }
    }

    @MainActor
    private func expandIfNeeded(to view: IslandView) {
        let state = AppState.shared
        let isAlert: Bool
        switch view {
        case .approval, .question, .finished, .error, .confused: isAlert = true
        default: isAlert = false
        }
        if state.mode == .expanded {
            // Approval and question always win; other alerts are blocked while a card is showing
            if view == .approval || view == .question {
                state.view = view
            } else if isAlert && state.pendingApproval == nil {
                state.view = view
            }
        } else if isAlert {
            // Alerts always force-expand
            NotificationCenter.default.post(name: .hookExpand, object: view)
        } else if state.mode == .hidden {
            // Non-alert work events: reveal compact only, never force-expand
            NotificationCenter.default.post(name: .hookReveal, object: nil)
        }
        // Already compact and non-alert: Mochi state update is enough, no expand
    }

    // MARK: - Status line (plan gauge)

    @MainActor
    private func processStatusLine(payload: [String: Any]) {
        guard let usage = ClaudePlanGauge.parse(payload: payload) else { return }
        // Claude Code calls the status line several times a second: publish (and save to
        // UserDefaults) only when the numbers change, or every 30 s for "updated … ago".
        if let cur = AppState.shared.claudePlanUsage,
           cur.fiveHour == usage.fiveHour, cur.sevenDay == usage.sevenDay,
           usage.updatedAt.timeIntervalSince(cur.updatedAt) < 30 { return }
        AppState.shared.claudePlanUsage = usage
    }

    // MARK: - Permission request (blocking — Claude Code waits for decision)

    @MainActor
    private func processPermissionRequest(fd: Int32, payload: [String: Any]) {
        let state = AppState.shared
        let sessionId = payload["session_id"] as? String
                     ?? payload["conversation_id"] as? String
                     ?? "unknown"
        let cwd       = payload["cwd"]        as? String ?? ""
        let projectName = sessionName(payload, cwd: cwd)

        let rawAgent = payload["coucou_agent"] as? String ?? ""
        let termProgram = payload["term_program"] as? String ?? ""
        let bundleId    = payload["bundle_id"]    as? String ?? ""
        let isCursorEditor = bundleId.lowercased() == "com.todesktop.230313mzl4w4u92"
        let isVSCodeEditor = !isCursorEditor && (
            termProgram.lowercased().contains("vscode") ||
            bundleId.lowercased().contains("vscode"))

        // Codex, Copilot CLI and Muse Code get the same approval card as Claude Code / Cursor.
        // Other external agents (any other coucou_agent) answer immediately with "ask"
        // so the agent re-asks in its own terminal — they do not get a notch card.
        #if !APPSTORE
        let isCodexRequest   = rawAgent == "codex"
        let isCopilotRequest = rawAgent == "copilot"
        let isMuseRequest    = rawAgent == "muse"
        // isHermesRequest is true only when the plugin sent coucou_has_transport: true,
        // meaning register_approval_transport is wired and Hermes will honour our choice.
        // Without that flag the request falls through to "ask" so Hermes handles it natively.
        let isHermesRequest  = rawAgent == "hermes"
            && UserDefaults.standard.bool(forKey: "hermesApprovalsEnabled")
            && (payload["coucou_has_transport"] as? Bool == true)
        #else
        let isCodexRequest   = false
        let isCopilotRequest = false
        let isMuseRequest    = false
        let isHermesRequest  = false
        #endif
        if !isCodexRequest && !isCopilotRequest && !isMuseRequest && !isHermesRequest && Self.validateAgent(rawAgent) != nil {
            Task.detached { [weak self] in
                self?.sendLine(fd: fd, text: #"{"permissionDecision":"ask"}"#)
                close(fd)
            }
            return
        }

        // Determine which workspace pill owns the request.
        let pillId: String
        if isCodexRequest {
            pillId = "agent_codex"
        } else if isCopilotRequest {
            pillId = "agent_copilot"
        } else if isMuseRequest {
            pillId = "agent_muse"
        } else if isHermesRequest {
            pillId = "agent_hermes"
        } else if isCursorEditor {
            pillId = "agent_cursor"
        } else {
            pillId = "integration_claude"
        }
        // Terminal sessions: only when turned on in Settings, else the terminal asks itself.
        let terminalHost = isCursorEditor || isVSCodeEditor ? nil
            : ClaudeHost.terminal(termProgram: termProgram, bundleId: bundleId)
        let isTerminal = terminalHost != nil && ClaudeHost.terminalCardsEnabled
        guard isCodexRequest || isCopilotRequest || isMuseRequest || isHermesRequest || isCursorEditor || isVSCodeEditor || isTerminal else {
            Task.detached { [weak self] in
                self?.sendLine(fd: fd, text: #"{"permissionDecision":"ask"}"#)
                close(fd)
            }
            return
        }

        let tool = payload["tool_name"] as? String ?? "Tool"
        let toolInput = payload["tool_input"] as? [String: Any] ?? [:]
        let inputKey = Self.approvalInputKey(toolInput)
        nbLog("PermissionRequest \(tool) [\(pillId)]")

        // AskUserQuestion is now handled via the dedicated --ask PreToolUse hook.
        // If it still arrives here as a PermissionRequest, reply "ask" so Claude Code
        // re-asks in the terminal — never show the question twice.
        if tool == "AskUserQuestion" {
            Task.detached { [weak self] in
                self?.sendLine(fd: fd, text: #"{"permissionDecision":"ask"}"#)
                close(fd)
            }
            return
        }

        // A plan is too long for the card: show its title.
        let command = tool == "ExitPlanMode"
            ? Self.planTitle(toolInput["plan"] as? String)
            : toolInput["command"] as? String ?? tool

        // Several requests can wait at once (several sessions or agents): they queue, the
        // card shows the oldest. Past the cap, the newest goes back to its own terminal.
        // A session that shares its pill with another pops out into a pill of its own while
        // it waits (SessionBoard), so the request shows under its own title.
        var entry = QueuedApproval(id: UUID(), fd: fd, sessionId: sessionId, pillId: pillId,
                                   projectName: projectName, cwd: cwd, tool: tool,
                                   command: command, inputKey: inputKey,
                                   hostApp: terminalHost?.bundleId, bundleId: bundleId)
        if approvals.count < ApprovalQueue.maxPending {
            entry.shownPill = popOutIfShared(pill: pillId, session: Self.boardKey(sessionId, pill: pillId, cwd: cwd),
                                             raw: sessionId, title: projectName)
        }
        guard approvals.enqueue(entry) == .accepted else {
            nbLog("PermissionRequest \(tool): \(ApprovalQueue.maxPending) already waiting, asked in the terminal")
            Task.detached { [weak self] in
                self?.sendLine(fd: fd, text: #"{"permissionDecision":"ask"}"#)
                close(fd)
            }
            return
        }
        activeSessionId = sessionId

        upsertTask(pill: pillId,
                   display: PillSessionRegistry.Display(session: sessionId, projectName: projectName,
                                                        cwd: cwd, hostApp: terminalHost?.bundleId,
                                                        bundleId: bundleId),
                   working: true, externalAgent: nil)
        syncPill(pillId)
        SoundEngine.shared.play("approval")

        // Monitor fd: if the agent closes the connection (answered in its own UI), drop the
        // request. The cancel handler closes the fd — never close it anywhere else.
        let entryId = entry.id
        let capturedPillId = entry.displayPill
        let source = DispatchSource.makeReadSource(fileDescriptor: fd, queue: .main)
        source.setEventHandler { [weak self] in
            guard let self, self.approvals.contains(id: entryId) else { return }
            self.removeApproval(id: entryId, note: self.handledNote(pill: capturedPillId))
        }
        source.setCancelHandler { close(fd) }
        source.resume()
        approvalSources[entryId] = source

        // Safety timeout — drop without a decision. nb-hook reads EOF from the cancel
        // handler's close and exits; the agent asks again itself.
        // Copilot/Muse use 110s (their relay waits 118s but their hook timeout is 120s, leaving little margin).
        let waitTimeout: Double = (isCopilotRequest || isMuseRequest) ? 110 : 115
        DispatchQueue.main.asyncAfter(deadline: .now() + waitTimeout) { [weak self] in
            guard let self, self.approvals.contains(id: entryId) else { return }
            self.removeApproval(id: entryId, note: self.waitingNote(pill: capturedPillId))
        }

        showApprovalHead()
    }

    /// Called by ApprovalView buttons and the iPhone. Writes the decision to the waiting
    /// nb-hook of request `id` — the one that was on screen. A click that lands after the
    /// card moved on to another request is ignored, so it can never answer the wrong one.
    @MainActor
    func sendApprovalDecision(_ decision: String, for id: UUID? = nil) {
        // Only intercept a demo card — a real card has a queued request behind it.
        if DemoEngine.shared.isActive,
           AppState.shared.pendingApproval?.sessionId == "demo_session",
           approvals.isEmpty {
            let s = AppState.shared
            s.pendingApproval = nil
            s.isPinned = false
            s.view = s.tasks.isEmpty ? .empty : .overview
            DemoEngine.shared.handleApprovalDecision(decision)
            return
        }
        guard let head = approvals.head else {
            // A card with nothing behind it any more: just close it.
            let s = AppState.shared
            s.pendingApproval = nil
            s.isPinned = false
            s.view = s.tasks.isEmpty ? .empty : .overview
            return
        }
        if let id, id != head.id {
            nbLog("Approval decision for a request no longer on the card, ignored")
            return
        }

        let json: String
        switch decision {
        case "allow":  json = #"{"permissionDecision":"allow"}"#
        case "always": json = #"{"permissionDecision":"always"}"#
        case "ask":    json = #"{"permissionDecision":"ask"}"#
        // Plan approval (ExitPlanMode): the hook turns "mode" into a setMode permission update.
        case "plan_auto":    json = #"{"permissionDecision":"allow","mode":"auto"}"#
        case "plan_default": json = #"{"permissionDecision":"allow","mode":"default"}"#
        // Reject the plan and stop Claude, so the change can be typed in the terminal.
        case "plan_change":  json = #"{"permissionDecision":"change_plan"}"#
        default:       json = #"{"permissionDecision":"deny"}"#
        }
        // The recap only counts allow / always / deny.
        let recapDecision = ["plan_auto": "allow", "plan_default": "allow", "plan_change": "deny"][decision] ?? decision
        RecapStore.shared.recordDecision(pillId: head.pillId, decision: recapDecision)
        removeApproval(id: head.id, answer: json)
        if decision == "plan_change" { ClaudeHost.activate(head.hostApp) }
    }

    /// The plan's first non-empty line without its Markdown heading marks, for the card.
    static func planTitle(_ plan: String?) -> String {
        let firstLine = plan?.split(separator: "\n")
            .first { !$0.trimmingCharacters(in: .whitespaces).isEmpty }
        let title = firstLine.map { String($0.drop { $0 == "#" || $0 == " " }) } ?? ""
        return title.isEmpty ? "Plan" : title
    }

    // MARK: - Question request

    @MainActor
    private func processQuestionRequest(fd: Int32, parsed: AskQuestion, payload: [String: Any]) {
        let state = AppState.shared
        let sessionId = payload["session_id"] as? String
                     ?? payload["conversation_id"] as? String
                     ?? "unknown"
        let cwd       = payload["cwd"]        as? String ?? ""
        let projectName = sessionName(payload, cwd: cwd)

        let rawAgent    = payload["coucou_agent"] as? String ?? ""
        let termProgram = payload["term_program"]  as? String ?? ""
        let bundleId    = payload["bundle_id"]     as? String ?? ""
        let isCursorEditor = bundleId.lowercased() == "com.todesktop.230313mzl4w4u92"
        let isVSCodeEditor = !isCursorEditor && (
            termProgram.lowercased().contains("vscode") ||
            bundleId.lowercased().contains("vscode"))
        #if !APPSTORE
        let isCodexRequest = rawAgent == "codex"
        #else
        let isCodexRequest = false
        #endif
        let pillId: String
        if isCodexRequest {
            pillId = "agent_codex"
        } else if isCursorEditor {
            pillId = "agent_cursor"
        } else {
            pillId = "integration_claude"
        }
        // Terminal sessions: only when turned on in Settings, else the terminal asks itself.
        let terminalHost = isCursorEditor || isVSCodeEditor ? nil
            : ClaudeHost.terminal(termProgram: termProgram, bundleId: bundleId)
        let isTerminal = terminalHost != nil && ClaudeHost.terminalCardsEnabled
        guard isCodexRequest || isCursorEditor || isVSCodeEditor || isTerminal else {
            Task.detached { [weak self] in
                self?.sendLine(fd: fd, text: #"{"permissionDecision":"ask"}"#)
                close(fd)
            }
            return
        }

        // Several sessions can wait on a question at once: they queue, the card shows the
        // oldest, and each answer goes back to the session that asked. A session asking again
        // replaces its own older question; past the cap, the newest goes back to its terminal.
        // A session that shares its pill with another pops out into a pill of its own while
        // it waits (SessionBoard), so the question shows under its own title.
        let key = Self.boardKey(sessionId, pill: pillId, cwd: cwd)
        var entry = QueuedQuestion(id: UUID(), fd: fd, sessionId: key,
                                   pillId: pillId, projectName: projectName, cwd: cwd, question: parsed)
        if questions.count < QuestionQueue.maxPending
            || questions.entries.contains(where: { $0.sessionId == key && $0.pillId == pillId }) {
            entry.shownPill = popOutIfShared(pill: pillId, session: key, raw: sessionId, title: projectName)
        }
        switch questions.enqueue(entry) {
        case .rejectedFull:
            nbLog("Question: \(QuestionQueue.maxPending) already waiting, asked in the terminal")
            Task.detached { [weak self] in
                self?.sendLine(fd: fd, text: #"{"permissionDecision":"ask"}"#)
                close(fd)
            }
            return
        case .accepted(let replaced?):
            let oldSource = questionSources.removeValue(forKey: replaced.id)
            let oldFD = replaced.fd
            Task.detached { [weak self] in
                self?.sendLine(fd: oldFD, text: #"{"permissionDecision":"ask"}"#)
                DispatchQueue.main.async { oldSource?.cancel() }
            }
        case .accepted(nil):
            break
        }
        activeSessionId = sessionId

        upsertTask(pill: pillId,
                   display: PillSessionRegistry.Display(session: sessionId, projectName: projectName,
                                                        cwd: cwd, hostApp: terminalHost?.bundleId,
                                                        bundleId: bundleId),
                   working: true, externalAgent: nil)
        syncPill(pillId)
        SoundEngine.shared.play("approval")

        // Monitor fd: if the agent closes the connection (stopped or answered in its own UI),
        // drop the question. The cancel handler closes the fd — never close it anywhere else.
        let entryId = entry.id
        let source = DispatchSource.makeReadSource(fileDescriptor: fd, queue: .main)
        source.setEventHandler { [weak self] in
            guard let self, self.questions.contains(id: entryId) else { return }
            self.removeQuestion(id: entryId)
        }
        source.setCancelHandler { close(fd) }
        source.resume()
        questionSources[entryId] = source

        DispatchQueue.main.asyncAfter(deadline: .now() + 120) { [weak self] in
            guard let self, self.questions.contains(id: entryId) else { return }
            // Send "ask" so nb-hook exits cleanly; Claude Code re-asks in terminal.
            self.removeQuestion(id: entryId, answer: #"{"permissionDecision":"ask"}"#)
        }

        showQuestionHead()
    }

    /// "VS Code", "Warp"… — where the session behind a Claude Code pill runs.
    @MainActor
    private func claudeHostName(pill: String) -> String {
        ClaudeHost.name(for: AppState.shared.tasks.first { $0.id == pill }?.hostApp)
    }

    /// Records the session an event came from, then refreshes its card.
    /// `externalAgent` is the validated `coucou_agent` name for a third-party agent pill,
    /// nil for a workspace pill.
    @MainActor
    private func upsertTask(pill: String, display: PillSessionRegistry.Display,
                            working: Bool, externalAgent: String?) {
        sessions.note(pill: pill, display: display, working: working)
        if let externalAgent {
            upsertExternalAgent(id: pill, name: externalAgent)
        } else {
            upsertWorkspaceTask(id: pill, projectName: display.projectName, cwd: display.cwd,
                                hostApp: display.hostApp, bundleId: display.bundleId,
                                session: display.session)
        }
    }

    /// Updates or transiently creates a workspace pill (VS Code or Cursor) task, or a session's
    /// own pill. If the task already exists (persistent), just updates name/cwd.
    /// If missing (transient), creates it and inserts after the main pill (a session's own
    /// pill: after its client's).
    /// Name, cwd and terminal belong to the session that owns the pill (the oldest one
    /// still running), so a second session under the same client cannot rename the card,
    /// or send "Open terminal" elsewhere, out from under the first.
    @MainActor
    private func upsertWorkspaceTask(id: String, projectName: String, cwd: String = "", hostApp: String? = nil, bundleId: String = "", session: String) {
        let state = AppState.shared
        if let idx = state.tasks.firstIndex(where: { $0.id == id }) {
            guard sessions.ownsDisplay(pill: id, session: session) else { return }
            state.tasks[idx].name = projectName
            if !cwd.isEmpty { state.tasks[idx].sessionCwd = cwd }
            if PillCatalog.basePillId(id) == "integration_claude" { state.tasks[idx].hostApp = hostApp }
            if !bundleId.isEmpty { state.tasks[idx].sessionBundleId = bundleId }
            return
        }
        // Transient: create and insert after the main pill
        let def = PillCatalog.definition(for: id)
        let color = def?.color ?? "#C0C4CC"
        let source = def?.source ?? .agent
        var task = AgentTask(id: id, name: projectName, color: color,
                             state: .idle, steps: [], source: source, isIntegration: true)
        if task.pill == "integration_claude" { task.hostApp = hostApp }
        if !bundleId.isEmpty { task.sessionBundleId = bundleId }
        // A session's own pill goes after its client's other pills, so they stay together.
        if let sibling = state.tasks.lastIndex(where: { $0.pill == task.pill }) {
            state.tasks.insert(task, at: sibling + 1)
        } else if let mainIdx = state.tasks.firstIndex(where: { $0.id == state.mainPillId }) {
            state.tasks.insert(task, at: mainIdx + 1)
        } else {
            state.tasks.insert(task, at: 0)
        }
        if state.focusId == nil { state.focusId = id }
        state.syncMode()
    }

    // MARK: - Badge helpers

    @MainActor
    private func setPillBadge(id: String, badge: PillBadge) {
        let state = AppState.shared
        guard let idx = state.tasks.firstIndex(where: { $0.id == id }) else { return }
        state.tasks[idx].pillBadge = badge
    }

    @MainActor
    private func clearPillBadge(id: String) {
        let state = AppState.shared
        guard let idx = state.tasks.firstIndex(where: { $0.id == id }) else { return }
        state.tasks[idx].pillBadge = nil
    }

    // MARK: - Project name alias mapping

    /// The pill's name: the session's /rename title, else the folder the session started
    /// in (the hook reads both from the transcript), else the current cwd's folder.
    private func sessionName(_ payload: [String: Any], cwd: String) -> String {
        if let title = payload["session_title"] as? String, !title.isEmpty { return title }
        let root = payload["session_root"] as? String ?? ""
        let rawName = URL(fileURLWithPath: root.isEmpty ? cwd : root).lastPathComponent
        return aliasProjectName(rawName.isEmpty ? "Session" : rawName)
    }

    private func aliasProjectName(_ name: String) -> String {
        let aliases: [String: String] = [
            "notch-buddy":  "Notch Buddy",
            "notchbuddy":   "Notch Buddy",
            "notch_buddy":  "Notch Buddy",
        ]
        return aliases[name.lowercased()] ?? name
    }

    // MARK: - Localized step labels

    private func localizedStep(tool: String, input: [String: Any]) -> String {
        let labels: [String: String] = [
            "Bash":         String(localized: "step.runs",       defaultValue: "Runs"),
            "Read":         String(localized: "step.reads",      defaultValue: "Reads"),
            "Write":        String(localized: "step.writes",     defaultValue: "Writes"),
            "Edit":         String(localized: "step.edits",      defaultValue: "Edits"),
            "Glob":         String(localized: "step.searches",   defaultValue: "Searches"),
            "Grep":         String(localized: "step.searches",   defaultValue: "Searches"),
            "WebSearch":    String(localized: "step.web-search", defaultValue: "Searches the web"),
            "WebFetch":     String(localized: "step.fetches",    defaultValue: "Fetches"),
            "TodoWrite":    String(localized: "step.tasks",      defaultValue: "Tasks"),
            "Task":         String(localized: "step.agent",      defaultValue: "Agent"),
            "LS":           String(localized: "step.lists",      defaultValue: "Lists"),
            "MultiEdit":    String(localized: "step.edits",      defaultValue: "Edits"),
            "NotebookEdit": String(localized: "step.notebook",   defaultValue: "Notebook"),
            // Codex tools
            "apply_patch":  String(localized: "step.edits",     defaultValue: "Edits"),
            "update_plan":  String(localized: "step.tasks",     defaultValue: "Tasks"),
            "spawn_agent":  String(localized: "step.agent",     defaultValue: "Agent"),
            // Antigravity tools
            "ask_question": String(localized: "step.needs-input", defaultValue: "Needs input"),
        ]
        let labelTool = tool == "ask_question" || tool.hasSuffix(":ask_question") ? "ask_question" : tool
        var label = labels[labelTool] ?? tool

        // Codex MCP tools arrive as mcp__server__tool — show "server · tool"
        if tool.hasPrefix("mcp__") {
            let rest = String(tool.dropFirst(5))
            let parts = rest.components(separatedBy: "__")
            label = parts.count >= 2 ? "\(parts[0]) · \(parts.dropFirst().joined(separator: "__"))" : rest
        }

        // Bash: infer a more precise verb from the command
        if tool == "Bash", let cmd = input["command"] as? String {
            return "\(bashVerb(cmd)) · \(oneLine(cmd))"
        }

        // apply_patch: extract the first file name from the patch
        if tool == "apply_patch", let patch = input["command"] as? String {
            for line in patch.split(separator: "\n") {
                for prefix in ["*** Update File: ", "*** Add File: ", "*** Delete File: "] {
                    if line.hasPrefix(prefix) {
                        let path = String(line.dropFirst(prefix.count))
                        return "\(label) · \(URL(fileURLWithPath: path).lastPathComponent)"
                    }
                }
            }
            return label
        }

        // ask_question: extract the question string
        if (tool == "ask_question" || tool.hasSuffix(":ask_question")),
           let questions = input["questions"] as? [[String: Any]],
           let firstQ = questions.first?["question"] as? String,
           !firstQ.trimmingCharacters(in: .whitespaces).isEmpty {
            return "\(label) · \(oneLine(firstQ))"
        }

        if let cmd = input["command"] as? String {
            return "\(label) · \(oneLine(cmd))"
        } else if let path = input["path"] as? String {
            return "\(label) · \(URL(fileURLWithPath: path).lastPathComponent)"
        } else if let file = input["file_path"] as? String {
            return "\(label) · \(URL(fileURLWithPath: file).lastPathComponent)"
        } else if let query = input["query"] as? String {
            return "\(label) · \(oneLine(query))"
        }
        return label
    }

    /// Infers a localized verb from a shell command's first word.
    private func bashVerb(_ command: String) -> String {
        let first = command.split(whereSeparator: { $0.isWhitespace }).first.map(String.init) ?? ""
        switch first {
        case "cat", "bat", "head", "tail", "less", "more", "nl": return String(localized: "step.reads",    defaultValue: "Reads")
        case "rg", "grep", "find", "fd", "ls", "tree", "wc":    return String(localized: "step.searches", defaultValue: "Searches")
        default: break
        }
        let testRunners = ["pytest", "vitest", "jest", "npm test", "npm run test",
                           "cargo test", "go test", "swift test", "make test",
                           "xcodebuild test", "unittest"]
        if testRunners.contains(where: { command.contains($0) }) { return String(localized: "step.tests", defaultValue: "Tests") }
        return String(localized: "step.runs", defaultValue: "Runs")
    }

    // MARK: - Live diff helpers

    @MainActor
    private func buildFileDiff(tool: String, input: [String: Any], pillId: String) -> FileDiff? {
        switch tool {
        case "Edit":
            guard let old = input["old_string"] as? String,
                  let new = input["new_string"] as? String,
                  let path = input["file_path"] as? String,
                  !old.isEmpty || !new.isEmpty else { return nil }
            let d = DiffEngine.fromEdit(old: old, new: new, path: path)
            return (d.added > 0 || d.removed > 0) ? d : nil

        case "MultiEdit":
            guard let path = input["file_path"] as? String,
                  let edits = input["edits"] as? [[String: Any]], !edits.isEmpty else { return nil }
            var totalAdded = 0, totalRemoved = 0, allHunks: [DiffHunk] = [], anyLarge = false
            for edit in edits {
                guard let old = edit["old_string"] as? String,
                      let new = edit["new_string"] as? String else { continue }
                let d = DiffEngine.fromEdit(old: old, new: new, path: path)
                totalAdded += d.added; totalRemoved += d.removed
                allHunks.append(contentsOf: d.hunks); if d.tooLarge { anyLarge = true }
            }
            guard totalAdded > 0 || totalRemoved > 0 else { return nil }
            return FileDiff(path: path, added: totalAdded, removed: totalRemoved,
                            hunks: allHunks, tooLarge: anyLarge, isNewFile: false)

        case "Write":
            guard let path = input["file_path"] as? String,
                  let content = input["content"] as? String, !content.isEmpty else { return nil }
            let d = DiffEngine.fromNew(content: content, path: path)
            return (d.added > 0 || d.removed > 0) ? d : nil

        default:
            return nil
        }
    }

    /// Collapses whitespace so a multi-line command stays one ticker row.
    private func oneLine(_ text: String, limit: Int = 60) -> String {
        let collapsed = text.split(whereSeparator: { $0.isNewline || $0 == "\t" })
                            .joined(separator: " ")
        return collapsed.count > limit ? String(collapsed.prefix(limit)) + "…" : collapsed
    }

    // MARK: - Logging

    private func nbLog(_ message: String) {
        appendAppLog("nb.log", message)
    }

    private func sendLine(fd: Int32, text: String) {
        let bytes = Array((text + "\n").utf8)
        bytes.withUnsafeBytes { buffer in
            var sent = 0
            while sent < buffer.count {
                let n = Darwin.send(fd, buffer.baseAddress! + sent, buffer.count - sent, 0)
                if n <= 0 { break }
                sent += n
            }
        }
    }

    // MARK: - nb-hook script installation

    func installHookScript() {
        #if APPSTORE
        // In App Store mode the script is written during settings hook installation
        // (requires NSOpenPanel to ~/.claude chosen by the user)
        #else
        let dir = Self.supportDir
        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
        try? FileManager.default.setAttributes([.posixPermissions: 0o700 as NSNumber], ofItemAtPath: dir.path)
        // nb-hook: shell wrapper (always exits 0, calls nb-hook.py via python3)
        let wrapperURL = URL(fileURLWithPath: Self.hookScriptPath)
        try? nbHookShellWrapper.write(to: wrapperURL, atomically: true, encoding: .utf8)
        _ = try? FileManager.default.setAttributes([.posixPermissions: 0o755 as NSNumber], ofItemAtPath: wrapperURL.path)
        // nb-hook.py: Python relay
        let pyURL = wrapperURL.deletingLastPathComponent().appendingPathComponent("nb-hook.py")
        try? nbHookPythonGitHub.write(to: pyURL, atomically: true, encoding: .utf8)
        _ = try? FileManager.default.setAttributes([.posixPermissions: 0o755 as NSNumber], ofItemAtPath: pyURL.path)
        #endif
    }

    // MARK: - Outdated hook detection

    /// Returns true if settings.json has a Coucou hook that needs updating:
    /// either a PermissionRequest hook with timeout < 120s, or the AskUserQuestion
    /// PreToolUse matcher is missing (requires Claude Code 2.1.85+).
    static func hooksNeedUpdate() -> Bool {
        #if APPSTORE
        // Sandboxed: ~/.claude can't be read here (homeDirectoryForCurrentUser is the
        // container). The relay script written at install carries the version it was
        // written with: an older one (1.1 wrote none) misses plan approval, session titles
        // and Claude Desktop routing, so Settings offers "Update hooks".
        guard UserDefaults.standard.bool(forKey: "coucouHooksInstalled") else { return false }
        return UserDefaults.standard.integer(forKey: appStoreHookVersionKey) < appStoreHookVersion
        #else
        let settingsURL = FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".claude/settings.json")
        guard let data = try? Data(contentsOf: settingsURL),
              let settings = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
              let hooks = settings["hooks"] as? [String: Any] else {
            return false
        }
        // Track whether any Coucou hook is installed at all
        var hasCoucouHooks = false

        if let permReqHooks = hooks["PermissionRequest"] as? [[String: Any]] {
            for matcher in permReqHooks {
                if let hookList = matcher["hooks"] as? [[String: Any]] {
                    for hook in hookList {
                        if let cmd = hook["command"] as? String,
                           cmd.contains("NotchBuddy") || cmd.contains("coucou") {
                            hasCoucouHooks = true
                            if let timeout = hook["timeout"] as? Int, timeout < 120 { return true }
                        }
                    }
                }
            }
        }

        // Check that the AskUserQuestion PreToolUse entry exists
        if hasCoucouHooks {
            let preToolHooks = hooks["PreToolUse"] as? [[String: Any]] ?? []
            let hasAskEntry = preToolHooks.contains { m in
                (m["matcher"] as? String) == "AskUserQuestion"
                && (m["hooks"] as? [[String: Any]])?.contains {
                    let cmd = $0["command"] as? String ?? ""
                    return cmd.contains("NotchBuddy") || cmd.contains("coucou")
                } ?? false
            }
            if !hasAskEntry { return true }
        }
        return false
        #endif
    }

    #if APPSTORE
    /// Bump when nbHookPythonAppStore or the hooks written by buildHooksData change in a way
    /// the installed copy must catch up with. 1.1 wrote no version (0); 2.0 is 2.
    static let appStoreHookVersion = 2
    static let appStoreHookVersionKey = "coucouAppStoreHookVersion"
    #endif

    // MARK: - Claude Code settings.json hook installer

    private var _pendingHooksData: Data?
    /// The bytes of settings.json the pending preview was computed from.
    private var _pendingHooksOriginal: Data?

    /// Returns preview JSON without writing — call writeClaudeHooks() to confirm.
    func previewClaudeHooks() throws -> String {
        let (data, original) = try buildHooksData()
        _pendingHooksData = data
        _pendingHooksOriginal = original
        return String(data: data, encoding: .utf8) ?? ""
    }

    /// Writes the hooks to disk (call after user confirms preview).
    /// Refused if settings.json changed since the preview, or cannot be backed up.
    func writeClaudeHooks() throws {
        guard let data = _pendingHooksData else { return }
        let settingsURL = FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".claude/settings.json")
        try ClaudeSettingsFile.write(data, to: settingsURL, expecting: _pendingHooksOriginal)
        _pendingHooksData = nil
        _pendingHooksOriginal = nil
    }

    private func buildHooksData() throws -> (data: Data, original: Data?) {
        let settingsURL = FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".claude/settings.json")
        // Unreadable or invalid settings must stop here, never count as empty.
        let snapshot = try ClaudeSettingsFile.read(at: settingsURL)
        var settings = snapshot.object
        let hookPath = Self.hookScriptPath
        #if APPSTORE
        // Sandboxed apps create quarantined files; /bin/sh bypasses the quarantine flag
        let quotedCmd = "/bin/sh \"\(hookPath.replacingOccurrences(of: "\"", with: "\\\""))\""
        #else
        let quotedCmd = "\"\(hookPath.replacingOccurrences(of: "\"", with: "\\\""))\""
        #endif
        let events: [(String, Int)] = [
            ("SessionStart", 10), ("SessionEnd", 10),
            ("UserPromptSubmit", 10),
            ("PreToolUse", 10), ("PostToolUse", 10), ("PostToolUseFailure", 10),
            ("PermissionRequest", 120),
            ("Notification", 10),
            ("Stop", 10), ("StopFailure", 10),
            ("SubagentStart", 10), ("SubagentStop", 10),
        ]
        // "hooks" in a shape we do not know is refused, never replaced.
        var hooks = try ClaudeSettingsFile.hooks(in: settings, name: "settings.json")
        for (event, timeout) in events {
            var existing = try ClaudeSettingsFile.hookGroups(in: hooks, event: event, name: "settings.json")
            // Remove only our own nb-hook entries, not whole groups that merely
            // mention us: a user hook like ~/dev/coucou/scripts/lint.sh must survive.
            existing = removeNbHookEntries(from: existing)
            existing.append(["hooks": [["type": "command", "command": quotedCmd, "timeout": timeout]]])
            hooks[event] = existing
        }
        // Dedicated AskUserQuestion PreToolUse hook (Claude Code 2.1.85+, timeout 130s)
        var preToolUse = hooks["PreToolUse"] as? [[String: Any]] ?? []
        preToolUse.append([
            "matcher": "AskUserQuestion",
            "hooks": [["type": "command", "command": "\(quotedCmd) --ask", "timeout": 130]],
        ])
        hooks["PreToolUse"] = preToolUse
        settings["hooks"] = hooks
        let data = try JSONSerialization.data(withJSONObject: settings, options: [.prettyPrinted, .sortedKeys])
        return (data, snapshot.bytes)
    }

    func uninstallClaudeHooks() throws {
        let settingsURL = FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".claude/settings.json")
        let snapshot = try ClaudeSettingsFile.read(at: settingsURL)
        var settings = snapshot.object
        guard var hooks = settings["hooks"] as? [String: Any] else { return }

        for key in hooks.keys {
            if var matchers = hooks[key] as? [[String: Any]] {
                // Per-entry removal, like the Gemini path: user hooks that merely
                // mention "coucou"/"NotchBuddy" are kept, only nb-hook commands go.
                matchers = removeNbHookEntries(from: matchers)
                if matchers.isEmpty { hooks.removeValue(forKey: key) }
                else { hooks[key] = matchers }
            }
        }
        settings["hooks"] = hooks
        let newData = try JSONSerialization.data(withJSONObject: settings, options: [.prettyPrinted, .sortedKeys])
        try ClaudeSettingsFile.write(newData, to: settingsURL, expecting: snapshot.bytes)
    }

    // MARK: - Claude plan status line installer

    private var statusLinePreviousURL: URL {
        Self.supportDir.appendingPathComponent("statusline-previous.json")
    }

    /// Returns true if our statusLine command is installed in ~/.claude/settings.json.
    static func statusLineInstalled() -> Bool {
        let url = FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".claude/settings.json")
        guard let data = try? Data(contentsOf: url),
              let settings = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any],
              let sl = settings["statusLine"] as? [String: Any],
              let cmd = sl["command"] as? String else { return false }
        return cmd.contains("nb-hook")
    }

    private var _pendingStatusLineData: Data?
    /// The bytes of settings.json the pending preview was computed from.
    private var _pendingStatusLineOriginal: Data?
    private var _pendingPreviousData: Data?
    private var _pendingDeletePrevious: Bool = false

    /// Returns a diff string (only the statusLine key: before → after) without writing anything.
    func previewStatusLine(install: Bool) throws -> String {
        let settingsURL = FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".claude/settings.json")
        // Unreadable or invalid settings must stop here, never count as empty.
        let snapshot = try ClaudeSettingsFile.read(at: settingsURL)
        let settings = snapshot.object
        let hookPath = Self.hookScriptPath
        let quotedPath = hookPath.replacingOccurrences(of: "\"", with: "\\\"")
        let quotedCmd = "\"\(quotedPath)\" --statusline"

        // Reset pending side-effects
        _pendingPreviousData = nil
        _pendingDeletePrevious = false

        let oldSL = settings["statusLine"] as? [String: Any]
        let newSL: [String: Any]?

        if install {
            // Check that Python 3 is available (requires Command Line Tools)
            let clCheck = Process()
            clCheck.executableURL = URL(fileURLWithPath: "/usr/bin/xcode-select")
            clCheck.arguments = ["-p"]
            clCheck.standardOutput = FileHandle.nullDevice
            clCheck.standardError = FileHandle.nullDevice
            try? clCheck.run()
            clCheck.waitUntilExit()
            if clCheck.terminationStatus != 0 {
                throw NSError(domain: "Coucou", code: 1,
                              userInfo: [NSLocalizedDescriptionKey:
                                  "Command Line Tools are required but not installed. Run: xcode-select --install"])
            }

            if let existing = oldSL,
               let cmd = existing["command"] as? String, !cmd.contains("nb-hook") {
                // Keep existing object but swap command; save old for later restoration
                var updated = existing
                updated["command"] = quotedCmd
                newSL = updated
                _pendingPreviousData = try? JSONSerialization.data(withJSONObject: existing,
                                                                   options: [.prettyPrinted, .sortedKeys])
            } else if let existing = oldSL,
                      let cmd = existing["command"] as? String, cmd.contains("nb-hook") {
                // Already installed — rebuild to update path if needed, keep other fields
                var updated = existing
                updated["command"] = quotedCmd
                newSL = updated
            } else {
                newSL = ["type": "command", "command": quotedCmd]
            }
        } else {
            // Uninstall: only if it's ours
            if let cur = oldSL, let cmd = cur["command"] as? String, cmd.contains("nb-hook") {
                if let prevData = try? Data(contentsOf: statusLinePreviousURL),
                   let prevObj = (try? JSONSerialization.jsonObject(with: prevData)) as? [String: Any] {
                    newSL = prevObj
                    _pendingDeletePrevious = true
                } else {
                    newSL = nil
                }
            } else {
                newSL = oldSL  // not ours — leave unchanged
            }
        }

        // Build the full settings.json with the new statusLine
        var newSettings = settings
        if let sl = newSL {
            newSettings["statusLine"] = sl
        } else {
            newSettings.removeValue(forKey: "statusLine")
        }
        let data = try JSONSerialization.data(withJSONObject: newSettings,
                                              options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])
        _pendingStatusLineData = data
        _pendingStatusLineOriginal = snapshot.bytes

        // Build a compact diff: show only the statusLine key before → after
        func slJSON(_ val: [String: Any]?) throws -> String {
            guard let v = val else { return "(none)" }
            let d = try JSONSerialization.data(withJSONObject: v, options: [.prettyPrinted, .sortedKeys])
            return String(data: d, encoding: .utf8) ?? "(none)"
        }
        let before = try slJSON(oldSL)
        let after  = try slJSON(newSL)
        return "statusLine\nBefore:\n\(before)\n\nAfter:\n\(after)"
    }

    /// Writes settings.json and commits side effects (call after user confirms).
    func writeStatusLine() throws {
        guard let data = _pendingStatusLineData else { return }
        let settingsURL = FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".claude/settings.json")
        try ClaudeSettingsFile.write(data, to: settingsURL, expecting: _pendingStatusLineOriginal)
        // Commit side effects only after successful write
        if let prevData = _pendingPreviousData {
            try? prevData.write(to: statusLinePreviousURL, options: .atomic)
        }
        if _pendingDeletePrevious {
            try? FileManager.default.removeItem(at: statusLinePreviousURL)
        }
        _pendingStatusLineData = nil
        _pendingStatusLineOriginal = nil
        _pendingPreviousData = nil
        _pendingDeletePrevious = false
    }

    // MARK: - App Store: hooks via security-scoped bookmark

    #if APPSTORE
    /// Writes nb-hook script and updates settings.json in one shot.
    /// claudeURL must be a URL from NSOpenPanel (sandbox access is granted immediately — no security scope needed).
    func installAndWriteClaudeHooksAppStore(claudeURL: URL) throws {
        let (data, original) = try buildHooksData(claudeURL: claudeURL)

        // Write nb-hook (shell wrapper) + nb-hook.py (Python relay) into ~/.claude/coucou/
        let coucouDir = claudeURL.appendingPathComponent("coucou")
        try FileManager.default.createDirectory(at: coucouDir, withIntermediateDirectories: true)
        let wrapperURL = coucouDir.appendingPathComponent("nb-hook")
        try nbHookShellWrapper.write(to: wrapperURL, atomically: true, encoding: .utf8)
        _ = try? FileManager.default.setAttributes([.posixPermissions: 0o755 as NSNumber], ofItemAtPath: wrapperURL.path)
        let pyURL = coucouDir.appendingPathComponent("nb-hook.py")
        try nbHookPythonAppStore.write(to: pyURL, atomically: true, encoding: .utf8)
        _ = try? FileManager.default.setAttributes([.posixPermissions: 0o755 as NSNumber], ofItemAtPath: pyURL.path)

        // Write settings.json (with backup)
        let settingsURL = claudeURL.appendingPathComponent("settings.json")
        try ClaudeSettingsFile.write(data, to: settingsURL, expecting: original)
        UserDefaults.standard.set(true, forKey: "coucouHooksInstalled")
        UserDefaults.standard.set(Self.appStoreHookVersion, forKey: Self.appStoreHookVersionKey)
    }

    /// The settings.json Coucou would write, to show before writing (CLAUDE.md: never
    /// write ~/.claude/settings.json without showing the change first).
    func previewClaudeHooksAppStore(claudeURL: URL) throws -> String {
        let (data, _) = try buildHooksData(claudeURL: claudeURL)
        return String(data: data, encoding: .utf8) ?? ""
    }

    func uninstallClaudeHooksAppStore(claudeURL: URL) throws {
        let settingsURL = claudeURL.appendingPathComponent("settings.json")
        let snapshot = try ClaudeSettingsFile.read(at: settingsURL)
        var settings = snapshot.object
        guard var hooks = settings["hooks"] as? [String: Any] else { return }
        for key in hooks.keys {
            if var matchers = hooks[key] as? [[String: Any]] {
                // Per-entry removal, like the Gemini path: user hooks that merely
                // mention "coucou"/"NotchBuddy" are kept, only nb-hook commands go.
                matchers = removeNbHookEntries(from: matchers)
                if matchers.isEmpty { hooks.removeValue(forKey: key) }
                else { hooks[key] = matchers }
            }
        }
        settings["hooks"] = hooks
        let newData = try JSONSerialization.data(withJSONObject: settings, options: [.prettyPrinted, .sortedKeys])
        try ClaudeSettingsFile.write(newData, to: settingsURL, expecting: snapshot.bytes)
        UserDefaults.standard.set(false, forKey: "coucouHooksInstalled")
    }

    private func buildHooksData(claudeURL: URL) throws -> (data: Data, original: Data?) {
        let settingsURL = claudeURL.appendingPathComponent("settings.json")
        // Unreadable or invalid settings must stop here, never count as empty.
        let snapshot = try ClaudeSettingsFile.read(at: settingsURL)
        var settings = snapshot.object
        // Derive hook path from the panel-selected claudeURL (real ~/.claude, not container)
        let hookPath = claudeURL.appendingPathComponent("coucou/nb-hook").path
        let quotedCmd = "/bin/sh \"\(hookPath.replacingOccurrences(of: "\"", with: "\\\""))\""
        let events: [(String, Int)] = [
            ("SessionStart", 10), ("SessionEnd", 10),
            ("UserPromptSubmit", 10),
            ("PreToolUse", 10), ("PostToolUse", 10), ("PostToolUseFailure", 10),
            ("PermissionRequest", 120),
            ("Notification", 10),
            ("Stop", 10), ("StopFailure", 10),
            ("SubagentStart", 10), ("SubagentStop", 10),
        ]
        // "hooks" in a shape we do not know is refused, never replaced.
        var hooks = try ClaudeSettingsFile.hooks(in: settings, name: "settings.json")
        for (event, timeout) in events {
            var existing = try ClaudeSettingsFile.hookGroups(in: hooks, event: event, name: "settings.json")
            // Remove only our own nb-hook entries, not whole groups that merely
            // mention us: a user hook like ~/dev/coucou/scripts/lint.sh must survive.
            existing = removeNbHookEntries(from: existing)
            existing.append(["hooks": [["type": "command", "command": quotedCmd, "timeout": timeout]]])
            hooks[event] = existing
        }
        // Dedicated AskUserQuestion PreToolUse hook (Claude Code 2.1.85+, timeout 130s)
        var preToolUse = hooks["PreToolUse"] as? [[String: Any]] ?? []
        preToolUse.append([
            "matcher": "AskUserQuestion",
            "hooks": [["type": "command", "command": "\(quotedCmd) --ask", "timeout": 130]],
        ])
        hooks["PreToolUse"] = preToolUse
        settings["hooks"] = hooks
        let data = try JSONSerialization.data(withJSONObject: settings, options: [.prettyPrinted, .sortedKeys])
        return (data, snapshot.bytes)
    }
    #endif

    // MARK: - Claude Code installed-state detection (both builds)

    /// True when ~/.claude/settings.json already routes Claude Code events to Coucou.
    /// Cursor sessions ride on these same hooks, so they share this state.
    static func claudeHooksInstalled() -> Bool {
        #if APPSTORE
        // Sandboxed: can't read ~/.claude directly — check the install flag set on write.
        return UserDefaults.standard.bool(forKey: "coucouHooksInstalled")
        #else
        let url = FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".claude/settings.json")
        guard let data = try? Data(contentsOf: url),
              let json = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any]
        else { return false }
        return coucouHooksPresent(inSettings: json)
        #endif
    }

    // MARK: - Removing Coucou's own hook entries (both builds)

    /// Removes entries containing "nb-hook" from a Gemini- or Claude-format groups array
    /// (matcher + hooks[]), handling the legacy flat format too (command at top level).
    /// Used by both paths' install/uninstall so only Coucou's own entries are removed;
    /// whole groups are dropped only when every entry in them was ours.
    private func removeNbHookEntries(from groups: [[String: Any]]) -> [[String: Any]] {
        groups.compactMap { group -> [String: Any]? in
            // Legacy flat entry — command at group level
            if let cmd = group["command"] as? String, cmd.contains("nb-hook") { return nil }
            // Group format — filter inner hooks
            if var innerHooks = group["hooks"] as? [[String: Any]] {
                innerHooks.removeAll { ($0["command"] as? String)?.contains("nb-hook") == true }
                if innerHooks.isEmpty { return nil }
                var updated = group
                updated["hooks"] = innerHooks
                return updated
            }
            return group
        }
    }

    // MARK: - Gemini CLI and Antigravity hook installers  (#if !APPSTORE only)

    #if !APPSTORE
    private static var geminiSettingsURL: URL {
        FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".gemini/settings.json")
    }
    private static var agyHooksURL: URL {
        FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".gemini/config/hooks.json")
    }

    // MARK: Installed-state detection

    static func geminiHooksInstalled() -> Bool {
        guard let data = try? Data(contentsOf: geminiSettingsURL),
              let settings = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any],
              let hooks = settings["hooks"] as? [String: Any] else { return false }
        for value in hooks.values {
            guard let groups = value as? [[String: Any]] else { continue }
            for group in groups {
                if let innerHooks = group["hooks"] as? [[String: Any]] {
                    for hook in innerHooks {
                        if let cmd = hook["command"] as? String,
                           cmd.contains("nb-hook"), cmd.contains("--agent gemini") { return true }
                    }
                }
                // Legacy flat entry
                if let cmd = group["command"] as? String,
                   cmd.contains("nb-hook"), cmd.contains("--agent gemini") { return true }
            }
        }
        return false
    }

    static func agyHooksInstalled() -> Bool {
        guard let data = try? Data(contentsOf: agyHooksURL),
              let root = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any],
              let coucou = root["coucou"] else { return false }
        let json = (try? JSONSerialization.data(withJSONObject: coucou))
            .flatMap { String(data: $0, encoding: .utf8) } ?? ""
        return json.contains("nb-hook")
    }

    // MARK: Gemini CLI – preview / write

    private var _pendingGeminiData: Data?
    private var _pendingGeminiFingerprint: String?

    func previewGeminiHooks(install: Bool) throws -> String {
        let url = Self.geminiSettingsURL
        let exists = FileManager.default.fileExists(atPath: url.path)
        if !install && !exists {
            throw NSError(domain: "CoucouNoop", code: 0, userInfo: [
                NSLocalizedDescriptionKey: "No Gemini CLI hooks to remove."
            ])
        }
        let current = exists ? try Data(contentsOf: url) : Data()
        _pendingGeminiFingerprint = sha256Hex(current)
        let newData = install ? try buildGeminiHooksData() : try withoutGeminiHooks()
        _pendingGeminiData = newData
        return String(data: newData, encoding: .utf8) ?? ""
    }

    func writeGeminiHooks() throws {
        guard let data = _pendingGeminiData, let fp = _pendingGeminiFingerprint else { return }
        let url = Self.geminiSettingsURL
        let current = (try? Data(contentsOf: url)) ?? Data()
        guard sha256Hex(current) == fp else {
            throw NSError(domain: "Coucou", code: 1, userInfo: [
                NSLocalizedDescriptionKey: "~/.gemini/settings.json changed since preview. Refresh and try again."
            ])
        }
        try writeJSONFile(data, to: url, suffix: "settings.json")
        _pendingGeminiData = nil
        _pendingGeminiFingerprint = nil
    }

    private func buildGeminiHooksData() throws -> Data {
        var settings = try Self.strictReadJSONObject(at: Self.geminiSettingsURL,
                                                     label: "~/.gemini/settings.json")
        if let raw = settings["hooks"], !(raw is [String: Any]) {
            throw NSError(domain: "Coucou", code: 2, userInfo: [
                NSLocalizedDescriptionKey: "~/.gemini/settings.json: \"hooks\" has an unexpected type — Coucou has not touched it."
            ])
        }
        let base = hookBase()
        // (Gemini event key, normalized event name passed via argv, timeout in ms)
        let events: [(String, String, Int)] = [
            ("SessionStart", "SessionStart", 10000),
            ("SessionEnd",   "SessionEnd",   10000),
            ("BeforeTool",   "PreToolUse",   5000),
            ("AfterTool",    "PostToolUse",  5000),
            ("BeforeAgent",  "UserPromptSubmit", 5000),
            ("AfterAgent",   "Stop",         5000),
        ]
        var hooks = settings["hooks"] as? [String: Any] ?? [:]
        for (geminiEvent, normalizedEvent, timeout) in events {
            if let raw = hooks[geminiEvent], !(raw is [[String: Any]]) {
                throw NSError(domain: "Coucou", code: 2, userInfo: [
                    NSLocalizedDescriptionKey: "~/.gemini/settings.json: \"hooks\"[\"\(geminiEvent)\"] has an unexpected type — Coucou has not touched it."
                ])
            }
            var groups = hooks[geminiEvent] as? [[String: Any]] ?? []
            // Remove legacy flat entries and groups whose inner hooks contain nb-hook
            groups = removeNbHookEntries(from: groups)
            let hookEntry: [String: Any] = [
                "type": "command",
                "command": "\(base) --agent gemini \(normalizedEvent)",
                "timeout": timeout,
            ]
            groups.append(["matcher": "*", "hooks": [hookEntry]])
            hooks[geminiEvent] = groups
        }
        settings["hooks"] = hooks
        return try JSONSerialization.data(withJSONObject: settings,
                                         options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])
    }

    private func withoutGeminiHooks() throws -> Data {
        var settings = try Self.strictReadJSONObject(at: Self.geminiSettingsURL,
                                                     label: "~/.gemini/settings.json")
        if let raw = settings["hooks"], !(raw is [String: Any]) {
            throw NSError(domain: "Coucou", code: 2, userInfo: [
                NSLocalizedDescriptionKey: "~/.gemini/settings.json: \"hooks\" has an unexpected type — Coucou has not touched it."
            ])
        }
        if var hooks = settings["hooks"] as? [String: Any] {
            for key in hooks.keys {
                if let groups = hooks[key] as? [[String: Any]] {
                    let cleaned = removeNbHookEntries(from: groups)
                    if cleaned.isEmpty { hooks.removeValue(forKey: key) } else { hooks[key] = cleaned }
                }
            }
            if hooks.isEmpty { settings.removeValue(forKey: "hooks") } else { settings["hooks"] = hooks }
        }
        return try JSONSerialization.data(withJSONObject: settings,
                                         options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])
    }

    // MARK: Antigravity – preview / write

    private var _pendingAgyData: Data?
    private var _pendingAgyFingerprint: String?

    func previewAgyHooks(install: Bool) throws -> String {
        let url = Self.agyHooksURL
        let exists = FileManager.default.fileExists(atPath: url.path)
        if !install && !exists {
            throw NSError(domain: "CoucouNoop", code: 0, userInfo: [
                NSLocalizedDescriptionKey: "No Antigravity hooks to remove."
            ])
        }
        let current = exists ? try Data(contentsOf: url) : Data()
        _pendingAgyFingerprint = sha256Hex(current)
        let newData = install ? try buildAgyHooksData() : try withoutAgyHooks()
        _pendingAgyData = newData
        return String(data: newData, encoding: .utf8) ?? ""
    }

    func writeAgyHooks() throws {
        guard let data = _pendingAgyData, let fp = _pendingAgyFingerprint else { return }
        let url = Self.agyHooksURL
        let current = (try? Data(contentsOf: url)) ?? Data()
        guard sha256Hex(current) == fp else {
            throw NSError(domain: "Coucou", code: 1, userInfo: [
                NSLocalizedDescriptionKey: "~/.gemini/config/hooks.json changed since preview. Refresh and try again."
            ])
        }
        try writeJSONFile(data, to: url, suffix: "hooks.json")
        _pendingAgyData = nil
        _pendingAgyFingerprint = nil
    }

    private func buildAgyHooksData() throws -> Data {
        var root = try Self.strictReadJSONObject(at: Self.agyHooksURL,
                                                 label: "~/.gemini/config/hooks.json")
        let base = hookBase()
        // PreToolUse / PostToolUse: tool-level hooks — use matcher group
        // PreInvocation / PostInvocation / Stop: lifecycle hooks — direct handler, no matcher
        var coucou: [String: Any] = [:]
        for event in ["PreToolUse", "PostToolUse"] {
            let hook: [String: Any] = ["type": "command",
                                       "command": "\(base) --agent antigravity \(event)",
                                       "timeout": 10]
            coucou[event] = [["matcher": "*", "hooks": [hook]]]
        }
        for event in ["PreInvocation", "PostInvocation", "Stop"] {
            let hook: [String: Any] = ["type": "command",
                                       "command": "\(base) --agent antigravity \(event)",
                                       "timeout": 10]
            coucou[event] = [hook]
        }
        root["coucou"] = coucou
        return try JSONSerialization.data(withJSONObject: root,
                                         options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])
    }

    private func withoutAgyHooks() throws -> Data {
        var root = try Self.strictReadJSONObject(at: Self.agyHooksURL,
                                                 label: "~/.gemini/config/hooks.json")
        root.removeValue(forKey: "coucou")
        return try JSONSerialization.data(withJSONObject: root,
                                         options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])
    }

    // MARK: Shared helpers

    /// /bin/sh "<hookScriptPath>" — quoted for paths containing spaces (Application Support).
    private func hookBase() -> String {
        let path = Self.hookScriptPath.replacingOccurrences(of: "\"", with: "\\\"")
        return "/bin/sh \"\(path)\""
    }

    /// Reads a JSON object from url.
    /// Absent file → empty dict. Present but invalid → throws with a user-facing message.
    private static func strictReadJSONObject(at url: URL, label: String) throws -> [String: Any] {
        guard FileManager.default.fileExists(atPath: url.path) else { return [:] }
        let data: Data
        do { data = try Data(contentsOf: url) }
        catch {
            throw NSError(domain: "Coucou", code: 2, userInfo: [
                NSLocalizedDescriptionKey: "\(label) cannot be read — Coucou has not touched it."
            ])
        }
        guard let obj = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else {
            throw NSError(domain: "Coucou", code: 2, userInfo: [
                NSLocalizedDescriptionKey: "\(label) is not valid JSON — Coucou has not touched it."
            ])
        }
        return obj
    }

    /// Backs up the existing file (throws on failure), creates parent dirs, then atomically writes.
    private func writeJSONFile(_ data: Data, to url: URL, suffix: String) throws {
        let fm = FileManager.default
        if fm.fileExists(atPath: url.path) {
            let fmt = DateFormatter()
            fmt.locale = Locale(identifier: "en_US_POSIX")
            fmt.dateFormat = "yyyyMMdd-HHmmss"
            let backupURL = url.deletingLastPathComponent()
                .appendingPathComponent("\(suffix).bak-\(fmt.string(from: Date()))")
            do { try fm.copyItem(at: url, to: backupURL) }
            catch {
                throw NSError(domain: "Coucou", code: 3, userInfo: [
                    NSLocalizedDescriptionKey: "Could not back up \(url.lastPathComponent): \(error.localizedDescription)"
                ])
            }
        }
        try fm.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
        try data.write(to: url, options: .atomic)
    }

    // MARK: - Codex hook installer  (#if !APPSTORE only)

    static var codexHooksURL: URL {
        FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".codex/hooks.json")
    }

    /// True when ~/.codex/hooks.json already routes Codex events to Coucou's nb-hook.
    static func codexHooksInstalled() -> Bool {
        guard let data = try? Data(contentsOf: codexHooksURL),
              let root = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any],
              let hooks = root["hooks"] as? [String: Any] else { return false }
        for value in hooks.values {
            guard let groups = value as? [[String: Any]] else { continue }
            for group in groups {
                if let innerHooks = group["hooks"] as? [[String: Any]] {
                    for hook in innerHooks {
                        if let cmd = hook["command"] as? String,
                           cmd.contains("nb-hook"), cmd.contains("--agent codex") { return true }
                    }
                }
            }
        }
        return false
    }

    private var _pendingCodexData: Data?
    private var _pendingCodexFingerprint: String?

    func previewCodexHooks(install: Bool) throws -> String {
        let url = Self.codexHooksURL
        let exists = FileManager.default.fileExists(atPath: url.path)
        if !install && !exists {
            throw NSError(domain: "CoucouNoop", code: 0, userInfo: [
                NSLocalizedDescriptionKey: "No Codex hooks to remove."
            ])
        }
        let current = exists ? try Data(contentsOf: url) : Data()
        _pendingCodexFingerprint = sha256Hex(current)
        let newData = install ? try buildCodexHooksData() : try withoutCodexHooks()
        _pendingCodexData = newData
        return String(data: newData, encoding: .utf8) ?? ""
    }

    func writeCodexHooks() throws {
        guard let data = _pendingCodexData, let fp = _pendingCodexFingerprint else { return }
        let url = Self.codexHooksURL
        let current = (try? Data(contentsOf: url)) ?? Data()
        guard sha256Hex(current) == fp else {
            throw NSError(domain: "Coucou", code: 1, userInfo: [
                NSLocalizedDescriptionKey: "~/.codex/hooks.json changed since preview. Refresh and try again."
            ])
        }
        try writeJSONFile(data, to: url, suffix: "hooks.json")
        _pendingCodexData = nil
        _pendingCodexFingerprint = nil
    }

    private func buildCodexHooksData() throws -> Data {
        var root = try Self.strictReadJSONObject(at: Self.codexHooksURL, label: "~/.codex/hooks.json")
        if let raw = root["hooks"], !(raw is [String: Any]) {
            throw NSError(domain: "Coucou", code: 2, userInfo: [
                NSLocalizedDescriptionKey: "~/.codex/hooks.json: \"hooks\" has an unexpected type — Coucou has not touched it."
            ])
        }
        let base = hookBase()
        // Events, timeouts in seconds (Codex format).
        // PermissionRequest uses 120s + a statusMessage shown in the Codex UI while waiting.
        let events: [(String, Int, String?)] = [
            ("SessionStart",    10,  nil),
            ("UserPromptSubmit", 10, nil),
            ("PreToolUse",      10,  nil),
            ("PermissionRequest", 120, "Waiting for your answer in the notch (Coucou)"),
            ("PostToolUse",     10,  nil),
            ("Stop",            10,  nil),
            ("SubagentStart",   10,  nil),
            ("SubagentStop",    10,  nil),
            ("Interrupt",        3,  nil),
            ("SessionEnd",       3,  nil),
        ]
        var hooks = root["hooks"] as? [String: Any] ?? [:]
        for (event, timeout, statusMsg) in events {
            if let raw = hooks[event], !(raw is [[String: Any]]) {
                throw NSError(domain: "Coucou", code: 2, userInfo: [
                    NSLocalizedDescriptionKey: "~/.codex/hooks.json: \"hooks\"[\"\(event)\"] has an unexpected type — Coucou has not touched it."
                ])
            }
            var groups = hooks[event] as? [[String: Any]] ?? []
            // Remove existing Coucou entries
            groups = removeNbHookEntries(from: groups)
            var hookEntry: [String: Any] = [
                "type": "command",
                "command": "\(base) --agent codex",
                "timeout": timeout,
            ]
            if let msg = statusMsg { hookEntry["statusMessage"] = msg }
            groups.append(["hooks": [hookEntry]])
            hooks[event] = groups
        }
        root["hooks"] = hooks
        return try JSONSerialization.data(withJSONObject: root,
                                         options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])
    }

    private func withoutCodexHooks() throws -> Data {
        var root = try Self.strictReadJSONObject(at: Self.codexHooksURL, label: "~/.codex/hooks.json")
        if let raw = root["hooks"], !(raw is [String: Any]) {
            throw NSError(domain: "Coucou", code: 2, userInfo: [
                NSLocalizedDescriptionKey: "~/.codex/hooks.json: \"hooks\" has an unexpected type — Coucou has not touched it."
            ])
        }
        if var hooks = root["hooks"] as? [String: Any] {
            for key in hooks.keys {
                if let groups = hooks[key] as? [[String: Any]] {
                    let cleaned = removeNbHookEntries(from: groups)
                    if cleaned.isEmpty { hooks.removeValue(forKey: key) } else { hooks[key] = cleaned }
                }
            }
            if hooks.isEmpty { root.removeValue(forKey: "hooks") } else { root["hooks"] = hooks }
        }
        return try JSONSerialization.data(withJSONObject: root,
                                         options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])
    }

    // MARK: - GitHub Copilot CLI hook installer

    static var copilotHooksURL: URL {
        FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".copilot/hooks/coucou.json")
    }

    /// True when ~/.copilot/hooks/coucou.json already routes Copilot events to Coucou's nb-hook.
    static func copilotHooksInstalled() -> Bool {
        guard let data = try? Data(contentsOf: copilotHooksURL),
              let root = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any],
              let hooks = root["hooks"] as? [String: Any] else { return false }
        for value in hooks.values {
            guard let entries = value as? [[String: Any]] else { continue }
            for entry in entries {
                if let cmd = entry["bash"] as? String,
                   cmd.contains("nb-hook"), cmd.contains("--agent copilot") { return true }
            }
        }
        return false
    }

    private var _pendingCopilotData: Data?
    private var _pendingCopilotFingerprint: String?

    func previewCopilotHooks(install: Bool) throws -> String {
        let url = Self.copilotHooksURL
        let exists = FileManager.default.fileExists(atPath: url.path)
        if !install && !exists {
            throw NSError(domain: "CoucouNoop", code: 0, userInfo: [
                NSLocalizedDescriptionKey: "No Copilot hooks to remove."
            ])
        }
        let current = exists ? try Data(contentsOf: url) : Data()
        _pendingCopilotFingerprint = sha256Hex(current)
        if install {
            let newData = try buildCopilotHooksData()
            _pendingCopilotData = newData
            return String(data: newData, encoding: .utf8) ?? ""
        } else {
            _pendingCopilotData = nil  // nil = delete signal
            return "(will delete \(url.path))"
        }
    }

    func writeCopilotHooks() throws {
        guard let fp = _pendingCopilotFingerprint else { return }
        let url = Self.copilotHooksURL
        let current = (try? Data(contentsOf: url)) ?? Data()
        guard sha256Hex(current) == fp else {
            throw NSError(domain: "Coucou", code: 1, userInfo: [
                NSLocalizedDescriptionKey: "~/.copilot/hooks/coucou.json changed since preview. Refresh and try again."
            ])
        }
        if let data = _pendingCopilotData {
            try writeJSONFile(data, to: url, suffix: "coucou.json")
        } else {
            // Uninstall: delete the file entirely
            try FileManager.default.removeItem(at: url)
        }
        _pendingCopilotData = nil
        _pendingCopilotFingerprint = nil
    }

    private func buildCopilotHooksData() throws -> Data {
        var root = try Self.strictReadJSONObject(at: Self.copilotHooksURL,
                                                  label: "~/.copilot/hooks/coucou.json")
        if let raw = root["hooks"], !(raw is [String: Any]) {
            throw NSError(domain: "Coucou", code: 2, userInfo: [
                NSLocalizedDescriptionKey: "~/.copilot/hooks/coucou.json: \"hooks\" has an unexpected type — Coucou has not touched it."
            ])
        }
        let base = hookBase()
        // Copilot CLI uses camelCase event names; each entry uses "bash" + "timeoutSec".
        // The event name is passed as a positional arg so the relay can fall back to it.
        // Copilot is fail-closed on permissionRequest — must always output valid JSON.
        let events: [(String, Int)] = [
            ("sessionStart",        10),
            ("userPromptSubmitted", 10),
            ("preToolUse",          10),
            ("permissionRequest",  120),
            ("postToolUse",         10),
            ("agentStop",           10),
            ("sessionEnd",           3),
            ("notification",        10),
        ]
        var hooks = root["hooks"] as? [String: Any] ?? [:]
        for (event, timeout) in events {
            if let raw = hooks[event], !(raw is [[String: Any]]) {
                throw NSError(domain: "Coucou", code: 2, userInfo: [
                    NSLocalizedDescriptionKey: "~/.copilot/hooks/coucou.json: \"hooks\"[\"\(event)\"] has an unexpected type — Coucou has not touched it."
                ])
            }
            var entries = hooks[event] as? [[String: Any]] ?? []
            entries.removeAll { ($0["bash"] as? String)?.contains("nb-hook") == true }
            entries.append(["type": "command", "bash": "\(base) --agent copilot \(event)", "timeoutSec": timeout])
            hooks[event] = entries
        }
        root["hooks"] = hooks
        root["version"] = 1
        return try JSONSerialization.data(withJSONObject: root,
                                         options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])
    }

    private func withoutCopilotHooks() throws -> Data {
        var root = try Self.strictReadJSONObject(at: Self.copilotHooksURL,
                                                  label: "~/.copilot/hooks/coucou.json")
        if var hooks = root["hooks"] as? [String: Any] {
            for key in hooks.keys {
                if var entries = hooks[key] as? [[String: Any]] {
                    entries.removeAll { ($0["command"] as? String)?.contains("nb-hook") == true }
                    if entries.isEmpty { hooks.removeValue(forKey: key) } else { hooks[key] = entries }
                }
            }
            if hooks.isEmpty { root.removeValue(forKey: "hooks") } else { root["hooks"] = hooks }
        }
        return try JSONSerialization.data(withJSONObject: root,
                                         options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])
    }

    // MARK: - Muse Code hook installer

    static var museSettingsURL: URL {
        FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".config/muse/settings.json")
    }

    /// True when ~/.config/muse/settings.json already routes Muse events to Coucou's nb-hook.
    static func museHooksInstalled() -> Bool {
        guard let data = try? Data(contentsOf: museSettingsURL),
              let settings = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any],
              let hooks = settings["hooks"] as? [String: Any] else { return false }
        for value in hooks.values {
            guard let groups = value as? [[String: Any]] else { continue }
            for group in groups {
                if let innerHooks = group["hooks"] as? [[String: Any]] {
                    for h in innerHooks {
                        if let cmd = h["command"] as? String,
                           cmd.contains("nb-hook"), cmd.contains("--agent muse") { return true }
                    }
                }
                if let cmd = group["command"] as? String,
                   cmd.contains("nb-hook"), cmd.contains("--agent muse") { return true }
            }
        }
        return false
    }

    private var _pendingMuseData: Data?
    private var _pendingMuseFingerprint: String?

    func previewMuseHooks(install: Bool) throws -> String {
        let url = Self.museSettingsURL
        let exists = FileManager.default.fileExists(atPath: url.path)
        if !install && !exists {
            throw NSError(domain: "CoucouNoop", code: 0, userInfo: [
                NSLocalizedDescriptionKey: "No Muse Code hooks to remove."
            ])
        }
        let current = exists ? try Data(contentsOf: url) : Data()
        _pendingMuseFingerprint = sha256Hex(current)
        let newData = install ? try buildMuseHooksData() : try withoutMuseHooks()
        _pendingMuseData = newData
        return String(data: newData, encoding: .utf8) ?? ""
    }

    func writeMuseHooks() throws {
        guard let data = _pendingMuseData, let fp = _pendingMuseFingerprint else { return }
        let url = Self.museSettingsURL
        let current = (try? Data(contentsOf: url)) ?? Data()
        guard sha256Hex(current) == fp else {
            throw NSError(domain: "Coucou", code: 1, userInfo: [
                NSLocalizedDescriptionKey: "~/.config/muse/settings.json changed since preview. Refresh and try again."
            ])
        }
        try writeJSONFile(data, to: url, suffix: "settings.json")
        _pendingMuseData = nil
        _pendingMuseFingerprint = nil
    }

    private func buildMuseHooksData() throws -> Data {
        var settings = try Self.strictReadJSONObject(at: Self.museSettingsURL,
                                                      label: "~/.config/muse/settings.json")
        if let raw = settings["hooks"], !(raw is [String: Any]) {
            throw NSError(domain: "Coucou", code: 2, userInfo: [
                NSLocalizedDescriptionKey: "~/.config/muse/settings.json: \"hooks\" has an unexpected type — Coucou has not touched it."
            ])
        }
        let base = hookBase()
        // Muse uses PascalCase events. Timeouts in milliseconds (seconds × 1000).
        let events: [(String, Int)] = [
            ("SessionStart",      10),
            ("UserPromptSubmit",   5),
            ("PreToolUse",         5),
            ("PermissionRequest", 120),
            ("PostToolUse",        5),
            ("Stop",               5),
            ("SessionEnd",         3),
        ]
        let isNew = !FileManager.default.fileExists(atPath: Self.museSettingsURL.path)
        var hooks = settings["hooks"] as? [String: Any] ?? [:]
        for (event, timeoutSec) in events {
            if let raw = hooks[event], !(raw is [[String: Any]]) {
                throw NSError(domain: "Coucou", code: 2, userInfo: [
                    NSLocalizedDescriptionKey: "~/.config/muse/settings.json: \"hooks\"[\"\(event)\"] has an unexpected type — Coucou has not touched it."
                ])
            }
            var groups = hooks[event] as? [[String: Any]] ?? []
            groups = removeNbHookEntries(from: groups)
            let hookEntry: [String: Any] = [
                "type": "command",
                "command": "\(base) --agent muse \(event)",
                "timeout": timeoutSec * 1000,
            ]
            groups.append(["matcher": "*", "hooks": [hookEntry]])
            hooks[event] = groups
        }
        settings["hooks"] = hooks
        if isNew { settings["schema_version"] = 1 }
        return try JSONSerialization.data(withJSONObject: settings,
                                         options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])
    }

    private func withoutMuseHooks() throws -> Data {
        var settings = try Self.strictReadJSONObject(at: Self.museSettingsURL,
                                                      label: "~/.config/muse/settings.json")
        if let raw = settings["hooks"], !(raw is [String: Any]) {
            throw NSError(domain: "Coucou", code: 2, userInfo: [
                NSLocalizedDescriptionKey: "~/.config/muse/settings.json: \"hooks\" has an unexpected type — Coucou has not touched it."
            ])
        }
        if var hooks = settings["hooks"] as? [String: Any] {
            for key in hooks.keys {
                if let groups = hooks[key] as? [[String: Any]] {
                    let cleaned = removeNbHookEntries(from: groups)
                    if cleaned.isEmpty { hooks.removeValue(forKey: key) } else { hooks[key] = cleaned }
                }
            }
            if hooks.isEmpty { settings.removeValue(forKey: "hooks") } else { settings["hooks"] = hooks }
        }
        return try JSONSerialization.data(withJSONObject: settings,
                                         options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])
    }

    // MARK: - OpenCode plugin installer

    private var _pendingOpenCodeContent: String?
    private var _pendingOpenCodeFingerprint: String?

    static var openCodePluginURL: URL {
        FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".config/opencode/plugins/coucou.js")
    }

    static func openCodePluginInstalled() -> Bool {
        guard let content = try? String(contentsOf: openCodePluginURL, encoding: .utf8) else { return false }
        return content.contains("nb-hook") && content.contains("opencode")
    }

    private func buildOpenCodePluginContent() -> String {
        let path = Self.hookScriptPath
            .replacingOccurrences(of: "\\", with: "\\\\")
            .replacingOccurrences(of: "'", with: "\\'")
        return """
// Coucou hook plugin for OpenCode — generated by Coucou.app
// Forwards every event to the Coucou notch (fire-and-forget, never blocks).
import { spawn } from 'node:child_process';

const HOOK = '\(path)';
const EVENT_MAP = {
  'session.created': 'SessionStart',
  'session.idle': 'Stop',
  'session.error': 'StopFailure',
  'session.deleted': 'SessionEnd',
  'permission.asked': 'PermissionRequest',
};

function forward(hook_event_name, payload) {
  const p = spawn('/bin/sh', [HOOK, '--agent', 'opencode'],
                  { stdio: ['pipe', 'ignore', 'ignore'], detached: true });
  p.on('error', () => {});
  p.stdin.on('error', () => {});
  p.stdin.write(JSON.stringify({ hook_event_name, ...payload }) + '\\n');
  p.stdin.end();
  p.unref();
}

export const CoucouPlugin = async (_ctx) => ({
  event: async ({ event }) => {
    const hook_event_name = EVENT_MAP[event.type];
    if (!hook_event_name) return;
    const props = event.properties || {};
    const payload = {
      session_id: event.sessionID || event.session_id || props.sessionID || props.session_id || '',
      cwd: event.cwd || event.directory || props.cwd || props.directory || '',
    };
    if (typeof props.tool === 'string') payload.tool_name = props.tool;
    if (props.input != null) payload.tool_input = props.input;
    forward(hook_event_name, payload);
  },
  'tool.execute.before': async (input) => {
    forward('PreToolUse', {
      session_id: input.sessionID || input.session_id || '',
      cwd: input.cwd || '',
      tool_name: typeof input.tool === 'string' ? input.tool : '',
      tool_input: input.input ?? null,
    });
  },
  'tool.execute.after': async (input, _output) => {
    forward('PostToolUse', {
      session_id: input.sessionID || input.session_id || '',
      cwd: input.cwd || '',
      tool_name: typeof input.tool === 'string' ? input.tool : '',
    });
  },
});
"""
    }

    func previewOpenCodePlugin(install: Bool) throws -> String {
        let url = Self.openCodePluginURL
        let exists = FileManager.default.fileExists(atPath: url.path)
        if !install {
            guard exists else {
                throw NSError(domain: "CoucouNoop", code: 0, userInfo: [
                    NSLocalizedDescriptionKey: "No OpenCode plugin to remove."
                ])
            }
            let current = (try? Data(contentsOf: url)) ?? Data()
            _pendingOpenCodeFingerprint = sha256Hex(current)
            _pendingOpenCodeContent = nil
            return "(will delete \(url.path))"
        }
        let current = exists ? (try? Data(contentsOf: url)) ?? Data() : Data()
        _pendingOpenCodeFingerprint = sha256Hex(current)
        let content = buildOpenCodePluginContent()
        _pendingOpenCodeContent = content
        return content
    }

    func writeOpenCodePlugin() throws {
        guard let fp = _pendingOpenCodeFingerprint else { return }
        let url = Self.openCodePluginURL
        let current = (try? Data(contentsOf: url)) ?? Data()
        guard sha256Hex(current) == fp else {
            throw NSError(domain: "Coucou", code: 1, userInfo: [
                NSLocalizedDescriptionKey: "~/.config/opencode/plugins/coucou.js changed since preview. Refresh and try again."
            ])
        }
        guard let content = _pendingOpenCodeContent else {
            // Uninstall path: checked by removeOpenCodePlugin
            return
        }
        let fm = FileManager.default
        if fm.fileExists(atPath: url.path) {
            let fmt = DateFormatter()
            fmt.locale = Locale(identifier: "en_US_POSIX")
            fmt.dateFormat = "yyyyMMdd-HHmmss"
            let backupURL = url.deletingLastPathComponent()
                .appendingPathComponent("coucou.js.bak-\(fmt.string(from: Date()))")
            try fm.copyItem(at: url, to: backupURL)
        }
        try fm.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
        try content.write(to: url, atomically: true, encoding: .utf8)
        _pendingOpenCodeContent = nil
        _pendingOpenCodeFingerprint = nil
    }

    func removeOpenCodePlugin() throws {
        let url = Self.openCodePluginURL
        guard FileManager.default.fileExists(atPath: url.path) else { return }
        let content = (try? String(contentsOf: url, encoding: .utf8)) ?? ""
        guard content.contains("generated by Coucou") else {
            throw NSError(domain: "Coucou", code: 3, userInfo: [
                NSLocalizedDescriptionKey: "~/.config/opencode/plugins/coucou.js was not generated by Coucou — not deleting it."
            ])
        }
        try FileManager.default.removeItem(at: url)
    }

    // MARK: - Amp plugin installer

    private var _pendingAmpContent: String?
    private var _pendingAmpFingerprint: String?

    static var ampPluginURL: URL {
        FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".config/amp/plugins/coucou.ts")
    }

    static func ampPluginInstalled() -> Bool {
        guard let content = try? String(contentsOf: ampPluginURL, encoding: .utf8) else { return false }
        return content.contains("nb-hook") && content.contains("'amp'")
    }

    private func buildAmpPluginContent() -> String {
        let path = Self.hookScriptPath
            .replacingOccurrences(of: "\\", with: "\\\\")
            .replacingOccurrences(of: "'", with: "\\'")
        return """
// Coucou hook plugin for Amp — generated by Coucou.app
// Forwards every event to the Coucou notch (display only, never blocks).
import { spawn } from 'node:child_process';

const HOOK = '\(path)';

function forward(event_name: string, fields: Record<string, unknown>): void {
  const payload = JSON.stringify({ hook_event_name: event_name, ...fields });
  const p = spawn('/bin/sh', [HOOK, '--agent', 'amp'],
                  { stdio: ['pipe', 'ignore', 'ignore'], detached: true });
  p.on('error', () => {});
  (p.stdin as import('node:stream').Writable).on('error', () => {});
  (p.stdin as import('node:stream').Writable).write(payload + '\\n');
  (p.stdin as import('node:stream').Writable).end();
  p.unref();
}

export default function (amp: any): void {
  amp.on('session.start', (e: any) => { forward('SessionStart',     { session_id: e.thread?.id ?? '' }); });
  amp.on('agent.start',   (e: any) => { forward('UserPromptSubmit', { session_id: e.thread?.id ?? '' }); });
  amp.on('tool.call',     (e: any) => { try { forward('PreToolUse', { session_id: e.thread?.id ?? '', tool_name: typeof e.tool === 'string' ? e.tool : '' }); } finally { return { action: 'allow' }; } });
  amp.on('tool.result',   (e: any) => { forward('PostToolUse',      { session_id: e.thread?.id ?? '' }); });
  amp.on('agent.end',     (e: any) => { forward('Stop',             { session_id: e.thread?.id ?? '' }); });
}
"""
    }

    func previewAmpPlugin(install: Bool) throws -> String {
        let url = Self.ampPluginURL
        let exists = FileManager.default.fileExists(atPath: url.path)
        if !install {
            guard exists else {
                throw NSError(domain: "CoucouNoop", code: 0, userInfo: [
                    NSLocalizedDescriptionKey: "No Amp plugin to remove."
                ])
            }
            let current = (try? Data(contentsOf: url)) ?? Data()
            _pendingAmpFingerprint = sha256Hex(current)
            _pendingAmpContent = nil
            return "(will delete \(url.path))"
        }
        let current = exists ? (try? Data(contentsOf: url)) ?? Data() : Data()
        _pendingAmpFingerprint = sha256Hex(current)
        let content = buildAmpPluginContent()
        _pendingAmpContent = content
        return content
    }

    func writeAmpPlugin() throws {
        guard let fp = _pendingAmpFingerprint else { return }
        let url = Self.ampPluginURL
        let current = (try? Data(contentsOf: url)) ?? Data()
        guard sha256Hex(current) == fp else {
            throw NSError(domain: "Coucou", code: 1, userInfo: [
                NSLocalizedDescriptionKey: "~/.config/amp/plugins/coucou.ts changed since preview. Refresh and try again."
            ])
        }
        guard let content = _pendingAmpContent else {
            // Uninstall path: checked by removeAmpPlugin
            return
        }
        let fm = FileManager.default
        if fm.fileExists(atPath: url.path) {
            let fmt = DateFormatter()
            fmt.locale = Locale(identifier: "en_US_POSIX")
            fmt.dateFormat = "yyyyMMdd-HHmmss"
            let backupURL = url.deletingLastPathComponent()
                .appendingPathComponent("coucou.ts.bak-\(fmt.string(from: Date()))")
            try fm.copyItem(at: url, to: backupURL)
        }
        try fm.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
        try content.write(to: url, atomically: true, encoding: .utf8)
        _pendingAmpContent = nil
        _pendingAmpFingerprint = nil
    }

    func removeAmpPlugin() throws {
        let url = Self.ampPluginURL
        guard FileManager.default.fileExists(atPath: url.path) else { return }
        let content = (try? String(contentsOf: url, encoding: .utf8)) ?? ""
        guard content.contains("generated by Coucou") else {
            throw NSError(domain: "Coucou", code: 3, userInfo: [
                NSLocalizedDescriptionKey: "~/.config/amp/plugins/coucou.ts was not generated by Coucou — not deleting it."
            ])
        }
        try FileManager.default.removeItem(at: url)
    }

    // MARK: - Hermes plugin installer

    private var _pendingHermesPluginContent: String?
    private var _pendingHermesPluginFingerprint: String?
    private var _pendingHermesConfigContent: String?
    private var _pendingHermesConfigFingerprint: String?

    static var hermesPluginDir: URL {
        FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent(".hermes/plugins/coucou")
    }
    static var hermesInitPyURL: URL { hermesPluginDir.appendingPathComponent("__init__.py") }
    static var hermesPluginYamlURL: URL { hermesPluginDir.appendingPathComponent("plugin.yaml") }
    static var hermesConfigURL: URL {
        FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".hermes/config.yaml")
    }

    static func hermesPluginInstalled() -> Bool {
        guard let content = try? String(contentsOf: hermesInitPyURL, encoding: .utf8) else { return false }
        return content.contains("nb-hook") && content.contains("hermes")
    }

    /// Returns true if the installed Hermes version exposes register_approval_transport.
    /// Runs a quick python3 import check; returns false on any error or if hermes is not installed.
    /// Finds the `hermes` executable in PATH and common install locations.
    private static func hermesExecutablePath() -> String? {
        // Try PATH via `which` first
        let which = Process()
        which.executableURL = URL(fileURLWithPath: "/usr/bin/which")
        which.arguments = ["hermes"]
        let pipe = Pipe()
        which.standardOutput = pipe
        which.standardError  = Pipe()
        if (try? which.run()) != nil {
            which.waitUntilExit()
            if which.terminationStatus == 0 {
                let out = String(data: pipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8)?
                    .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
                if !out.isEmpty && FileManager.default.isExecutableFile(atPath: out) { return out }
            }
        }
        // Explicit common locations
        let home = FileManager.default.homeDirectoryForCurrentUser.path
        for candidate in [
            "\(home)/.local/bin/hermes",
            "\(home)/.hermes/bin/hermes",
            "/usr/local/bin/hermes",
            "/opt/homebrew/bin/hermes",
        ] {
            if FileManager.default.isExecutableFile(atPath: candidate) { return candidate }
        }
        return nil
    }

    /// Reads the shebang of `executablePath` and returns the interpreter path.
    /// Handles `#!/usr/bin/env python3` by resolving via `which`.
    private static func interpreterFromShebang(_ executablePath: String) -> String? {
        guard let fh = FileHandle(forReadingAtPath: executablePath) else { return nil }
        let data = fh.readData(ofLength: 512)
        try? fh.close()
        guard let text = String(data: data, encoding: .utf8),
              text.hasPrefix("#!") else { return nil }
        let line = String(text.prefix(while: { $0 != "\n" }).dropFirst(2))
            .trimmingCharacters(in: .whitespaces)
        if line.hasPrefix("/usr/bin/env ") {
            let name = String(line.dropFirst("/usr/bin/env ".count))
                .trimmingCharacters(in: .whitespaces)
            let task = Process(); let pipe = Pipe()
            task.executableURL = URL(fileURLWithPath: "/usr/bin/which")
            task.arguments = [name]; task.standardOutput = pipe; task.standardError = Pipe()
            if (try? task.run()) != nil {
                task.waitUntilExit()
                let out = String(data: pipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8)?
                    .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
                return out.isEmpty ? nil : out
            }
            return nil
        }
        return line.isEmpty ? nil : line
    }

    /// Returns true if the installed Hermes version exposes register_approval_transport.
    /// Finds the hermes binary, reads its shebang to get the right interpreter (never uses
    /// system python3), and runs an import check with a 3-second timeout.
    /// Returns false if hermes/interpreter not found, or import fails.
    #if !APPSTORE
    static func hermesSupportsApprovalTransport() -> Bool {
        guard let hermesPath = hermesExecutablePath(),
              let pythonPath = interpreterFromShebang(hermesPath),
              FileManager.default.isExecutableFile(atPath: pythonPath) else { return false }
        let task = Process()
        task.executableURL = URL(fileURLWithPath: pythonPath)
        task.arguments     = ["-c", "from hermes_cli.approval_transport import ApprovalRequest"]
        task.standardOutput = Pipe(); task.standardError = Pipe()
        do { try task.run() } catch { return false }
        // Wait up to 3 seconds
        let group = DispatchGroup(); group.enter()
        var exited = false
        DispatchQueue.global(qos: .background).async { task.waitUntilExit(); exited = true; group.leave() }
        if group.wait(timeout: .now() + 3) == .timedOut { task.terminate(); return false }
        return task.terminationStatus == 0
    }
    #endif

    private func buildHermesInitPy() -> String {
        let path = Self.hookScriptPath
            .replacingOccurrences(of: "\\", with: "\\\\")
            .replacingOccurrences(of: "'", with: "\\'")
        return """
# Coucou hook plugin for Hermes Agent — generated by Coucou.app
# Session/tool events → Coucou notch (fire-and-forget, never blocks).
# Approval transport: uses register_approval_transport when available (future Hermes),
# falls back to pre_approval_request observer-only hook (hermes 0.15.x).
import json, subprocess, threading
from pathlib import Path

HOOK = Path('\(path)')
_lock = threading.Lock()
# Maps session_id → metadata dict. Keeps correct session when multiple
# sessions run concurrently (gateway mode). _current_session_id is kept as
# a last-seen fallback for hooks that don't supply a session_id.
_sessions: dict = {}
_current_session_id = ''


def _fire(fields: dict) -> None:
    \"\"\"Non-blocking: spawn nb-hook and return immediately. Reaps child to avoid zombies.\"\"\"
    def _run() -> None:
        try:
            p = subprocess.Popen(
                [str(HOOK), '--agent', 'hermes'],
                stdin=subprocess.PIPE,
                stdout=subprocess.DEVNULL,
                stderr=subprocess.DEVNULL,
                start_new_session=True,   # detach from process group
            )
            p.stdin.write(json.dumps(fields).encode() + b'\\n')
            p.stdin.close()
            p.wait(timeout=5)             # reap; 5s >> the 0.3s socket timeout
        except Exception:
            pass
    threading.Thread(target=_run, daemon=True).start()


def register(ctx) -> None:
    def on_session_start(**kwargs) -> None:
        global _current_session_id
        sid = kwargs.get('session_id', '')
        meta = {
            'model': kwargs.get('model', ''),
            'platform': kwargs.get('platform', 'cli') or 'cli',
        }
        with _lock:
            _sessions[sid] = meta
            _current_session_id = sid
        _fire({'hook_event_name': 'SessionStart', 'session_id': sid, 'platform': meta['platform']})

    def on_session_end(**kwargs) -> None:
        sid = kwargs.get('session_id', '')
        with _lock:
            _sessions.pop(sid, None)
        # Stop is sent by post_llm_call (which has the last assistant message).
        # Only send StopFailure here when the session was interrupted abnormally.
        if kwargs.get('interrupted'):
            _fire({'hook_event_name': 'StopFailure', 'session_id': sid})

    def post_llm_call(**kwargs) -> None:
        sid = kwargs.get('session_id', '') or _current_session_id
        response = kwargs.get('assistant_response', '')
        _fire({
            'hook_event_name': 'Stop',
            'session_id': sid,
            'last_assistant_message': response,
        })

    def pre_tool_call(**kwargs) -> None:
        sid = kwargs.get('session_id', '') or _current_session_id
        _fire({
            'hook_event_name': 'PreToolUse',
            'session_id': sid,
            'tool_name': kwargs.get('tool_name', ''),
            'tool_input': kwargs.get('args') or {},
        })

    def post_tool_call(**kwargs) -> None:
        sid = kwargs.get('session_id', '') or _current_session_id
        _fire({
            'hook_event_name': 'PostToolUse',
            'session_id': sid,
            'tool_name': kwargs.get('tool_name', ''),
        })

    ctx.register_hook('on_session_start', on_session_start)
    ctx.register_hook('on_session_end',   on_session_end)
    ctx.register_hook('post_llm_call',    post_llm_call)
    ctx.register_hook('pre_tool_call',    pre_tool_call)
    ctx.register_hook('post_tool_call',   post_tool_call)

    if hasattr(ctx, 'register_approval_transport'):
        # Hermes version supports transport API — Coucou shows a real Allow/Deny card
        # and returns the user's choice to Hermes.
        def _present(request) -> object:
            sid = (getattr(request, 'session_id', None)
                   or getattr(request, 'session_key', None)
                   or _current_session_id)
            cmd     = getattr(request, 'command', '')
            desc    = getattr(request, 'description', '')
            timeout = getattr(request, 'timeout_seconds',
                              getattr(request, 'timeout', 30.0))
            allowed = list(getattr(request, 'allowed_choices', ('once', 'deny')))

            payload = json.dumps({
                'hook_event_name': 'PermissionRequest',
                'session_id': sid,
                'coucou_agent': 'hermes',
                'coucou_has_transport': True,
                'tool_name': cmd,
                'tool_input': {'command': cmd, 'description': desc},
            }).encode()
            try:
                result = subprocess.run(
                    [str(HOOK), '--agent', 'hermes'],
                    input=payload,
                    capture_output=True,
                    timeout=max(1.0, float(timeout) - 2.0),
                )
                data   = json.loads(result.stdout)
                choice = data['choice']
                if choice not in allowed:
                    raise ValueError(f'invalid choice: {choice!r}')
                return request.respond(choice)
            except Exception:
                # Fall back to Hermes' native prompt on any error.
                return request.respond('deny')

        ctx.register_approval_transport('coucou', _present)
    else:
        # Observer-only hook (hermes 0.15.x): Hermes still controls the decision.
        # Fire a PreToolUse-style step so the notch shows "⏳ Approval pending in Hermes"
        # in the step list without displaying a fake Allow/Deny card.
        def pre_approval_request(**kwargs) -> None:
            sid = kwargs.get('session_key', '') or _current_session_id
            _fire({
                'hook_event_name': 'PreToolUse',
                'session_id': sid,
                'tool_name': '⏳ Approval pending in Hermes',
                'tool_input': {
                    'command': kwargs.get('command', ''),
                    'description': kwargs.get('description', ''),
                },
            })

        ctx.register_hook('pre_approval_request', pre_approval_request)
"""
    }

    private static let hermesPluginYaml = """
name: coucou
version: "1.0"
description: Coucou notch integration — generated by Coucou.app
"""

    /// Merges Coucou keys into a Hermes config.yaml string without touching other settings.
    ///
    /// Returns the merged YAML string, or nil if the file uses an unsupported structure
    /// (flow maps `{…}`, YAML anchors `&`, multi-document `---`) that the line-level
    /// merger cannot safely handle. Callers should surface an error with the lines
    /// the user needs to add manually.
    ///
    /// Plugin enablement (plugins.enabled) is handled by the `hermes plugins enable/disable`
    /// CLI after the plugin files are written; this function only manages security.approval.
    static func mergedHermesConfig(_ base: String, enableApprovals: Bool) -> String? {
        // Reject structures the simple merger cannot handle safely.
        // Flow maps, anchors, and multi-document markers require a full YAML parser.
        let unsafePatterns = ["{", " &", "\n---"]
        for p in unsafePatterns where base.contains(p) {
            return nil
        }

        var lines = base.components(separatedBy: "\n")

        // Detect file indentation: look for the first indented line and count spaces.
        let indent: Int = {
            for line in lines {
                let leading = line.prefix(while: { $0 == " " }).count
                if leading > 0 && leading <= 8 { return leading }
            }
            return 2  // default
        }()
        let ind  = String(repeating: " ", count: indent)         // e.g. "  " (2) or "    " (4)
        let ind2 = String(repeating: " ", count: indent * 2)     // one extra level

        // Returns the index of the first top-level section header line matching `key`.
        // Top-level = no leading spaces, ends with `:` (optionally with trailing space/comment).
        func topLevelIndex(key: String) -> Int? {
            lines.firstIndex { line in
                let t = line.trimmingCharacters(in: .whitespaces)
                guard !line.hasPrefix(" ") && !line.hasPrefix("\t") else { return false }
                return t == "\(key):" || t.hasPrefix("\(key):")
            }
        }

        // Returns the range of lines that belong to a top-level section (from its header to
        // just before the next top-level section, or the end of the array).
        func sectionRange(from sectionIdx: Int) -> Range<Int> {
            var end = sectionIdx + 1
            while end < lines.count {
                let l = lines[end]
                // A new top-level key: not blank, not a comment, no leading whitespace
                if !l.isEmpty && !l.hasPrefix("#") && !l.hasPrefix(" ") && !l.hasPrefix("\t") {
                    break
                }
                end += 1
            }
            return sectionIdx ..< end
        }

        // --- security.approval ---
        let transportLine = "\(ind2)transport: coucou"
        let fallbackLine  = "\(ind2)transport_fallback: builtin"

        func ensureApprovalTransport() {
            if let secIdx = topLevelIndex(key: "security") {
                let secRange = sectionRange(from: secIdx)
                // Look for approval: within the security section (must be indented)
                if let approvalIdx = (secRange.lowerBound + 1 ..< secRange.upperBound)
                    .first(where: { lines[$0].trimmingCharacters(in: .whitespaces).hasPrefix("approval:") }) {
                    // approval: block exists — update or add transport keys within it
                    let approvalRange = sectionRange(from: approvalIdx)
                    var hasTransport = false
                    var hasFallback  = false
                    for i in (approvalRange.lowerBound + 1 ..< approvalRange.upperBound) {
                        let t = lines[i].trimmingCharacters(in: .whitespaces)
                        if t.hasPrefix("transport:") && !t.hasPrefix("transport_fallback") {
                            lines[i] = transportLine; hasTransport = true
                        } else if t.hasPrefix("transport_fallback:") {
                            lines[i] = fallbackLine; hasFallback = true
                        }
                    }
                    let insertAt = approvalRange.lowerBound + 1
                    if !hasFallback  { lines.insert(fallbackLine,  at: insertAt) }
                    if !hasTransport { lines.insert(transportLine, at: insertAt) }
                } else {
                    // No approval: key — insert right after security:
                    let insertAt = secIdx + 1
                    lines.insert("\(ind)approval:", at: insertAt)
                    lines.insert(transportLine,     at: insertAt + 1)
                    lines.insert(fallbackLine,      at: insertAt + 2)
                }
            } else {
                // No security: section — append
                if lines.last != "" { lines.append("") }
                lines.append("security:")
                lines.append("\(ind)approval:")
                lines.append(transportLine)
                lines.append(fallbackLine)
            }
        }

        func removeApprovalTransport() {
            // Only remove exact Coucou-written transport keys; don't touch unrelated keys.
            lines.removeAll { line in
                let t = line.trimmingCharacters(in: .whitespaces)
                return t == "transport: coucou" || t == "transport_fallback: builtin"
            }
        }

        // --- plugins.enabled ---
        // Note: actual plugin enable/disable is done via `hermes plugins enable/disable coucou`
        // CLI after writing/removing the plugin files. This block ensures the preview
        // shows the complete intended state of config.yaml.
        func ensureCoucouPlugin() {
            // "Already present" = coucou in the plugins.enabled list specifically.
            // Check by finding plugins: section first, then enabled: sub-key within it.
            if let pluginsIdx = topLevelIndex(key: "plugins") {
                let pluginsRange = sectionRange(from: pluginsIdx)
                // Find enabled: within the plugins section
                if let enabledIdx = (pluginsRange.lowerBound + 1 ..< pluginsRange.upperBound)
                    .first(where: { lines[$0].trimmingCharacters(in: .whitespaces).hasPrefix("enabled:") }) {
                    let enabledLine = lines[enabledIdx]
                    let trimmed = enabledLine.trimmingCharacters(in: .whitespaces)
                    if trimmed.contains("[") && trimmed.contains("]") {
                        // Inline list: enabled: [x, y]  or  enabled: []
                        if trimmed.contains("coucou") { return }   // already present
                        if trimmed == "enabled: []" || trimmed == "enabled:[]" {
                            // Empty inline list → expand to block entry
                            let prefix = enabledLine.prefix(while: { $0 == " " })
                            lines[enabledIdx] = "\(prefix)enabled:"
                            lines.insert("\(prefix)\(ind)- coucou", at: enabledIdx + 1)
                        } else {
                            lines[enabledIdx] = enabledLine.replacingOccurrences(of: "]", with: ", coucou]")
                        }
                    } else {
                        // Block list — check if coucou is already a child of this enabled:
                        let enabledRange = sectionRange(from: enabledIdx)
                        let alreadyPresent = (enabledRange.lowerBound + 1 ..< enabledRange.upperBound)
                            .contains { lines[$0].trimmingCharacters(in: .whitespaces) == "- coucou" }
                        if alreadyPresent { return }
                        // Insert after enabled:
                        let prefix = enabledLine.prefix(while: { $0 == " " })
                        lines.insert("\(prefix)\(ind)- coucou", at: enabledIdx + 1)
                    }
                } else {
                    // No enabled: key under plugins: — insert after plugins:
                    lines.insert("\(ind)enabled:", at: pluginsIdx + 1)
                    lines.insert("\(ind)\(ind)- coucou", at: pluginsIdx + 2)
                }
            } else {
                // No plugins: section — append
                if lines.last != "" { lines.append("") }
                lines.append("plugins:")
                lines.append("\(ind)enabled:")
                lines.append("\(ind)\(ind)- coucou")
            }
        }

        func removeCoucouPlugin() {
            // Remove the `- coucou` entry from plugins.enabled only.
            // If that leaves enabled: with no entries, leave the key in place (don't remove it).
            guard let pluginsIdx = topLevelIndex(key: "plugins") else { return }
            let pluginsRange = sectionRange(from: pluginsIdx)
            guard let enabledIdx = (pluginsRange.lowerBound + 1 ..< pluginsRange.upperBound)
                .first(where: { lines[$0].trimmingCharacters(in: .whitespaces).hasPrefix("enabled:") })
            else { return }
            let enabledLine = lines[enabledIdx]
            let trimmed = enabledLine.trimmingCharacters(in: .whitespaces)
            if trimmed.contains("[") && trimmed.contains("]") {
                // Inline list: remove coucou from it
                let cleaned = trimmed
                    .replacingOccurrences(of: ", coucou", with: "")
                    .replacingOccurrences(of: "coucou, ", with: "")
                    .replacingOccurrences(of: "coucou",   with: "")
                let prefix = enabledLine.prefix(while: { $0 == " " })
                lines[enabledIdx] = "\(prefix)\(cleaned)"
            } else {
                // Block list: remove the `- coucou` entry
                let enabledRange = sectionRange(from: enabledIdx)
                // Collect indices to remove first, then remove in reverse to preserve indices.
                let toRemove = (enabledRange.lowerBound + 1 ..< enabledRange.upperBound)
                    .filter { lines[$0].trimmingCharacters(in: .whitespaces) == "- coucou" }
                for i in toRemove.reversed() { lines.remove(at: i) }
            }
        }

        ensureCoucouPlugin()
        if enableApprovals { ensureApprovalTransport() } else { removeApprovalTransport() }
        return lines.joined(separator: "\n")
    }

    func previewHermesPlugin(install: Bool) throws -> String {
        if !install {
            guard FileManager.default.fileExists(atPath: Self.hermesInitPyURL.path) else {
                throw NSError(domain: "CoucouNoop", code: 0, userInfo: [
                    NSLocalizedDescriptionKey: "No Hermes plugin to remove."
                ])
            }
            let current = (try? Data(contentsOf: Self.hermesInitPyURL)) ?? Data()
            _pendingHermesPluginFingerprint = sha256Hex(current)
            _pendingHermesPluginContent = nil
            return "(will delete \(Self.hermesInitPyURL.path))"
        }
        let current = (try? Data(contentsOf: Self.hermesInitPyURL)) ?? Data()
        _pendingHermesPluginFingerprint = sha256Hex(current)
        let content = buildHermesInitPy()
        _pendingHermesPluginContent = content
        return content
    }

    func writeHermesPlugin() throws {
        guard let fp = _pendingHermesPluginFingerprint else { return }
        let url = Self.hermesInitPyURL
        let current = (try? Data(contentsOf: url)) ?? Data()
        guard sha256Hex(current) == fp else {
            throw NSError(domain: "Coucou", code: 1, userInfo: [
                NSLocalizedDescriptionKey: "~/.hermes/plugins/coucou/__init__.py changed since preview. Refresh and try again."
            ])
        }
        let fm = FileManager.default
        if let content = _pendingHermesPluginContent {
            try fm.createDirectory(at: Self.hermesPluginDir, withIntermediateDirectories: true)
            if fm.fileExists(atPath: url.path) {
                let fmt = DateFormatter()
                fmt.locale = Locale(identifier: "en_US_POSIX")
                fmt.dateFormat = "yyyyMMdd-HHmmss"
                let bak = url.deletingLastPathComponent()
                    .appendingPathComponent("__init__.py.bak-\(fmt.string(from: Date()))")
                try fm.copyItem(at: url, to: bak)
            }
            try content.write(to: url, atomically: true, encoding: .utf8)
            try Self.hermesPluginYaml.write(to: Self.hermesPluginYamlURL, atomically: true, encoding: .utf8)
            // Register the plugin with the Hermes CLI so it appears in plugins.enabled.
            // Best-effort — silently ignored if hermes is not on PATH.
            try? Self.runHermesCLI(["plugins", "enable", "coucou"])
        }
        _pendingHermesPluginContent = nil
        _pendingHermesPluginFingerprint = nil
    }

    func removeHermesPlugin() throws {
        let url = Self.hermesInitPyURL
        guard FileManager.default.fileExists(atPath: url.path) else { return }
        let content = (try? String(contentsOf: url, encoding: .utf8)) ?? ""
        guard content.contains("generated by Coucou") else {
            throw NSError(domain: "Coucou", code: 3, userInfo: [
                NSLocalizedDescriptionKey: "~/.hermes/plugins/coucou/__init__.py was not generated by Coucou — not deleting it."
            ])
        }
        // Remove from hermes plugins.enabled first, then delete the files.
        // Best-effort — silently ignored if hermes is not on PATH.
        try? Self.runHermesCLI(["plugins", "disable", "coucou"])
        try FileManager.default.removeItem(at: Self.hermesPluginDir)
    }

    /// Invoke the Hermes CLI with the given arguments.
    /// Searches standard PATH locations for the `hermes` binary.
    @discardableResult
    private static func runHermesCLI(_ args: [String]) throws -> String {
        let hermesPaths = [
            "/opt/homebrew/bin/hermes",
            "/usr/local/bin/hermes",
            "/usr/bin/hermes",
            (ProcessInfo.processInfo.environment["HOME"] ?? "") + "/.local/bin/hermes",
        ]
        guard let hermesBin = hermesPaths.first(where: { FileManager.default.fileExists(atPath: $0) }) else {
            throw NSError(domain: "CoucouNoop", code: 0, userInfo: [
                NSLocalizedDescriptionKey: "hermes CLI not found."
            ])
        }
        let proc = Process()
        proc.executableURL = URL(fileURLWithPath: hermesBin)
        proc.arguments = args
        let out = Pipe()
        proc.standardOutput = out
        proc.standardError  = Pipe()   // discard stderr
        try proc.run()
        proc.waitUntilExit()
        return String(data: out.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? ""
    }

    func previewHermesConfig(enableApprovals: Bool, supportsTransport: Bool) throws -> String {
        let base = (try? String(contentsOf: Self.hermesConfigURL, encoding: .utf8)) ?? ""
        let current = (try? Data(contentsOf: Self.hermesConfigURL)) ?? Data()
        _pendingHermesConfigFingerprint = sha256Hex(current)
        let effectiveApprovals = enableApprovals && supportsTransport
        guard let merged = Self.mergedHermesConfig(base, enableApprovals: effectiveApprovals) else {
            _pendingHermesConfigContent = nil
            throw NSError(domain: "Coucou", code: 4, userInfo: [
                NSLocalizedDescriptionKey: "~/.hermes/config.yaml uses an unsupported structure (flow maps, YAML anchors, or multi-document). Edit it manually and add:\n  security:\n    approval:\n      transport: coucou\n      transport_fallback: builtin"
            ])
        }
        _pendingHermesConfigContent = merged
        return merged
    }

    func writeHermesConfig() throws {
        guard let fp = _pendingHermesConfigFingerprint,
              let content = _pendingHermesConfigContent else { return }
        let url = Self.hermesConfigURL
        let current = (try? Data(contentsOf: url)) ?? Data()
        guard sha256Hex(current) == fp else {
            throw NSError(domain: "Coucou", code: 1, userInfo: [
                NSLocalizedDescriptionKey: "~/.hermes/config.yaml changed since preview. Refresh and try again."
            ])
        }
        let fm = FileManager.default
        if fm.fileExists(atPath: url.path) {
            let fmt = DateFormatter()
            fmt.locale = Locale(identifier: "en_US_POSIX")
            fmt.dateFormat = "yyyyMMdd-HHmmss"
            let bak = url.deletingLastPathComponent()
                .appendingPathComponent("config.yaml.bak-\(fmt.string(from: Date()))")
            try fm.copyItem(at: url, to: bak)
        }
        try fm.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
        try content.write(to: url, atomically: true, encoding: .utf8)
        _pendingHermesConfigContent = nil
        _pendingHermesConfigFingerprint = nil
    }

    // MARK: SHA-256 fingerprint

    private func sha256Hex(_ data: Data) -> String {
        SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
    }
    #endif
}

// MARK: - Notification names for hook server → controller communication

extension Notification.Name {
    static let hookExpand = Notification.Name("notchBuddy.hookExpand")
}

// MARK: - nb-hook shell wrapper (same for both GitHub and App Store)
// Invoked by Claude Code via /bin/sh or directly via shebang.
// Always exits 0 — never blocks Claude Code.
// On macOS, checks xcode-select before running python3 to avoid triggering the
// "install developer tools" dialog on machines without Xcode CLI tools.
// Elsewhere (the hook copied to a Linux machine reached over SSH, docs/REMOTE.md)
// it runs the python3 found in PATH.

private let nbHookShellWrapper = """
#!/bin/sh
# Coucou hook relay — always exits 0, never blocks Claude Code
HOOK_DIR="$(dirname "$0")"
PY=""
if [ "$(uname -s)" = "Darwin" ]; then
    xcode-select -p >/dev/null 2>&1 && PY=/usr/bin/python3
else
    PY=$(command -v python3 2>/dev/null)
fi
out=""
if [ -n "$PY" ]; then
    out=$("$PY" "$HOOK_DIR/nb-hook.py" "$@" 2>/dev/null)
    rc=$?
    if [ "$rc" -ne 0 ] || [ -z "$out" ]; then
        out=""
    fi
fi
if [ -n "$out" ]; then
    printf '%s\\n' "$out"
else
    # Copilot is fail-closed — must always output valid JSON even when python3 is absent or crashes.
    _cop=0; _perm=0
    for _a in "$@"; do
        case "$_a" in
            copilot) _cop=1 ;;
            permissionRequest|PermissionRequest) _perm=1 ;;
        esac
    done
    if [ "$_cop" -eq 1 ]; then
        if [ "$_perm" -eq 1 ]; then
            printf '{"permissionDecision":"ask"}\\n'
        else
            printf '{}\\n'
        fi
    fi
fi
exit 0
"""

// MARK: - nb-hook Python relay (GitHub / non-sandboxed version)

private let nbHookPythonGitHub = """
#!/usr/bin/env python3
# nb-hook.py — Coucou hook relay for Claude Code and third-party agents (GitHub version)
# Reads JSON from stdin, forwards to Coucou via Unix socket, translates response.
import sys, json, os, socket

def normalize_event(name):
    mapping = {
        'BeforeTool': 'PreToolUse', 'BeforeToolSelection': 'PreToolUse',
        'AfterTool': 'PostToolUse', 'AfterModel': 'PostToolUse',
        'BeforeAgent': 'UserPromptSubmit', 'AfterAgent': 'Stop',
        'startup': 'SessionStart', 'exit': 'SessionEnd',
        'PreInvocation': 'UserPromptSubmit', 'PostInvocation': 'PostToolUse',
        'pre_tool_use': 'PreToolUse', 'post_tool_use': 'PostToolUse',
        'user_prompt_submit': 'UserPromptSubmit', 'session_start': 'SessionStart',
        'session_end': 'SessionEnd', 'stop': 'Stop',
        'sessionStart': 'SessionStart', 'userPromptSubmitted': 'UserPromptSubmit',
        'agentStop': 'Stop', 'notification': 'Notification',
        'preToolUse': 'PreToolUse', 'postToolUse': 'PostToolUse',
        'permissionRequest': 'PermissionRequest', 'sessionEnd': 'SessionEnd',
    }
    return mapping.get(name, name)

def normalize_tool_fields(payload):
    if 'tool_name' not in payload:
        # Copilot sends toolName directly; other agents nest in toolCall
        if payload.get('toolName'):
            payload['tool_name'] = payload['toolName']
        else:
            tool = payload.get('toolCall')
            if not isinstance(tool, dict):
                tool = {}
            name = tool.get('name') or payload.get('tool', '')
            if name:
                payload['tool_name'] = name
    if 'tool_input' not in payload:
        # Copilot sends toolArgs directly
        tool_args = payload.get('toolArgs')
        if isinstance(tool_args, dict):
            payload['tool_input'] = tool_args
        else:
            tool = payload.get('toolCall') or {}
            if isinstance(tool.get('args'), dict):
                flat = dict(tool['args'])
                for src, dst in [('CommandLine', 'command'), ('FilePath', 'file_path'),
                                 ('Path', 'path'), ('Url', 'url'), ('Query', 'query'), ('Pattern', 'pattern')]:
                    if src in flat:
                        flat[dst] = flat[src]
                payload['tool_input'] = flat
    if 'session_id' not in payload:
        for k in ['conversationId', 'conversation_id', 'sessionId', 'GEMINI_SESSION_ID']:
            if payload.get(k):
                payload['session_id'] = payload[k]
                break
        if 'session_id' not in payload:
            sid = os.environ.get('GEMINI_SESSION_ID', '')
            if sid:
                payload['session_id'] = sid
    # Copilot sends workdir for the current working directory
    if not payload.get('cwd') and payload.get('workdir'):
        payload['cwd'] = payload['workdir']

def add_session_name(payload):
    # Name the pill after the session's title, else the folder the session started in,
    # not the current cwd (the agent may cd into subfolders). Both come from the
    # transcript: its first lines, and its last custom-title entry (/rename), else its
    # last ai-title one (the title Claude Code gives a session; VS Code sessions only
    # have that). Entries are told by their type: a message that merely quotes one is not
    # a title. Claude Code writes the title again every 40-80 KB, hence a 256 KB tail.
    path = payload.get('transcript_path') or ''
    if not path:
        return
    try:
        with open(path, 'rb') as f:
            for line in f.read(16384).splitlines():
                try:
                    root = json.loads(line).get('cwd')
                except Exception:
                    continue
                if root:
                    payload['session_root'] = root
                    break
            f.seek(0, os.SEEK_END)
            start = max(0, f.tell() - 262144)
            f.seek(start)
            lines = f.read().splitlines()
            ai_title = ''
            for line in reversed(lines[1:] if start else lines):
                if b'"type":"custom-title"' not in line and b'"type":"ai-title"' not in line:
                    continue
                try:
                    entry = json.loads(line)
                except Exception:
                    continue
                if entry.get('type') == 'custom-title' and entry.get('customTitle'):
                    payload['session_title'] = entry['customTitle']
                    return
                if entry.get('type') == 'ai-title' and not ai_title:
                    ai_title = entry.get('aiTitle') or ''
            if ai_title:
                payload['session_title'] = ai_title
    except Exception:
        pass

def term_program(env):
    # VS Code's Claude Code extension on a remote machine (Remote - SSH) has neither
    # TERM_PROGRAM nor the app's bundle ID; its entrypoint still says where it runs.
    term = env.get('TERM_PROGRAM', '')
    if not term and not env.get('__CFBundleIdentifier') and env.get('CLAUDE_CODE_ENTRYPOINT') == 'claude-vscode':
        return 'vscode'
    return term

def main():
    raw = b''
    payload = {}
    try:
        raw = sys.stdin.buffer.read()
        if not raw:
            if '--statusline' not in sys.argv[1:]:
                return
        else:
            payload = json.loads(raw)
    except Exception:
        if '--statusline' not in sys.argv[1:]:
            return

    # COUCOU_SOCKET points the relay at another socket, for instance the one an
    # `ssh -R` tunnel forwards from the Mac to a remote machine (docs/REMOTE.md).
    socket_path = os.path.expanduser(
        os.environ.get('COUCOU_SOCKET') or '~/Library/Application Support/NotchBuddy/nb.sock'
    )

    # --statusline mode: relay rate_limits to Coucou, then delegate to saved previous
    if '--statusline' in sys.argv[1:]:
        relay = {
            'coucou_kind': 'statusline',
            'session_id': payload.get('session_id', ''),
            'rate_limits': payload.get('rate_limits', {}),
        }
        try:
            s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
            s.settimeout(0.3)
            s.connect(socket_path)
            s.sendall((json.dumps(relay) + '\\n').encode())
            s.close()
        except Exception:
            pass
        prev_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'statusline-previous.json')
        if os.path.exists(prev_file):
            try:
                import subprocess
                with open(prev_file) as f:
                    prev = json.load(f)
                cmd = prev.get('command', '')
                if cmd:
                    result = subprocess.run(['/bin/sh', '-c', cmd], input=raw,
                                             capture_output=True, timeout=10)
                    if result.stdout:
                        sys.stdout.buffer.write(result.stdout)
                        sys.stdout.buffer.flush()
            except Exception:
                pass
        return

    # --ask mode: dedicated hook for AskUserQuestion via PreToolUse (Claude Code 2.1.85+)
    if '--ask' in sys.argv[1:]:
        tool = payload.get('tool_name', '')
        if tool != 'AskUserQuestion':
            return  # Not an AskUserQuestion invocation — exit cleanly (no output)
        payload['coucou_kind'] = 'ask_user_question'
        env = os.environ
        payload.setdefault('term_program', term_program(env))
        payload.setdefault('iterm_session_id', env.get('ITERM_SESSION_ID', ''))
        payload.setdefault('term_session_id', env.get('TERM_SESSION_ID', ''))
        payload.setdefault('bundle_id', env.get('__CFBundleIdentifier', ''))
        if 'cwd' not in payload or not payload['cwd']:
            paths = payload.get('workspacePaths') or payload.get('workspace_roots', [])
            if isinstance(paths, list) and paths:
                payload['cwd'] = paths[0]
            else:
                payload['cwd'] = os.getcwd()
        add_session_name(payload)
        try:
            s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
            s.settimeout(125)
            s.connect(socket_path)
            s.sendall((json.dumps(payload) + '\\n').encode())
            chunks = []
            while True:
                chunk = s.recv(4096)
                if not chunk:
                    break
                chunks.append(chunk)
                if b'\\n' in chunk:
                    break
            s.close()
            response = b''.join(chunks).decode().strip()
            if response:
                try:
                    resp_obj = json.loads(response)
                    decision = resp_obj.get('permissionDecision', '')
                except Exception:
                    decision = ''
                if decision == 'answer':
                    answers = resp_obj.get('answers', {})
                    questions = payload.get('tool_input', {}).get('questions', [])
                    out = {'hookSpecificOutput': {'hookEventName': 'PreToolUse', 'permissionDecision': 'allow', 'updatedInput': {'questions': questions, 'answers': answers}}}
                    sys.stdout.write(json.dumps(out) + '\\n')
                    sys.stdout.flush()
                    sys.exit(0)
                # 'ask' or unknown: fall through → no output → Claude Code asks in terminal
        except Exception:
            pass
        return

    # Parse --agent <name> and optional positional event from argv.
    # --agent tags the payload with coucou_agent so the app routes to the right pill.
    # The positional arg is a fallback event name for agents that do not set hook_event_name.
    args = sys.argv[1:]
    agent = ''
    arg_event = ''
    i = 0
    while i < len(args):
        if args[i] == '--agent' and i + 1 < len(args):
            agent = args[i + 1]
            i += 2
        else:
            if not arg_event:
                arg_event = args[i]
            i += 1
    if agent:
        payload.setdefault('coucou_agent', agent)
    # Claude Code sessions from the Claude desktop app (Code tab) report this entrypoint;
    # route them to the Claude Desktop pill instead of dropping them (no VS Code terminal).
    if not payload.get('coucou_agent') and os.environ.get('CLAUDE_CODE_ENTRYPOINT') == 'claude-desktop':
        payload['coucou_agent'] = 'claude-desktop'

    # Enrich with terminal context
    env = os.environ
    payload.setdefault('term_program', term_program(env))
    payload.setdefault('iterm_session_id', env.get('ITERM_SESSION_ID', ''))
    payload.setdefault('term_session_id', env.get('TERM_SESSION_ID', ''))
    payload.setdefault('bundle_id', env.get('__CFBundleIdentifier', ''))
    if 'cwd' not in payload or not payload['cwd']:
        paths = payload.get('workspacePaths') or payload.get('workspace_roots', [])
        if isinstance(paths, list) and paths:
            payload['cwd'] = paths[0]
        else:
            payload['cwd'] = os.getcwd()
    add_session_name(payload)

    # Normalize event name and tool fields (Gemini CLI / Antigravity → canonical names)
    try:
        raw_event = payload.get('hook_event_name', '') or arg_event
        if raw_event:
            payload['hook_event_name'] = normalize_event(raw_event)
        normalize_tool_fields(payload)
    except Exception:
        pass

    event = payload.get('hook_event_name', '')
    # socket_path is already defined above

    if event == 'PermissionRequest':
        # Block and wait for Coucou's decision (Claude Code allows up to 120s)
        try:
            s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
            s.settimeout(118)
            s.connect(socket_path)
            s.sendall((json.dumps(payload) + '\\n').encode())
            chunks = []
            while True:
                chunk = s.recv(4096)
                if not chunk:
                    break
                chunks.append(chunk)
                if b'\\n' in chunk:
                    break
            s.close()
            response = b''.join(chunks).decode().strip()
            if response:
                try:
                    resp_obj = json.loads(response)
                    decision = resp_obj.get('permissionDecision', '')
                except Exception:
                    decision = ''
                if agent == 'hermes':
                    hermes_choice = 'once' if decision == 'allow' else decision
                    if hermes_choice in ('once', 'always', 'deny'):
                        sys.stdout.write(json.dumps({'choice': hermes_choice}) + '\\n')
                        sys.stdout.flush()
                    sys.exit(0)
                if decision in ('allow', 'always'):
                    # Copilot/Muse use {"permissionDecision":"allow"} directly
                    if agent in ('copilot', 'muse'):
                        out = {'permissionDecision': 'allow'}
                    elif decision == 'always' and agent != 'codex':
                        # Let Claude Code persist the rule via updatedPermissions
                        suggestions = payload.get('permission_suggestions', [])
                        out = {'hookSpecificOutput': {'hookEventName': 'PermissionRequest', 'decision': {'behavior': 'allow', 'updatedPermissions': suggestions}}}
                    else:
                        # Claude Code / Codex plain allow
                        out = {'hookSpecificOutput': {'hookEventName': 'PermissionRequest', 'decision': {'behavior': 'allow'}}}
                    # Claude Code ignores an allow for ExitPlanMode without updatedInput (Allow and Always).
                    if payload.get('tool_name') == 'ExitPlanMode' and 'hookSpecificOutput' in out:
                        out['hookSpecificOutput']['decision']['updatedInput'] = payload.get('tool_input', {})
                        # Mode picked on the plan card: same choice as the terminal's plan dialog.
                        mode = resp_obj.get('mode')
                        if mode in ('auto', 'default'):
                            out['hookSpecificOutput']['decision']['updatedPermissions'] = [{'type': 'setMode', 'mode': mode, 'destination': 'session'}]
                    sys.stdout.write(json.dumps(out) + '\\n')
                    sys.stdout.flush()
                    sys.exit(0)
                elif decision == 'deny':
                    if agent in ('copilot', 'muse'):
                        out = {'permissionDecision': 'deny'}
                    else:
                        out = {'hookSpecificOutput': {'hookEventName': 'PermissionRequest', 'decision': {'behavior': 'deny', 'message': 'Denied from Coucou'}}}
                    sys.stdout.write(json.dumps(out) + '\\n')
                    sys.stdout.flush()
                    sys.exit(0)
                elif decision == 'answer':
                    # AskUserQuestion answered from the notch
                    answers = resp_obj.get('answers', {})
                    questions = payload.get('tool_input', {}).get('questions', [])
                    out = {'hookSpecificOutput': {'hookEventName': 'PermissionRequest', 'decision': {'behavior': 'allow', 'updatedInput': {'questions': questions, 'answers': answers}}}}
                    sys.stdout.write(json.dumps(out) + '\\n')
                    sys.stdout.flush()
                    sys.exit(0)
                elif decision == 'change_plan':
                    # Plan card "Change plan": like the terminal's "Tell Claude what to change",
                    # reject the plan and stop Claude so the prompt is free for the change.
                    out = {'hookSpecificOutput': {'hookEventName': 'PermissionRequest', 'decision': {'behavior': 'deny', 'interrupt': True, 'message': 'The user wants to change the plan and will type the changes in the terminal.'}}}
                    sys.stdout.write(json.dumps(out) + '\\n')
                    sys.stdout.flush()
                    sys.exit(0)
                # 'ask' or unknown: fall through → no output → agent re-asks
        except Exception:
            pass
        # App unreachable, timed out, or no explicit decision — print nothing
        # Copilot is fail-closed: must always output valid JSON so it re-asks rather than deny
        # Hermes: no output → json.loads raises in plugin → transport_fallback: builtin activates
        if agent == 'copilot':
            sys.stdout.write('{"permissionDecision":"ask"}\\n')
            sys.stdout.flush()
        sys.exit(0)

    # All other events: fire-and-forget (0.3s timeout, never blocks)
    try:
        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        s.settimeout(0.3)
        s.connect(socket_path)
        s.sendall((json.dumps(payload) + '\\n').encode())
        s.close()
    except Exception:
        pass  # Always exit cleanly — never block the agent

    # Antigravity needs a decision on PreToolUse ({} reads as a denial). "ask" keeps its own
    # permission prompt (and the user's Always Allow); Coucou never allows a tool by itself.
    if agent == 'antigravity' and event == 'PreToolUse':
        sys.stdout.write('{"decision":"ask"}\\n')
        sys.stdout.flush()
    elif agent in ('gemini', 'antigravity', 'muse', 'copilot'):
        sys.stdout.write('{}\\n')
        sys.stdout.flush()

try:
    main()
except Exception:
    pass
sys.exit(0)
"""

// MARK: - nb-hook Python relay (App Store — socket in sandboxed container)

private let nbHookPythonAppStore = """
#!/usr/bin/env python3
# nb-hook.py — Coucou (App Store) hook relay for Claude Code and third-party agents
# Socket lives inside the sandboxed container; script runs outside the sandbox.
import sys, json, os, socket

def normalize_event(name):
    mapping = {
        'BeforeTool': 'PreToolUse', 'BeforeToolSelection': 'PreToolUse',
        'AfterTool': 'PostToolUse', 'AfterModel': 'PostToolUse',
        'BeforeAgent': 'UserPromptSubmit', 'AfterAgent': 'Stop',
        'startup': 'SessionStart', 'exit': 'SessionEnd',
        'PreInvocation': 'UserPromptSubmit', 'PostInvocation': 'PostToolUse',
        'pre_tool_use': 'PreToolUse', 'post_tool_use': 'PostToolUse',
        'user_prompt_submit': 'UserPromptSubmit', 'session_start': 'SessionStart',
        'session_end': 'SessionEnd', 'stop': 'Stop',
        'sessionStart': 'SessionStart', 'userPromptSubmitted': 'UserPromptSubmit',
        'agentStop': 'Stop', 'notification': 'Notification',
        'preToolUse': 'PreToolUse', 'postToolUse': 'PostToolUse',
        'permissionRequest': 'PermissionRequest', 'sessionEnd': 'SessionEnd',
    }
    return mapping.get(name, name)

def normalize_tool_fields(payload):
    if 'tool_name' not in payload:
        # Copilot sends toolName directly; other agents nest in toolCall
        if payload.get('toolName'):
            payload['tool_name'] = payload['toolName']
        else:
            tool = payload.get('toolCall')
            if not isinstance(tool, dict):
                tool = {}
            name = tool.get('name') or payload.get('tool', '')
            if name:
                payload['tool_name'] = name
    if 'tool_input' not in payload:
        # Copilot sends toolArgs directly
        tool_args = payload.get('toolArgs')
        if isinstance(tool_args, dict):
            payload['tool_input'] = tool_args
        else:
            tool = payload.get('toolCall') or {}
            if isinstance(tool.get('args'), dict):
                flat = dict(tool['args'])
                for src, dst in [('CommandLine', 'command'), ('FilePath', 'file_path'),
                                 ('Path', 'path'), ('Url', 'url'), ('Query', 'query'), ('Pattern', 'pattern')]:
                    if src in flat:
                        flat[dst] = flat[src]
                payload['tool_input'] = flat
    if 'session_id' not in payload:
        for k in ['conversationId', 'conversation_id', 'sessionId', 'GEMINI_SESSION_ID']:
            if payload.get(k):
                payload['session_id'] = payload[k]
                break
        if 'session_id' not in payload:
            sid = os.environ.get('GEMINI_SESSION_ID', '')
            if sid:
                payload['session_id'] = sid
    # Copilot sends workdir for the current working directory
    if not payload.get('cwd') and payload.get('workdir'):
        payload['cwd'] = payload['workdir']

def add_session_name(payload):
    # Name the pill after the session's title, else the folder the session started in,
    # not the current cwd (the agent may cd into subfolders). Both come from the
    # transcript: its first lines, and its last custom-title entry (/rename), else its
    # last ai-title one (the title Claude Code gives a session; VS Code sessions only
    # have that). Entries are told by their type: a message that merely quotes one is not
    # a title. Claude Code writes the title again every 40-80 KB, hence a 256 KB tail.
    path = payload.get('transcript_path') or ''
    if not path:
        return
    try:
        with open(path, 'rb') as f:
            for line in f.read(16384).splitlines():
                try:
                    root = json.loads(line).get('cwd')
                except Exception:
                    continue
                if root:
                    payload['session_root'] = root
                    break
            f.seek(0, os.SEEK_END)
            start = max(0, f.tell() - 262144)
            f.seek(start)
            lines = f.read().splitlines()
            ai_title = ''
            for line in reversed(lines[1:] if start else lines):
                if b'"type":"custom-title"' not in line and b'"type":"ai-title"' not in line:
                    continue
                try:
                    entry = json.loads(line)
                except Exception:
                    continue
                if entry.get('type') == 'custom-title' and entry.get('customTitle'):
                    payload['session_title'] = entry['customTitle']
                    return
                if entry.get('type') == 'ai-title' and not ai_title:
                    ai_title = entry.get('aiTitle') or ''
            if ai_title:
                payload['session_title'] = ai_title
    except Exception:
        pass

def term_program(env):
    # VS Code's Claude Code extension on a remote machine (Remote - SSH) has neither
    # TERM_PROGRAM nor the app's bundle ID; its entrypoint still says where it runs.
    term = env.get('TERM_PROGRAM', '')
    if not term and not env.get('__CFBundleIdentifier') and env.get('CLAUDE_CODE_ENTRYPOINT') == 'claude-vscode':
        return 'vscode'
    return term

def main():
    raw = b''
    payload = {}
    try:
        raw = sys.stdin.buffer.read()
        if not raw:
            if '--statusline' not in sys.argv[1:]:
                return
        else:
            payload = json.loads(raw)
    except Exception:
        if '--statusline' not in sys.argv[1:]:
            return

    # COUCOU_SOCKET points the relay at another socket, for instance the one an
    # `ssh -R` tunnel forwards from the Mac to a remote machine (docs/REMOTE.md).
    socket_path = os.path.expanduser(
        os.environ.get('COUCOU_SOCKET') or '~/Library/Containers/fr.louisraille.Coucou/Data/nb.sock'
    )

    # --statusline mode: relay rate_limits to Coucou, then delegate to saved previous
    if '--statusline' in sys.argv[1:]:
        relay = {
            'coucou_kind': 'statusline',
            'session_id': payload.get('session_id', ''),
            'rate_limits': payload.get('rate_limits', {}),
        }
        try:
            s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
            s.settimeout(0.3)
            s.connect(socket_path)
            s.sendall((json.dumps(relay) + '\\n').encode())
            s.close()
        except Exception:
            pass
        prev_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'statusline-previous.json')
        if os.path.exists(prev_file):
            try:
                import subprocess
                with open(prev_file) as f:
                    prev = json.load(f)
                cmd = prev.get('command', '')
                if cmd:
                    result = subprocess.run(['/bin/sh', '-c', cmd], input=raw,
                                             capture_output=True, timeout=10)
                    if result.stdout:
                        sys.stdout.buffer.write(result.stdout)
                        sys.stdout.buffer.flush()
            except Exception:
                pass
        return

    # --ask mode: dedicated hook for AskUserQuestion via PreToolUse (Claude Code 2.1.85+)
    if '--ask' in sys.argv[1:]:
        tool = payload.get('tool_name', '')
        if tool != 'AskUserQuestion':
            return  # Not an AskUserQuestion invocation — exit cleanly (no output)
        payload['coucou_kind'] = 'ask_user_question'
        env = os.environ
        payload.setdefault('term_program', term_program(env))
        payload.setdefault('iterm_session_id', env.get('ITERM_SESSION_ID', ''))
        payload.setdefault('term_session_id', env.get('TERM_SESSION_ID', ''))
        payload.setdefault('bundle_id', env.get('__CFBundleIdentifier', ''))
        if 'cwd' not in payload or not payload['cwd']:
            paths = payload.get('workspacePaths') or payload.get('workspace_roots', [])
            if isinstance(paths, list) and paths:
                payload['cwd'] = paths[0]
            else:
                payload['cwd'] = os.getcwd()
        add_session_name(payload)
        try:
            s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
            s.settimeout(125)
            s.connect(socket_path)
            s.sendall((json.dumps(payload) + '\\n').encode())
            chunks = []
            while True:
                chunk = s.recv(4096)
                if not chunk:
                    break
                chunks.append(chunk)
                if b'\\n' in chunk:
                    break
            s.close()
            response = b''.join(chunks).decode().strip()
            if response:
                try:
                    resp_obj = json.loads(response)
                    decision = resp_obj.get('permissionDecision', '')
                except Exception:
                    decision = ''
                if decision == 'answer':
                    answers = resp_obj.get('answers', {})
                    questions = payload.get('tool_input', {}).get('questions', [])
                    out = {'hookSpecificOutput': {'hookEventName': 'PreToolUse', 'permissionDecision': 'allow', 'updatedInput': {'questions': questions, 'answers': answers}}}
                    sys.stdout.write(json.dumps(out) + '\\n')
                    sys.stdout.flush()
                    sys.exit(0)
                # 'ask' or unknown: fall through → no output → Claude Code asks in terminal
        except Exception:
            pass
        return

    # Parse --agent <name> and optional positional event from argv.
    # --agent tags the payload with coucou_agent so the app routes to the right pill.
    # The positional arg is a fallback event name for agents that do not set hook_event_name.
    args = sys.argv[1:]
    agent = ''
    arg_event = ''
    i = 0
    while i < len(args):
        if args[i] == '--agent' and i + 1 < len(args):
            agent = args[i + 1]
            i += 2
        else:
            if not arg_event:
                arg_event = args[i]
            i += 1
    if agent:
        payload.setdefault('coucou_agent', agent)
    # Claude Code sessions from the Claude desktop app (Code tab) report this entrypoint;
    # route them to the Claude Desktop pill instead of dropping them (no VS Code terminal).
    if not payload.get('coucou_agent') and os.environ.get('CLAUDE_CODE_ENTRYPOINT') == 'claude-desktop':
        payload['coucou_agent'] = 'claude-desktop'

    env = os.environ
    payload.setdefault('term_program', term_program(env))
    payload.setdefault('iterm_session_id', env.get('ITERM_SESSION_ID', ''))
    payload.setdefault('term_session_id', env.get('TERM_SESSION_ID', ''))
    payload.setdefault('bundle_id', env.get('__CFBundleIdentifier', ''))
    if 'cwd' not in payload or not payload['cwd']:
        paths = payload.get('workspacePaths') or payload.get('workspace_roots', [])
        if isinstance(paths, list) and paths:
            payload['cwd'] = paths[0]
        else:
            payload['cwd'] = os.getcwd()
    add_session_name(payload)

    # Normalize event name and tool fields (Gemini CLI / Antigravity → canonical names)
    try:
        raw_event = payload.get('hook_event_name', '') or arg_event
        if raw_event:
            payload['hook_event_name'] = normalize_event(raw_event)
        normalize_tool_fields(payload)
    except Exception:
        pass

    event = payload.get('hook_event_name', '')
    # socket_path is already defined above

    if event == 'PermissionRequest':
        # Block and wait for Coucou's decision (Claude Code allows up to 120s)
        try:
            s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
            s.settimeout(118)
            s.connect(socket_path)
            s.sendall((json.dumps(payload) + '\\n').encode())
            chunks = []
            while True:
                chunk = s.recv(4096)
                if not chunk:
                    break
                chunks.append(chunk)
                if b'\\n' in chunk:
                    break
            s.close()
            response = b''.join(chunks).decode().strip()
            if response:
                try:
                    resp_obj = json.loads(response)
                    decision = resp_obj.get('permissionDecision', '')
                except Exception:
                    decision = ''
                if agent == 'hermes':
                    hermes_choice = 'once' if decision == 'allow' else decision
                    if hermes_choice in ('once', 'always', 'deny'):
                        sys.stdout.write(json.dumps({'choice': hermes_choice}) + '\\n')
                        sys.stdout.flush()
                    sys.exit(0)
                if decision in ('allow', 'always'):
                    # Copilot/Muse use {"permissionDecision":"allow"} directly
                    if agent in ('copilot', 'muse'):
                        out = {'permissionDecision': 'allow'}
                    elif decision == 'always' and agent != 'codex':
                        # Let Claude Code persist the rule via updatedPermissions
                        suggestions = payload.get('permission_suggestions', [])
                        out = {'hookSpecificOutput': {'hookEventName': 'PermissionRequest', 'decision': {'behavior': 'allow', 'updatedPermissions': suggestions}}}
                    else:
                        # Claude Code / Codex plain allow
                        out = {'hookSpecificOutput': {'hookEventName': 'PermissionRequest', 'decision': {'behavior': 'allow'}}}
                    # Claude Code ignores an allow for ExitPlanMode without updatedInput (Allow and Always).
                    if payload.get('tool_name') == 'ExitPlanMode' and 'hookSpecificOutput' in out:
                        out['hookSpecificOutput']['decision']['updatedInput'] = payload.get('tool_input', {})
                        # Mode picked on the plan card: same choice as the terminal's plan dialog.
                        mode = resp_obj.get('mode')
                        if mode in ('auto', 'default'):
                            out['hookSpecificOutput']['decision']['updatedPermissions'] = [{'type': 'setMode', 'mode': mode, 'destination': 'session'}]
                    sys.stdout.write(json.dumps(out) + '\\n')
                    sys.stdout.flush()
                    sys.exit(0)
                elif decision == 'deny':
                    if agent in ('copilot', 'muse'):
                        out = {'permissionDecision': 'deny'}
                    else:
                        out = {'hookSpecificOutput': {'hookEventName': 'PermissionRequest', 'decision': {'behavior': 'deny', 'message': 'Denied from Coucou'}}}
                    sys.stdout.write(json.dumps(out) + '\\n')
                    sys.stdout.flush()
                    sys.exit(0)
                elif decision == 'answer':
                    # AskUserQuestion answered from the notch
                    answers = resp_obj.get('answers', {})
                    questions = payload.get('tool_input', {}).get('questions', [])
                    out = {'hookSpecificOutput': {'hookEventName': 'PermissionRequest', 'decision': {'behavior': 'allow', 'updatedInput': {'questions': questions, 'answers': answers}}}}
                    sys.stdout.write(json.dumps(out) + '\\n')
                    sys.stdout.flush()
                    sys.exit(0)
                elif decision == 'change_plan':
                    # Plan card "Change plan": like the terminal's "Tell Claude what to change",
                    # reject the plan and stop Claude so the prompt is free for the change.
                    out = {'hookSpecificOutput': {'hookEventName': 'PermissionRequest', 'decision': {'behavior': 'deny', 'interrupt': True, 'message': 'The user wants to change the plan and will type the changes in the terminal.'}}}
                    sys.stdout.write(json.dumps(out) + '\\n')
                    sys.stdout.flush()
                    sys.exit(0)
                # 'ask' or unknown: fall through → no output → agent re-asks
        except Exception:
            pass
        # App unreachable, timed out, or no explicit decision — print nothing
        # Copilot is fail-closed: must always output valid JSON so it re-asks rather than deny
        # Hermes: no output → json.loads raises in plugin → transport_fallback: builtin activates
        if agent == 'copilot':
            sys.stdout.write('{"permissionDecision":"ask"}\\n')
            sys.stdout.flush()
        sys.exit(0)

    try:
        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        s.settimeout(0.3)
        s.connect(socket_path)
        s.sendall((json.dumps(payload) + '\\n').encode())
        s.close()
    except Exception:
        pass  # Always exit cleanly — never block the agent

    # Antigravity needs a decision on PreToolUse ({} reads as a denial). "ask" keeps its own
    # permission prompt (and the user's Always Allow); Coucou never allows a tool by itself.
    if agent == 'antigravity' and event == 'PreToolUse':
        sys.stdout.write('{"decision":"ask"}\\n')
        sys.stdout.flush()
    elif agent in ('gemini', 'antigravity', 'muse', 'copilot'):
        sys.stdout.write('{}\\n')
        sys.stdout.flush()

try:
    main()
except Exception:
    pass
sys.exit(0)
"""


extension HookServer {
    /// What stopped a Claude Code turn, from its StopFailure hook: Claude Code's own message when
    /// it sends one, else a sentence for the kind of error. nil when nothing says.
    static func stopFailureDetail(_ payload: [String: Any]) -> String? {
        for key in ["error_message", "error_details", "message"] {
            if let text = payload[key] as? String, !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
                return DiffEngine.toOneLine(text)
            }
        }
        if let error = payload["error"] as? [String: Any], let text = error["message"] as? String, !text.isEmpty {
            return DiffEngine.toOneLine(text)
        }
        let kind = (payload["error_type"] as? String) ?? (payload["error"] as? String) ?? ""
        switch kind {
        case "rate_limit":            return String(localized: "Claude's rate limit is reached. Try again in a moment.")
        case "overloaded":            return String(localized: "Claude is overloaded. Try again in a moment.")
        case "authentication_failed", "oauth_org_not_allowed":
                                      return String(localized: "Claude Code is not signed in, or its key is no longer valid.")
        case "billing_error":         return String(localized: "Billing problem on the Claude account.")
        case "server_error":          return String(localized: "Claude's servers had a problem. Try again.")
        case "max_output_tokens":     return String(localized: "The answer was too long and was cut.")
        case "model_not_found":       return String(localized: "This model is not available.")
        default:
            // Claude Code often sends only `error: "unknown"`: its last message then usually
            // carries the API's own words ("API Error: 529 Overloaded…").
            if let last = payload["last_assistant_message"] as? String,
               last.range(of: "error", options: .caseInsensitive) != nil {
                return DiffEngine.toOneLine(last)
            }
            // A readable error is shown as it is; "unknown" or a bare status code says nothing.
            return kind.count > 3 && Int(kind) == nil && kind != "unknown" ? kind : nil
        }
    }
}