diff --git a/package-lock.json b/package-lock.json
index 31a52ff..74fc198 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -51,6 +51,7 @@
         "geist": "^1.7.2",
         "github-markdown-css": "^5.9.0",
         "lucide-react": "^1.21.0",
+        "motion": "^12.42.2",
         "react": "^19.1.0",
         "react-dom": "^19.1.0",
         "react-markdown": "^10.1.0",
@@ -1370,7 +1371,6 @@
     "node_modules/@emotion/is-prop-valid": {
       "version": "1.4.0",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@emotion/memoize": "^0.9.0"
       }
diff --git a/package.json b/package.json
index c0765e1..b7e6c1c 100644
--- a/package.json
+++ b/package.json
@@ -59,6 +59,7 @@
     "geist": "^1.7.2",
     "github-markdown-css": "^5.9.0",
     "lucide-react": "^1.21.0",
+    "motion": "^12.42.2",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-markdown": "^10.1.0",
diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock
index 9bb6267..5e8a604 100644
--- a/src-tauri/Cargo.lock
+++ b/src-tauri/Cargo.lock
@@ -89,6 +89,12 @@ dependencies = [
  "x11rb",
 ]
 
+[[package]]
+name = "ascii"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d92bec98840b8f03a5ff5413de5293bfcd8bf96467cf5452609f939ec6f5de16"
+
 [[package]]
 name = "async-broadcast"
 version = "0.7.2"
@@ -557,6 +563,12 @@ dependencies = [
  "windows-link 0.2.1",
 ]
 
+[[package]]
+name = "chunked_transfer"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e4de3bc4ea267985becf712dc6d9eed8b04c953b3fcfb339ebc87acd9804901"
+
 [[package]]
 name = "clipboard-win"
 version = "5.4.1"
@@ -4438,6 +4450,7 @@ version = "0.1.6"
 dependencies = [
  "dashmap",
  "dbiso",
+ "getrandom 0.2.17",
  "hephaestus",
  "junction",
  "libc",
@@ -4453,6 +4466,7 @@ dependencies = [
  "tauri-plugin-opener",
  "tauri-plugin-process",
  "tauri-plugin-updater",
+ "tiny_http",
  "url",
 ]
 
@@ -4572,6 +4586,18 @@ dependencies = [
  "time-core",
 ]
 
+[[package]]
+name = "tiny_http"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "389915df6413a2e74fb181895f933386023c71110878cd0825588928e64cdc82"
+dependencies = [
+ "ascii",
+ "chunked_transfer",
+ "httpdate",
+ "log",
+]
+
 [[package]]
 name = "tinystr"
 version = "0.8.3"
diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml
index 33fe4cf..6d55018 100644
--- a/src-tauri/Cargo.toml
+++ b/src-tauri/Cargo.toml
@@ -43,6 +43,11 @@ tauri-plugin-process = "2"
 # Verifies the signed remote agents manifest (config/agents.json). Already in the
 # tree via tauri-plugin-updater; named here so the verify command can use it.
 minisign-verify = "0.2"
+# Loopback HTTP receiver for agent lifecycle hooks (agent_hooks.rs). A small,
+# correct HTTP impl beats hand-rolling request parsing over raw TCP.
+tiny_http = "0.12"
+# OS entropy for the per-run hook-server auth token.
+getrandom = "0.2"
 
 [target.'cfg(unix)'.dependencies]
 libc = "0.2"
diff --git a/src-tauri/src/agent_hooks.rs b/src-tauri/src/agent_hooks.rs
new file mode 100644
index 0000000..3ce8b06
--- /dev/null
+++ b/src-tauri/src/agent_hooks.rs
@@ -0,0 +1,222 @@
+//! Loopback receiver for agent lifecycle hooks.
+//!
+//! A managed hook script that Tempest installs into each agent's own config
+//! (see `src/lib/agentHooks/`) POSTs one event per turn boundary / tool call /
+//! permission prompt to `http://127.0.0.1:<port>/hook/<agent>`. This module is a
+//! **dumb, secure pipe**: it authenticates the request, reads which Tempest
+//! session it belongs to (echoed back from the `TEMPEST_SESSION` env we inject
+//! at spawn), and forwards the raw agent payload to the frontend as an
+//! `agent-hook` event. All per-agent parsing lives in TypeScript next to the
+//! agent registry — Rust never interprets the payload.
+//!
+//! The port is ephemeral and the token is per-run, both published to
+//! `~/.tempest/hooks/endpoint.{env,cmd}` so a hook script re-sources the current
+//! values even after the app restarts under a still-live PTY.
+
+use std::io::Read;
+use std::path::Path;
+use tauri::{AppHandle, Emitter};
+
+/// Hard cap on a forwarded payload. Tool outputs can be large but a status hook
+/// never needs more; anything past this is a malformed or hostile poster.
+const MAX_BODY_BYTES: u64 = 1024 * 1024;
+
+#[derive(Clone, serde::Serialize)]
+struct HookEvent {
+    agent: String,
+    session: String,
+    /// Lifecycle event name, when the script conveys it out-of-band via the
+    /// X-Tempest-Event header (agents like Antigravity whose payload doesn't
+    /// carry it). Empty when the event lives inside the payload itself.
+    event: String,
+    /// Raw agent payload (JSON text as the agent emitted it). Parsed in TS.
+    body: String,
+}
+
+/// `~/.tempest/hooks` — holds the managed scripts, agent plugins, and the
+/// endpoint files. Shared with the TS installer, which computes the same path
+/// from the home dir.
+pub fn hooks_dir() -> std::path::PathBuf {
+    super::global_home().join(".tempest").join("hooks")
+}
+
+/// Atomic write (temp + rename) with mkdir -p, a same-content skip, and an
+/// optional exec bit on unix. Backs both the endpoint files here and the
+/// `hooks_write_atomic` command the installer uses for scripts and configs.
+#[cfg_attr(not(unix), allow(unused_variables))]
+pub fn write_atomic(path: &Path, contents: &str, executable: bool) -> std::io::Result<()> {
+    if let Some(dir) = path.parent() {
+        std::fs::create_dir_all(dir)?;
+    }
+    // Skip a no-op rewrite so re-installing on every launch neither churns the
+    // disk nor rolls a backup forward over the last good copy.
+    if let Ok(existing) = std::fs::read_to_string(path) {
+        if existing == contents {
+            #[cfg(unix)]
+            if executable {
+                set_executable(path)?;
+            }
+            return Ok(());
+        }
+    }
+    let file_name = path
+        .file_name()
+        .map(|n| n.to_string_lossy().to_string())
+        .unwrap_or_else(|| "tmp".to_string());
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_nanos())
+        .unwrap_or(0);
+    let tmp = path.with_file_name(format!(".{file_name}.{}.{nanos}.tmp", std::process::id()));
+    std::fs::write(&tmp, contents)?;
+    #[cfg(unix)]
+    if executable {
+        set_executable(&tmp)?;
+    }
+    // rename is atomic on the same filesystem; a crash mid-write leaves the
+    // original intact and only an orphan temp behind.
+    if let Err(e) = std::fs::rename(&tmp, path) {
+        let _ = std::fs::remove_file(&tmp);
+        return Err(e);
+    }
+    Ok(())
+}
+
+#[cfg(unix)]
+fn set_executable(path: &Path) -> std::io::Result<()> {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755))
+}
+
+/// 32 hex chars of OS entropy — the shared secret a poster must present so a
+/// stray local process can't spoof agent status.
+fn random_token() -> String {
+    let mut buf = [0u8; 16];
+    if getrandom::getrandom(&mut buf).is_err() {
+        // Entropy failure is near-impossible; fall back to a time+pid seed so the
+        // server still starts (degrades auth strength, never availability).
+        let nanos = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_nanos())
+            .unwrap_or(0);
+        let seed = nanos ^ (std::process::id() as u128);
+        return format!("{seed:032x}");
+    }
+    buf.iter().map(|b| format!("{b:02x}")).collect()
+}
+
+/// Length-independent equality so token verification doesn't leak the secret
+/// through response timing. Loopback makes this near-paranoia, but it's cheap.
+fn constant_time_eq(a: &str, b: &str) -> bool {
+    let (a, b) = (a.as_bytes(), b.as_bytes());
+    if a.len() != b.len() {
+        return false;
+    }
+    let mut diff = 0u8;
+    for i in 0..a.len() {
+        diff |= a[i] ^ b[i];
+    }
+    diff == 0
+}
+
+fn write_endpoint_files(dir: &Path, port: u16, token: &str) {
+    // POSIX `. endpoint.env` sources these; the shell reads KEY=VALUE lines.
+    let env = format!("TEMPEST_HOOK_PORT={port}\nTEMPEST_HOOK_TOKEN={token}\n");
+    let _ = write_atomic(&dir.join("endpoint.env"), &env, false);
+    // cmd.exe `call endpoint.cmd` needs `set KEY=VALUE` with CRLF.
+    let cmd = format!("set TEMPEST_HOOK_PORT={port}\r\nset TEMPEST_HOOK_TOKEN={token}\r\n");
+    let _ = write_atomic(&dir.join("endpoint.cmd"), &cmd, false);
+}
+
+/// Start the loopback hook server. Best-effort: a bind failure logs and returns,
+/// leaving sessions on the PTY-scraping fallback — status degrades, never breaks.
+pub fn start(app: AppHandle) {
+    let dir = hooks_dir();
+    let _ = std::fs::create_dir_all(&dir);
+    let token = random_token();
+
+    let server = match tiny_http::Server::http("127.0.0.1:0") {
+        Ok(s) => s,
+        Err(e) => {
+            eprintln!("[agent-hooks] failed to bind loopback server: {e}");
+            return;
+        }
+    };
+    let port = match server.server_addr().to_ip() {
+        Some(addr) => addr.port(),
+        None => {
+            eprintln!("[agent-hooks] server bound to a non-IP address");
+            return;
+        }
+    };
+    write_endpoint_files(&dir, port, &token);
+
+    std::thread::spawn(move || {
+        for request in server.incoming_requests() {
+            handle_request(&app, &token, request);
+        }
+    });
+}
+
+// Takes the request by value: `Request::respond` consumes it, and each branch
+// below responds exactly once before returning.
+fn handle_request(app: &AppHandle, token: &str, mut request: tiny_http::Request) {
+    if *request.method() != tiny_http::Method::Post {
+        let _ = request.respond(tiny_http::Response::empty(404));
+        return;
+    }
+    // URL is `/hook/<agent>`; agent selects the TS adapter.
+    let agent = request
+        .url()
+        .strip_prefix("/hook/")
+        .map(|a| a.split(['?', '/']).next().unwrap_or("").to_string())
+        .unwrap_or_default();
+    if agent.is_empty() {
+        let _ = request.respond(tiny_http::Response::empty(404));
+        return;
+    }
+
+    let mut got_token: Option<String> = None;
+    let mut session: Option<String> = None;
+    let mut event = String::new();
+    for header in request.headers() {
+        let field = header.field.as_str().as_str();
+        if field.eq_ignore_ascii_case("x-tempest-token") {
+            got_token = Some(header.value.as_str().to_string());
+        } else if field.eq_ignore_ascii_case("x-tempest-session") {
+            session = Some(header.value.as_str().to_string());
+        } else if field.eq_ignore_ascii_case("x-tempest-event") {
+            event = header.value.as_str().to_string();
+        }
+    }
+
+    if !got_token.map(|t| constant_time_eq(&t, token)).unwrap_or(false) {
+        let _ = request.respond(tiny_http::Response::empty(403));
+        return;
+    }
+    let session = match session {
+        Some(s) if !s.is_empty() => s,
+        // An unattributed hook can't be routed to a session; drop it.
+        _ => {
+            let _ = request.respond(tiny_http::Response::empty(400));
+            return;
+        }
+    };
+
+    let mut body = String::new();
+    let _ = request
+        .as_reader()
+        .take(MAX_BODY_BYTES)
+        .read_to_string(&mut body);
+
+    let _ = app.emit(
+        "agent-hook",
+        HookEvent {
+            agent,
+            session,
+            event,
+            body,
+        },
+    );
+    let _ = request.respond(tiny_http::Response::empty(200));
+}
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index 969d8e2..24d7721 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -6,6 +6,8 @@ use tauri::ipc::Channel;
 use tauri::Emitter;
 use hephaestus::Isolate;
 
+mod agent_hooks;
+
 /// Process-global isolation backend (Job Objects on Windows). Provisioned lazily
 /// the first time a sandboxed PTY session is created.
 static ISOLATE: std::sync::OnceLock<Arc<dyn Isolate>> = std::sync::OnceLock::new();
@@ -62,6 +64,39 @@ fn write_file(path: String, content: String) -> Result<(), String> {
     std::fs::write(&path, content).map_err(|e| e.to_string())
 }
 
+/// Atomic write (temp + rename, mkdir -p, optional exec bit) used by the agent-
+/// hooks installer for managed scripts and for merged agent config files. The
+/// atomicity matters: a crash mid-write must never leave an agent's own
+/// settings.json truncated.
+#[tauri::command(async)]
+fn hooks_write_atomic(path: String, content: String, executable: bool) -> Result<(), String> {
+    agent_hooks::write_atomic(std::path::Path::new(&path), &content, executable)
+        .map_err(|e| e.to_string())
+}
+
+#[derive(serde::Serialize)]
+struct HookPaths {
+    home: String,
+    hooks_dir: String,
+    endpoint_env: String,
+    endpoint_cmd: String,
+    windows: bool,
+}
+
+/// Filesystem locations + platform the agent-hooks installer needs. Sourced from
+/// Rust so the frontend never has to resolve the home dir or guess the OS.
+#[tauri::command(async)]
+fn hooks_paths() -> HookPaths {
+    let dir = agent_hooks::hooks_dir();
+    HookPaths {
+        home: global_home().to_string_lossy().to_string(),
+        endpoint_env: dir.join("endpoint.env").to_string_lossy().to_string(),
+        endpoint_cmd: dir.join("endpoint.cmd").to_string_lossy().to_string(),
+        hooks_dir: dir.to_string_lossy().to_string(),
+        windows: cfg!(windows),
+    }
+}
+
 /// Returns the @usetempest/atlas package directory inside the runtime folder.
 /// Dev builds: src-tauri/resources/atlas/node_modules/@usetempest/atlas/
 /// Release builds: <exe>/resources/atlas/node_modules/@usetempest/atlas/
@@ -559,6 +594,81 @@ async fn shell_run(
     Ok(())
 }
 
+/// Run a repo-supplied worktree hook (`tempest.yml` `setup:` / `teardown:`) to
+/// completion, one command at a time, stopping at the first failure.
+///
+/// Unlike `shell_run` this waits and reports the exit status: a worktree must
+/// not be reported ready on the strength of a command that failed. Output lines
+/// are streamed as `hook:{token}` events so the caller can show progress.
+#[tauri::command(async)]
+fn run_hook(
+    app: tauri::AppHandle,
+    token: String,
+    cwd: String,
+    commands: Vec<String>,
+    env: Option<std::collections::HashMap<String, String>>,
+) -> Result<(), String> {
+    use std::io::{BufRead, BufReader};
+
+    let ev = format!("hook:{token}");
+    let (program, flag) = if cfg!(windows) { ("cmd", "/C") } else { ("sh", "-c") };
+
+    for cmd_str in commands {
+        let _ = app.emit(&ev, format!("$ {cmd_str}"));
+
+        let mut command = new_command(program);
+        command
+            .arg(flag)
+            .arg(&cmd_str)
+            .current_dir(&cwd)
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped());
+        // The config's `env` is already stripped of loader and DB-isolation
+        // variables by tempestConfig.ts before it reaches here.
+        if let Some(ref vars) = env {
+            for (k, v) in vars {
+                command.env(k, v);
+            }
+        }
+
+        let mut child = command
+            .spawn()
+            .map_err(|e| format!("{cmd_str}: failed to start: {e}"))?;
+
+        let stdout = child.stdout.take().ok_or("no stdout")?;
+        let stderr = child.stderr.take().ok_or("no stderr")?;
+
+        // stderr on its own thread; stdout drained here. Both must be consumed
+        // or a chatty command fills its pipe buffer and blocks forever.
+        let app_err = app.clone();
+        let ev_err = ev.clone();
+        let err_thread = std::thread::spawn(move || {
+            let mut tail = String::new();
+            for line in BufReader::new(stderr).lines().map_while(Result::ok) {
+                let _ = app_err.emit(&ev_err, &line);
+                tail = line;
+            }
+            tail
+        });
+
+        for line in BufReader::new(stdout).lines().map_while(Result::ok) {
+            let _ = app.emit(&ev, &line);
+        }
+
+        let last_err = err_thread.join().unwrap_or_default();
+        let status = child.wait().map_err(|e| format!("{cmd_str}: {e}"))?;
+        if !status.success() {
+            let code = status.code().map_or("signal".to_string(), |c| c.to_string());
+            return Err(if last_err.is_empty() {
+                format!("`{cmd_str}` exited with {code}")
+            } else {
+                format!("`{cmd_str}` exited with {code}: {last_err}")
+            });
+        }
+    }
+    Ok(())
+}
+
 #[tauri::command]
 fn shell_kill(state: tauri::State<'_, RunState>, session_id: String) -> Result<(), String> {
     if let Some(mut child) = state.0.lock().unwrap().remove(&session_id) {
@@ -3474,6 +3584,9 @@ pub fn run() {
                 .map_err(|e| std::io::Error::new(std::io::ErrorKind::Other, e))?;
             app.manage(DbState(Mutex::new(conn)));
             tauri::async_runtime::spawn(async { let _ = dbiso::sweep_orphans().await; });
+            // Loopback receiver for agent lifecycle hooks. Best-effort; a bind
+            // failure leaves sessions on PTY-scraped status.
+            agent_hooks::start(app.handle().clone());
             Ok(())
         })
         .invoke_handler(tauri::generate_handler![
@@ -3517,6 +3630,8 @@ pub fn run() {
             get_ide_panel_url,
             read_file,
             write_file,
+            hooks_write_atomic,
+            hooks_paths,
             start_atlas_index,
             get_atlas_graph,
             atlas_query,
@@ -3532,6 +3647,7 @@ pub fn run() {
             db_sweep_orphans,
             shell_run,
             shell_kill,
+            run_hook,
             remove_atlas_index,
             start_atlas_daemon,
             stop_atlas_daemon,
diff --git a/src/components/DynamicIsland.css b/src/components/DynamicIsland.css
new file mode 100644
index 0000000..7948766
--- /dev/null
+++ b/src/components/DynamicIsland.css
@@ -0,0 +1,209 @@
+/* ─── Dynamic island — live quota, centred on the toolbar ─────────────────────
+   Motion lives in DynamicIsland.tsx: `layout` springs the shape to whatever the
+   content measures, so there are no widths or heights written down here. This
+   file is material and type only. */
+
+/* Pinned by its top edge, not centred: opening must only ever grow downwards,
+   so the pill and the panel start at the same line. 11px puts the 22px pill on
+   the toolbar's icon row — `.bar` pads 8px off the top and `.bar-end` 8px off
+   the bottom, putting that row's midline at 22px.
+
+   Height is left to shrink-wrap the island, and the box is click-through, so it
+   never steals a press meant for the bar underneath. */
+.island-anchor {
+  position: absolute;
+  top: 11px;
+  right: 0;
+  left: 0;
+  z-index: 20;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  pointer-events: none;
+}
+
+.island {
+  display: flex;
+  overflow: hidden;
+  border: 1px solid var(--tempest-island-border-closed);
+  border-radius: 999px;
+  background: var(--tempest-island-bg-closed);
+  /* Specular hairline along the top edge — the thing that makes it read as a
+     lit object rather than a flat chip. */
+  box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.07);
+  color: var(--tempest-fg-default);
+  font-family: var(--tempest-font-sans, "Geist", sans-serif);
+  font-feature-settings: "tnum" 1;
+  outline: none;
+  pointer-events: auto;
+  transition: background 0.28s ease, border-color 0.28s ease, box-shadow 0.4s ease;
+  -webkit-app-region: no-drag;
+}
+
+.island[data-open] {
+  border-color: var(--tempest-island-border-open);
+  background: var(--tempest-island-bg-open);
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.09),
+    0 1px 2px var(--tempest-ui-shadow-sm),
+    0 16px 40px -8px var(--tempest-ui-shadow-lg);
+  -webkit-backdrop-filter: blur(24px) saturate(180%);
+  backdrop-filter: blur(24px) saturate(180%);
+}
+
+/* ─── Tone ─────────────────────────────────────────────────────────────────── */
+
+.island[data-level="ok"],
+.island-row[data-level="ok"] {
+  --island-tone: var(--tempest-accent-green);
+}
+
+.island[data-level="warn"],
+.island-row[data-level="warn"] {
+  --island-tone: var(--tempest-accent-yellow);
+}
+
+.island[data-level="crit"],
+.island-row[data-level="crit"] {
+  --island-tone: var(--tempest-accent-red);
+}
+
+/* ─── Collapsed pill ───────────────────────────────────────────────────────── */
+
+.island-pill {
+  display: flex;
+  height: 22px;
+  align-items: center;
+  gap: 8px;
+  padding: 0 9px;
+}
+
+/* Fill ring: a conic arc masked to an annulus. One element, no SVG. */
+.island-gauge {
+  width: 13px;
+  height: 13px;
+  flex-shrink: 0;
+  border-radius: 50%;
+  background: conic-gradient(
+    from -90deg,
+    var(--island-tone) calc(var(--fill, 0) * 1%),
+    var(--tempest-bg-hover) 0
+  );
+  -webkit-mask: radial-gradient(closest-side, transparent 57%, #000 58%);
+  mask: radial-gradient(closest-side, transparent 57%, #000 58%);
+}
+
+.island[data-level="crit"] .island-gauge {
+  animation: island-breathe 2s ease-in-out infinite;
+}
+
+@keyframes island-breathe {
+  50% { opacity: 0.4; }
+}
+
+.island-peak {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 11px;
+  line-height: 1;
+  white-space: nowrap;
+}
+
+.island-peak-label {
+  color: var(--tempest-fg-muted);
+  font-weight: 500;
+  letter-spacing: -0.005em;
+}
+
+.island-peak-pct {
+  color: var(--island-tone);
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+}
+
+/* ─── Open panel ───────────────────────────────────────────────────────────── */
+
+/* The only measurement in the file: bars are proportional, so the track needs a
+   floor. A longer label still widens the panel past it. */
+.island-panel {
+  min-width: 236px;
+  padding: 11px 13px 13px;
+}
+
+.island-title {
+  margin-bottom: 10px;
+  color: var(--tempest-fg-subtle);
+  font-size: 9px;
+  font-weight: 600;
+  letter-spacing: 0.09em;
+  text-transform: uppercase;
+}
+
+.island-row + .island-row {
+  margin-top: 12px;
+}
+
+.island-row-head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 10px;
+  margin-bottom: 6px;
+}
+
+.island-row-label {
+  overflow: hidden;
+  color: var(--tempest-fg-default);
+  font-size: 11.5px;
+  font-weight: 500;
+  letter-spacing: -0.008em;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.island-row-pct {
+  flex-shrink: 0;
+  color: var(--island-tone);
+  font-size: 11px;
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+}
+
+.island-bar {
+  height: 3px;
+  overflow: hidden;
+  border-radius: 999px;
+  background: var(--tempest-bg-hover);
+}
+
+/* Full width, scaled by the spring — so the fill animates on the compositor
+   rather than relaying out the track on every frame. */
+.island-bar-fill {
+  width: 100%;
+  height: 100%;
+  border-radius: inherit;
+  background: var(--island-tone);
+  transform-origin: left;
+}
+
+.island-row-reset {
+  margin-top: 6px;
+  color: var(--tempest-fg-subtle);
+  font-size: 10px;
+  font-variant-numeric: tabular-nums;
+  letter-spacing: 0.005em;
+  line-height: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .island {
+    transition: none;
+  }
+
+  .island[data-level="crit"] .island-gauge {
+    animation: none;
+  }
+}
diff --git a/src/components/DynamicIsland.tsx b/src/components/DynamicIsland.tsx
new file mode 100644
index 0000000..c5aa7d6
--- /dev/null
+++ b/src/components/DynamicIsland.tsx
@@ -0,0 +1,116 @@
+import { useState, type CSSProperties } from "react";
+import { AnimatePresence, motion, useReducedMotion, type Transition, type Variants } from "motion/react";
+import { formatReset, levelOf, pct, peakQuota, type QuotaWindow } from "../lib/quota";
+import "./DynamicIsland.css";
+
+/** Arrives fast, overshoots a little, settles. Interruptible mid-flight. */
+const SPRING: Transition = { type: "spring", stiffness: 420, damping: 36, mass: 0.9 };
+
+const PANEL: Variants = {
+  hidden: { opacity: 0 },
+  shown: { opacity: 1, transition: { staggerChildren: 0.045, delayChildren: 0.05 } },
+};
+
+const ROW: Variants = {
+  hidden: { opacity: 0, y: 8 },
+  shown: { opacity: 1, y: 0 },
+};
+
+/**
+ * Toolbar island for live rate-limit windows.
+ *
+ * Quiet when there is room — a fill ring and nothing else. As a window fills it
+ * widens and names the one that is filling. Hover (or focus) opens every window
+ * with its bar and reset time.
+ *
+ * Every size here comes from content: `layout` morphs the shape to whatever the
+ * labels need, so nothing is a hardcoded width waiting to truncate.
+ *
+ * Presentational: no polling, no fetching. Renders nothing without data, so it
+ * is inert until a reader supplies `quotas`.
+ */
+export function DynamicIsland({ quotas }: { quotas: QuotaWindow[] }) {
+  const [open, setOpen] = useState(false);
+  const still = useReducedMotion();
+  const spring = still ? { duration: 0 } : SPRING;
+
+  const peak = peakQuota(quotas);
+  if (!peak) return null;
+
+  const level = levelOf(peak.used);
+
+  return (
+    // Full-width, click-through anchor: the island is flex-centred inside it, so
+    // `layout` owns the element's own transform without fighting a translate.
+    <div className="island-anchor">
+      <motion.div
+        layout
+        className="island"
+        data-level={level}
+        data-open={open || undefined}
+        tabIndex={0}
+        role="group"
+        aria-label={`Usage limits — ${peak.label} at ${pct(peak.used)} percent`}
+        onMouseEnter={() => setOpen(true)}
+        onMouseLeave={() => setOpen(false)}
+        onFocus={() => setOpen(true)}
+        onBlur={() => setOpen(false)}
+        animate={{ borderRadius: open ? 18 : 999 }}
+        transition={spring}
+      >
+        <AnimatePresence mode="popLayout" initial={false}>
+          {!open ? (
+            <motion.div
+              key="pill"
+              layout="position"
+              className="island-pill"
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+              transition={{ duration: still ? 0 : 0.14 }}
+            >
+              {/* --fill drives the conic arc; the ring is one element, no SVG. */}
+              <span className="island-gauge" style={{ "--fill": pct(peak.used) } as CSSProperties} />
+              {level !== "ok" && (
+                <span className="island-peak">
+                  <span className="island-peak-label">{peak.label}</span>
+                  <span className="island-peak-pct">{pct(peak.used)}%</span>
+                </span>
+              )}
+            </motion.div>
+          ) : (
+            <motion.div
+              key="panel"
+              layout="position"
+              className="island-panel"
+              variants={PANEL}
+              initial="hidden"
+              animate="shown"
+              exit="hidden"
+              transition={{ duration: still ? 0 : 0.18 }}
+            >
+              <motion.div className="island-title" variants={ROW}>Usage</motion.div>
+              {quotas.map(q => (
+                <motion.div className="island-row" key={q.id} data-level={levelOf(q.used)} variants={ROW}>
+                  <div className="island-row-head">
+                    <span className="island-row-label">{q.label}</span>
+                    <span className="island-row-pct">{pct(q.used)}%</span>
+                  </div>
+                  <div className="island-bar">
+                    <motion.div
+                      className="island-bar-fill"
+                      initial={{ scaleX: 0 }}
+                      animate={{ scaleX: pct(q.used) / 100 }}
+                      transition={still ? { duration: 0 } : { ...SPRING, delay: 0.12 }}
+                    />
+                  </div>
+                  <div className="island-row-reset">{formatReset(q.resetsAt)}</div>
+                </motion.div>
+              ))}
+            </motion.div>
+          )}
+        </AnimatePresence>
+      </motion.div>
+    </div>
+  );
+}
diff --git a/src/components/ProjectSettingsPanel/PermissionsSection.tsx b/src/components/ProjectSettingsPanel/PermissionsSection.tsx
index 9a04566..731790a 100644
--- a/src/components/ProjectSettingsPanel/PermissionsSection.tsx
+++ b/src/components/ProjectSettingsPanel/PermissionsSection.tsx
@@ -5,7 +5,9 @@ export function PermissionsSection({ value, onChange }: {
   onChange: (v: ProjectSettings["permissions"]) => void;
 }) {
   const allowSkip = value.allowSkipPermissions;
-  const setAllowSkip = (next: boolean) => onChange({ allowSkipPermissions: next });
+  const setAllowSkip = (next: boolean) => onChange({ ...value, allowSkipPermissions: next });
+  const allowHooks = value.allowRepoHooks;
+  const setAllowHooks = (next: boolean) => onChange({ ...value, allowRepoHooks: next });
 
   return (
     <div className="sp-section">
@@ -32,6 +34,26 @@ export function PermissionsSection({ value, onChange }: {
             <span className="sp-toggle-thumb" />
           </button>
         </div>
+
+        <div className="sp-toggle-row" onClick={() => setAllowHooks(!allowHooks)}>
+          <div className="sp-toggle-text">
+            <span className="sp-toggle-label">Run worktree hooks without asking</span>
+            <span className="sp-toggle-desc">
+              Runs this repo's{" "}
+              <code className="sp-code">setup</code> and <code className="sp-code">teardown</code>{" "}
+              commands from <code className="sp-code">tempest.yml</code> automatically. Off, you are
+              shown the exact commands and asked each time.
+            </span>
+          </div>
+          <button
+            className={`sp-toggle${allowHooks ? " sp-toggle--on" : ""}`}
+            onClick={(e) => { e.stopPropagation(); setAllowHooks(!allowHooks); }}
+            role="switch"
+            aria-checked={allowHooks}
+          >
+            <span className="sp-toggle-thumb" />
+          </button>
+        </div>
       </div>
     </div>
   );
diff --git a/src/components/ProjectSettingsPanel/useProjectSettings.ts b/src/components/ProjectSettingsPanel/useProjectSettings.ts
index 58f38c0..10aff45 100644
--- a/src/components/ProjectSettingsPanel/useProjectSettings.ts
+++ b/src/components/ProjectSettingsPanel/useProjectSettings.ts
@@ -11,7 +11,7 @@ export interface ProjectSettings {
   sandbox: { mode: "off" | "monitor" | "enforce" };
   network: { policy: "permissive" | "restrictive"; allowHosts: string[]; blockHosts: string[] };
   filesystem: { rwPaths: string[]; roPaths: string[] };
-  permissions: { allowSkipPermissions: boolean };
+  permissions: { allowSkipPermissions: boolean; allowRepoHooks: boolean };
   agents: { permitted: string[] };
   database: { isolationEnabled: boolean };
   /// OS-level quotas per session. `null` leaves a limit at the OS default.
@@ -28,7 +28,9 @@ const DEFAULTS: ProjectSettings = {
   sandbox: { mode: "monitor" },
   network: { policy: "permissive", allowHosts: ["api.anthropic.com", "*.github.com"], blockHosts: [] },
   filesystem: { rwPaths: ["."], roPaths: [] },
-  permissions: { allowSkipPermissions: true },
+  // Hooks run commands the repo checked in, so they are opt-in: off means the
+  // user is asked before each run, never that the commands run unannounced.
+  permissions: { allowSkipPermissions: true, allowRepoHooks: false },
   agents: { permitted: getAgents().map((a) => a.hint) },
   database: { isolationEnabled: false },
   resources: { maxMemoryMb: null, maxProcesses: null, maxDiskWriteMb: null, cpuWeight: null },
diff --git a/src/components/SettingsPanel/SecuritySection.tsx b/src/components/SettingsPanel/SecuritySection.tsx
index 45646ad..20eb9cb 100644
--- a/src/components/SettingsPanel/SecuritySection.tsx
+++ b/src/components/SettingsPanel/SecuritySection.tsx
@@ -1,7 +1,13 @@
 import { useSettings, updateSetting } from "../../store/appSettings";
+import { setPreciseAgentStatus } from "../../store/agentHooks";
 
 export function SecuritySection() {
   const s = useSettings();
+  const togglePreciseStatus = () => {
+    const next = !s.preciseAgentStatus;
+    updateSetting("preciseAgentStatus", next);
+    void setPreciseAgentStatus(next);
+  };
   return (
     <div className="sp-section">
       <div className="sp-section-heading">Security</div>
@@ -46,6 +52,27 @@ export function SecuritySection() {
             <span className="sp-toggle-thumb" />
           </button>
         </div>
+
+        <div className="sp-toggle-row" onClick={togglePreciseStatus}>
+          <div className="sp-toggle-text">
+            <span className="sp-toggle-label">Precise agent status (hooks)</span>
+            <span className="sp-toggle-desc">
+              Install a managed lifecycle hook into supported agents' own configs so
+              working / waiting-for-you / done is driven by real events instead of
+              scraping terminal output. Preserves your existing hooks. Off removes the
+              managed hooks and falls back to the heuristic. Supported: Claude Code,
+              Gemini, Cursor, Copilot, Antigravity, Codex, Hermes, Opencode.
+            </span>
+          </div>
+          <button
+            className={`sp-toggle${s.preciseAgentStatus ? " sp-toggle--on" : ""}`}
+            onClick={(e) => { e.stopPropagation(); togglePreciseStatus(); }}
+            role="switch"
+            aria-checked={s.preciseAgentStatus}
+          >
+            <span className="sp-toggle-thumb" />
+          </button>
+        </div>
       </div>
     </div>
   );
diff --git a/src/components/Toolbar.tsx b/src/components/Toolbar.tsx
index 23538f0..374ba2c 100644
--- a/src/components/Toolbar.tsx
+++ b/src/components/Toolbar.tsx
@@ -1,12 +1,16 @@
 import { Mark } from "../assets/Mark";
+import { DynamicIsland } from "./DynamicIsland";
+import type { QuotaWindow } from "../lib/quota";
 
 interface Props {
   tabsMode: "designed" | "tabbed" | "ver1" | "designer";
   projectName: string;
   rightActions: React.ReactNode;
+  /** Empty until a reader supplies it; the island renders nothing then. */
+  quotas?: QuotaWindow[];
 }
 
-export function Toolbar({ tabsMode, projectName, rightActions }: Props) {
+export function Toolbar({ tabsMode, projectName, rightActions, quotas = [] }: Props) {
   const modeClass = tabsMode === "tabbed" ? " tabs-tabbed"
     : tabsMode === "ver1"      ? " tabs-ver1"
     : tabsMode === "designer"  ? " tabs-designer"
@@ -26,6 +30,10 @@ export function Toolbar({ tabsMode, projectName, rightActions }: Props) {
         )}
       </div>
 
+      {/* Centred on the bar itself, not between the ends — so it holds the
+          middle no matter how wide the project name or the actions slot get. */}
+      <DynamicIsland quotas={quotas} />
+
       {/* Right end — actions slot */}
       <div className="bar-end">
         {rightActions}
diff --git a/src/components/WorkspaceView.css b/src/components/WorkspaceView.css
index 0221041..ed1f637 100644
--- a/src/components/WorkspaceView.css
+++ b/src/components/WorkspaceView.css
@@ -1434,6 +1434,54 @@
   flex-shrink: 0;
 }
 
+/* tempest.yml worktree hooks — consent prompt and run progress */
+.hook-consent,
+.hook-progress {
+  width: 420px;
+}
+
+.hook-consent .naming-modal-desc strong {
+  color: var(--tempest-fg-default);
+  font-weight: 500;
+}
+
+.hook-cmd-list {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  max-height: 180px;
+  overflow-y: auto;
+  padding: 10px;
+  background: var(--tempest-bg-editor);
+  border: 1px solid var(--tempest-border-default);
+  border-radius: 6px;
+}
+
+.hook-cmd,
+.hook-progress-line {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--tempest-fg-default);
+  white-space: pre-wrap;
+  word-break: break-all;
+}
+
+.hook-progress-line {
+  display: block;
+  color: var(--tempest-fg-subtle);
+  padding: 10px;
+  background: var(--tempest-bg-editor);
+  border: 1px solid var(--tempest-border-default);
+  border-radius: 6px;
+  max-height: 96px;
+  overflow: hidden;
+}
+
+.hook-spinner {
+  animation: spin 0.75s linear infinite;
+  flex-shrink: 0;
+}
+
 @keyframes spin {
   from { transform: rotate(0deg); }
   to   { transform: rotate(360deg); }
diff --git a/src/components/WorkspaceView.tsx b/src/components/WorkspaceView.tsx
index 901438a..78db241 100644
--- a/src/components/WorkspaceView.tsx
+++ b/src/components/WorkspaceView.tsx
@@ -49,6 +49,7 @@ import {
   SunMoon,
   GitBranch,
   Cog,
+  Loader,
 } from "lucide-react";
 import { setWorkState, clearWorkState, getWorkState, setAttention, getAttention } from "../store/workState";
 import { useKeybindings, matchesEvent, formatShortcut } from "../store/keybindings";
@@ -77,9 +78,11 @@ import { StatusBar } from "./StatusBar";
 import { UpdateNotice } from "./UpdateNotice";
 import { useAvailableUpdate, dismissUpdate, startUpdateChecks, installUpdate, openReleaseNotes } from "../store/updates";
 import { startModelManifestFetch } from "../lib/remoteConfig";
+import { startAgentHooks } from "../store/agentHooks";
 import { AtlasIndexModal } from "./AtlasIndexModal";
 import { KnowledgeBasePage } from "./KnowledgeBasePage";
 import { Toolbar } from "./Toolbar";
+import { SAMPLE_QUOTAS } from "../lib/quota";
 import AgentTabs from "./AgentTabs";
 import IconCapsule from "./IconCapsule";
 import { SidebarWorkBadge, ProjectWorkBadge, AttentionPill } from "./SessionBadges";
@@ -113,6 +116,7 @@ function sbRows(live: Session[], ghosts: WorktreeSession[]): SbRow[] {
 }
 
 import { folderName, timeAgo } from "../lib/format";
+import { getHookCommands, runHook, type HookKind } from "../lib/worktreeHooks";
 import { buildAgentArgs } from "../lib/agentArgs";
 import {
   type SplitDir,
@@ -246,13 +250,21 @@ export function WorkspaceView({ zen, name, path }: Props) {
 
   // Delete workspace dialog state
   const [deleteDialog, setDeleteDialog] = useState<DeleteDialogState | null>(null);
+  /// Pending consent for a repo's tempest.yml hook. `resolve` is the awaiting
+  /// hook runner — answering the dialog is what lets it continue.
+  const [hookConsent, setHookConsent] = useState<
+    { kind: HookKind; commands: string[]; cwd: string; resolve: (ok: boolean) => void } | null
+  >(null);
+  /// Latest output line while a hook is running, shown in whichever modal
+  /// triggered it.
+  const [hookRun, setHookRun] = useState<{ kind: HookKind; line: string } | null>(null);
   /// Message from a project-policy refusal at spawn time, or a failed update.
   /// Rendered as a dismissible notice near the bottom of the window.
   const [policyError, setPolicyError] = useState<string | null>(null);
 
   // Update checks: one now, then daily for as long as the app stays open.
   const availableUpdate = useAvailableUpdate();
-  useEffect(() => { startUpdateChecks(); void startModelManifestFetch(); }, []);
+  useEffect(() => { startUpdateChecks(); void startModelManifestFetch(); void startAgentHooks(); }, []);
 
   /// The Overview footer has to stay mounted while it retracts, so ✕ sets this
   /// instead of dismissing outright; the dismissal lands on animation end.
@@ -735,6 +747,12 @@ export function WorkspaceView({ zen, name, path }: Props) {
     const { worktree, projectPath, projectId, sessionId, branchName } = deleteDialog;
     setDeleteDialog((d) => d ? { ...d, loading: true, error: null } : null);
     try {
+      // Teardown gets its turn while the worktree still exists. Failure is
+      // reported but never blocks the delete: the directory is going away, and
+      // a broken cleanup command must not strand a workspace on disk.
+      const failure = await runWorktreeHook("teardown", projectPath, projectId, worktree.path);
+      if (failure) console.warn(`[tempest.yml] teardown failed: ${failure}`);
+
       // Single Rust round-trip: kill the PTY child, wait for it to exit, then
       // remove the worktree directory. Collapsing these two operations into one
       // invoke is the fix for the delete race — there is no longer any window
@@ -911,7 +929,10 @@ export function WorkspaceView({ zen, name, path }: Props) {
           sandbox: sandboxParam,
           policy: policyParam,
           dbIsolation: projectSettings.database.isolationEnabled,
-          env: tempestConfig.env ?? null,
+          // TEMPEST_SESSION lets an installed agent hook (see src/lib/agentHooks)
+          // attribute its lifecycle POSTs back to this exact session, without
+          // touching the PTY spawn internals. Merged over tempest.yml env.
+          env: { ...(tempestConfig.env ?? {}), TEMPEST_SESSION: sessionId },
           onEvent: channel,
         });
       } catch (e) {
@@ -1182,6 +1203,48 @@ export function WorkspaceView({ zen, name, path }: Props) {
     return name;
   }
 
+  // ── tempest.yml worktree hooks ─────────────────────────────────────────────
+  // `setup` runs once the worktree exists, `teardown` before it is removed.
+  // The commands come from a file the repo carries, so unless the project has
+  // opted into running them unprompted, the user is shown the exact commands
+  // and asked. Declining is not an error — the worktree is simply left as git
+  // made it.
+  //
+  // Returns the failure message, or null when the hook ran clean / was skipped.
+  async function runWorktreeHook(
+    kind: HookKind,
+    projectPath: string,
+    projectId: string,
+    cwd: string,
+  ): Promise<string | null> {
+    let commands: string[];
+    try {
+      commands = await getHookCommands(projectPath, kind);
+    } catch {
+      return null; // unreadable config is "no hooks", same as everywhere else
+    }
+    if (!commands.length) return null;
+
+    const settings = await loadProjectSettings(projectId, projectPath);
+    if (!settings.permissions.allowRepoHooks) {
+      const approved = await new Promise<boolean>((resolve) =>
+        setHookConsent({ kind, commands, cwd, resolve })
+      );
+      setHookConsent(null);
+      if (!approved) return null;
+    }
+
+    setHookRun({ kind, line: commands[0] });
+    try {
+      await runHook(projectPath, kind, cwd, (line) => setHookRun({ kind, line }));
+      return null;
+    } catch (e) {
+      return String(e);
+    } finally {
+      setHookRun(null);
+    }
+  }
+
   async function launchTerminalWorktree() {
     const activePath = getActivePath();
     const workingProjectId = pendingProjectId;
@@ -1227,6 +1290,11 @@ export function WorkspaceView({ zen, name, path }: Props) {
         const result = await createWorktree({ projectPath: activePath, name: branchName, existingBranch });
         worktreePath = result.path;
         addWorktreeToState({ name: branchName, path: worktreePath }, workingProjectId);
+        // The worktree exists either way; a failed setup leaves it in the
+        // sidebar and keeps the modal open with the reason, rather than opening
+        // a session into a half-prepared checkout.
+        const failure = await runWorktreeHook("setup", activePath, workingProjectId ?? "", worktreePath);
+        if (failure) { setTerminalError(failure); return; }
       }
       await openSession(sessionName, worktreePath, workingProjectId ?? "", agent, prompt, undefined, undefined, undefined, undefined, false, undefined, undefined);
       resetTerminalModal();
@@ -1254,6 +1322,8 @@ export function WorkspaceView({ zen, name, path }: Props) {
       await gitInit(activePath);
       const result = await createWorktree({ projectPath: activePath, name: fullName });
       addWorktreeToState({ name: fullName, path: result.path }, workingProjectId);
+      const failure = await runWorktreeHook("setup", activePath, workingProjectId ?? "", result.path);
+      if (failure) { setTerminalError(failure); return; }
       await openSession(sessionName, result.path, workingProjectId ?? "", agent, prompt, undefined);
       resetTerminalModal();
     } catch (e) {
@@ -1767,6 +1837,7 @@ export function WorkspaceView({ zen, name, path }: Props) {
       <Toolbar
         tabsMode={tabsMode}
         projectName={activeSessionProject?.name ?? projects[0]?.name ?? ""}
+        quotas={import.meta.env.DEV ? SAMPLE_QUOTAS : []}
         rightActions={
           <>
             <Tooltip content="Open diff view" placement="bottom">
@@ -2928,6 +2999,58 @@ export function WorkspaceView({ zen, name, path }: Props) {
         />
       )}
 
+      {/* Consent for a repo-supplied hook — the commands are shown verbatim,
+          because approving this runs code the repo carries, not the user's. */}
+      {hookConsent && createPortal(
+        <div className="naming-modal-overlay">
+          <div className="naming-modal hook-consent" onClick={(e) => e.stopPropagation()}>
+            <div className="naming-modal-header">
+              <TerminalSquare size={15} />
+              Run this repo's {hookConsent.kind} commands?
+            </div>
+            <p className="naming-modal-desc">
+              <strong>tempest.yml</strong> in this repository asks to run the following in{" "}
+              <strong>{folderName(hookConsent.cwd)}</strong>. These commands come from the repo, not
+              from Tempest.
+            </p>
+            <div className="hook-cmd-list">
+              {hookConsent.commands.map((c, i) => (
+                <code key={i} className="hook-cmd">{c}</code>
+              ))}
+            </div>
+            <div className="naming-modal-actions">
+              <button
+                className="naming-modal-btn naming-modal-btn--cancel"
+                onClick={() => hookConsent.resolve(false)}
+              >
+                Skip
+              </button>
+              <button
+                className="naming-modal-btn naming-modal-btn--create"
+                onClick={() => hookConsent.resolve(true)}
+              >
+                Run
+              </button>
+            </div>
+          </div>
+        </div>,
+        document.body
+      )}
+
+      {/* Hook progress — both callers block on it, so one overlay serves both. */}
+      {hookRun && createPortal(
+        <div className="naming-modal-overlay">
+          <div className="naming-modal hook-progress">
+            <div className="naming-modal-header">
+              <Loader size={15} className="hook-spinner" />
+              Running {hookRun.kind}…
+            </div>
+            <code className="hook-progress-line">{hookRun.line}</code>
+          </div>
+        </div>,
+        document.body
+      )}
+
       {showTerminalNaming && (
         <TerminalNamingModal
           pendingAgent={pendingAgent}
diff --git a/src/lib/agentHooks/adapters/antigravity.ts b/src/lib/agentHooks/adapters/antigravity.ts
new file mode 100644
index 0000000..d7b04e0
--- /dev/null
+++ b/src/lib/agentHooks/adapters/antigravity.ts
@@ -0,0 +1,205 @@
+// Antigravity hook adapter.
+//
+// Config: ~/.gemini/config/hooks.json (NOT the Gemini CLI settings file), under a
+// dedicated bundle key so we never touch other hook bundles. Antigravity spawns
+// the hook command as argv[0], so on Windows each event gets a wrapper .cmd that
+// sets the event name in the environment and calls one core script; on posix the
+// core is invoked with the event as an env prefix. The event reaches the server
+// via X-Tempest-Event. Antigravity requires the hook to print a JSON object on
+// stdout (`{"decision":""}` for Stop, else `{}`) or it stalls.
+//
+// We subscribe the observational events (PreInvocation/PostInvocation/Stop/
+// PostToolUse) — NOT PreToolUse, whose hook gates tool permission and would let
+// a status hook block the user. So there's no permission signal here:
+// coversWaiting = false keeps the PTY attention path live.
+
+import type { AdapterInstall, HookAdapter, HookPaths, HookState, JsonObject } from "../types";
+import { wrapBarePathOrEncoded, wrapPosix } from "../wrappers.ts";
+import { joinNative } from "../paths.ts";
+
+const BUNDLE_KEY = "tempest-status";
+const CORE_STEM = "tempest-antigravity-hook";
+const EVENT_ENV = "TEMPEST_HOOK_EVENT";
+
+interface AntigravityEvent {
+  name: string;
+  schema: "direct" | "tool";
+  wrapper: string; // Windows per-event wrapper filename
+}
+
+const EVENTS: AntigravityEvent[] = [
+  { name: "PreInvocation", schema: "direct", wrapper: "tempest-antigravity-pre-invocation.cmd" },
+  { name: "PostInvocation", schema: "direct", wrapper: "tempest-antigravity-post-invocation.cmd" },
+  { name: "Stop", schema: "direct", wrapper: "tempest-antigravity-stop.cmd" },
+  { name: "PostToolUse", schema: "tool", wrapper: "tempest-antigravity-post-tool-use.cmd" },
+];
+
+const TIMEOUT_SECONDS = 10;
+
+// Any Tempest-owned Antigravity command (core script or a per-event wrapper).
+function isManaged(command: string | undefined): boolean {
+  return !!command && command.replace(/\\/g, "/").includes("tempest-antigravity");
+}
+
+function coreScript(paths: HookPaths): string {
+  if (paths.windows) {
+    return [
+      "@echo off",
+      "setlocal",
+      'if /I "%TEMPEST_HOOK_EVENT%"=="Stop" (echo {"decision":""}) else (echo {})',
+      `if exist "${paths.endpointCmd}" call "${paths.endpointCmd}" >nul 2>nul`,
+      `if "%TEMPEST_HOOK_PORT%"=="" exit /b 0`,
+      `if "%TEMPEST_SESSION%"=="" exit /b 0`,
+      `"%SystemRoot%\\System32\\curl.exe" -sS -X POST "http://127.0.0.1:%TEMPEST_HOOK_PORT%/hook/antigravity" --connect-timeout 0.5 --max-time 1.5 -H "X-Tempest-Token: %TEMPEST_HOOK_TOKEN%" -H "X-Tempest-Session: %TEMPEST_SESSION%" -H "X-Tempest-Event: %TEMPEST_HOOK_EVENT%" -H "Content-Type: application/json" --data-binary @- >nul 2>nul`,
+      "exit /b 0",
+      "",
+    ].join("\r\n");
+  }
+  return [
+    "#!/bin/sh",
+    'if [ "$TEMPEST_HOOK_EVENT" = "Stop" ]; then printf \'{"decision":""}\\n\'; else printf \'{}\\n\'; fi',
+    'if [ -r "' + paths.endpointEnv + '" ]; then . "' + paths.endpointEnv + '" 2>/dev/null || :; fi',
+    'if [ -z "$TEMPEST_HOOK_PORT" ] || [ -z "$TEMPEST_SESSION" ]; then exit 0; fi',
+    'curl -sS -X POST "http://127.0.0.1:${TEMPEST_HOOK_PORT}/hook/antigravity" \\',
+    "  --connect-timeout 0.5 --max-time 1.5 \\",
+    '  -H "X-Tempest-Token: ${TEMPEST_HOOK_TOKEN}" \\',
+    '  -H "X-Tempest-Session: ${TEMPEST_SESSION}" \\',
+    '  -H "X-Tempest-Event: ${TEMPEST_HOOK_EVENT}" \\',
+    '  -H "Content-Type: application/json" \\',
+    "  --data-binary @- >/dev/null 2>&1 || true",
+    "exit 0",
+    "",
+  ].join("\n");
+}
+
+// Windows wrapper: set the event env, call the core; if the core is missing,
+// still satisfy Antigravity's stdout contract so it never stalls.
+function wrapperScript(event: string, coreFileName: string): string {
+  return [
+    "@echo off",
+    "setlocal",
+    `set "${EVENT_ENV}=${event}"`,
+    `set "CORE=%~dp0${coreFileName}"`,
+    'if exist "%CORE%" (',
+    '  call "%CORE%"',
+    "  exit /b 0",
+    ")",
+    'if /I "%' + EVENT_ENV + '%"=="Stop" (echo {"decision":""}) else (echo {})',
+    "exit /b 0",
+    "",
+  ].join("\r\n");
+}
+
+interface HookDef {
+  matcher?: string;
+  command?: string;
+  hooks?: { command?: string; [k: string]: unknown }[];
+  [k: string]: unknown;
+}
+
+function defManaged(def: HookDef): boolean {
+  return isManaged(def.command) || (Array.isArray(def.hooks) && def.hooks.some((h) => isManaged(h.command)));
+}
+
+export const antigravityAdapter: HookAdapter = {
+  id: "antigravity",
+  coversWaiting: false,
+
+  plan(paths: HookPaths): AdapterInstall {
+    const coreFileName = `${CORE_STEM}.${paths.windows ? "cmd" : "sh"}`;
+    const corePath = joinNative(paths.windows, paths.hooksDir, coreFileName);
+
+    const scripts = [{ path: corePath, content: coreScript(paths), executable: !paths.windows }];
+    if (paths.windows) {
+      for (const ev of EVENTS) {
+        scripts.push({
+          path: joinNative(true, paths.hooksDir, ev.wrapper),
+          content: wrapperScript(ev.name, coreFileName),
+          executable: false,
+        });
+      }
+    }
+
+    const commandFor = (ev: AntigravityEvent): string =>
+      paths.windows
+        ? wrapBarePathOrEncoded(joinNative(true, paths.hooksDir, ev.wrapper))
+        : wrapPosix(corePath, { [EVENT_ENV]: ev.name });
+
+    const defFor = (ev: AntigravityEvent): HookDef =>
+      ev.schema === "tool"
+        ? { matcher: "*", hooks: [{ type: "command", command: commandFor(ev), timeout: TIMEOUT_SECONDS }] }
+        : { type: "command", command: commandFor(ev), timeout: TIMEOUT_SECONDS };
+
+    const bundleOf = (config: JsonObject): Record<string, HookDef[]> => {
+      const b = config[BUNDLE_KEY];
+      return b && typeof b === "object" && !Array.isArray(b) ? { ...(b as Record<string, HookDef[]>) } : {};
+    };
+    const sweep = (bundle: Record<string, HookDef[]>): Record<string, HookDef[]> => {
+      const next: Record<string, HookDef[]> = {};
+      for (const [name, defs] of Object.entries(bundle)) {
+        if (!Array.isArray(defs)) {
+          next[name] = defs;
+          continue;
+        }
+        const cleaned = defs.filter((d) => !defManaged(d));
+        if (cleaned.length > 0) next[name] = cleaned;
+      }
+      return next;
+    };
+
+    return {
+      scripts,
+      configs: [
+        {
+          path: joinNative(paths.windows, paths.home, ".gemini", "config", "hooks.json"),
+          apply: (raw) => {
+            const config = parseObj(raw);
+            if (config === null) return null;
+            const bundle = sweep(bundleOf(config));
+            for (const ev of EVENTS) bundle[ev.name] = [...(bundle[ev.name] ?? []), defFor(ev)];
+            return serialize({ ...config, [BUNDLE_KEY]: bundle });
+          },
+          remove: (raw) => {
+            if (raw === null || raw.trim() === "") return null;
+            const config = parseObj(raw);
+            if (config === null) return null;
+            const before = config[BUNDLE_KEY];
+            if (!before || typeof before !== "object") return null;
+            const bundle = sweep(bundleOf(config));
+            const next: JsonObject = { ...config };
+            if (Object.keys(bundle).length === 0) delete next[BUNDLE_KEY];
+            else next[BUNDLE_KEY] = bundle;
+            const out = serialize(next);
+            return out === serialize(config) ? null : out;
+          },
+        },
+      ],
+    };
+  },
+
+  parse(body: unknown): HookState | null {
+    if (!body || typeof body !== "object") return null;
+    const o = body as Record<string, unknown>;
+    const event = o.hook_event_name;
+    if (event === "Stop") {
+      const fullyIdle = o.fullyIdle ?? o.fully_idle;
+      return fullyIdle === false ? "working" : "done";
+    }
+    if (event === "PreInvocation" || event === "PostInvocation" || event === "PostToolUse") return "working";
+    return null;
+  },
+};
+
+function parseObj(raw: string | null): JsonObject | null {
+  if (raw === null || raw.trim() === "") return {};
+  try {
+    const p = JSON.parse(raw);
+    return p && typeof p === "object" && !Array.isArray(p) ? (p as JsonObject) : null;
+  } catch {
+    return null;
+  }
+}
+
+function serialize(config: JsonObject): string {
+  return JSON.stringify(config, null, 2) + "\n";
+}
diff --git a/src/lib/agentHooks/adapters/claude.ts b/src/lib/agentHooks/adapters/claude.ts
new file mode 100644
index 0000000..08c0718
--- /dev/null
+++ b/src/lib/agentHooks/adapters/claude.ts
@@ -0,0 +1,107 @@
+// Claude Code hook adapter.
+//
+// Claude runs hook commands through a shell (Git Bash on Windows), delivering the
+// event as JSON on the hook's stdin. We register a managed script on the events
+// that bound a turn, a tool call, or a permission prompt; the script forwards the
+// stdin payload to Tempest's loopback server tagged with the session id we
+// injected at spawn (`TEMPEST_SESSION`). Docs: docs.anthropic.com Claude Code hooks.
+
+import type { AdapterInstall, HookAdapter, HookPaths, HookState } from "../types";
+// Explicit .ts so the node self-check (installer.check.ts) can import this
+// adapter directly; the bundler tsconfig allows importing .ts extensions.
+import { applyJsonConfig, applyNestedHooks, removeJsonConfig, removeNestedHooks, type NestedEvent } from "../schema.ts";
+import { wrapGitBash, wrapPosix } from "../wrappers.ts";
+import { buildHookScript } from "../script.ts";
+
+// Tool-lifecycle events carry a "*" matcher; the rest are bare lifecycle events.
+const CLAUDE_EVENTS: NestedEvent[] = [
+  { name: "UserPromptSubmit" },
+  { name: "PreToolUse", matcher: true },
+  { name: "PostToolUse", matcher: true },
+  // Newer Claude emits a dedicated PermissionRequest; older builds signal via
+  // Notification. Subscribing both makes the "waiting" signal version-proof.
+  { name: "PermissionRequest", matcher: true },
+  { name: "Notification" },
+  { name: "Stop" },
+];
+
+const SCRIPT_STEM = "tempest-claude-hook";
+
+function fwd(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+function join(sep: string, ...parts: string[]): string {
+  return parts.join(sep);
+}
+
+function readString(o: Record<string, unknown>, key: string): string | undefined {
+  const v = o[key];
+  return typeof v === "string" ? v : undefined;
+}
+
+function isAskUserQuestion(toolName: string | undefined): boolean {
+  return (toolName ?? "").trim().toLowerCase() === "askuserquestion";
+}
+
+export const claudeAdapter: HookAdapter = {
+  id: "claude",
+  // Claude emits PermissionRequest / permission Notifications → full authority.
+  coversWaiting: true,
+
+  plan(paths: HookPaths): AdapterInstall {
+    const sep = paths.windows ? "\\" : "/";
+    const scriptFileName = `${SCRIPT_STEM}.${paths.windows ? "cmd" : "sh"}`;
+    const scriptPathNative = join(sep, paths.hooksDir, scriptFileName);
+    const scriptContent = buildHookScript({
+      route: "claude",
+      endpointCmd: paths.endpointCmd,
+      endpointEnv: paths.endpointEnv,
+      windows: paths.windows,
+    });
+    const command = paths.windows ? wrapGitBash(fwd(scriptPathNative)) : wrapPosix(scriptPathNative);
+    return {
+      scripts: [{ path: scriptPathNative, content: scriptContent, executable: !paths.windows }],
+      configs: [
+        {
+          path: join(sep, paths.home, ".claude", "settings.json"),
+          apply: (raw) => applyJsonConfig(raw, (c) => applyNestedHooks(c, command, scriptFileName, CLAUDE_EVENTS)),
+          remove: (raw) => removeJsonConfig(raw, (c) => removeNestedHooks(c, scriptFileName)),
+        },
+      ],
+    };
+  },
+
+  parse(body: unknown): HookState | null {
+    if (!body || typeof body !== "object") return null;
+    const o = body as Record<string, unknown>;
+    const event = readString(o, "hook_event_name");
+    const toolName = readString(o, "tool_name");
+    switch (event) {
+      case "UserPromptSubmit":
+        return "working";
+      case "PreToolUse":
+        // Claude blocks on AskUserQuestion for a human answer — surface it as
+        // "needs you", not a spinner that would decay to done.
+        return isAskUserQuestion(toolName) ? "waiting" : "working";
+      case "PostToolUse":
+        return "working";
+      case "PermissionRequest":
+        return "waiting";
+      case "Notification": {
+        const nt = (readString(o, "notification_type") ?? readString(o, "notificationType") ?? "").toLowerCase();
+        if (nt === "permission_prompt" || nt === "elicitation_dialog") return "waiting";
+        const msg = (readString(o, "message") ?? "").toLowerCase();
+        if (msg.includes("permission") || msg.includes("approve") || msg.includes("waiting for your input")) {
+          return "waiting";
+        }
+        // Generic notifications (e.g. idle nudges) aren't a state transition.
+        return null;
+      }
+      case "Stop":
+        return "done";
+      default:
+        return null;
+    }
+  },
+};
diff --git a/src/lib/agentHooks/adapters/codex.ts b/src/lib/agentHooks/adapters/codex.ts
new file mode 100644
index 0000000..468236d
--- /dev/null
+++ b/src/lib/agentHooks/adapters/codex.ts
@@ -0,0 +1,145 @@
+// Codex CLI hook adapter.
+//
+// Two files under ~/.codex: hooks.json declares the hook (PascalCase event keys),
+// and config.toml must trust each handler via a `[hooks.state."<key>"]` block or
+// Codex silently skips it. We merge our managed hook LAST per event (preserving
+// user hooks + their trust positions), record each event's group index, then
+// write matching trust blocks with the reproduced trusted_hash. If the hash ever
+// drifts from Codex's, Codex just ignores the hook and status falls back to PTY.
+// Codex has PermissionRequest + auto-allowed request_user_input → coversWaiting.
+
+import type { AdapterInstall, HookAdapter, HookPaths, JsonObject, HookState } from "../types";
+import { applyJsonConfig, removeJsonConfig } from "../schema.ts";
+import { wrapBarePathOrEncoded, wrapPosix } from "../wrappers.ts";
+import { buildHookScript } from "../script.ts";
+import { joinNative } from "../paths.ts";
+import { CODEX_EVENT_LABEL, upsertTrustBlocks, removeTrustBlocks, type CodexTrustEntry } from "../codexTrust.ts";
+
+// hooks.json event keys (PascalCase). Keep in sync with CODEX_EVENT_LABEL.
+const CODEX_EVENTS = ["SessionStart", "UserPromptSubmit", "PreToolUse", "PermissionRequest", "PostToolUse", "Stop"] as const;
+const SCRIPT_STEM = "tempest-codex-hook";
+const TIMEOUT_SECONDS = 10;
+
+const SNAKE_TO_PASCAL: Record<string, string> = Object.fromEntries(
+  Object.entries(CODEX_EVENT_LABEL).map(([pascal, snake]) => [snake, pascal]),
+);
+
+interface HookDef {
+  matcher?: string;
+  command?: string;
+  hooks?: { command?: string; [k: string]: unknown }[];
+  [k: string]: unknown;
+}
+
+function isManaged(command: string | undefined): boolean {
+  return !!command && command.replace(/\\/g, "/").includes(SCRIPT_STEM);
+}
+
+function defManaged(def: HookDef): boolean {
+  return isManaged(def.command) || (Array.isArray(def.hooks) && def.hooks.some((h) => isManaged(h.command)));
+}
+
+function isAskUserQuestion(name: unknown): boolean {
+  const n = typeof name === "string" ? name.trim().toLowerCase() : "";
+  return n === "askuserquestion" || n === "request_user_input" || n === "requestuserinput";
+}
+
+export const codexAdapter: HookAdapter = {
+  id: "codex",
+  coversWaiting: true,
+
+  plan(paths: HookPaths): AdapterInstall {
+    const scriptFileName = `${SCRIPT_STEM}.${paths.windows ? "cmd" : "sh"}`;
+    const scriptPath = joinNative(paths.windows, paths.hooksDir, scriptFileName);
+    const command = paths.windows ? wrapBarePathOrEncoded(scriptPath) : wrapPosix(scriptPath);
+    const hooksJsonPath = joinNative(paths.windows, paths.home, ".codex", "hooks.json");
+    const configTomlPath = joinNative(paths.windows, paths.home, ".codex", "config.toml");
+
+    // Filled by the hooks.json apply, read by the config.toml apply (the engine
+    // runs the two edits in order). Keeps both files' positions consistent.
+    const positions: Record<string, number> = {};
+
+    const hooksApply = (config: JsonObject): JsonObject => {
+      const prev = (config.hooks && typeof config.hooks === "object" ? config.hooks : {}) as Record<string, HookDef[]>;
+      const nextHooks: Record<string, HookDef[]> = { ...prev };
+      for (const ev of CODEX_EVENTS) {
+        const current = Array.isArray(nextHooks[ev]) ? nextHooks[ev] : [];
+        const cleaned = current.filter((d) => !defManaged(d));
+        positions[ev] = cleaned.length; // appended last → this is our group index
+        nextHooks[ev] = [...cleaned, { hooks: [{ type: "command", command, timeout: TIMEOUT_SECONDS }] }];
+      }
+      return { ...config, hooks: nextHooks };
+    };
+    const hooksRemove = (config: JsonObject): { config: JsonObject; changed: boolean } => {
+      const prev = (config.hooks && typeof config.hooks === "object" ? config.hooks : null) as Record<string, HookDef[]> | null;
+      if (!prev) return { config, changed: false };
+      const nextHooks: Record<string, HookDef[]> = {};
+      let changed = false;
+      for (const [name, defs] of Object.entries(prev)) {
+        if (!Array.isArray(defs)) {
+          nextHooks[name] = defs;
+          continue;
+        }
+        const cleaned = defs.filter((d) => !defManaged(d));
+        if (cleaned.length !== defs.length) changed = true;
+        if (cleaned.length > 0) nextHooks[name] = cleaned;
+      }
+      return { config: { ...config, hooks: nextHooks }, changed };
+    };
+
+    const trustEntries = (): CodexTrustEntry[] =>
+      CODEX_EVENTS.map((ev) => ({
+        sourcePath: hooksJsonPath,
+        eventLabel: CODEX_EVENT_LABEL[ev],
+        groupIndex: positions[ev] ?? 0,
+        handlerIndex: 0,
+        command,
+        timeoutSec: TIMEOUT_SECONDS,
+      }));
+
+    return {
+      scripts: [
+        {
+          path: scriptPath,
+          content: buildHookScript({ route: "codex", endpointCmd: paths.endpointCmd, endpointEnv: paths.endpointEnv, windows: paths.windows }),
+          executable: !paths.windows,
+        },
+      ],
+      configs: [
+        {
+          path: hooksJsonPath,
+          apply: (raw) => applyJsonConfig(raw, hooksApply),
+          remove: (raw) => removeJsonConfig(raw, hooksRemove),
+        },
+        {
+          path: configTomlPath,
+          apply: (raw) => {
+            // The hooks.json apply must have run first to fill positions; if it
+            // bailed (malformed), don't write trust for a hook we didn't install.
+            if (Object.keys(positions).length === 0) return null;
+            const next = upsertTrustBlocks(raw ?? "", trustEntries());
+            return next === (raw ?? "") ? null : next;
+          },
+          remove: (raw) => {
+            if (raw === null) return null;
+            const { content, changed } = removeTrustBlocks(raw, hooksJsonPath, new Set(Object.values(CODEX_EVENT_LABEL)));
+            return changed ? content : null;
+          },
+        },
+      ],
+    };
+  },
+
+  parse(body: unknown): HookState | null {
+    if (!body || typeof body !== "object") return null;
+    const o = body as Record<string, unknown>;
+    const rawEvent = o.hook_event_name;
+    const event = typeof rawEvent === "string" ? SNAKE_TO_PASCAL[rawEvent] ?? rawEvent : rawEvent;
+    const tool = o.tool_name ?? o.name;
+    const isUserInput = event === "PreToolUse" && isAskUserQuestion(tool);
+    if (event === "PermissionRequest" || isUserInput) return "waiting";
+    if (event === "SessionStart" || event === "UserPromptSubmit" || event === "PreToolUse" || event === "PostToolUse") return "working";
+    if (event === "Stop") return "done";
+    return null;
+  },
+};
diff --git a/src/lib/agentHooks/adapters/copilot.ts b/src/lib/agentHooks/adapters/copilot.ts
new file mode 100644
index 0000000..9a02571
--- /dev/null
+++ b/src/lib/agentHooks/adapters/copilot.ts
@@ -0,0 +1,132 @@
+// GitHub Copilot CLI hook adapter.
+//
+// Config: ~/.copilot/hooks/tempest.json. Copilot's schema puts the command on a
+// `powershell` (Windows) or `bash` (posix) key of each definition, and a
+// separate managed command is registered PER EVENT so the event name can be
+// injected via env (Copilot's payload doesn't name the event). The event reaches
+// the server through the X-Tempest-Event header the script sends from that env.
+// Copilot has real permission signals (blocking Notification, AskUser tool) →
+// coversWaiting = true.
+
+import type { AdapterInstall, ConfigEdit, HookAdapter, HookPaths, HookState, JsonObject } from "../types";
+import { applyJsonConfig, makeManagedMatcher, removeJsonConfig } from "../schema.ts";
+import { wrapPosix, wrapPowerShellInline } from "../wrappers.ts";
+import { buildHookScript } from "../script.ts";
+import { joinNative } from "../paths.ts";
+
+// Only events that map to a state (Copilot also emits subagent/compact events
+// we don't model). Notification/PermissionRequest carry the "needs you" signal.
+const COPILOT_EVENTS = [
+  "SessionStart",
+  "SessionEnd",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PostToolUse",
+  "PostToolUseFailure",
+  "Stop",
+  "ErrorOccurred",
+  "PermissionRequest",
+  "Notification",
+] as const;
+
+const SCRIPT_STEM = "tempest-copilot-hook";
+const EVENT_ENV = "TEMPEST_HOOK_EVENT";
+
+interface CopilotDef {
+  command?: string;
+  bash?: string;
+  powershell?: string;
+  hooks?: { command?: string }[];
+  [k: string]: unknown;
+}
+
+function defManaged(def: CopilotDef, isManaged: (c: string | undefined) => boolean): boolean {
+  return (
+    isManaged(def.command) ||
+    isManaged(def.bash) ||
+    isManaged(def.powershell) ||
+    (Array.isArray(def.hooks) && def.hooks.some((h) => isManaged(h.command)))
+  );
+}
+
+function isAskUserTool(name: unknown): boolean {
+  const n = typeof name === "string" ? name.trim().toLowerCase() : "";
+  return n === "askuser" || n === "askuserquestion";
+}
+
+export const copilotAdapter: HookAdapter = {
+  id: "copilot",
+  coversWaiting: true,
+
+  plan(paths: HookPaths): AdapterInstall {
+    const scriptFileName = `${SCRIPT_STEM}.${paths.windows ? "cmd" : "sh"}`;
+    const scriptPath = joinNative(paths.windows, paths.hooksDir, scriptFileName);
+    const scriptContent = buildHookScript({
+      route: "copilot",
+      endpointCmd: paths.endpointCmd,
+      endpointEnv: paths.endpointEnv,
+      windows: paths.windows,
+      emitEmptyJson: true,
+      eventEnvVar: EVENT_ENV,
+    });
+    // Per-event command: inject the event name via env so the script reports it.
+    const perEvent = (event: string): CopilotDef =>
+      paths.windows
+        ? { type: "command", powershell: wrapPowerShellInline(scriptPath, { [EVENT_ENV]: event }), timeoutSec: 5 }
+        : { type: "command", bash: wrapPosix(scriptPath, { [EVENT_ENV]: event }), timeoutSec: 5 };
+    const isManaged = makeManagedMatcher(scriptFileName);
+
+    const apply = (config: JsonObject): JsonObject => {
+      const prev = (config.hooks && typeof config.hooks === "object" ? config.hooks : {}) as Record<string, CopilotDef[]>;
+      const nextHooks: Record<string, CopilotDef[]> = { ...prev };
+      for (const ev of COPILOT_EVENTS) {
+        const current = Array.isArray(nextHooks[ev]) ? nextHooks[ev] : [];
+        const cleaned = current.filter((d) => !defManaged(d, isManaged));
+        nextHooks[ev] = [...cleaned, perEvent(ev)];
+      }
+      return { ...config, hooks: nextHooks };
+    };
+    const remove = (config: JsonObject): { config: JsonObject; changed: boolean } => {
+      const prev = (config.hooks && typeof config.hooks === "object" ? config.hooks : null) as Record<string, CopilotDef[]> | null;
+      if (!prev) return { config, changed: false };
+      const nextHooks: Record<string, CopilotDef[]> = {};
+      let changed = false;
+      for (const [name, defs] of Object.entries(prev)) {
+        if (!Array.isArray(defs)) {
+          nextHooks[name] = defs;
+          continue;
+        }
+        const cleaned = defs.filter((d) => !defManaged(d, isManaged));
+        if (cleaned.length !== defs.length) changed = true;
+        if (cleaned.length > 0) nextHooks[name] = cleaned;
+      }
+      return { config: { ...config, hooks: nextHooks }, changed };
+    };
+
+    const config: ConfigEdit = {
+      path: joinNative(paths.windows, paths.home, ".copilot", "hooks", "tempest.json"),
+      apply: (raw) => applyJsonConfig(raw, apply),
+      remove: (raw) => removeJsonConfig(raw, remove),
+    };
+    return { scripts: [{ path: scriptPath, content: scriptContent, executable: !paths.windows }], configs: [config] };
+  },
+
+  parse(body: unknown): HookState | null {
+    if (!body || typeof body !== "object") return null;
+    const o = body as Record<string, unknown>;
+    const event = o.hook_event_name;
+    const nt = (typeof o.notification_type === "string" ? o.notification_type : typeof o.notificationType === "string" ? o.notificationType : "").toLowerCase();
+    if (event === "Notification") {
+      return nt === "permission_prompt" || nt === "elicitation_dialog" ? "waiting" : null;
+    }
+    if (event === "PreToolUse" || event === "PermissionRequest") {
+      return isAskUserTool(o.tool_name) ? "waiting" : "working";
+    }
+    if (event === "SessionStart" || event === "UserPromptSubmit" || event === "PostToolUse" || event === "PostToolUseFailure") {
+      return "working";
+    }
+    if (event === "Stop" || event === "SessionEnd") return "done";
+    if (event === "ErrorOccurred") return o.recoverable === true ? "working" : "done";
+    return null;
+  },
+};
diff --git a/src/lib/agentHooks/adapters/cursor.ts b/src/lib/agentHooks/adapters/cursor.ts
new file mode 100644
index 0000000..caad9d5
--- /dev/null
+++ b/src/lib/agentHooks/adapters/cursor.ts
@@ -0,0 +1,107 @@
+// Cursor Agent hook adapter.
+//
+// Config: ~/.cursor/hooks.json. Cursor's schema differs from Claude's: the
+// command sits DIRECTLY on the definition (`{ command, timeout }`, not nested
+// under `hooks`), and the file requires a top-level `version: 1`
+// (https://cursor.com/docs/hooks). Cursor treats its shell/MCP pre-execution
+// gates as ordinary work (not approval prompts), so it has no "waiting" event:
+// coversWaiting = false keeps the PTY attention path live.
+
+import type { AdapterInstall, HookAdapter, HookPaths, HookState, JsonObject } from "../types";
+import { applyJsonConfig, makeManagedMatcher, removeJsonConfig } from "../schema.ts";
+import { wrapEncodedPowerShell, wrapPosix } from "../wrappers.ts";
+import { buildHookScript } from "../script.ts";
+import { joinNative } from "../paths.ts";
+
+const CURSOR_EVENTS = [
+  "beforeSubmitPrompt",
+  "stop",
+  "preToolUse",
+  "postToolUse",
+  "postToolUseFailure",
+  "beforeShellExecution",
+  "beforeMCPExecution",
+  "afterAgentResponse",
+] as const;
+
+const SCRIPT_STEM = "tempest-cursor-hook";
+const CURSOR_TIMEOUT_SECONDS = 10;
+
+interface CursorDef {
+  command?: string;
+  hooks?: { command?: string }[];
+  [k: string]: unknown;
+}
+
+function defManaged(def: CursorDef, isManaged: (c: string | undefined) => boolean): boolean {
+  return isManaged(def.command) || (Array.isArray(def.hooks) && def.hooks.some((h) => isManaged(h.command)));
+}
+
+function applyCursorHooks(config: JsonObject, command: string, scriptFileName: string): JsonObject {
+  const isManaged = makeManagedMatcher(scriptFileName);
+  const prev = (config.hooks && typeof config.hooks === "object" ? config.hooks : {}) as Record<string, CursorDef[]>;
+  const nextHooks: Record<string, CursorDef[]> = { ...prev };
+  for (const ev of CURSOR_EVENTS) {
+    const current = Array.isArray(nextHooks[ev]) ? nextHooks[ev] : [];
+    const cleaned = current.filter((d) => !defManaged(d, isManaged));
+    nextHooks[ev] = [...cleaned, { command, timeout: CURSOR_TIMEOUT_SECONDS }];
+  }
+  const next: JsonObject = { ...config, hooks: nextHooks };
+  // Cursor's schema requires a top-level version; keep any user-pinned value.
+  if (next.version === undefined) next.version = 1;
+  return next;
+}
+
+function removeCursorHooks(config: JsonObject, scriptFileName: string): { config: JsonObject; changed: boolean } {
+  const isManaged = makeManagedMatcher(scriptFileName);
+  const prev = (config.hooks && typeof config.hooks === "object" ? config.hooks : null) as Record<string, CursorDef[]> | null;
+  if (!prev) return { config, changed: false };
+  const nextHooks: Record<string, CursorDef[]> = {};
+  let changed = false;
+  for (const [name, defs] of Object.entries(prev)) {
+    if (!Array.isArray(defs)) {
+      nextHooks[name] = defs;
+      continue;
+    }
+    const cleaned = defs.filter((d) => !defManaged(d, isManaged));
+    if (cleaned.length !== defs.length) changed = true;
+    if (cleaned.length > 0) nextHooks[name] = cleaned;
+  }
+  return { config: { ...config, hooks: nextHooks }, changed };
+}
+
+export const cursorAdapter: HookAdapter = {
+  id: "cursor",
+  coversWaiting: false,
+
+  plan(paths: HookPaths): AdapterInstall {
+    const scriptFileName = `${SCRIPT_STEM}.${paths.windows ? "cmd" : "sh"}`;
+    const scriptPath = joinNative(paths.windows, paths.hooksDir, scriptFileName);
+    const scriptContent = buildHookScript({
+      route: "cursor",
+      endpointCmd: paths.endpointCmd,
+      endpointEnv: paths.endpointEnv,
+      windows: paths.windows,
+      emitEmptyJson: true,
+    });
+    const command = paths.windows ? wrapEncodedPowerShell(scriptPath) : wrapPosix(scriptPath);
+    return {
+      scripts: [{ path: scriptPath, content: scriptContent, executable: !paths.windows }],
+      configs: [
+        {
+          path: joinNative(paths.windows, paths.home, ".cursor", "hooks.json"),
+          apply: (raw) => applyJsonConfig(raw, (c) => applyCursorHooks(c, command, scriptFileName)),
+          remove: (raw) => removeJsonConfig(raw, (c) => removeCursorHooks(c, scriptFileName)),
+        },
+      ],
+    };
+  },
+
+  parse(body: unknown): HookState | null {
+    if (!body || typeof body !== "object") return null;
+    const event = (body as Record<string, unknown>).hook_event_name ?? (body as Record<string, unknown>).hookEventName;
+    if (event === "stop" || event === "sessionEnd") return "done";
+    if (typeof event === "string" && (CURSOR_EVENTS as readonly string[]).includes(event)) return "working";
+    return null;
+  },
+};
diff --git a/src/lib/agentHooks/adapters/gemini.ts b/src/lib/agentHooks/adapters/gemini.ts
new file mode 100644
index 0000000..760c622
--- /dev/null
+++ b/src/lib/agentHooks/adapters/gemini.ts
@@ -0,0 +1,73 @@
+// Gemini CLI hook adapter.
+//
+// Config: ~/.gemini/settings.json, Claude-nested schema. Quirks vs Claude:
+//  - Gemini's hook `timeout` unit is MILLISECONDS, not seconds.
+//  - Gemini parses the hook's stdout as JSON, so the script must print `{}`.
+//  - Gemini's tool events are BeforeTool/AfterTool (not Pre/PostToolUse), and it
+//    has NO permission-prompt hook — approvals are inline UI. So working/done are
+//    precise but "needs you" is NOT covered: coversWaiting = false keeps the PTY
+//    attention heuristics (Gemini's ✋ title) live.
+
+import type { AdapterInstall, HookAdapter, HookPaths, HookState } from "../types";
+import { applyJsonConfig, applyNestedHooks, removeJsonConfig, removeNestedHooks, type NestedEvent } from "../schema.ts";
+import { wrapEncodedPowerShell, wrapPosix } from "../wrappers.ts";
+import { buildHookScript } from "../script.ts";
+import { joinNative } from "../paths.ts";
+
+// No matcher: Gemini emits a single managed entry per event bucket.
+const GEMINI_EVENTS: NestedEvent[] = [
+  { name: "BeforeAgent" },
+  { name: "BeforeTool" },
+  { name: "AfterTool" },
+  { name: "AfterAgent" },
+];
+
+const GEMINI_TIMEOUT_MS = 10_000;
+const SCRIPT_STEM = "tempest-gemini-hook";
+
+export const geminiAdapter: HookAdapter = {
+  id: "gemini",
+  // No permission event in Gemini's hook set — keep the title/OSC attention path.
+  coversWaiting: false,
+
+  plan(paths: HookPaths): AdapterInstall {
+    const scriptFileName = `${SCRIPT_STEM}.${paths.windows ? "cmd" : "sh"}`;
+    const scriptPath = joinNative(paths.windows, paths.hooksDir, scriptFileName);
+    const scriptContent = buildHookScript({
+      route: "gemini",
+      endpointCmd: paths.endpointCmd,
+      endpointEnv: paths.endpointEnv,
+      windows: paths.windows,
+      emitEmptyJson: true,
+    });
+    // Gemini runs the hook command through an unspecified shell; the encoded
+    // PowerShell launcher runs it reliably on Windows.
+    const command = paths.windows ? wrapEncodedPowerShell(scriptPath) : wrapPosix(scriptPath);
+    return {
+      scripts: [{ path: scriptPath, content: scriptContent, executable: !paths.windows }],
+      configs: [
+        {
+          path: joinNative(paths.windows, paths.home, ".gemini", "settings.json"),
+          apply: (raw) =>
+            applyJsonConfig(raw, (c) => applyNestedHooks(c, command, scriptFileName, GEMINI_EVENTS, GEMINI_TIMEOUT_MS)),
+          remove: (raw) => removeJsonConfig(raw, (c) => removeNestedHooks(c, scriptFileName)),
+        },
+      ],
+    };
+  },
+
+  parse(body: unknown): HookState | null {
+    if (!body || typeof body !== "object") return null;
+    const event = (body as Record<string, unknown>).hook_event_name;
+    switch (event) {
+      case "BeforeAgent":
+      case "BeforeTool":
+      case "AfterTool":
+        return "working";
+      case "AfterAgent":
+        return "done";
+      default:
+        return null;
+    }
+  },
+};
diff --git a/src/lib/agentHooks/adapters/hermes.ts b/src/lib/agentHooks/adapters/hermes.ts
new file mode 100644
index 0000000..59ee72e
--- /dev/null
+++ b/src/lib/agentHooks/adapters/hermes.ts
@@ -0,0 +1,212 @@
+// Hermes hook adapter.
+//
+// Hermes loads Python plugins from ~/.hermes/plugins/<name>/ and enables them via
+// a `plugins.enabled` list in ~/.hermes/config.yaml. We install a managed plugin
+// (plugin.yaml manifest + __init__.py) that registers Hermes' lifecycle hooks and
+// POSTs each to Tempest's server, then enable it in the YAML config. Mirrors
+// Orca's Hermes service. pre_approval_request is a real "needs you" signal →
+// coversWaiting = true.
+
+import { parse, stringify } from "yaml";
+import type { AdapterInstall, HookAdapter, HookPaths, HookState, JsonObject } from "../types";
+import { joinNative } from "../paths.ts";
+
+const PLUGIN_NAME = "tempest-status";
+const MARKER = "Managed by Tempest. Do not edit; changes may be overwritten.";
+
+const HERMES_EVENTS = [
+  "on_session_start",
+  "pre_llm_call",
+  "post_llm_call",
+  "pre_tool_call",
+  "post_tool_call",
+  "pre_approval_request",
+  "post_approval_response",
+  "on_session_end",
+  "on_session_finalize",
+  "on_session_reset",
+] as const;
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function strArr(v: unknown): string[] | null {
+  if (v === undefined) return [];
+  if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) return null;
+  return v as string[];
+}
+
+function pluginManifest(): string {
+  return [
+    `# ${MARKER}`,
+    `name: ${PLUGIN_NAME}`,
+    "version: 1.0.0",
+    'description: "Reports Hermes lifecycle events to Tempest."',
+    'author: "Tempest"',
+    "kind: standalone",
+    "provides_hooks:",
+    ...HERMES_EVENTS.map((e) => `  - ${e}`),
+    "",
+  ].join("\n");
+}
+
+// The Python plugin: sources the endpoint file for the current port/token, reads
+// the Tempest session id from env, and POSTs each lifecycle event (with its name)
+// to /hook/hermes. Best-effort — any failure is swallowed so status can't break a turn.
+function pluginInit(endpointEnv: string): string {
+  return `# ${MARKER}
+from __future__ import annotations
+import json, os, urllib.error, urllib.request
+
+EVENTS = ${JSON.stringify([...HERMES_EVENTS])}
+ENDPOINT = ${JSON.stringify(endpointEnv)}
+SELECTED = {
+    "pre_llm_call": ("user_message", "model"),
+    "post_llm_call": ("assistant_response", "model"),
+    "pre_tool_call": ("tool_name", "args"),
+    "post_tool_call": ("tool_name", "args"),
+    "pre_approval_request": ("command", "description"),
+    "post_approval_response": ("command", "choice"),
+}
+MAX_STR = 8192
+
+
+def _cap(v):
+    s = v if isinstance(v, str) else repr(v)
+    return s if len(s) <= MAX_STR else s[:MAX_STR] + "...[truncated]"
+
+
+def _coords():
+    port = os.environ.get("TEMPEST_HOOK_PORT", "")
+    token = os.environ.get("TEMPEST_HOOK_TOKEN", "")
+    try:
+        with open(ENDPOINT, "r", encoding="utf-8") as f:
+            for raw in f:
+                line = raw.strip()
+                if line.startswith("set "):
+                    line = line[4:]
+                k, sep, val = line.partition("=")
+                if sep and k == "TEMPEST_HOOK_PORT":
+                    port = val.rstrip("\\r")
+                elif sep and k == "TEMPEST_HOOK_TOKEN":
+                    token = val.rstrip("\\r")
+    except OSError:
+        pass
+    return port, token
+
+
+def _post(payload):
+    port, token = _coords()
+    session = os.environ.get("TEMPEST_SESSION", "")
+    if not port or not token or not session:
+        return
+    data = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+    req = urllib.request.Request(
+        "http://127.0.0.1:" + port + "/hook/hermes",
+        data=data, method="POST",
+        headers={"Content-Type": "application/json",
+                 "X-Tempest-Token": token, "X-Tempest-Session": session})
+    try:
+        with urllib.request.urlopen(req, timeout=0.75):
+            pass
+    except (OSError, urllib.error.URLError):
+        return
+
+
+def _payload(event_name, kwargs):
+    p = {"hook_event_name": event_name}
+    for key in SELECTED.get(event_name, ()):
+        if key in kwargs:
+            p[key] = _cap(kwargs[key])
+    return p
+
+
+def _make(event_name):
+    def _hook(**kwargs):
+        _post(_payload(event_name, kwargs))
+    return _hook
+
+
+def register(ctx):
+    for event_name in EVENTS:
+        ctx.register_hook(event_name, _make(event_name))
+`;
+}
+
+export const hermesAdapter: HookAdapter = {
+  id: "hermes",
+  coversWaiting: true,
+
+  plan(paths: HookPaths): AdapterInstall {
+    const pluginDir = joinNative(paths.windows, paths.home, ".hermes", "plugins", PLUGIN_NAME);
+    const configPath = joinNative(paths.windows, paths.home, ".hermes", "config.yaml");
+
+    return {
+      // The plugin files live under the Hermes home, not the shared hooks dir —
+      // ScriptFile.path is an absolute path, so that's fine.
+      scripts: [
+        { path: joinNative(paths.windows, pluginDir, "plugin.yaml"), content: pluginManifest(), executable: false },
+        { path: joinNative(paths.windows, pluginDir, "__init__.py"), content: pluginInit(paths.endpointEnv), executable: false },
+      ],
+      configs: [
+        {
+          path: configPath,
+          apply: (raw) => enableInYaml(raw),
+          remove: (raw) => disableInYaml(raw),
+        },
+      ],
+    };
+  },
+
+  parse(body: unknown): HookState | null {
+    if (!body || typeof body !== "object") return null;
+    const event = (body as Record<string, unknown>).hook_event_name;
+    if (event === "pre_approval_request") return "waiting";
+    if (event === "post_llm_call" || event === "on_session_end" || event === "on_session_finalize" || event === "on_session_reset") {
+      return "done";
+    }
+    if (
+      event === "on_session_start" ||
+      event === "pre_llm_call" ||
+      event === "pre_tool_call" ||
+      event === "post_tool_call" ||
+      event === "post_approval_response"
+    ) {
+      return "working";
+    }
+    return null;
+  },
+};
+
+function parseYaml(raw: string | null): JsonObject | null {
+  if (raw === null || raw.trim() === "") return {};
+  try {
+    const p = parse(raw);
+    if (p === null || p === undefined) return {};
+    return isRecord(p) ? (p as JsonObject) : null;
+  } catch {
+    return null;
+  }
+}
+
+function enableInYaml(raw: string | null): string | null {
+  const config = parseYaml(raw);
+  if (config === null) return null;
+  const plugins = isRecord(config.plugins) ? { ...config.plugins } : {};
+  const enabled = strArr(plugins.enabled) ?? [];
+  plugins.enabled = Array.from(new Set([...enabled, PLUGIN_NAME])).sort();
+  const disabled = strArr(plugins.disabled);
+  plugins.disabled = disabled === null ? [] : disabled.filter((n) => n !== PLUGIN_NAME);
+  return stringify({ ...config, plugins }, { lineWidth: 0 });
+}
+
+function disableInYaml(raw: string | null): string | null {
+  if (raw === null || raw.trim() === "") return null;
+  const config = parseYaml(raw);
+  if (config === null || !isRecord(config.plugins)) return null;
+  const enabled = strArr(config.plugins.enabled);
+  if (enabled === null || !enabled.includes(PLUGIN_NAME)) return null;
+  const plugins = { ...config.plugins, enabled: enabled.filter((n) => n !== PLUGIN_NAME) };
+  return stringify({ ...config, plugins }, { lineWidth: 0 });
+}
diff --git a/src/lib/agentHooks/adapters/opencode.ts b/src/lib/agentHooks/adapters/opencode.ts
new file mode 100644
index 0000000..f2bdc97
--- /dev/null
+++ b/src/lib/agentHooks/adapters/opencode.ts
@@ -0,0 +1,112 @@
+// Opencode hook adapter.
+//
+// Opencode auto-loads ESM plugins from ~/.config/opencode/plugin/. We drop a
+// managed plugin that runs inside Opencode's process, listens to its event
+// stream, and POSTs normalized lifecycle events to Tempest's server. Mirrors
+// Orca's plugin mapping: session.status busy → SessionBusy, session.idle →
+// SessionIdle, permission.asked → PermissionRequest, question.asked →
+// AskUserQuestion, text parts → MessagePart. Opencode has real permission/ask
+// signals → coversWaiting = true.
+
+import type { AdapterInstall, HookAdapter, HookPaths, HookState } from "../types";
+import { joinNative } from "../paths.ts";
+
+const MARKER = "Managed by Tempest. Do not edit; changes may be overwritten.";
+const REMOVED_STUB = `// ${MARKER} (removed)\nexport const TempestOpenCodeStatusPlugin = async () => ({});\n`;
+
+function pluginSource(endpointEnv: string): string {
+  return `// ${MARKER}
+import { readFileSync } from "node:fs";
+
+const ENDPOINT = ${JSON.stringify(endpointEnv)};
+
+function coords() {
+  let port = process.env.TEMPEST_HOOK_PORT;
+  let token = process.env.TEMPEST_HOOK_TOKEN;
+  try {
+    for (const line of readFileSync(ENDPOINT, "utf8").split(/\\r?\\n/)) {
+      const m = line.replace(/^set\\s+/, "").match(/^([A-Z_]+)=(.*)$/);
+      if (!m) continue;
+      if (m[1] === "TEMPEST_HOOK_PORT") port = m[2].replace(/\\r$/, "");
+      if (m[1] === "TEMPEST_HOOK_TOKEN") token = m[2].replace(/\\r$/, "");
+    }
+  } catch {}
+  return { port, token };
+}
+
+async function post(hookEventName) {
+  const { port, token } = coords();
+  const session = process.env.TEMPEST_SESSION;
+  if (!port || !token || !session) return;
+  try {
+    await fetch("http://127.0.0.1:" + port + "/hook/opencode", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Tempest-Token": token,
+        "X-Tempest-Session": session,
+      },
+      body: JSON.stringify({ hook_event_name: hookEventName }),
+    });
+  } catch {}
+}
+
+let lastStatus = "";
+async function setStatus(next) {
+  if (lastStatus === next) return;
+  lastStatus = next;
+  await post(next === "busy" ? "SessionBusy" : "SessionIdle");
+}
+
+// Opencode may invoke the factory with undefined during startup; accept an opaque
+// arg rather than destructuring so that can't throw.
+export const TempestOpenCodeStatusPlugin = async (_ctx) => ({
+  event: async ({ event }) => {
+    if (!event || !event.type) return;
+    if (event.type === "permission.asked") return void post("PermissionRequest");
+    if (event.type === "question.asked") return void post("AskUserQuestion");
+    if (event.type === "message.part.updated") {
+      const part = event.properties && event.properties.part;
+      if (part && part.type === "text" && part.text) await post("MessagePart");
+      return;
+    }
+    if (event.type === "session.idle" || event.type === "session.error") return void setStatus("idle");
+    if (event.type === "session.status") {
+      const t = (event.properties && event.properties.status && event.properties.status.type) || (event.status && event.status.type);
+      if (t === "busy" || t === "retry") await setStatus("busy");
+      else if (t === "idle") await setStatus("idle");
+    }
+  },
+});
+`;
+}
+
+export const opencodeAdapter: HookAdapter = {
+  id: "opencode",
+  coversWaiting: true,
+
+  plan(paths: HookPaths): AdapterInstall {
+    const pluginPath = joinNative(paths.windows, paths.home, ".config", "opencode", "plugin", "tempest-status.js");
+    const source = pluginSource(paths.endpointEnv);
+    return {
+      scripts: [],
+      configs: [
+        {
+          path: pluginPath,
+          apply: () => source,
+          // Overwrite with a no-op plugin (we can't delete files from the engine).
+          remove: (raw) => (raw === null || raw === REMOVED_STUB ? null : REMOVED_STUB),
+        },
+      ],
+    };
+  },
+
+  parse(body: unknown): HookState | null {
+    if (!body || typeof body !== "object") return null;
+    const event = (body as Record<string, unknown>).hook_event_name;
+    if (event === "SessionBusy" || event === "MessagePart") return "working";
+    if (event === "SessionIdle") return "done";
+    if (event === "PermissionRequest" || event === "AskUserQuestion") return "waiting";
+    return null;
+  },
+};
diff --git a/src/lib/agentHooks/codexTrust.ts b/src/lib/agentHooks/codexTrust.ts
new file mode 100644
index 0000000..8b6faf2
--- /dev/null
+++ b/src/lib/agentHooks/codexTrust.ts
@@ -0,0 +1,219 @@
+// Codex hook trust — the piece that makes Codex actually fire our hooks.
+//
+// Codex (0.129+) only runs a hook whose handler is trusted in config.toml via a
+// `[hooks.state."<key>"]` block carrying a `trusted_hash`. The hash is a SHA-256
+// over a canonical identity of the handler, reproduced here exactly from Codex's
+// own algorithm (canonical_json + command_hook_hash), the same way Orca does it.
+// A wrong hash isn't destructive — Codex just ignores the untrusted hook and we
+// fall back to PTY scraping — but a right one gives precise status.
+//
+// Self-contained + synchronous (no Web Crypto) so the install path and the node
+// self-check share one implementation; the SHA-256 is checked against a known
+// vector in installer.check.ts.
+
+// PascalCase hooks.json event key → snake_case trust label (codex-rs serde).
+export const CODEX_EVENT_LABEL: Record<string, string> = {
+  SessionStart: "session_start",
+  UserPromptSubmit: "user_prompt_submit",
+  PreToolUse: "pre_tool_use",
+  PermissionRequest: "permission_request",
+  PostToolUse: "post_tool_use",
+  Stop: "stop",
+};
+
+export interface CodexTrustEntry {
+  sourcePath: string; // path to hooks.json (the "key_source")
+  eventLabel: string; // snake_case
+  groupIndex: number;
+  handlerIndex: number;
+  command: string;
+  timeoutSec: number;
+}
+
+// Codex drops the matcher for these events before hashing; ours have no matcher
+// anyway, so this only matters if a matcher were ever added.
+function matcherForEvent(label: string, matcher: string | undefined): string | undefined {
+  if (label === "user_prompt_submit" || label === "stop") return undefined;
+  return matcher;
+}
+
+// Recursively sort object keys (Codex's canonical_json); arrays keep order.
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(value as Record<string, unknown>).sort()) {
+      out[k] = canonicalize((value as Record<string, unknown>)[k]);
+    }
+    return out;
+  }
+  return value;
+}
+
+// Reproduces Codex's command_hook_hash: sha256 of the canonical
+// { event_name, matcher?, hooks: [handler] } identity.
+export function computeTrustedHash(entry: CodexTrustEntry): string {
+  const handler: Record<string, unknown> = {
+    type: "command",
+    command: entry.command,
+    timeout: Math.max(1, entry.timeoutSec),
+    async: false,
+  };
+  const identity: Record<string, unknown> = { event_name: entry.eventLabel, hooks: [handler] };
+  const matcher = matcherForEvent(entry.eventLabel, undefined);
+  if (matcher !== undefined) identity.matcher = matcher;
+  const serialized = JSON.stringify(canonicalize(identity));
+  return "sha256:" + sha256Hex(serialized);
+}
+
+export function trustKey(entry: CodexTrustEntry): string {
+  return `${entry.sourcePath}:${entry.eventLabel}:${entry.groupIndex}:${entry.handlerIndex}`;
+}
+
+function escapeTomlBasic(v: string): string {
+  return v.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+// Upsert a trust block for each entry into config.toml (append if absent, replace
+// its hash/enabled if present). Byte-preserves the rest of the file. Returns the
+// updated content, or the input unchanged when every block already matches.
+export function upsertTrustBlocks(content: string, entries: CodexTrustEntry[]): string {
+  let out = content;
+  for (const entry of entries) {
+    const key = trustKey(entry);
+    const hash = computeTrustedHash(entry);
+    const block = [`[hooks.state."${escapeTomlBasic(key)}"]`, "enabled = true", `trusted_hash = "${hash}"`].join("\n");
+    const range = findBlockRange(out, key);
+    if (range) {
+      out = out.slice(0, range.start) + block + out.slice(range.end);
+    } else {
+      const sep = out.length === 0 ? "" : out.endsWith("\n\n") ? "" : out.endsWith("\n") ? "\n" : "\n\n";
+      out = `${out}${sep}${block}\n`;
+    }
+  }
+  return out;
+}
+
+// Remove trust blocks whose key targets one of our (sourcePath, label) pairs.
+export function removeTrustBlocks(content: string, sourcePath: string, labels: Set<string>): { content: string; changed: boolean } {
+  let out = "";
+  let cursor = 0;
+  let changed = false;
+  const headerRe = /^\[hooks\.state\."((?:[^"\\]|\\.)*)"\]\s*$/gm;
+  let m: RegExpExecArray | null;
+  const ranges: { start: number; end: number }[] = [];
+  while ((m = headerRe.exec(content)) !== null) {
+    const key = m[1].replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    const parsed = parseKey(key);
+    if (parsed && samePath(parsed.sourcePath, sourcePath) && labels.has(parsed.eventLabel)) {
+      const start = m.index;
+      const end = nextHeaderOrEnd(content, headerRe.lastIndex);
+      ranges.push({ start, end });
+      headerRe.lastIndex = end;
+    }
+  }
+  for (const r of ranges) {
+    out += content.slice(cursor, r.start);
+    cursor = r.end;
+    changed = true;
+  }
+  out += content.slice(cursor);
+  return { content: out, changed };
+}
+
+function samePath(a: string, b: string): boolean {
+  return a.replace(/\\/g, "/").toLowerCase() === b.replace(/\\/g, "/").toLowerCase();
+}
+
+function parseKey(key: string): { sourcePath: string; eventLabel: string } | null {
+  // key = <sourcePath>:<label>:<group>:<handler>; sourcePath may contain ':'.
+  const parts = key.split(":");
+  if (parts.length < 4) return null;
+  const handler = parts.pop()!;
+  const group = parts.pop()!;
+  const label = parts.pop()!;
+  if (!/^\d+$/.test(handler) || !/^\d+$/.test(group)) return null;
+  return { sourcePath: parts.join(":"), eventLabel: label };
+}
+
+function findBlockRange(content: string, key: string): { start: number; end: number } | null {
+  const header = `[hooks.state."${escapeTomlBasic(key)}"]`;
+  const idx = content.indexOf(header);
+  if (idx === -1) return null;
+  return { start: idx, end: nextHeaderOrEnd(content, idx + header.length) };
+}
+
+// End of a block = the next `[` table header at line start, or EOF.
+function nextHeaderOrEnd(content: string, from: number): number {
+  const re = /^\[/gm;
+  re.lastIndex = from;
+  const m = re.exec(content);
+  return m ? m.index : content.length;
+}
+
+// ── pure synchronous SHA-256 ─────────────────────────────────────────────────
+const K = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+
+export function sha256Hex(message: string): string {
+  const bytes = utf8Bytes(message);
+  const l = bytes.length;
+  const withOne = new Uint8Array((((l + 8) >> 6) + 1) << 6);
+  withOne.set(bytes);
+  withOne[l] = 0x80;
+  const bitLen = l * 8;
+  const dv = new DataView(withOne.buffer);
+  dv.setUint32(withOne.length - 4, bitLen >>> 0);
+  dv.setUint32(withOne.length - 8, Math.floor(bitLen / 0x100000000));
+
+  const h = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
+  const w = new Uint32Array(64);
+  for (let off = 0; off < withOne.length; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = dv.getUint32(off + i * 4);
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = h;
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (hh + S1 + ch + K[i] + w[i]) >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) >>> 0;
+      hh = g; g = f; f = e; e = (d + t1) >>> 0; d = c; c = b; b = a; a = (t1 + t2) >>> 0;
+    }
+    h[0] = (h[0] + a) >>> 0; h[1] = (h[1] + b) >>> 0; h[2] = (h[2] + c) >>> 0; h[3] = (h[3] + d) >>> 0;
+    h[4] = (h[4] + e) >>> 0; h[5] = (h[5] + f) >>> 0; h[6] = (h[6] + g) >>> 0; h[7] = (h[7] + hh) >>> 0;
+  }
+  return h.map((x) => x.toString(16).padStart(8, "0")).join("");
+}
+
+function rotr(x: number, n: number): number {
+  return (x >>> n) | (x << (32 - n));
+}
+
+function utf8Bytes(s: string): Uint8Array {
+  const out: number[] = [];
+  for (let i = 0; i < s.length; i++) {
+    let c = s.charCodeAt(i);
+    if (c < 0x80) out.push(c);
+    else if (c < 0x800) out.push(0xc0 | (c >> 6), 0x80 | (c & 0x3f));
+    else if (c >= 0xd800 && c <= 0xdbff) {
+      const c2 = s.charCodeAt(++i);
+      c = 0x10000 + ((c & 0x3ff) << 10) + (c2 & 0x3ff);
+      out.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 0x3f), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
+    } else out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
+  }
+  return new Uint8Array(out);
+}
diff --git a/src/lib/agentHooks/index.ts b/src/lib/agentHooks/index.ts
new file mode 100644
index 0000000..446d7d4
--- /dev/null
+++ b/src/lib/agentHooks/index.ts
@@ -0,0 +1,50 @@
+// Agent-hooks registry + top-level (un)install. Add an agent by dropping its
+// adapter in `adapters/` and listing it here — the engine, receiver, and Settings
+// toggle need no further wiring.
+
+import type { HookAdapter } from "./types";
+import { claudeAdapter } from "./adapters/claude";
+import { geminiAdapter } from "./adapters/gemini";
+import { cursorAdapter } from "./adapters/cursor";
+import { copilotAdapter } from "./adapters/copilot";
+import { antigravityAdapter } from "./adapters/antigravity";
+import { codexAdapter } from "./adapters/codex";
+import { hermesAdapter } from "./adapters/hermes";
+import { opencodeAdapter } from "./adapters/opencode";
+import { getHookPaths, installAdapter, uninstallAdapter, type InstallResult } from "./installer";
+
+export type { HookAdapter, HookState } from "./types";
+export { getHookPaths } from "./installer";
+
+// Every hook-capable agent Tempest supports. Agents without a hook mechanism
+// (cline, goose, pi) are absent by design — they stay on PTY-scraped status.
+const ADAPTERS: HookAdapter[] = [
+  claudeAdapter,
+  geminiAdapter,
+  cursorAdapter,
+  copilotAdapter,
+  antigravityAdapter,
+  codexAdapter,
+  hermesAdapter,
+  opencodeAdapter,
+];
+
+const BY_ID = new Map(ADAPTERS.map((a) => [a.id, a]));
+
+export function getAdapter(id: string): HookAdapter | undefined {
+  return BY_ID.get(id);
+}
+
+export function adapterIds(): string[] {
+  return ADAPTERS.map((a) => a.id);
+}
+
+export async function installAll(): Promise<InstallResult[]> {
+  const paths = await getHookPaths();
+  return Promise.all(ADAPTERS.map((a) => installAdapter(a, paths)));
+}
+
+export async function uninstallAll(): Promise<InstallResult[]> {
+  const paths = await getHookPaths();
+  return Promise.all(ADAPTERS.map((a) => uninstallAdapter(a, paths)));
+}
diff --git a/src/lib/agentHooks/installer.check.ts b/src/lib/agentHooks/installer.check.ts
new file mode 100644
index 0000000..0b17cdb
--- /dev/null
+++ b/src/lib/agentHooks/installer.check.ts
@@ -0,0 +1,304 @@
+// Self-check for the agent-hooks merge engine + the Claude adapter.
+//
+// The merge is a trust-sensitive edit of the user's OWN agent config files, so
+// the properties that matter are: never drop a user's hooks, be idempotent
+// (startup re-install must be a no-op), sweep only our own entries on removal,
+// and map events to the right state. Run with `node src/lib/agentHooks/installer.check.ts`
+// (Node strips types natively — no framework, no build step).
+//
+// Only pure functions are exercised; the install engine itself needs Tauri.
+import assert from "node:assert";
+import { applyNestedHooks, removeNestedHooks, makeManagedMatcher, applyJsonConfig, removeJsonConfig, type NestedEvent } from "./schema.ts";
+import { claudeAdapter } from "./adapters/claude.ts";
+import { geminiAdapter } from "./adapters/gemini.ts";
+import { cursorAdapter } from "./adapters/cursor.ts";
+import { copilotAdapter } from "./adapters/copilot.ts";
+import { antigravityAdapter } from "./adapters/antigravity.ts";
+import { codexAdapter } from "./adapters/codex.ts";
+import { hermesAdapter } from "./adapters/hermes.ts";
+import { opencodeAdapter } from "./adapters/opencode.ts";
+import { sha256Hex, computeTrustedHash } from "./codexTrust.ts";
+import type { HookAdapter, HookPaths, JsonObject } from "./types.ts";
+
+const SCRIPT = "tempest-claude-hook.cmd";
+const CMD = "if [ -f '/home/u/.tempest/hooks/tempest-claude-hook.cmd' ]; then '/home/u/.tempest/hooks/tempest-claude-hook.cmd'; fi";
+const EVENTS: NestedEvent[] = [
+  { name: "UserPromptSubmit" },
+  { name: "PreToolUse", matcher: true },
+  { name: "Stop" },
+];
+
+function managedCount(config: JsonObject): number {
+  const isManaged = makeManagedMatcher(SCRIPT);
+  const hooks = (config.hooks ?? {}) as Record<string, any[]>;
+  let n = 0;
+  for (const defs of Object.values(hooks)) {
+    for (const def of defs) {
+      if (isManaged(def.command)) n++;
+      for (const h of def.hooks ?? []) if (isManaged(h.command)) n++;
+    }
+  }
+  return n;
+}
+
+// ── user hooks and unrelated keys survive a merge ────────────────────────────
+{
+  const userHook = { hooks: [{ type: "command", command: "my-own-linter" }] };
+  const before: JsonObject = {
+    model: "opus",
+    permissions: { allow: ["Bash"] },
+    hooks: { PreToolUse: [userHook], Stop: [{ hooks: [{ type: "command", command: "user-stop" }] }] },
+  };
+  const after = applyNestedHooks(before, CMD, SCRIPT, EVENTS);
+
+  assert.strictEqual((after as any).model, "opus", "unrelated top-level keys must survive");
+  assert.deepStrictEqual((after as any).permissions, { allow: ["Bash"] }, "unrelated keys untouched");
+  const pre = (after as any).hooks.PreToolUse as any[];
+  assert.ok(pre.some((d) => d === userHook || d.hooks?.[0]?.command === "my-own-linter"), "user PreToolUse hook preserved");
+  assert.strictEqual(managedCount(after), 3, "one managed entry per subscribed event");
+  // The user's Stop hook still there alongside ours.
+  const stop = (after as any).hooks.Stop as any[];
+  assert.ok(stop.some((d) => d.hooks?.[0]?.command === "user-stop"), "user Stop hook preserved");
+}
+
+// ── idempotent: re-install writes the same object ────────────────────────────
+{
+  const before: JsonObject = { hooks: { Stop: [{ hooks: [{ type: "command", command: "keep-me" }] }] } };
+  const once = applyNestedHooks(before, CMD, SCRIPT, EVENTS);
+  const twice = applyNestedHooks(once, CMD, SCRIPT, EVENTS);
+  assert.strictEqual(JSON.stringify(once), JSON.stringify(twice), "re-install must be a no-op");
+  assert.strictEqual(managedCount(twice), 3, "no duplicate managed entries after re-install");
+}
+
+// ── stale platform entry (.sh) is swept when installing (.cmd) ───────────────
+{
+  const stale: JsonObject = {
+    hooks: { Stop: [{ hooks: [{ type: "command", command: "sh /x/tempest-claude-hook.sh" }] }] },
+  };
+  const after = applyNestedHooks(stale, CMD, SCRIPT, EVENTS);
+  const stop = (after as any).hooks.Stop as any[];
+  const shGone = !stop.some((d) => (d.hooks ?? []).some((h: any) => String(h.command).includes(".sh")));
+  assert.ok(shGone, "a stale .sh managed entry must be swept by the .cmd install");
+  assert.strictEqual(managedCount(after), 3, "exactly our entries remain");
+}
+
+// ── removal strips only our entries and restores the config ──────────────────
+{
+  const before: JsonObject = {
+    model: "opus",
+    hooks: { PreToolUse: [{ hooks: [{ type: "command", command: "my-own-linter" }] }] },
+  };
+  const installed = applyNestedHooks(before, CMD, SCRIPT, EVENTS);
+  const { config: removed, changed } = removeNestedHooks(installed, SCRIPT);
+  assert.strictEqual(changed, true, "removal reports a change when our entries existed");
+  assert.strictEqual(managedCount(removed), 0, "no managed entries after removal");
+  const pre = (removed as any).hooks.PreToolUse as any[];
+  assert.ok(pre.some((d) => d.hooks?.[0]?.command === "my-own-linter"), "user hook survives our removal");
+  assert.strictEqual((removed as any).model, "opus", "unrelated keys survive removal");
+
+  const { changed: changedAgain } = removeNestedHooks(removed, SCRIPT);
+  assert.strictEqual(changedAgain, false, "removing again is a no-op");
+}
+
+// ── matcher only matches our script token ────────────────────────────────────
+{
+  const isManaged = makeManagedMatcher(SCRIPT);
+  assert.ok(isManaged("C:\\Users\\u\\.tempest\\hooks\\tempest-claude-hook.cmd"), "matches windows path");
+  assert.ok(isManaged("/home/u/.tempest/hooks/tempest-claude-hook.sh"), "matches posix path, any ext");
+  assert.ok(!isManaged("claude-hook-of-mine"), "must not match an unrelated command");
+  assert.ok(!isManaged(undefined), "undefined command is not managed");
+}
+
+// ── Claude event → state map ─────────────────────────────────────────────────
+{
+  const s = (body: unknown) => claudeAdapter.parse(body);
+  assert.strictEqual(s({ hook_event_name: "UserPromptSubmit" }), "working");
+  assert.strictEqual(s({ hook_event_name: "PreToolUse", tool_name: "Bash" }), "working");
+  assert.strictEqual(s({ hook_event_name: "PostToolUse", tool_name: "Bash" }), "working");
+  assert.strictEqual(s({ hook_event_name: "PreToolUse", tool_name: "AskUserQuestion" }), "waiting", "AskUserQuestion blocks for a human");
+  assert.strictEqual(s({ hook_event_name: "PermissionRequest", tool_name: "Bash" }), "waiting");
+  assert.strictEqual(s({ hook_event_name: "Notification", notification_type: "permission_prompt" }), "waiting");
+  assert.strictEqual(s({ hook_event_name: "Notification", message: "Claude needs your permission to use Bash" }), "waiting");
+  assert.strictEqual(s({ hook_event_name: "Notification", message: "Compacting conversation" }), null, "generic notifications aren't a transition");
+  assert.strictEqual(s({ hook_event_name: "Stop" }), "done");
+  assert.strictEqual(s({ hook_event_name: "SomethingNew" }), null, "unknown events ignored");
+  assert.strictEqual(s("not an object"), null, "non-object payload ignored");
+}
+
+// ── raw-text JSON config helpers ─────────────────────────────────────────────
+{
+  const add = (c: JsonObject) => ({ ...c, tempest: true });
+  // Missing/empty file → starts from {}.
+  assert.strictEqual(applyJsonConfig(null, add), '{\n  "tempest": true\n}\n');
+  assert.strictEqual(applyJsonConfig("", add), '{\n  "tempest": true\n}\n');
+  // Malformed JSON → null (leave the user's file untouched).
+  assert.strictEqual(applyJsonConfig("{ not json", add), null, "malformed config is never clobbered");
+  assert.strictEqual(applyJsonConfig("[1,2,3]", add), null, "a non-object top level is treated as malformed");
+  // Remove never creates a file and no-ops on absent.
+  assert.strictEqual(removeJsonConfig(null, (c) => ({ config: c, changed: true })), null, "remove never creates the file");
+  assert.strictEqual(removeJsonConfig('{"a":1}', (c) => ({ config: c, changed: false })), null, "no change → no write");
+}
+
+// ── posix plan shape, per adapter ────────────────────────────────────────────
+const POSIX: HookPaths = {
+  home: "/home/u",
+  hooksDir: "/home/u/.tempest/hooks",
+  endpointEnv: "/home/u/.tempest/hooks/endpoint.env",
+  endpointCmd: "/home/u/.tempest/hooks/endpoint.cmd",
+  windows: false,
+};
+function checkPlan(adapter: HookAdapter, route: string, configPath: string, script: string) {
+  const plan = adapter.plan(POSIX);
+  assert.strictEqual(plan.scripts.length, 1, `${adapter.id}: one script`);
+  assert.strictEqual(plan.scripts[0].path, `/home/u/.tempest/hooks/${script}`);
+  assert.ok(plan.scripts[0].executable, `${adapter.id}: posix script needs exec bit`);
+  assert.ok(plan.scripts[0].content.includes(`/hook/${route}`), `${adapter.id}: posts to its route`);
+  assert.ok(plan.scripts[0].content.includes("--data-binary @-"), `${adapter.id}: forwards stdin`);
+  assert.strictEqual(plan.configs.length, 1, `${adapter.id}: one config`);
+  assert.strictEqual(plan.configs[0].path, configPath);
+  // apply on a blank config produces JSON that references our script.
+  const applied = plan.configs[0].apply(null);
+  assert.ok(applied && applied.includes(script), `${adapter.id}: managed command references the script`);
+  // remove on that applied config strips it back out.
+  const removed = plan.configs[0].remove(applied);
+  assert.ok(removed !== null && !removed.includes(script), `${adapter.id}: remove strips our command`);
+}
+checkPlan(claudeAdapter, "claude", "/home/u/.claude/settings.json", "tempest-claude-hook.sh");
+checkPlan(geminiAdapter, "gemini", "/home/u/.gemini/settings.json", "tempest-gemini-hook.sh");
+checkPlan(cursorAdapter, "cursor", "/home/u/.cursor/hooks.json", "tempest-cursor-hook.sh");
+
+// ── Gemini: ms timeout, {} on stdout, no waiting, Before/After map ───────────
+{
+  const plan = geminiAdapter.plan(POSIX);
+  assert.ok(plan.scripts[0].content.includes("printf '{}\\n'"), "gemini prints {} for its stdout parser");
+  assert.ok(plan.configs[0].apply(null)!.includes("10000"), "gemini timeout is in milliseconds");
+  assert.strictEqual(geminiAdapter.coversWaiting, false, "gemini keeps the attention fallback");
+  assert.strictEqual(geminiAdapter.parse({ hook_event_name: "BeforeAgent" }), "working");
+  assert.strictEqual(geminiAdapter.parse({ hook_event_name: "BeforeTool" }), "working");
+  assert.strictEqual(geminiAdapter.parse({ hook_event_name: "AfterAgent" }), "done");
+  assert.strictEqual(geminiAdapter.parse({ hook_event_name: "Stop" }), null, "gemini has no Stop event");
+}
+
+// ── Cursor: direct-command schema + version:1, stop→done ─────────────────────
+{
+  const applied = cursorAdapter.plan(POSIX).configs[0].apply('{"hooks":{"stop":[{"command":"mine"}]}}');
+  const cfg = JSON.parse(applied!);
+  assert.strictEqual(cfg.version, 1, "cursor requires top-level version");
+  assert.ok(cfg.hooks.stop.some((d: { command?: string }) => d.command === "mine"), "user cursor hook preserved");
+  assert.ok(cfg.hooks.stop.some((d: { command?: string }) => (d.command ?? "").includes("tempest-cursor-hook")), "our command added directly on the definition");
+  assert.strictEqual(cursorAdapter.parse({ hook_event_name: "stop" }), "done");
+  assert.strictEqual(cursorAdapter.parse({ hook_event_name: "preToolUse" }), "working");
+  assert.strictEqual(cursorAdapter.parse({ hook_event_name: "beforeShellExecution" }), "working", "cursor pre-exec gates are working, not waiting");
+  assert.strictEqual(cursorAdapter.coversWaiting, false);
+}
+
+// ── Copilot: per-event env-injected command, waiting signals ─────────────────
+{
+  const plan = copilotAdapter.plan(POSIX);
+  assert.strictEqual(plan.configs[0].path, "/home/u/.copilot/hooks/tempest.json");
+  const applied = plan.configs[0].apply(null)!;
+  const cfg = JSON.parse(applied);
+  // Each event carries a distinct env-injected command referencing our script.
+  assert.ok(cfg.hooks.SessionStart[0].bash.includes("TEMPEST_HOOK_EVENT='SessionStart'"), "per-event name injected");
+  assert.ok(cfg.hooks.Stop[0].bash.includes("TEMPEST_HOOK_EVENT='Stop'"));
+  assert.ok(cfg.hooks.SessionStart[0].bash.includes("tempest-copilot-hook"), "invokes our script");
+  assert.ok(plan.scripts[0].content.includes('X-Tempest-Event'), "script forwards the event header");
+  const removed = plan.configs[0].remove(applied);
+  assert.ok(removed !== null && !removed.includes("tempest-copilot-hook"), "copilot remove strips ours");
+  assert.strictEqual(copilotAdapter.parse({ hook_event_name: "Stop" }), "done");
+  assert.strictEqual(copilotAdapter.parse({ hook_event_name: "PostToolUse" }), "working");
+  assert.strictEqual(copilotAdapter.parse({ hook_event_name: "Notification", notification_type: "permission_prompt" }), "waiting");
+  assert.strictEqual(copilotAdapter.parse({ hook_event_name: "PreToolUse", tool_name: "AskUser" }), "waiting");
+  assert.strictEqual(copilotAdapter.parse({ hook_event_name: "PreToolUse", tool_name: "Bash" }), "working");
+  assert.strictEqual(copilotAdapter.parse({ hook_event_name: "ErrorOccurred", recoverable: false }), "done");
+  assert.strictEqual(copilotAdapter.coversWaiting, true);
+}
+
+// ── Antigravity: bundle key, per-event wrappers (win), Stop fullyIdle ─────────
+{
+  const posix = antigravityAdapter.plan(POSIX);
+  assert.strictEqual(posix.configs[0].path, "/home/u/.gemini/config/hooks.json");
+  assert.strictEqual(posix.scripts.length, 1, "posix: only the core script");
+  const applied = posix.configs[0].apply('{"other-bundle":{"X":[{"command":"user"}]}}')!;
+  const cfg = JSON.parse(applied);
+  assert.ok(cfg["other-bundle"], "unrelated hook bundles are preserved");
+  assert.ok(cfg["tempest-status"].PreInvocation[0].command.includes("tempest-antigravity"), "our bundle installed");
+  assert.ok(Array.isArray(cfg["tempest-status"].PostToolUse[0].hooks), "PostToolUse uses the tool schema");
+  const removed = posix.configs[0].remove(applied);
+  const rcfg = JSON.parse(removed!);
+  assert.ok(!rcfg["tempest-status"], "remove drops our bundle");
+  assert.ok(rcfg["other-bundle"], "remove keeps unrelated bundles");
+  // Windows plan writes the core + one wrapper per event.
+  const win = antigravityAdapter.plan({ ...POSIX, windows: true });
+  assert.strictEqual(win.scripts.length, 1 + 4, "windows: core + 4 per-event wrappers");
+  assert.strictEqual(antigravityAdapter.parse({ hook_event_name: "Stop" }), "done");
+  assert.strictEqual(antigravityAdapter.parse({ hook_event_name: "Stop", fullyIdle: false }), "working", "Stop with fullyIdle:false is still working");
+  assert.strictEqual(antigravityAdapter.parse({ hook_event_name: "PreInvocation" }), "working");
+  assert.strictEqual(antigravityAdapter.coversWaiting, false);
+}
+
+// ── SHA-256 correctness (known vectors) ──────────────────────────────────────
+{
+  assert.strictEqual(sha256Hex(""), "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
+  assert.strictEqual(sha256Hex("abc"), "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad");
+  const trusted = computeTrustedHash({ sourcePath: "/h/.codex/hooks.json", eventLabel: "stop", groupIndex: 0, handlerIndex: 0, command: "x", timeoutSec: 10 });
+  assert.ok(/^sha256:[0-9a-f]{64}$/.test(trusted), "trusted hash is sha256:<64 hex>");
+  assert.strictEqual(trusted, computeTrustedHash({ sourcePath: "/other", eventLabel: "stop", groupIndex: 5, handlerIndex: 9, command: "x", timeoutSec: 10 }), "hash ignores path/position (Codex hashes only the handler identity)");
+}
+
+// ── Codex: hooks.json + config.toml trust, positions shared across both ───────
+{
+  const plan = codexAdapter.plan(POSIX);
+  const [hooksEdit, tomlEdit] = plan.configs;
+  assert.strictEqual(hooksEdit.path, "/home/u/.codex/hooks.json");
+  assert.strictEqual(tomlEdit.path, "/home/u/.codex/config.toml");
+  // hooks.json apply must run first (it fills the group positions the toml uses).
+  const hooksOut = hooksEdit.apply('{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"user-stop"}]}]}}')!;
+  const hj = JSON.parse(hooksOut);
+  assert.ok(hj.hooks.Stop.some((d: { hooks?: { command?: string }[] }) => d.hooks?.[0]?.command === "user-stop"), "user codex hook preserved");
+  assert.ok(hj.hooks.Stop[1].hooks[0].command.includes("tempest-codex-hook"), "our hook appended last");
+  const toml = tomlEdit.apply(null)!;
+  assert.ok(toml.includes('[hooks.state."/home/u/.codex/hooks.json:stop:1:0"]'), "trust key uses the shared group index (1)");
+  assert.ok(toml.includes("trusted_hash"), "trust block carries a hash");
+  assert.ok(toml.includes("enabled = true"));
+  // remove strips both.
+  assert.ok(!codexAdapter.plan(POSIX).configs[0].remove(hooksOut)!.includes("tempest-codex-hook"), "codex hooks.json remove strips ours");
+  const rem = codexAdapter.plan(POSIX).configs[1].remove(toml);
+  assert.ok(rem !== null && !rem.includes("tempest-codex-hook.sh".slice(0, 0) + "hooks.json:stop"), "codex toml remove strips our trust");
+  assert.strictEqual(codexAdapter.parse({ hook_event_name: "PermissionRequest" }), "waiting");
+  assert.strictEqual(codexAdapter.parse({ hook_event_name: "session_start" }), "working", "snake_case events accepted");
+  assert.strictEqual(codexAdapter.parse({ hook_event_name: "PreToolUse", tool_name: "request_user_input" }), "waiting");
+  assert.strictEqual(codexAdapter.parse({ hook_event_name: "Stop" }), "done");
+}
+
+// ── Hermes: enable in YAML, plugin files, approval → waiting ──────────────────
+{
+  const plan = hermesAdapter.plan(POSIX);
+  assert.strictEqual(plan.scripts.length, 2, "hermes writes plugin.yaml + __init__.py");
+  assert.ok(plan.scripts.some((s) => s.path.endsWith("__init__.py") && s.content.includes("/hook/hermes")), "python plugin posts to hermes route");
+  const enabled = plan.configs[0].apply("plugins:\n  enabled: [other]\n")!;
+  assert.ok(enabled.includes("tempest-status"), "plugin enabled in config.yaml");
+  assert.ok(enabled.includes("other"), "existing enabled plugins preserved");
+  const disabled = plan.configs[0].remove(enabled);
+  assert.ok(disabled !== null && !disabled.includes("tempest-status"), "hermes remove disables the plugin");
+  assert.strictEqual(hermesAdapter.parse({ hook_event_name: "pre_approval_request" }), "waiting");
+  assert.strictEqual(hermesAdapter.parse({ hook_event_name: "post_llm_call" }), "done");
+  assert.strictEqual(hermesAdapter.parse({ hook_event_name: "pre_tool_call" }), "working");
+}
+
+// ── Opencode: JS plugin file, event map ──────────────────────────────────────
+{
+  const plan = opencodeAdapter.plan(POSIX);
+  assert.strictEqual(plan.configs[0].path, "/home/u/.config/opencode/plugin/tempest-status.js");
+  const js = plan.configs[0].apply(null)!;
+  assert.ok(js.includes("/hook/opencode") && js.includes("permission.asked"), "plugin maps opencode events");
+  assert.ok(js.includes("X-Tempest-Session"), "plugin sends the session header");
+  const removed = plan.configs[0].remove(js);
+  assert.ok(removed !== null && !removed.includes("permission.asked"), "remove replaces with a no-op plugin");
+  assert.strictEqual(plan.configs[0].remove(removed), null, "remove is idempotent");
+  assert.strictEqual(opencodeAdapter.parse({ hook_event_name: "SessionBusy" }), "working");
+  assert.strictEqual(opencodeAdapter.parse({ hook_event_name: "SessionIdle" }), "done");
+  assert.strictEqual(opencodeAdapter.parse({ hook_event_name: "PermissionRequest" }), "waiting");
+}
+
+console.log("agentHooks installer.check: all assertions passed");
diff --git a/src/lib/agentHooks/installer.ts b/src/lib/agentHooks/installer.ts
new file mode 100644
index 0000000..45e7a38
--- /dev/null
+++ b/src/lib/agentHooks/installer.ts
@@ -0,0 +1,98 @@
+// Install engine — agent-agnostic. Drives a HookAdapter's pure plan through the
+// Rust filesystem commands to (un)install its managed hooks, preserving the
+// user's own config. Every write is atomic and idempotent; a config an adapter
+// declines to edit (malformed, or nothing to change) is left untouched.
+
+import { invoke } from "@tauri-apps/api/core";
+import type { HookAdapter, HookPaths } from "./types";
+
+export interface InstallResult {
+  id: string;
+  ok: boolean;
+  changed: boolean;
+  detail?: string;
+}
+
+let cachedPaths: HookPaths | null = null;
+
+export async function getHookPaths(): Promise<HookPaths> {
+  if (cachedPaths) return cachedPaths;
+  const raw = await invoke<{
+    home: string;
+    hooks_dir: string;
+    endpoint_env: string;
+    endpoint_cmd: string;
+    windows: boolean;
+  }>("hooks_paths");
+  cachedPaths = {
+    home: raw.home,
+    hooksDir: raw.hooks_dir,
+    endpointEnv: raw.endpoint_env,
+    endpointCmd: raw.endpoint_cmd,
+    windows: raw.windows,
+  };
+  return cachedPaths;
+}
+
+async function readText(path: string): Promise<string | null> {
+  try {
+    return await invoke<string>("read_file", { path });
+  } catch {
+    return null; // missing/unreadable → the adapter starts from a blank config
+  }
+}
+
+async function writeAtomic(path: string, content: string, executable: boolean): Promise<void> {
+  await invoke("hooks_write_atomic", { path, content, executable });
+}
+
+// Apply (or, with `mode: "remove"`, strip) one config edit: read raw, transform,
+// and write atomically with a rolling .bak — but only when the text actually
+// changes and the transform returned something (null = leave untouched).
+async function editConfig(
+  edit: { path: string; apply: (raw: string | null) => string | null; remove: (raw: string | null) => string | null },
+  mode: "apply" | "remove",
+): Promise<boolean> {
+  const raw = await readText(edit.path);
+  const next = mode === "apply" ? edit.apply(raw) : edit.remove(raw);
+  if (next === null) return false;
+  if (raw !== null && raw === next) return false;
+  if (raw !== null && raw.trim().length > 0) {
+    await writeAtomic(`${edit.path}.bak`, raw, false);
+  }
+  await writeAtomic(edit.path, next, false);
+  return true;
+}
+
+export async function installAdapter(adapter: HookAdapter, paths: HookPaths): Promise<InstallResult> {
+  try {
+    const plan = adapter.plan(paths);
+    // Scripts first: if a config pointed at a not-yet-written script, the agent
+    // would exit-127 on every turn until the script landed.
+    for (const s of plan.scripts) {
+      await writeAtomic(s.path, s.content, s.executable);
+    }
+    let changed = false;
+    for (const c of plan.configs) {
+      if (await editConfig(c, "apply")) changed = true;
+    }
+    return { id: adapter.id, ok: true, changed };
+  } catch (e) {
+    return { id: adapter.id, ok: false, changed: false, detail: String(e) };
+  }
+}
+
+export async function uninstallAdapter(adapter: HookAdapter, paths: HookPaths): Promise<InstallResult> {
+  try {
+    const plan = adapter.plan(paths);
+    let changed = false;
+    for (const c of plan.configs) {
+      if (await editConfig(c, "remove")) changed = true;
+    }
+    // Managed scripts are left on disk (harmless once the config no longer
+    // references them); only the config entries decide whether a hook fires.
+    return { id: adapter.id, ok: true, changed };
+  } catch (e) {
+    return { id: adapter.id, ok: false, changed: false, detail: String(e) };
+  }
+}
diff --git a/src/lib/agentHooks/paths.ts b/src/lib/agentHooks/paths.ts
new file mode 100644
index 0000000..477b107
--- /dev/null
+++ b/src/lib/agentHooks/paths.ts
@@ -0,0 +1,15 @@
+// Tiny path helpers shared by adapters. Rust hands us native paths (backslashes
+// on Windows); config/script paths are built native, and forward-slash variants
+// are only needed for the Git-Bash-invoked command wrapper.
+
+export function sepFor(windows: boolean): string {
+  return windows ? "\\" : "/";
+}
+
+export function joinNative(windows: boolean, ...parts: string[]): string {
+  return parts.join(sepFor(windows));
+}
+
+export function toFwd(p: string): string {
+  return p.replace(/\\/g, "/");
+}
diff --git a/src/lib/agentHooks/schema.ts b/src/lib/agentHooks/schema.ts
new file mode 100644
index 0000000..965e2f3
--- /dev/null
+++ b/src/lib/agentHooks/schema.ts
@@ -0,0 +1,180 @@
+// Pure helpers for the "Claude-nested" hooks schema, shared by every adapter
+// whose config stores hooks as:
+//
+//   { "hooks": { "<Event>": [ { "matcher"?: "*", "hooks": [ { "type": "command",
+//                                                              "command": "…" } ] } ] } }
+//
+// (Claude, Gemini, Codex, Antigravity all use this shape.) Adapters with a
+// different shape — Cursor's direct `command` on the definition, Copilot's
+// per-event files — bring their own apply/remove and don't use this module.
+//
+// No React, no I/O: unit-testable on its own (see installer.check.ts).
+
+import type { JsonObject } from "./types";
+
+// A single event subscription. Tool events carry a matcher ("*" = all tools);
+// lifecycle events (Stop, UserPromptSubmit, …) have none.
+export interface NestedEvent {
+  name: string;
+  matcher?: boolean;
+}
+
+interface CommandHook {
+  type: "command";
+  command: string;
+  timeout?: number;
+  [k: string]: unknown;
+}
+
+interface HookDefinition {
+  matcher?: string;
+  command?: string;
+  hooks?: CommandHook[];
+  [k: string]: unknown;
+}
+
+// Host-side backstop: a status hook that can't reach a dead server must not stall
+// the agent's turn. The script's own curl --max-time is the first line; this is
+// the config-level ceiling. Unit is per-agent — Claude/Codex seconds, Gemini ms —
+// so the value is passed in, not assumed.
+const DEFAULT_HOOK_TIMEOUT = 10;
+
+// Match a config command by the managed script's *filename stem*, not an exact
+// string, so a fresh install sweeps entries left by an older Tempest build or a
+// platform switch (.cmd ⇄ .sh). Managed script names are `tempest-…-hook`, a
+// token distinctive enough to never collide with a user's own hook command.
+export function makeManagedMatcher(scriptFileName: string): (command: string | undefined) => boolean {
+  const stem = scriptFileName.replace(/\.(?:cmd|ps1|sh)$/i, "");
+  return (command) => {
+    if (!command) return false;
+    return command.replace(/\\/g, "/").includes(stem);
+  };
+}
+
+function buildManagedHook(command: string, timeout: number): CommandHook {
+  return { type: "command", command, timeout };
+}
+
+function definitionHasManaged(
+  def: HookDefinition,
+  isManaged: (c: string | undefined) => boolean,
+): boolean {
+  if (isManaged(def.command)) return true;
+  return Array.isArray(def.hooks) && def.hooks.some((h) => isManaged(h.command));
+}
+
+// Strip our managed command out of one event's definition list, dropping any
+// definition left empty. Preserves the user's own hooks untouched.
+function stripManaged(defs: HookDefinition[], isManaged: (c: string | undefined) => boolean): HookDefinition[] {
+  const out: HookDefinition[] = [];
+  for (const def of defs) {
+    if (!definitionHasManaged(def, isManaged)) {
+      out.push(def);
+      continue;
+    }
+    const next: HookDefinition = { ...def };
+    if (isManaged(next.command)) delete next.command;
+    if (Array.isArray(next.hooks)) {
+      const kept = next.hooks.filter((h) => !isManaged(h.command));
+      if (kept.length > 0) next.hooks = kept;
+      else delete next.hooks;
+    }
+    const stillHasSomething =
+      typeof next.command === "string" || (Array.isArray(next.hooks) && next.hooks.length > 0);
+    if (stillHasSomething) out.push(next);
+  }
+  return out;
+}
+
+// Splice our managed command into each subscribed event, first sweeping any
+// prior Tempest entry so re-install is idempotent. Returns a new config; the
+// input is not mutated. All non-hook keys and every user hook are preserved.
+export function applyNestedHooks(
+  config: JsonObject,
+  command: string,
+  scriptFileName: string,
+  events: NestedEvent[],
+  timeout: number = DEFAULT_HOOK_TIMEOUT,
+): JsonObject {
+  const isManaged = makeManagedMatcher(scriptFileName);
+  const prevHooks = (config.hooks && typeof config.hooks === "object" ? config.hooks : {}) as Record<
+    string,
+    HookDefinition[]
+  >;
+  const nextHooks: Record<string, HookDefinition[]> = { ...prevHooks };
+  for (const event of events) {
+    const current = Array.isArray(nextHooks[event.name]) ? nextHooks[event.name] : [];
+    const cleaned = stripManaged(current, isManaged);
+    const def: HookDefinition = event.matcher
+      ? { matcher: "*", hooks: [buildManagedHook(command, timeout)] }
+      : { hooks: [buildManagedHook(command, timeout)] };
+    nextHooks[event.name] = [...cleaned, def];
+  }
+  return { ...config, hooks: nextHooks };
+}
+
+// Remove every Tempest-owned entry across all event buckets, dropping buckets
+// left empty. `changed` is false when nothing of ours was present.
+export function removeNestedHooks(
+  config: JsonObject,
+  scriptFileName: string,
+): { config: JsonObject; changed: boolean } {
+  const isManaged = makeManagedMatcher(scriptFileName);
+  const prevHooks = (config.hooks && typeof config.hooks === "object" ? config.hooks : null) as Record<
+    string,
+    HookDefinition[]
+  > | null;
+  if (!prevHooks) return { config, changed: false };
+  const nextHooks: Record<string, HookDefinition[]> = {};
+  let changed = false;
+  for (const [name, defs] of Object.entries(prevHooks)) {
+    if (!Array.isArray(defs)) {
+      nextHooks[name] = defs;
+      continue;
+    }
+    const cleaned = stripManaged(defs, isManaged);
+    if (cleaned.length !== defs.length || JSON.stringify(cleaned) !== JSON.stringify(defs)) {
+      changed = true;
+    }
+    if (cleaned.length > 0) nextHooks[name] = cleaned;
+  }
+  return { config: { ...config, hooks: nextHooks }, changed };
+}
+
+// ── raw-text config helpers (for ConfigEdit.apply / .remove) ─────────────────
+// Parse a JSON config file, run a transform, re-serialize. A missing/empty file
+// starts from {}. Malformed JSON returns null so the engine leaves the user's
+// (currently broken) file untouched rather than clobbering it.
+export function applyJsonConfig(
+  raw: string | null,
+  transform: (config: JsonObject) => JsonObject,
+): string | null {
+  const obj = parseConfigObject(raw);
+  if (obj === "malformed") return null;
+  return JSON.stringify(transform(obj), null, 2) + "\n";
+}
+
+// Remove path: never create the file (null in → null out), never touch malformed
+// JSON, and skip the write when the transform reports no change.
+export function removeJsonConfig(
+  raw: string | null,
+  transform: (config: JsonObject) => { config: JsonObject; changed: boolean },
+): string | null {
+  if (raw === null || raw.trim() === "") return null;
+  const obj = parseConfigObject(raw);
+  if (obj === "malformed") return null;
+  const { config, changed } = transform(obj);
+  if (!changed) return null;
+  return JSON.stringify(config, null, 2) + "\n";
+}
+
+function parseConfigObject(raw: string | null): JsonObject | "malformed" {
+  if (raw === null || raw.trim() === "") return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed as JsonObject;
+    return "malformed";
+  } catch {
+    return "malformed";
+  }
+}
diff --git a/src/lib/agentHooks/script.ts b/src/lib/agentHooks/script.ts
new file mode 100644
index 0000000..041762e
--- /dev/null
+++ b/src/lib/agentHooks/script.ts
@@ -0,0 +1,60 @@
+// Shared managed-hook script body. Every agent's script does the same thing —
+// source the endpoint file for the current port/token, bail if unset, then POST
+// the stdin payload to /hook/<route> tagged with $TEMPEST_SESSION — differing
+// only in the route and whether the agent requires a JSON object on the hook's
+// stdout (Gemini/Cursor parse it; Claude tolerates empty output).
+
+export interface HookScriptOptions {
+  route: string;
+  endpointCmd: string; // Windows-native path to endpoint.cmd
+  endpointEnv: string; // POSIX path to endpoint.env
+  windows: boolean;
+  // Emit `{}` to stdout first (agents that parse the hook's stdout as JSON).
+  emitEmptyJson?: boolean;
+  // Name of an env var holding the lifecycle event name, for agents whose
+  // payload doesn't carry it (Antigravity, Copilot). Sent as X-Tempest-Event.
+  eventEnvVar?: string;
+}
+
+export function buildHookScript(o: HookScriptOptions): string {
+  return o.windows ? windows(o) : posix(o);
+}
+
+function windows(o: HookScriptOptions): string {
+  const eventHeader = o.eventEnvVar ? ` -H "X-Tempest-Event: %${o.eventEnvVar}%"` : "";
+  const lines = ["@echo off", "setlocal"];
+  if (o.emitEmptyJson) lines.push("echo {}");
+  lines.push(
+    `if exist "${o.endpointCmd}" call "${o.endpointCmd}" >nul 2>nul`,
+    `if "%TEMPEST_HOOK_PORT%"=="" exit /b 0`,
+    `if "%TEMPEST_SESSION%"=="" exit /b 0`,
+    // curl.exe (Win10 1803+) reads the payload from stdin via --data-binary @-,
+    // fully qualified so a repo-local curl.exe can't hijack it.
+    `"%SystemRoot%\\System32\\curl.exe" -sS -X POST "http://127.0.0.1:%TEMPEST_HOOK_PORT%/hook/${o.route}" --connect-timeout 0.5 --max-time 1.5 -H "X-Tempest-Token: %TEMPEST_HOOK_TOKEN%" -H "X-Tempest-Session: %TEMPEST_SESSION%"${eventHeader} -H "Content-Type: application/json" --data-binary @- >nul 2>nul`,
+    "exit /b 0",
+    "",
+  );
+  return lines.join("\r\n");
+}
+
+function posix(o: HookScriptOptions): string {
+  const lines = ["#!/bin/sh"];
+  if (o.emitEmptyJson) lines.push("printf '{}\\n'");
+  // Single-quoted lines keep the shell `$VAR` refs literal in the generated file.
+  lines.push(
+    'if [ -r "' + o.endpointEnv + '" ]; then . "' + o.endpointEnv + '" 2>/dev/null || :; fi',
+    'if [ -z "$TEMPEST_HOOK_PORT" ] || [ -z "$TEMPEST_SESSION" ]; then exit 0; fi',
+    'curl -sS -X POST "http://127.0.0.1:${TEMPEST_HOOK_PORT}/hook/' + o.route + '" \\',
+    "  --connect-timeout 0.5 --max-time 1.5 \\",
+    '  -H "X-Tempest-Token: ${TEMPEST_HOOK_TOKEN}" \\',
+    '  -H "X-Tempest-Session: ${TEMPEST_SESSION}" \\',
+  );
+  if (o.eventEnvVar) lines.push('  -H "X-Tempest-Event: ${' + o.eventEnvVar + '}" \\');
+  lines.push(
+    '  -H "Content-Type: application/json" \\',
+    "  --data-binary @- >/dev/null 2>&1 || true",
+    "exit 0",
+    "",
+  );
+  return lines.join("\n");
+}
diff --git a/src/lib/agentHooks/types.ts b/src/lib/agentHooks/types.ts
new file mode 100644
index 0000000..203e15e
--- /dev/null
+++ b/src/lib/agentHooks/types.ts
@@ -0,0 +1,63 @@
+// Shared types for the agent-hooks subsystem.
+//
+// A hook adapter teaches Tempest how ONE agent's lifecycle hooks work: where its
+// config lives, what the managed script/command look like, how to splice our
+// entry into (and out of) that config without disturbing the user's own hooks,
+// and how to map a received event onto the 3-state model. The install engine
+// (`installer.ts`) and the runtime receiver (`../../store/agentHooks.ts`) are
+// agent-agnostic and drive adapters through this interface.
+
+// The canonical status a hook resolves to. "waiting" is our "needs you" state —
+// the receiver maps it onto the existing `done` + attention pair.
+export type HookState = "working" | "waiting" | "done";
+
+export type JsonObject = Record<string, unknown>;
+
+// Filesystem locations + platform, sourced from Rust (`hooks_paths` command).
+export interface HookPaths {
+  home: string;
+  hooksDir: string;
+  endpointEnv: string;
+  endpointCmd: string;
+  windows: boolean;
+}
+
+// A managed script/plugin file written into the shared hooks dir.
+export interface ScriptFile {
+  path: string;
+  content: string;
+  executable: boolean;
+}
+
+// One config file the adapter edits. `apply`/`remove` take the file's raw text
+// (null when absent) and return the new text, or null to leave it untouched
+// (malformed JSON, nothing to change, or "don't create on remove"). Raw text in
+// and out lets a JSON adapter parse+merge while Codex byte-edits its TOML — both
+// fit one engine.
+export interface ConfigEdit {
+  path: string;
+  apply: (raw: string | null) => string | null;
+  remove: (raw: string | null) => string | null;
+}
+
+// Everything an adapter produces for a single install, computed for the current
+// platform. Pure data + pure functions so it is unit-testable off-device. An
+// adapter may write several scripts (e.g. Antigravity's per-event wrappers) and
+// touch several config files (e.g. Codex's hooks.json + config.toml).
+export interface AdapterInstall {
+  scripts: ScriptFile[];
+  configs: ConfigEdit[];
+}
+
+export interface HookAdapter {
+  // Manifest agent id (`AgentConfig.id`) AND the `/hook/<id>` route the script posts to.
+  id: string;
+  // True when this agent's hook set includes a permission/waiting event. When
+  // false, hooks drive working/done but the PTY attention heuristics (title ✋,
+  // OSC RequestAttention, BEL) stay live so the agent keeps a "needs you" signal.
+  coversWaiting: boolean;
+  // Build the install for the current platform/paths.
+  plan: (paths: HookPaths) => AdapterInstall;
+  // Map a parsed hook payload to a state, or null to ignore this event.
+  parse: (body: unknown) => HookState | null;
+}
diff --git a/src/lib/agentHooks/wrappers.ts b/src/lib/agentHooks/wrappers.ts
new file mode 100644
index 0000000..e427956
--- /dev/null
+++ b/src/lib/agentHooks/wrappers.ts
@@ -0,0 +1,71 @@
+// How each agent's config invokes the managed hook script. Agents don't all run
+// hook commands through the same shell — Claude uses Git Bash on Windows, Gemini/
+// Cursor run an arbitrary shell (so an encoded-PowerShell one-liner is safest),
+// Antigravity/Codex spawn the command as argv[0] (so a bare path). Each wrapper
+// also guards a missing script so a stale config entry is a silent no-op that
+// still drains the agent's stdin payload, never an exit-127 on every turn.
+//
+// Ported from Orca's installer-utils (design, not code) — no Node Buffer, so
+// base64 is done with browser-safe primitives that also work under `node`.
+
+// Drains the agent's stdin payload so a missing script doesn't leave the write
+// end blocking. `|| true` keeps a hook wrapper from tripping an outer set -e.
+const POSIX_STDIN_DRAIN = "cat >/dev/null 2>&1 || true";
+
+function sq(s: string): string {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
+// Claude: Git Bash executes a forward-slash .cmd/.sh path directly.
+export function wrapGitBash(scriptPathFwd: string): string {
+  const q = sq(scriptPathFwd);
+  return `if [ -f ${q} ]; then ${q}; else ${POSIX_STDIN_DRAIN}; fi`;
+}
+
+// mac/linux: guard for a readable + executable file, run via /bin/sh. `env`
+// entries are prefixed on the invocation (used to pass a per-event name).
+export function wrapPosix(scriptPath: string, env: Record<string, string> = {}): string {
+  const q = sq(scriptPath);
+  const prefix = Object.entries(env)
+    .map(([k, v]) => `${k}='${v.replace(/'/g, "'\\''")}' `)
+    .join("");
+  return `if [ -f ${q} ] && [ -x ${q} ]; then ${prefix}/bin/sh ${q}; else ${POSIX_STDIN_DRAIN}; fi`;
+}
+
+// A non-encoded PowerShell one-liner that sets env vars then runs the script.
+// Used where an agent's config invokes the command AS PowerShell (Copilot's
+// `powershell` hook field), so a nested encoded launcher would be wasteful.
+export function wrapPowerShellInline(scriptPath: string, env: Record<string, string> = {}): string {
+  const q = "'" + scriptPath.replace(/'/g, "''") + "'";
+  const prefix = Object.entries(env)
+    .map(([k, v]) => `$env:${k} = '${v.replace(/'/g, "''")}'; `)
+    .join("");
+  return `${prefix}if (Test-Path -LiteralPath ${q} -PathType Leaf) { & ${q} }`;
+}
+
+// Windows, shell-agnostic: an encoded PowerShell command runs whatever shell the
+// agent uses to launch hooks, tests the path, and drains stdin when it's gone.
+export function wrapEncodedPowerShell(scriptPath: string): string {
+  const q = "'" + scriptPath.replace(/'/g, "''") + "'";
+  const cmd = `if (Test-Path -LiteralPath ${q} -PathType Leaf) { & ${q}; exit $LASTEXITCODE }; [Console]::In.ReadToEnd() | Out-Null; exit 0`;
+  const encoded = base64Utf16le(cmd);
+  return `%SystemRoot%\\System32\\WindowsPowerShell\\v1.0\\powershell.exe -NoProfile -ExecutionPolicy Bypass -EncodedCommand ${encoded}`;
+}
+
+// Antigravity/Codex spawn the hook as argv[0], so the command must be one
+// spawnable token — a bare path when it's shell-safe, else the encoded launcher.
+const CMD_SAFE_PATH = /^[A-Za-z0-9_.:\\/~-]+$/;
+export function wrapBarePathOrEncoded(scriptPath: string): string {
+  return CMD_SAFE_PATH.test(scriptPath) ? scriptPath : wrapEncodedPowerShell(scriptPath);
+}
+
+// UTF-16LE → base64, for PowerShell -EncodedCommand. btoa exists in both the
+// Tauri webview and node. Hook script paths are BMP, so charCodeAt is exact.
+function base64Utf16le(s: string): string {
+  let binary = "";
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    binary += String.fromCharCode(c & 0xff, (c >> 8) & 0xff);
+  }
+  return btoa(binary);
+}
diff --git a/src/lib/quota.check.ts b/src/lib/quota.check.ts
new file mode 100644
index 0000000..9098b67
--- /dev/null
+++ b/src/lib/quota.check.ts
@@ -0,0 +1,37 @@
+// Self-check for the quota helpers behind the title-bar island.
+// Run with `node src/lib/quota.check.ts` (Node strips the types natively).
+import assert from "node:assert";
+import { CRIT, WARN, formatReset, levelOf, pct, peakQuota, type QuotaWindow } from "./quota.ts";
+
+// ── level thresholds are inclusive at the boundary ───────────────────────────
+assert.strictEqual(levelOf(0), "ok");
+assert.strictEqual(levelOf(WARN - 0.001), "ok");
+assert.strictEqual(levelOf(WARN), "warn", "the island must open up exactly at the warn mark");
+assert.strictEqual(levelOf(CRIT - 0.001), "warn");
+assert.strictEqual(levelOf(CRIT), "crit");
+assert.strictEqual(levelOf(1.4), "crit", "an over-budget window is still critical, not wrapped");
+
+// ── pct clamps rather than printing a bar wider than its track ───────────────
+assert.strictEqual(pct(0.5), 50);
+assert.strictEqual(pct(0.006), 1);
+assert.strictEqual(pct(1.4), 100, "an over-budget window must not overflow the bar");
+assert.strictEqual(pct(-1), 0);
+
+// ── the island speaks for the fullest window ─────────────────────────────────
+const q = (id: string, used: number): QuotaWindow => ({ id, label: id, used, resetsAt: 0 });
+assert.strictEqual(peakQuota([]), null, "no data is not a zeroed window");
+assert.strictEqual(peakQuota([q("a", 0.2), q("b", 0.8), q("c", 0.5)])?.id, "b");
+assert.strictEqual(peakQuota([q("a", 0), q("b", 0)])?.id, "a", "a tie keeps the first, so the pill does not flicker");
+
+// ── reset text never prints a nonsense duration ──────────────────────────────
+const now = 1_000_000_000_000;
+const at = (ms: number) => formatReset(now + ms, now);
+assert.strictEqual(at(-5_000), "resetting");
+assert.strictEqual(at(0), "resetting");
+assert.strictEqual(at(30_000), "resets in 1m", "under a minute rounds up, never to 0m");
+assert.strictEqual(at(8 * 60_000), "resets in 8m");
+assert.strictEqual(at(59.6 * 60_000), "resets in 1h", "rounding to 60 minutes must carry, not print 60m");
+assert.strictEqual(at(60 * 60_000), "resets in 1h");
+assert.strictEqual(at(134 * 60_000), "resets in 2h 14m");
+
+console.log("quota.check.ts — all assertions passed");
diff --git a/src/lib/quota.ts b/src/lib/quota.ts
new file mode 100644
index 0000000..654e639
--- /dev/null
+++ b/src/lib/quota.ts
@@ -0,0 +1,55 @@
+// Rate-limit windows read from the agent CLIs' own credentials, surfaced by the
+// title-bar island. Pure shape + formatting here; the reader lands beside it.
+
+export interface QuotaWindow {
+  /** Stable key — provider + window, e.g. `claude-5h`. */
+  id: string;
+  /** Shown verbatim in the island, e.g. `Claude · 5h`. */
+  label: string;
+  /** Fraction of the window consumed. Clamped on display, not here. */
+  used: number;
+  /** Epoch ms at which the window rolls over. */
+  resetsAt: number;
+}
+
+export type QuotaLevel = "ok" | "warn" | "crit";
+
+/** Below WARN the island stays a dot; at WARN it opens up and names the window. */
+export const WARN = 0.75;
+export const CRIT = 0.9;
+
+export function levelOf(used: number): QuotaLevel {
+  return used >= CRIT ? "crit" : used >= WARN ? "warn" : "ok";
+}
+
+export function pct(used: number): number {
+  return Math.round(Math.min(1, Math.max(0, used)) * 100);
+}
+
+/** The window the island speaks for: the fullest one. */
+export function peakQuota(quotas: QuotaWindow[]): QuotaWindow | null {
+  return quotas.reduce<QuotaWindow | null>((a, b) => (a && a.used >= b.used ? a : b), null);
+}
+
+/**
+ * Stand-in so the island can be looked at before the reader exists — wired in
+ * under `import.meta.env.DEV` only, so it never reaches a build. Delete this
+ * and its call site once real windows are being read.
+ * ponytail: dev-only placeholder, goes away with the CLI reader.
+ */
+export const SAMPLE_QUOTAS: QuotaWindow[] = [
+  { id: "claude-5h", label: "Claude · 5h", used: 0.82, resetsAt: Date.now() + 134 * 60_000 },
+  { id: "claude-week", label: "Claude · weekly", used: 0.41, resetsAt: Date.now() + 3.2 * 86_400_000 },
+  { id: "codex", label: "Codex", used: 0.16, resetsAt: Date.now() + 47 * 60_000 },
+];
+
+export function formatReset(resetsAt: number, now = Date.now()): string {
+  const ms = resetsAt - now;
+  if (ms <= 0) return "resetting";
+  // Round to whole minutes first so 59m30s never prints as "0h 60m".
+  const mins = Math.max(1, Math.round(ms / 60_000));
+  if (mins < 60) return `resets in ${mins}m`;
+  const h = Math.floor(mins / 60);
+  const m = mins % 60;
+  return m ? `resets in ${h}h ${m}m` : `resets in ${h}h`;
+}
diff --git a/src/lib/tempestConfig.check.ts b/src/lib/tempestConfig.check.ts
index 8b0066a..f4e9529 100644
--- a/src/lib/tempestConfig.check.ts
+++ b/src/lib/tempestConfig.check.ts
@@ -13,7 +13,7 @@ const base: ProjectSettings = {
   sandbox: { mode: "monitor" },
   network: { policy: "permissive", allowHosts: ["a.com", "b.com"], blockHosts: ["bad.com"] },
   filesystem: { rwPaths: [".", "src"], roPaths: ["vendor"] },
-  permissions: { allowSkipPermissions: true },
+  permissions: { allowSkipPermissions: true, allowRepoHooks: false },
   agents: { permitted: ["claude", "codex", "gemini"] },
   database: { isolationEnabled: false },
   resources: { maxMemoryMb: 4096, maxProcesses: null, maxDiskWriteMb: null, cpuWeight: null },
@@ -26,7 +26,7 @@ const base: ProjectSettings = {
     sandbox: { mode: "off" },
     network: { policy: "permissive", allowHosts: ["a.com", "b.com", "evil.com"], blockHosts: [] },
     filesystem: { rwPaths: [".", "src", "/etc"], roPaths: ["vendor", "/root"] },
-    permissions: { allowSkipPermissions: true },
+    permissions: { allowSkipPermissions: true, allowRepoHooks: true },
     agents: { permitted: ["claude", "codex", "gemini", "rogue"] },
     database: { isolationEnabled: false },
     resources: { maxMemoryMb: 99999, maxProcesses: 500, maxDiskWriteMb: 900, cpuWeight: 100 },
@@ -38,6 +38,7 @@ const base: ProjectSettings = {
   assert.deepStrictEqual(widened.filesystem.roPaths, ["vendor"], "yml must not add ro paths");
   assert.deepStrictEqual(widened.agents.permitted, ["claude", "codex", "gemini"], "yml must not add agents");
   assert.strictEqual(widened.resources.maxMemoryMb, 4096, "yml must not raise a quota");
+  assert.strictEqual(widened.permissions.allowRepoHooks, false, "yml must not grant itself unprompted hooks");
   // Quotas the user left unset are "no limit", so yml setting one is a tightening.
   assert.strictEqual(widened.resources.maxProcesses, 500, "yml may set an unset quota");
 }
@@ -48,7 +49,7 @@ const base: ProjectSettings = {
     sandbox: { mode: "enforce" },
     network: { policy: "restrictive", allowHosts: ["a.com"], blockHosts: ["worse.com"] },
     filesystem: { rwPaths: ["src"], roPaths: [] },
-    permissions: { allowSkipPermissions: false },
+    permissions: { allowSkipPermissions: false, allowRepoHooks: false },
     agents: { permitted: ["claude"] },
     database: { isolationEnabled: true },
     resources: { maxMemoryMb: 512, maxProcesses: null, maxDiskWriteMb: null, cpuWeight: null },
@@ -70,6 +71,19 @@ const base: ProjectSettings = {
   assert.deepStrictEqual(clampSecurity(base, {}), base);
 }
 
+{
+  // A repo may revoke its own hook autonomy, never grant it.
+  const trusted: ProjectSettings = {
+    ...base,
+    permissions: { allowSkipPermissions: true, allowRepoHooks: true },
+  };
+  assert.strictEqual(
+    clampSecurity(trusted, { permissions: { allowSkipPermissions: true, allowRepoHooks: false } })
+      .permissions.allowRepoHooks,
+    false,
+  );
+}
+
 {
   // Enforce must survive a yml asking for the weaker "monitor".
   const strict: ProjectSettings = { ...base, sandbox: { mode: "enforce" } };
@@ -131,6 +145,34 @@ env:
   assert.strictEqual(cfg.warnings.length, 5, "every dropped env var warns");
 }
 
+// ── worktree hooks ───────────────────────────────────────────────────────────
+{
+  // One command or a list; both spellings land as a list, blanks dropped.
+  const single = parseTempestConfig(`setup: npm install`);
+  assert.deepStrictEqual(single.hooks.setup, ["npm install"]);
+  assert.deepStrictEqual(single.hooks.teardown, []);
+
+  const many = parseTempestConfig(`
+setup:
+  - npm install
+  - "  "
+  - cp ../.env .env
+teardown:
+  - docker compose down
+`);
+  assert.deepStrictEqual(many.hooks.setup, ["npm install", "cp ../.env .env"]);
+  assert.deepStrictEqual(many.hooks.teardown, ["docker compose down"]);
+  assert.deepStrictEqual(many.warnings, []);
+
+  // A hook that is neither a string nor a list of them is dropped, with a warning.
+  const wrong = parseTempestConfig(`setup:\n  cmd: npm install`);
+  assert.deepStrictEqual(wrong.hooks.setup, []);
+  assert.strictEqual(wrong.warnings.length, 1);
+
+  // No hooks is empty arrays, so callers can skip on length without a branch.
+  assert.deepStrictEqual(parseTempestConfig("preview:\n  port: 3000").hooks, { setup: [], teardown: [] });
+}
+
 {
   // Malformed input degrades to "no config" instead of throwing.
   const bad = parseTempestConfig("sandbox: [unclosed\n  : :");
diff --git a/src/lib/tempestConfig.ts b/src/lib/tempestConfig.ts
index a2878b7..abcff29 100644
--- a/src/lib/tempestConfig.ts
+++ b/src/lib/tempestConfig.ts
@@ -15,12 +15,15 @@ export interface TempestConfig {
   instructions?: string;
   env?: Record<string, string>;
   preview?: { port?: number };
+  /// Shell commands run around a worktree's life: `setup` once after it is
+  /// created, `teardown` before it is removed. Empty arrays when absent.
+  hooks: { setup: string[]; teardown: string[] };
   /// Human-readable notes about what was dropped during parse/clamp. Surfaced in
   /// the console so a config that silently does nothing is diagnosable.
   warnings: string[];
 }
 
-const EMPTY: TempestConfig = { security: {}, warnings: [] };
+const EMPTY: TempestConfig = { security: {}, warnings: [], hooks: { setup: [], teardown: [] } };
 
 // ── env allow rules ──────────────────────────────────────────────────────────
 // `env` writes straight into the agent's process environment, so a hostile repo
@@ -52,6 +55,11 @@ const posInt = (v: unknown): number | undefined =>
 const isObj = (v: unknown): v is Record<string, unknown> =>
   typeof v === "object" && v !== null && !Array.isArray(v);
 
+/// A hook is one command or a list of them; both spellings are natural in yml.
+/// Blank entries are dropped rather than handed to a shell.
+const cmdList = (v: unknown): string[] =>
+  (typeof v === "string" ? [v] : strList(v) ?? []).map((c) => c.trim()).filter(Boolean);
+
 /// Assign only when `v` is defined, so an absent yml key means "no opinion"
 /// rather than "reset to undefined".
 function put<T extends object, K extends keyof T>(target: T, key: K, v: T[K] | undefined) {
@@ -102,8 +110,10 @@ export function clampSecurity(
     if (yml.filesystem.roPaths) out.filesystem.roPaths = intersect(base.filesystem.roPaths, yml.filesystem.roPaths);
   }
 
-  // Only ever revokes the bypass.
+  // Only ever revokes. A repo asking to run its own hooks unprompted would be
+  // granting itself privilege, which is the one direction this merge forbids.
   if (yml.permissions?.allowSkipPermissions === false) out.permissions.allowSkipPermissions = false;
+  if (yml.permissions?.allowRepoHooks === false) out.permissions.allowRepoHooks = false;
 
   // Only ever removes agents from the permitted set.
   if (yml.agents?.permitted) out.agents.permitted = intersect(base.agents.permitted, yml.agents.permitted);
@@ -164,8 +174,10 @@ export function parseTempestConfig(text: string): TempestConfig {
   }
 
   if (isObj(doc.permissions)) {
-    const b = bool(doc.permissions.allowSkipPermissions);
-    if (b !== undefined) security.permissions = { allowSkipPermissions: b };
+    const p: Partial<ProjectSettings["permissions"]> = {};
+    put(p, "allowSkipPermissions", bool(doc.permissions.allowSkipPermissions));
+    put(p, "allowRepoHooks", bool(doc.permissions.allowRepoHooks));
+    if (Object.keys(p).length) security.permissions = p as ProjectSettings["permissions"];
   }
 
   if (isObj(doc.agents)) {
@@ -187,7 +199,13 @@ export function parseTempestConfig(text: string): TempestConfig {
     if (Object.keys(r).length) security.resources = r as ProjectSettings["resources"];
   }
 
-  const out: TempestConfig = { security, warnings };
+  const out: TempestConfig = {
+    security,
+    warnings,
+    hooks: { setup: cmdList(doc.setup), teardown: cmdList(doc.teardown) },
+  };
+  if (doc.setup !== undefined && !out.hooks.setup.length) warnings.push(`setup must be a command or a list of commands — ignored.`);
+  if (doc.teardown !== undefined && !out.hooks.teardown.length) warnings.push(`teardown must be a command or a list of commands — ignored.`);
 
   const instructions = str(doc.instructions);
   if (instructions?.trim()) out.instructions = instructions.trim();
diff --git a/src/lib/worktreeHooks.ts b/src/lib/worktreeHooks.ts
new file mode 100644
index 0000000..9bd8ac5
--- /dev/null
+++ b/src/lib/worktreeHooks.ts
@@ -0,0 +1,46 @@
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+import { loadTempestConfig } from "./tempestConfig";
+
+// `tempest.yml` worktree hooks — `setup` after a worktree is created, `teardown`
+// before it is removed. A fresh worktree has no node_modules and none of the
+// repo's ignored files, so this is where dependencies get installed and secrets
+// copied across from the source checkout.
+//
+// These commands come from a file the repo carries, which means running them is
+// running code the user may not have written. Consent is the caller's job (see
+// `permissions.allowRepoHooks`); this module only reads and runs.
+
+export type HookKind = "setup" | "teardown";
+
+/// The commands a project's config declares for `kind`. Empty when there is no
+/// config, no hook, or the file is malformed — callers can skip on `length`.
+export async function getHookCommands(projectPath: string, kind: HookKind): Promise<string[]> {
+  const cfg = await loadTempestConfig(projectPath);
+  return cfg.hooks[kind];
+}
+
+/// Run `kind`'s commands in `cwd`, resolving only once every one has exited 0.
+/// Rejects with the failing command and its last stderr line.
+///
+/// `onLine` receives stdout and stderr as they arrive, plus a `$ command` line
+/// before each — enough for a modal to show what is happening during an install
+/// that takes minutes.
+export async function runHook(
+  projectPath: string,
+  kind: HookKind,
+  cwd: string,
+  onLine?: (line: string) => void,
+): Promise<void> {
+  const cfg = await loadTempestConfig(projectPath);
+  const commands = cfg.hooks[kind];
+  if (!commands.length) return;
+
+  const token = crypto.randomUUID();
+  const unlisten = await listen<string>(`hook:${token}`, (e) => onLine?.(e.payload));
+  try {
+    await invoke("run_hook", { token, cwd, commands, env: cfg.env ?? null });
+  } finally {
+    unlisten();
+  }
+}
diff --git a/src/store/agentHooks.ts b/src/store/agentHooks.ts
new file mode 100644
index 0000000..b728ab3
--- /dev/null
+++ b/src/store/agentHooks.ts
@@ -0,0 +1,70 @@
+// Runtime receiver for agent lifecycle hooks.
+//
+// The Rust loopback server (src-tauri/src/agent_hooks.rs) forwards each hook POST
+// as an `agent-hook` event carrying the agent id, the Tempest session id (echoed
+// back from the TEMPEST_SESSION env we inject at spawn), and the raw agent
+// payload. Here we parse it through the matching adapter and drive the existing
+// 3-state model via sessionManager — which flips the session to hook-authoritative
+// and retires its PTY-scraping heuristics.
+
+import { listen } from "@tauri-apps/api/event";
+import { sessionManager } from "./sessionManager";
+import { getSettings } from "./appSettings";
+import { getAdapter, installAll, uninstallAll } from "../lib/agentHooks";
+
+interface AgentHookEvent {
+  agent: string;
+  session: string;
+  event: string;
+  body: string;
+}
+
+let started = false;
+
+// Wire the receiver and, when precise status is enabled, install the managed
+// hooks. Idempotent: safe to call once at app startup.
+export async function startAgentHooks(): Promise<void> {
+  if (started) return;
+  started = true;
+
+  await listen<AgentHookEvent>("agent-hook", (evt) => {
+    const { agent, session, event, body } = evt.payload;
+    const adapter = getAdapter(agent);
+    if (!adapter) return;
+    let parsed: unknown;
+    try {
+      parsed = body.trim().length > 0 ? JSON.parse(body) : {};
+    } catch {
+      // A malformed payload can't be a reliable state signal; ignore it and let
+      // the next well-formed hook (or the fallback) speak.
+      return;
+    }
+    // When the script conveyed the event out-of-band (X-Tempest-Event), fold it
+    // into the payload so every adapter reads `hook_event_name` uniformly.
+    if (event && parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      const rec = parsed as Record<string, unknown>;
+      if (rec.hook_event_name === undefined) rec.hook_event_name = event;
+    }
+    const state = adapter.parse(parsed);
+    if (state) sessionManager.applyHookState(session, state, adapter.coversWaiting);
+  });
+
+  if (getSettings().preciseAgentStatus) {
+    try {
+      await installAll();
+    } catch (e) {
+      console.error("[agent-hooks] install failed", e);
+    }
+  }
+}
+
+// Toggle handler for the Settings switch: install or fully uninstall the managed
+// hooks. Existing sessions stay hook-authoritative until they end (harmless); new
+// sessions after an uninstall use the PTY heuristic.
+export async function setPreciseAgentStatus(enabled: boolean): Promise<void> {
+  try {
+    await (enabled ? installAll() : uninstallAll());
+  } catch (e) {
+    console.error("[agent-hooks] toggle failed", e);
+  }
+}
diff --git a/src/store/appSettings.ts b/src/store/appSettings.ts
index 3f98823..35087f5 100644
--- a/src/store/appSettings.ts
+++ b/src/store/appSettings.ts
@@ -14,6 +14,10 @@ export interface AppSettings {
   atlasAutoIndex: boolean;
   isolateAgents: boolean;
   autoApprove: boolean;
+  // Install lifecycle hooks into supported agents' configs for precise
+  // working/waiting/done status. Off uninstalls them and falls back to the
+  // PTY-scraping heuristic. See src/lib/agentHooks.
+  preciseAgentStatus: boolean;
 }
 
 export const SETTINGS_DEFAULTS: AppSettings = {
@@ -29,6 +33,7 @@ export const SETTINGS_DEFAULTS: AppSettings = {
   atlasAutoIndex: false,
   isolateAgents: true,
   autoApprove: true,
+  preciseAgentStatus: true,
 };
 
 export const FONT_FAMILY_OPTIONS: { label: string; value: string }[] = [
diff --git a/src/store/sessionManager.ts b/src/store/sessionManager.ts
index 64eef5c..6967eaa 100644
--- a/src/store/sessionManager.ts
+++ b/src/store/sessionManager.ts
@@ -97,6 +97,18 @@ interface SessionRecord {
   // Claude, to catch permission dialogs painted after the OSC 9 that tripped
   // markDone. Cleared on new user input or when attention actually fires.
   permCheckTimers: ReturnType<typeof setTimeout>[];
+  // Set once the first lifecycle hook lands for this session (see applyHookState).
+  // Precise hook events are authoritative from then on: the working/done PTY
+  // heuristics (quiet/ceiling timers, OSC done/working, title busy/idle) stand
+  // down so they can't fight the hooks. Sessions for hookless agents never set
+  // this and keep the full heuristic path.
+  hookAuthoritative: boolean;
+  // True only for agents whose hooks ALSO emit a permission/waiting signal
+  // (Claude). When false, the agent's hooks cover working/done but NOT "needs
+  // you", so the attention heuristics (title ✋, OSC RequestAttention, BEL) stay
+  // live even under hook authority — otherwise those agents (e.g. Gemini) would
+  // lose their only waiting signal.
+  hookCoversWaiting: boolean;
   listeners: Set<(data: string) => void>;
 }
 
@@ -128,6 +140,8 @@ class SessionManager {
       attentionFired: false,
       claudeCleanTail: "",
       permCheckTimers: [],
+      hookAuthoritative: false,
+      hookCoversWaiting: false,
       listeners: new Set(),
     };
     this.sessions.set(sessionId, record);
@@ -171,8 +185,54 @@ class SessionManager {
     // New turn starts — any prior attention flag no longer applies.
     setAttention(sessionId, false);
     setWorkState(sessionId, "working");
-    this.scheduleQuiet(record, sessionId);
-    this.scheduleCeiling(record, sessionId);
+    // Under hooks, the agent's own UserPromptSubmit/Stop events drive the turn;
+    // the byte-quiet and ceiling fallbacks would only race them, so skip them.
+    if (!record.hookAuthoritative) {
+      this.scheduleQuiet(record, sessionId);
+      this.scheduleCeiling(record, sessionId);
+    }
+  }
+
+  // Apply a precise lifecycle-hook state for a session (called by the agent-hook
+  // receiver). The first call flips the session to hook-authoritative, retiring
+  // the PTY heuristics. Mirrors the markDone/markAttention side effects (onDone
+  // fires once per turn on the working→terminal edge) so queued-message delivery
+  // and diff refresh behave identically whether a turn ends via hook or scrape.
+  applyHookState(sessionId: string, state: "working" | "waiting" | "done", coversWaiting: boolean) {
+    const record = this.sessions.get(sessionId);
+    if (!record?.isAgent) return;
+    record.hookAuthoritative = true;
+    record.hookCoversWaiting = coversWaiting;
+    this.clearHeuristicTimers(record);
+    if (state === "working") {
+      record.attentionFired = false;
+      setAttention(sessionId, false);
+      setWorkState(sessionId, "working");
+      return;
+    }
+    if (state === "waiting") {
+      // Once per turn, like markAttention — repeated permission repaints don't
+      // re-fire onDone or re-stamp the bell after the user clears it.
+      if (record.attentionFired) return;
+      record.attentionFired = true;
+      setWorkState(sessionId, "done");
+      setAttention(sessionId, true);
+      record.onDone?.();
+      return;
+    }
+    // done
+    const wasWorking = getWorkState(sessionId) === "working";
+    record.attentionFired = false;
+    setAttention(sessionId, false);
+    setWorkState(sessionId, "done");
+    if (wasWorking) record.onDone?.();
+  }
+
+  private clearHeuristicTimers(record: SessionRecord) {
+    if (record.quietTimer !== null) { clearTimeout(record.quietTimer); record.quietTimer = null; }
+    if (record.ceilTimer !== null) { clearTimeout(record.ceilTimer); record.ceilTimer = null; }
+    for (const t of record.permCheckTimers) clearTimeout(t);
+    record.permCheckTimers = [];
   }
 
   // Called by TerminalPane via term.onTitleChange(). Classifies the title as
@@ -180,7 +240,15 @@ class SessionManager {
   updateTitle(sessionId: string, title: string) {
     const record = this.sessions.get(sessionId);
     if (!record?.isAgent) return;
+    // Hooks that cover waiting own all of it — title heuristics stand down.
+    if (record.hookAuthoritative && record.hookCoversWaiting) return;
     const state = this.classifyTitle(record.agentHint, title);
+    // When hooks own working/done but not waiting, the title's only useful
+    // contribution is the "needs you" signal (e.g. Gemini's ✋); ignore busy/idle.
+    if (record.hookAuthoritative) {
+      if (state === "attention") this.markAttention(record, sessionId);
+      return;
+    }
     if (state === "busy") {
       record.senderBusy = true;
     } else if (state === "idle") {
@@ -274,6 +342,15 @@ class SessionManager {
   }
 
   private detectSignals(record: SessionRecord, sessionId: string, scan: string) {
+    // Hooks that also carry the "needs you" signal (Claude) fully supersede
+    // byte-scraping — nothing here may fight them.
+    if (record.hookAuthoritative && record.hookCoversWaiting) return;
+    // When hooks own working/done but NOT waiting (the agent's hook set has no
+    // permission event), suppress only the working/done detectors and keep the
+    // attention ones (OSC RequestAttention, BEL) — they're the agent's only
+    // "needs you" source under hook authority.
+    const suppressState = record.hookAuthoritative;
+
     // --- OSC sequences (XTerm ctlseqs + vendor extension docs) ---
     OSC_RE.lastIndex = 0;
     let m: RegExpExecArray | null;
@@ -282,6 +359,20 @@ class SessionManager {
       const parts = m[1].split(";");
       const oscNum = parts[0];
 
+      if (oscNum === "1337") {
+        // OSC 1337 — iTerm2 proprietary. RequestAttention=yes/fireworks means the
+        // agent is explicitly blocked and needs the user's input. An attention
+        // signal, so it stays live even under state-suppressing hook authority.
+        // Source: iTerm2 "Proprietary Escape Codes" docs.
+        if (/^RequestAttention=(yes|fireworks)$/i.test(parts.slice(1).join(";"))) {
+          this.markAttention(record, sessionId);
+        }
+        continue;
+      }
+
+      // Everything below is a working/done transition — owned by hooks when authoritative.
+      if (suppressState) continue;
+
       if (oscNum === "9") {
         if (parts[1] === "4") {
           // OSC 9;4;<state> — ConEmu / Windows Terminal progress bar protocol.
@@ -325,19 +416,13 @@ class SessionManager {
         // Same semantics as OSC 9: agent is signalling attention / turn complete.
         // Source: urxvt man page; VTE source.
         this.markDone(record, sessionId);
-      } else if (oscNum === "1337") {
-        // OSC 1337 — iTerm2 proprietary. RequestAttention=yes/fireworks means the
-        // agent is explicitly blocked and needs the user's input.
-        // Source: iTerm2 "Proprietary Escape Codes" docs.
-        if (/^RequestAttention=(yes|fireworks)$/i.test(parts.slice(1).join(";"))) {
-          this.markAttention(record, sessionId);
-        }
       }
     }
 
     // --- DEC private mode set/reset: ESC [ ? <params> h|l ---
+    // Working/done transitions — skipped when hooks own state.
     DEC_MODE_RE.lastIndex = 0;
-    while ((m = DEC_MODE_RE.exec(scan)) !== null) {
+    while (!suppressState && (m = DEC_MODE_RE.exec(scan)) !== null) {
       const params = m[1];
       const action = m[2]; // "h" = set/enable, "l" = reset/disable
 
@@ -398,8 +483,10 @@ class SessionManager {
     }
 
     // Re-arm the byte-quiet fallback timer on any output while still working.
-    // If markDone already fired above, getWorkState returns "done" and this is a no-op.
-    if (getWorkState(sessionId) === "working") {
+    // Skipped under hook authority — the agent's Stop/AfterAgent hook, not a
+    // quiet window, decides done. If markDone already fired above, getWorkState
+    // returns "done" and this is a no-op.
+    if (!suppressState && getWorkState(sessionId) === "working") {
       this.scheduleQuiet(record, sessionId);
     }
   }