feat: add agent lifecycle hooks (Claude Code-compatible config)

Hooks fire at key agent lifecycle events and execute user-configured
actions via MCP tools. Supports blocking (prompt submit, tool use)
and context injection (PostCompact).

- 8 of 16 events wired: SessionStart, UserPromptSubmit, PreToolUse,
  PostToolUse, PostToolUseFailure, PreCompact, PostCompact, Stop
- Two action types: command (via developer__shell) and mcp_tool
- Config reads .goose/settings.json, .claude/settings.json, or
  ~/.config/goose/hooks.json with forward-compatible parsing
- Fail-open: hook errors never crash the agent

Author: tlongwell-block

crates/goose/src/agents/agent.rs

@@ -86,13 +86,29 @@ impl Agent {
             .conversation
             .ok_or_else(|| anyhow!("Session has no conversation"))?;
 
+        // Load hooks and fire PreCompact
+        let hooks = crate::hooks::Hooks::load(&session.working_dir).ok();
+        if let Some(ref hooks) = hooks {
+            let invocation = crate::hooks::HookInvocation::pre_compact(
+                session_id.to_string(),
+                conversation.messages().len(),
+                true, // manual = true for /compact command
+                session.working_dir.to_string_lossy().to_string(),
+            );
+            let _ = hooks
+                .run(invocation, &self.extension_manager, &session.working_dir)
+                .await;
+        }
+
+        let pre_compact_len = conversation.messages().len();
         let (compacted_conversation, usage) = compact_messages(
             self.provider().await?.as_ref(),
             session_id,
             &conversation,
             true, // is_manual_compact
         )
         .await?;
+        let post_compact_len = compacted_conversation.messages().len();
 
         manager
             .replace_conversation(session_id, &compacted_conversation)
@@ -101,6 +117,28 @@ impl Agent {
         self.update_session_metrics(session_id, session.schedule_id, &usage, true)
             .await?;
 
+        // Fire PostCompact hook and inject context if any
+        if let Some(ref hooks) = hooks {
+            let invocation = crate::hooks::HookInvocation::post_compact(
+                session_id.to_string(),
+                pre_compact_len,
+                post_compact_len,
+                true, // manual = true for /compact command
+                session.working_dir.to_string_lossy().to_string(),
+            );
+            if let Ok(outcome) = hooks
+                .run(invocation, &self.extension_manager, &session.working_dir)
+                .await
+            {
+                if let Some(context) = outcome.context {
+                    let context_msg = Message::assistant()
+                        .with_text(context)
+                        .with_visibility(false, true); // agent-only
+                    manager.add_message(session_id, &context_msg).await?;
+                }
+            }
+        }
+
         Ok(Some(Message::assistant().with_system_notification(
             SystemNotificationType::InlineMessage,
             "Compaction complete",

crates/goose/src/agents/execute_commands.rs

@@ -49,6 +49,7 @@ pub const CHAT_MODE_TOOL_SKIPPED_RESPONSE: &str = "Let the user know the tool ca
                                         If needed, adjust the explanation based on user preferences or questions.";
 
 impl Agent {
+    #[allow(clippy::too_many_arguments)]
     pub(crate) fn handle_approval_tool_requests<'a>(
         &'a self,
         tool_requests: &'a [ToolRequest],
@@ -57,6 +58,7 @@ impl Agent {
         cancellation_token: Option<CancellationToken>,
         session: &'a Session,
         inspection_results: &'a [crate::tool_inspection::InspectionResult],
+        hooks: &'a Option<crate::hooks::Hooks>,
     ) -> BoxStream<'a, anyhow::Result<Message>> {
         try_stream! {
         for request in tool_requests.iter() {
@@ -97,6 +99,38 @@ impl Agent {
                         }
 
                         if confirmation.permission == Permission::AllowOnce || confirmation.permission == Permission::AlwaysAllow {
+                            // Fire PreToolUse hook — if blocked, treat as declined
+                            if let Some(ref hooks) = hooks {
+                                let invocation = crate::hooks::HookInvocation::pre_tool_use(
+                                    session.id.clone(),
+                                    tool_call.name.to_string(),
+                                    serde_json::to_value(&tool_call.arguments)
+                                        .unwrap_or(serde_json::Value::Null),
+                                    session.working_dir.to_string_lossy().to_string(),
+                                );
+                                let outcome = hooks
+                                    .run(invocation, &self.extension_manager, &session.working_dir)
+                                    .await
+                                    .unwrap_or_default();
+                                if outcome.blocked {
+                                    // Hook blocked — treat same as user declining
+                                    if let Some(response_msg) = request_to_response_map.get(&request.id) {
+                                        let mut response = response_msg.lock().await;
+                                        *response = response.clone().with_tool_response_with_metadata(
+                                            request.id.clone(),
+                                            Ok(rmcp::model::CallToolResult {
+                                                content: vec![Content::text("Tool execution blocked by hook")],
+                                                structured_content: None,
+                                                is_error: Some(true),
+                                                meta: None,
+                                            }),
+                                            request.metadata.as_ref(),
+                                        );
+                                    }
+                                    break;
+                                }
+                            }
+
                             let (req_id, tool_result) = self.dispatch_tool_call(tool_call.clone(), request.id.clone(), cancellation_token.clone(), session).await;
                             let mut futures = tool_futures.lock().await;
 

crates/goose/src/agents/tool_execution.rs

@@ -0,0 +1,173 @@
+use anyhow::{Context, Result};
+use serde::Deserialize;
+use std::collections::HashMap;
+use std::path::Path;
+use std::str::FromStr;
+
+use super::types::HookEventKind;
+
+#[derive(Debug, Clone, Default)]
+pub struct HookSettingsFile {
+    pub hooks: HashMap<HookEventKind, Vec<HookEventConfig>>,
+    pub allow_project_hooks: bool,
+}
+
+impl<'de> serde::Deserialize<'de> for HookSettingsFile {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        #[derive(Deserialize)]
+        struct Raw {
+            #[serde(default)]
+            hooks: HashMap<String, Vec<HookEventConfig>>,
+            #[serde(default)]
+            allow_project_hooks: bool,
+        }
+
+        let raw = Raw::deserialize(deserializer)?;
+        let mut hooks = HashMap::new();
+
+        for (key, configs) in raw.hooks {
+            match HookEventKind::from_str(&key) {
+                Ok(event) => {
+                    hooks.insert(event, configs);
+                }
+                Err(_) => {
+                    tracing::warn!("Unknown hook event '{}', ignoring", key);
+                }
+            }
+        }
+
+        Ok(Self {
+            hooks,
+            allow_project_hooks: raw.allow_project_hooks,
+        })
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct HookEventConfig {
+    #[serde(default)]
+    pub matcher: Option<String>,
+
+    pub hooks: Vec<HookAction>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(tag = "type", rename_all = "lowercase")]
+pub enum HookAction {
+    Command {
+        command: String,
+
+        #[serde(default = "default_timeout")]
+        timeout: u64,
+    },
+    #[serde(rename = "mcp_tool")]
+    McpTool {
+        tool: String,
+        #[serde(default)]
+        arguments: serde_json::Map<String, serde_json::Value>,
+        #[serde(default = "default_timeout")]
+        timeout: u64,
+    },
+}
+
+fn default_timeout() -> u64 {
+    600
+}
+
+impl HookSettingsFile {
+    pub fn load_merged(working_dir: &Path) -> Result<Self> {
+        let global_path = crate::config::paths::Paths::in_config_dir("hooks.json");
+        let goose_project_path = working_dir.join(".goose").join("settings.json");
+        let claude_project_path = working_dir.join(".claude").join("settings.json");
+
+        let global = Self::load_from_file(&global_path).unwrap_or_else(|e| {
+            tracing::debug!("No global hooks config at {:?}: {}", global_path, e);
+            Self::default()
+        });
+
+        // Use the allow_project_hooks setting from the global config
+        let allow_project_hooks = global.allow_project_hooks;
+
+        // If project hooks are not allowed, check if they exist and log a warning
+        if !allow_project_hooks {
+            let project_path = if goose_project_path.exists() {
+                Some(&goose_project_path)
+            } else if claude_project_path.exists() {
+                Some(&claude_project_path)
+            } else {
+                None
+            };
+
+            if let Some(path) = project_path {
+                tracing::info!(
+                    "Project hooks found at {:?} but project hooks are not enabled. Set allow_project_hooks: true in ~/.config/goose/hooks.json to enable.",
+                    path
+                );
+            }
+
+            return Ok(global);
+        }
+
+        let project = if goose_project_path.exists() {
+            if claude_project_path.exists() {
+                tracing::warn!("Found hooks config in both .goose/ and .claude/; using .goose/");
+            }
+            Self::load_from_file(&goose_project_path).unwrap_or_else(|e| {
+                tracing::warn!(
+                    "Failed to parse hooks config {:?}: {}",
+                    goose_project_path,
+                    e
+                );
+                Self::default()
+            })
+        } else {
+            Self::load_from_file(&claude_project_path).unwrap_or_else(|e| {
+                if claude_project_path.exists() {
+                    tracing::warn!(
+                        "Failed to parse hooks config {:?}: {}",
+                        claude_project_path,
+                        e
+                    );
+                }
+                Self::default()
+            })
+        };
+
+        Ok(Self::merge(global, project))
+    }
+
+    fn load_from_file(path: &Path) -> Result<Self> {
+        if !path.exists() {
+            anyhow::bail!("Config file does not exist: {:?}", path);
+        }
+
+        let content = std::fs::read_to_string(path)
+            .with_context(|| format!("Failed to read hooks config from {:?}", path))?;
+
+        let config: Self = serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse hooks config from {:?}", path))?;
+
+        Ok(config)
+    }
+
+    fn merge(global: Self, project: Self) -> Self {
+        let mut merged_hooks: HashMap<HookEventKind, Vec<HookEventConfig>> = global.hooks;
+
+        for (event, project_configs) in project.hooks {
+            merged_hooks
+                .entry(event)
+                .or_default()
+                .extend(project_configs);
+        }
+
+        Self {
+            hooks: merged_hooks,
+            allow_project_hooks: global.allow_project_hooks,
+        }
+    }
+
+    pub fn get_hooks_for_event(&self, event: HookEventKind) -> &[HookEventConfig] {
+        self.hooks.get(&event).map(|v| v.as_slice()).unwrap_or(&[])
+    }
+}