Skip to content

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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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:
```bash
ai-memory finalize-session