//! Agent activity hook (#106). //! //! Two halves, both shared by the `maestro hooks install` CLI subcommand and //! the daemon's first-start auto-install: //! //! * [`HOOK_SCRIPT`] — the hook itself, written to disk at install time. It //! posts an [`ActivityState`](maestro-protocol) to //! `$MAESTRO_URL/api/sessions/$MAESTRO_SESSION_ID/activity` (#105). The same //! global hook runs in every agent session on the machine, so it exits //! 0 and silently when either #103 env var is unset, and it never lets a //! daemon failure escape (short curl timeout, status ignored). //! * [`install`] — idempotent registration of that script in one [`Target`]'s //! hook file. Only entries maestro itself wrote (identified by //! [`HOOK_MARKER`]) are touched; every other hook and every other field in //! the file is preserved verbatim. //! //! One script serves every [`Target`]: Claude Code and Codex read the same //! `{"hooks": {Event: [{"hooks": [{"type": "command", "command": …}]}]}}` //! shape and hand the hook the same JSON on stdin. Only the file's location //! and the event set differ. use std::path::Path; /// Marker substring every maestro-installed hook command carries. The /// installer rewrites or removes exactly these entries — nothing else in the /// user's settings file. /// /// It still says `claude` although the script now serves every [`Target`]: /// the marker is how an install from an older maestro is recognised, and /// renaming it would orphan every entry already on disk. pub const HOOK_MARKER: &str = "maestro-claude-hook"; /// File name of the installed script (carries [`HOOK_MARKER`]). One script /// for every [`Target`] — see the note on [`HOOK_MARKER`] for the name. pub const SCRIPT_FILE_NAME: &str = "maestro-claude-hook.sh"; /// Hook events installed only with the `haiku-autoname` feature (#131), for /// every [`Target`] — Claude Code and Codex both spell the event /// `UserPromptSubmit` and both put the submitted text in the payload's /// `prompt`. The script forwards the whole payload to /// `/api/sessions/:id/prompt`, which names a still-provisionally-named /// session after its first one. #[cfg(feature = "haiku-autoname")] pub const PROMPT_EVENTS: [(&str, &str); 1] = [("UserPromptSubmit", "Prompt")]; /// Same, with the feature off: nothing is installed, so the script never /// posts a prompt and no hook points at a route the daemon does not serve. #[cfg(not(feature = "haiku-autoname"))] pub const PROMPT_EVENTS: [(&str, &str); 0] = []; /// Claude Code hook event → `ActivityState` spelling posted to the daemon. /// /// `PreToolUse` is what makes a session `Active` *during* a long tool call — /// `PostToolUse` alone only fires once it ends (#114). `StopFailure` is /// Claude Code's own name for "the turn ended on an API error"; there is no /// failure signal in `Stop` or `SessionEnd` payloads, so those never report /// `Error`. pub const CLAUDE_EVENTS: [(&str, &str); 5] = [ // Tool starting: the agent is demonstrably producing work, even if the // tool itself runs for minutes. ("PreToolUse", "Active"), // Tool finished successfully. ("PostToolUse", "Active"), // Permission / idle notices: Claude is blocked on the user. ("Notification", "AwaitingInput"), // Turn ended: waiting on the user again. ("Stop", "AwaitingInput"), // Turn ended on an API error; the payload's `error` field is forwarded // as the report's `detail` (#114). ("StopFailure", "Error"), ]; /// Codex hook event → `ActivityState` spelling posted to the daemon. /// /// Codex's event set is close to Claude Code's but not identical: a pending /// approval arrives as `PermissionRequest` rather than `Notification`, and /// there is no `StopFailure`, so a codex session never reports `Error`. pub const CODEX_EVENTS: [(&str, &str); 4] = [ ("PreToolUse", "Active"), ("PostToolUse", "Active"), // Codex is blocked on the operator approving a tool call. ("PermissionRequest", "AwaitingInput"), ("Stop", "AwaitingInput"), ]; /// An agent whose hook file maestro writes into. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Target { /// `~/.claude/settings.json`. ClaudeCode, /// `~/.codex/hooks.json`. Codex asks the operator to trust a hook it has /// not seen before, so an install here does nothing until they approve it /// once inside codex — maestro never writes that approval itself. Codex, } impl Target { /// Every target an install covers. Both files are written whether or not /// the agent is on the machine: an unused hook file costs nothing, and /// the alternative is a session spawned after the daemon started missing /// the hook because its agent arrived later. pub const ALL: [Target; 2] = [Target::ClaudeCode, Target::Codex]; /// How the target is named in logs and CLI output. pub fn label(self) -> &'static str { match self { Target::ClaudeCode => "claude-code", Target::Codex => "codex", } } /// The file this target's hook entries are registered in, under `home`. pub fn settings_path(self, home: &Path) -> std::path::PathBuf { match self { Target::ClaudeCode => home.join(".claude/settings.json"), Target::Codex => home.join(".codex/hooks.json"), } } /// The activity events this target emits. pub fn activity_events(self) -> &'static [(&'static str, &'static str)] { match self { Target::ClaudeCode => &CLAUDE_EVENTS, Target::Codex => &CODEX_EVENTS, } } /// Every event installed for this target: its activity events plus, with /// `haiku-autoname` on, the prompt event both agents spell the same way. pub fn events(self) -> impl Iterator { self.activity_events() .iter() .chain(PROMPT_EVENTS.iter()) .copied() } } /// The shipped hook script. POSIX sh so any `/bin/sh` works. pub const HOOK_SCRIPT: &str = r#"#!/bin/sh # Installed by maestro (#106): report agent activity to its daemon. # One script for every agent maestro installs hooks into; the state to post # is chosen by the caller, so the two event sets differ only in what is # registered where. Exits silently unless running inside a session maestro # spawned (#103 env). # Event -> ActivityState mapping: # PreToolUse -> Active (tool started; agent is working) # PostToolUse -> Active (tool finished) # Notification -> AwaitingInput (claude code: permission / idle) # PermissionRequest -> AwaitingInput (codex: waiting on an approval) # Stop -> AwaitingInput (turn ended; waiting on the user) # StopFailure -> Error (claude code: turn ended on an error) # Prompt -> the payload is forwarded to the prompt route (#131) state="$1" [ -n "$MAESTRO_SESSION_ID" ] || exit 0 [ -n "$MAESTRO_URL" ] || exit 0 payload=$(cat 2>/dev/null) || true # "Prompt" is not an activity state (#131): the payload already carries the # submitted prompt, so it is forwarded verbatim to the prompt route. Building # the JSON here instead would mean quoting arbitrary user text in shell. if [ "$state" = "Prompt" ]; then printf '%s' "$payload" | curl -fsS --connect-timeout 1 --max-time 2 \ -H 'Content-Type: application/json' \ --data-binary @- \ "$MAESTRO_URL/api/sessions/$MAESTRO_SESSION_ID/prompt" \ >/dev/null 2>&1 || true exit 0 fi body="{\"state\":\"$state\"}" # StopFailure payloads carry the outcome in "error". Only a plain enum # spelling is reported as the detail — anything else (quotes, backslashes, # prose) would risk breaking the JSON body, and the spelling already names # the failure. detail=$(printf '%s' "$payload" | sed -n 's/.*"error"[[:space:]]*:[[:space:]]*"\([a-z_]*\)".*/\1/p') if [ -n "$detail" ]; then body="{\"state\":\"$state\",\"detail\":\"$detail\"}" fi curl -fsS --connect-timeout 1 --max-time 2 \ -H 'Content-Type: application/json' \ -d "$body" \ "$MAESTRO_URL/api/sessions/$MAESTRO_SESSION_ID/activity" \ >/dev/null 2>&1 || true exit 0 "#; #[derive(Debug, thiserror::Error)] pub enum HooksError { #[error("io: {0}")] Io(#[from] std::io::Error), #[error("json: {0}")] Json(#[from] serde_json::Error), } /// Where the script is written for a given home directory: /// `/.local/share/maestro/maestro-claude-hook.sh`. pub fn script_path(home: &Path) -> std::path::PathBuf { home.join(".local/share/maestro").join(SCRIPT_FILE_NAME) } /// Whether the file at `settings_path` already carries a maestro hook /// (#106). Presence only: an install from an older release answers `true` /// even when it is missing events this build ships — see [`is_current`]. pub fn is_installed(settings_path: &Path) -> bool { settings_json(settings_path) .map(|root| find_maestro_commands(&root).next().is_some()) .unwrap_or(false) } /// Whether what is on disk is what this build ships for `target`: the script /// at `script_path` byte-for-byte, and exactly one settings entry per one of /// the target's [`Target::events`], pointing at that script. /// /// This is the upgrade question, asked per [`Target`]. A maestro that gains /// an event — #131 added `UserPromptSubmit` long after #106 had installed /// itself — leaves every existing user with a present but incomplete /// install, which [`is_installed`] cannot tell apart from a current one. pub fn is_current(target: Target, settings_path: &Path, script_path: &Path) -> bool { if std::fs::read_to_string(script_path).ok().as_deref() != Some(HOOK_SCRIPT) { return false; } settings_json(settings_path) .map(|root| maestro_entries(&root) == expected_entries(target, script_path)) .unwrap_or(false) } /// Every maestro entry in the file as `(event, command)`, sorted — so a /// duplicate, a stale event or a wrong script path all show up as a /// difference against [`expected_entries`]. fn maestro_entries(root: &serde_json::Value) -> Vec<(String, String)> { let mut found: Vec<(String, String)> = root .get("hooks") .and_then(|h| h.as_object()) .into_iter() .flatten() .flat_map(|(event, groups)| { groups .as_array() .into_iter() .flatten() .filter_map(|group| group.get("hooks")) .filter_map(|inner| inner.as_array()) .flatten() .filter_map(|hook| hook.get("command")) .filter_map(|cmd| cmd.as_str()) .filter(|cmd| cmd.contains(HOOK_MARKER)) .map(move |cmd| (event.clone(), cmd.to_string())) }) .collect(); found.sort(); found } /// What [`install`] writes for `target` and `script_path`, in the same shape. fn expected_entries(target: Target, script_path: &Path) -> Vec<(String, String)> { let mut want: Vec<(String, String)> = target .events() .map(|(event, state)| { ( event.to_string(), format!("{} {state}", script_path.display()), ) }) .collect(); want.sort(); want } /// Write [`HOOK_SCRIPT`] to `path`, executable. Parent directories are /// created as needed — this is always under the caller's chosen data dir, /// never inside a repository. pub fn write_script(path: &Path) -> Result<(), HooksError> { if let Some(dir) = path.parent() { std::fs::create_dir_all(dir)?; } std::fs::write(path, HOOK_SCRIPT)?; #[cfg(unix)] { use std::os::unix::fs::PermissionsExt; let mut perms = std::fs::metadata(path)?.permissions(); perms.set_mode(0o755); std::fs::set_permissions(path, perms)?; } Ok(()) } /// Install the full hook setup for one target under `home`: write the script /// under `.local/share/maestro/` and register it in the target's hook file. /// Idempotent; returns whether anything changed on disk. pub fn install_target(target: Target, home: &Path) -> Result { let script = script_path(home); let settings = target.settings_path(home); // A script left over from an older release counts as a change even when // the settings entries pointing at it are already right. let changed = !is_current(target, &settings, &script); write_script(&script)?; install(target, &settings, &script)?; Ok(changed) } /// Install for every [`Target::ALL`], reporting each one separately. One /// target failing — an unwritable file, unparseable JSON — never stops the /// others: an agent whose hook could not be written is one agent without /// activity reporting, not a failed install. pub fn install_for_home(home: &Path) -> Vec<(Target, Result)> { Target::ALL .iter() .map(|&target| (target, install_target(target, home))) .collect() } /// Register the hook command for every one of `target`'s [`Target::events`] /// in the settings file at `settings_path`. Idempotent: existing maestro /// entries are updated in place wherever they sit, stale ones removed, /// duplicates folded; every non-maestro entry and every unrelated top-level /// field survives. /// /// Never inspects or writes anywhere but `settings_path` — callers pass the /// user's real home or a temp one in tests, never a repository. pub fn install(target: Target, settings_path: &Path, script_path: &Path) -> Result<(), HooksError> { let mut root = settings_json(settings_path)?; // Strip every maestro entry wherever it currently sits, so an older // install under different events is replaced rather than duplicated. strip_maestro_entries(&mut root); let hooks = ensure_object(&mut root, "hooks"); for (event, state) in target.events() { let groups = ensure_array(hooks, event); let mut group = serde_json::Map::new(); group.insert( "hooks".into(), serde_json::json!([{ "type": "command", "command": format!("{} {state}", script_path.display()), }]), ); groups.push(serde_json::Value::Object(group)); } write_atomic(settings_path, &root) } fn settings_json(path: &Path) -> Result { match std::fs::read_to_string(path) { Ok(s) => Ok(serde_json::from_str(&s)?), Err(e) if e.kind() == std::io::ErrorKind::NotFound => { Ok(serde_json::Value::Object(Default::default())) } Err(e) => Err(e.into()), } } /// Every command string in the file belonging to a maestro hook. fn find_maestro_commands(root: &serde_json::Value) -> impl Iterator { root.get("hooks") .and_then(|h| h.as_object()) .into_iter() .flat_map(|events| events.values()) .filter_map(|groups| groups.as_array()) .flatten() .filter_map(|group| group.get("hooks")) .filter_map(|inner| inner.as_array()) .flatten() .filter_map(|hook| hook.get("command")) .filter_map(|cmd| cmd.as_str()) .filter(|cmd| cmd.contains(HOOK_MARKER)) } /// Remove all maestro inner-hook entries from every event group, dropping /// groups left empty. Non-maestro siblings survive untouched. fn strip_maestro_entries(root: &mut serde_json::Value) { let Some(events) = root.get_mut("hooks").and_then(|h| h.as_object_mut()) else { return; }; for (_, groups) in events.iter_mut() { let Some(list) = groups.as_array_mut() else { continue; }; for group in list.iter_mut() { let Some(inner) = group.get_mut("hooks").and_then(|h| h.as_array_mut()) else { continue; }; inner.retain(|hook| { !hook .get("command") .and_then(|c| c.as_str()) .is_some_and(|c| c.contains(HOOK_MARKER)) }); } list.retain(|group| { group .get("hooks") .and_then(|h| h.as_array()) .is_some_and(|h| !h.is_empty()) }); } // An event left with no groups at all (ours emptied it, or the user's // file carried an empty list) reads better gone. events.retain(|_, groups| groups.as_array().is_some_and(|g| !g.is_empty())); } fn ensure_object<'a>( root: &'a mut serde_json::Value, key: &str, ) -> &'a mut serde_json::Map { if !root.get(key).map(|v| v.is_object()).unwrap_or(false) { root[key] = serde_json::json!({}); } root.get_mut(key).unwrap().as_object_mut().unwrap() } fn ensure_array<'a>( parent: &'a mut serde_json::Map, key: &str, ) -> &'a mut Vec { let v = parent .entry(key.to_string()) .or_insert_with(|| serde_json::json!([])); if !v.is_array() { *v = serde_json::json!([]); } v.as_array_mut().unwrap() } fn write_atomic(path: &Path, value: &serde_json::Value) -> Result<(), HooksError> { if let Some(dir) = path.parent() { std::fs::create_dir_all(dir)?; } let tmp = path.with_extension("json.maestro-tmp"); std::fs::write(&tmp, serde_json::to_string_pretty(value)? + "\n")?; std::fs::rename(&tmp, path)?; Ok(()) } #[cfg(test)] mod tests;