Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
1 change: 1 addition & 0 deletions src/admin.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
57 changes: 57 additions & 0 deletions src/cli/notify.rs
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,9 @@ pub struct Settings {
pub mode: Mode,
pub command: Option<String>,
pub after: Duration,
/// The operator's `notification` hook commands (`crate::hooks`), run
/// beside `command` for every notification.
pub hooks: Option<crate::hooks::HookRunner>,
}

impl Default for Settings {
Expand All @@ -87,6 +90,7 @@ impl Default for Settings {
mode: Mode::Auto,
command: None,
after: DEFAULT_AFTER,
hooks: None,
}
}
}
Expand All @@ -105,6 +109,7 @@ impl Settings {
after: admin
.notify_after_secs
.map_or(DEFAULT_AFTER, Duration::from_secs),
hooks: crate::hooks::HookRunner::from_settings(),
}
}

Expand Down Expand Up @@ -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),
Expand Down Expand Up @@ -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::<serde_json::Value>(&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);
Expand Down
2 changes: 2 additions & 0 deletions src/desktop/mcp.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1756,6 +1756,7 @@ mod tests {
user_prompt_submit: Vec::new(),
pre_compact: Vec::new(),
stop: Vec::new(),
notification: Vec::new(),
},
);

Expand Down Expand Up @@ -1795,6 +1796,7 @@ mod tests {
user_prompt_submit: Vec::new(),
pre_compact: Vec::new(),
stop: Vec::new(),
notification: Vec::new(),
},
);

Expand Down
29 changes: 29 additions & 0 deletions src/hooks/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,11 @@ pub struct HookConfig {
/// with the turn's notices.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub stop: Vec<String>,
/// 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<String>,
}

impl HookConfig {
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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);
}
}

Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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()));
Expand All @@ -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()));
Expand Down
1 change: 1 addition & 0 deletions src/toolbox/hook_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ fn hooked(ws: &Path, pre: String, post: Vec<String>) -> Toolbox {
user_prompt_submit: Vec::new(),
pre_compact: Vec::new(),
stop: Vec::new(),
notification: Vec::new(),
},
)))
}
Expand Down
Loading