Interface AgentHook

atomic-agent/src/hooks/mod.rs:132–262

Trait for agent hook adapters. Each AI coding agent (Claude Code, Gemini CLI, Codex, OpenCode) implements this trait to: 1. **Parse** agent-specific JSON from stdin into a common [`TurnEvent`] 2. **Install** hooks into the agent's configuration file 3. **Uninstall** hooks from the agent's configuration file 4. **Detect** whether hooks are currently installed Implementations must be `Send + Sync

/// can return `Ok(0)` / `Ok(())` for agents that don't support hook
/// installation (e.g., agents detected via file watching instead).
pub trait AgentHook: Send + Sync + fmt::Debug {
    /// Returns the registry key for this agent.
    ///
    /// This is the string used in CLI commands:
    /// `atomic agent enable --agent <name>`
    /// `atomic agent hooks <name> <verb>`
    ///
    /// Convention: lowercase with hyphens (e.g., "claude-code", "gemini-cli").
    fn name(&self) -> &str;

    /// Returns a human-readable display name.
    ///
    /// Used in UI output and log messages (e.g., "Claude Code", "Gemini CLI").
    fn display_name(&self) -> &str;

    /// Parse hook input from an agent callback into a normalized [`TurnEvent`].
    ///
    /// The `input` parameter is the raw bytes read from stdin when the agent
    /// invokes the hook. Each agent sends a different JSON format.
    ///
    /// # Arguments
    ///
    /// * `hook_type` - The type of lifecycle event (from the CLI verb)
    /// * `input` - Raw bytes from stdin (typically JSON)
    ///
    /// # Errors
    ///
    /// Returns [`AgentError::HookParseFailed`] if the input cannot be parsed,
    /// or [`AgentError::HookInputEmpty`] if `input` is empty.
    fn parse_event(&self, hook_type: HookType, input: &[u8]) -> AgentResult<TurnEvent>;

    /// Install hooks into the agent's configuration file.
    ///
    /// This writes entries into the agent's settings file (e.g.,
    /// `.claude/settings.json`) that call back to `atomic agent hooks`.
    ///
    /// # Arguments
    ///
    /// * `repo_root` - The repository root directory (where `.atomic/` lives)
    ///
    /// # Returns
    ///
    /// The number of hooks that were installed. Returns 0 if all hooks
    /// were already present.
    ///
    /// # Errors
    ///
    /// Returns [`AgentError::ConfigError`] if the config file cannot be
    /// read or written.
    fn install(&self, repo_root: &Path) -> AgentResult<usize>;

    /// Remove hooks from the agent's configuration file.
    ///
    /// Removes only hooks with the `atomic agent hooks` prefix — other
    /// hooks in the agent's config are preserved.
    ///
    /// # Arguments
    ///