From 239aa2b64a3547e574011aefa3a9f68ffbd1eadf Mon Sep 17 00:00:00 2001 From: blockmandev <194144408+blockmandev@users.noreply.github.com> Date: Wed, 21 Oct 2026 22:34:38 -0600 Subject: [PATCH] hooks: notification, run beside notify_command (refs #26) #26 item 5, third event. The operator's `notification` hook commands (admin.json `hooks`, and the operator's own plugins: a project's plugin gives only the tool events) run whenever incode would notify the person: a long turn finished, or the agent is waiting on them. The event is JSON on stdin: hook_event_name Notification, notification_type (turn_done or input_needed) and message, bounded at 10 s. They run from cli::notify::deliver on a thread of their own, beside notify_command, so a slow one never holds up the prompt; they cannot change anything and what they print is not shown. REPL only, as the notifications themselves are. Test: deliver with the hook set runs it, and it is told the kind and the message. Control: with the firing removed, it never runs. --- README.md | 2 +- src/admin.rs | 1 + src/cli/notify.rs | 57 +++++++++++++++++++++++++++++++++++++++ src/desktop/mcp.rs | 2 ++ src/hooks/mod.rs | 29 ++++++++++++++++++++ src/toolbox/hook_tests.rs | 1 + 6 files changed, 91 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2f22335..e3858af 100644 --- a/README.md +++ b/README.md @@ -1343,7 +1343,7 @@ and `--admin` prints which layer decided each value. | `sandbox_network` | `allow` (default) · `deny` — see [the OS sandbox](#the-os-sandbox) | | `sandbox_engine` · `sandbox_allow_hosts` · `sandbox_backend` | `builtin` (default) · `sbx`; under sbx, the hosts a command may reach and, on Windows, `native` · `wsl` · `auto` — see [the OS sandbox](#the-os-sandbox) | | `codex_tools` | `own` (default) · `incode` — whose tools a `codex` model runs; see [the codex route](#the-codex-route-whose-tools) | -| `hooks` (also `desktop_hooks`) | Your `pre_tool_use` / `post_tool_use` commands, run for every tool, and `user_prompt_submit`, run for each line you send. The event is JSON on stdin (`hook_event_name`, `session_id`, `cwd`, and `tool_name`/`tool_input` or `prompt`); exit 2 on a pre-tool command denies the call, on a prompt command refuses the line (the reason is shown and nothing is sent — not to the agent, not to the memory engine); a prompt command's stdout is added to that turn's context, and your line is never changed; bounded at 10 s. The prompt hook runs for lines typed in the REPL or sent over `--acp`, and for `-t`; `/review` and `/run` do not run it. It is taken from here and from your own plugins (`~/.incode/plugins/`), never from a project's `.incode/plugins/`, which arrives with whatever was cloned. `pre_compact` runs before `/compact` (event field `trigger`: `manual`, plus `custom_instructions`; when the agent compacts its own conversation, as a CLI agent does, it still runs and nothing is compacted by incode), and `stop` when one of your turns has ended (`last_assistant_message`); neither can refuse anything, and their stdout is shown — with the compaction result, and with the turn's notices | +| `hooks` (also `desktop_hooks`) | Your `pre_tool_use` / `post_tool_use` commands, run for every tool, and `user_prompt_submit`, run for each line you send. The event is JSON on stdin (`hook_event_name`, `session_id`, `cwd`, and `tool_name`/`tool_input` or `prompt`); exit 2 on a pre-tool command denies the call, on a prompt command refuses the line (the reason is shown and nothing is sent — not to the agent, not to the memory engine); a prompt command's stdout is added to that turn's context, and your line is never changed; bounded at 10 s. The prompt hook runs for lines typed in the REPL or sent over `--acp`, and for `-t`; `/review` and `/run` do not run it. It is taken from here and from your own plugins (`~/.incode/plugins/`), never from a project's `.incode/plugins/`, which arrives with whatever was cloned. `pre_compact` runs before `/compact` (event field `trigger`: `manual`, plus `custom_instructions`; when the agent compacts its own conversation, as a CLI agent does, it still runs and nothing is compacted by incode), and `stop` when one of your turns has ended (`last_assistant_message`); neither can refuse anything, and their stdout is shown — with the compaction result, and with the turn's notices. `notification` runs whenever incode would notify you (`notification_type`: `turn_done` or `input_needed`, plus `message`), in the background beside `notify_command`, in the REPL; its output is not shown | | `desktop_limits` | The desktop's limits, each optional: `max_actions_per_minute` (120), `heartbeat_deadline_secs` (30), `tree_depth` (12), `tree_max_elements` (400), `journal_max_bytes` (262144), `xvfb_start_timeout_secs` (10), `clipboard_timeout_secs` (5), `accessibility_call_timeout_ms` (1000), `paste_restore_delay_ms` (500, how long the pasted text stays on the clipboard before the old one is put back), `settle_ms` (300, the pause before a `screenshot_after`), `max_scroll_steps` (50, wheel steps in one `scroll`), `tree_max_visited` (4000, elements one tree walk may visit), and `blocked_apps` (application names, matched case-insensitively as a part of the name, added to the built-in password managers: 1Password, Bitwarden, LastPass, Dashlane, KeePass, NordPass, Proton Pass, Enpass, RoboForm, Keeper). The first two are safety limits and may only be lowered; zero and unknown keys are refused, and the desktop does not start on a malformed admin.json | | `desktop_display` | Linux computer use: `":N"` drives a running X display; `"xvfb"` or `"xvfb:1280x800"` starts a private Xvfb for the desktop server's lifetime (default 1920x1080). Unset refuses rather than using `$DISPLAY`. `paste_text` needs `xclip` or `xsel`; `ui_tree` needs a D-Bus session with at-spi2-core | | `plugins` | Which memory-service parts are used; all on by default | diff --git a/src/admin.rs b/src/admin.rs index 200b874..7fdfd91 100644 --- a/src/admin.rs +++ b/src/admin.rs @@ -1608,6 +1608,7 @@ mod tests { user_prompt_submit: vec!["a-prompt-check".to_string()], pre_compact: vec!["a-compact-note".to_string()], stop: vec!["a-stop-note".to_string()], + notification: vec!["a-notify-hook".to_string()], }, desktop_display: Some("xvfb:1280x800".to_string()), desktop_limits: crate::desktop::limits::DesktopLimits { diff --git a/src/cli/notify.rs b/src/cli/notify.rs index f6fda67..6929667 100644 --- a/src/cli/notify.rs +++ b/src/cli/notify.rs @@ -79,6 +79,9 @@ pub struct Settings { pub mode: Mode, pub command: Option, pub after: Duration, + /// The operator's `notification` hook commands (`crate::hooks`), run + /// beside `command` for every notification. + pub hooks: Option, } impl Default for Settings { @@ -87,6 +90,7 @@ impl Default for Settings { mode: Mode::Auto, command: None, after: DEFAULT_AFTER, + hooks: None, } } } @@ -105,6 +109,7 @@ impl Settings { after: admin .notify_after_secs .map_or(DEFAULT_AFTER, Duration::from_secs), + hooks: crate::hooks::HookRunner::from_settings(), } } @@ -159,6 +164,20 @@ fn deliver(settings: &Settings, event: Event, message: &str) { if let Some(command) = &settings.command { spawn_shell(command, &command_env(event, message)); } + // The operator's `notification` hooks (`crate::hooks`), beside the + // command and like it in the background: a slow one never holds up the + // prompt. What they print is not shown — a notification is the output. + if let Some(hooks) = settings.hooks.clone() { + let kind = match event { + Event::Done => "turn_done", + Event::Input => "input_needed", + }; + let message = message.to_string(); + std::thread::spawn(move || { + let cwd = std::env::current_dir().ok(); + let _told = hooks.notification(kind, &message, cwd.as_deref()); + }); + } match settings.mode { Mode::Off => {} Mode::Bell => write_terminal(BELL), @@ -331,6 +350,44 @@ fn spawn_detached(program: &str, args: &[String], env: &[(String, String)]) -> b mod tests { use super::*; + /// **A NOTIFICATION RUNS THE OPERATOR'S `notification` HOOK**, in the + /// background, told what kind it is and what the person is told. + #[test] + fn a_notification_runs_the_notification_hook_with_its_kind_and_message() { + let dir = tempfile::tempdir().expect("dir"); + let saved = dir.path().join("event.json"); + let command = if cfg!(windows) { + format!("more > \"{}\"", saved.display()) + } else { + format!("cat > '{}'", saved.display()) + }; + let settings = Settings { + mode: Mode::Off, + hooks: Some(crate::hooks::HookRunner::new(crate::hooks::HookConfig { + notification: vec![command], + ..crate::hooks::HookConfig::default() + })), + ..Settings::default() + }; + deliver(&settings, Event::Input, "allow Write to a.rs?"); + let deadline = std::time::Instant::now() + Duration::from_secs(15); + let mut event = None; + while std::time::Instant::now() < deadline { + if let Some(json) = std::fs::read_to_string(&saved) + .ok() + .and_then(|text| serde_json::from_str::(&text).ok()) + { + event = Some(json); + break; + } + std::thread::sleep(Duration::from_millis(50)); + } + let event = event.expect("the notification hook never ran"); + assert_eq!(event["hook_event_name"], "Notification"); + assert_eq!(event["notification_type"], "input_needed"); + assert_eq!(event["message"], "allow Write to a.rs?"); + } + #[test] fn the_mode_reads_every_spelling_and_defaults_to_auto() { assert_eq!(Mode::parse(None), Mode::Auto); diff --git a/src/desktop/mcp.rs b/src/desktop/mcp.rs index 2cc829e..dcfc926 100644 --- a/src/desktop/mcp.rs +++ b/src/desktop/mcp.rs @@ -1756,6 +1756,7 @@ mod tests { user_prompt_submit: Vec::new(), pre_compact: Vec::new(), stop: Vec::new(), + notification: Vec::new(), }, ); @@ -1795,6 +1796,7 @@ mod tests { user_prompt_submit: Vec::new(), pre_compact: Vec::new(), stop: Vec::new(), + notification: Vec::new(), }, ); diff --git a/src/hooks/mod.rs b/src/hooks/mod.rs index 76b439f..22bfb79 100644 --- a/src/hooks/mod.rs +++ b/src/hooks/mod.rs @@ -140,6 +140,11 @@ pub struct HookConfig { /// with the turn's notices. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub stop: Vec, + /// Commands run when incode would notify the person: a long turn + /// finished, or the agent is waiting on them. Run in the background, + /// beside `notify_command`; they cannot change anything. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub notification: Vec, } impl HookConfig { @@ -154,6 +159,7 @@ impl HookConfig { && self.user_prompt_submit.is_empty() && self.pre_compact.is_empty() && self.stop.is_empty() + && self.notification.is_empty() } /// How many commands, over every event. Used where a plugin's hooks are @@ -165,6 +171,7 @@ impl HookConfig { + self.user_prompt_submit.len() + self.pre_compact.len() + self.stop.len() + + self.notification.len() } /// `other`'s commands after these, event by event (a plugin's after the @@ -175,6 +182,7 @@ impl HookConfig { self.user_prompt_submit.extend(other.user_prompt_submit); self.pre_compact.extend(other.pre_compact); self.stop.extend(other.stop); + self.notification.extend(other.notification); } } @@ -434,6 +442,25 @@ impl HookRunner { } } +impl HookRunner { + /// The `notification` commands: `kind` is `turn_done` or + /// `input_needed`, `message` what the person is told. They cannot change + /// anything; what they print is not shown. + /// + /// Called by `cli::notify::deliver`, on a thread of its own. + #[must_use] + pub fn notification(&self, kind: &str, message: &str, cwd: Option<&Path>) -> HookRunResult { + run_event( + &self.config.notification, + "Notification", + json!({ "notification_type": kind, "message": message }), + "", + cwd, + false, + ) + } +} + /// Run `commands` for one event that is not a tool call: the event as JSON on /// stdin — `hook_event_name`, `session_id`, `cwd` and `fields` — bounded at /// [`HOOK_TIMEOUT`]. With `can_refuse`, exit 2 refuses (stderr, else stdout, @@ -620,6 +647,7 @@ mod tests { user_prompt_submit: Vec::new(), pre_compact: Vec::new(), stop: Vec::new(), + notification: Vec::new(), }); let input = json!({"path": "a.txt", "content": "hi"}); let ran = runner.pre_tool(&call(&input, dir.path())); @@ -646,6 +674,7 @@ mod tests { user_prompt_submit: Vec::new(), pre_compact: Vec::new(), stop: Vec::new(), + notification: Vec::new(), }); let input = json!({"path": "a.txt"}); let pre = runner.pre_tool(&call(&input, dir.path())); diff --git a/src/toolbox/hook_tests.rs b/src/toolbox/hook_tests.rs index 229622f..bf66e61 100644 --- a/src/toolbox/hook_tests.rs +++ b/src/toolbox/hook_tests.rs @@ -45,6 +45,7 @@ fn hooked(ws: &Path, pre: String, post: Vec) -> Toolbox { user_prompt_submit: Vec::new(), pre_compact: Vec::new(), stop: Vec::new(), + notification: Vec::new(), }, ))) }