From aeeb755702fafbcd7845e949996fe77e961aa553 Mon Sep 17 00:00:00 2001 From: Vincent Date: Thu, 25 Jun 2026 15:37:06 -0400 Subject: [PATCH 1/4] feat(agent): add --json output to `atomic agent hooks` Adds an opt-in `--json` flag to `atomic agent hooks ` that prints a machine-readable result on stdout describing what the hook recorded: session id, whether a change was recorded, the change hash, and the files in that change. Why: a coordinator driving an agent turn through the hook surface (e.g. the Sherpa UI bridging an ACP run into Atomic) needs the recorded change hash to link the turn to its Atomic change. The hook surface previously kept stdout quiet by design, so there was no way to get the hash back without linking the engine crate directly. The flag is off by default, so existing integrations are unaffected (Claude Code reads its own JSON response from stdout; the OpenCode plugin treats stdout as TUI noise). Only callers that pass `--json` get the extra line. --- atomic-cli/src/commands/agent/hooks.rs | 102 +++++++++++++++++++++++++ 1 file changed, 102 insertions(+) diff --git a/atomic-cli/src/commands/agent/hooks.rs b/atomic-cli/src/commands/agent/hooks.rs index 4efbdb0a..790008c0 100644 --- a/atomic-cli/src/commands/agent/hooks.rs +++ b/atomic-cli/src/commands/agent/hooks.rs @@ -57,6 +57,7 @@ use clap::Args; use atomic_agent::event::HookType; use atomic_agent::hooks::AgentRegistry; +use atomic_core::types::Base32; use crate::commands::{find_repository_root, Command}; use crate::error::{CliError, CliResult}; @@ -87,6 +88,33 @@ pub struct Hooks { /// Run the hook body in this process. #[arg(long, hide = true)] foreground: bool, + + /// Emit a machine-readable JSON result on stdout describing what the hook + /// recorded (session id, whether a change was recorded, the change hash, + /// and the files in that change). + /// + /// Off by default so existing agent integrations (Claude Code reads its own + /// JSON response from stdout; the OpenCode plugin treats stdout as TUI + /// noise) are unaffected. Callers that need the recorded change hash — e.g. + /// the Sherpa UI bridging an ACP run into Atomic — pass `--json`. + #[arg(long, hide = true)] + json: bool, +} + +/// Machine-readable result of a hook invocation, emitted on stdout when +/// `--json` is passed. Lets a coordinator (e.g. the Sherpa UI) link the ACP +/// turn to the Atomic change it produced. +#[derive(Debug, serde::Serialize)] +struct HookJsonResult { + /// The agent session id the hook ran under. + session_id: String, + /// Whether this hook recorded an Atomic change. + recorded: bool, + /// The recorded change hash (base32), if a change was recorded. + #[serde(skip_serializing_if = "Option::is_none")] + change_hash: Option, + /// The files in the recorded change (empty when nothing was recorded). + files: Vec, } impl Command for Hooks { @@ -209,6 +237,33 @@ impl Command for Hooks { log::debug!("Hook response: {}", message); } + // When explicitly requested (`--json`), emit a machine-readable result + // on stdout for coordinators that need the recorded change hash. This is + // opt-in so the default quiet behavior above is preserved for the agents + // that read or ignore stdout themselves. + if self.json { + let json = match &result.change_recorded { + Some(outcome) => HookJsonResult { + session_id: result.session_id.clone(), + recorded: true, + change_hash: Some(outcome.hash.to_base32()), + files: outcome.recorded_file_list().to_vec(), + }, + None => HookJsonResult { + session_id: result.session_id.clone(), + recorded: false, + change_hash: None, + files: Vec::new(), + }, + }; + // Serialize defensively: a serialization failure must not turn a + // successful hook into an error. + match serde_json::to_string(&json) { + Ok(s) => println!("{}", s), + Err(e) => log::warn!("Failed to serialize hook JSON result: {}", e), + } + } + Ok(()) } } @@ -268,6 +323,7 @@ mod tests { agent_name: "claude-code".to_string(), verb: "stop".to_string(), foreground: false, + json: false, }; assert_eq!(hooks.agent_name, "claude-code"); assert_eq!(hooks.verb, "stop"); @@ -376,6 +432,7 @@ mod tests { agent_name: "claude-code".to_string(), verb: "session-start".to_string(), foreground: false, + json: false, }; let debug = format!("{:?}", hooks); assert!(debug.contains("claude-code")); @@ -388,6 +445,7 @@ mod tests { agent_name: "codex".to_string(), verb: "stop".to_string(), foreground: false, + json: false, }; assert!(hooks.should_handoff_codex_stop()); @@ -399,6 +457,7 @@ mod tests { agent_name: "codex".to_string(), verb: "stop".to_string(), foreground: true, + json: false, }; assert!(!hooks.should_handoff_codex_stop()); @@ -410,8 +469,51 @@ mod tests { agent_name: "claude-code".to_string(), verb: "stop".to_string(), foreground: false, + json: false, }; assert!(!hooks.should_handoff_codex_stop()); } + + #[test] + fn test_hook_json_result_recorded() { + // The shape a coordinator (Sherpa UI) parses to link an ACP turn to its + // Atomic change. + let result = HookJsonResult { + session_id: "sess-abc".to_string(), + recorded: true, + change_hash: Some("ABC123".to_string()), + files: vec!["src/main.rs".to_string(), "src/lib.rs".to_string()], + }; + let parsed: serde_json::Value = + serde_json::from_str(&serde_json::to_string(&result).unwrap()).unwrap(); + + assert_eq!(parsed["session_id"], "sess-abc"); + assert_eq!(parsed["recorded"], true); + assert_eq!(parsed["change_hash"], "ABC123"); + assert_eq!(parsed["files"][0], "src/main.rs"); + assert_eq!(parsed["files"][1], "src/lib.rs"); + } + + #[test] + fn test_hook_json_result_not_recorded_omits_hash() { + // When nothing was recorded, `change_hash` is omitted (not null) and + // `files` is empty. + let result = HookJsonResult { + session_id: "sess-xyz".to_string(), + recorded: false, + change_hash: None, + files: Vec::new(), + }; + let json = serde_json::to_string(&result).unwrap(); + let parsed: serde_json::Value = serde_json::from_str(&json).unwrap(); + + assert_eq!(parsed["recorded"], false); + assert!( + !json.contains("change_hash"), + "change_hash must be omitted when None, got: {}", + json + ); + assert_eq!(parsed["files"].as_array().unwrap().len(), 0); + } } From 20579945a71f0d02753776e640db82d68c8324e1 Mon Sep 17 00:00:00 2001 From: Vincent Date: Thu, 25 Jun 2026 15:49:55 -0400 Subject: [PATCH 2/4] fix(agent): don't background-handoff codex stop when --json is set `atomic agent hooks codex stop` detaches into a background recorder whose stdout is null, so a `--json` caller could never receive the recorded change hash. Skip the handoff and run in-process when `--json` is requested, so the caller gets the JSON result synchronously. Default (non-json) codex stop still hands off as before. --- atomic-cli/src/commands/agent/hooks.rs | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/atomic-cli/src/commands/agent/hooks.rs b/atomic-cli/src/commands/agent/hooks.rs index 790008c0..6ba984a6 100644 --- a/atomic-cli/src/commands/agent/hooks.rs +++ b/atomic-cli/src/commands/agent/hooks.rs @@ -270,7 +270,11 @@ impl Command for Hooks { impl Hooks { fn should_handoff_codex_stop(&self) -> bool { - !self.foreground && self.agent_name == "codex" && self.verb == "stop" + // `--json` callers (e.g. the Sherpa UI bridge) need the recorded change + // hash on stdout synchronously. The background handoff detaches into a + // child whose stdout is null, so it can never return JSON — run the hook + // in-process instead when JSON output is requested. + !self.foreground && !self.json && self.agent_name == "codex" && self.verb == "stop" } fn handoff_codex_stop(&self, input: &[u8]) -> CliResult<()> { @@ -451,6 +455,20 @@ mod tests { assert!(hooks.should_handoff_codex_stop()); } + #[test] + fn test_codex_stop_json_disables_handoff() { + // `--json` must run in-process so the caller gets the change hash on + // stdout; the background handoff nulls stdout and could never return it. + let hooks = Hooks { + agent_name: "codex".to_string(), + verb: "stop".to_string(), + foreground: false, + json: true, + }; + + assert!(!hooks.should_handoff_codex_stop()); + } + #[test] fn test_codex_stop_foreground_disables_handoff() { let hooks = Hooks { From e7df4349ff5f1b7d28fdc8d8aded585f44ea91ee Mon Sep 17 00:00:00 2001 From: Vincent Date: Fri, 26 Jun 2026 10:01:30 -0400 Subject: [PATCH 3/4] chore(agent): trim hook json comments --- atomic-cli/src/commands/agent/hooks.rs | 40 ++++---------------------- 1 file changed, 5 insertions(+), 35 deletions(-) diff --git a/atomic-cli/src/commands/agent/hooks.rs b/atomic-cli/src/commands/agent/hooks.rs index 6ba984a6..d545055b 100644 --- a/atomic-cli/src/commands/agent/hooks.rs +++ b/atomic-cli/src/commands/agent/hooks.rs @@ -89,31 +89,18 @@ pub struct Hooks { #[arg(long, hide = true)] foreground: bool, - /// Emit a machine-readable JSON result on stdout describing what the hook - /// recorded (session id, whether a change was recorded, the change hash, - /// and the files in that change). - /// - /// Off by default so existing agent integrations (Claude Code reads its own - /// JSON response from stdout; the OpenCode plugin treats stdout as TUI - /// noise) are unaffected. Callers that need the recorded change hash — e.g. - /// the Sherpa UI bridging an ACP run into Atomic — pass `--json`. + /// Print one JSON result line for callers that need the recorded change hash. #[arg(long, hide = true)] json: bool, } -/// Machine-readable result of a hook invocation, emitted on stdout when -/// `--json` is passed. Lets a coordinator (e.g. the Sherpa UI) link the ACP -/// turn to the Atomic change it produced. +/// JSON emitted by `--json`. #[derive(Debug, serde::Serialize)] struct HookJsonResult { - /// The agent session id the hook ran under. session_id: String, - /// Whether this hook recorded an Atomic change. recorded: bool, - /// The recorded change hash (base32), if a change was recorded. #[serde(skip_serializing_if = "Option::is_none")] change_hash: Option, - /// The files in the recorded change (empty when nothing was recorded). files: Vec, } @@ -229,18 +216,12 @@ impl Command for Hooks { log::debug!("{}", outcome); } - // Log the system message instead of printing to stdout. - // Claude Code expects JSON on stdout, but OpenCode's plugin $ - // captures stdout and displays it in the TUI as noise. - // Use log::debug so it's available in RUST_LOG but silent otherwise. + // Keep hook stdout quiet by default; some agent TUIs display it directly. if let Some(ref message) = result.message { log::debug!("Hook response: {}", message); } - // When explicitly requested (`--json`), emit a machine-readable result - // on stdout for coordinators that need the recorded change hash. This is - // opt-in so the default quiet behavior above is preserved for the agents - // that read or ignore stdout themselves. + // Emit the recorded change hash for UI/bridge callers. if self.json { let json = match &result.change_recorded { Some(outcome) => HookJsonResult { @@ -256,8 +237,6 @@ impl Command for Hooks { files: Vec::new(), }, }; - // Serialize defensively: a serialization failure must not turn a - // successful hook into an error. match serde_json::to_string(&json) { Ok(s) => println!("{}", s), Err(e) => log::warn!("Failed to serialize hook JSON result: {}", e), @@ -270,10 +249,7 @@ impl Command for Hooks { impl Hooks { fn should_handoff_codex_stop(&self) -> bool { - // `--json` callers (e.g. the Sherpa UI bridge) need the recorded change - // hash on stdout synchronously. The background handoff detaches into a - // child whose stdout is null, so it can never return JSON — run the hook - // in-process instead when JSON output is requested. + // Codex stop handoff drops stdout, so `--json` must stay in-process. !self.foreground && !self.json && self.agent_name == "codex" && self.verb == "stop" } @@ -457,8 +433,6 @@ mod tests { #[test] fn test_codex_stop_json_disables_handoff() { - // `--json` must run in-process so the caller gets the change hash on - // stdout; the background handoff nulls stdout and could never return it. let hooks = Hooks { agent_name: "codex".to_string(), verb: "stop".to_string(), @@ -495,8 +469,6 @@ mod tests { #[test] fn test_hook_json_result_recorded() { - // The shape a coordinator (Sherpa UI) parses to link an ACP turn to its - // Atomic change. let result = HookJsonResult { session_id: "sess-abc".to_string(), recorded: true, @@ -515,8 +487,6 @@ mod tests { #[test] fn test_hook_json_result_not_recorded_omits_hash() { - // When nothing was recorded, `change_hash` is omitted (not null) and - // `files` is empty. let result = HookJsonResult { session_id: "sess-xyz".to_string(), recorded: false, From 8868ed5496175bb4e5112608ab7ff19bda115edb Mon Sep 17 00:00:00 2001 From: Vincent Date: Fri, 26 Jun 2026 16:40:37 -0400 Subject: [PATCH 4/4] feat(agent): include the record view in hooks turn-end --json MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The agent records each turn onto the session's own (haikunator-named) view, not the default/shared view, so a caller that has only the change hash can't locate it with a plain `log` on the default view. Expose the view as the source of truth from the hook itself. DispatchResult gains a `view` field, set from the session's view_name on turn-end; `atomic agent hooks … turn-end --json` now emits `view` alongside session_id / recorded / change_hash / files (omitted when unknown). Surfaced by a local integration rehearsal: a recorded ACP run's change was on the session view and invisible to a default-view `log`, while `diff --change` (global) still worked. --- atomic-agent/src/turn/orchestrator/mod.rs | 14 ++++++++++++++ atomic-agent/src/turn/orchestrator/turn.rs | 7 +++++-- atomic-cli/src/commands/agent/hooks.rs | 14 ++++++++++++++ 3 files changed, 33 insertions(+), 2 deletions(-) diff --git a/atomic-agent/src/turn/orchestrator/mod.rs b/atomic-agent/src/turn/orchestrator/mod.rs index 43fc34f2..2edb9189 100644 --- a/atomic-agent/src/turn/orchestrator/mod.rs +++ b/atomic-agent/src/turn/orchestrator/mod.rs @@ -97,6 +97,13 @@ pub struct DispatchResult { /// If a turn was recorded, contains the outcome. pub change_recorded: Option, + /// The Atomic view the session records onto (the per-session agent view). + /// + /// Set on turn events so a caller can locate the recorded change, which + /// lives on this view rather than the default/shared view. `None` when the + /// session view is not known for this event. + pub view: Option, + /// User-facing message to return to the agent (via hook stdout). /// /// For `SessionStart`, this is the "Atomic is tracking" message. @@ -117,6 +124,7 @@ impl DispatchResult { session_id: session_id.into(), new_phase: phase, change_recorded: None, + view: None, message: None, warnings: Vec::new(), } @@ -128,6 +136,12 @@ impl DispatchResult { self } + /// Set the session's record view. + pub(crate) fn with_view(mut self, view: impl Into) -> Self { + self.view = Some(view.into()); + self + } + /// Set the user-facing message. pub(crate) fn with_message(mut self, message: impl Into) -> Self { self.message = Some(message.into()); diff --git a/atomic-agent/src/turn/orchestrator/turn.rs b/atomic-agent/src/turn/orchestrator/turn.rs index b35f604a..75aba45e 100644 --- a/atomic-agent/src/turn/orchestrator/turn.rs +++ b/atomic-agent/src/turn/orchestrator/turn.rs @@ -215,8 +215,11 @@ impl TurnOrchestrator { ); let remaining = phase::apply_common_actions(&mut session, &result); - // Execute strategy-specific actions - let mut dispatch = DispatchResult::new(session_id, session.phase); + // Execute strategy-specific actions. Record the session's view so the + // caller can locate the change, which lands on the agent view rather + // than the default view. + let mut dispatch = + DispatchResult::new(session_id, session.phase).with_view(&session.view_name); for action in &remaining { match action { diff --git a/atomic-cli/src/commands/agent/hooks.rs b/atomic-cli/src/commands/agent/hooks.rs index d545055b..20e6a408 100644 --- a/atomic-cli/src/commands/agent/hooks.rs +++ b/atomic-cli/src/commands/agent/hooks.rs @@ -101,6 +101,10 @@ struct HookJsonResult { recorded: bool, #[serde(skip_serializing_if = "Option::is_none")] change_hash: Option, + /// The view the change was recorded onto (the per-session agent view), so a + /// caller can locate it — the change lives here, not on the default view. + #[serde(skip_serializing_if = "Option::is_none")] + view: Option, files: Vec, } @@ -228,12 +232,14 @@ impl Command for Hooks { session_id: result.session_id.clone(), recorded: true, change_hash: Some(outcome.hash.to_base32()), + view: result.view.clone(), files: outcome.recorded_file_list().to_vec(), }, None => HookJsonResult { session_id: result.session_id.clone(), recorded: false, change_hash: None, + view: result.view.clone(), files: Vec::new(), }, }; @@ -473,6 +479,7 @@ mod tests { session_id: "sess-abc".to_string(), recorded: true, change_hash: Some("ABC123".to_string()), + view: Some("bold-creek-a3f2".to_string()), files: vec!["src/main.rs".to_string(), "src/lib.rs".to_string()], }; let parsed: serde_json::Value = @@ -481,6 +488,7 @@ mod tests { assert_eq!(parsed["session_id"], "sess-abc"); assert_eq!(parsed["recorded"], true); assert_eq!(parsed["change_hash"], "ABC123"); + assert_eq!(parsed["view"], "bold-creek-a3f2"); assert_eq!(parsed["files"][0], "src/main.rs"); assert_eq!(parsed["files"][1], "src/lib.rs"); } @@ -491,6 +499,7 @@ mod tests { session_id: "sess-xyz".to_string(), recorded: false, change_hash: None, + view: None, files: Vec::new(), }; let json = serde_json::to_string(&result).unwrap(); @@ -502,6 +511,11 @@ mod tests { "change_hash must be omitted when None, got: {}", json ); + assert!( + !json.contains("view"), + "view must be omitted when None, got: {}", + json + ); assert_eq!(parsed["files"].as_array().unwrap().len(), 0); } }