Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(hooks): normalize native Codex tool observations
Alan Hoffmeister716dc4d70205
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rsindex 2a362a1d..fd6ba9be 100644--- a/crates/ai-memory-cli/src/commands/hook.rs+++ b/crates/ai-memory-cli/src/commands/hook.rs@@ -1924,6 +1924,79 @@ mod tests {assert_eq!(hook_spool::spool_len(&hook_spool::spool_dir(&data_dir)), 0);}+ #[tokio::test]+ async fn codex_native_capture_policy_runs_before_spool_and_preserves_identity() {+ for (tool, input, disposition) in [+ (+ "read_file",+ serde_json::json!({"path": "secret/private.txt"}),+ CaptureDisposition::Drop,+ ),+ (+ "apply_patch",+ serde_json::json!({"command": "*** Begin Patch\n*** Add File: secret/private.txt\n+PRIVATE_CONTENT\n*** End Patch"}),+ CaptureDisposition::MetadataOnly,+ ),+ (+ "apply_patch",+ serde_json::json!(null),+ CaptureDisposition::MetadataOnly,+ ),+ ] {+ for event in ["pre-tool-use", "post-tool-use"] {+ let tmp = tempfile::tempdir().unwrap();+ std::fs::write(+ tmp.path().join(".ai-memory.toml"),+ "workspace = \"native\"\nproject = \"codex\"\n[capture]\nignore_paths = [\"secret/**\"]\n",+ ).unwrap();+ let data_dir = tmp.path().join("data");+ let mut args = devin_hook_args(event);+ args.agent = "codex".into();+ let raw = serde_json::json!({+ "session_id": "native-codex", "cwd": tmp.path(), "turn_id": "turn-1",+ "hook_event_name": if event == "pre-tool-use" { "PreToolUse" } else { "PostToolUse" },+ "tool_name": tool, "tool_input": input, "tool_use_id": "call-native-1",+ "tool_response": {"content": [{"type": "text", "text": "PRIVATE_CONTENT"}]},+ });+ let mut stdout = Vec::new();+ run_with_payload(+ Some(data_dir.clone()),+ args,+ raw.to_string(),+ &mut stdout,+ |_, _| {+ panic!("tool events below the threshold must only spool");+ },+ )+ .await+ .unwrap();+ assert_eq!(stdout, b"{}\n");+ let spool = hook_spool::spool_dir(&data_dir);+ if disposition == CaptureDisposition::Drop {+ assert!(!spool.exists());+ } else {+ let entries = read_spooled_entries(&spool);+ assert_eq!(entries.len(), 1);+ let entry = &entries[0];+ assert_eq!(query_param(&entry.url, "agent"), Some("codex"));+ assert_eq!(query_param(&entry.url, "workspace"), Some("native"));+ assert_eq!(query_param(&entry.url, "project"), Some("codex"));+ assert!(query_param(&entry.url, "ingest_key").is_some());+ assert!(!entry.body.contains("PRIVATE_CONTENT"));+ assert!(!entry.body.contains("private.txt"));+ let body: serde_json::Value = serde_json::from_str(&entry.body).unwrap();+ assert_eq!(body["session_id"], "native-codex");+ assert_eq!(body["tool_call_id"], "call-native-1");+ assert_eq!(body["_ai_memory_capture"]["disposition"], "metadata-only");+ assert_eq!(+ body["_ai_memory_capture"]["extraction_state"],+ "missing-or-malformed"+ );+ }+ }+ }+ }+#[tokio::test]async fn hermes_file_exclusion_drops_before_spool_or_drain() {let tmp = tempfile::tempdir().unwrap();diff --git a/crates/ai-memory-hooks/src/capture_policy.rs b/crates/ai-memory-hooks/src/capture_policy.rsindex 1baa33db..b1475345 100644--- a/crates/ai-memory-hooks/src/capture_policy.rs+++ b/crates/ai-memory-hooks/src/capture_policy.rs@@ -164,7 +164,9 @@ pub(crate) fn tool_observation_metadata(// ZCode tool payloads carry Claude Code's snake_case aliases// (`tool_name`, `tool_use_id`, `tool_input`) alongside the native// camelCase — all captured live (engine v0.16.5, #512).- AgentKind::ClaudeCode | AgentKind::CommandCode | AgentKind::Zcode => (+ // Native Codex 0.154 uses these same top-level fields, including+ // `tool_use_id` on both sides of a tool call.+ AgentKind::ClaudeCode | AgentKind::CommandCode | AgentKind::Codex | AgentKind::Zcode => (object.get("tool_name")?.as_str()?,object.get("tool_use_id").and_then(Value::as_str),),@@ -206,6 +208,7 @@ pub(crate) fn tool_observation_metadata(agent,AgentKind::ClaudeCode| AgentKind::CommandCode+ | AgentKind::Codex| AgentKind::Hermes| AgentKind::KiroCli| AgentKind::Pool@@ -262,6 +265,9 @@ pub(crate) fn tool_observation_outcome(agent: AgentKind, raw: &Value) -> ToolOut{ToolOutcome::Error}+ // Codex PostToolUse also fires for failed commands. Its native exec+ // response is output text, with no separate success/exit-code field;+ // neither the event nor arbitrary response JSON proves an outcome._ => ToolOutcome::Unknown,}}diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rsindex 9f0aeabc..571d4e91 100644--- a/crates/ai-memory-hooks/src/payload.rs+++ b/crates/ai-memory-hooks/src/payload.rs@@ -432,8 +432,9 @@ impl HookEnvelope {let agent = agent_from_payload(&raw).unwrap_or_else(|| query.agent.as_deref().map_or(AgentKind::Other, parse_agent));// OpenCode's plugin SDK sends `sessionID` (capital `ID`) on the- // tool.execute.*/session.* events; Claude Code uses `session_id`,- // Codex `sessionId`, and Antigravity CLI uses `conversationId`.+ // tool.execute.*/session.* events; Claude Code and native Codex use+ // `session_id`, older Codex bridges `sessionId`, and Antigravity CLI+ // uses `conversationId`.// JSON keys are case-sensitive, so all spellings must be listed// or tool events fail the router's "missing session_id" check.let body_session_id = extract_string(@@ -624,6 +625,7 @@ const fn closed_tool_agent(agent: AgentKind) -> bool {agent,AgentKind::ClaudeCode| AgentKind::CommandCode+ | AgentKind::Codex| AgentKind::OpenCode| AgentKind::Pi| AgentKind::AntigravityCli@@ -683,11 +685,16 @@ fn safe_tool_body(if metadata.tool_family == crate::capture_policy::ToolFamily::Unknown {return Some(summary);}- let result =+ let result = if agent == AgentKind::Codex {+ // Codex's native schema has one top-level JSON response.+ // Do not promote unrelated aliases or nested payloads to output.+ raw.get("tool_response").and_then(value_to_text)+ } else {extract_content(raw, &["tool_response", "tool_output", "output", "result"]).or_else(|| extract_content(raw, &["error"])).or_else(|| antigravity_edit_content(agent, raw))- .unwrap_or_else(|| "(no output captured)".into());+ }+ .unwrap_or_else(|| "(no output captured)".into());summary.push_str("\n---\n");summary.push_str(&result);Some(truncate_excerpt(&summary))@@ -2172,6 +2179,152 @@ mod tests {assert_eq!(env.body_excerpt.as_deref(), Some("MARKER_PROMPT_789"));}+ // Native fields and canonical tool names follow Codex rust-v0.154.0's+ // pre/post-tool-use schemas. `tool_response` accepts any JSON value.+ #[test]+ fn codex_native_tool_pairs_capture_bounded_output_and_stable_metadata() {+ for (tool, input, response, family, text) in [+ (+ "Bash",+ serde_json::json!({"command": "echo private-input"}),+ serde_json::json!("native stdout"),+ "non-file",+ "native stdout",+ ),+ (+ "apply_patch",+ serde_json::json!({"command": "*** Begin Patch\n*** Add File: private-input\n+text\n*** End Patch"}),+ serde_json::json!("Success. Updated the following files:\nA public.txt"),+ "file",+ "public.txt",+ ),+ (+ "Bash",+ serde_json::json!({"command": "private-input"}),+ serde_json::json!({"stdout": "structured stdout", "exit_code": 1}),+ "non-file",+ "structured stdout",+ ),+ (+ "Bash",+ serde_json::json!({"command": "private-input"}),+ serde_json::json!([{"type": "text", "text": "block output"}]),+ "non-file",+ "block output",+ ),+ ] {+ for event in ["PreToolUse", "PostToolUse"] {+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: event.into(),+ agent: Some("codex".into()),+ ..Default::default()+ },+ serde_json::json!({+ "session_id": "native-codex", "cwd": "/repo", "turn_id": "turn-1",+ "hook_event_name": event, "permission_mode": "bypassPermissions",+ "tool_name": tool, "tool_input": input, "tool_response": response,+ "tool_use_id": "call-native-1",+ }),+ );+ assert_eq!(env.agent, AgentKind::Codex);+ assert_eq!(env.session_id.as_deref(), Some("native-codex"));+ assert_eq!(env.cwd.as_deref(), Some("/repo"));+ assert_eq!(env.title_hint, Some(format!("tool {family}")));+ let body = env.body_excerpt.unwrap();+ assert!(body.starts_with(&format!(+ "tool_family: {family}\ntool_call_id: call-native-1"+ )));+ assert!(!body.contains("private-input"));+ if event == "PostToolUse" {+ assert!(body.contains("outcome: unknown"));+ assert!(body.contains(text));+ } else {+ assert!(!body.contains(text));+ assert!(!body.contains("outcome:"));+ }+ }+ }+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "PostToolUse".into(),+ agent: Some("codex".into()),+ ..Default::default()+ },+ serde_json::json!({"tool_name": "Bash", "tool_use_id": "call-long", "tool_response": {"content": [{"type": "text", "text": "é".repeat(2_000)}]}}),+ );+ let body = env.body_excerpt.unwrap();+ assert!(body.contains('é'));+ assert!(body.len() <= TOOL_EXCERPT_MAX_BYTES);+ }++ #[test]+ fn codex_native_unknown_and_malformed_tools_do_not_promote_unproven_content() {+ for raw in [+ serde_json::json!(null),+ serde_json::json!([]),+ serde_json::json!(42),+ serde_json::json!({"tool_name": 7, "tool_input": {}, "tool_response": "UNPROVEN"}),+ serde_json::json!({"payload": {"tool_name": "Bash", "tool_input": {}, "tool_response": "UNPROVEN"}}),+ serde_json::json!({"tool": "Bash", "args": {}, "output": "UNPROVEN"}),+ ] {+ for event in ["PreToolUse", "PostToolUse"] {+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: event.into(),+ agent: Some("codex".into()),+ ..Default::default()+ },+ raw.clone(),+ );+ assert!(env.title_hint.is_none());+ assert!(env.body_excerpt.is_none());+ }+ }+ for tool in ["mcp__fs__read", "update_plan", "UNPROVEN_TOOL"] {+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "PostToolUse".into(),+ agent: Some("codex".into()),+ ..Default::default()+ },+ serde_json::json!({"tool_name": tool, "tool_input": {"path": "UNPROVEN"}, "tool_use_id": "call-unknown", "tool_response": {"content": [{"type": "text", "text": "UNPROVEN"}], "structuredContent": {"text": "UNPROVEN"}, "isError": false}}),+ );+ assert_eq!(+ env.body_excerpt.as_deref(),+ Some("tool_family: unknown\ntool_call_id: call-unknown\noutcome: unknown")+ );+ }+ for response in [+ serde_json::json!(null),+ serde_json::json!({}),+ serde_json::json!([]),+ ] {+ let raw = serde_json::json!({"tool_name": "Bash", "tool_use_id": "invalid\nUNPROVEN", "tool_response": response, "output": "UNPROVEN", "error": "UNPROVEN", "payload": {"tool_response": "UNPROVEN"}});+ let pre = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "PreToolUse".into(),+ agent: Some("codex".into()),+ ..Default::default()+ },+ raw.clone(),+ );+ assert!(pre.body_excerpt.is_none(), "missing native input");+ let post = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "PostToolUse".into(),+ agent: Some("codex".into()),+ ..Default::default()+ },+ raw,+ );+ assert_eq!(+ post.body_excerpt.as_deref(),+ Some("tool_family: non-file\noutcome: unknown\n---\n(no output captured)")+ );+ }+ }+#[test]fn closed_tool_summaries_keep_only_safe_metadata_and_cap_total_body() {let fixtures = [@@ -2305,7 +2458,7 @@ mod tests {let unsupported = HookEnvelope::from_query_and_body(HookQuery {event: "pre-tool-use".into(),- agent: Some("codex".into()),+ agent: Some("other".into()),..Default::default()},serde_json::json!({"tool_name":"Bash","tool_input":{"command":"private"}}),diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex 2ed4b477..ab903c97 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -11676,6 +11676,171 @@ mod tests {assert_eq!(inspect_capture_envelope(env).unwrap().raw, raw);}+ #[tokio::test]+ async fn codex_native_tools_are_sanitized_scoped_and_idempotent_until_session_end() {+ let tmp = TempDir::new().unwrap();+ let mut state = make_state(&tmp).await;+ state.sanitizer = Sanitizer::new(&SanitizeConfig {+ extra_patterns: vec!["PRIVATE_CONTENT".into()],+ allowlist: Vec::new(),+ })+ .unwrap();+ let mut projects = Vec::new();+ for project in ["codex-a", "codex-b"] {+ let sid = SessionId::new();+ let envelope = |event: &str| {+ HookEnvelope::from_query_and_body(+ HookQuery {+ event: event.into(),+ agent: Some("codex".into()),+ workspace: Some("default".into()),+ project: Some(project.into()),+ ingest_key: Some(format!("native-{event}")),+ ..Default::default()+ },+ serde_json::json!({+ "session_id": sid.to_string(), "cwd": "/repo", "turn_id": "turn-1",+ "hook_event_name": event, "tool_name": "Bash",+ "tool_use_id": "call-native-1", "tool_input": {"command": "PRIVATE_INPUT"},+ "tool_response": {"content": [{"type": "text", "text": format!("{project}: PRIVATE_CONTENT")} ]},+ }),+ )+ };+ for event in [+ "SessionStart",+ "PreToolUse",+ "PostToolUse",+ "PreToolUse",+ "PostToolUse",+ "Stop",+ ] {+ process(&state, envelope(event), None, Vec::new())+ .await+ .unwrap();+ }+ let (ws, proj) = state+ .reader+ .session_project_ids(sid)+ .await+ .unwrap()+ .unwrap();+ assert!(+ !projects.contains(&proj),+ "the same ingest keys must work in both projects"+ );+ projects.push(proj);+ let observations = state.reader.observations_for_session(sid).await.unwrap();+ assert_eq!(+ observations.len(),+ 4,+ "tool retries must not append observations"+ );+ assert!(+ observations+ .iter()+ .all(|o| o.workspace_id == ws && o.project_id == proj)+ );+ assert!(observations.iter().all(|o| !o.body.contains("PRIVATE_")));+ let pre = observations+ .iter()+ .find(|o| o.kind == ObservationKind::PreToolUse)+ .unwrap();+ assert_eq!(+ pre.body,+ "tool_family: non-file\ntool_call_id: call-native-1"+ );+ let post = observations+ .iter()+ .find(|o| o.kind == ObservationKind::PostToolUse)+ .unwrap();+ assert_eq!(+ post.body,+ format!(+ "tool_family: non-file\ntool_call_id: call-native-1\noutcome: unknown\n---\n{project}: [REDACTED]"+ )+ );+ assert!(+ state+ .reader+ .open_session_for_scope_agent_by_id(+ ws,+ proj,+ AgentKind::Codex,+ ai_memory_core::OwnerFilter::Any,+ sid+ )+ .await+ .unwrap()+ .is_some(),+ "Stop must leave the Codex session open"+ );+ assert!(+ state+ .reader+ .latest_open_handoff(ws, proj, None, ai_memory_core::OwnerFilter::Any)+ .await+ .unwrap()+ .is_none()+ );++ process(&state, envelope("SessionEnd"), None, Vec::new())+ .await+ .unwrap();+ assert_eq!(+ state+ .reader+ .session_end_disposition(sid, ws, proj, AgentKind::Codex)+ .await+ .unwrap(),+ ai_memory_store::SessionEndDisposition::AlreadyEnded+ );+ assert!(+ state+ .reader+ .latest_open_handoff(ws, proj, None, ai_memory_core::OwnerFilter::Any)+ .await+ .unwrap()+ .is_some()+ );+ }+ }++ #[test]+ fn codex_native_patch_capture_backstop_discards_unproven_output() {+ for protocol in [+ capture_protocol("keep", "active", "file", 1, "extracted"),+ serde_json::json!({"version": 99}),+ ] {+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "PostToolUse".into(),+ agent: Some("codex".into()),+ ..Default::default()+ },+ serde_json::json!({+ "session_id": "native-codex", "cwd": "/repo", "tool_name": "apply_patch",+ "tool_input": {"command": "*** Begin Patch\n*** Add File: secret/private.txt\n+PRIVATE_CONTENT\n*** End Patch"},+ "tool_use_id": "call-patch", "tool_response": "PRIVATE_CONTENT",+ "_ai_memory_capture": protocol,+ }),+ );+ assert!(+ env.body_excerpt+ .as_ref()+ .unwrap()+ .contains("PRIVATE_CONTENT")+ );+ let safe = inspect_capture_envelope(env).unwrap();+ assert_eq!(safe.agent, AgentKind::Codex);+ assert_eq!(+ safe.body_excerpt.as_deref(),+ Some("tool_family: file\ntool_call_id: call-patch\noutcome: unknown")+ );+ assert!(!safe.raw.to_string().contains("PRIVATE_CONTENT"));+ assert!(!safe.raw.to_string().contains("private.txt"));+ }+ }+#[test]fn capture_protocol_keep_file_mismatch_becomes_metadata_only() {let env = HookEnvelope::from_query_and_body(diff --git a/docs/install.md b/docs/install.mdindex a5c1af96..911a3983 100644--- a/docs/install.md+++ b/docs/install.md@@ -743,10 +743,28 @@ docker run --rm akitaonrails/ai-memory:latest \--auth-token "$TOKEN"```-Codex still does not expose a reliable true session-end hook. Its `Stop` hook is-captured as a turn/stop observation only; ai-memory does **not** treat it as-SessionEnd. When you need the final session summary, handoff, and-auto-improvement eligibility for the current project, run:+Native Codex tool hooks use top-level `tool_name`, `tool_input`, `tool_response`,+and `tool_use_id` fields (verified against CLI 0.154.0). ai-memory records the+tool family and call ID on `PreToolUse` and `PostToolUse`; recognized tools such+as `Bash` and `apply_patch` also retain a sanitized response excerpt on+`PostToolUse`, capped at 2 KB including metadata. Structured JSON responses are+flattened using the same bounded excerpt path. Inputs are not copied into+observations, and unknown tools (including unrecognized MCP names) retain only+metadata. `PostToolUse` alone does not prove success, so Codex outcomes remain+`unknown`.++Capture exclusions still run before native spooling. Codex's `apply_patch`+passes patch text in `tool_input.command`, which does not provide direct file+paths to the capture policy. With active `ignore_paths`, those events retain+only metadata; ai-memory does not parse patch or shell text to infer paths.+Tool events are delivered at the normal 32-event catch-up threshold or a+lifecycle drain boundary, so a small active turn may still have queued events.++Codex CLI 0.145.0 and later expose a native `SessionEnd` hook. `Stop` is captured+as a turn boundary and leaves the session open; a native `SessionEnd` triggers+the final summary, handoff, and auto-improvement eligibility. See the+[Codex hook lifecycle](https://learn.chatgpt.com/docs/hooks#sessionend) for when+Codex ends a session. For older clients or a missed session-end delivery, run:```bashai-memory finalize-session