feat: support hermes agent integration

refs #144

9 files changed, 566 insertions, 9 deletions

diff --git a/src/api/schema.rs b/src/api/schema.rs
index a82070e0..7cf73cda 100644
--- a/src/api/schema.rs
+++ b/src/api/schema.rs
@@ -397,6 +397,7 @@ pub enum IntegrationTarget {
     Claude,
     Codex,
     Opencode,
+    Hermes,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
diff --git a/src/cli.rs b/src/cli.rs
index e9315c3d..f57cc625 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1627,11 +1627,11 @@ fn parse_integration_target(
     action: &str,
 ) -> std::io::Result<Option<IntegrationTarget>> {
     let Some(target) = args.first().map(|arg| arg.as_str()) else {
-        eprintln!("usage: herdr integration {action} <pi|claude|codex|opencode>");
+        eprintln!("usage: herdr integration {action} <pi|claude|codex|opencode|hermes>");
         return Ok(None);
     };
     if args.len() != 1 {
-        eprintln!("usage: herdr integration {action} <pi|claude|codex|opencode>");
+        eprintln!("usage: herdr integration {action} <pi|claude|codex|opencode|hermes>");
         return Ok(None);
     }
 
@@ -1640,9 +1640,10 @@ fn parse_integration_target(
         "claude" => IntegrationTarget::Claude,
         "codex" => IntegrationTarget::Codex,
         "opencode" => IntegrationTarget::Opencode,
+        "hermes" => IntegrationTarget::Hermes,
         _ => {
             eprintln!("unknown integration target: {target}");
-            eprintln!("currently supported: pi, claude, codex, opencode");
+            eprintln!("currently supported: pi, claude, codex, opencode, hermes");
             return Ok(None);
         }
     };
@@ -2145,6 +2146,7 @@ fn print_integration_help() {
     eprintln!("  herdr integration install claude");
     eprintln!("  herdr integration install codex");
     eprintln!("  herdr integration install opencode");
+    eprintln!("  herdr integration install hermes");
     eprintln!("  herdr integration uninstall pi");
     eprintln!("  herdr integration uninstall claude");
     eprintln!("  herdr integration uninstall codex");
diff --git a/src/config/sound.rs b/src/config/sound.rs
index d4e279c3..09d85c18 100644
--- a/src/config/sound.rs
+++ b/src/config/sound.rs
@@ -37,6 +37,7 @@ pub struct AgentSoundOverrides {
     pub droid: AgentSoundSetting,
     pub amp: AgentSoundSetting,
     pub grok: AgentSoundSetting,
+    pub hermes: AgentSoundSetting,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)]
@@ -124,6 +125,7 @@ impl AgentSoundOverrides {
             Some(Agent::Droid) => self.droid,
             Some(Agent::Amp) => self.amp,
             Some(Agent::Grok) => self.grok,
+            Some(Agent::Hermes) => self.hermes,
             None => AgentSoundSetting::Default,
         }
     }
@@ -156,6 +158,7 @@ impl Default for AgentSoundOverrides {
             droid: AgentSoundSetting::Off,
             amp: AgentSoundSetting::Default,
             grok: AgentSoundSetting::Default,
+            hermes: AgentSoundSetting::Default,
         }
     }
 }
diff --git a/src/detect.rs b/src/detect.rs
index 5d890b90..0319b4ef 100644
--- a/src/detect.rs
+++ b/src/detect.rs
@@ -31,6 +31,7 @@ pub enum Agent {
     Droid,
     Amp,
     Grok,
+    Hermes,
 }
 
 pub fn agent_label(agent: Agent) -> &'static str {
@@ -47,6 +48,7 @@ pub fn agent_label(agent: Agent) -> &'static str {
         Agent::Droid => "droid",
         Agent::Amp => "amp",
         Agent::Grok => "grok",
+        Agent::Hermes => "hermes",
     }
 }
 
@@ -65,6 +67,7 @@ pub fn parse_agent_label(agent: &str) -> Option<Agent> {
         "droid" => Some(Agent::Droid),
         "amp" | "amp-local" => Some(Agent::Amp),
         "grok" | "grok-build" => Some(Agent::Grok),
+        "hermes" | "hermes-agent" => Some(Agent::Hermes),
         _ => None,
     }
 }
@@ -87,6 +90,7 @@ pub fn identify_agent(process_name: &str) -> Option<Agent> {
         "droid" => Some(Agent::Droid),
         "amp" | "amp-local" => Some(Agent::Amp),
         "grok" | "grok-build" => Some(Agent::Grok),
+        "hermes" | "hermes-agent" => Some(Agent::Hermes),
         _ => None,
     }
 }
@@ -129,6 +133,7 @@ pub fn detect_state(agent: Option<Agent>, screen_content: &str) -> AgentState {
         Agent::Droid => detect_droid(screen_content),
         Agent::Amp => detect_amp(screen_content),
         Agent::Grok => detect_grok(screen_content),
+        Agent::Hermes => detect_hermes(screen_content),
     }
 }
 
@@ -461,6 +466,31 @@ fn detect_grok(content: &str) -> AgentState {
     AgentState::Idle
 }
 
+/// Hermes Agent detection.
+///
+/// Hermes shows a bottom status bar while turns are active and modal approval
+/// dialogs for dangerous terminal commands. Prefer the modal controls for
+/// blocked detection, then the live interrupt/status controls for working.
+fn detect_hermes(content: &str) -> AgentState {
+    let lower = content.to_lowercase();
+
+    let has_approval_options = lower.contains("allow once")
+        && lower.contains("allow for this session")
+        && lower.contains("deny");
+    let has_approval_controls = lower.contains("enter to confirm")
+        || lower.contains("↑/↓ to select")
+        || lower.contains("show full command");
+    if (lower.contains("dangerous command") || has_approval_options) && has_approval_controls {
+        return AgentState::Blocked;
+    }
+
+    if lower.contains("msg=interrupt") || lower.contains("ctrl+c cancel") {
+        return AgentState::Working;
+    }
+
+    AgentState::Idle
+}
+
 /// Check for braille spinner characters at the start of a line.
 /// These are the Unicode braille pattern dots used by CLI spinners.
 fn has_braille_spinner(content: &str) -> bool {
@@ -731,6 +761,8 @@ mod tests {
         assert_eq!(identify_agent("ghcs"), Some(Agent::GithubCopilot));
         assert_eq!(identify_agent("grok"), Some(Agent::Grok));
         assert_eq!(identify_agent("grok-build"), Some(Agent::Grok));
+        assert_eq!(identify_agent("hermes"), Some(Agent::Hermes));
+        assert_eq!(identify_agent("hermes-agent"), Some(Agent::Hermes));
     }
 
     #[test]
@@ -744,6 +776,7 @@ mod tests {
         );
         assert_eq!(parse_agent_label("amp-local"), Some(Agent::Amp));
         assert_eq!(parse_agent_label("grok-build"), Some(Agent::Grok));
+        assert_eq!(parse_agent_label("hermes-agent"), Some(Agent::Hermes));
     }
 
     #[test]
@@ -752,6 +785,7 @@ mod tests {
         assert_eq!(agent_label(Agent::GithubCopilot), "copilot");
         assert_eq!(agent_label(Agent::OpenCode), "opencode");
         assert_eq!(agent_label(Agent::Grok), "grok");
+        assert_eq!(agent_label(Agent::Hermes), "hermes");
     }
 
     #[test]
@@ -1405,6 +1439,50 @@ mod tests {
         assert_eq!(detect_state(Some(Agent::Grok), screen), AgentState::Idle);
     }
 
+    // ---- Hermes ----
+
+    #[test]
+    fn hermes_identified_by_process_name() {
+        assert_eq!(identify_agent("hermes"), Some(Agent::Hermes));
+        assert_eq!(identify_agent("hermes-agent"), Some(Agent::Hermes));
+    }
+
+    #[test]
+    fn hermes_working_on_interrupt_footer() {
+        let screen = "  (⌐■_■) computing...\n\n ⚕ gpt-5.5 │ 15.5K/272K │ [█░░░░░░░░░] 6% │ 2m │ ⏱ 3s\n─────────────────────────────────────────────────────────────────────────────────────────\n⚕ ❯ msg=interrupt · /queue · /bg · /steer · Ctrl+C cancel";
+        assert_eq!(
+            detect_state(Some(Agent::Hermes), screen),
+            AgentState::Working
+        );
+    }
+
+    #[test]
+    fn hermes_idle_ignores_stale_initializing_agent_text() {
+        let screen = "● say exactly READY and stop\nInitializing agent...\n\n╭─ ⚕ Hermes ────────────────────────────────────────────────────────────────────────────╮\n    READY\n╰───────────────────────────────────────────────────────────────────────────────────────╯\n ⚕ gpt-5.5 │ 15.5K/272K │ [█░░░░░░░░░] 6% │ 15s │ ⏲ 2s\n─────────────────────────────────────────────────────────────────────────────────────────\n❯";
+        assert_eq!(detect_state(Some(Agent::Hermes), screen), AgentState::Idle);
+    }
+
+    #[test]
+    fn hermes_blocked_on_dangerous_command_prompt() {
+        let screen = "╭────────────────────────────────────────────────────────────╮\n│ ⚠️  Dangerous Command                                      │\n│ mkdir -p /tmp/herdr-hermes-block-test/subdir && touch      │\n│ ❯ 1. Allow once                                            │\n│   2. Allow for this session                                │\n│   3. Add to permanent allowlist                            │\n│   4. Deny                                                  │\n│   5. Show full command                                     │\n╰────────────────────────────────────────────────────────────╯\n  ↑/↓ to select, Enter to confirm\n⚠ ❯";
+        assert_eq!(
+            detect_state(Some(Agent::Hermes), screen),
+            AgentState::Blocked
+        );
+    }
+
+    #[test]
+    fn hermes_idle_at_prompt_after_response() {
+        let screen = "╭─ ⚕ Hermes ────────────────────────────────────────────────────────────────────────────╮\n    READY\n╰───────────────────────────────────────────────────────────────────────────────────────╯\n ⚕ gpt-5.5 │ 15.5K/272K │ [█░░░░░░░░░] 6% │ 15s │ ⏲ 2s\n─────────────────────────────────────────────────────────────────────────────────────────\n❯\n─────────────────────────────────────────────────────────────────────────────────────────";
+        assert_eq!(detect_state(Some(Agent::Hermes), screen), AgentState::Idle);
+    }
+
+    #[test]
+    fn hermes_denied_message_is_idle() {
+        let screen = "╭─ ⚕ Hermes ────────────────────────────────────────────────────────────────────────────╮\n    Command was blocked/denied by the safety layer. I did not retry.\n╰───────────────────────────────────────────────────────────────────────────────────────╯\n ⚕ gpt-5.5 │ 15.4K/272K │ [█░░░░░░░░░] 6% │ 2m │ ⏲ 11s\n─────────────────────────────────────────────────────────────────────────────────────────\n❯";
+        assert_eq!(detect_state(Some(Agent::Hermes), screen), AgentState::Idle);
+    }
+
     // ---- Helpers ----
 
     #[test]
diff --git a/src/integration/assets/hermes/__init__.py b/src/integration/assets/hermes/__init__.py
new file mode 100644
index 00000000..03d15a55
--- /dev/null
+++ b/src/integration/assets/hermes/__init__.py
@@ -0,0 +1,97 @@
+"""Hermes plugin installed by Herdr to report agent lifecycle state."""
+
+# HERDR_INTEGRATION_ID=hermes
+# HERDR_INTEGRATION_VERSION=1
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import socket
+import time
+
+_SOURCE = "herdr:hermes"
+_AGENT = "hermes"
+
+
+def _base_params() -> tuple[str, str] | None:
+    if os.environ.get("HERDR_ENV") != "1":
+        return None
+    pane_id = os.environ.get("HERDR_PANE_ID", "").strip()
+    socket_path = os.environ.get("HERDR_SOCKET_PATH", "").strip()
+    if not pane_id or not socket_path:
+        return None
+    return pane_id, socket_path
+
+
+def _send(method: str, params: dict) -> None:
+    base = _base_params()
+    if base is None:
+        return
+    pane_id, socket_path = base
+    params = {
+        "pane_id": pane_id,
+        "source": _SOURCE,
+        "agent": _AGENT,
+        "seq": time.time_ns(),
+        **params,
+    }
+    request = {
+        "id": f"{_SOURCE}:{int(time.time() * 1000)}:{random.randrange(1_000_000):06d}",
+        "method": method,
+        "params": params,
+    }
+    try:
+        client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        client.settimeout(0.5)
+        client.connect(socket_path)
+        client.sendall((json.dumps(request) + "\n").encode("utf-8"))
+        try:
+            client.recv(4096)
+        except Exception:
+            pass
+        client.close()
+    except Exception:
+        pass
+
+
+def _report(state: str) -> None:
+    _send("pane.report_agent", {"state": state})
+
+
+def _release() -> None:
+    _send("pane.release_agent", {})
+
+
+def _working(**kwargs) -> None:
+    del kwargs
+    _report("working")
+
+
+def _blocked(**kwargs) -> None:
+    del kwargs
+    _report("blocked")
+
+
+def _idle(**kwargs) -> None:
+    del kwargs
+    _report("idle")
+
+
+def _finalize(**kwargs) -> None:
+    del kwargs
+    _release()
+
+
+def register(ctx):
+    ctx.register_hook("on_session_start", _idle)
+    ctx.register_hook("pre_llm_call", _working)
+    ctx.register_hook("pre_api_request", _working)
+    ctx.register_hook("pre_tool_call", _working)
+    ctx.register_hook("post_tool_call", _working)
+    ctx.register_hook("pre_approval_request", _blocked)
+    ctx.register_hook("post_approval_response", _working)
+    ctx.register_hook("post_llm_call", _idle)
+    ctx.register_hook("on_session_end", _idle)
+    ctx.register_hook("on_session_finalize", _finalize)
diff --git a/src/integration/assets/hermes/plugin.yaml b/src/integration/assets/hermes/plugin.yaml
new file mode 100644
index 00000000..282f3b34
--- /dev/null
+++ b/src/integration/assets/hermes/plugin.yaml
@@ -0,0 +1,3 @@
+name: herdr-agent-state
+version: "1.0"
+description: Report Hermes Agent lifecycle state to Herdr panes
diff --git a/src/integration/mod.rs b/src/integration/mod.rs
index 88f673ed..309d81f7 100644
--- a/src/integration/mod.rs
+++ b/src/integration/mod.rs
@@ -25,6 +25,12 @@ const CODEX_HOME_ENV_VAR: &str = "CODEX_HOME";
 const OPENCODE_PLUGIN_INSTALL_NAME: &str = "herdr-agent-state.js";
 const OPENCODE_PLUGIN_ASSET: &str = include_str!("assets/opencode/herdr-agent-state.js");
 const OPENCODE_INTEGRATION_VERSION: u32 = 1;
+const HERMES_PLUGIN_INSTALL_NAME: &str = "herdr-agent-state";
+const HERMES_PLUGIN_MANIFEST_INSTALL_NAME: &str = "plugin.yaml";
+const HERMES_PLUGIN_INIT_INSTALL_NAME: &str = "__init__.py";
+const HERMES_PLUGIN_MANIFEST_ASSET: &str = include_str!("assets/hermes/plugin.yaml");
+const HERMES_PLUGIN_INIT_ASSET: &str = include_str!("assets/hermes/__init__.py");
+const HERMES_INTEGRATION_VERSION: u32 = 1;
 const INTEGRATION_VERSION_MARKER: &str = "HERDR_INTEGRATION_VERSION=";
 
 #[derive(Debug)]
@@ -45,6 +51,12 @@ pub(crate) struct OpenCodeInstallPaths {
     pub plugin_path: PathBuf,
 }
 
+#[derive(Debug)]
+pub(crate) struct HermesInstallPaths {
+    pub plugin_dir: PathBuf,
+    pub config_path: PathBuf,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct IntegrationStatus {
     pub target: crate::api::schema::IntegrationTarget,
@@ -90,6 +102,14 @@ pub(crate) struct OpenCodeUninstallResult {
     pub removed_plugin: bool,
 }
 
+#[derive(Debug)]
+pub(crate) struct HermesUninstallResult {
+    pub plugin_dir: PathBuf,
+    pub config_path: PathBuf,
+    pub removed_plugin_dir: bool,
+    pub updated_config: bool,
+}
+
 pub(crate) fn apply_pane_env(cmd: &mut CommandBuilder, pane_id: PaneId) {
     cmd.env(crate::api::SOCKET_PATH_ENV_VAR, crate::api::socket_path());
     cmd.env(HERDR_PANE_ID_ENV_VAR, format!("p_{}", pane_id.raw()));
@@ -137,6 +157,19 @@ pub(crate) fn install_target(
                 installed.plugin_path.display()
             )]
         }
+        crate::api::schema::IntegrationTarget::Hermes => {
+            let installed = install_hermes()?;
+            vec![
+                format!(
+                    "installed hermes integration plugin to {}",
+                    installed.plugin_dir.display()
+                ),
+                format!(
+                    "enabled hermes plugin in {}",
+                    installed.config_path.display()
+                ),
+            ]
+        }
     };
 
     crate::logging::integration_action("install", integration_target_label(target), "ok");
@@ -233,6 +266,33 @@ pub(crate) fn uninstall_target(
                 )]
             }
         }
+        crate::api::schema::IntegrationTarget::Hermes => {
+            let result = uninstall_hermes()?;
+            let mut messages = Vec::new();
+            if result.removed_plugin_dir {
+                messages.push(format!(
+                    "removed hermes integration plugin at {}",
+                    result.plugin_dir.display()
+                ));
+            } else {
+                messages.push(format!(
+                    "no hermes integration plugin found at {}",
+                    result.plugin_dir.display()
+                ));
+            }
+            if result.updated_config {
+                messages.push(format!(
+                    "disabled hermes plugin in {}",
+                    result.config_path.display()
+                ));
+            } else {
+                messages.push(format!(
+                    "no hermes plugin entry found in {}",
+                    result.config_path.display()
+                ));
+            }
+            messages
+        }
     };
 
     crate::logging::integration_action("uninstall", integration_target_label(target), "ok");
@@ -247,6 +307,7 @@ pub(crate) fn integration_target_label(
         crate::api::schema::IntegrationTarget::Claude => "claude",
         crate::api::schema::IntegrationTarget::Codex => "codex",
         crate::api::schema::IntegrationTarget::Opencode => "opencode",
+        crate::api::schema::IntegrationTarget::Hermes => "hermes",
     }
 }
 
@@ -270,7 +331,7 @@ fn integration_specs() -> [(
     crate::api::schema::IntegrationTarget,
     io::Result<PathBuf>,
     u32,
-); 4] {
+); 5] {
     [
         (
             crate::api::schema::IntegrationTarget::Pi,
@@ -292,6 +353,11 @@ fn integration_specs() -> [(
             opencode_dir().map(|dir| dir.join("plugins").join(OPENCODE_PLUGIN_INSTALL_NAME)),
             OPENCODE_INTEGRATION_VERSION,
         ),
+        (
+            crate::api::schema::IntegrationTarget::Hermes,
+            hermes_plugin_dir().map(|dir| dir.join(HERMES_PLUGIN_INIT_INSTALL_NAME)),
+            HERMES_INTEGRATION_VERSION,
+        ),
     ]
 }
 
@@ -590,6 +656,43 @@ pub(crate) fn install_opencode() -> io::Result<OpenCodeInstallPaths> {
     Ok(OpenCodeInstallPaths { plugin_path })
 }
 
+pub(crate) fn install_hermes() -> io::Result<HermesInstallPaths> {
+    let dir = hermes_dir()?;
+    if !dir.is_dir() {
+        return Err(io::Error::other(format!(
+            "hermes config directory not found at {}. install hermes agent first",
+            dir.display()
+        )));
+    }
+
+    let plugin_dir = hermes_plugin_dir()?;
+    fs::create_dir_all(&plugin_dir)?;
+    fs::write(
+        plugin_dir.join(HERMES_PLUGIN_MANIFEST_INSTALL_NAME),
+        HERMES_PLUGIN_MANIFEST_ASSET,
+    )?;
+    fs::write(
+        plugin_dir.join(HERMES_PLUGIN_INIT_INSTALL_NAME),
+        HERMES_PLUGIN_INIT_ASSET,
+    )?;
+
+    let config_path = dir.join("config.yaml");
+    let existing_config = if config_path.is_file() {
+        fs::read_to_string(&config_path)?
+    } else {
+        String::new()
+    };
+    let new_config = ensure_hermes_plugin_enabled(&existing_config);
+    if new_config != existing_config {
+        fs::write(&config_path, new_config)?;
+    }
+
+    Ok(HermesInstallPaths {
+        plugin_dir,
+        config_path,
+    })
+}
+
 pub(crate) fn uninstall_pi() -> io::Result<PiUninstallResult> {
     let extension_path = pi_extension_dir()?.join(PI_EXTENSION_INSTALL_NAME);
     let removed_extension = remove_file_if_exists(&extension_path)?;
@@ -742,6 +845,30 @@ pub(crate) fn uninstall_opencode() -> io::Result<OpenCodeUninstallResult> {
     })
 }
 
+pub(crate) fn uninstall_hermes() -> io::Result<HermesUninstallResult> {
+    let dir = hermes_dir()?;
+    let plugin_dir = hermes_plugin_dir()?;
+    let config_path = dir.join("config.yaml");
+
+    let removed_plugin_dir = remove_dir_all_if_exists(&plugin_dir)?;
+    let mut updated_config = false;
+    if config_path.is_file() {
+        let existing_config = fs::read_to_string(&config_path)?;
+        let new_config = remove_hermes_plugin_enabled(&existing_config);
+        if new_config != existing_config {
+            fs::write(&config_path, new_config)?;
+            updated_config = true;
+        }
+    }
+
+    Ok(HermesUninstallResult {
+        plugin_dir,
+        config_path,
+        removed_plugin_dir,
+        updated_config,
+    })
+}
+
 fn ensure_hooks_object<'a>(
     settings: &'a mut Value,
     settings_path: &Path,
@@ -891,6 +1018,136 @@ fn remove_file_if_exists(path: &Path) -> io::Result<bool> {
     }
 }
 
+fn remove_dir_all_if_exists(path: &Path) -> io::Result<bool> {
+    match fs::remove_dir_all(path) {
+        Ok(()) => Ok(true),
+        Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(false),
+        Err(err) => Err(err),
+    }
+}
+
+fn ensure_hermes_plugin_enabled(content: &str) -> String {
+    update_hermes_enabled_plugin(content, true)
+}
+
+fn remove_hermes_plugin_enabled(content: &str) -> String {
+    update_hermes_enabled_plugin(content, false)
+}
+
+fn update_hermes_enabled_plugin(content: &str, enabled: bool) -> String {
+    let trailing_newline = content.ends_with('\n');
+    let mut lines: Vec<String> = content.lines().map(str::to_string).collect();
+    let Some(plugins_index) = top_level_yaml_key_index(&lines, "plugins") else {
+        if !enabled {
+            return content.to_string();
+        }
+        let mut result = content.trim_end_matches('\n').to_string();
+        if !result.is_empty() {
+            result.push('\n');
+        }
+        result.push_str("plugins:\n  enabled:\n    - herdr-agent-state\n");
+        return result;
+    };
+
+    let plugins_end =
+        next_top_level_yaml_key_index(&lines, plugins_index + 1).unwrap_or(lines.len());
+    let enabled_index = lines[plugins_index + 1..plugins_end]
+        .iter()
+        .position(|line| yaml_key_at_indent(line, 2) == Some("enabled"))
+        .map(|offset| plugins_index + 1 + offset);
+
+    if let Some(enabled_index) = enabled_index {
+        let line = lines[enabled_index].trim();
+        if line == "enabled: []" || line == "enabled: [] # herdr" {
+            if enabled {
+                lines[enabled_index] = "  enabled:".to_string();
+                lines.insert(enabled_index + 1, "    - herdr-agent-state".to_string());
+            }
+            return join_yaml_lines(lines, trailing_newline);
+        }
+
+        let list_start = enabled_index + 1;
+        let list_end = lines[list_start..plugins_end]
+            .iter()
+            .position(|line| {
+                yaml_indent(line).is_some_and(|indent| indent <= 2) && yaml_key_name(line).is_some()
+            })
+            .map(|offset| list_start + offset)
+            .unwrap_or(plugins_end);
+        let existing_item_index = lines[list_start..list_end]
+            .iter()
+            .position(|line| yaml_list_item_value(line) == Some(HERMES_PLUGIN_INSTALL_NAME))
+            .map(|offset| list_start + offset);
+
+        match (enabled, existing_item_index) {
+            (true, Some(_)) | (false, None) => return content.to_string(),
+            (true, None) => lines.insert(list_start, "    - herdr-agent-state".to_string()),
+            (false, Some(index)) => {
+                lines.remove(index);
+            }
+        }
+        return join_yaml_lines(lines, trailing_newline);
+    }
+
+    if enabled {
+        lines.insert(plugins_index + 1, "  enabled:".to_string());
+        lines.insert(plugins_index + 2, "    - herdr-agent-state".to_string());
+        return join_yaml_lines(lines, trailing_newline);
+    }
+
+    content.to_string()
+}
+
+fn top_level_yaml_key_index(lines: &[String], key: &str) -> Option<usize> {
+    lines
+        .iter()
+        .position(|line| yaml_key_at_indent(line, 0) == Some(key))
+}
+
+fn next_top_level_yaml_key_index(lines: &[String], start: usize) -> Option<usize> {
+    lines[start..]
+        .iter()
+        .position(|line| yaml_indent(line) == Some(0) && yaml_key_name(line).is_some())
+        .map(|offset| start + offset)
+}
+
+fn yaml_key_at_indent(line: &str, indent: usize) -> Option<&str> {
+    if yaml_indent(line)? != indent {
+        return None;
+    }
+    yaml_key_name(line)
+}
+
+fn yaml_key_name(line: &str) -> Option<&str> {
+    let trimmed = line.trim_start();
+    if trimmed.is_empty() || trimmed.starts_with('#') || trimmed.starts_with('-') {
+        return None;
+    }
+    let (key, _) = trimmed.split_once(':')?;
+    let key = key.trim();
+    (!key.is_empty()).then_some(key)
+}
+
+fn yaml_indent(line: &str) -> Option<usize> {
+    let trimmed = line.trim_start();
+    if trimmed.is_empty() || trimmed.starts_with('#') {
+        return None;
+    }
+    Some(line.len() - trimmed.len())
+}
+
+fn yaml_list_item_value(line: &str) -> Option<&str> {
+    line.trim().strip_prefix("- ").map(str::trim)
+}
+
+fn join_yaml_lines(lines: Vec<String>, trailing_newline: bool) -> String {
+    let mut result = lines.join("\n");
+    if trailing_newline || result.is_empty() {
+        result.push('\n');
+    }
+    result
+}
+
 fn build_codex_config_with_hooks(content: &str) -> String {
     let mut lines: Vec<String> = content.lines().map(str::to_string).collect();
     let trailing_newline = content.ends_with('\n');
@@ -1053,6 +1310,16 @@ fn opencode_dir() -> io::Result<PathBuf> {
     Ok(home_dir()?.join(".config/opencode"))
 }
 
+fn hermes_dir() -> io::Result<PathBuf> {
+    Ok(home_dir()?.join(".hermes"))
+}
+
+fn hermes_plugin_dir() -> io::Result<PathBuf> {
+    Ok(hermes_dir()?
+        .join("plugins")
+        .join(HERMES_PLUGIN_INSTALL_NAME))
+}
+
 fn home_dir() -> io::Result<PathBuf> {
     std::env::var("HOME")
         .map(PathBuf::from)
@@ -1695,4 +1962,110 @@ mod tests {
         std::env::remove_var("HOME");
         let _ = fs::remove_dir_all(base);
     }
+
+    #[test]
+    fn install_hermes_writes_plugin_and_enables_it() {
+        let _lock = integration_env_lock();
+        let base = unique_base();
+        let home = base.join("home");
+        let hermes_dir = home.join(".hermes");
+        fs::create_dir_all(&hermes_dir).unwrap();
+        fs::write(hermes_dir.join("config.yaml"), "model:\n  provider: auto\n").unwrap();
+        std::env::set_var("HOME", &home);
+
+        let installed = install_hermes().unwrap();
+        let manifest = fs::read_to_string(
+            installed
+                .plugin_dir
+                .join(HERMES_PLUGIN_MANIFEST_INSTALL_NAME),
+        )
+        .unwrap();
+        let init =
+            fs::read_to_string(installed.plugin_dir.join(HERMES_PLUGIN_INIT_INSTALL_NAME)).unwrap();
+        let config = fs::read_to_string(&installed.config_path).unwrap();
+
+        assert_eq!(
+            installed.plugin_dir,
+            hermes_dir.join("plugins").join(HERMES_PLUGIN_INSTALL_NAME)
+        );
+        assert_eq!(manifest, HERMES_PLUGIN_MANIFEST_ASSET);
+        assert_eq!(init, HERMES_PLUGIN_INIT_ASSET);
+        assert!(config.contains("plugins:\n  enabled:\n    - herdr-agent-state"));
+
+        std::env::remove_var("HOME");
+        let _ = fs::remove_dir_all(base);
+    }
+
+    #[test]
+    fn install_hermes_is_idempotent_for_enabled_entry() {
+        let _lock = integration_env_lock();
+        let base = unique_base();
+        let home = base.join("home");
+        let hermes_dir = home.join(".hermes");
+        fs::create_dir_all(&hermes_dir).unwrap();
+        fs::write(
+            hermes_dir.join("config.yaml"),
+            "plugins:\n  enabled:\n    - herdr-agent-state\n",
+        )
+        .unwrap();
+        std::env::set_var("HOME", &home);
+
+        install_hermes().unwrap();
+        install_hermes().unwrap();
+
+        let config = fs::read_to_string(hermes_dir.join("config.yaml")).unwrap();
+        assert_eq!(config.matches("herdr-agent-state").count(), 1);
+
+        std::env::remove_var("HOME");
+        let _ = fs::remove_dir_all(base);
+    }
+
+    #[test]
+    fn uninstall_hermes_removes_plugin_and_enabled_entry() {
+        let _lock = integration_env_lock();
+        let base = unique_base();
+        let home = base.join("home");
+        let hermes_dir = home.join(".hermes");
+        let plugin_dir = hermes_dir.join("plugins").join(HERMES_PLUGIN_INSTALL_NAME);
+        fs::create_dir_all(&plugin_dir).unwrap();
+        fs::write(
+            plugin_dir.join(HERMES_PLUGIN_INIT_INSTALL_NAME),
+            HERMES_PLUGIN_INIT_ASSET,
+        )
+        .unwrap();
+        fs::write(
+            hermes_dir.join("config.yaml"),
+            "plugins:\n  enabled:\n    - other-plugin\n    - herdr-agent-state\n",
+        )
+        .unwrap();
+        std::env::set_var("HOME", &home);
+
+        let result = uninstall_hermes().unwrap();
+        let config = fs::read_to_string(hermes_dir.join("config.yaml")).unwrap();
+
+        assert!(result.removed_plugin_dir);
+        assert!(result.updated_config);
+        assert!(!plugin_dir.exists());
+        assert!(config.contains("    - other-plugin"));
+        assert!(!config.contains("herdr-agent-state"));
+
+        std::env::remove_var("HOME");
+        let _ = fs::remove_dir_all(base);
+    }
+
+    #[test]
+    fn install_hermes_errors_when_config_dir_missing() {
+        let _lock = integration_env_lock();
+        let base = unique_base();
+        let home = base.join("home");
+        fs::create_dir_all(&home).unwrap();
+        std::env::set_var("HOME", &home);
+
+        let err = install_hermes().unwrap_err().to_string();
+
+        assert!(err.contains("hermes config directory not found"));
+
+        std::env::remove_var("HOME");
+        let _ = fs::remove_dir_all(base);
+    }
 }
diff --git a/src/server/protocol.rs b/src/server/protocol.rs
index 6745b0db..abc3abec 100644
--- a/src/server/protocol.rs
+++ b/src/server/protocol.rs
@@ -13,7 +13,7 @@ use serde::{Deserialize, Serialize};
 // ---------------------------------------------------------------------------
 
 /// Current protocol version. Bumped when wire format changes incompatibly.
-pub const PROTOCOL_VERSION: u32 = 6;
+pub const PROTOCOL_VERSION: u32 = 7;
 
 /// Maximum allowed frame payload size (2 MB). Frames larger than this are
 /// rejected to prevent denial-of-service via oversized length prefixes.
diff --git a/src/terminal/state.rs b/src/terminal/state.rs
index 8c27f1a5..5b2d956d 100644
--- a/src/terminal/state.rs
+++ b/src/terminal/state.rs
@@ -428,14 +428,14 @@ mod tests {
         terminal.set_detected_state(Some(Agent::Pi), AgentState::Idle);
         terminal.set_hook_authority(
             "herdr:custom".into(),
-            "hermes".into(),
+            "custom-agent".into(),
             AgentState::Working,
             None,
             None,
         );
 
         assert_eq!(terminal.detected_agent, Some(Agent::Pi));
-        assert_eq!(terminal.effective_agent_label(), Some("hermes"));
+        assert_eq!(terminal.effective_agent_label(), Some("custom-agent"));
         assert_eq!(terminal.effective_known_agent(), None);
         assert_eq!(terminal.state, AgentState::Working);
     }
@@ -504,7 +504,7 @@ mod tests {
         terminal.set_detected_state(Some(Agent::Pi), AgentState::Idle);
         terminal.set_hook_authority(
             "herdr:custom".into(),
-            "hermes".into(),
+            "custom-agent".into(),
             AgentState::Working,
             None,
             None,
@@ -514,7 +514,7 @@ mod tests {
 
         assert!(terminal.hook_authority.is_some());
         assert_eq!(terminal.detected_agent, None);
-        assert_eq!(terminal.effective_agent_label(), Some("hermes"));
+        assert_eq!(terminal.effective_agent_label(), Some("custom-agent"));
         assert_eq!(terminal.state, AgentState::Working);
     }