maestro/crates/maestro-hooks/src/lib.rs

//! 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";

/// 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)
state="$1"
[ -n "$MAESTRO_SESSION_ID" ] || exit 0
[ -n "$MAESTRO_URL" ] || exit 0
payload=$(cat 2>/dev/null) || true
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:
/// `<home>/.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<bool, HooksError> {
    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 {
        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<serde_json::Value, HooksError> {
    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<Item = &str> {
    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<String, serde_json::Value> {
    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<String, serde_json::Value>,
    key: &str,
) -> &'a mut Vec<serde_json::Value> {
    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;