Merge branch 'dev/hook0610' into dev/websearch0610

# Conflicts:
#	crates/cli/src/prompt_command.rs
#	crates/core/src/tools/router.rs
#	crates/server/src/runtime/turn_exec.rs

Author: wangtsiao

Cargo.lock

@@ -82,6 +82,17 @@ pub(crate) async fn run_prompt(
             collaboration_mode: devo_protocol::CollaborationMode::Build,
             agent_coordinator: None,
             local_web_search: None,
+            hooks: (!app_config.hooks.is_empty()).then(|| devo_core::HookRuntimeContext {
+                runner: devo_core::HookRunner::new(app_config.hooks.clone()),
+                base: devo_core::HookBaseInput {
+                    session_id: session_state.id.clone(),
+                    transcript_path: String::new(),
+                    cwd: cwd.clone(),
+                    permission_mode: Some("auto-approve".to_string()),
+                    agent_id: None,
+                    agent_type: None,
+                },
+            }),
             network_proxy: None,
         },
     );

crates/cli/src/prompt_command.rs

@@ -14,6 +14,7 @@ consumer crates.
 - `server.rs` defines server transport and connection defaults.
 - `logging.rs` defines logging and rolling file-log settings.
 - `skills.rs` defines skill discovery settings.
+- `hooks.rs` defines external hook event and command configuration.
 - `experimental.rs` defines opt-in experimental feature gates.
 - `error.rs` defines app and provider config error types.
 - `provider.rs` re-exports provider config APIs and contains provider-focused
@@ -88,6 +89,7 @@ without clearing every omitted provider field from user config.
 - `updates.enabled = true`
 - `updates.check_on_startup = true`
 - `updates.check_interval_hours = 24`
+- `hooks = {}`
 - `project_root_markers = [".git"]`
 - `projects = {}`
 
@@ -154,6 +156,14 @@ check_interval_hours = 24
 
 [projects."/path/to/project"]
 permission_preset = "default" # read-only, default, auto-review, or full-access
+
+[[hooks.PreToolUse]]
+matcher = "exec_command"
+
+[[hooks.PreToolUse.hooks]]
+type = "command"
+command = "hooks/pre-tool-use.sh"
+timeout = 30
 ```
 
 `logging.file.directory` is optional. Relative logging directories resolve under
@@ -176,6 +186,105 @@ permission_preset = "default" # read-only, default, auto-review, or full-access
 Provider-specific validation happens while resolving or mutating provider
 config.
 
+## Hooks
+
+External hooks are configured under the top-level `[hooks]` table. Each hook
+event contains matcher entries, and each matcher entry contains one or more hook
+commands:
+
+```toml
+[[hooks.PostToolUse]]
+matcher = "exec_command|read_file"
+
+[[hooks.PostToolUse.hooks]]
+type = "command"
+command = "hooks/post-tool-use.sh"
+shell = "bash"
+timeout = 30
+
+[[hooks.UserPromptSubmit]]
+
+[[hooks.UserPromptSubmit.hooks]]
+type = "command"
+command = "hooks/check-prompt.sh"
+async = false
+```
+
+Command hooks receive one JSON object on stdin. The common fields are
+`hook_event_name`, `session_id`, `transcript_path`, and `cwd`. Runtime contexts
+may also include `permission_mode`, `agent_id`, and `agent_type`, followed by
+event-specific fields such as `tool_name`, `tool_input`, `tool_use_id`,
+`tool_response`, `prompt`, `source`, `trigger`, `reason`, `file_path`, `event`,
+`old_cwd`, and `new_cwd`.
+
+Hook command results follow Claude Code-style blocking semantics:
+
+- Exit status `0` succeeds unless stdout contains a blocking JSON decision.
+- Exit status `2` blocks the triggering action. The block reason is read from
+  stdout JSON or stderr.
+- Stdout JSON shaped as `{"decision":"block","reason":"..."}` blocks even when
+  the process exits successfully.
+- Claude-style `hookSpecificOutput` denial JSON blocks for `PreToolUse` and
+  `PermissionRequest`.
+- Stdout JSON shaped as `{"continue":false,"stopReason":"..."}` is treated as a
+  blocking stop for lifecycle events that consume blocking decisions.
+- Other non-zero exits are logged as non-blocking hook failures.
+
+The `command` hook type is executed by the runtime. `prompt`, `agent`, and
+`http` hook definitions are parsed so config files remain forward compatible,
+but they are currently logged as unsupported and not executed. `shell` accepts
+`bash` and `powershell`. `timeout` is in seconds and defaults to `600`.
+`async = true` and `asyncRewake = true` spawn the command in the background and
+do not wait for a blocking decision. `if`, `status_message`, and `once` are
+preserved in config but are not interpreted by the current runtime.
+
+All 27 hook event names are accepted by config:
+
+- `PreToolUse`, `PostToolUse`, `PostToolUseFailure`
+- `Notification`, `UserPromptSubmit`
+- `SessionStart`, `SessionEnd`, `Stop`, `StopFailure`
+- `SubagentStart`, `SubagentStop`
+- `PreCompact`, `PostCompact`
+- `PermissionRequest`, `PermissionDenied`
+- `Setup`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`
+- `Elicitation`, `ElicitationResult`
+- `ConfigChange`, `WorktreeCreate`, `WorktreeRemove`
+- `InstructionsLoaded`, `CwdChanged`, `FileChanged`
+
+The current runtime triggers hooks where Devo has a matching lifecycle point:
+tool execution, prompt submission, server setup, session start and resume,
+session shutdown, turn stop and failure, subagent start and stop, manual
+compaction, permission request and denial, config writes through `provider/upsert`
+and `skills/set_enabled`, per-turn cwd changes, and file changes reported by
+`write`/`apply_patch` tool metadata.
+
+Runtime-triggered events:
+
+- `PreToolUse`, `PostToolUse`, `PostToolUseFailure`
+- `UserPromptSubmit`
+- `SessionStart`, `SessionEnd`
+- `Stop`, `StopFailure`
+- `SubagentStart`, `SubagentStop`
+- `PreCompact`, `PostCompact`
+- `PermissionRequest`, `PermissionDenied`
+- `Setup`
+- `ConfigChange`
+- `CwdChanged`, `FileChanged`
+
+Config-ready but not currently triggered:
+
+- `Notification`: Devo has protocol notifications, but no single user-facing
+  notification lifecycle equivalent to Claude's external notification hook.
+- `TeammateIdle`, `TaskCreated`, `TaskCompleted`: the standalone `devo-tasks`
+  crate is not wired into the server runtime task lifecycle.
+- `Elicitation`, `ElicitationResult`: MCP elicitation is currently handled
+  inside the MCP manager with an automatic response and no server-session hook
+  bridge.
+- `WorktreeCreate`, `WorktreeRemove`: Devo currently has no worktree lifecycle
+  API.
+- `InstructionsLoaded`: Devo discovers AGENTS-style instructions during context
+  assembly, but does not expose a hookable per-file instruction-load event.
+
 ## Provider Config
 
 Provider config is part of `config.toml` and is modeled by `ProviderConfigSection`.

crates/config/README.md

@@ -16,6 +16,7 @@ use devo_util_paths::FileSystemConfigPathResolver;
 use crate::AUTH_CONFIG_FILE_NAME;
 use crate::AppConfigError;
 use crate::ExperimentalConfig;
+use crate::HooksConfig;
 use crate::LogRotation;
 use crate::LoggingConfig;
 use crate::LoggingFileConfig;
@@ -65,6 +66,9 @@ pub struct AppConfig {
     /// Tool-specific runtime configuration.
     #[serde(default, skip_serializing_if = "ToolsConfig::is_empty")]
     pub tools: ToolsConfig,
+    /// External lifecycle hooks keyed by event name.
+    #[serde(default, skip_serializing_if = "HooksConfig::is_empty")]
+    pub hooks: HooksConfig,
     /// Provider, model, and active model defaults.
     #[serde(flatten)]
     pub provider: ProviderConfigSection,
@@ -154,6 +158,7 @@ impl Default for AppConfig {
             mcp_oauth_credentials_store: Some(OAuthCredentialsStoreMode::default()),
             mcp: McpConfig::default(),
             tools: ToolsConfig::default(),
+            hooks: HooksConfig::default(),
             provider: ProviderConfigSection::default(),
             provider_http: ProviderHttpConfig::default(),
             updates: UpdatesConfig {

crates/config/src/app.rs

@@ -0,0 +1,177 @@
+use std::collections::BTreeMap;
+
+use serde::Deserialize;
+use serde::Serialize;
+
+/// External hook events understood by Devo configuration.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+pub enum HookEvent {
+    PreToolUse,
+    PostToolUse,
+    PostToolUseFailure,
+    Notification,
+    UserPromptSubmit,
+    SessionStart,
+    SessionEnd,
+    Stop,
+    StopFailure,
+    SubagentStart,
+    SubagentStop,
+    PreCompact,
+    PostCompact,
+    PermissionRequest,
+    PermissionDenied,
+    Setup,
+    TeammateIdle,
+    TaskCreated,
+    TaskCompleted,
+    Elicitation,
+    ElicitationResult,
+    ConfigChange,
+    WorktreeCreate,
+    WorktreeRemove,
+    InstructionsLoaded,
+    CwdChanged,
+    FileChanged,
+}
+
+/// Top-level hook configuration keyed by event name.
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct HooksConfig(pub BTreeMap<HookEvent, Vec<HookMatcherConfig>>);
+
+impl HooksConfig {
+    pub fn is_empty(&self) -> bool {
+        self.0.values().all(Vec::is_empty)
+    }
+
+    pub fn matchers_for(&self, event: HookEvent) -> &[HookMatcherConfig] {
+        self.0.get(&event).map_or(&[], Vec::as_slice)
+    }
+}
+
+/// A matcher groups one or more hooks for an event-specific match query.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct HookMatcherConfig {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub matcher: Option<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub hooks: Vec<HookCommandConfig>,
+}
+
+/// Persistable hook command definitions.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum HookCommandConfig {
+    Command(CommandHookConfig),
+    Prompt(PromptHookConfig),
+    Agent(AgentHookConfig),
+    Http(HttpHookConfig),
+}
+
+/// Shell command hook definition.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CommandHookConfig {
+    pub command: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub shell: Option<HookShell>,
+    #[serde(rename = "if", default, skip_serializing_if = "Option::is_none")]
+    pub condition: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeout: Option<u64>,
+    #[serde(
+        rename = "statusMessage",
+        alias = "status_message",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub status_message: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub once: Option<bool>,
+    #[serde(rename = "async", default, skip_serializing_if = "Option::is_none")]
+    pub async_hook: Option<bool>,
+    #[serde(
+        rename = "asyncRewake",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub async_rewake: Option<bool>,
+}
+
+/// Shell used to run a command hook.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum HookShell {
+    #[serde(rename = "bash")]
+    Bash,
+    #[serde(rename = "powershell", alias = "power_shell")]
+    PowerShell,
+}
+
+/// Parsed but currently unsupported LLM prompt hook definition.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PromptHookConfig {
+    pub prompt: String,
+    #[serde(rename = "if", default, skip_serializing_if = "Option::is_none")]
+    pub condition: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeout: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    #[serde(
+        rename = "statusMessage",
+        alias = "status_message",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub status_message: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub once: Option<bool>,
+}
+
+/// Parsed but currently unsupported agent hook definition.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AgentHookConfig {
+    pub prompt: String,
+    #[serde(rename = "if", default, skip_serializing_if = "Option::is_none")]
+    pub condition: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeout: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    #[serde(
+        rename = "statusMessage",
+        alias = "status_message",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub status_message: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub once: Option<bool>,
+}
+
+/// Parsed but currently unsupported HTTP hook definition.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct HttpHookConfig {
+    pub url: String,
+    #[serde(rename = "if", default, skip_serializing_if = "Option::is_none")]
+    pub condition: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeout: Option<u64>,
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub headers: BTreeMap<String, String>,
+    #[serde(
+        rename = "allowedEnvVars",
+        default,
+        skip_serializing_if = "Vec::is_empty"
+    )]
+    pub allowed_env_vars: Vec<String>,
+    #[serde(
+        rename = "statusMessage",
+        alias = "status_message",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub status_message: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub once: Option<bool>,
+}

crates/config/src/hooks.rs

@@ -1,6 +1,7 @@
 mod app;
 mod error;
 mod experimental;
+mod hooks;
 mod logging;
 mod mcp;
 mod oauth;
@@ -12,6 +13,7 @@ mod tools;
 pub use app::*;
 pub use error::*;
 pub use experimental::*;
+pub use hooks::*;
 pub use logging::*;
 pub use mcp::*;
 pub use oauth::*;