feat(maestro): add maestro hooks install subcommand

crates/maestro-cli/src/cli.rs

@@ -43,6 +43,23 @@ pub enum Command {
     Kill(KillArgs),
     /// List retained worktrees, or reclaim one by ID (#86).
     Worktrees(WorktreesArgs),
+    /// Install or update the agent activity hook (#106).
+    Hooks(HooksArgs),
+}
+
+/// `maestro hooks <install>`
+#[derive(Debug, clap::Args)]
+pub struct HooksArgs {
+    #[command(subcommand)]
+    pub command: HooksCommand,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum HooksCommand {
+    /// Write the Claude Code activity hook into ~/.claude/settings.json.
+    /// Idempotent: an older maestro hook is updated in place, every other
+    /// hook is left untouched.
+    Install,
 }
 
 /// `maestro worktrees <list|reclaim>`
@@ -275,6 +292,23 @@ mod tests {
         assert!(err.to_string().contains("KEY=VALUE"));
     }
 
+    #[test]
+    fn parses_hooks_install() {
+        let cli = Cli::try_parse_from(["maestro", "hooks", "install"]).unwrap();
+        match cli.command {
+            Command::Hooks(h) => {
+                assert!(matches!(h.command, HooksCommand::Install));
+            }
+            _ => panic!("wrong subcommand"),
+        }
+        // No subcommand → help, like `worktrees`.
+        let err = Cli::try_parse_from(["maestro", "hooks"]).unwrap_err();
+        assert!(matches!(
+            err.kind(),
+            clap::error::ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
+        ));
+    }
+
     #[test]
     fn parses_worktrees_list() {
         let cli = Cli::try_parse_from(["maestro", "worktrees", "list", "--json"]).unwrap();

crates/maestro-cli/src/dispatch.rs

@@ -24,6 +24,10 @@ pub enum CliError {
     #[error("{0}")]
     Attach(#[from] crate::attach::AttachError),
     #[error("{0}")]
+    Hooks(#[from] maestro_hooks::HooksError),
+    #[error("could not determine the home directory ($HOME unset?)")]
+    NoHome,
+    #[error("{0}")]
     Io(#[from] std::io::Error),
 }
 
@@ -40,6 +44,15 @@ pub async fn dispatch(
         None => default_config_path()?,
     };
 
+    // `hooks install` is purely local: it must work with the daemon down, so
+    // it never touches the client.
+    if let Command::Hooks(args) = &command {
+        match args.command {
+            crate::cli::HooksCommand::Install => run_hooks_install()?,
+        }
+        return Ok(());
+    }
+
     let daemon = client(&config_path, daemon_url_override)?;
 
     match command {
@@ -77,6 +90,7 @@ pub async fn dispatch(
                 );
             }
         }
+        Command::Hooks(_) => unreachable!("hooks handled before the daemon client exists"),
         Command::Worktrees(args) => match args.command {
             WorktreesCommand::List(list_args) => {
                 let mut stdout = std::io::stdout().lock();
@@ -101,6 +115,25 @@ pub async fn dispatch(
     Ok(())
 }
 
+/// `maestro hooks install` (#106): write the shipped hook script under the
+/// user's data dir and register it in their Claude Code settings. Idempotent
+/// and foreign-hook-preserving — the guarantees live in [`maestro_hooks`].
+#[allow(clippy::result_large_err)]
+fn run_hooks_install() -> Result<(), CliError> {
+    let home = dirs::home_dir().ok_or(CliError::NoHome)?;
+    let changed = maestro_hooks::install_for_home(&home)?;
+    if changed {
+        println!(
+            "installed claude-code activity hook: {} → {}",
+            maestro_hooks::script_path(&home).display(),
+            maestro_hooks::settings_path(&home).display()
+        );
+    } else {
+        println!("claude-code activity hook already up to date");
+    }
+    Ok(())
+}
+
 /// Default detach byte, matching `maestro attach --detach-key`'s `^q`.
 const CTRL_Q: u8 = 0x11;