Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Wire envelope received on `POST /hook`.
use ai_memory_core::{
AgentKind, OBSERVATION_BODY_MAX_BYTES, ObservationKind, Sanitizer, TOOL_BODY_SEPARATOR,
TOOL_OUTCOME_LINE_PREFIX, truncate_utf8_bytes,
};
use serde::{Deserialize, Serialize};
use crate::capture_policy::{
ToolFamily, ToolObservationMetadata, tool_observation_metadata, tool_observation_outcome,
};
/// Durable excerpt ceiling for user prompts. Prompts retain more working
/// context than tool/notification summaries while remaining bounded.
pub const USER_PROMPT_EXCERPT_MAX_BYTES: usize = OBSERVATION_BODY_MAX_BYTES;
/// Durable excerpt ceiling for post-compaction summaries.
pub const POST_COMPACTION_EXCERPT_MAX_BYTES: usize = OBSERVATION_BODY_MAX_BYTES;
/// Durable excerpt ceiling for notifications.
pub const NOTIFICATION_EXCERPT_MAX_BYTES: usize = 2_000;
/// Durable excerpt ceiling for tool I/O summaries and short excerpts
/// (tool results, extension bodies, Stop assistant excerpts).
pub const TOOL_EXCERPT_MAX_BYTES: usize = 2_000;
/// Durable body ceiling the ingest funnel applies to an event's excerpt
/// **after** the sanitizer has scrubbed the full text.
///
/// The cap used to run inside excerpt extraction, before the sanitizer ever
/// saw the text, so a secret straddling the cutoff was cut in half and the
/// surviving prefix too short to match a pattern — stored unredacted (#1114),
/// the body-side twin of the #980 title-hint leak. Extraction now returns the
/// uncapped text and the router applies this cap to the scrubbed output,
/// mirroring `ai_memory_core::sanitize::Sanitized::new`.
#[must_use]
pub fn durable_body_cap(event: HookEvent) -> usize {
match event {
HookEvent::UserPrompt => USER_PROMPT_EXCERPT_MAX_BYTES,
HookEvent::PostCompaction => POST_COMPACTION_EXCERPT_MAX_BYTES,
HookEvent::Notification
| HookEvent::PreToolUse
| HookEvent::PostToolUse
| HookEvent::Stop
| HookEvent::Other => TOOL_EXCERPT_MAX_BYTES,
_ => OBSERVATION_BODY_MAX_BYTES,
}
}
/// Query-string parameters on `POST /hook`.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct HookQuery {
/// Lifecycle event identifier (kebab-case or snake_case).
pub event: String,
/// Agent CLI identifier (`claude-code`, `codex`, `cursor`, etc.).
pub agent: Option<String>,
/// Working directory of the agent at the time the hook fired.
/// Most agents put this in the JSON body, but accepting it on the
/// query string too lets `curl` / tests / non-Claude bridges
/// populate it without constructing a body envelope.
pub cwd: Option<String>,
/// Workspace name override (typically declared by the agent's
/// host-side hook via a `.ai-memory.toml` walk-up). When `None`
/// the server falls back to `DEFAULT_WORKSPACE_NAME`.
pub workspace: Option<String>,
/// Project name override (same source as `workspace`). When
/// `None` the server falls back to `basename(cwd)`.
pub project: Option<String>,
/// Session identifier supplied by a host-side bridge when the agent's
/// native hook payload does not include one. Body values still win.
pub session_id: Option<String>,
/// Optional project derivation strategy from `.ai-memory.toml`.
/// `repo-root` makes the server derive project identity from the
/// main git repository root instead of `basename(cwd)`.
pub project_strategy: Option<String>,
/// Optional third-party extension namespace. When present, ai-memory
/// preserves a validated source event name without expanding the
/// closed core event vocabulary.
pub extension: Option<String>,
/// Optional explicit source event name for extension vocabularies.
/// When omitted and `extension` is present, unknown `event` values
/// are preserved as the source event.
pub source_event: Option<String>,
/// Per-project opt-in for `drop_subagent_captures`, forwarded by the
/// host-side hook from a project's `.ai-memory.toml`. A truthy value
/// (`1`/`true`/…) makes the server accept-but-drop this project's subagent
/// captures; absent/falsy leaves them stored. Scoping the drop to the
/// project that asked for it avoids a server-global switch that would shed
/// subagent captures for every project on a shared instance.
pub drop_subagent: Option<String>,
/// Per-repo opt-in for `[recall] default_global`, forwarded by the
/// host-side hook from a project's `.ai-memory.toml`. A truthy value makes
/// the server publish `default_global` on this actor's `ActiveProject`, so
/// a default-scoped `memory_query` / `memory_recent` searches every project
/// instead of just the current one — the meta-repo case (e.g. `ai-memory`
/// needing to see `ai-memory-ops` / `infra` without passing `global=true`).
pub default_global: Option<String>,
/// Invocation-scoped `ai-memory run` lease. Absent for every direct
/// harness launch, preserving legacy capture and handoff behavior.
pub managed_run: Option<String>,
/// Client-side opt-in for assistant/Stop capture, baked onto the native
/// `stop` hook command by `install-hooks --capture-assistant`. A truthy
/// value tells the server the client deliberately attached a sanitized
/// `_ai_memory_assistant` excerpt; the server still gates on its own
/// `capture_assistant` config before persisting it (#196).
pub capture_assistant: Option<String>,
/// Client idempotency key, minted once when the event is spooled and
/// re-sent verbatim on every retry of that entry. Lets the server drop
/// a replay whose previous delivery succeeded but whose response was
/// lost (the conservative-retry duplication vector). Absent on older
/// clients; older servers ignore it — both directions keep today's
/// behavior.
pub ingest_key: Option<String>,
/// Explicit root-only recovery propagation from `finalize-session --all-owners`.
pub all_owners: Option<String>,
/// Provenance of the `project` override: `marker` when a
/// `.ai-memory.toml` named it, `repo-root` when the host hook derived it
/// from the enclosing checkout. Absent on older clients (#394).
pub project_src: Option<String>,
/// Repository identity the client resolved for this checkout (#708):
/// an explicit marker `identity`, or a normalised git remote. Paired
/// with `identity_src`. Absent on older clients and for checkouts that
/// declare a `project`, which keep routing by name.
pub identity: Option<String>,
/// Which rung produced `identity`: `explicit` or `git_remote`. Anything
/// else, or a malformed identity, is ignored and the event routes by name.
pub identity_src: Option<String>,
/// An explicit marker `identity_style` (#1033). `path` names a
/// remote-backed project from its repository path without the host;
/// `host_path` preserves legacy naming. Omission uses the server default.
pub identity_style: Option<String>,
/// Compact JSON array of validated former project names from the local
/// marker. Accepted only with a full git-remote identity.
pub aliases: Option<String>,
}
/// Coalesced view of an incoming hook event after light parsing of the
/// body. We keep the original raw JSON around so consumers can extract
/// agent-specific fields they care about.
#[derive(Clone, Serialize)]
pub struct HookEnvelope {
/// Mapped lifecycle event.
pub event: HookEvent,
/// Agent CLI identifier.
pub agent: AgentKind,
/// Session identifier from the body, or from the query string when a
/// host-side bridge had to supply it. Required for everything except the
/// initial `SessionStart`.
pub session_id: Option<String>,
/// Current working directory at the time of the event.
pub cwd: Option<String>,
/// Workspace name override declared by the hook (via marker file
/// walk-up). Empty / `None` defers to `DEFAULT_WORKSPACE_NAME`.
pub workspace_override: Option<String>,
/// Project name override declared by the hook. Empty / `None`
/// defers to `basename(cwd)`.
pub project_override: Option<String>,
/// Project derivation strategy declared by the hook marker.
pub project_strategy: ProjectStrategy,
/// Where `project_override` came from. Always [`ProjectSource::Unspecified`]
/// when there is no override, so the two can never disagree (#394).
pub project_source: ProjectSource,
/// Repository identity from the client, already validated by
/// [`ai_memory_core::repository_identity::accept_wire_identity`]. `None`
/// routes by project name, as every event did before identities existed.
pub identity: Option<ai_memory_core::repository_identity::RepositoryIdentity>,
/// How a project this event creates is named; see
/// [`ai_memory_core::repository_identity::IdentityStyle`].
pub identity_style: ai_memory_core::repository_identity::IdentityStyle,
/// Validated, normalized former project names supplied by the local marker.
pub aliases: ai_memory_core::repository_identity::MarkerAliases,
/// Whether an alias query was malformed or lacked a git-remote identity.
pub aliases_invalid: bool,
/// Whether this project opted into `drop_subagent_captures` via its
/// `.ai-memory.toml` (forwarded as the `drop_subagent` query flag). The
/// ingest router consults this per-event so the drop is scoped to the
/// project that asked for it.
pub drop_subagent_requested: bool,
/// Whether this repo opted into `[recall] default_global` via its
/// `.ai-memory.toml` (forwarded as the `default_global` query flag). The
/// router publishes it on the actor's `ActiveProject` so default-scoped
/// read tools broaden to a global search.
pub recall_default_global_requested: bool,
/// Explicit cross-owner recovery request (never honored for ordinary hooks).
pub all_owners_requested: bool,
/// Invocation-scoped managed-run id forwarded by the host hook.
pub managed_run: Option<String>,
/// Optional third-party extension namespace.
pub extension: Option<String>,
/// Optional source event name from the extension vocabulary.
pub source_event: Option<String>,
/// Whether the client requested assistant/Stop capture for this event
/// (the `capture_assistant` query flag baked onto the native `stop`
/// command). The server still gates on its own `capture_assistant` config
/// before honoring it (#196).
pub capture_assistant_requested: bool,
/// Validated client idempotency key (`ingest_key` query param): 1–64
/// ASCII `[A-Za-z0-9_-]` chars, else dropped at parse time. `Some` makes
/// the ingest path dedup the event against a replayed delivery.
pub ingest_key: Option<String>,
/// Optional title hint extracted from the body.
pub title_hint: Option<String>,
/// Optional body excerpt extracted from the agent's raw payload.
pub body_excerpt: Option<String>,
/// Original event time (RFC 3339), when the client supplied one —
/// notably backfill replaying a transcript's own per-event timestamps.
/// Bounded and converted at the point of use via
/// [`HookEnvelope::occurred_at_micros`]; never trust it unchecked.
#[serde(default)]
pub occurred_at: Option<String>,
/// The closed-tool call's validated name and skill/subagent identifier,
/// read at parse time and written into the title and body only by
/// [`HookEnvelope::record_tool_name`] (`[ingest] record_tool_names`).
/// The metadata-only rebuilds clear it.
#[serde(skip)]
pub(crate) recorded_tool: Option<crate::capture_policy::RecordedToolName>,
/// The agent's raw JSON, kept for forensics.
pub raw: serde_json::Value,
}
/// Manual `Debug` that omits raw and derived hook content. A stray `?env` or
/// `%env` in a tracing span must not copy prompt or tool content into logs.
impl std::fmt::Debug for HookEnvelope {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("HookEnvelope")
.field("event", &self.event)
.field("agent", &self.agent)
.field("session_id", &self.session_id)
.field("cwd", &self.cwd)
.field("workspace_override", &self.workspace_override)
.field("project_override", &self.project_override)
.field("project_strategy", &self.project_strategy)
.field("identity", &self.identity)
.field("alias_count", &self.aliases.as_slice().len())
.field("aliases_invalid", &self.aliases_invalid)
.field("drop_subagent_requested", &self.drop_subagent_requested)
.field(
"recall_default_global_requested",
&self.recall_default_global_requested,
)
.field("managed_run", &self.managed_run)
.field(
"capture_assistant_requested",
&self.capture_assistant_requested,
)
.field("extension", &self.extension)
.field("source_event", &self.source_event)
// Client-controlled and only loosely shaped at this point (parsed
// and bounded later, in `occurred_at_micros`), so it is capped
// here rather than logged verbatim — a valid RFC 3339 timestamp
// is well under this, only a hostile payload would hit it.
.field(
"occurred_at",
&self
.occurred_at
.as_deref()
.map(|s| truncate_utf8_bytes(s, 64)),
)
.field(
"title_hint",
&self.title_hint.as_ref().map(|_| "<redacted>"),
)
.field(
"body_excerpt",
&self.body_excerpt.as_ref().map(|_| "<redacted>"),
)
.field("recorded_tool", &self.recorded_tool.is_some())
.field("raw", &"<redacted>")
.finish()
}
}
/// Keys by which agent harnesses tag a hook event as belonging to a SUBAGENT
/// (a nested/spawned agent session) rather than the top-level session. Grok
/// sets `subagentType` (on its tool-use events); Claude Code sets `agent_id`
/// on subagent events. `agent_type` alone is not a subagent marker: Claude
/// Code also sets it on top-level sessions launched with `--agent`. The set
/// is a union so one check covers every harness that signals subagent-ness;
/// a harness that does not signal it simply never matches.
const SUBAGENT_MARKER_KEYS: &[&str] = &["subagentType", "agent_id"];
/// True when the raw hook payload carries a non-empty subagent marker — i.e.
/// the event originates from a spawned subagent session. The ingest router
/// consults this to optionally drop subagent captures (the
/// `drop_subagent_captures` setting). Only top-level string keys are inspected.
pub(crate) fn body_is_subagent(raw: &serde_json::Value) -> bool {
SUBAGENT_MARKER_KEYS.iter().any(|key| {
raw.get(*key)
.and_then(serde_json::Value::as_str)
.is_some_and(|value| !value.trim().is_empty())
})
}
/// Truthy interpretation of a query-string flag (`1`/`true`/`yes`/`on`,
/// case-insensitive). Used for the per-project `drop_subagent` opt-in the
/// host-side hook forwards from a project's `.ai-memory.toml`.
pub(crate) fn query_flag_truthy(value: Option<&str>) -> bool {
matches!(
value.map(|v| v.trim().to_ascii_lowercase()).as_deref(),
Some("1" | "true" | "yes" | "on")
)
}
/// Whether a forwarded flag was explicitly turned off (`0` / `false` / `no` /
/// `off`, any case). An absent flag is not falsy: settings that default on,
/// like `[profile] contribute`, stay on unless a marker says otherwise.
pub(crate) fn query_flag_falsy(value: Option<&str>) -> bool {
matches!(
value.map(|v| v.trim().to_ascii_lowercase()).as_deref(),
Some("0" | "false" | "no" | "off")
)
}
pub(crate) fn marker_aliases_from_wire(
project: Option<&str>,
project_source: ProjectSource,
identity: Option<&ai_memory_core::repository_identity::RepositoryIdentity>,
raw: Option<&str>,
) -> Result<
ai_memory_core::repository_identity::MarkerAliases,
ai_memory_core::repository_identity::MarkerAliasError,
> {
let aliases = ai_memory_core::repository_identity::accept_wire_aliases(raw)?;
if raw.is_some()
&& (project.is_none_or(|project| project.trim().is_empty())
|| project_source != ProjectSource::Marker
|| !identity.is_some_and(|identity| {
identity.source == ai_memory_core::repository_identity::IdentitySource::GitRemote
}))
{
return Err(ai_memory_core::repository_identity::MarkerAliasError::InvalidWire);
}
Ok(aliases)
}
/// How the hook router derives a project name when no explicit
/// `project` override is present.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum ProjectStrategy {
/// Preserve v1 behavior: `project = basename(cwd)`.
#[default]
Basename,
/// Opt-in marker behavior: `project = basename(main git repo root)`.
RepoRoot,
}
impl ProjectStrategy {
/// Parse a query-string marker value. Unknown values are ignored so a
/// typo cannot route sessions into surprising new buckets.
#[must_use]
pub fn parse(value: Option<&str>) -> Self {
match value {
Some("repo-root" | "repo_root") => Self::RepoRoot,
_ => Self::Basename,
}
}
/// Stable cache-key representation.
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Basename => "basename",
Self::RepoRoot => "repo-root",
}
}
}
/// Where a `project` override on the wire came from.
///
/// The host-side hook sends `project=` for two very different reasons: a
/// `.ai-memory.toml` marker naming the project outright, and `repo-root`
/// derivation of the enclosing checkout's name (which must run host-side —
/// a containerized server cannot see the client's checkout). Both arrive as
/// the same query parameter, so before #394's `sticky` knob the router could
/// not honor one while overriding the other. This discriminator is that
/// missing signal: a marker is a deliberate rescope and always wins, while a
/// repo-root derivation is just "where the cwd happens to be" and may yield
/// to the session under `[routing] mid_session = "sticky"`.
///
/// Older clients omit the parameter entirely and parse as [`Self::Unspecified`],
/// which keeps their overrides authoritative — the pre-#394 behavior.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum ProjectSource {
/// No provenance declared: either no override at all, or a client too
/// old to tag one. Treated as authoritative, never as fell-through.
#[default]
Unspecified,
/// A `.ai-memory.toml` marker named this project explicitly.
Marker,
/// The host hook derived it from the enclosing git repo root under the
/// `repo-root` strategy.
RepoRoot,
}
impl ProjectSource {
/// Parse the `project_src` query value. Unknown values fall back to
/// [`Self::Unspecified`] so a typo can never downgrade an override into
/// something the session is allowed to overrule.
#[must_use]
pub fn parse(value: Option<&str>) -> Self {
match value {
Some("marker") => Self::Marker,
Some("repo-root" | "repo_root") => Self::RepoRoot,
_ => Self::Unspecified,
}
}
/// Stable wire/log representation.
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Unspecified => "unspecified",
Self::Marker => "marker",
Self::RepoRoot => "repo-root",
}
}
/// Whether an override from this source may yield to session-sticky
/// attribution. Only host-side repo-root derivation may: it carries no
/// operator intent, just the cwd's enclosing checkout.
#[must_use]
pub const fn yields_to_session(self) -> bool {
matches!(self, Self::RepoRoot)
}
}
/// Discriminator for the lifecycle event that triggered the hook.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum HookEvent {
/// New session started (capture cwd + model).
SessionStart,
/// User submitted a prompt.
UserPrompt,
/// Agent is about to call a tool.
PreToolUse,
/// Agent finished a tool call.
PostToolUse,
/// Compaction event (context window pressure).
PreCompact,
/// Post-compaction event (Devin-specific, after context compaction).
PostCompaction,
/// Agent emitted a notification.
Notification,
/// Agent finished its turn (interactive `/stop` or natural end).
Stop,
/// Session ended (final).
SessionEnd,
/// A subagent (nested/spawned child session) started.
SubagentStart,
/// A subagent finished.
SubagentStop,
/// Anything else.
Other,
}
impl HookEvent {
/// Parse a kebab- or snake-case event identifier into [`HookEvent`].
#[must_use]
pub fn parse(s: &str) -> Self {
match s {
"session-start" | "session_start" | "SessionStart" | "sessionStart" => {
Self::SessionStart
}
"user-prompt" | "user_prompt" | "user-prompt-submit" | "user_prompt_submit"
| "UserPromptSubmit" | "beforeSubmitPrompt" => Self::UserPrompt,
"pre-tool-use" | "pre_tool_use" | "PreToolUse" | "preToolUse" | "BeforeTool" => {
Self::PreToolUse
}
"post-tool-use" | "post_tool_use" | "PostToolUse" | "postToolUse"
| "postToolUseFailure" | "PostToolUseFailure" | "AfterTool" => Self::PostToolUse,
"pre-compact" | "pre_compact" | "PreCompact" | "preCompact" | "PreCompress" => {
Self::PreCompact
}
"post-compaction" | "post_compaction" | "PostCompaction" => Self::PostCompaction,
"notification" | "Notification" => Self::Notification,
"stop" | "Stop" => Self::Stop,
"session-end" | "session_end" | "SessionEnd" | "sessionEnd" => Self::SessionEnd,
"subagent-start" | "subagent_start" | "SubagentStart" | "subagentStart" => {
Self::SubagentStart
}
"subagent-stop" | "subagent_stop" | "SubagentStop" | "subagentStop"
| "subagent-end" | "SubagentEnd" => Self::SubagentStop,
_ => Self::Other,
}
}
/// Map to the storage-level [`ObservationKind`].
#[must_use]
pub const fn to_observation_kind(self) -> ObservationKind {
match self {
Self::SessionStart => ObservationKind::SessionStart,
Self::UserPrompt => ObservationKind::UserPrompt,
Self::PreToolUse => ObservationKind::PreToolUse,
Self::PostToolUse => ObservationKind::PostToolUse,
Self::PreCompact => ObservationKind::PreCompact,
Self::PostCompaction => ObservationKind::PostCompaction,
Self::Notification => ObservationKind::Notification,
Self::Stop => ObservationKind::Stop,
Self::SessionEnd => ObservationKind::SessionEnd,
// Subagent lifecycle events are normally dropped (drop_subagent_captures);
// bucket as Other for the flag-off path rather than growing ObservationKind.
Self::SubagentStart | Self::SubagentStop => ObservationKind::Other,
Self::Other => ObservationKind::Other,
}
}
}
/// Parse an agent identifier into [`AgentKind`]. Unknown values map to
/// [`AgentKind::Other`].
#[must_use]
pub fn parse_agent(s: &str) -> AgentKind {
AgentKind::from_wire(s)
}
/// The prompt text of a `UserPromptSubmit`-style payload, from the same keys
/// the router reads (`prompt`, `message`, `text`), flattened when a harness
/// sends content blocks.
#[must_use]
pub fn user_prompt_text(raw: &serde_json::Value) -> Option<String> {
extract_content(raw, &["prompt", "message", "text"])
}
/// The submitted user prompt for a specific harness.
///
/// Qwen's `prompt` field can also contain a continuation or hook-generated
/// prompt. Its optional `submitted_prompt` field is the provenance-bearing
/// value for an actual user submission, so Qwen must never fall back to the
/// generic field.
#[must_use]
pub fn user_prompt_text_for_agent(agent: AgentKind, raw: &serde_json::Value) -> Option<String> {
if agent == AgentKind::QwenCode {
extract_content(raw, &["submitted_prompt"])
} else {
user_prompt_text(raw)
}
}
/// Identify the harness from the payload itself when it carries an
/// unambiguous vendor marker, overriding the `?agent=` the hook command
/// declared.
///
/// The Cursor CLI also loads and runs the hook commands declared in Claude
/// Code's `~/.claude/settings.json` (its Claude Code config compatibility
/// path, alongside `~/.cursor/hooks.json`). Those commands were installed by
/// `install-hooks --agent claude-code`, so they hardcode
/// `--agent claude-code` — and a Cursor-driven session was therefore stored
/// with `agent_kind = claude-code`. The query string is the *installer's*
/// guess; `cursor_version` is stamped on every Cursor hook payload and never
/// appears in a Claude Code one, so the body is the stronger evidence.
///
/// Returns `None` when the payload carries no vendor marker, leaving the
/// declared `?agent=` untouched.
#[must_use]
pub fn agent_from_payload(raw: &serde_json::Value) -> Option<AgentKind> {
extract_string(raw, &["cursor_version"]).map(|_| AgentKind::Cursor)
}
/// Session and checkout fields extracted from the canonical hook payload shapes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HookPayloadContext {
/// Harness-native session identity.
pub session_id: Option<String>,
/// Current checkout directory.
pub cwd: Option<String>,
}
/// Extract the session and checkout exactly as [`HookEnvelope`] does.
#[must_use]
pub fn hook_payload_context(raw: &serde_json::Value) -> HookPayloadContext {
let session_id = extract_string(
raw,
&[
"session_id",
"sessionId",
"sessionID",
"session",
"conversationId",
"taskId",
],
)
.or_else(|| {
extract_string_path(
raw,
&[
&["info", "id"],
&["properties", "sessionID"],
&["properties", "info", "id"],
&["event", "properties", "sessionID"],
&["event", "properties", "info", "id"],
&["payload", "info", "id"],
&["payload", "properties", "sessionID"],
&["payload", "properties", "info", "id"],
],
)
});
let cwd = extract_string(raw, &["cwd", "current_dir", "working_dir", "directory"])
.or_else(|| {
extract_first_string_array_item(
raw,
&["workspacePaths", "workspace_roots", "workspaceRoots"],
)
})
.or_else(|| {
extract_string_path(
raw,
&[
&["path", "cwd"],
&["info", "directory"],
&["properties", "info", "directory"],
&["event", "properties", "info", "directory"],
&["payload", "path", "cwd"],
&["payload", "info", "directory"],
&["payload", "properties", "info", "directory"],
],
)
});
HookPayloadContext { session_id, cwd }
}
impl HookEnvelope {
/// Build an envelope from the parsed query + the body JSON. Performs
/// best-effort extraction of `session_id` / `cwd` / a body excerpt
/// from common shapes used by Claude Code, Codex, and OpenCode hook
/// payloads.
#[must_use]
pub fn from_query_and_body(query: HookQuery, raw: serde_json::Value) -> Self {
let event = HookEvent::parse(&query.event);
let agent = agent_from_payload(&raw)
.unwrap_or_else(|| query.agent.as_deref().map_or(AgentKind::Other, parse_agent));
let context = hook_payload_context(&raw);
let session_id = context
.session_id
.or_else(|| query.session_id.filter(|s| !s.is_empty()));
// Body cwd wins over the query-string fallback: the body is
// what agent CLIs natively send, so any query-string `cwd` is
// a bridge / test override that should defer to live data.
let cwd = context.cwd.or_else(|| query.cwd.filter(|s| !s.is_empty()));
let workspace_override = query.workspace.filter(|s| !s.is_empty());
let project_override = query.project.filter(|s| !s.is_empty());
let project_strategy = ProjectStrategy::parse(query.project_strategy.as_deref());
// Provenance describes an override, so it is meaningless without one.
// Pinning it to `Unspecified` here keeps every downstream check from
// having to re-test `project_override.is_some()` alongside it.
let project_source = if project_override.is_some() {
ProjectSource::parse(query.project_src.as_deref())
} else {
ProjectSource::Unspecified
};
let identity = match (query.identity.as_deref(), query.identity_src.as_deref()) {
(Some(identity), Some(source)) => {
ai_memory_core::repository_identity::accept_wire_identity(identity, source)
}
_ => None,
};
let identity_style = query
.identity_style
.as_deref()
.and_then(ai_memory_core::repository_identity::IdentityStyle::from_str_opt)
.unwrap_or_default();
let aliases = marker_aliases_from_wire(
project_override.as_deref(),
project_source,
identity.as_ref(),
query.aliases.as_deref(),
);
let aliases_invalid = aliases.is_err();
let aliases = if aliases_invalid {
ai_memory_core::repository_identity::MarkerAliases::default()
} else {
aliases.unwrap_or_default()
};
let drop_subagent_requested = query_flag_truthy(query.drop_subagent.as_deref());
let recall_default_global_requested = query_flag_truthy(query.default_global.as_deref());
let all_owners_requested = query_flag_truthy(query.all_owners.as_deref());
let managed_run = query.managed_run.filter(|value| !value.trim().is_empty());
let capture_assistant_requested = query_flag_truthy(query.capture_assistant.as_deref());
let extension = normalize_extension_name(query.extension.as_deref());
let source_event = extension.as_ref().and_then(|_| {
let raw_source = query
.source_event
.as_deref()
.or_else(|| (event == HookEvent::Other).then_some(query.event.as_str()))?;
normalize_source_event(raw_source)
});
let extension = if source_event.is_some() {
extension
} else {
None
};
// Antigravity step output is read from `output.txt` by the client-side
// hook (`ai-memory hook`), on the machine that ran the tool. The server
// must never open a path a hook payload names: `artifactDirectoryPath`
// and `transcriptPath` are caller-controlled, so reading them here would
// turn any capture credential into a read of the server's own disk.
let tool_metadata = tool_observation_metadata(agent, &raw, event == HookEvent::PreToolUse);
let closed_tool_event = matches!(event, HookEvent::PreToolUse | HookEvent::PostToolUse)
&& closed_tool_agent(agent);
let recorded_tool = if closed_tool_event && tool_metadata.is_some() {
crate::capture_policy::recorded_tool_name(agent, &raw)
} else {
None
};
let title_hint = if closed_tool_event {
tool_metadata.as_ref().map(safe_tool_title).or_else(|| {
(event == HookEvent::PostToolUse && agent == AgentKind::OpenCode)
.then(|| legacy_tool_title(event, agent, &raw))
.flatten()
})
} else if matches!(event, HookEvent::PreToolUse | HookEvent::PostToolUse) {
legacy_tool_title(event, agent, &raw)
} else {
best_title_hint(event, agent, &raw).or_else(|| {
source_event
.as_deref()
.map(|source| extension_title_hint(&raw, source))
})
};
let body_excerpt = if closed_tool_event {
safe_tool_body(event, tool_metadata.as_ref(), agent, &raw).or_else(|| {
(event == HookEvent::PostToolUse && agent == AgentKind::OpenCode)
.then(|| legacy_tool_body(event, agent, &raw))
.flatten()
})
} else if matches!(event, HookEvent::PreToolUse | HookEvent::PostToolUse) {
legacy_tool_body(event, agent, &raw)
} else {
best_body_excerpt(event, agent, &raw).or_else(|| {
source_event
.as_deref()
.and_then(|_| extension_body_excerpt(&raw))
})
};
let ingest_key = query.ingest_key.filter(|k| valid_ingest_key(k));
// Original event time (RFC 3339), when the client carried one — currently
// only `ai-memory backfill`, replaying a transcript's own per-event
// timestamps. This is numeric metadata, not text, so it never goes
// through the sanitizer (invariant #6 is about untrusted TEXT reaching
// storage/prompts unscrubbed; a timestamp has no such surface). It is
// still client-controlled input over the hook endpoint, so it is bounded
// at parse time in `occurred_at_micros`, not trusted here.
//
// Read from the top-level body only, unlike `extract_string`'s nested
// `payload`/`event`/`properties`/`info`/`path` search: that search
// exists for text fields real agent harnesses nest under those keys,
// but a real harness payload happening to carry an `occurred_at` key
// somewhere in that structure must not be mistaken for backfill's own
// top-level field.
let occurred_at = raw
.get("occurred_at")
.and_then(serde_json::Value::as_str)
.filter(|s| !s.is_empty())
.map(str::to_string);
Self {
event,
agent,
session_id,
cwd,
workspace_override,
project_override,
project_strategy,
project_source,
identity,
identity_style,
aliases,
aliases_invalid,
drop_subagent_requested,
recall_default_global_requested,
all_owners_requested,
managed_run,
capture_assistant_requested,
ingest_key,
extension,
source_event,
title_hint,
body_excerpt,
occurred_at,
recorded_tool,
raw,
}
}
/// Name a closed-tool call (`[ingest] record_tool_names`): the title
/// `tool <family>` becomes `tool <family>: <name>`, and the body gains a
/// `tool_name:` line, plus `skill:` or `subagent_type:` when the call ran
/// one. The family stays first, so [`tool_family_from_title`] still reads
/// it.
///
/// Does nothing unless the title is still the family label this module
/// wrote. A metadata-only rebuild writes a bare family and clears
/// [`Self::recorded_tool`], so a call a capture policy reduced to metadata
/// never gets its name back.
pub fn record_tool_name(&mut self) {
let Some(tool) = self.recorded_tool.take() else {
return;
};
let Some(title) = self
.title_hint
.as_deref()
.filter(|title| matches!(split_tool_title(title), Some((_, None))))
.filter(|title| title.starts_with("tool "))
else {
return;
};
self.title_hint = Some(format!("{title}: {}", tool.name));
if let Some(body) = self.body_excerpt.take() {
let mut lines = format!("tool_name: {}", tool.name);
for (key, value) in [
("skill", &tool.skill),
("subagent_type", &tool.subagent_type),
] {
if let Some(value) = value {
lines.push_str(&format!("\n{key}: {value}"));
}
}
// The body opens with the `tool_family:` line; the name goes
// right under it, above the call id and the output.
self.body_excerpt = Some(match body.split_once('\n') {
Some((family, rest)) => format!("{family}\n{lines}\n{rest}"),
None => format!("{body}\n{lines}"),
});
}
}
/// Parse and bound [`Self::occurred_at`] into a microsecond timestamp
/// suitable for `NewSession`/`NewObservation::occurred_at`.
///
/// `occurred_at` arrives from a client over the hook endpoint, so it is
/// bounded here rather than trusted outright: only strictly positive
/// values that are no more than [`MAX_OCCURRED_AT_FUTURE_SKEW_MICROS`]
/// ahead of server time are honored. Anything else — an unparseable
/// string, a non-positive value, or a suspicious far-future timestamp —
/// resolves to `None`, which callers fall back to "now" for. Hooks are
/// fire-and-forget, so this never errors.
#[must_use]
pub fn occurred_at_micros(&self) -> Option<i64> {
let parsed = self
.occurred_at
.as_deref()?
.parse::<jiff::Timestamp>()
.ok()?
.as_microsecond();
let now = jiff::Timestamp::now().as_microsecond();
if parsed > 0 && parsed <= now.saturating_add(MAX_OCCURRED_AT_FUTURE_SKEW_MICROS) {
Some(parsed)
} else {
None
}
}
}
/// How far ahead of server time a client-supplied `occurred_at` may sit
/// before it is treated as bogus (clock skew, or a hostile client) and
/// dropped to `None` instead of being trusted.
const MAX_OCCURRED_AT_FUTURE_SKEW_MICROS: i64 = 5 * 60 * 1_000_000;
/// An ingest key is client-controlled input: accept only short, plain tokens
/// (1–64 ASCII alphanumerics, `-` or `_` — a UUID simple/hyphenated form
/// fits). Anything else is treated as absent rather than rejected, so a
/// malformed key degrades to today's at-least-once behavior instead of a 4xx.
fn valid_ingest_key(key: &str) -> bool {
!key.is_empty()
&& key.len() <= 64
&& key
.bytes()
.all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
}
fn legacy_tool_title(
event: HookEvent,
agent: AgentKind,
raw: &serde_json::Value,
) -> Option<String> {
let payload = (event == HookEvent::PostToolUse && agent == AgentKind::OpenCode)
.then(|| raw.get("payload"))
.flatten()?;
extract_string(payload, &["tool"]).filter(|_| {
extract_content(
payload,
&["tool_response", "tool_output", "output", "result", "error"],
)
.is_some()
})
}
fn legacy_tool_body(event: HookEvent, agent: AgentKind, raw: &serde_json::Value) -> Option<String> {
let payload = (event == HookEvent::PostToolUse && agent == AgentKind::OpenCode)
.then(|| raw.get("payload"))
.flatten()?;
let tool = extract_string(payload, &["tool"])?;
let result = extract_content(
payload,
&["tool_response", "tool_output", "output", "result"],
)
.or_else(|| extract_content(payload, &["error"]))?;
Some(format!("tool: {tool}\n---\n{result}"))
}
const fn closed_tool_agent(agent: AgentKind) -> bool {
matches!(
agent,
AgentKind::ClaudeCode
| AgentKind::CommandCode
| AgentKind::Codex
// Cursor's own hooks and its copies of the Claude Code hooks carry
// Claude's snake_case tool aliases.
| AgentKind::Cursor
| AgentKind::OpenCode
| AgentKind::Pi
| AgentKind::Omp
| AgentKind::AntigravityCli
| AgentKind::Grok
| AgentKind::Hermes
| AgentKind::KiroCli
| AgentKind::Pool
| AgentKind::Zcode
| AgentKind::CopilotCli
| AgentKind::Grizzybot
| AgentKind::Droid
| AgentKind::Muse
// CodeBuddy Code sends Claude Code's snake_case tool fields
// (#1299). Unknown values stay `Other` and keep the capture-only
// path.
| AgentKind::CodeBuddy
| AgentKind::IbmBob
// DSH's Claude Code hooks bridge (`@deepseek-ai/dsh-hooks-claude-code`)
// forwards Claude Code's snake_case tool fields for PreToolUse /
// PostToolUse.
| AgentKind::Dsh
| AgentKind::Cline
// Gemini CLI's BeforeTool and AfterTool carry Claude Code's
// `tool_name` and `tool_input`, plus a `tool_response` object.
| AgentKind::GeminiCli
| AgentKind::QwenCode
| AgentKind::Qoder
)
}
fn safe_tool_title(metadata: &ToolObservationMetadata) -> String {
format!(
"tool {}",
serde_json::to_string(&metadata.tool_family)
.unwrap_or_default()
.trim_matches('"')
)
}
/// `true` when `title` is one this module produced from a [`ToolFamily`]
/// rather than from the harness's own tool name: `tool <family>`, or
/// `tool <family>: <name>` once `[ingest] record_tool_names` named the call.
///
/// Derived from the same serde representation [`safe_tool_title`] writes, so
/// a new `ToolFamily` variant is recognised here without a second edit — the
/// two cannot drift into disagreeing about what this module emits.
///
/// The distinction matters downstream: a family is a partition of the calls,
/// not a name for what they did, so a reader gains nothing from being told a
/// session spent itself "across tool non-file and tool unknown".
pub(crate) fn is_safe_tool_title(title: &str) -> bool {
title.starts_with("tool ") && split_tool_title(title).is_some()
}
/// Split a tool label this crate wrote into its family and, when
/// `[ingest] record_tool_names` named the call, the tool name: `tool <family>`,
/// `tool <family>: <name>`, or the bare `<family>` the reserved-protocol path
/// writes. `None` for anything else, a harness's own raw tool name included.
fn split_tool_title(title: &str) -> Option<(ToolFamily, Option<&str>)> {
let (label, name) = match title.strip_prefix("tool ") {
Some(rest) => match rest.split_once(": ") {
Some((family, name)) if crate::capture_policy::valid_tool_name(name) => {
(family, Some(name))
}
Some(_) => return None,
None => (rest, None),
},
None => (title, None),
};
let family =
serde_json::from_value::<ToolFamily>(serde_json::Value::String(label.to_owned())).ok()?;
Some((family, name))
}
/// The name a reader should see for a tool observation title: the recorded
/// tool name of a `tool <family>: <name>` label, or `None` for a bare family
/// label, which names no tool. Any other title is a harness's own tool name
/// and is returned as is.
pub(crate) fn listable_tool_name(title: &str) -> Option<&str> {
if title.is_empty() {
return None;
}
match split_tool_title(title) {
Some((_, name)) => name,
None => Some(title),
}
}
/// The text to show for a tool observation title in a count: the recorded
/// name when there is one, the title itself otherwise, so a bare family label
/// still shows as `tool non-file`.
pub(crate) fn tool_title_display(title: &str) -> &str {
match split_tool_title(title) {
Some((_, Some(name))) => name,
_ => title,
}
}
/// Map a stored observation title back to the [`ToolFamily`] it was derived
/// from, recognising **both** spellings this crate emits for a family label:
/// the bare `canonical_tool_name` form the reserved-protocol path writes
/// ("file" / "search-list" / "non-file" / "unknown") and the `"tool "`-prefixed
/// [`safe_tool_title`] form every closed-tool agent writes ("tool file", …),
/// with or without the `: <name>` that [`HookEnvelope::record_tool_name`] adds.
///
/// Returns `None` for a harness's own raw tool name ("edit", "bash", "Read"),
/// which is never one of these labels. That distinction is load-bearing: it is
/// what keeps the family labels out of handoffs, titles, and the file-activity
/// heuristic while a real tool name still flows through. Shares the serde
/// representation with [`safe_tool_title`] and [`is_safe_tool_title`], so a new
/// `ToolFamily` variant is recognised here without a second edit.
pub(crate) fn tool_family_from_title(title: &str) -> Option<ToolFamily> {
split_tool_title(title).map(|(family, _)| family)
}
fn safe_tool_body(
event: HookEvent,
metadata: Option<&ToolObservationMetadata>,
agent: AgentKind,
raw: &serde_json::Value,
) -> Option<String> {
let metadata = metadata?;
let mut summary = format!(
"tool_family: {}",
serde_json::to_string(&metadata.tool_family)
.ok()?
.trim_matches('"')
);
if let Some(id) = &metadata.tool_call_id {
summary.push_str("\ntool_call_id: ");
summary.push_str(id);
}
if let Some(mcp) = &metadata.mcp_tool {
summary.push_str("\nmcp_server: ");
summary.push_str(&mcp.server);
summary.push_str("\nmcp_tool: ");
summary.push_str(&mcp.tool);
}
match event {
HookEvent::PreToolUse => Some(summary),
HookEvent::PostToolUse => {
summary.push_str(TOOL_OUTCOME_LINE_PREFIX);
summary.push_str(tool_observation_outcome(agent, raw).as_str());
if metadata.tool_family == crate::capture_policy::ToolFamily::Unknown {
return Some(summary);
}
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 if agent == AgentKind::CopilotCli {
// Copilot CLI's VS-Code-compatible `PostToolUse` nests the
// model-facing text at `tool_result.text_result_for_llm`
// (#1040); read only that documented field so `result_type`
// never leaks in through an object-stringify fallback.
raw.pointer("/tool_result/text_result_for_llm")
.and_then(value_to_text)
.or_else(|| extract_content(raw, &["error"]))
} else if agent == AgentKind::Hermes {
// Hermes 3.x nests the tool result inside `extra.result`
// (`agent/shell_hooks.py::_payload_fields` keeps everything
// not in the top-level key set inside `extra`). Read only
// that documented field plus `error_message` so unrelated
// `extra` telemetry (task_id, middleware_trace, …) never
// leaks in through an object-stringify fallback.
raw.pointer("/extra/result")
.and_then(value_to_text)
.or_else(|| raw.pointer("/extra/error_message").and_then(value_to_text))
.or_else(|| extract_content(raw, &["error"]))
} else if agent == AgentKind::Cline {
raw.pointer("/tool_result/output")
.and_then(value_to_text)
.or_else(|| raw.pointer("/tool_result/error").and_then(value_to_text))
} else if agent == AgentKind::GeminiCli {
// Gemini CLI's `AfterTool` `tool_response` holds the model's
// copy of the result in `llmContent` (a string or a Part
// list) beside `returnDisplay`, the terminal rendering, which
// for an edit is a diff object carrying both whole versions of
// the file. Read only the model's text, then the error message
// (`ToolResult`, packages/core/src/tools/tools.ts, v0.66.0).
raw.pointer("/tool_response/llmContent")
.and_then(value_to_text)
.or_else(|| {
raw.pointer("/tool_response/error/message")
.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());
summary.push_str(TOOL_BODY_SEPARATOR);
summary.push_str(&result);
Some(summary)
}
_ => None,
}
}
fn antigravity_edit_content(agent: AgentKind, raw: &serde_json::Value) -> Option<String> {
if agent != AgentKind::AntigravityCli {
return None;
}
let tool_call = raw.get("toolCall")?;
let tool = tool_call.get("name")?.as_str()?;
if !matches!(
tool.to_ascii_lowercase().as_str(),
"write_to_file" | "replace_file_content" | "multi_replace_file_content"
) {
return None;
}
let args = tool_call.get("args")?;
extract_content(
args,
&["ReplacementContent", "CodeContent", "ReplacementChunks"],
)
}
/// The tool a tool event names, under the keys the observation title uses.
pub(crate) fn event_tool_name(raw: &serde_json::Value) -> Option<String> {
extract_string(raw, &["tool", "tool_name", "name"])
}
/// The tool-use id a tool event carries (Claude-family payloads).
pub(crate) fn event_tool_use_id(raw: &serde_json::Value) -> Option<String> {
extract_string(raw, &["tool_use_id"])
}
fn extract_string(value: &serde_json::Value, keys: &[&str]) -> Option<String> {
for key in keys {
for candidate in extraction_candidates(value) {
if let Some(s) = candidate.get(*key).and_then(serde_json::Value::as_str)
&& !s.is_empty()
{
return Some(s.to_string());
}
}
}
None
}
fn extract_string_path(value: &serde_json::Value, paths: &[&[&str]]) -> Option<String> {
for path in paths {
if let Some(s) = value_at_path(value, path).and_then(serde_json::Value::as_str)
&& !s.is_empty()
{
return Some(s.to_string());
}
}
None
}
fn extract_scalar_string(value: &serde_json::Value, keys: &[&str]) -> Option<String> {
for key in keys {
for candidate in extraction_candidates(value) {
if let Some(value) = candidate.get(*key) {
if let Some(s) = value.as_str()
&& !s.is_empty()
{
return Some(s.to_string());
}
if let Some(n) = value.as_i64() {
return Some(n.to_string());
}
if let Some(n) = value.as_u64() {
return Some(n.to_string());
}
}
}
}
None
}
fn extract_first_string_array_item(value: &serde_json::Value, keys: &[&str]) -> Option<String> {
for key in keys {
for candidate in extraction_candidates(value) {
if let Some(items) = candidate.get(*key).and_then(serde_json::Value::as_array) {
for item in items {
if let Some(s) = item.as_str()
&& !s.is_empty()
{
return Some(s.to_string());
}
}
}
}
}
None
}
fn value_at_path<'a>(
mut value: &'a serde_json::Value,
path: &[&str],
) -> Option<&'a serde_json::Value> {
for segment in path {
value = value.get(*segment)?;
}
Some(value)
}
fn extraction_candidates(value: &serde_json::Value) -> Vec<&serde_json::Value> {
let mut out = Vec::new();
push_candidates(&mut out, value);
if let Some(payload) = value.get("payload") {
push_candidates(&mut out, payload);
}
if let Some(event) = value.get("event") {
push_candidates(&mut out, event);
}
out
}
fn push_candidates<'a>(out: &mut Vec<&'a serde_json::Value>, value: &'a serde_json::Value) {
out.push(value);
if let Some(properties) = value.get("properties") {
out.push(properties);
if let Some(info) = properties.get("info") {
out.push(info);
}
}
if let Some(info) = value.get("info") {
out.push(info);
}
if let Some(path) = value.get("path") {
out.push(path);
}
}
fn best_title_hint(event: HookEvent, agent: AgentKind, raw: &serde_json::Value) -> Option<String> {
match event {
HookEvent::SessionStart => extract_string(raw, &["model", "title"]).and_then(first_line),
HookEvent::UserPrompt => {
// Kimi Code sends `prompt` as content blocks
// (`[{"type":"text","text":...}]`); `extract_content` flattens
// them and returns identical values for plain-string agents.
user_prompt_text_for_agent(agent, raw)
.or_else(|| {
(agent != AgentKind::QwenCode)
.then(|| {
raw.pointer("/userPromptSubmit/prompt")
.and_then(value_to_text)
})
.flatten()
})
.and_then(first_line)
}
HookEvent::PreToolUse | HookEvent::PostToolUse => {
extract_string(raw, &["tool", "tool_name", "name"])
.or_else(|| extract_string_path(raw, &[&["toolCall", "name"]]))
.or_else(|| {
extract_scalar_string(raw, &["stepIdx"]).map(|step| format!("step {step}"))
})
}
HookEvent::Notification => extract_string(raw, &["message", "text"]).and_then(first_line),
HookEvent::PostCompaction => extract_string(raw, &["summary"]).and_then(first_line),
_ => None,
}
}
fn extension_title_hint(raw: &serde_json::Value, source_event: &str) -> String {
extract_string(raw, &["title", "summary", "subject", "name"])
.and_then(first_line)
.unwrap_or_else(|| source_event.to_string())
}
fn extension_body_excerpt(raw: &serde_json::Value) -> Option<String> {
extract_string(
raw,
&[
"body",
"message",
"text",
"description",
"summary",
"details",
],
)
}
/// Extract human-readable text content for an observation body, accepting the
/// shapes agents actually send: a plain string, an **array of content blocks**
/// (`[{ "type": "text", "text": "…" }]` — the shape Claude Code uses for
/// `tool_response`), or a structured object (rendered as compact JSON). Unlike
/// [`extract_string`], which only matches a JSON string and silently drops
/// everything else, this keeps tool outputs / inputs that arrive as
/// arrays/objects.
fn extract_content(value: &serde_json::Value, keys: &[&str]) -> Option<String> {
for key in keys {
for candidate in extraction_candidates(value) {
if let Some(found) = candidate.get(*key).and_then(value_to_text)
&& !found.is_empty()
{
return Some(found);
}
}
}
None
}
/// Flatten a JSON value into text. Strings pass through; arrays concatenate
/// their flattened items (one per line); objects prefer a `text` / `content`
/// field and otherwise fall back to compact JSON. `null` yields `None`.
fn value_to_text(value: &serde_json::Value) -> Option<String> {
match value {
serde_json::Value::String(s) => (!s.is_empty()).then(|| s.clone()),
serde_json::Value::Array(items) => {
let joined = items
.iter()
.filter_map(value_to_text)
.collect::<Vec<_>>()
.join("\n");
(!joined.is_empty()).then_some(joined)
}
serde_json::Value::Object(_) => value
.get("text")
.and_then(serde_json::Value::as_str)
.map(ToString::to_string)
.or_else(|| value.get("content").and_then(value_to_text))
.or_else(|| {
serde_json::to_string(value)
.ok()
.filter(|s| s != "{}" && s != "null")
}),
serde_json::Value::Number(n) => Some(n.to_string()),
serde_json::Value::Bool(b) => Some(b.to_string()),
serde_json::Value::Null => None,
}
}
fn best_body_excerpt(
event: HookEvent,
agent: AgentKind,
raw: &serde_json::Value,
) -> Option<String> {
match event {
HookEvent::UserPrompt => user_prompt_text_for_agent(agent, raw).or_else(|| {
(agent != AgentKind::QwenCode)
.then(|| {
raw.pointer("/userPromptSubmit/prompt")
.and_then(value_to_text)
})
.flatten()
}),
HookEvent::PostToolUse => {
let tool = extract_string(raw, &["tool", "tool_name", "name"])
.or_else(|| extract_string_path(raw, &[&["toolCall", "name"]]))
.or_else(|| {
extract_scalar_string(raw, &["stepIdx"]).map(|step| format!("step {step}"))
})?;
let result =
extract_content(raw, &["tool_response", "tool_output", "output", "result"])
.or_else(|| extract_content(raw, &["error"]))
.unwrap_or_else(|| "(no output captured)".into());
Some(format!("tool: {tool}\n---\n{result}"))
}
HookEvent::Notification => extract_content(raw, &["message", "text"]),
HookEvent::PostCompaction => extract_content(raw, &["summary"]),
// Why the session ended (#1225): a string only, first line only, so
// consolidation and the zero-LLM page can tell a normal quit from
// anything else.
HookEvent::SessionEnd => extract_string(raw, &["reason"])
.and_then(first_line)
.map(|reason| format!("reason: {reason}")),
_ => None,
}
}
/// Reduce a hook-supplied string to its first line.
///
/// Terminators are LF, CRLF, and a lone CR (`str::lines`). An empty first
/// line (a payload that starts with a newline) yields `None` so the caller
/// can fall back instead of storing `""`.
///
/// This is the only shaping `title_hint` gets before it reaches the
/// sanitizer: the 80-char display cap used to happen here too, but that ran
/// *before* redaction and could cut a secret in half — the truncated prefix
/// was then too short to match the sanitizer's pattern, so it was stored in
/// clear text (#980). The length cap now lives in
/// `ai_memory_core::sanitize::truncate_for_title`, applied by
/// `Sanitized::new` *after* `Sanitizer::scrub`.
fn first_line(s: String) -> Option<String> {
// `str::lines` treats `\n`, `\r\n`, and a lone `\r` as terminators and
// does not keep them. Stopping only at `\n` left a trailing CR on
// Windows prompts, which the sanitizer preserves and `truncate_for_title`
// does not strip, so the CR was stored in the observation title.
let line = s.lines().next().unwrap_or("").to_string();
(!line.is_empty()).then_some(line)
}
/// Cap core lifecycle body fields before the native hook writes its local
/// spool entry. The server independently reapplies the same per-event limits
/// while constructing [`HookEnvelope`], and the typed persistence boundary has
/// a universal backstop.
pub fn cap_lifecycle_body_for_client(raw: &mut serde_json::Value, event: HookEvent) -> bool {
let Some((keys, max_bytes)) = core_body_cap(event) else {
return false;
};
let mut changed = cap_candidate_group(raw, keys, max_bytes);
for container in ["payload", "event"] {
if let Some(nested) = raw.get_mut(container) {
changed |= cap_candidate_group(nested, keys, max_bytes);
}
}
changed
}
fn core_body_cap(event: HookEvent) -> Option<(&'static [&'static str], usize)> {
match event {
// `submitted_prompt` is Qwen Code's prompt field
// (`user_prompt_text_for_agent`), and the only one a Qwen
// `UserPromptSubmit` body carries. It is listed here so the field is
// capped and scrubbed alongside its siblings; every listed key is
// capped independently, so this is not a fallback and leaves the
// submission-provenance rule intact.
HookEvent::UserPrompt => Some((
&["prompt", "message", "text", "submitted_prompt"],
USER_PROMPT_EXCERPT_MAX_BYTES,
)),
HookEvent::Notification => Some((&["message", "text"], NOTIFICATION_EXCERPT_MAX_BYTES)),
HookEvent::PostCompaction => Some((&["summary"], POST_COMPACTION_EXCERPT_MAX_BYTES)),
_ => None,
}
}
fn cap_candidate_group(value: &mut serde_json::Value, keys: &[&str], max_bytes: usize) -> bool {
let mut changed = cap_object_fields(value, keys, max_bytes);
if let Some(properties) = value.get_mut("properties") {
changed |= cap_object_fields(properties, keys, max_bytes);
if let Some(info) = properties.get_mut("info") {
changed |= cap_object_fields(info, keys, max_bytes);
}
}
for container in ["info", "path"] {
if let Some(nested) = value.get_mut(container) {
changed |= cap_object_fields(nested, keys, max_bytes);
}
}
changed
}
fn cap_object_fields(value: &mut serde_json::Value, keys: &[&str], max_bytes: usize) -> bool {
let Some(object) = value.as_object_mut() else {
return false;
};
let mut changed = false;
for key in keys {
let Some(field) = object.get_mut(*key) else {
continue;
};
let Some(text) = value_to_text(field) else {
continue;
};
if text.len() > max_bytes {
// Scrub the full text before capping it. The client cannot see
// the server's `[sanitize]` extras, but the built-in patterns
// cover the credential classes and the server re-scrubs the
// capped field with its configured sanitizer; truncating first
// would cut a straddling secret in half and persist an
// unmatchable prefix (#1114), the class #980 / #1109 fixed.
// Same order as `assistant_capture::transform_for_client`.
let scrubbed = Sanitizer::builtin().scrub(&text);
*field = serde_json::Value::String(truncate_utf8_bytes(&scrubbed, max_bytes));
changed = true;
}
}
changed
}
fn normalize_extension_name(value: Option<&str>) -> Option<String> {
normalize_token(value?, 64)
}
fn normalize_source_event(value: &str) -> Option<String> {
normalize_token(value, 128)
}
fn normalize_token(value: &str, max_len: usize) -> Option<String> {
let trimmed = value.trim();
if trimmed.is_empty() || trimmed.len() > max_len {
return None;
}
if trimmed
.chars()
.all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-' | ':'))
{
Some(trimmed.to_string())
} else {
None
}
}
#[cfg(test)]
mod tests {
use super::*;
/// The predicate must accept exactly what `safe_tool_title` emits, for
/// every `ToolFamily` variant. Inputs are built *through* the writer
/// rather than written by hand, so the two cannot drift apart on what a
/// family title looks like.
///
/// The list below is checked by the compiler, not by trust: the
/// wildcard-free `match` stops compiling the moment a variant is added,
/// which routes whoever adds it here. Without that this test would keep
/// passing while the new variant went uncovered — the comment would be
/// making a promise the enumeration does not keep.
#[test]
fn the_predicate_recognises_every_title_the_writer_can_emit() {
let every_variant = [
ToolFamily::File,
ToolFamily::SearchList,
ToolFamily::NonFile,
ToolFamily::Unknown,
];
for family in every_variant {
match family {
ToolFamily::File
| ToolFamily::SearchList
| ToolFamily::NonFile
| ToolFamily::Unknown => {}
}
}
for family in every_variant {
let written = safe_tool_title(&ToolObservationMetadata {
tool_family: family,
tool_call_id: None,
mcp_tool: None,
});
assert!(
is_safe_tool_title(&written),
"{written:?} is written by safe_tool_title and must be recognised"
);
}
}
/// A harness's own tool name is never mistaken for a family label, even
/// when it happens to start with the same word.
#[test]
fn a_real_tool_name_is_not_a_family_label() {
for name in [
"Bash",
"Edit",
"tool",
"tool ",
"tool Bash",
"toolfile",
"Tool file",
] {
assert!(
!is_safe_tool_title(name),
"{name:?} is not something safe_tool_title writes"
);
}
}
#[test]
fn project_source_parses_both_spellings_and_defaults_closed() {
assert_eq!(ProjectSource::parse(Some("marker")), ProjectSource::Marker);
assert_eq!(
ProjectSource::parse(Some("repo-root")),
ProjectSource::RepoRoot
);
assert_eq!(
ProjectSource::parse(Some("repo_root")),
ProjectSource::RepoRoot
);
// Absent (older client) and unknown values both stay authoritative,
// so a typo can never downgrade an override into something the
// session is allowed to overrule.
assert_eq!(ProjectSource::parse(None), ProjectSource::Unspecified);
assert_eq!(
ProjectSource::parse(Some("REPO-ROOT")),
ProjectSource::Unspecified
);
assert_eq!(
ProjectSource::parse(Some("nonsense")),
ProjectSource::Unspecified
);
// Only a host-derived name may yield to the session.
assert!(ProjectSource::RepoRoot.yields_to_session());
assert!(!ProjectSource::Marker.yields_to_session());
assert!(!ProjectSource::Unspecified.yields_to_session());
}
#[test]
fn cline_context_uses_task_id_and_first_workspace_root() {
let raw = serde_json::json!({
"taskId": "cline-task-1",
"workspaceRoots": ["/work/project", "/work/other"],
"userPromptSubmit": {"prompt": "continue the audit"}
});
let context = hook_payload_context(&raw);
assert_eq!(context.session_id.as_deref(), Some("cline-task-1"));
assert_eq!(context.cwd.as_deref(), Some("/work/project"));
let envelope = HookEnvelope::from_query_and_body(
HookQuery {
event: "user-prompt".into(),
agent: Some("cline".into()),
..Default::default()
},
raw,
);
assert_eq!(envelope.body_excerpt.as_deref(), Some("continue the audit"));
}
#[test]
fn omitted_style_stays_legacy_host_path_while_new_clients_send_path() {
let envelope = |identity_style: Option<&str>| {
HookEnvelope::from_query_and_body(
HookQuery {
event: "user-prompt-submit".into(),
identity_style: identity_style.map(str::to_owned),
..Default::default()
},
serde_json::json!({ "session_id": "s" }),
)
};
assert_eq!(
envelope(None).identity_style,
ai_memory_core::repository_identity::IdentityStyle::HostPath
);
assert_eq!(
envelope(Some("path")).identity_style,
ai_memory_core::repository_identity::IdentityStyle::Path
);
assert_eq!(
envelope(Some("host_path")).identity_style,
ai_memory_core::repository_identity::IdentityStyle::HostPath
);
assert_eq!(
envelope(Some("unknown")).identity_style,
ai_memory_core::repository_identity::IdentityStyle::HostPath
);
}
#[test]
fn project_source_is_pinned_unspecified_without_an_override() {
// Provenance describes an override; a `project_src` arriving without
// one is meaningless and must not read as a fell-through signal.
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "user-prompt-submit".into(),
agent: Some("claude-code".into()),
cwd: Some("/checkouts/repo-a".into()),
project_src: Some("repo-root".into()),
..Default::default()
},
serde_json::json!({ "session_id": "s" }),
);
assert_eq!(env.project_override, None);
assert_eq!(env.project_source, ProjectSource::Unspecified);
// With an override it is carried through verbatim.
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "user-prompt-submit".into(),
agent: Some("claude-code".into()),
cwd: Some("/checkouts/repo-a".into()),
project: Some("repo-a".into()),
project_src: Some("repo-root".into()),
..Default::default()
},
serde_json::json!({ "session_id": "s" }),
);
assert_eq!(env.project_override.as_deref(), Some("repo-a"));
assert_eq!(env.project_source, ProjectSource::RepoRoot);
}
/// `occurred_at` is client-controlled input arriving over the hook
/// endpoint, so it must be bounded, not trusted outright. A valid past
/// timestamp is stored exactly; garbage, non-positive, and far-future
/// values must all fall back to `None` ("now" at the store boundary) —
/// never an error, since hooks are fire-and-forget.
#[test]
fn occurred_at_micros_accepts_a_valid_past_timestamp() {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "user-prompt-submit".into(),
..Default::default()
},
serde_json::json!({ "session_id": "s", "occurred_at": "2026-09-10T12:00:00Z" }),
);
let expected = "2026-09-10T12:00:00Z"
.parse::<jiff::Timestamp>()
.unwrap()
.as_microsecond();
assert_eq!(env.occurred_at_micros(), Some(expected));
}
#[test]
fn occurred_at_micros_rejects_a_far_future_timestamp() {
// Adversarial: a client claiming its event happened next year must not
// be trusted — the bound must actually reject it.
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "user-prompt-submit".into(),
..Default::default()
},
serde_json::json!({ "session_id": "s", "occurred_at": "2099-01-01T00:00:00Z" }),
);
assert_eq!(
env.occurred_at_micros(),
None,
"a far-future timestamp must not be trusted"
);
}
#[test]
fn occurred_at_micros_rejects_non_positive_values() {
for bogus in ["1970-01-01T00:00:00Z", "0000-01-01T00:00:00Z"] {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "user-prompt-submit".into(),
..Default::default()
},
serde_json::json!({ "session_id": "s", "occurred_at": bogus }),
);
// The epoch and earlier parse fine as an RFC 3339 timestamp but
// must still be rejected: a non-positive microsecond value is
// never a plausible original event time.
let micros = bogus.parse::<jiff::Timestamp>().unwrap().as_microsecond();
assert!(micros <= 0, "fixture must actually be non-positive");
assert_eq!(env.occurred_at_micros(), None);
}
}
#[test]
fn occurred_at_micros_rejects_garbage_strings() {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "user-prompt-submit".into(),
..Default::default()
},
serde_json::json!({ "session_id": "s", "occurred_at": "not-a-timestamp" }),
);
assert_eq!(env.occurred_at_micros(), None);
}
#[test]
fn occurred_at_missing_from_the_body_parses_as_none() {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "user-prompt-submit".into(),
..Default::default()
},
serde_json::json!({ "session_id": "s" }),
);
assert_eq!(env.occurred_at, None);
assert_eq!(env.occurred_at_micros(), None);
}
#[test]
fn body_is_subagent_detects_harness_markers() {
// grok tags subagent tool-use events with `subagentType`.
assert!(body_is_subagent(
&serde_json::json!({ "sessionId": "s", "subagentType": "general-purpose" })
));
// Claude Code identifies spawned agents with `agent_id`.
assert!(body_is_subagent(
&serde_json::json!({ "session_id": "s", "agent_type": "workflow-subagent", "agent_id": "agent-abc123" })
));
assert!(body_is_subagent(
&serde_json::json!({ "agent_id": "agent-abc123" })
));
}
#[test]
fn body_is_subagent_keeps_top_level_claude_agent_sessions() {
// `claude --agent <name>` also sets agent_type on the main session.
let mut raw = serde_json::json!({
"session_id": "main-session",
"agent_type": "regulus:regulus",
});
assert!(!body_is_subagent(&raw), "agent_id absent");
for agent_id in [
serde_json::Value::Null,
serde_json::json!(""),
serde_json::json!(" "),
serde_json::json!(42),
serde_json::json!(false),
] {
raw["agent_id"] = agent_id;
assert!(!body_is_subagent(&raw), "{raw}");
}
}
#[test]
fn body_is_subagent_false_for_top_level_and_empty_markers() {
// A normal top-level event carries no marker.
assert!(!body_is_subagent(
&serde_json::json!({ "session_id": "s", "tool_name": "Write" })
));
// An empty / blank or non-string marker does not count as a subagent.
assert!(!body_is_subagent(
&serde_json::json!({ "subagentType": "" })
));
assert!(!body_is_subagent(
&serde_json::json!({ "subagentType": " " })
));
assert!(!body_is_subagent(
&serde_json::json!({ "agent_type": null })
));
assert!(!body_is_subagent(&serde_json::json!({})));
}
#[test]
fn parses_known_events() {
assert_eq!(HookEvent::parse("session-start"), HookEvent::SessionStart);
assert_eq!(HookEvent::parse("PreToolUse"), HookEvent::PreToolUse);
assert_eq!(HookEvent::parse("user_prompt"), HookEvent::UserPrompt);
assert_eq!(HookEvent::parse("bogus"), HookEvent::Other);
}
#[test]
fn debug_never_renders_hook_content() {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "user-prompt".into(),
agent: Some("claude-code".into()),
managed_run: Some("run-1".into()),
..Default::default()
},
serde_json::json!({
"session_id": "dbg",
"prompt": "SENTINEL_DERIVED_CONTENT",
"secret": "SENTINEL_RAW_PAYLOAD",
}),
);
assert_eq!(
env.body_excerpt.as_deref(),
Some("SENTINEL_DERIVED_CONTENT")
);
let rendered = format!("{env:?}");
assert!(
!rendered.contains("SENTINEL_RAW_PAYLOAD"),
"Debug leaked the raw payload: {rendered}"
);
assert!(
!rendered.contains("SENTINEL_DERIVED_CONTENT"),
"Debug leaked derived hook content: {rendered}"
);
assert!(rendered.contains("<redacted>"), "raw was not redacted");
assert!(rendered.contains("UserPrompt"), "event field went missing");
assert!(rendered.contains("run-1"), "managed run field went missing");
}
/// `ingest_key` is client-controlled input: only short plain tokens pass;
/// anything else degrades to "absent" (at-least-once), never a 4xx.
#[test]
fn ingest_key_is_validated_at_parse_time() {
let fire = |key: Option<&str>| {
HookEnvelope::from_query_and_body(
HookQuery {
event: "stop".into(),
ingest_key: key.map(str::to_string),
..Default::default()
},
serde_json::json!({ "session_id": "k-1" }),
)
};
// A UUID in simple or hyphenated form passes untouched.
assert_eq!(
fire(Some("abcDEF123_-")).ingest_key.as_deref(),
Some("abcDEF123_-")
);
// Empty, oversized or non-token input is dropped, not rejected.
let oversized = "x".repeat(65);
for bad in ["", "spaces here", "chave!", "key\n", oversized.as_str()] {
assert_eq!(
fire(Some(bad)).ingest_key,
None,
"expected {bad:?} to be dropped"
);
}
assert_eq!(fire(None).ingest_key, None);
}
#[test]
fn extension_event_preserves_source_event_when_opted_in() {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "lead.contact".into(),
extension: Some("fstech".into()),
..Default::default()
},
serde_json::json!({
"session_id": "fst-1",
"title": "Lead contacted",
"message": "Lead Maria requested a proposal"
}),
);
assert_eq!(env.event, HookEvent::Other);
assert_eq!(env.extension.as_deref(), Some("fstech"));
assert_eq!(env.source_event.as_deref(), Some("lead.contact"));
assert_eq!(env.title_hint.as_deref(), Some("Lead contacted"));
assert_eq!(
env.body_excerpt.as_deref(),
Some("Lead Maria requested a proposal")
);
}
#[test]
fn unknown_event_without_extension_leaves_no_source_event() {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "lead.contact".into(),
..Default::default()
},
serde_json::json!({
"session_id": "fst-1",
"title": "Lead contacted",
"message": "Lead Maria requested a proposal"
}),
);
assert_eq!(env.event, HookEvent::Other);
assert_eq!(env.extension, None);
assert_eq!(env.source_event, None);
assert_eq!(env.title_hint, None);
assert_eq!(env.body_excerpt, None);
}
#[test]
fn invalid_extension_tokens_are_not_preserved() {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "lead.contact".into(),
extension: Some("bad extension".into()),
..Default::default()
},
serde_json::json!({ "session_id": "fst-1" }),
);
assert_eq!(env.extension, None);
assert_eq!(env.source_event, None);
}
#[test]
fn maps_to_observation_kind() {
assert_eq!(
HookEvent::SessionEnd.to_observation_kind(),
ObservationKind::SessionEnd
);
assert_eq!(
HookEvent::PostCompaction.to_observation_kind(),
ObservationKind::PostCompaction
);
}
#[test]
fn hook_event_parses_post_compaction() {
assert_eq!(
HookEvent::parse("post-compaction"),
HookEvent::PostCompaction
);
assert_eq!(
HookEvent::parse("post_compaction"),
HookEvent::PostCompaction
);
assert_eq!(
HookEvent::parse("PostCompaction"),
HookEvent::PostCompaction
);
// Unknown event still maps to Other.
assert_eq!(HookEvent::parse("unknown-event"), HookEvent::Other);
}
#[test]
fn envelope_maps_default_global_flag() {
let on = HookEnvelope::from_query_and_body(
HookQuery {
default_global: Some("true".into()),
..Default::default()
},
serde_json::json!({ "session_id": "s1" }),
);
assert!(on.recall_default_global_requested);
let off = HookEnvelope::from_query_and_body(
HookQuery::default(),
serde_json::json!({ "session_id": "s1" }),
);
assert!(!off.recall_default_global_requested);
}
#[test]
fn envelope_extracts_session_and_cwd() {
let q = HookQuery {
event: "session-start".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let raw = serde_json::json!({
"session_id": "abc-123",
"cwd": "/tmp/x",
"model": "claude-sonnet-4-6"
});
let env = HookEnvelope::from_query_and_body(q.clone(), raw);
assert_eq!(env.event, HookEvent::SessionStart);
assert_eq!(env.session_id.as_deref(), Some("abc-123"));
assert_eq!(env.cwd.as_deref(), Some("/tmp/x"));
assert_eq!(env.title_hint.as_deref(), Some("claude-sonnet-4-6"));
}
/// Cursor's `sessionStart` carries no `cwd` key at all — the workspace
/// directory arrives only as `workspace_roots`. Shape captured live from
/// Cursor CLI 2026.09.02-c22c1a3.
#[test]
fn envelope_resolves_cursor_session_start_cwd_from_workspace_roots() {
let q = HookQuery {
event: "session-start".into(),
agent: Some("cursor".into()),
..Default::default()
};
let raw = serde_json::json!({
"conversation_id": "cf111450-8c45-4da1-a384-7a48e08099c3",
"session_id": "cf111450-8c45-4da1-a384-7a48e08099c3",
"is_background_agent": false,
"hook_event_name": "sessionStart",
"cursor_version": "2026.09.02-c22c1a3",
"workspace_roots": ["/checkouts/repo-a"],
"transcript_path": serde_json::Value::Null
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.event, HookEvent::SessionStart);
assert_eq!(env.agent, AgentKind::Cursor);
assert_eq!(
env.cwd.as_deref(),
Some("/checkouts/repo-a"),
"without workspace_roots the session resolves to no cwd and lands \
in the server-default scratch project"
);
}
/// Cursor's tool events DO carry a `cwd` key, but send it as an empty
/// string; resolution must fall through to `workspace_roots` instead of
/// accepting `""`.
#[test]
fn envelope_resolves_cursor_tool_event_cwd_despite_empty_cwd_string() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("cursor".into()),
..Default::default()
};
let raw = serde_json::json!({
"conversation_id": "cf111450-8c45-4da1-a384-7a48e08099c3",
"session_id": "cf111450-8c45-4da1-a384-7a48e08099c3",
"tool_name": "Shell",
"tool_input": {"command": "echo cap > CAP.txt", "cwd": "", "timeout": 30000},
"tool_use_id": "b0fe7c49-7ee7-45e6-91ee-6ee68b7b17e2",
"cwd": "",
"hook_event_name": "postToolUse",
"cursor_version": "2026.09.02-c22c1a3",
"workspace_roots": ["/checkouts/repo-a"]
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.cwd.as_deref(), Some("/checkouts/repo-a"));
}
/// The Cursor CLI also runs the hook commands declared in Claude Code's
/// `~/.claude/settings.json`, which `install-hooks --agent claude-code`
/// hardcoded to `--agent claude-code`. The payload's `cursor_version`
/// identifies the real harness, so the session must not be filed as
/// Claude Code.
#[test]
fn envelope_attributes_cursor_payload_to_cursor_over_declared_claude_code() {
let q = HookQuery {
event: "session-start".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let raw = serde_json::json!({
"conversation_id": "cf111450-8c45-4da1-a384-7a48e08099c3",
"session_id": "cf111450-8c45-4da1-a384-7a48e08099c3",
"hook_event_name": "sessionStart",
"cursor_version": "2026.09.02-c22c1a3",
"workspace_roots": ["/checkouts/repo-a"]
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.agent, AgentKind::Cursor);
assert_eq!(env.cwd.as_deref(), Some("/checkouts/repo-a"));
}
/// A genuine Claude Code payload carries no vendor marker, so the
/// declared `?agent=` still decides.
#[test]
fn envelope_keeps_declared_agent_when_payload_has_no_vendor_marker() {
let q = HookQuery {
event: "session-start".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let raw = serde_json::json!({
"session_id": "abc-123",
"cwd": "/checkouts/repo-a",
"hook_event_name": "SessionStart"
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.agent, AgentKind::ClaudeCode);
}
#[test]
fn envelope_uses_query_session_id_when_body_omits_it() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("devin".into()),
session_id: Some("bridge-session-123".into()),
..Default::default()
};
let raw = serde_json::json!({
"hook_event_name": "PostToolUse",
"tool_name": "exec",
"tool_input": {"command": "ls"},
"tool_use_id": "call_c101a272288d400b831e1498",
"tool_response": {"success": true, "output": "ok", "error": null}
});
let env = HookEnvelope::from_query_and_body(q.clone(), raw);
assert_eq!(env.event, HookEvent::PostToolUse);
assert_eq!(env.agent, AgentKind::Devin);
assert_eq!(env.session_id.as_deref(), Some("bridge-session-123"));
}
#[test]
fn envelope_body_session_id_wins_over_query_session_id() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("devin".into()),
session_id: Some("bridge-session-123".into()),
..Default::default()
};
let raw = serde_json::json!({
"session_id": "body-session-456",
"hook_event_name": "PostToolUse",
"tool_name": "exec"
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.session_id.as_deref(), Some("body-session-456"));
}
#[test]
fn envelope_uses_query_cwd_when_body_omits_it() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("devin".into()),
cwd: Some("/resolved/from/hook".into()),
session_id: Some("bridge-session-123".into()),
..Default::default()
};
let raw = serde_json::json!({
"hook_event_name": "PostToolUse",
"tool_name": "exec",
"tool_input": {"command": "ls"},
"tool_use_id": "call_c101a272288d400b831e1498",
"tool_response": {"success": true, "output": "ok", "error": null}
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.agent, AgentKind::Devin);
assert_eq!(env.session_id.as_deref(), Some("bridge-session-123"));
assert_eq!(env.cwd.as_deref(), Some("/resolved/from/hook"));
}
#[test]
fn envelope_body_cwd_wins_over_query_cwd() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("devin".into()),
cwd: Some("/resolved/from/hook".into()),
..Default::default()
};
let raw = serde_json::json!({
"hook_event_name": "PostToolUse",
"cwd": "/native/from/body"
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.cwd.as_deref(), Some("/native/from/body"));
}
#[test]
fn devin_real_session_start_fixture_has_no_native_session_or_cwd() {
let q = HookQuery {
event: "session-start".into(),
agent: Some("devin".into()),
..Default::default()
};
let raw = serde_json::json!({
"source": "startup"
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.event, HookEvent::SessionStart);
assert_eq!(env.agent, AgentKind::Devin);
assert!(env.session_id.is_none());
assert!(env.cwd.is_none());
}
#[test]
fn envelope_parses_project_strategy_query() {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "session-start".into(),
project_strategy: Some("repo-root".into()),
..Default::default()
},
serde_json::json!({}),
);
assert_eq!(env.project_strategy, ProjectStrategy::RepoRoot);
}
/// Antigravity CLI identifies the conversation as `conversationId`
/// and reports cwd-like routing through `workspacePaths`.
#[test]
fn envelope_extracts_antigravity_conversation_and_workspace_path() {
let q = HookQuery {
event: "PreToolUse".into(),
agent: Some("agy".into()),
..Default::default()
};
let raw = serde_json::json!({
"conversationId": "ec33ebf9-0cba-4100-8142-c61503f6c587",
"workspacePaths": ["/workspace/project", "/workspace/other"],
"toolCall": {
"name": "run_command",
"args": {"CommandLine": "cargo test"}
},
"stepIdx": 3
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.agent, AgentKind::AntigravityCli);
assert_eq!(env.event, HookEvent::PreToolUse);
assert_eq!(
env.session_id.as_deref(),
Some("ec33ebf9-0cba-4100-8142-c61503f6c587")
);
assert_eq!(env.cwd.as_deref(), Some("/workspace/project"));
assert_eq!(env.title_hint.as_deref(), Some("tool non-file"));
}
#[test]
fn envelope_uses_antigravity_step_idx_for_post_tool_title_fallback() {
let q = HookQuery {
event: "PostToolUse".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
};
let raw = serde_json::json!({
"conversationId": "agy-conv",
"workspacePaths": ["/workspace/project"],
"stepIdx": 5,
"error": "exit status 1"
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert!(env.title_hint.is_none());
assert!(env.body_excerpt.is_none());
}
/// OpenCode's plugin SDK sends `sessionID` (capital `ID`) on the
/// tool.execute.* / session.* events. Regression for issue #1: this
/// spelling must be extracted, otherwise non-session-start events
/// fail the router's "missing session_id" check.
#[test]
fn envelope_extracts_opencode_camelcase_session_id() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("open-code".into()),
..Default::default()
};
let raw = serde_json::json!({
"sessionID": "ses_abc123",
"tool": "bash",
"callID": "call_1"
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.session_id.as_deref(), Some("ses_abc123"));
}
/// Earlier OpenCode plugin generation wrapped the actual SDK hook
/// input under `payload`. Keep accepting that shape so users with
/// an old plugin don't silently lose project routing until they
/// restart with the fixed plugin.
#[test]
fn envelope_extracts_legacy_opencode_nested_payload() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("open-code".into()),
..Default::default()
};
let raw = serde_json::json!({
"hook_event_name": "post-tool-use",
"agent": "open-code",
"payload": {
"sessionID": "ses_nested",
"cwd": "/home/user/ai-memory",
"tool": "bash",
"output": "tests passed"
}
});
let env = HookEnvelope::from_query_and_body(q.clone(), raw);
assert_eq!(env.session_id.as_deref(), Some("ses_nested"));
assert_eq!(env.cwd.as_deref(), Some("/home/user/ai-memory"));
assert_eq!(env.title_hint.as_deref(), Some("bash"));
assert_eq!(
env.body_excerpt.as_deref(),
Some("tool: bash\n---\ntests passed")
);
let long = HookEnvelope::from_query_and_body(
q,
serde_json::json!({"payload":{"tool":"bash","output":"é".repeat(2_000)}}),
);
let body = long.body_excerpt.unwrap();
assert!(body.len() > 2_000);
let capped = truncate_utf8_bytes(&body, durable_body_cap(HookEvent::PostToolUse));
assert!(capped.len() <= 2_000);
}
/// OpenCode's plugin `event` hook receives bus events shaped like
/// `{ event: { type, properties } }`; session creation carries the
/// cwd as `properties.info.directory`.
#[test]
fn envelope_extracts_opencode_bus_event_session_info() {
let q = HookQuery {
event: "session-start".into(),
agent: Some("open-code".into()),
..Default::default()
};
let raw = serde_json::json!({
"event": {
"type": "session.created",
"properties": {
"sessionID": "ses_bus",
"info": {
"id": "ses_bus",
"directory": "/home/user/ai-memory",
"title": "New session"
}
}
}
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.session_id.as_deref(), Some("ses_bus"));
assert_eq!(env.cwd.as_deref(), Some("/home/user/ai-memory"));
assert_eq!(env.title_hint.as_deref(), Some("New session"));
}
/// Alternative agent-name spellings all map to the same canonical
/// AgentKind. The hook scripts and the test e2e shim send slightly
/// different strings for historical reasons; this asserts we
/// remain forgiving.
#[test]
fn agent_name_aliases_all_map_correctly() {
assert_eq!(parse_agent("claude-code"), AgentKind::ClaudeCode);
assert_eq!(parse_agent("claude_code"), AgentKind::ClaudeCode);
assert_eq!(parse_agent("claude"), AgentKind::ClaudeCode);
assert_eq!(parse_agent("codex"), AgentKind::Codex);
assert_eq!(parse_agent("opencode"), AgentKind::OpenCode);
assert_eq!(parse_agent("open-code"), AgentKind::OpenCode);
assert_eq!(parse_agent("cursor"), AgentKind::Cursor);
assert_eq!(parse_agent("gemini-cli"), AgentKind::GeminiCli);
assert_eq!(parse_agent("gemini"), AgentKind::GeminiCli);
assert_eq!(parse_agent("claude-desktop"), AgentKind::ClaudeDesktop);
assert_eq!(parse_agent("openclaw"), AgentKind::OpenClaw);
assert_eq!(parse_agent("antigravity-cli"), AgentKind::AntigravityCli);
assert_eq!(parse_agent("antigravity"), AgentKind::AntigravityCli);
assert_eq!(parse_agent("agy"), AgentKind::AntigravityCli);
assert_eq!(parse_agent("omp"), AgentKind::Omp);
assert_eq!(parse_agent("pi"), AgentKind::Pi);
assert_eq!(parse_agent("oh-my-pi"), AgentKind::Omp);
assert_eq!(parse_agent("hermes"), AgentKind::Hermes);
assert_eq!(parse_agent("hermes-agent"), AgentKind::Hermes);
assert_eq!(parse_agent("pool"), AgentKind::Pool);
assert_eq!(parse_agent("poolside"), AgentKind::Pool);
assert_eq!(parse_agent("codebuddy"), AgentKind::CodeBuddy);
assert_eq!(parse_agent("code-buddy"), AgentKind::CodeBuddy);
assert_eq!(parse_agent("qwen-code"), AgentKind::QwenCode);
assert_eq!(parse_agent("qwen"), AgentKind::QwenCode);
assert_eq!(parse_agent("qwencode"), AgentKind::QwenCode);
assert_eq!(parse_agent("qoder"), AgentKind::Qoder);
// Anything else is `Other`. Critical for the hook router:
// a typo in the query string must not crash, it just gets
// attributed to the catch-all bucket.
assert_eq!(parse_agent(""), AgentKind::Other);
assert_eq!(parse_agent("CLAUDE-CODE"), AgentKind::Other); // case-sensitive on purpose
assert_eq!(parse_agent("../../etc/passwd"), AgentKind::Other);
}
/// An empty body is legitimate (some hook events carry no
/// payload). Envelope extraction must produce sane defaults
/// rather than panicking.
#[test]
fn envelope_tolerates_empty_body() {
let q = HookQuery {
event: "stop".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let env = HookEnvelope::from_query_and_body(q, serde_json::json!({}));
assert_eq!(env.event, HookEvent::Stop);
assert!(env.session_id.is_none());
assert!(env.cwd.is_none());
assert!(env.title_hint.is_none());
assert!(env.body_excerpt.is_none());
}
#[test]
fn hermes_tool_title_uses_only_the_verified_shell_hook_shape() {
let raw = serde_json::json!({
"hook_event_name": "post_tool_call",
"tool_name": "write_file",
"tool_input": {"path": "src/lib.rs", "content": "untrusted"},
"session_id": "hermes-session",
"cwd": "/repo",
"extra": {"tool_call_id": "call-42", "status": "ok"}
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("hermes".into()),
..Default::default()
},
raw.clone(),
);
assert_eq!(env.agent, AgentKind::Hermes);
assert_eq!(env.title_hint.as_deref(), Some("tool file"));
assert_eq!(env.session_id.as_deref(), Some("hermes-session"));
assert_eq!(env.cwd.as_deref(), Some("/repo"));
let unknown = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("unverified-agent".into()),
..Default::default()
},
raw,
);
assert_eq!(unknown.agent, AgentKind::Other);
assert!(unknown.title_hint.is_none());
}
/// CodeBuddy posts Claude Code's tool payload. The same body under
/// `agent=codebuddy` is a closed tool observation; under an unknown
/// agent it stays capture-only (`title` empty, no tool family).
#[test]
fn codebuddy_post_tool_use_uses_the_claude_shaped_parser() {
let raw = serde_json::json!({
"hook_event_name": "PostToolUse",
"session_id": "11111111-2222-3333-4444-555555555555",
"cwd": "/repo",
"tool_name": "Read",
"tool_use_id": "toolu_codebuddy",
"tool_input": {"file_path": "src/lib.rs"},
"tool_response": "file contents"
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("codebuddy".into()),
..Default::default()
},
raw.clone(),
);
assert_eq!(env.agent, AgentKind::CodeBuddy);
assert_eq!(
env.session_id.as_deref(),
Some("11111111-2222-3333-4444-555555555555")
);
assert_eq!(env.cwd.as_deref(), Some("/repo"));
assert_eq!(env.title_hint.as_deref(), Some("tool file"));
let body = env.body_excerpt.expect("structured tool body");
assert!(body.starts_with("tool_family: file\n"), "{body}");
assert!(body.contains("outcome: unknown"), "{body}");
assert!(body.contains("tool_call_id: toolu_codebuddy"), "{body}");
assert!(body.contains("\n---\nfile contents"), "{body}");
let unknown = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("codebuddy-2".into()),
..Default::default()
},
raw,
);
assert_eq!(unknown.agent, AgentKind::Other);
assert!(unknown.title_hint.is_none());
assert!(unknown.body_excerpt.is_none());
}
/// IBM Bob documents the same snake_case tool fields as Claude Code. A
/// recognized Bob payload becomes a closed tool observation while an
/// unknown agent carrying identical JSON stays on the capture-only path.
#[test]
fn ibm_bob_post_tool_use_uses_the_claude_shaped_parser() {
let raw = serde_json::json!({
"hook_event_name": "PostToolUse",
"session_id": "11111111-2222-3333-4444-555555555555",
"cwd": "/repo",
"tool_name": "Read",
"tool_use_id": "toolu_bob",
"tool_input": {"file_path": "src/lib.rs"},
"tool_response": "file contents"
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("ibm-bob".into()),
..Default::default()
},
raw.clone(),
);
assert_eq!(env.agent, AgentKind::IbmBob);
assert_eq!(env.title_hint.as_deref(), Some("tool file"));
let body = env.body_excerpt.expect("structured tool body");
assert!(body.starts_with("tool_family: file\n"), "{body}");
assert!(body.contains("tool_call_id: toolu_bob"), "{body}");
assert!(body.contains("\n---\nfile contents"), "{body}");
let unknown = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("ibm-bob-2".into()),
..Default::default()
},
raw,
);
assert_eq!(unknown.agent, AgentKind::Other);
assert!(unknown.title_hint.is_none());
assert!(unknown.body_excerpt.is_none());
}
/// Qwen Code documents Claude Code's snake_case tool fields, including
/// `tool_use_id`. A recognized Qwen payload becomes a closed tool
/// observation while an unknown agent carrying identical JSON stays on
/// the capture-only path.
#[test]
fn qwen_code_post_tool_use_uses_the_claude_shaped_parser() {
let raw = serde_json::json!({
"hook_event_name": "PostToolUse",
"session_id": "11111111-2222-3333-4444-555555555555",
"cwd": "/repo",
"tool_name": "write_file",
"tool_use_id": "toolu_qwen",
"tool_input": {"file_path": "src/lib.rs", "content": "x"},
"tool_response": "wrote file"
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("qwen-code".into()),
..Default::default()
},
raw.clone(),
);
assert_eq!(env.agent, AgentKind::QwenCode);
assert_eq!(env.title_hint.as_deref(), Some("tool file"));
let body = env.body_excerpt.expect("structured tool body");
assert!(body.starts_with("tool_family: file\n"), "{body}");
assert!(body.contains("tool_call_id: toolu_qwen"), "{body}");
assert!(body.contains("\n---\nwrote file"), "{body}");
let unknown = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("qwen-code-2".into()),
..Default::default()
},
raw,
);
assert_eq!(unknown.agent, AgentKind::Other);
assert!(unknown.title_hint.is_none());
assert!(unknown.body_excerpt.is_none());
}
/// Hermes 3.x puts the tool result inside `extra.result` and mirrors the
/// call status in `extra.status` (`ok` | `error`). The extractor must read
/// both from the documented `extra` object: output lands in the body
/// instead of "(no output captured)", and a proven status maps to a real
/// outcome instead of permanent `unknown`. Live-captured 2026-10-07 from
/// `agent/shell_hooks.py::_payload_fields` +
/// `model_tools.py::_emit_post_tool_call_hook` (Hermes main).
#[test]
fn hermes_output_and_outcome_come_from_the_extra_object() {
let raw = serde_json::json!({
"hook_event_name": "post_tool_call",
"tool_name": "execute_code",
"tool_input": {"code": "print(1)"},
"session_id": "hermes-session",
"cwd": "/repo",
"extra": {
"tool_call_id": "call-43",
"status": "ok",
"result": {"output": "1", "exit_code": 0}
}
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("hermes".into()),
..Default::default()
},
raw,
);
let body = env.body_excerpt.expect("post-tool-use body");
assert!(body.contains("tool_family: non-file"), "body: {body}");
assert_eq!(env.title_hint.as_deref(), Some("tool non-file"));
assert!(
body.contains("outcome: success"),
"status ok must map to success — body: {body}"
);
assert!(
body.contains("\"output\": \"1\"") || body.contains("exit_code"),
"extra.result content must appear in the body — body: {body}"
);
}
#[test]
fn hermes_error_status_maps_to_error_outcome() {
let raw = serde_json::json!({
"hook_event_name": "post_tool_call",
"tool_name": "terminal",
"tool_input": {"command": "false"},
"session_id": "hermes-session",
"cwd": "/repo",
"extra": {
"tool_call_id": "call-44",
"status": "error",
"error_message": "command failed with exit code 1",
"result": "command failed"
}
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("hermes".into()),
..Default::default()
},
raw,
);
let body = env.body_excerpt.expect("post-tool-use body");
assert!(body.contains("outcome: error"), "body: {body}");
}
/// A truly unknown tool name keeps the upstream privacy invariant: the
/// family gates output capture, so `unknown` still omits the body. Real
/// Hermes tools that execute code or reach the web are named in
/// `family()` and classify as `non-file` (see
/// `hermes_documented_tool_names_map_to_canonical_families`); a brand-new
/// Hermes tool degrades to metadata-only until its name is upstreamed —
/// capture fidelity is preserved by extending the list, not by relaxing
/// the unknown-family gate.
#[test]
fn hermes_unknown_family_keeps_metadata_only_invariant() {
let raw = serde_json::json!({
"hook_event_name": "post_tool_call",
"tool_name": "brand_new_tool",
"tool_input": {"query": "x"},
"session_id": "hermes-session",
"cwd": "/repo",
"extra": {
"tool_call_id": "call-45",
"status": "ok",
"result": "search hit count: 3"
}
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("hermes".into()),
..Default::default()
},
raw,
);
let body = env.body_excerpt.expect("post-tool-use body");
assert!(body.contains("tool_family: unknown"), "body: {body}");
assert!(body.contains("outcome: success"), "body: {body}");
assert!(
!body.contains("search hit count: 3"),
"unknown family must not leak output — body: {body}"
);
}
/// Hermes v0.22.2 names an MCP tool `mcp__<server>__<tool>`
/// (`tools/mcp_tool_schema.py` `mcp_prefixed_tool_name`) in the same
/// `pre_tool_call` / `post_tool_call` envelope as its own tools. Such a
/// call stays an unknown family, so its arguments and result are never
/// kept, but its server and tool names are (#1522).
#[test]
fn hermes_mcp_tool_keeps_its_server_and_tool_names_but_no_input_or_output() {
for (event, hermes_event, expected) in [
(
"pre-tool-use",
"pre_tool_call",
"tool_family: unknown\ntool_call_id: call_00_2m0e\nmcp_server: aim\nmcp_tool: memory_query",
),
(
"post-tool-use",
"post_tool_call",
"tool_family: unknown\ntool_call_id: call_00_2m0e\nmcp_server: aim\nmcp_tool: memory_query\noutcome: success",
),
] {
let raw = serde_json::json!({
"hook_event_name": hermes_event,
"tool_name": "mcp__aim__memory_query",
"tool_input": {"query": "SECRET-ARGUMENT"},
"session_id": "hermes-session",
"cwd": "/repo",
"extra": {
"tool_call_id": "call_00_2m0e",
"status": "ok",
"result": "SECRET-RESULT"
}
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: event.into(),
agent: Some("hermes".into()),
..Default::default()
},
raw,
);
assert_eq!(env.title_hint.as_deref(), Some("tool unknown"));
assert_eq!(env.body_excerpt.as_deref(), Some(expected), "{event}");
}
}
/// Every documented `mcp__<server>__<tool>` spelling keeps both names:
/// a hyphenated Claude Code server, a Claude Code plugin server, Codex's
/// own example and a Hermes name clamped to 64 characters with a hash.
#[test]
fn mcp_tool_names_from_each_documented_harness_keep_server_and_tool() {
for (agent, tool_name, server, tool) in [
(
"claude-code",
"mcp__brave-search__web_search",
"brave-search",
"web_search",
),
(
"claude-code",
"mcp__plugin_my-plugin_db__query",
"plugin_my-plugin_db",
"query",
),
("codex", "mcp__fs__read", "fs", "read"),
(
"hermes",
"mcp__plugin_bridge_team_server__list_open_pull_requests_1a2b3c4d",
"plugin_bridge_team_server",
"list_open_pull_requests_1a2b3c4d",
),
] {
let mut raw = serde_json::json!({
"tool_name": tool_name,
"tool_input": {"path": "/etc/SECRET"},
"tool_use_id": "call-1",
"tool_response": "SECRET-OUTPUT",
});
if agent == "hermes" {
raw["extra"] =
serde_json::json!({"tool_call_id": "call-1", "result": "SECRET-OUTPUT"});
}
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "PreToolUse".into(),
agent: Some(agent.into()),
..Default::default()
},
raw,
);
assert_eq!(
env.body_excerpt.as_deref(),
Some(
format!(
"tool_family: unknown\ntool_call_id: call-1\nmcp_server: {server}\nmcp_tool: {tool}"
)
.as_str()
),
"{agent} {tool_name}"
);
}
}
/// A name that is not exactly the documented MCP shape keeps no name at
/// all, as before: an older Hermes `mcp_<server>_<tool>` cannot be split,
/// and free text, over-long names and empty halves are refused.
#[test]
fn names_outside_the_mcp_shape_keep_no_tool_identity() {
for tool_name in [
"mcp_github_create_issue",
"mcp__server",
"mcp____tool",
"mcp__server__",
"MCP__server__tool",
"mcp__my server__tool",
"mcp__srv__tool\nsecret",
"mcp__srv__tool.read",
"mcp__srv/path__tool",
"mcp__s\u{e9}rver__tool",
&format!("mcp__srv__{}", "t".repeat(55)),
"brand_new_tool",
] {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "PreToolUse".into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({"tool_name": tool_name, "tool_input": {}, "tool_use_id": "call-1"}),
);
assert_eq!(
env.body_excerpt.as_deref(),
Some("tool_family: unknown\ntool_call_id: call-1"),
"{tool_name:?}"
);
}
}
/// Real Hermes execution-surface tools classify as non-file so their
/// bodies carry the `extra.result` output (live names, 2026-10-07).
#[test]
fn hermes_execution_tools_classify_non_file_and_capture_output() {
for tool in ["execute_code", "browser_exec", "web_extract"] {
let raw = serde_json::json!({
"hook_event_name": "post_tool_call",
"tool_name": tool,
"tool_input": {"query": "x"},
"session_id": "hermes-session",
"cwd": "/repo",
"extra": {
"tool_call_id": "call-46",
"status": "ok",
"result": "CAPTURE-ME-42"
}
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("hermes".into()),
..Default::default()
},
raw,
);
let body = env.body_excerpt.unwrap_or_default();
assert!(
body.contains("tool_family: non-file"),
"{tool} should be non-file — body: {body}"
);
assert!(
body.contains("CAPTURE-ME-42"),
"{tool} output must be captured — body: {body}"
);
}
}
#[test]
fn pool_tool_title_uses_the_documented_snake_case_shape() {
let raw = serde_json::json!({
"hook_event_name": "PostToolUse",
"tool_name": "edit",
"tool_input": {"path": "src/lib.rs", "old_string": "a", "new_string": "b"},
"session_id": "pool-session",
"cwd": "/repo"
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("pool".into()),
..Default::default()
},
raw,
);
assert_eq!(env.agent, AgentKind::Pool);
assert_eq!(env.title_hint.as_deref(), Some("tool file"));
assert_eq!(env.session_id.as_deref(), Some("pool-session"));
assert_eq!(env.cwd.as_deref(), Some("/repo"));
}
#[test]
fn zcode_tool_payload_uses_the_captured_dual_casing_shape() {
// Live-captured PostToolUse payload (embedded engine v0.16.5, #512):
// native camelCase plus Claude Code-compatible snake_case aliases on
// every shared field.
let raw = serde_json::json!({
"hookEventName": "PostToolUse",
"hook_event_name": "PostToolUse",
"toolName": "Bash",
"tool_name": "Bash",
"toolCallId": "call_86cedcb9c40a4a40856e9ee7",
"tool_use_id": "call_86cedcb9c40a4a40856e9ee7",
"toolInput": {"command": "echo capture-ok"},
"tool_input": {"command": "echo capture-ok"},
"sessionId": "sess_4fc06da3",
"session_id": "sess_4fc06da3",
"cwd": "/tmp/zcode-capture"
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("zcode".into()),
..Default::default()
},
raw,
);
assert_eq!(env.agent, AgentKind::Zcode);
assert_eq!(env.session_id.as_deref(), Some("sess_4fc06da3"));
assert_eq!(env.cwd.as_deref(), Some("/tmp/zcode-capture"));
assert_eq!(env.title_hint.as_deref(), Some("tool non-file"));
}
#[test]
fn grizzybot_tool_title_is_a_closed_family() {
let raw = serde_json::json!({
"hook_event_name": "PostToolUse",
"tool_name": "write_file",
"tool_input": {"path": "notes.md", "content": "untrusted"},
"tool_response": "ok",
"session_id": "gb-session",
"cwd": "/bot/home"
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("grizzybot".into()),
..Default::default()
},
raw,
);
assert_eq!(env.agent, AgentKind::Grizzybot);
assert_eq!(env.title_hint.as_deref(), Some("tool file"));
assert_eq!(env.session_id.as_deref(), Some("gb-session"));
assert_eq!(env.cwd.as_deref(), Some("/bot/home"));
}
/// Factory Droid's PostToolUse is Claude-shaped with no tool-call id
/// (0.240.0 tool schemas, #1240): a `Create` is a closed `file` family and
/// its `tool_response` is the captured output.
#[test]
fn droid_create_post_tool_use_is_a_closed_file_family_without_call_id() {
let raw = serde_json::json!({
"hook_event_name": "PostToolUse",
"permission_mode": "auto-low",
"tool_name": "Create",
"tool_input": {"file_path": "/repo/notes.md", "content": "hello"},
"tool_response": {"filePath": "/repo/notes.md", "success": true},
"session_id": "droid-session",
"transcript_path": "/home/u/.factory/sessions/x.jsonl",
"cwd": "/repo"
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("droid".into()),
..Default::default()
},
raw,
);
assert_eq!(env.agent, AgentKind::Droid);
assert_eq!(env.title_hint.as_deref(), Some("tool file"));
assert_eq!(env.session_id.as_deref(), Some("droid-session"));
let body = env.body_excerpt.expect("post-tool-use body");
assert!(body.starts_with("tool_family: file\n"), "{body}");
assert!(!body.contains("tool_call_id"), "{body}");
assert!(body.contains("/repo/notes.md"), "{body}");
}
/// Meta Muse Code's PostToolUse and PostToolUseFailure, as captured
/// offline from Muse Code 1.4.7 (paths rewritten): a `write_file` is a
/// closed `file` family that keeps its `tool_use_id`, the session id is
/// the payload's UUIDv7, and a failure aliases to `post-tool-use`.
#[test]
fn muse_post_tool_use_is_a_closed_file_family_with_call_id() {
let raw = serde_json::json!({
"cwd": "/repo",
"hook_event_name": "PostToolUse",
"model": "muse-wonder-1.0",
"model_provider": "meta",
"permission_mode": "bypassPermissions",
"session_id": "01a13669-dc61-7a72-b5ec-ad2f300ffd26",
"tool_input": {"content": "alpha\n", "path": "notes.txt"},
"tool_name": "write_file",
"tool_response": {
"filePath": "/repo/notes.txt",
"structuredPatch": [{"lines": ["+alpha"], "newLines": 1, "newStart": 1, "oldLines": 0, "oldStart": 1}]
},
"tool_use_id": "call_30a33793ad9c",
"transcript_path": null,
"turn_id": "ccfe4a87-c654-49f5-b5e9-473015c7a90b"
});
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("muse".into()),
..Default::default()
},
raw,
);
assert_eq!(env.agent, AgentKind::Muse);
assert_eq!(env.title_hint.as_deref(), Some("tool file"));
assert_eq!(
env.session_id.as_deref(),
Some("01a13669-dc61-7a72-b5ec-ad2f300ffd26")
);
assert_eq!(env.cwd.as_deref(), Some("/repo"));
let body = env.body_excerpt.expect("post-tool-use body");
assert!(body.starts_with("tool_family: file\n"), "{body}");
assert!(body.contains("call_30a33793ad9c"), "{body}");
assert_eq!(
HookEvent::parse("PostToolUseFailure"),
HookEvent::PostToolUse
);
}
/// Body is well-formed JSON but the expected `session_id` /
/// `cwd` keys are missing — extraction returns None per key.
#[test]
fn envelope_missing_expected_fields() {
let q = HookQuery {
event: "user-prompt".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let raw = serde_json::json!({ "garbage": 42 });
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.event, HookEvent::UserPrompt);
assert!(env.session_id.is_none());
assert!(env.cwd.is_none());
}
/// Body is a JSON primitive (string / null / number) rather
/// than an object. The extractors must short-circuit cleanly.
/// This guards against an upstream that POSTs a stringified
/// payload by mistake.
#[test]
fn envelope_accepts_non_object_body() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
};
for raw in [
serde_json::json!(null),
serde_json::json!("a stringy payload"),
serde_json::json!(42),
serde_json::json!([1, 2, 3]),
] {
let env = HookEnvelope::from_query_and_body(q.clone(), raw);
assert!(
env.session_id.is_none(),
"no session_id from non-object body"
);
assert!(env.cwd.is_none(), "no cwd from non-object body");
}
}
/// Empty `agent` query param maps to Other (rather than panic
/// or default to ClaudeCode). The hook router uses this for the
/// attribution column, so we want it consistent.
#[test]
fn missing_agent_query_param_maps_to_other() {
let q = HookQuery {
event: "session-end".into(),
agent: None,
..Default::default()
};
let env = HookEnvelope::from_query_and_body(q, serde_json::json!({}));
assert_eq!(env.agent, AgentKind::Other);
}
/// #1225: a SessionEnd's `reason` becomes the observation body (first
/// line, string only), so why a session ended survives capture. An
/// absent, empty or non-string reason leaves the body empty as before.
#[test]
fn session_end_reason_becomes_the_observation_body() {
let q = HookQuery {
event: "session-end".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let body = |raw| HookEnvelope::from_query_and_body(q.clone(), raw).body_excerpt;
assert_eq!(
body(serde_json::json!({ "reason": "prompt_input_exit" })).as_deref(),
Some("reason: prompt_input_exit")
);
assert_eq!(
body(serde_json::json!({ "reason": "logout\ninjected second line" })).as_deref(),
Some("reason: logout")
);
assert_eq!(body(serde_json::json!({})), None);
assert_eq!(body(serde_json::json!({ "reason": "" })), None);
assert_eq!(body(serde_json::json!({ "reason": 7 })), None);
assert_eq!(body(serde_json::json!({ "reason": { "kind": "x" } })), None);
}
/// Title-hint extraction must truncate at the first newline (the
/// "first line" rule used everywhere in the wiki log + handoff
/// surfaces), but must NOT cap length here any more: the 80-char display
/// cap moved to `ai_memory_core::sanitize::truncate_for_title`, applied
/// by `Sanitized::new` after redaction (#980) — truncating a long
/// `title_hint` in `payload.rs`, before the sanitizer ever runs, could
/// cut a secret in half and leave the unmatched fragment unredacted.
#[test]
fn user_prompt_title_keeps_first_line_full_length_untruncated() {
let q = HookQuery {
event: "user-prompt".into(),
agent: Some("claude-code".into()),
..Default::default()
};
// Multi-line prompt → title is the first line only.
let env = HookEnvelope::from_query_and_body(
q.clone(),
serde_json::json!({ "prompt": "first line\nsecond line should be lost" }),
);
assert_eq!(env.title_hint.as_deref(), Some("first line"));
let env = HookEnvelope::from_query_and_body(
q.clone(),
serde_json::json!({ "prompt": "first line\r\nsecond line should be lost" }),
);
assert_eq!(
env.title_hint.as_deref(),
Some("first line"),
"CRLF must not leave a trailing CR on the title"
);
let env = HookEnvelope::from_query_and_body(
q.clone(),
serde_json::json!({ "prompt": "\r\nhello" }),
);
assert!(
env.title_hint.is_none(),
"empty first line after leading CRLF must not become a CR or empty title, got {:?}",
env.title_hint
);
// Very long single line → title_hint keeps every character; the
// 80-char cap now happens later, after sanitization.
let long = "x".repeat(200);
let env = HookEnvelope::from_query_and_body(q, serde_json::json!({ "prompt": long }));
let title = env.title_hint.unwrap();
assert_eq!(title.chars().count(), 200);
assert!(!title.contains('…'));
}
#[test]
fn notification_and_compaction_titles_are_the_first_line() {
let start = HookQuery {
event: "session-start".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let env = HookEnvelope::from_query_and_body(
start,
serde_json::json!({ "title": "first\r\nsecond" }),
);
assert_eq!(env.title_hint.as_deref(), Some("first"));
let notify = HookQuery {
event: "notification".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let env = HookEnvelope::from_query_and_body(
notify,
serde_json::json!({ "message": "first\r\nsecond" }),
);
assert_eq!(env.title_hint.as_deref(), Some("first"));
let compact = HookQuery {
event: "post-compaction".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let env = HookEnvelope::from_query_and_body(
compact,
serde_json::json!({ "summary": "kept\nlost" }),
);
assert_eq!(env.title_hint.as_deref(), Some("kept"));
}
#[test]
fn core_lifecycle_bodies_use_named_utf8_safe_caps() {
for (event, field, cap) in [
("user-prompt", "prompt", USER_PROMPT_EXCERPT_MAX_BYTES),
("notification", "message", NOTIFICATION_EXCERPT_MAX_BYTES),
(
"post-compaction",
"summary",
POST_COMPACTION_EXCERPT_MAX_BYTES,
),
] {
let body = format!("{}éTAIL_SENTINEL", "x".repeat(cap - 1));
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: event.into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({(field): body}),
);
// Extraction no longer caps (#1114): the sanitizer at the ingest
// funnel must see the full text before any byte limit runs. The
// scrub-then-cap order itself is asserted by the router's
// `issue_1114_*` tests.
let excerpt = env.body_excerpt.expect("body excerpt");
assert_eq!(excerpt, body, "{event} excerpt was capped at extraction");
let hook_event = HookEvent::parse(event);
assert_eq!(durable_body_cap(hook_event), cap);
let capped = truncate_utf8_bytes(&excerpt, durable_body_cap(hook_event));
assert!(capped.len() <= cap, "{event} exceeded {cap} bytes");
assert!(capped.ends_with('…'), "{event} omitted truncation marker");
assert!(
!capped.contains("TAIL_SENTINEL"),
"{event} retained content after the cap"
);
}
}
#[test]
fn client_body_cap_covers_supported_nested_candidate_shapes() {
let mut raw = serde_json::json!({
"prompt": "x".repeat(USER_PROMPT_EXCERPT_MAX_BYTES + 1),
"payload": {
"properties": {
"info": {
"message": [{"type": "text", "text": "y".repeat(USER_PROMPT_EXCERPT_MAX_BYTES + 1)}]
}
}
},
"event": {
"info": {
"text": "z".repeat(USER_PROMPT_EXCERPT_MAX_BYTES + 1)
}
}
});
assert!(cap_lifecycle_body_for_client(
&mut raw,
HookEvent::UserPrompt
));
for value in [
&raw["prompt"],
&raw["payload"]["properties"]["info"]["message"],
&raw["event"]["info"]["text"],
] {
let text = value.as_str().expect("oversized value flattened to text");
assert!(text.len() <= USER_PROMPT_EXCERPT_MAX_BYTES);
assert!(text.ends_with('…'));
}
assert!(!cap_lifecycle_body_for_client(
&mut raw,
HookEvent::UserPrompt
));
assert!(!cap_lifecycle_body_for_client(
&mut raw,
HookEvent::SessionStart
));
}
/// Regression for #1114 (client side): an oversized lifecycle body is
/// scrubbed with the built-in sanitizer **before** the spool cap runs, so
/// a secret straddling the cutoff is redacted whole instead of being cut
/// into an unmatchable prefix that the spool — and later the server —
/// persists in clear text. Mirrors `transform_for_client` (#196) and the
/// #980 / #1109 scrub-before-cap fixes.
#[test]
fn client_body_cap_scrubs_before_truncating() {
// AWS access key id shape: a built-in pattern.
let secret = format!("AKIA{}", "A".repeat(16));
let mut raw = serde_json::json!({
"prompt": format!("{} {secret}", "x".repeat(USER_PROMPT_EXCERPT_MAX_BYTES - 14)),
});
assert!(cap_lifecycle_body_for_client(
&mut raw,
HookEvent::UserPrompt
));
let capped = raw["prompt"].as_str().expect("oversized prompt capped");
assert!(
!capped.contains("AKIA"),
"unredacted secret fragment survived the cap: {capped:?}"
);
assert!(
capped.contains("[REDACTED:"),
"capped prompt carries no redaction marker: {capped:?}"
);
assert!(capped.len() <= USER_PROMPT_EXCERPT_MAX_BYTES);
}
/// A Qwen Code `UserPromptSubmit` body carries its prompt only in
/// `submitted_prompt` (`user_prompt_text_for_agent`), so that field must
/// be scrubbed and capped before the native hook spools the body, exactly
/// like the `prompt` / `message` / `text` siblings.
#[test]
fn client_body_cap_covers_qwen_submitted_prompt() {
// AWS access key id shape: a built-in pattern.
let secret = format!("AKIA{}", "A".repeat(16));
let mut raw = serde_json::json!({
"session_id": "qwen-session",
"submitted_prompt": format!(
"{} {secret}",
"x".repeat(USER_PROMPT_EXCERPT_MAX_BYTES - 14)
),
});
assert!(
cap_lifecycle_body_for_client(&mut raw, HookEvent::UserPrompt),
"oversized Qwen submitted_prompt left the body unchanged"
);
let capped = raw["submitted_prompt"]
.as_str()
.expect("oversized submitted_prompt capped");
assert!(
capped.len() <= USER_PROMPT_EXCERPT_MAX_BYTES,
"submitted_prompt exceeds the per-event cap: {} bytes",
capped.len()
);
assert!(capped.ends_with('…'), "submitted_prompt not truncated");
assert!(
!capped.contains("AKIA"),
"unredacted secret fragment survived the cap: {capped:?}"
);
assert!(
capped.contains("[REDACTED:"),
"capped submitted_prompt carries no redaction marker: {capped:?}"
);
}
/// Capping is size-triggered: a Qwen prompt within the limit reaches the
/// spool byte-for-byte, and the body is reported unchanged so the hook
/// keeps the original serialization.
#[test]
fn client_body_cap_leaves_normal_qwen_submitted_prompt_untouched() {
let mut raw = serde_json::json!({
"session_id": "qwen-session",
"submitted_prompt": "MARKER_QWEN_USER_PROMPT",
});
assert!(!cap_lifecycle_body_for_client(
&mut raw,
HookEvent::UserPrompt
));
assert_eq!(raw["submitted_prompt"], "MARKER_QWEN_USER_PROMPT");
}
/// `submitted_prompt` joins the `UserPrompt` arm only: the other harnesses'
/// fields keep capping as before, and the `Notification` /
/// `PostCompaction` arms are untouched by the new key.
#[test]
fn client_body_cap_keeps_other_harness_and_event_caps() {
let oversized = "x".repeat(USER_PROMPT_EXCERPT_MAX_BYTES + 1);
let mut raw = serde_json::json!({ "prompt": oversized.clone() });
assert!(cap_lifecycle_body_for_client(
&mut raw,
HookEvent::UserPrompt
));
let capped = raw["prompt"].as_str().expect("oversized prompt capped");
assert!(capped.len() <= USER_PROMPT_EXCERPT_MAX_BYTES);
assert!(capped.ends_with('…'));
let mut notification = serde_json::json!({
"message": "y".repeat(NOTIFICATION_EXCERPT_MAX_BYTES + 1),
"submitted_prompt": oversized.clone(),
});
assert!(cap_lifecycle_body_for_client(
&mut notification,
HookEvent::Notification
));
assert!(
notification["message"]
.as_str()
.expect("oversized notification message capped")
.len()
<= NOTIFICATION_EXCERPT_MAX_BYTES
);
assert_eq!(
notification["submitted_prompt"], oversized,
"submitted_prompt must not be capped outside the UserPrompt arm"
);
let mut compaction = serde_json::json!({ "submitted_prompt": oversized.clone() });
assert!(!cap_lifecycle_body_for_client(
&mut compaction,
HookEvent::PostCompaction
));
assert_eq!(compaction["submitted_prompt"], oversized);
}
/// Kimi Code's content-block `prompt` must flatten into the title
/// exactly like the body excerpt does.
#[test]
fn user_prompt_title_flattens_kimi_code_content_blocks() {
let q = HookQuery {
event: "user-prompt".into(),
agent: Some("kimi-code".into()),
..Default::default()
};
let env = HookEnvelope::from_query_and_body(
q,
serde_json::json!({
"hook_event_name": "UserPromptSubmit",
"session_id": "session_kimi-1",
"cwd": "/tmp/proj",
"prompt": [ { "type": "text", "text": "hello" } ]
}),
);
assert_eq!(env.title_hint.as_deref(), Some("hello"));
assert_eq!(env.body_excerpt.as_deref(), Some("hello"));
}
#[test]
fn post_tool_excerpt_truncates_without_splitting_utf8() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let output = format!("{}é", "x".repeat(1_999));
let env = HookEnvelope::from_query_and_body(
q,
serde_json::json!({
"tool_name": "Bash",
"tool_input": {},
"result": output,
}),
);
let excerpt = env.body_excerpt.unwrap();
assert!(excerpt.starts_with("tool_family: non-file\noutcome: unknown\n---\n"));
let capped = truncate_utf8_bytes(&excerpt, durable_body_cap(HookEvent::PostToolUse));
assert!(capped.ends_with('…'));
}
/// Regression: the native-binary hook command sends the script stem
/// `user-prompt-submit` as the event token (rendered by `render_shared.rs`,
/// forwarded verbatim by `ai-memory hook`). The parser must map it to
/// `UserPrompt`; otherwise native installs (the Windows / posix-native
/// default) bucket every prompt as `Other` and drop its text.
#[test]
fn parses_native_user_prompt_submit_event_token() {
assert_eq!(
HookEvent::parse("user-prompt-submit"),
HookEvent::UserPrompt
);
assert_eq!(
HookEvent::parse("user_prompt_submit"),
HookEvent::UserPrompt
);
}
/// Claude Code sends `tool_response` as an array of content blocks
/// (`[{ "type": "text", "text": "…" }]`). The body excerpt must capture
/// that text instead of falling back to "(no output captured)".
#[test]
fn post_tool_excerpt_captures_array_tool_response() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let env = HookEnvelope::from_query_and_body(
q,
serde_json::json!({
"tool_name": "Bash",
"tool_input": {},
"tool_response": [{"type": "text", "text": "MARKER_OUTPUT_123"}],
}),
);
let body = env.body_excerpt.expect("post-tool body");
assert!(
body.contains("MARKER_OUTPUT_123"),
"array tool_response text should be captured: {body:?}"
);
assert!(
!body.contains("(no output captured)"),
"should not fall back when output is present: {body:?}"
);
}
/// An object-shaped `tool_response` is serialized into the body rather than
/// dropped.
#[test]
fn post_tool_excerpt_captures_object_tool_response() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let env = HookEnvelope::from_query_and_body(
q,
serde_json::json!({
"tool_name": "Read",
"tool_input": {},
"tool_response": {"stdout": "MARKER_OBJ_456"},
}),
);
let body = env.body_excerpt.expect("post-tool body");
assert!(
body.contains("MARKER_OBJ_456"),
"object tool_response should be serialized into the body: {body:?}"
);
}
/// Cursor runs the Claude Code hooks too, sending its own payload with
/// Claude's `tool_name`/`tool_input` aliases and the result as a JSON
/// string in `tool_output`. The payload marks the event as Cursor's, and
/// Cursor was absent from `closed_tool_agent`, so its tool observations
/// were stored with no title or body (captured live from Cursor 3.24.9).
#[test]
fn cursor_tool_events_keep_their_family_title_and_output() {
let post = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({
"conversation_id": "17689370-2e8e-4dfd-bcd0-7e5bb9cd19ed",
"session_id": "17689370-2e8e-4dfd-bcd0-7e5bb9cd19ed",
"hook_event_name": "postToolUse",
"cursor_version": "3.24.9",
"tool_name": "Shell",
"tool_input": {"command": "ls", "cwd": "", "timeout": 30000},
"tool_output": "{\"output\":\"MARKER_CURSOR_OUTPUT\",\"exitCode\":0}",
"tool_use_id": "9fc522a1-2a0e-4847-9ffc-24256e023574",
"cwd": "",
"workspace_roots": [],
}),
);
assert_eq!(post.agent, AgentKind::Cursor);
assert_eq!(post.title_hint.as_deref(), Some("tool non-file"));
let body = post.body_excerpt.expect("cursor post-tool body");
assert!(body.contains("MARKER_CURSOR_OUTPUT"), "{body:?}");
let pre = HookEnvelope::from_query_and_body(
HookQuery {
event: "pre-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({
"session_id": "17689370-2e8e-4dfd-bcd0-7e5bb9cd19ed",
"hook_event_name": "preToolUse",
"cursor_version": "3.24.9",
"tool_name": "Shell",
"tool_input": {"command": "ls", "cwd": "", "timeout": 30000},
"tool_use_id": "9fc522a1-2a0e-4847-9ffc-24256e023574",
}),
);
assert_eq!(pre.title_hint.as_deref(), Some("tool non-file"));
assert!(pre.body_excerpt.is_some_and(|body| !body.is_empty()));
}
/// Kiro CLI's tool hooks carry `tool_name` and `tool_input`, and its
/// `PostToolUse` adds `tool_response`: a plain string on the v3 engine
/// (live capture, Kiro CLI 2.16.2) and an object with a `success` flag on
/// v2. The capture policy already read this shape, but Kiro was absent from
/// `closed_tool_agent`, so its tool observations were stored with no title
/// or body, the failure mode Grok had in #931.
#[test]
fn kiro_cli_tool_events_keep_their_family_title_and_output() {
let v3 = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("kiro-cli".into()),
..Default::default()
},
serde_json::json!({
"hook_event_name": "PostToolUse",
"session_id": "kiro-v3-session",
"cwd": "/workspace/project",
"tool_name": "read_file",
"tool_input": {"path": "/workspace/project/sample.txt"},
"tool_response": "MARKER_KIRO_V3_OUTPUT",
}),
);
assert_eq!(v3.agent, AgentKind::KiroCli);
assert_eq!(v3.title_hint.as_deref(), Some("tool file"));
let body = v3.body_excerpt.expect("kiro v3 post-tool body");
assert!(body.contains("MARKER_KIRO_V3_OUTPUT"), "{body:?}");
let v2 = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("kiro-cli".into()),
..Default::default()
},
serde_json::json!({
"session_id": "kiro-v2-session",
"cwd": "/workspace/project",
"tool_name": "fs_read",
"tool_input": {"operations": [{"mode": "Line", "path": "src/lib.rs"}]},
"tool_response": {"success": true, "result": ["MARKER_KIRO_V2_OUTPUT"]},
}),
);
assert_eq!(v2.title_hint.as_deref(), Some("tool file"));
let body = v2.body_excerpt.expect("kiro v2 post-tool body");
assert!(body.contains("outcome: success"), "{body:?}");
assert!(body.contains("MARKER_KIRO_V2_OUTPUT"), "{body:?}");
let pre = HookEnvelope::from_query_and_body(
HookQuery {
event: "pre-tool-use".into(),
agent: Some("kiro-cli".into()),
..Default::default()
},
serde_json::json!({
"hook_event_name": "PreToolUse",
"session_id": "kiro-v3-session",
"cwd": "/workspace/project",
"tool_name": "read_file",
"tool_input": {"path": "/workspace/project/sample.txt"},
}),
);
assert_eq!(pre.title_hint.as_deref(), Some("tool file"));
assert!(pre.body_excerpt.is_some_and(|body| !body.is_empty()));
}
/// Gemini CLI's AfterTool carries `tool_name`, `tool_input` and a
/// `tool_response` of `{llmContent, returnDisplay, error?}`, and BeforeTool
/// the first two (docs/hooks/reference.md and `hookEventHandler.ts`,
/// v0.66.0). Gemini was absent from `closed_tool_agent`, so its tool
/// observations were stored with no title or body, the failure mode Grok
/// had in #931. The body keeps the model's `llmContent`, never
/// `returnDisplay`, which for an edit holds both whole versions of the file.
#[test]
fn gemini_cli_tool_events_keep_their_family_title_and_output() {
// Adds the base fields every Gemini hook input carries.
let gemini = |event: &str, mut body: serde_json::Value| {
let hook_event_name = if event == "pre-tool-use" {
"BeforeTool"
} else {
"AfterTool"
};
body["session_id"] = serde_json::json!("gemini-session");
body["transcript_path"] =
serde_json::json!("/home/u/.gemini/tmp/project/chats/session.json");
body["cwd"] = serde_json::json!("/workspace/project");
body["hook_event_name"] = serde_json::json!(hook_event_name);
body["timestamp"] = serde_json::json!("2026-10-31T12:00:00.000Z");
HookEnvelope::from_query_and_body(
HookQuery {
event: event.into(),
agent: Some("gemini-cli".into()),
..Default::default()
},
body,
)
};
let edit = gemini(
"post-tool-use",
serde_json::json!({
"tool_name": "replace",
"tool_input": {"file_path": "/workspace/project/src/lib.rs", "old_string": "a", "new_string": "b"},
"tool_response": {
"llmContent": "Successfully modified file: src/lib.rs (1 replacements). MARKER_GEMINI_EDIT",
"returnDisplay": {
"fileDiff": "@@ -1 +1 @@",
"fileName": "lib.rs",
"originalContent": "SENTINEL_ORIGINAL_FILE",
"newContent": "SENTINEL_NEW_FILE",
},
},
}),
);
assert_eq!(edit.agent, AgentKind::GeminiCli);
assert_eq!(edit.title_hint.as_deref(), Some("tool file"));
let body = edit.body_excerpt.expect("gemini edit body");
assert!(body.contains("outcome: success"), "{body:?}");
assert!(body.contains("MARKER_GEMINI_EDIT"), "{body:?}");
assert!(!body.contains("SENTINEL_ORIGINAL_FILE"), "{body:?}");
assert!(!body.contains("SENTINEL_NEW_FILE"), "{body:?}");
// `llmContent` can be a Part list; its texts are kept in order.
let shell = gemini(
"post-tool-use",
serde_json::json!({
"tool_name": "run_shell_command",
"tool_input": {"command": "ls"},
"tool_response": {
"llmContent": [{"text": "MARKER_PART_ONE"}, {"text": "MARKER_PART_TWO"}],
"returnDisplay": "SENTINEL_DISPLAY",
},
}),
);
assert_eq!(shell.title_hint.as_deref(), Some("tool non-file"));
let body = shell.body_excerpt.expect("gemini shell body");
assert!(
body.contains("MARKER_PART_ONE\nMARKER_PART_TWO"),
"{body:?}"
);
assert!(!body.contains("SENTINEL_DISPLAY"), "{body:?}");
// A failed call: `error` makes the outcome an error, and its message
// stands in when `llmContent` is empty.
let failed = gemini(
"post-tool-use",
serde_json::json!({
"tool_name": "read_file",
"tool_input": {"file_path": "/workspace/project/missing.md"},
"tool_response": {
"llmContent": "",
"returnDisplay": "SENTINEL_DISPLAY",
"error": {"message": "MARKER_GEMINI_ERROR", "type": "FILE_NOT_FOUND"},
},
}),
);
let body = failed.body_excerpt.expect("gemini failure body");
assert!(body.contains("outcome: error"), "{body:?}");
assert!(body.contains("MARKER_GEMINI_ERROR"), "{body:?}");
let pre = gemini(
"pre-tool-use",
serde_json::json!({"tool_name": "read_file", "tool_input": {"file_path": "README.md"}}),
);
assert_eq!(pre.title_hint.as_deref(), Some("tool file"));
assert!(pre.body_excerpt.is_some_and(|body| !body.is_empty()));
}
/// Claude Code's Windows `PowerShell` tool shares Bash's payload shape but
/// fell through to the unknown family, so its output was never stored
/// (#1186). The PreToolUse body still never carries the command.
#[test]
fn claude_code_powershell_tool_keeps_its_family_title_and_output() {
let post = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({
"session_id": "s",
"tool_name": "PowerShell",
"tool_input": {"command": "Get-ChildItem SENTINEL_COMMAND", "description": "list"},
"tool_response": {"stdout": "MARKER_POWERSHELL_1186", "stderr": ""},
"tool_use_id": "toolu_1186",
}),
);
assert_eq!(post.title_hint.as_deref(), Some("tool non-file"));
let body = post.body_excerpt.expect("powershell post-tool body");
assert!(body.contains("tool_family: non-file"), "{body:?}");
assert!(body.contains("MARKER_POWERSHELL_1186"), "{body:?}");
let pre = HookEnvelope::from_query_and_body(
HookQuery {
event: "pre-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({
"session_id": "s",
"tool_name": "PowerShell",
"tool_input": {"command": "Get-ChildItem SENTINEL_COMMAND"},
"tool_use_id": "toolu_1186",
}),
);
assert_eq!(pre.title_hint.as_deref(), Some("tool non-file"));
let body = pre.body_excerpt.expect("powershell pre-tool body");
assert!(!body.contains("SENTINEL_COMMAND"), "{body:?}");
}
/// A Claude Code `PostToolUseFailure` lands on the post-tool-use channel
/// with `outcome: error` and the error text, never the tool's arguments.
#[test]
fn claude_code_post_tool_use_failure_records_the_error_outcome_and_text() {
let failure = HookEnvelope::from_query_and_body(
HookQuery {
event: "PostToolUseFailure".into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({
"session_id": "s",
"hook_event_name": "PostToolUseFailure",
"tool_name": "Bash",
"tool_input": {"command": "npm test SENTINEL_COMMAND", "description": "Run test suite"},
"tool_use_id": "toolu_01ABC123",
"error": "Exit code 1
Error: Cannot find module 'express'",
"is_interrupt": false,
"duration_ms": 4187
}),
);
assert_eq!(failure.event, HookEvent::PostToolUse);
assert_eq!(failure.title_hint.as_deref(), Some("tool non-file"));
let body = failure.body_excerpt.expect("failure body");
assert!(body.contains("tool_family: non-file"), "{body:?}");
assert!(
body.contains(
"
outcome: error
---
"
),
"{body:?}"
);
assert!(body.contains("Exit code 1"), "{body:?}");
assert!(body.contains("Cannot find module 'express'"), "{body:?}");
assert!(!body.contains("SENTINEL_COMMAND"), "{body:?}");
// Control: a success body is unchanged.
let success = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({
"session_id": "s",
"hook_event_name": "PostToolUse",
"tool_name": "Bash",
"tool_input": {"command": "npm test"},
"tool_response": {"stdout": "42 passing", "stderr": "", "interrupted": false},
"tool_use_id": "toolu_01ABC124",
}),
);
let body = success.body_excerpt.expect("success body");
assert!(
body.contains(
"
outcome: unknown
---
"
),
"{body:?}"
);
assert!(body.contains("42 passing"), "{body:?}");
}
/// Grok Build CLI posts a `PostToolUse` with Claude Code's snake_case
/// aliases (`tool_name` / `tool_input` / `tool_use_id`). It was absent from
/// both `closed_tool_agent` and the `tool_observation_metadata` match, so
/// every Grok tool observation was stored with an empty body (#931).
#[test]
fn grok_post_tool_excerpt_captures_tool_response() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("grok".into()),
..Default::default()
};
let env = HookEnvelope::from_query_and_body(
q,
serde_json::json!({
"tool_name": "Bash",
"tool_input": {"command": "ls"},
"tool_use_id": "call_grok_1",
"tool_response": {"stdout": "MARKER_GROK_931"},
}),
);
let body = env
.body_excerpt
.expect("grok post-tool body should not be empty");
assert!(
body.contains("MARKER_GROK_931"),
"grok tool_response should be serialized into the body: {body:?}"
);
}
/// Copilot CLI's VS-Code-compatible `PostToolUse` nests the output at
/// `tool_result.text_result_for_llm` (#1040). Without Copilot in
/// `closed_tool_agent` the observation would be stored with an empty body,
/// the #931 failure mode Grok had; without the dedicated path the
/// `result_type` envelope would leak into the excerpt.
#[test]
fn copilot_cli_post_tool_excerpt_reads_text_result_for_llm() {
let q = HookQuery {
event: "post-tool-use".into(),
agent: Some("copilot-cli".into()),
..Default::default()
};
let env = HookEnvelope::from_query_and_body(
q,
serde_json::json!({
"hook_event_name": "PostToolUse",
"session_id": "copilot-session",
"cwd": "/repo",
"tool_name": "bash",
"tool_input": {"command": "ls"},
"tool_result": {
"result_type": "success",
"text_result_for_llm": "MARKER_COPILOT_1040",
},
}),
);
let body = env
.body_excerpt
.expect("copilot-cli post-tool body should not be empty");
assert!(body.contains("MARKER_COPILOT_1040"), "{body:?}");
assert!(body.contains("outcome: success"), "{body:?}");
assert!(!body.contains("result_type"), "{body:?}");
}
/// End-to-end: a native-hook user prompt (`event=user-prompt-submit`,
/// string `prompt`) maps to `UserPrompt` and keeps its body text.
#[test]
fn native_user_prompt_submit_keeps_prompt_body() {
let q = HookQuery {
event: "user-prompt-submit".into(),
agent: Some("claude-code".into()),
..Default::default()
};
let env = HookEnvelope::from_query_and_body(
q,
serde_json::json!({ "session_id": "s1", "prompt": "MARKER_PROMPT_789" }),
);
assert_eq!(env.event, HookEvent::UserPrompt);
assert_eq!(env.body_excerpt.as_deref(), Some("MARKER_PROMPT_789"));
}
#[test]
fn qwen_user_prompt_uses_only_submission_provenance() {
let query = HookQuery {
event: "user-prompt-submit".into(),
agent: Some("qwen-code".into()),
..Default::default()
};
let envelope = HookEnvelope::from_query_and_body(
query.clone(),
serde_json::json!({
"session_id": "qwen-session",
"prompt": "AUTOMATED_CONTINUATION_MUST_NOT_BE_CAPTURED",
"submitted_prompt": "MARKER_QWEN_USER_PROMPT"
}),
);
assert_eq!(
envelope.title_hint.as_deref(),
Some("MARKER_QWEN_USER_PROMPT")
);
assert_eq!(
envelope.body_excerpt.as_deref(),
Some("MARKER_QWEN_USER_PROMPT")
);
let automated = HookEnvelope::from_query_and_body(
query,
serde_json::json!({
"session_id": "qwen-session",
"prompt": "AUTOMATED_CONTINUATION_MUST_NOT_BE_CAPTURED"
}),
);
assert!(automated.title_hint.is_none());
assert!(automated.body_excerpt.is_none());
}
// 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)}]}}),
);
// Extraction no longer caps: the sanitizer must see the full text
// before any byte limit runs (#1114). The cap itself is asserted at
// the ingest funnel, where it is applied to the scrubbed body.
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, identity) in [
// An MCP tool keeps its validated names (#1522), never its input
// or output.
("mcp__fs__read", "\nmcp_server: fs\nmcp_tool: 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(
format!(
"tool_family: unknown\ntool_call_id: call-unknown{identity}\noutcome: unknown"
)
.as_str()
)
);
}
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 = [
(
"claude-code",
serde_json::json!({"tool_name":"Bash","tool_input":{"command":"SENTINEL_COMMAND","path":"SENTINEL_PATH"},"tool_use_id":"claude-1","output":"SENTINEL_OUTPUT"}),
"claude-1",
"unknown",
),
(
"open-code",
serde_json::json!({"tool":"bash","args":{"command":"SENTINEL_COMMAND"},"callID":"open-1","output":"SENTINEL_OUTPUT"}),
"open-1",
"unknown",
),
(
"pi",
serde_json::json!({"tool":"bash","args":{"command":"SENTINEL_COMMAND"},"callID":"pi-1","isError":true,"output":"SENTINEL_OUTPUT"}),
"pi-1",
"error",
),
];
for (agent, raw, id, outcome) in fixtures {
let pre = HookEnvelope::from_query_and_body(
HookQuery {
event: "pre-tool-use".into(),
agent: Some(agent.into()),
..Default::default()
},
raw.clone(),
);
let pre_body = pre.body_excerpt.expect("pre summary");
assert!(pre_body.contains(id));
for sentinel in ["SENTINEL_COMMAND", "SENTINEL_PATH", "SENTINEL_OUTPUT"] {
assert!(!pre_body.contains(sentinel));
}
let post = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some(agent.into()),
..Default::default()
},
raw,
);
let post_body = post.body_excerpt.expect("post summary");
assert!(post_body.contains(&format!("outcome: {outcome}")));
}
let long = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({"tool_name":"Bash","tool_input":{},"tool_use_id":"utf8-1","output": "é".repeat(2_000)}),
);
let body = long.body_excerpt.unwrap();
assert!(body.len() > 2_000);
let capped = truncate_utf8_bytes(&body, durable_body_cap(HookEvent::PostToolUse));
assert!(capped.len() <= 2_000);
}
#[test]
fn unknown_closed_tool_post_never_includes_output_or_name() {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({"tool_name":"ARBITRARY_TOOL_SENTINEL","tool_use_id":"unknown-1","output":"OUTPUT_SENTINEL"}),
);
let body = env.body_excerpt.unwrap();
assert!(body.contains("tool_family: unknown"));
assert!(body.contains("tool_call_id: unknown-1"));
assert!(body.contains("outcome: unknown"));
assert!(!body.contains("ARBITRARY_TOOL_SENTINEL"));
assert!(!body.contains("OUTPUT_SENTINEL"));
}
#[test]
fn claude_and_opencode_paired_summaries_share_agent_ids() {
for (agent, pre_raw, post_raw, id) in [
(
"claude-code",
serde_json::json!({"tool_name":"Bash","tool_input":{"command":"PRE_COMMAND_SENTINEL"},"tool_use_id":"claude-pair"}),
serde_json::json!({"tool_name":"Bash","tool_use_id":"claude-pair","output":"POST_OUTPUT"}),
"claude-pair",
),
(
"open-code",
serde_json::json!({"tool":"bash","args":{"path":"PRE_PATH_SENTINEL"},"callID":"open-pair"}),
serde_json::json!({"tool":"bash","callID":"open-pair","output":"POST_OUTPUT"}),
"open-pair",
),
] {
let pre = HookEnvelope::from_query_and_body(
HookQuery {
event: "pre-tool-use".into(),
agent: Some(agent.into()),
..Default::default()
},
pre_raw,
);
let post = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some(agent.into()),
..Default::default()
},
post_raw,
);
let pre_body = pre.body_excerpt.unwrap();
let post_body = post.body_excerpt.unwrap();
assert!(pre_body.contains(id) && post_body.contains(id));
assert!(post_body.contains("POST_OUTPUT"));
assert!(!pre_body.contains("SENTINEL"));
}
}
#[test]
fn antigravity_omits_id_and_unsupported_pre_has_no_body() {
let antigravity = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({"toolCall":{"name":"run_command","args":{}},"error":"private"}),
);
let body = antigravity.body_excerpt.unwrap();
assert!(body.contains("outcome: error"));
assert!(!body.contains("tool_call_id"));
let unsupported = HookEnvelope::from_query_and_body(
HookQuery {
event: "pre-tool-use".into(),
agent: Some("other".into()),
..Default::default()
},
serde_json::json!({"tool_name":"Bash","tool_input":{"command":"private"}}),
);
assert!(unsupported.body_excerpt.is_none());
}
#[test]
fn unsupported_and_stop_tool_payloads_never_render_content() {
for event in ["pre-tool-use", "post-tool-use"] {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: event.into(),
agent: Some("other".into()),
..Default::default()
},
serde_json::json!({"tool":"SENTINEL_TOOL","args":{"command":"SENTINEL_COMMAND","path":"SENTINEL_PATH"},"output":"SENTINEL_OUTPUT"}),
);
assert!(env.title_hint.is_none());
assert!(env.body_excerpt.is_none());
}
let stop = HookEnvelope::from_query_and_body(
HookQuery {
event: "stop".into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({"last_assistant_message":"SENTINEL_ASSISTANT"}),
);
assert!(stop.body_excerpt.is_none());
}
#[test]
fn antigravity_outcome_and_call_id_boundaries_are_closed() {
let absent = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({"toolCall":{"name":"run_command","args":{}}}),
);
assert!(absent.body_excerpt.unwrap().contains("outcome: unknown"));
for (error, outcome) in [
(serde_json::json!(null), "unknown"),
(serde_json::json!(""), "unknown"),
(serde_json::json!("failed"), "error"),
] {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({"toolCall":{"name":"run_command","args":{}},"error":error}),
);
assert!(
env.body_excerpt
.unwrap()
.contains(&format!("outcome: {outcome}"))
);
}
let id = "a".repeat(129);
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "pre-tool-use".into(),
agent: Some("claude-code".into()),
..Default::default()
},
serde_json::json!({"tool_name":"Bash","tool_input":{},"tool_use_id":id}),
);
assert!(!env.body_excerpt.unwrap().contains("tool_call_id"));
}
#[test]
fn antigravity_native_file_and_search_tools_render_captured_content() {
for (tool, args, family) in [
(
"view_file",
serde_json::json!({"TargetFile": "src/main.rs"}),
"file",
),
(
"replace_file_content",
serde_json::json!({"TargetFile": "src/main.rs"}),
"file",
),
(
"list_dir",
serde_json::json!({"DirectoryPath": "src"}),
"search-list",
),
(
"grep_search",
serde_json::json!({"SearchPath": "src"}),
"search-list",
),
] {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({
"toolCall": {"name": tool, "args": args},
"tool_response": "SENTINEL_CONTENT",
}),
);
let body = env.body_excerpt.unwrap();
assert!(
body.contains(&format!("tool_family: {family}")),
"tool: {tool}, body: {body}"
);
assert!(
body.contains("SENTINEL_CONTENT"),
"tool: {tool}, body: {body}"
);
}
}
#[test]
fn antigravity_edit_tools_capture_real_written_content() {
// Fixture shapes captured from a live antigravity-cli session. The hook
// never sends a top-level result; the written content lives in args.
let write_to_file = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({
"toolCall": {
"name": "write_to_file",
"args": {
"CodeContent": "# Scratch Test File 09\n\nLine 1: first line\n",
"Description": "Temporary scratch file",
"Overwrite": true,
"TargetFile": "/repo/scratch-test-09.md"
}
}
}),
);
let body = write_to_file.body_excerpt.unwrap();
assert!(body.contains("tool_family: file"));
assert!(body.contains("Scratch Test File 09"));
let replace_file_content = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({
"toolCall": {
"name": "replace_file_content",
"args": {
"TargetFile": "/repo/1-visao.md",
"TargetContent": "old line",
"ReplacementContent": "new line REPLACED_SENTINEL",
"Instruction": "Add debug test comment"
}
}
}),
);
let body = replace_file_content.body_excerpt.unwrap();
assert!(body.contains("tool_family: file"));
assert!(body.contains("REPLACED_SENTINEL"));
let multi_replace = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({
"toolCall": {
"name": "multi_replace_file_content",
"args": {
"TargetFile": "/repo/scratch-test-09.md",
"Instruction": "Edit Line 1 and Line 4",
"ReplacementChunks": [
{
"TargetContent": "Line 1: first line",
"ReplacementContent": "Line 1: first line edited",
"StartLine": 3,
"EndLine": 3,
"AllowMultiple": false
},
{
"TargetContent": "Line 4: fourth line",
"ReplacementContent": "Line 4: fourth line edited",
"StartLine": 6,
"EndLine": 6,
"AllowMultiple": false
}
]
}
}
}),
);
let body = multi_replace.body_excerpt.unwrap();
assert!(body.contains("tool_family: file"));
assert!(body.contains("Line 1: first line edited"));
assert!(body.contains("Line 4: fourth line edited"));
}
#[test]
fn antigravity_failed_edit_prefers_error_over_attempted_content() {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({
"error": "EDIT_FAILED_SENTINEL",
"toolCall": {
"name": "replace_file_content",
"args": {
"TargetFile": "/repo/src/main.rs",
"ReplacementContent": "CONTENT_WAS_NOT_WRITTEN"
}
}
}),
);
let body = env.body_excerpt.unwrap();
assert!(body.contains("outcome: error"));
assert!(body.contains("EDIT_FAILED_SENTINEL"));
assert!(!body.contains("CONTENT_WAS_NOT_WRITTEN"));
}
#[test]
fn antigravity_generic_tools_and_unrelated_events_fail_closed() {
for tool in ["read_url_content", "read_resource", "call_mcp_tool"] {
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({
"toolCall": {
"name": tool,
"args": {"message": "NESTED_ARGUMENT_SENTINEL"}
},
"tool_response": "UNPROVEN_OUTPUT_SENTINEL"
}),
);
assert_eq!(
env.body_excerpt.as_deref(),
Some("tool_family: unknown\noutcome: unknown")
);
}
let notification = HookEnvelope::from_query_and_body(
HookQuery {
event: "notification".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({
"toolCall": {
"args": {"message": "NESTED_ARGUMENT_SENTINEL"}
}
}),
);
assert!(notification.body_excerpt.is_none());
}
#[test]
fn antigravity_post_tool_use_renders_client_enriched_output() {
// The client hook reads `output.txt` and sends it as `tool_response`.
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({
"conversationId": "conv-1",
"toolCall": {
"name": "run_command",
"args": {"CommandLine": "cargo test"}
},
"stepIdx": 42,
"tool_response": "cargo test: 10 passed"
}),
);
let body = env.body_excerpt.expect("body excerpt should be present");
assert!(body.contains("tool_family: non-file"));
assert!(body.contains("cargo test: 10 passed"));
}
/// Parsing a hook payload never opens a file the payload names.
///
/// `artifactDirectoryPath` and `transcriptPath` come from the caller. If
/// envelope parsing (which runs on the server for every `/hook` and
/// `/hook/batch` item) followed them, any capture credential could copy
/// `<any dir>/.system_generated/steps/<n>/output.txt` from the server's
/// disk into a project it can read back.
#[test]
fn envelope_parsing_never_reads_a_payload_named_antigravity_artifact() {
let dir = tempfile::tempdir().unwrap();
let logs = dir.path().join(".system_generated").join("logs");
let step_dir = dir
.path()
.join(".system_generated")
.join("steps")
.join("42");
std::fs::create_dir_all(&step_dir).unwrap();
std::fs::create_dir_all(&logs).unwrap();
std::fs::write(step_dir.join("output.txt"), "SERVER_DISK_SENTINEL\n").unwrap();
let transcript = logs.join("transcript.jsonl");
for locator in [
serde_json::json!({ "artifactDirectoryPath": dir.path().to_str().unwrap() }),
serde_json::json!({ "transcriptPath": transcript.to_str().unwrap() }),
] {
let mut raw = serde_json::json!({
"conversationId": "conv-1",
"toolCall": {
"name": "run_command",
"args": {"CommandLine": "cat secrets"}
},
"stepIdx": 42
});
raw.as_object_mut()
.unwrap()
.extend(locator.as_object().unwrap().clone());
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
raw,
);
let body = env.body_excerpt.unwrap_or_default();
assert!(
!body.contains("SERVER_DISK_SENTINEL"),
"envelope parsing read a file named by the payload ({locator}): {body}"
);
}
}
#[test]
fn antigravity_post_tool_use_preserves_edit_tool_code_content() {
let dir = tempfile::tempdir().unwrap();
let step_dir = dir.path().join(".system_generated").join("steps").join("1");
std::fs::create_dir_all(&step_dir).unwrap();
std::fs::write(step_dir.join("output.txt"), "Created file test.rs\n").unwrap();
let env = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("antigravity-cli".into()),
..Default::default()
},
serde_json::json!({
"conversationId": "conv-1",
"toolCall": {
"name": "write_to_file",
"args": {
"TargetFile": "/workspace/test.rs",
"CodeContent": "fn preserved_code() {}"
}
},
"stepIdx": 1,
"artifactDirectoryPath": dir.path().to_str().unwrap()
}),
);
let body = env.body_excerpt.expect("body excerpt should be present");
assert!(body.contains("fn preserved_code() {}"));
assert!(!body.contains("Created file test.rs"));
}
#[test]
fn pi_and_omp_post_outcomes_and_stable_id_are_rendered() {
for agent in ["pi", "omp"] {
for (is_error, outcome) in [
(Some(false), "success"),
(Some(true), "error"),
(None, "unknown"),
] {
let mut raw = serde_json::json!({"tool":"bash","args":{},"callID":"pi-stable-190","output":"result"});
if let Some(is_error) = is_error {
raw["isError"] = serde_json::json!(is_error);
}
let pre = HookEnvelope::from_query_and_body(
HookQuery {
event: "pre-tool-use".into(),
agent: Some(agent.into()),
..Default::default()
},
raw.clone(),
);
let post = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some(agent.into()),
..Default::default()
},
raw,
);
assert!(
pre.body_excerpt
.unwrap()
.contains("tool_call_id: pi-stable-190")
);
let body = post.body_excerpt.unwrap();
assert!(body.contains("tool_call_id: pi-stable-190"));
assert!(
body.contains(&format!("outcome: {outcome}")),
"{agent}: {body}"
);
}
}
}
#[test]
fn omp_tool_events_keep_family_call_id_and_output_but_not_arguments() {
// `build_pi_extension` in the CLI derives the Pi extension from the OMP
// one, so OMP posts this exact tool payload shape.
let pre = HookEnvelope::from_query_and_body(
HookQuery {
event: "pre-tool-use".into(),
agent: Some("omp".into()),
..Default::default()
},
serde_json::json!({"tool":"bash","callID":"omp-1","args":{"command":"SENTINEL_COMMAND"}}),
);
assert_eq!(pre.title_hint.as_deref(), Some("tool non-file"));
assert_eq!(
pre.body_excerpt.as_deref(),
Some("tool_family: non-file\ntool_call_id: omp-1")
);
let post = HookEnvelope::from_query_and_body(
HookQuery {
event: "post-tool-use".into(),
agent: Some("omp".into()),
..Default::default()
},
serde_json::json!({"tool":"bash","callID":"omp-1","args":{"command":"SENTINEL_COMMAND"},"output":"tests passed","details":{"diff":"SENTINEL_DETAILS"}}),
);
assert_eq!(post.title_hint.as_deref(), Some("tool non-file"));
assert_eq!(
post.body_excerpt.as_deref(),
Some("tool_family: non-file\ntool_call_id: omp-1\noutcome: unknown\n---\ntests passed")
);
}
fn claude_tool_event(event: &str, body: serde_json::Value) -> HookEnvelope {
HookEnvelope::from_query_and_body(
HookQuery {
event: event.into(),
agent: Some("claude-code".into()),
..Default::default()
},
body,
)
}
/// `[ingest] record_tool_names`: a Claude Code shell call keeps its family
/// first and gains its name, never its command.
#[test]
fn record_tool_name_names_the_call_and_never_keeps_its_arguments() {
let mut env = claude_tool_event(
"PostToolUse",
serde_json::json!({
"session_id": "s",
"tool_name": "Bash",
"tool_use_id": "toolu_1",
"tool_input": {"command": "curl -H 'Authorization: Bearer sk-secret' https://x"},
"tool_response": {"stdout": "ok"}
}),
);
assert_eq!(env.title_hint.as_deref(), Some("tool non-file"));
env.record_tool_name();
assert_eq!(env.title_hint.as_deref(), Some("tool non-file: Bash"));
let body = env.body_excerpt.as_deref().unwrap();
assert!(
body.starts_with("tool_family: non-file\ntool_name: Bash\ntool_call_id: toolu_1\n"),
"{body}"
);
assert!(
!body.contains("curl") && !body.contains("sk-secret"),
"{body}"
);
assert_eq!(
tool_family_from_title(env.title_hint.as_deref().unwrap()),
Some(ToolFamily::NonFile)
);
}
/// Claude Code's `Skill` and `Agent` calls also keep the skill and the
/// subagent type (<https://code.claude.com/docs/en/hooks>), and nothing
/// else from their input.
#[test]
fn record_tool_name_keeps_the_skill_and_the_subagent_type() {
let mut skill = claude_tool_event(
"PreToolUse",
serde_json::json!({
"session_id": "s",
"tool_name": "Skill",
"tool_use_id": "toolu_2",
"tool_input": {"skill": "visual-explainer:diff-review", "args": "free text the user typed"}
}),
);
skill.record_tool_name();
assert_eq!(skill.title_hint.as_deref(), Some("tool unknown: Skill"));
let body = skill.body_excerpt.as_deref().unwrap();
assert!(
body.contains("\ntool_name: Skill\nskill: visual-explainer:diff-review\n"),
"{body}"
);
assert!(!body.contains("free text"), "{body}");
for name in ["Agent", "Task"] {
let mut agent = claude_tool_event(
"PreToolUse",
serde_json::json!({
"session_id": "s",
"tool_name": name,
"tool_input": {"subagent_type": "Explore", "prompt": "find the auth code", "description": "search"}
}),
);
agent.record_tool_name();
assert_eq!(
agent.title_hint.as_deref(),
Some(format!("tool unknown: {name}").as_str())
);
let body = agent.body_excerpt.as_deref().unwrap();
assert!(body.contains("\nsubagent_type: Explore"), "{body}");
assert!(!body.contains("find the auth code"), "{body}");
}
}
/// Free text in a name or descriptor field is refused whole: no partial
/// name, no truncated skill.
#[test]
fn record_tool_name_refuses_free_text_names_and_descriptors() {
let mut spaced = claude_tool_event(
"PreToolUse",
serde_json::json!({
"session_id": "s",
"tool_name": "Bash; rm -rf /",
"tool_input": {"command": "ls"}
}),
);
spaced.record_tool_name();
assert_eq!(spaced.title_hint.as_deref(), Some("tool unknown"));
assert!(
!spaced
.body_excerpt
.as_deref()
.unwrap()
.contains("tool_name")
);
let mut long = claude_tool_event(
"PreToolUse",
serde_json::json!({"session_id": "s", "tool_name": "x".repeat(65), "tool_input": {}}),
);
long.record_tool_name();
assert_eq!(long.title_hint.as_deref(), Some("tool unknown"));
let mut skill = claude_tool_event(
"PreToolUse",
serde_json::json!({
"session_id": "s",
"tool_name": "Skill",
"tool_input": {"skill": "review then email [email protected]"}
}),
);
skill.record_tool_name();
assert_eq!(skill.title_hint.as_deref(), Some("tool unknown: Skill"));
let body = skill.body_excerpt.as_deref().unwrap();
assert!(
!body.contains("skill:") && !body.contains("alice"),
"{body}"
);
}
/// The descriptors are Claude Code's own fields: another agent's `Skill`
/// tool keeps its name only.
#[test]
fn record_tool_name_reads_descriptors_for_claude_code_only() {
let mut env = HookEnvelope::from_query_and_body(
HookQuery {
event: "PreToolUse".into(),
agent: Some("codex".into()),
..Default::default()
},
serde_json::json!({"session_id": "s", "tool_name": "Skill", "tool_input": {"skill": "x"}}),
);
env.record_tool_name();
assert_eq!(env.title_hint.as_deref(), Some("tool unknown: Skill"));
assert!(!env.body_excerpt.as_deref().unwrap().contains("skill:"));
}
/// Off by default: without the call, the envelope is what it always was.
#[test]
fn an_envelope_is_unnamed_until_record_tool_name_runs() {
let env = claude_tool_event(
"PostToolUse",
serde_json::json!({
"session_id": "s",
"tool_name": "Edit",
"tool_use_id": "toolu_3",
"tool_input": {"file_path": "/repo/a.rs", "old_string": "a", "new_string": "b"},
"tool_response": {"filePath": "/repo/a.rs"}
}),
);
assert_eq!(env.title_hint.as_deref(), Some("tool file"));
assert!(!env.body_excerpt.as_deref().unwrap().contains("tool_name"));
}
/// A title that is not this module's bare family label (a metadata-only
/// rebuild's bare `non-file`, or one already named) is never renamed.
#[test]
fn record_tool_name_leaves_other_titles_alone() {
let mut env = claude_tool_event(
"PreToolUse",
serde_json::json!({"session_id": "s", "tool_name": "Bash", "tool_input": {"command": "ls"}}),
);
env.title_hint = Some("non-file".into());
env.record_tool_name();
assert_eq!(env.title_hint.as_deref(), Some("non-file"));
let mut twice = claude_tool_event(
"PreToolUse",
serde_json::json!({"session_id": "s", "tool_name": "Bash", "tool_input": {"command": "ls"}}),
);
twice.record_tool_name();
twice.record_tool_name();
assert_eq!(twice.title_hint.as_deref(), Some("tool non-file: Bash"));
}
#[test]
fn named_tool_titles_keep_their_family_and_list_by_name() {
assert!(is_safe_tool_title("tool file: Edit"));
assert_eq!(
tool_family_from_title("tool file: Edit"),
Some(ToolFamily::File)
);
assert_eq!(listable_tool_name("tool file: Edit"), Some("Edit"));
assert_eq!(tool_title_display("tool file: Edit"), "Edit");
assert_eq!(listable_tool_name("tool non-file"), None);
assert_eq!(tool_title_display("tool non-file"), "tool non-file");
assert_eq!(listable_tool_name("edit"), Some("edit"));
assert_eq!(listable_tool_name(""), None);
for not_ours in ["tool file: two words", "tool nope: Bash", "Tool file: Edit"] {
assert!(!is_safe_tool_title(not_ours), "{not_ours}");
assert_eq!(tool_family_from_title(not_ours), None, "{not_ours}");
}
}
}