Skip to content

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

Rust

fix(hooks): count tool family labels in the summary, stop naming them (#527)

Samir Hanna Verzaead9a5a79b70
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 69a4e7f5..95130e6d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Fixed
+- Stopped a session summary spending its characters on tool family labels. The
+ summary #477 added names the busiest tools, but for the seven agents that go
+ through `closed_tool_agent` — Claude Code among them — a tool observation's
+ title is written by `safe_tool_title` as `tool <family>`, and `ToolFamily`
+ has four variants. Measured on a live 1,885-page instance, 21,136 of 29,804
+ `PostToolUse` observations (71%) carried one of three such literals against
+ 56 real tool names in the other 29%, and every tool mention in every summary
+ there was a family label: `580 completed tool calls across tool non-file,
+ tool unknown and tool file` spent 47 characters to say that some calls
+ touched files and some did not. Family labels are now counted but not named,
+ and a session with nothing else to name drops the clause instead of filling
+ it. The predicate lives beside the writer and is derived from the same serde
+ representation, so a new `ToolFamily` variant cannot escape it. (#527)
+
## [1.36.0] - 2026-08-29
### Added
diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rs
index 607a13b5..c48c4977 100644
--- a/crates/ai-memory-hooks/src/payload.rs
+++ b/crates/ai-memory-hooks/src/payload.rs
@@ -4,7 +4,7 @@ use ai_memory_core::{AgentKind, OBSERVATION_BODY_MAX_BYTES, ObservationKind, tru
use serde::{Deserialize, Serialize};
use crate::capture_policy::{
- ToolObservationMetadata, tool_observation_metadata, tool_observation_outcome,
+ ToolFamily, ToolObservationMetadata, tool_observation_metadata, tool_observation_outcome,
};
/// Durable excerpt ceiling for user prompts. Prompts retain more working
@@ -612,6 +612,22 @@ fn safe_tool_title(metadata: &ToolObservationMetadata) -> String {
)
}
+/// `true` when `title` is one this module produced from a [`ToolFamily`]
+/// rather than from the harness's own tool name.
+///
+/// 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.strip_prefix("tool ").is_some_and(|family| {
+ serde_json::from_value::<ToolFamily>(serde_json::Value::String(family.to_owned())).is_ok()
+ })
+}
+
fn safe_tool_body(
event: HookEvent,
metadata: Option<&ToolObservationMetadata>,
@@ -994,6 +1010,64 @@ fn normalize_token(value: &str, max_len: usize) -> Option<String> {
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,
+ });
+ 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);
diff --git a/crates/ai-memory-hooks/src/synth.rs b/crates/ai-memory-hooks/src/synth.rs
index 4b2950d5..540c7bed 100644
--- a/crates/ai-memory-hooks/src/synth.rs
+++ b/crates/ai-memory-hooks/src/synth.rs
@@ -14,7 +14,7 @@ use ai_memory_core::{
};
use jiff::tz::TimeZone;
-use crate::payload::truncate_for_title;
+use crate::payload::{is_safe_tool_title, truncate_for_title};
const RAW_OBSERVATION_MAX_LINES: usize = 500;
const RAW_OBSERVATION_HEAD_LINES: usize = 250;
@@ -232,24 +232,39 @@ fn session_summary(tally: &SessionTally<'_>) -> String {
let mut by_calls: Vec<(&str, usize)> =
tally.tool_counts.iter().map(|(k, v)| (*k, *v)).collect();
by_calls.sort_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.cmp(b.0)));
- let named: Vec<&str> = by_calls
+ // A `tool <family>` title is what `safe_tool_title` writes when the
+ // harness's own tool name is not carried through: a partition of the
+ // calls, never a name for them. Listing those spends the reader's
+ // attention to say "some of the calls touched files and some did
+ // not", so they are counted but not named, and a session with
+ // nothing else to name drops the clause rather than filling it.
+ let nameable: Vec<&str> = by_calls
.iter()
- .take(SUMMARY_MAX_NAMED_TOOLS)
.map(|(name, _)| *name)
+ .filter(|name| !is_safe_tool_title(name))
.collect();
- let tools = if by_calls.len() > SUMMARY_MAX_NAMED_TOOLS {
+ parts.push(if nameable.is_empty() {
+ format!("{calls} completed tool call{}", plural(calls))
+ } else {
+ let named: Vec<&str> = nameable
+ .iter()
+ .copied()
+ .take(SUMMARY_MAX_NAMED_TOOLS)
+ .collect();
+ let tools = if by_calls.len() > named.len() {
+ format!(
+ "{} and {} more",
+ join_and(&named),
+ by_calls.len() - named.len()
+ )
+ } else {
+ join_and(&named)
+ };
format!(
- "{} and {} more",
- join_and(&named),
- by_calls.len() - SUMMARY_MAX_NAMED_TOOLS
+ "{calls} completed tool call{} across {tools}",
+ plural(calls)
)
- } else {
- join_and(&named)
- };
- parts.push(format!(
- "{calls} completed tool call{} across {tools}",
- plural(calls)
- ));
+ });
}
if let (Some(start), Some(end)) = (tally.start, tally.end)
@@ -568,6 +583,44 @@ mod tests {
);
}
+ /// Measured on a live 1,885-page instance: 21,136 of 29,804 `PostToolUse`
+ /// observations (71%) carried one of three `tool <family>` literals,
+ /// against 56 real tool names in the other 29%. Every tool mention in
+ /// every summary on that instance was a family label, so the clause was
+ /// spending characters to say nothing.
+ #[test]
+ fn family_labels_are_counted_but_not_named() {
+ let mut observations = vec![obs(ObservationKind::UserPrompt, "do the thing")];
+ for (tool, calls) in [("tool non-file", 9), ("tool file", 4), ("tool unknown", 2)] {
+ for _ in 0..calls {
+ observations.push(obs(ObservationKind::PostToolUse, tool));
+ }
+ }
+ let summary = session_summary(&tally_session(&observations));
+ assert_eq!(summary, "1 prompt, 15 completed tool calls.");
+ assert!(
+ !summary.contains("across"),
+ "nothing nameable is left, so the clause must go rather than be filled: {summary}"
+ );
+ }
+
+ /// A session that mixes both keeps the names it has. The families still
+ /// count toward the total and toward "and N more", because they are real
+ /// groups of calls — they just are not worth a reader's attention.
+ #[test]
+ fn real_names_survive_alongside_family_labels() {
+ let mut observations = vec![obs(ObservationKind::UserPrompt, "do the thing")];
+ for (tool, calls) in [("tool non-file", 20), ("Bash", 5), ("Edit", 2)] {
+ for _ in 0..calls {
+ observations.push(obs(ObservationKind::PostToolUse, tool));
+ }
+ }
+ assert_eq!(
+ session_summary(&tally_session(&observations)),
+ "1 prompt, 27 completed tool calls across Bash and Edit and 1 more."
+ );
+ }
+
#[test]
fn many_tools_are_named_by_volume_then_counted() {
let mut observations = vec![obs(ObservationKind::UserPrompt, "do the thing")];