Rebuild detection on ground truth: Claude Code hooks (v1.1.0)

After repeated both-ways failures (sleeps mid-task / won't sleep after),
the root problem was the approach: inferring agent state from transcript
formats and CPU/network thresholds is inherently fragile. Vigil now installs
a Claude Code hook (merged into ~/.claude/settings.json — one-time backup,
idempotent, refuses unparseable JSON, user's hooks untouched) so Claude
itself reports state instantly:

  UserPromptSubmit/PreToolUse/PostToolUse -> active (with claude pid)
  Notification (permission/idle prompt)   -> waiting (human needed; may sleep)
  Stop/SessionEnd                         -> idle

Detection tiers: hooks (primary, immediate) > transcript semantic (only for
sessions without markers) > debounced net/CPU heuristic. Found the main
"never sleeps" culprit on real hardware: an IDLE Claude Desktop window burns
~10% CPU compositing its Electron UI, permanently tripping the CPU threshold
- GUI apps are now judged by sustained network only. Claude Code CLI
processes are dropped from the heuristic when hooks are live.

Hardening from adversarial review: pid-less active markers trusted only
10 min; stale markers cross-checked against the transcript (lost-Stop guard:
turn ended after marker -> idle; mid-tool -> stays active, so a single long
tool survives); hook script lands the event before pid discovery so a slow
ps can never lose it.

Verified: settings merge diffed (all user keys/hooks preserved, idempotent
across relaunches); hook script per-event; detector states incl. dead-pid/
stale/waiting/lost-Stop/long-tool; modes off/keepAwake; live ground truth
(real markers from real sessions, active with live pid / idle after Stop).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: botus-ai

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.1.0 — 2026-06-10
+
+**Detection rebuilt on ground truth.** After repeated reports of both failure
+modes (sleeps mid-task / won't sleep after), the root problem was the approach:
+guessing agent state from transcript formats and CPU/network thresholds is
+inherently fragile. Vigil now installs a tiny **Claude Code hook** (merged into
+`~/.claude/settings.json` with a one-time backup; removable from the menu), so
+Claude itself reports session state the instant it changes:
+
+- `UserPromptSubmit` / `PreToolUse` / `PostToolUse` → session is **working**
+- `Notification` (permission prompt / waiting for input) → **a human is needed**
+  — the Mac may sleep instead of staying awake at a forgotten permission dialog
+- `Stop` / `SessionEnd` → **turn over** — sleep follows after the short grace
+
+No more format guessing, no thresholds, no polling lag for Claude Code sessions.
+Crash-safe: an "active" marker only counts while its claude process is alive
+(and never longer than 2h without a refresh).
+
+Also found & fixed the main "never sleeps" culprit on real hardware: **an idle
+Claude Desktop window**. Its Electron helpers burn ~10% CPU just compositing the
+UI, which permanently tripped the CPU heuristic. GUI apps are now judged by
+sustained network only (streaming = working); CPU stays meaningful for CLI
+agents. Plus: transcript detection now only covers sessions without hook
+markers, and Claude Code CLI processes are dropped from the heuristic when
+hooks are live.
+
 ## 1.0.5 — 2026-06-03
 
 - **No more confusing/flickering agent count.** The menu used to show "N of M

README.md

@@ -82,7 +82,8 @@ Click the menu-bar eye icon:
 - **Automatic** — keep awake only while an AI agent is working (the default).
 - **Keep Awake** / **Off** — classic manual modes.
 - **Watch for…** — pick which AI tools to track.
-- **Semantic detection** — read Claude transcripts for precise mid-turn detection.
+- **Precise detection (Claude Code hooks)** — ground truth from Claude itself (default on).
+- **Semantic detection** — read Claude transcripts (fallback for sessions without hooks).
 - **Keep awake with lid closed** — one-time admin approval installs the helper.
 - **Stop other keep-awake tools** — quit redundant `caffeinate` / scripts.
 - **Launch at Login** — on by default.
@@ -91,17 +92,23 @@ Icons: `eye` = idle · `eye.fill` = keeping awake · `bolt.fill` = force-awake 
 
 ## How it works
 
-Each agent session is evaluated **individually** (so a crowd of idle/leftover sessions can
-never falsely keep the Mac awake). A session is *working* when any of these is true:
+Detection is layered, most reliable first:
 
-1. **Semantic state (Claude)** — its transcript shows it's mid-turn (`stop_reason != end_turn`).
-2. **API throughput** — sustained network traffic, *including loopback* so agents talking to
-   a local model server (e.g. ollama on `127.0.0.1`) count too.
-3. **Subtree CPU** — the process *and its children* are busy (catches long local test/build runs).
+1. **Ground truth — Claude Code hooks.** Vigil installs a tiny hook (merged into
+   `~/.claude/settings.json`, one-time backup kept, removable from the menu), so Claude
+   itself reports state the instant it changes: prompt submitted / tool running → working;
+   permission prompt or waiting for input → a human is needed (sleep allowed); turn done →
+   idle. No guessing, no polling lag. Crash-safe: a "working" marker only counts while its
+   claude process is actually alive.
+2. **Semantic state (fallback)** — for sessions without hooks, the transcript shows whether
+   it's mid-turn (`stop_reason != end_turn`).
+3. **Network/CPU heuristic (for non-Claude tools)** — sustained traffic *including loopback*
+   (local ollama counts) or subtree CPU. GUI apps like Claude Desktop are judged by network
+   only — an idle Electron window burns ~10% CPU just compositing, which is not "work".
 
 To avoid false positives, `claude`-named background tooling (vault sync, memory daemons,
-Vigil's own helper) is excluded, and detection is debounced so a single CPU blip can't pin
-the Mac awake.
+Vigil's own helper) is excluded, and the heuristic is debounced so a single CPU blip can't
+pin the Mac awake.
 
 While any agent works, Vigil holds IOKit power assertions for **both** system and display
 sleep (so the screen doesn't lock on you mid-task), plus a grace period after work stops.

Resources/Info.plist

@@ -9,9 +9,9 @@
 	<key>CFBundleIdentifier</key>
 	<string>app.vigil.menubar</string>
 	<key>CFBundleVersion</key>
-	<string>1.0.0</string>
+	<string>1.1.0</string>
 	<key>CFBundleShortVersionString</key>
-	<string>1.0.0</string>
+	<string>1.1.0</string>
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleExecutable</key>

Sources/ActivityMonitor.swift

@@ -3,14 +3,15 @@ import Foundation
 struct ActivitySnapshot {
     var agentCount: Int          // number of detected agent sessions (root processes)
     var activeAgentCount: Int    // how many of those are working right now (combined)
-    var semanticBusy: Int        // Claude sessions mid-turn per transcript (reliable signal)
+    var hookActive: Int          // sessions mid-turn per Claude Code hooks (ground truth)
+    var semanticBusy: Int        // non-hooked sessions mid-turn per transcript (fallback)
     var heuristicActive: Int     // sessions over the network/CPU threshold (noisy signal)
     var isActive: Bool           // at least one agent is working right now
     var netBytesPerSec: Double   // throughput of the busiest agent
     var cpuPercent: Double       // CPU% of the busiest agent's subtree
 
-    static let empty = ActivitySnapshot(agentCount: 0, activeAgentCount: 0, semanticBusy: 0,
-                                        heuristicActive: 0, isActive: false,
+    static let empty = ActivitySnapshot(agentCount: 0, activeAgentCount: 0, hookActive: 0,
+                                        semanticBusy: 0, heuristicActive: 0, isActive: false,
                                         netBytesPerSec: 0, cpuPercent: 0)
 }
 
@@ -29,6 +30,14 @@ final class ActivityMonitor {
     private var timer: DispatchSourceTimer?
 
     private let semantic = SemanticDetector()
+    private let hooks = HookSessionDetector()
+
+    init() {
+        // Lost-Stop guard: stale "active" hook markers are validated against the
+        // session transcript (capture `semantic` directly — no cycle).
+        let sem = semantic
+        hooks.transcriptSaysEnded = { sid, marker in sem.turnEnded(sessionId: sid, after: marker) }
+    }
 
     // Per-PID cumulative byte counters from the previous nettop sample.
     private var prevBytesIn: [Int: UInt64] = [:]
@@ -77,23 +86,38 @@ final class ActivityMonitor {
         guard !patterns.isEmpty else { return .empty }
         let excludes = prefs.watchExcludes.map { $0.lowercased() }.filter { !$0.isEmpty }
 
-        // Primary signal for Claude: transcript state. Counts mid-turn sessions.
-        let semanticBusy = prefs.semanticDetection ? semantic.busySessionCount() : 0
+        // PRIMARY signal: Claude Code hooks (ground truth — Claude tells us when a
+        // turn starts/ends). Sessions with a hook marker are "governed": for them
+        // we trust the hooks completely and skip transcript guessing.
+        let hookScan = hooks.scan()
+        let hooksLive = !hookScan.governedSessions.isEmpty
+
+        // FALLBACK signal: transcript state, only for sessions hooks don't govern
+        // (sessions started before hook install, or if hooks are removed).
+        let semanticBusy = prefs.semanticDetection
+            ? semantic.busySessionCount(excludingSessions: hookScan.governedSessions) : 0
 
         let procs = readProcesses()
         // A process is a watched agent if it matches a watch pattern AND is not
         // excluded. The exclude list keeps "claude"-named background tooling
         // (vault sync, memory daemons, Vigil's own helper) from being mistaken
-        // for a working agent and pinning the Mac awake.
+        // for a working agent and pinning the Mac awake. When hooks are live,
+        // Claude Code CLI processes are governed by hooks — drop them from the
+        // CPU/network heuristic too, so an idle VS Code session that briefly
+        // spikes CPU can't fake "working".
         let watched = procs.filter { p in
             let c = p.command.lowercased()
             guard patterns.contains(where: { c.contains($0) }) else { return false }
-            return !excludes.contains(where: { c.contains($0) })
+            if excludes.contains(where: { c.contains($0) }) { return false }
+            if hooksLive && c.contains("native-binary/claude") { return false }
+            return true
         }
-        guard !watched.isEmpty || semanticBusy > 0 else {
+        guard !watched.isEmpty || semanticBusy > 0 || hookScan.activeCount > 0 else {
             prevBytesIn = [:]
             prevSampleDate = nil
-            return .empty
+            var snap = ActivitySnapshot.empty
+            snap.agentCount = hookScan.governedSessions.count
+            return snap
         }
 
         let watchedPIDs = Set(watched.map { $0.pid })
@@ -133,7 +157,11 @@ final class ActivityMonitor {
 
             // Evaluated per session: a single working agent is enough, and a
             // crowd of idle ones never sums its way over the threshold.
-            if rate > prefs.netThresholdBytesPerSec || cpu > prefs.cpuThresholdPercent {
+            // GUI apps (Claude Desktop & co) idle at ~10% CPU just compositing
+            // their Electron UI, so CPU is meaningless for them — only sustained
+            // network (streaming a response) counts. CLI agents keep CPU+network.
+            let isGUIApp = session.command.contains(".app/Contents/MacOS/")
+            if rate > prefs.netThresholdBytesPerSec || (!isGUIApp && cpu > prefs.cpuThresholdPercent) {
                 activeCount += 1
             }
             peakRate = max(peakRate, rate)
@@ -143,16 +171,17 @@ final class ActivityMonitor {
         prevBytesIn = bytesIn
         prevSampleDate = now
 
-        // Combine the heuristic (network/CPU) with the semantic signal: an agent
-        // is working if either says so.
-        let totalAgents = max(sessions.count, semanticBusy)
-        let activeAgents = max(activeCount, semanticBusy)
+        // Combine: hooks (ground truth) + semantic (non-hooked fallback) engage
+        // immediately; the network/CPU heuristic is debounced by the controller.
+        let immediate = hookScan.activeCount + semanticBusy
+        let totalAgents = max(sessions.count + hookScan.governedSessions.count, immediate)
 
         return ActivitySnapshot(agentCount: totalAgents,
-                                activeAgentCount: activeAgents,
+                                activeAgentCount: max(activeCount, immediate),
+                                hookActive: hookScan.activeCount,
                                 semanticBusy: semanticBusy,
                                 heuristicActive: activeCount,
-                                isActive: activeAgents > 0,
+                                isActive: immediate > 0,
                                 netBytesPerSec: peakRate,
                                 cpuPercent: peakCPU)
     }

Sources/AppController.swift

@@ -69,7 +69,10 @@ final class AppController {
         } else {
             consecutiveActiveTicks = 0
         }
-        let working = snap.semanticBusy > 0 || consecutiveActiveTicks >= activateAfterTicks
+        // Hooks (ground truth) and semantic (fallback) engage immediately; only
+        // the noisy CPU/network heuristic needs the debounce.
+        let working = snap.hookActive > 0 || snap.semanticBusy > 0
+            || consecutiveActiveTicks >= activateAfterTicks
         if working { lastActive = Date() }
         liveActive = working
         evaluate()
@@ -99,7 +102,7 @@ final class AppController {
         let wantDisplay = (prefs.mode == .keepAwake || prefs.keepDisplayAwake) && engaged
 
         if ProcessInfo.processInfo.environment["VIGIL_DEBUG"] != nil {
-            NSLog("VIGIL mode=\(prefs.mode.rawValue) agents=\(lastSnapshot.agentCount) sem=\(lastSnapshot.semanticBusy) heur=\(lastSnapshot.heuristicActive) ticks=\(consecutiveActiveTicks) live=\(liveActive) engaged=\(engaged) display=\(wantDisplay)")
+            NSLog("VIGIL mode=\(prefs.mode.rawValue) agents=\(lastSnapshot.agentCount) hooks=\(lastSnapshot.hookActive) sem=\(lastSnapshot.semanticBusy) heur=\(lastSnapshot.heuristicActive) ticks=\(consecutiveActiveTicks) live=\(liveActive) engaged=\(engaged) display=\(wantDisplay)")
         }
         sleep.apply(awake: engaged, keepDisplayAwake: wantDisplay)
 

Sources/AppDelegate.swift

@@ -18,6 +18,14 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
             LaunchAtLogin.set(true)
         }
 
+        // Out of the box: install the ground-truth Claude Code hook (merged into
+        // ~/.claude/settings.json with a one-time backup; removable from the menu).
+        // Called every launch: the settings merge is idempotent, and rewriting
+        // the hook script keeps it current across app updates.
+        if Preferences.shared.hooksEnabled, !HooksInstaller().install() {
+            NSLog("Vigil: hook install failed — falling back to transcript/heuristic detection")
+        }
+
         // First-run welcome + optional lid-closed setup (after the menu appears).
         if !Preferences.shared.didOnboard {
             Preferences.shared.didOnboard = true

Sources/HookSessionDetector.swift

@@ -0,0 +1,96 @@
+import Foundation
+
+struct HookScan {
+    var governedSessions: Set<String>   // session ids that have any marker (hooks are live for them)
+    var activeCount: Int                // sessions confirmed mid-turn right now
+    var waitingCount: Int               // sessions waiting for the human (permission / idle prompt)
+
+    static let empty = HookScan(governedSessions: [], activeCount: 0, waitingCount: 0)
+}
+
+/// Ground-truth activity detection via Claude Code hooks.
+///
+/// Vigil installs a tiny hook script into ~/.claude/settings.json (see
+/// HooksInstaller). Claude Code then *tells us* what each session is doing:
+///   UserPromptSubmit / PreToolUse / PostToolUse → "active <claude-pid> <ts>"
+///   Notification (permission prompt / waiting for input) → "waiting 0 <ts>"
+///   Stop / SessionEnd → "idle 0 <ts>"
+/// One marker file per session id. This replaces guessing from transcript
+/// formats and CPU/network thresholds with events emitted by Claude Code
+/// itself — instant on turn start, instant on turn end.
+///
+/// Crash-safety: an "active" marker is only honoured while the recorded claude
+/// process is still alive, and never longer than `activeTrustWindow` without a
+/// refresh (a turn that long without a single tool call means a dead/hung
+/// session — multi-tool turns refresh on every PostToolUse).
+final class HookSessionDetector {
+
+    static var sessionsDir: String {
+        if let o = ProcessInfo.processInfo.environment["VIGIL_SESSIONS_DIR"], !o.isEmpty { return o }
+        return NSHomeDirectory() + "/Library/Application Support/Vigil/sessions"
+    }
+
+    private let activeTrustWindow: TimeInterval = 2 * 3600
+    /// An "active" marker with no recorded pid (the hook couldn't identify its
+    /// claude process) is weaker evidence — trust it only briefly.
+    private let pidlessTrustWindow: TimeInterval = 600
+    /// Markers older than this get cross-checked against the transcript, which
+    /// catches a lost Stop event (turn actually ended but the idle marker never
+    /// arrived, e.g. the hook was killed at the wrong moment).
+    private let crossCheckAge: TimeInterval = 600
+    private let markerTTL: TimeInterval = 48 * 3600
+
+    /// Injected: returns true if the session's transcript shows the turn ENDED
+    /// after the given marker time (terminal stop_reason with a newer timestamp).
+    var transcriptSaysEnded: ((String, Date) -> Bool)?
+
+    func scan() -> HookScan {
+        var result = HookScan.empty
+        let fm = FileManager.default
+        guard let names = try? fm.contentsOfDirectory(atPath: Self.sessionsDir) else { return result }
+        let now = Date().timeIntervalSince1970
+        for name in names where !name.hasPrefix(".") {
+            let path = Self.sessionsDir + "/" + name
+            guard let content = try? String(contentsOfFile: path, encoding: .utf8) else { continue }
+            let parts = content.split(whereSeparator: { $0 == " " || $0 == "\n" || $0 == "\t" })
+            guard parts.count >= 3,
+                  let pid = Int32(parts[1]),
+                  let ts = TimeInterval(parts[2]) else { continue }
+            let age = now - ts
+            if age > markerTTL { try? fm.removeItem(atPath: path); continue }
+            result.governedSessions.insert(name)
+            switch parts[0] {
+            case "active":
+                var ok: Bool
+                if pid > 0 {
+                    // Strong evidence: the claude process must still be alive,
+                    // bounded by the trust window (multi-tool turns refresh on
+                    // every PostToolUse; a single silent tool is covered up to
+                    // the window).
+                    ok = processAlive(pid) && age < activeTrustWindow
+                } else {
+                    ok = age < pidlessTrustWindow
+                }
+                // Lost-Stop guard: if the marker is old but the transcript shows
+                // the turn ended AFTER it was written, the idle event was lost —
+                // don't keep the Mac awake on a finished turn.
+                if ok, age > crossCheckAge,
+                   let ended = transcriptSaysEnded,
+                   ended(name, Date(timeIntervalSince1970: ts)) {
+                    ok = false
+                }
+                if ok { result.activeCount += 1 }
+            case "waiting":
+                result.waitingCount += 1
+            default:
+                break   // idle
+            }
+        }
+        return result
+    }
+
+    private func processAlive(_ pid: Int32) -> Bool {
+        if kill(pid, 0) == 0 { return true }
+        return errno == EPERM
+    }
+}