Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs: clarify Codex shell hook payload (#974)

yubr-zzh691e3cc31701
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 53454e5e..c376849a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,13 +36,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
(`docs/lifecycle-ops.md#backup`) is unchanged. (#950)
### Fixed
-- Codex `exec_command` is now recognized as a shell tool by the capture
- policy, so `ignore_paths` and the invalid-marker fail-closed stripping
- apply to it. Previously, this Codex tool name bypassed the shell-command
- path inspection, allowing commands that name an ignored path to be
- captured. String and argv `cmd` forms, relative paths under `workdir`,
- and malformed commands under an invalid marker now follow the existing
- shell policy. (#974)
- The `/web` page view keeps a leading H1 that is not the page title. It
dropped the body's first H1 whatever it said, as a duplicate of the title
in the header, but a frontmatter `title:` outranks the H1 and a setext H1
diff --git a/crates/ai-memory-hooks/src/capture_policy.rs b/crates/ai-memory-hooks/src/capture_policy.rs
index 4a190198..c92f98b0 100644
--- a/crates/ai-memory-hooks/src/capture_policy.rs
+++ b/crates/ai-memory-hooks/src/capture_policy.rs
@@ -795,7 +795,7 @@ fn family(name: &str) -> ToolFamily {
"search" | "grep" | "glob" | "find" | "list" | "ls" | "list_files" | "read_dir"
| "list_dir" | "grep_search" | "search_files" => ToolFamily::SearchList,
"bash" | "shell" | "shell_command" | "exec" | "execute" | "run_command" | "web_search"
- | "terminal" | "execute_bash" | "execute_cmd" | "exec_command" => ToolFamily::NonFile,
+ | "terminal" | "execute_bash" | "execute_cmd" => ToolFamily::NonFile,
_ => ToolFamily::Unknown,
}
}
@@ -1872,99 +1872,21 @@ mod tests {
),
] {
let decision = policy.inspect(agent, &raw, "/repo");
- assert_eq!(
- decision.protocol().tool_family(),
- ToolFamily::NonFile,
- "raw: {raw}",
- );
- assert_eq!(
- decision.protocol().disposition(),
- CaptureDisposition::Drop,
- "raw: {raw}",
- );
+ if decision.protocol().tool_family() == ToolFamily::NonFile {
+ assert_eq!(
+ decision.protocol().disposition(),
+ CaptureDisposition::Drop,
+ "raw: {raw}"
+ );
+ } else {
+ // `exec_command` is not a recognized shell tool name; it keeps
+ // today's unknown-tool behavior rather than guessing.
+ assert_eq!(raw["tool_name"], "exec_command", "raw: {raw}");
+ assert_eq!(decision.protocol().tool_family(), ToolFamily::Unknown);
+ }
}
}
- #[test]
- fn codex_exec_command_honors_ignored_paths() {
- let policy = shell_policy();
- // Regression for #974: Codex `exec_command` previously fell through
- // to `ToolFamily::Unknown`, so the ignore_paths gate never matched
- // the command line and the event kept flowing to the server. A
- // command line that names an ignored path must be dropped locally,
- // exactly like Claude `Bash` and Codex `shell`.
- let ignored = json!({
- "tool_name": "exec_command",
- "tool_input": {"cmd": "cat docs/adr/x.md"},
- });
- assert_eq!(
- policy
- .inspect(AgentKind::Codex, &ignored, "/repo")
- .protocol()
- .disposition(),
- CaptureDisposition::Drop,
- "exec_command on an ignored path should be dropped",
- );
- // Legitimate control: the same shape against a path that is not
- // ignored must still be captured, so the privacy gate does not
- // become a blanket blackout for shell tools we now classify as
- // recognized.
- let allowed = json!({
- "tool_name": "exec_command",
- "tool_input": {"cmd": "cat src/lib.rs"},
- });
- assert_eq!(
- policy
- .inspect(AgentKind::Codex, &allowed, "/repo")
- .protocol()
- .disposition(),
- CaptureDisposition::Keep,
- "exec_command on an allowed path should still be captured",
- );
- }
-
- #[test]
- fn codex_exec_command_array_form_honors_ignored_paths() {
- let policy = shell_policy();
- // Codex often wraps scripts as `["bash", "-lc", "..."]`; the argv
- // form must be parsed the same way `shell` already is (#974).
- let argv = json!({
- "tool_name": "exec_command",
- "tool_input": {"cmd": ["bash", "-lc", "cat docs/adr/x.md"]},
- });
- assert_eq!(
- policy
- .inspect(AgentKind::Codex, &argv, "/repo")
- .protocol()
- .disposition(),
- CaptureDisposition::Drop,
- "exec_command argv form on an ignored path should be dropped",
- );
- }
-
- #[test]
- fn codex_exec_command_with_workdir_resolves_relative_ignored_paths() {
- let policy = shell_policy();
- // Codex `exec_command` carries its own `workdir`; relative
- // arguments must be anchored to it, like OpenClaw `exec` and the
- // other NonFile tools that already honour `workdir`.
- let payload = json!({
- "tool_name": "exec_command",
- "tool_input": {
- "cmd": "cat 0001.md",
- "workdir": "docs/adr",
- },
- });
- assert_eq!(
- policy
- .inspect(AgentKind::Codex, &payload, "/repo")
- .protocol()
- .disposition(),
- CaptureDisposition::Drop,
- "exec_command with workdir + relative ignored path should be dropped",
- );
- }
-
#[test]
fn shell_matching_is_off_when_inactive_and_fails_closed_when_invalid_or_over_budget() {
let raw = bash("cat docs/adr/x.md");
@@ -2116,18 +2038,6 @@ mod tests {
AgentKind::ClaudeCode,
json!({"tool_name":"Bash","tool_input":{"cmd_line":"cat secret/x.md"}}),
),
- (
- AgentKind::Codex,
- json!({"tool_name":"exec_command","tool_input":{"cmd":7}}),
- ),
- (
- AgentKind::Codex,
- json!({"tool_name":"exec_command","tool_input":{"cmd":["cat", 7]}}),
- ),
- (
- AgentKind::Codex,
- json!({"tool_name":"exec_command","tool_input":{}}),
- ),
] {
let decision = policy.inspect(agent, &payload, "/repo");
assert_eq!(
@@ -2138,36 +2048,6 @@ mod tests {
}
}
- #[test]
- fn invalid_marker_does_not_leak_codex_exec_command_body() {
- // Security-boundary assertion for #974: even when a Codex
- // `exec_command` payload cannot be parsed into a command line, the
- // metadata-only body must never carry the raw argument. The fixed
- // key set in `metadata_only_body` (session_id, cwd, tool_family,
- // tool_name, tool_call_id, _ai_memory_capture) is the contract; if a
- // future refactor widens it for shell tools, this test bites.
- let policy = CapturePolicy::resolve(CaptureSource::Invalid, "/repo", None);
- for payload in [
- json!({"tool_name": "exec_command", "tool_input": {"cmd": 7}}),
- json!({"tool_name": "exec_command", "tool_input": {"cmd": ["cat", 7]}}),
- json!({"tool_name": "exec_command", "tool_input": {}}),
- json!({"tool_name": "exec_command", "tool_input": {"cmd": "cat secret/x.md"}}),
- ] {
- let decision = policy.inspect(AgentKind::Codex, &payload, "/repo");
- assert_eq!(
- decision.protocol().disposition(),
- CaptureDisposition::MetadataOnly,
- "exec_command under an invalid marker must be metadata-only: {payload}",
- );
- let body =
- serde_json::to_string(&metadata_only_body(Some("s"), Some("/repo"), &decision))
- .unwrap();
- assert!(!body.contains("cat"), "command body leaked: {body}");
- assert!(!body.contains("secret"), "path-like body leaked: {body}");
- assert!(!body.contains("\"cmd\""), "raw cmd key leaked: {body}");
- }
- }
-
#[test]
fn long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget() {
let ignore_paths = (0..40).map(|i| format!("/repo/private{i}/**")).collect();
diff --git a/docs/marker-file.md b/docs/marker-file.md
index a9a57c87..2459102f 100644
--- a/docs/marker-file.md
+++ b/docs/marker-file.md
@@ -235,10 +235,11 @@ That form contains only bounded routing/tool/decision metadata, never paths,
patterns, arguments, output, errors, titles, or nested payload. Unknown tools
retain current behavior.
-Recognized shell tools (`Bash`, `shell`, `exec`, `exec_command`, `execute_bash`,
-`terminal`, …) have no path field, so the command line is split into words
-lexically, the way a POSIX shell quotes and separates them, without expanding
-or running anything.
+Recognized shell tools (`Bash`, `shell`, `exec`, `execute_bash`, `terminal`, …)
+have no path field, so the command line is split into words lexically, the way
+a POSIX shell quotes and separates them, without expanding or running anything.
+Codex shell calls, including its `exec_command` path, reach hooks as `Bash`
+with the command in `tool_input.command`.
A command given as an argument vector keeps each element as one word (a path
with spaces stays whole, up to 256 characters) and also splits each element on
its own, so a `bash -lc "<script>"` script is read like any command line. Each
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index ee869d9b..b3fdf56a 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -40,7 +40,7 @@ boundary not yet built.
| 10 | Destructive-op live-process refusal + confirm flags (invariant #9) | `ai-memory-cli/src/commands/process_guard.rs` `sibling_processes` + confirm flags in `reset`/`restore`/`reindex`/`uninstall --purge-data`/`purge_project` | `admin_purge.rs` confirm→400; `removal.rs` — injected live-sibling makes each destructive command bail before touching the data dir | STRONG |
| 10b | Session purge is scope+owner-bound (no cross-session/project over-delete) | `ai-memory-store/src/ops.rs` `purge_session` — selection scoped to `(workspace_id, project_id)` and keyed on this session's own `summary_page_id` **or** `path='sessions/<sid>.md'` + `json_extract(frontmatter_json,'$.session_id')=<sid>` (frontmatter owner, not the recursive latest-chain); `in_scope==0 → NotFound` fail-closed; whole op in one transaction | `ops.rs` `purge_session_leaves_a_sibling_session_in_the_same_project_intact`, `…refuses_a_session_from_another_project_and_deletes_nothing`, `…refuses_a_session_from_another_workspace`, `…does_not_delete_an_identically_pathed_page_in_another_project`, `…removes_older_summary_versions_without_deleting_prior_manual_page` (#862) | STRONG |
| 11a | Hook backpressure (202/429) + bounded fan-out (invariant #5) | `ai-memory-hooks/src/router.rs` semaphore→429, 202 immediately, `MAX_HOOK_BATCH_ITEMS`, bounded LRU limiter | `router.rs` `handle_hook_returns_429_when_ingest_saturated`, `ingest_rate_limiter_is_bounded` | STRONG |
-| 11b | Capture exclusions drop before storage | `ai-memory-hooks` `capture_policy.rs` `inspect`→`Drop` (before semaphore/spawn), including shell commands whose arguments name an ignored path (`match_command`; argv elements matched whole and tokenized); Codex `exec_command` (`tool_input.cmd`, string or string array, `workdir` relative-anchored) is recognized the same way as Codex `shell` so the gate cannot be bypassed by adapter/tool-name drift (#974); an invalid marker makes file and shell calls metadata-only, and the server admits a metadata-only shell body only under an invalid marker (`router.rs` `metadata_protocol_is_legal`); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`) | `capture_policy.rs` per-agent `…honors_exclusions` tests, `shell_fixture_vectors` (shared `capture-policy.json` `shell` drop/keep vectors: tool aliases incl. OpenClaw/Devin `exec`, `workdir`, glob directories, Windows paths), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors); `shell_matching_is_off_when_inactive_and_fails_closed_when_invalid_or_over_budget`; `capture_policy.rs` `codex_exec_command_honors_ignored_paths`, `codex_exec_command_array_form_honors_ignored_paths`, `codex_exec_command_with_workdir_resolves_relative_ignored_paths` (#974); `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`, `capture_protocol_invalid_marker_shell_is_metadata_only` (active metadata-only shell refused, older client's invalid-marker keep stripped, commandless control kept), `capture_protocol_unparseable_marker_strips_shell_events` (server fallback for an unparseable marker), `capture_protocol_invalid_shell_metadata_claim_must_be_canonical` (a stripped shell claim with a path count or non-`extracted` state is refused); `capture_policy.rs` `invalid_marker_strips_shell_calls_with_unparseable_commands` (now incl. Codex `exec_command` `cmd` int / mixed-argv / missing), `invalid_marker_does_not_leak_codex_exec_command_body` (security-boundary body-leak assertion, #974), `long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget`; `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`; `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job) | STRONG |
+| 11b | Capture exclusions drop before storage | `ai-memory-hooks` `capture_policy.rs` `inspect`→`Drop` (before semaphore/spawn), including shell commands whose arguments name an ignored path (`match_command`; argv elements matched whole and tokenized); an invalid marker makes file and shell calls metadata-only, and the server admits a metadata-only shell body only under an invalid marker (`router.rs` `metadata_protocol_is_legal`); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`) | `capture_policy.rs` per-agent `…honors_exclusions` tests, `shell_fixture_vectors` (shared `capture-policy.json` `shell` drop/keep vectors: tool aliases incl. OpenClaw/Devin `exec`, `workdir`, glob directories, Windows paths), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors); `shell_matching_is_off_when_inactive_and_fails_closed_when_invalid_or_over_budget`; `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`, `capture_protocol_invalid_marker_shell_is_metadata_only` (active metadata-only shell refused, older client's invalid-marker keep stripped, commandless control kept), `capture_protocol_unparseable_marker_strips_shell_events` (server fallback for an unparseable marker), `capture_protocol_invalid_shell_metadata_claim_must_be_canonical` (a stripped shell claim with a path count or non-`extracted` state is refused); `capture_policy.rs` `invalid_marker_strips_shell_calls_with_unparseable_commands`, `long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget`; `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`; `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job) | STRONG |
| 11c | Capture hook ≤200ms budget (invariant #5) | `hooks/_lib.sh` capture path `curl --max-time 0.2` (context-fetch 1.0s and background drain 2.0s are separate, larger-budget paths) | none (shell-script timeout; hard to unit-test) — watch on any capture-path change | WATCH |
| 12 | Network/auth posture | `config.rs` loopback `DEFAULT_BIND`; `serve.rs` `validate_http_exposure`, `require_allowed_host`; `auth.rs` `require_bearer` | `serve.rs` host-guard (missing→400 / forged→403), non-loopback-requires-token; `auth.rs` wrong-token 401 | STRONG |
| 13 | Managed-run transcript attribution (concurrent launches in one checkout, invariant #16) | `ai-memory-store/src/workstream.rs` `link_native_session` stamps `native_session_linked_at` on its own run only, both `finish` updates drop the stamp when the session changes, `run_status` reports it; `ai-memory-cli/src/commands/run.rs` `resolve_native_session_after_run` takes a linked session only when `ai-memory-workstream` `native_session_in_checkout` holds it for this checkout (OpenCode by recorded directory), and never falls back to a link it set aside | `multi_session.rs` `a_session_linked_by_one_managed_run_is_not_another_runs`; `run.rs` `a_session_linked_during_the_run_wins_over_discovery` (concurrent newer session, another checkout's link refused, no fallback to it, unlinked control); `transcript.rs` `native_session_in_checkout_checks_the_opencode_directory`; `store/src/lib.rs` `managed_run_status_reports_a_link_made_during_the_run` | PARTIAL: a run whose child links nothing still falls back to discovering the newest session in the checkout |