//! Claude Code 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 Claude Code 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 //! `~/.claude/settings.json`. Only entries maestro itself wrote (identified //! by [`HOOK_MARKER`]) are touched; every other hook and every other field //! in the file is preserved verbatim. 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. pub const HOOK_MARKER: &str = "maestro-claude-hook"; /// File name of the installed script (carries [`HOOK_MARKER`]). pub const SCRIPT_FILE_NAME: &str = "maestro-claude-hook.sh"; /// Hook events installed only with the `haiku-autoname` feature (#131). /// `UserPromptSubmit` carries the prompt the user just submitted; 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 HOOK_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"), ]; /// The shipped hook script. POSIX sh so any `/bin/sh` works. pub const HOOK_SCRIPT: &str = r#"#!/bin/sh # Installed by maestro (#106): report Claude Code activity to its daemon. # 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 (permission / idle notice) # Stop -> AwaitingInput (turn ended; waiting on the user) # StopFailure -> Error (turn ended on an API 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) } /// The user-level Claude Code settings file for a given home directory. pub fn settings_path(home: &Path) -> std::path::PathBuf { home.join(".claude/settings.json") } /// Whether `settings_path` already carries a maestro hook (#106). pub fn is_installed(settings_path: &Path) -> bool { settings_json(settings_path) .map(|root| find_maestro_commands(&root).next().is_some()) .unwrap_or(false) } /// 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 `home`: write the script under /// `.local/share/maestro/` and register it in `.claude/settings.json`. /// Idempotent; returns whether anything changed on disk. pub fn install_for_home(home: &Path) -> Result { let script = script_path(home); let settings = settings_path(home); let before = std::fs::read_to_string(&settings).unwrap_or_default(); write_script(&script)?; install(&settings, &script)?; let after = std::fs::read_to_string(&settings).unwrap_or_default(); Ok(before != after) } /// Register the hook command for every event in [`HOOK_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(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 HOOK_EVENTS.iter().chain(PROMPT_EVENTS.iter()).copied() { 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;