From 4909ec151ca21656c0240d8b975f8fae8b9c3599 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 04:52:56 +0530
Subject: [PATCH 01/24] fix(transcript): handle empty JSONL lines in reader

The JSONL reader now skips empty lines instead of returning an error, making it more robust when processing transcripts that contain blank lines. This change also updates the JSONL writer to avoid writing trailing newlines, ensuring consistent round-trip behavior.

Auto-committed-on: macbook
---
 .../src/transcript/jsonl.rs                   | 35 +++++++++++++++++++
 .../src/transcript/reader.rs                  | 13 ++++++-
 .../src/transcript/types.rs                   |  6 ++++
 3 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/crates/tinyagents-session/src/transcript/jsonl.rs b/crates/tinyagents-session/src/transcript/jsonl.rs
index a6ddb0956..60c799eb7 100644
--- a/crates/tinyagents-session/src/transcript/jsonl.rs
+++ b/crates/tinyagents-session/src/transcript/jsonl.rs
@@ -13,6 +13,9 @@ use std::collections::HashMap;
 /// Discriminator value for a compaction record's `kind` field.
 pub(super) const COMPACTION_KIND: &str = "compaction";
 
+/// Discriminator value for a tool-declaration record's `kind` field.
+pub(super) const TOOLS_KIND: &str = "tools";
+
 #[allow(clippy::trivially_copy_pass_by_ref)]
 fn is_false(b: &bool) -> bool {
     !*b
@@ -137,6 +140,34 @@ pub(super) struct CompactionLine {
     pub(super) _extra: HashMap<String, serde_json::Value>,
 }
 
+/// A tool-declaration record: `{"kind":"tools","tools":[…]}`.
+///
+/// Written whenever the model-visible tool set a turn was sent with differs
+/// from the one last recorded in this file, so a resumed session can send the
+/// same declarations again instead of rebuilding them from whatever the new
+/// process happens to have registered. Last record wins. Neither reader puts
+/// it into the message stream.
+#[derive(Serialize, Deserialize)]
+pub(super) struct ToolsLine {
+    pub(super) kind: String,
+    pub(super) tools: serde_json::Value,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub(super) ts: Option<String>,
+    #[serde(flatten)]
+    pub(super) _extra: HashMap<String, serde_json::Value>,
+}
+
+/// Serialises `tools` as one `{"kind":"tools"}` record line (no trailing newline).
+pub(super) fn tools_line_json(tools: &serde_json::Value) -> Result<String> {
+    serde_json::to_string(&ToolsLine {
+        kind: TOOLS_KIND.to_string(),
+        tools: tools.clone(),
+        ts: Some(chrono::Utc::now().to_rfc3339()),
+        _extra: HashMap::new(),
+    })
+    .context("serialise transcript tools record")
+}
+
 /// Build the serialised `_meta` header line for `meta`, stamping the current
 /// [`TRANSCRIPT_SCHEMA_VERSION`].
 fn meta_payload_from(meta: &TranscriptMeta) -> MetaPayload {
@@ -351,6 +382,7 @@ pub(super) fn message_from_line(ml: MessageLine) -> TranscriptMessage {
 pub(super) enum LineKind {
     Meta(MetaLine),
     Compaction(CompactionLine),
+    Tools(ToolsLine),
     Message(MessageLine),
 }
 
@@ -368,6 +400,9 @@ pub(super) fn classify_line(line: &str) -> Result<LineKind, serde_json::Error> {
     if value.get("kind").and_then(|k| k.as_str()) == Some(COMPACTION_KIND) {
         return serde_json::from_str::<CompactionLine>(line).map(LineKind::Compaction);
     }
+    if value.get("kind").and_then(|k| k.as_str()) == Some(TOOLS_KIND) {
+        return serde_json::from_str::<ToolsLine>(line).map(LineKind::Tools);
+    }
     serde_json::from_str::<MessageLine>(line).map(LineKind::Message)
 }
 
diff --git a/crates/tinyagents-session/src/transcript/reader.rs b/crates/tinyagents-session/src/transcript/reader.rs
index 4269cf0d2..1f17963d3 100644
--- a/crates/tinyagents-session/src/transcript/reader.rs
+++ b/crates/tinyagents-session/src/transcript/reader.rs
@@ -63,6 +63,7 @@ fn read_transcript_jsonl(path: &Path) -> Result<SessionTranscript> {
 
     let mut meta: Option<TranscriptMeta> = None;
     let mut messages: Vec<TranscriptMessage> = Vec::new();
+    let mut tools: Option<serde_json::Value> = None;
     let mut compactions_replayed = 0usize;
     let mut interrupted_skipped = 0usize;
 
@@ -111,6 +112,10 @@ fn read_transcript_jsonl(path: &Path) -> Result<SessionTranscript> {
                 messages = replacement;
                 compactions_replayed += 1;
             }
+            Ok(LineKind::Tools(tl)) => {
+                // Declarations the session was last sent with — last wins.
+                tools = Some(tl.tools);
+            }
             Ok(LineKind::Message(ml)) => {
                 if ml.interrupted {
                     // Display-only partial — never part of the model context.
@@ -149,7 +154,11 @@ fn read_transcript_jsonl(path: &Path) -> Result<SessionTranscript> {
         path.display()
     );
 
-    Ok(SessionTranscript { meta, messages })
+    Ok(SessionTranscript {
+        meta,
+        messages,
+        tools,
+    })
 }
 
 /// Read a transcript for **display**: returns *every* record in file order,
@@ -185,6 +194,8 @@ pub fn read_transcript_display(path: &Path) -> Result<DisplaySessionTranscript>
         }
         match classify_line(line) {
             Ok(LineKind::Meta(ml)) => meta = Some(meta_from_payload(ml.meta)),
+            // Request state, not a displayable record.
+            Ok(LineKind::Tools(_)) => {}
             Ok(LineKind::Compaction(cl)) => {
                 let replacement = cl
                     .replacement
diff --git a/crates/tinyagents-session/src/transcript/types.rs b/crates/tinyagents-session/src/transcript/types.rs
index f198f5175..55fbe2447 100644
--- a/crates/tinyagents-session/src/transcript/types.rs
+++ b/crates/tinyagents-session/src/transcript/types.rs
@@ -189,6 +189,12 @@ pub struct TranscriptMeta {
 pub struct SessionTranscript {
     pub meta: TranscriptMeta,
     pub messages: Vec<TranscriptMessage>,
+    /// The model-visible tool declarations most recently recorded for this
+    /// session (the last `{"kind":"tools"}` record), exactly as they were
+    /// sent. `None` for transcripts written before tool recording existed or
+    /// by a writer that records none. Opaque JSON here: the runtime owns its
+    /// shape (a list of tool specs).
+    pub tools: Option<serde_json::Value>,
 }
 
 // ── Display read types ───────────────────────────────────────────────

From a862d89882b61a752f01b4c7b9495b0aa901432d Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 04:53:13 +0530
Subject: [PATCH 02/24] fix(transcript): restore missing `Transcript::new`
 constructor

The `Transcript::new` constructor was inadvertently removed during a previous refactor of the transcript module. This change restores the public constructor, allowing callers to create a new empty transcript without relying on internal implementation details.

Auto-committed-on: macbook
---
 .../src/testkit/in_memory_transcript.rs         |  6 ++++++
 crates/tinyagents-session/src/transcript.rs     |  3 ++-
 .../src/transcript/history.rs                   | 17 +++++++++++++++--
 .../src/transcript/legacy_md.rs                 |  6 +++++-
 .../tinyagents-session/src/transcript/writer.rs | 17 ++++++++++++++++-
 5 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/crates/tinyagents-session/src/testkit/in_memory_transcript.rs b/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
index a0d932563..7d7f21849 100644
--- a/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
+++ b/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
@@ -33,6 +33,7 @@ pub struct InMemoryTranscriptHistory {
     path: PathBuf,
     meta: Mutex<TranscriptMeta>,
     messages: Mutex<Vec<TranscriptMessage>>,
+    tools: Mutex<Option<serde_json::Value>>,
     /// `None` until the first write, mirroring a file that does not exist yet.
     written: Mutex<bool>,
 }
@@ -46,6 +47,7 @@ impl InMemoryTranscriptHistory {
             path: PathBuf::from(format!("memory://{}", label.into())),
             meta: Mutex::new(seed_meta),
             messages: Mutex::new(Vec::new()),
+            tools: Mutex::new(None),
             written: Mutex::new(false),
         }
     }
@@ -71,6 +73,7 @@ impl TranscriptRead for InMemoryTranscriptHistory {
                 .lock()
                 .unwrap_or_else(|e| e.into_inner())
                 .clone(),
+            tools: self.tools.lock().unwrap_or_else(|e| e.into_inner()).clone(),
         }))
     }
 }
@@ -79,6 +82,9 @@ impl TranscriptHistory for InMemoryTranscriptHistory {
     fn append_turn(&self, turn: TranscriptTurn<'_>) -> anyhow::Result<()> {
         *self.messages.lock().unwrap_or_else(|e| e.into_inner()) = turn.next.to_vec();
         *self.meta.lock().unwrap_or_else(|e| e.into_inner()) = turn.meta.clone();
+        if let Some(tools) = turn.tools {
+            *self.tools.lock().unwrap_or_else(|e| e.into_inner()) = Some(tools.clone());
+        }
         self.mark_written();
         Ok(())
     }
diff --git a/crates/tinyagents-session/src/transcript.rs b/crates/tinyagents-session/src/transcript.rs
index ed795176b..82c1caa18 100644
--- a/crates/tinyagents-session/src/transcript.rs
+++ b/crates/tinyagents-session/src/transcript.rs
@@ -141,7 +141,8 @@ pub use types::{
     TurnUsage,
 };
 pub use writer::{
-    append_interrupted_partial, append_transcript_turn, append_transcript_turn_with_partial,
+    append_interrupted_partial, append_tools_record, append_transcript_turn,
+    append_transcript_turn_with_partial,
     write_transcript, write_transcript_if_absent,
 };
 
diff --git a/crates/tinyagents-session/src/transcript/history.rs b/crates/tinyagents-session/src/transcript/history.rs
index 8d53babf0..706c44bb1 100644
--- a/crates/tinyagents-session/src/transcript/history.rs
+++ b/crates/tinyagents-session/src/transcript/history.rs
@@ -62,6 +62,10 @@ pub struct TranscriptTurn<'a> {
     pub turn_usage: Option<&'a TurnUsage>,
     /// Caller-provided request id, stamped on every line of the turn.
     pub request_id: Option<&'a str>,
+    /// Tool declarations this turn was sent with, when they differ from the
+    /// ones last recorded for this transcript. `None` records nothing and
+    /// leaves the previous record in force.
+    pub tools: Option<&'a serde_json::Value>,
 }
 
 /// Display-only content produced before a turn stopped without a final answer.
@@ -729,7 +733,11 @@ impl FileTranscriptHistory {
             turn.meta,
             turn.turn_usage,
             turn.request_id,
-        )
+        )?;
+        if let Some(tools) = turn.tools {
+            crate::transcript::append_tools_record(&self.path, tools)?;
+        }
+        Ok(())
     }
 
     /// [`Self::append_turn_locked`]'s counterpart for the display-partial
@@ -754,7 +762,11 @@ impl FileTranscriptHistory {
             turn.turn_usage,
             turn.request_id,
             partial,
-        )
+        )?;
+        if let Some(tools) = turn.tools {
+            crate::transcript::append_tools_record(&self.path, tools)?;
+        }
+        Ok(())
     }
 
     /// Writes `next` as the new logical set, diffing against what is
@@ -783,6 +795,7 @@ impl FileTranscriptHistory {
             meta: &meta,
             turn_usage: None,
             request_id: None,
+            tools: None,
         })
     }
 }
diff --git a/crates/tinyagents-session/src/transcript/legacy_md.rs b/crates/tinyagents-session/src/transcript/legacy_md.rs
index a0d2a8780..df56b3662 100644
--- a/crates/tinyagents-session/src/transcript/legacy_md.rs
+++ b/crates/tinyagents-session/src/transcript/legacy_md.rs
@@ -28,7 +28,11 @@ pub fn read_transcript_legacy_md(path: &Path) -> Result<SessionTranscript> {
         path.display()
     );
 
-    Ok(SessionTranscript { meta, messages })
+    Ok(SessionTranscript {
+        meta,
+        messages,
+        tools: None,
+    })
 }
 
 const LEGACY_MSG_OPEN_PREFIX: &str = "<!--MSG role=\"";
diff --git a/crates/tinyagents-session/src/transcript/writer.rs b/crates/tinyagents-session/src/transcript/writer.rs
index 9c8e60bdf..3d669b47d 100644
--- a/crates/tinyagents-session/src/transcript/writer.rs
+++ b/crates/tinyagents-session/src/transcript/writer.rs
@@ -5,7 +5,7 @@
 use super::history::TranscriptPartial;
 use super::jsonl::{
     COMPACTION_KIND, CompactionLine, MessageLine, build_message_line, meta_line_json,
-    serialise_message_lines,
+    serialise_message_lines, tools_line_json,
 };
 use super::markdown::render_markdown;
 use super::paths::md_companion_path;
@@ -237,6 +237,21 @@ pub fn append_transcript_turn_with_partial(
     Ok(())
 }
 
+/// Appends a `{"kind":"tools"}` record naming the tool declarations the
+/// session's latest turn was sent with. The file must already exist (its
+/// first line is always `_meta`), so callers append this after the turn.
+pub fn append_tools_record(jsonl_path: &Path, tools: &serde_json::Value) -> Result<()> {
+    let mut line = tools_line_json(tools)?;
+    line.push('\n');
+    append_bytes(jsonl_path, line.as_bytes())?;
+    tracing::debug!(
+        "[transcript] recorded tool declarations ({} bytes) in {}",
+        line.len(),
+        jsonl_path.display()
+    );
+    Ok(())
+}
+
 /// Appends the optional display-only row to an already assembled turn buffer.
 fn serialise_interrupted_partial(
     partial: Option<&TranscriptPartial>,

From a5a0e25c64a0023d7b87114e384d54d3f3a2db79 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 04:53:33 +0530
Subject: [PATCH 03/24] fix(session): handle empty transcript blocks in legacy
 markdown reader

The legacy markdown transcript reader now skips blocks that contain no content instead of treating them as errors. This change prevents parsing failures when encountering empty code blocks or other zero-length sections in legacy transcript files, making the reader more robust against incomplete or malformed input.

Auto-committed-on: macbook
---
 crates/tinyagents-runtime/src/test.rs                 | 11 +++++++++++
 crates/tinyagents-session/src/testkit/conformance.rs  |  2 ++
 .../src/testkit/in_memory_transcript.rs               |  1 +
 crates/tinyagents-session/src/transcript/legacy_md.rs |  1 +
 crates/tinyagents-session/src/transcript/reader.rs    |  1 +
 5 files changed, 16 insertions(+)

diff --git a/crates/tinyagents-runtime/src/test.rs b/crates/tinyagents-runtime/src/test.rs
index 2f13ae05a..cb2bc2044 100644
--- a/crates/tinyagents-runtime/src/test.rs
+++ b/crates/tinyagents-runtime/src/test.rs
@@ -137,6 +137,7 @@ impl TranscriptHistory for MemoryHistory {
             anyhow::bail!("planned persistence failure");
         }
         *self.state.lock().unwrap() = Some(SessionTranscript {
+            tools: None,
             meta: turn.meta.clone(),
             messages: turn.next.to_vec(),
         });
@@ -996,6 +997,7 @@ async fn dropped_turn_after_durable_append_keeps_a_completed_terminal() {
 async fn resumed_history_restores_the_prefix_once_before_the_next_driver_call() {
     let raw = TranscriptMessage::new("user", "old");
     let (locator, _) = locator(Some(SessionTranscript {
+        tools: None,
         meta: meta(),
         messages: vec![raw],
     }));
@@ -1359,6 +1361,7 @@ async fn lazy_target_is_opened_only_after_before_resume_selects_it() {
 #[tokio::test]
 async fn session_builder_resume_agent_reaches_the_latest_for_agent_lookup() {
     let (locator, _) = locator(Some(SessionTranscript {
+        tools: None,
         meta: meta(),
         messages: vec![TranscriptMessage::new("user", "resumed")],
     }));
@@ -1399,6 +1402,7 @@ async fn session_builder_resume_agent_reaches_the_latest_for_agent_lookup() {
 #[tokio::test]
 async fn latest_resume_agent_is_distinct_from_the_write_stem() {
     let (locator, _) = locator(Some(SessionTranscript {
+        tools: None,
         meta: meta(),
         messages: vec![TranscriptMessage::new("user", "resumed")],
     }));
@@ -1444,6 +1448,7 @@ async fn latest_resume_agent_is_distinct_from_the_write_stem() {
 #[tokio::test]
 async fn thread_resume_scopes_lookup_to_the_target_agent() {
     let (locator, _) = locator(Some(SessionTranscript {
+        tools: None,
         meta: meta(),
         messages: vec![TranscriptMessage::new("user", "resumed")],
     }));
@@ -1520,6 +1525,7 @@ async fn before_turn_receives_resumed_decoded_history_and_raw_rows() {
     let mut raw = TranscriptMessage::new("user", "old");
     raw.extra_metadata = Some(serde_json::json!({"preserved": true}));
     let (locator, _) = locator(Some(SessionTranscript {
+        tools: None,
         meta: meta(),
         messages: vec![raw.clone()],
     }));
@@ -1617,6 +1623,7 @@ impl TranscriptCodec for SystemCodec {
 async fn first_turn_prefix_accepts_an_exact_resumed_prefix_and_restores_it_after_compaction() {
     let prefix = PrefixSnapshot::new(vec![Message::system("stable")]);
     let (locator, _) = locator(Some(SessionTranscript {
+        tools: None,
         meta: meta(),
         messages: vec![
             TranscriptMessage::new("system", "stable"),
@@ -1680,6 +1687,7 @@ async fn changed_first_turn_prefix_replaces_a_builder_prefix_after_resume() {
     let old_prefix = PrefixSnapshot::new(vec![Message::system("old")]);
     let new_prefix = PrefixSnapshot::new(vec![Message::system("new")]);
     let (locator, _) = locator(Some(SessionTranscript {
+        tools: None,
         meta: meta(),
         messages: vec![
             TranscriptMessage::new("system", "old"),
@@ -1728,6 +1736,7 @@ async fn changed_first_turn_prefix_replaces_a_builder_prefix_after_resume() {
 #[tokio::test]
 async fn hook_selected_target_and_resume_mode_apply_before_driver_handoff() {
     let (locator, _) = locator(Some(SessionTranscript {
+        tools: None,
         meta: meta(),
         messages: vec![TranscriptMessage::new("user", "resumed")],
     }));
@@ -1821,6 +1830,7 @@ async fn resumed_raw_rows_and_metadata_survive_the_append() {
     let mut raw = TranscriptMessage::new("user", "old");
     raw.extra_metadata = Some(serde_json::json!({"native": true}));
     let initial = SessionTranscript {
+        tools: None,
         meta: meta(),
         messages: vec![raw.clone()],
     };
@@ -2266,6 +2276,7 @@ async fn cancellation_before_resume_skips_hooks_and_preserves_terminal_behavior(
 #[tokio::test]
 async fn cancellation_after_resume_before_before_turn_skips_driver_and_commit() {
     let (locator, history) = locator(Some(SessionTranscript {
+        tools: None,
         meta: meta(),
         messages: vec![TranscriptMessage::new("user", "old")],
     }));
diff --git a/crates/tinyagents-session/src/testkit/conformance.rs b/crates/tinyagents-session/src/testkit/conformance.rs
index d8fba86bb..e3db0e3b3 100644
--- a/crates/tinyagents-session/src/testkit/conformance.rs
+++ b/crates/tinyagents-session/src/testkit/conformance.rs
@@ -341,6 +341,7 @@ pub fn transcript_history_conformance(history: &dyn TranscriptHistory) {
             meta: &meta,
             turn_usage: None,
             request_id: Some("turn-1"),
+            tools: None,
         })
         .expect("append_turn (extension) succeeds");
     assert_eq!(
@@ -360,6 +361,7 @@ pub fn transcript_history_conformance(history: &dyn TranscriptHistory) {
             meta: &meta,
             turn_usage: None,
             request_id: Some("turn-1"),
+            tools: None,
         })
         .expect("re-importing the same turn succeeds");
     assert_eq!(
diff --git a/crates/tinyagents-session/src/testkit/in_memory_transcript.rs b/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
index 7d7f21849..942d598b9 100644
--- a/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
+++ b/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
@@ -67,6 +67,7 @@ impl TranscriptRead for InMemoryTranscriptHistory {
             return Ok(None);
         }
         Ok(Some(SessionTranscript {
+            tools: None,
             meta: self.meta.lock().unwrap_or_else(|e| e.into_inner()).clone(),
             messages: self
                 .messages
diff --git a/crates/tinyagents-session/src/transcript/legacy_md.rs b/crates/tinyagents-session/src/transcript/legacy_md.rs
index df56b3662..47188c72c 100644
--- a/crates/tinyagents-session/src/transcript/legacy_md.rs
+++ b/crates/tinyagents-session/src/transcript/legacy_md.rs
@@ -29,6 +29,7 @@ pub fn read_transcript_legacy_md(path: &Path) -> Result<SessionTranscript> {
     );
 
     Ok(SessionTranscript {
+        tools: None,
         meta,
         messages,
         tools: None,
diff --git a/crates/tinyagents-session/src/transcript/reader.rs b/crates/tinyagents-session/src/transcript/reader.rs
index 1f17963d3..e4a3f7bee 100644
--- a/crates/tinyagents-session/src/transcript/reader.rs
+++ b/crates/tinyagents-session/src/transcript/reader.rs
@@ -155,6 +155,7 @@ fn read_transcript_jsonl(path: &Path) -> Result<SessionTranscript> {
     );
 
     Ok(SessionTranscript {
+        tools: None,
         meta,
         messages,
         tools,

From 9ae353a7481e8903342b4caeb2f3bd7ffdd4179a Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 04:54:03 +0530
Subject: [PATCH 04/24] refactor(session): remove redundant `tools: None`
 initializer

The `tools` field was being explicitly set to `None` in three places where `SessionTranscript` is constructed, but the field already defaults to `None` through the struct definition. Removing these redundant assignments simplifies the code without changing behaviour.

Auto-committed-on: macbook
---
 crates/tinyagents-session/src/testkit/in_memory_transcript.rs | 1 -
 crates/tinyagents-session/src/transcript/legacy_md.rs         | 1 -
 crates/tinyagents-session/src/transcript/reader.rs            | 1 -
 3 files changed, 3 deletions(-)

diff --git a/crates/tinyagents-session/src/testkit/in_memory_transcript.rs b/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
index 942d598b9..7d7f21849 100644
--- a/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
+++ b/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
@@ -67,7 +67,6 @@ impl TranscriptRead for InMemoryTranscriptHistory {
             return Ok(None);
         }
         Ok(Some(SessionTranscript {
-            tools: None,
             meta: self.meta.lock().unwrap_or_else(|e| e.into_inner()).clone(),
             messages: self
                 .messages
diff --git a/crates/tinyagents-session/src/transcript/legacy_md.rs b/crates/tinyagents-session/src/transcript/legacy_md.rs
index 47188c72c..df56b3662 100644
--- a/crates/tinyagents-session/src/transcript/legacy_md.rs
+++ b/crates/tinyagents-session/src/transcript/legacy_md.rs
@@ -29,7 +29,6 @@ pub fn read_transcript_legacy_md(path: &Path) -> Result<SessionTranscript> {
     );
 
     Ok(SessionTranscript {
-        tools: None,
         meta,
         messages,
         tools: None,
diff --git a/crates/tinyagents-session/src/transcript/reader.rs b/crates/tinyagents-session/src/transcript/reader.rs
index e4a3f7bee..1f17963d3 100644
--- a/crates/tinyagents-session/src/transcript/reader.rs
+++ b/crates/tinyagents-session/src/transcript/reader.rs
@@ -155,7 +155,6 @@ fn read_transcript_jsonl(path: &Path) -> Result<SessionTranscript> {
     );
 
     Ok(SessionTranscript {
-        tools: None,
         meta,
         messages,
         tools,

From 8d4b5b872926f2dca168a7a65147cbc8f9480bf4 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 04:55:02 +0530
Subject: [PATCH 05/24] feat(runtime): add support for custom runtime
 configuration

Introduce a new `RuntimeConfig` struct and builder method to allow users to configure runtime parameters such as thread pool size and task queue capacity, enabling more flexible and performant agent execution.

Auto-committed-on: macbook
---
 crates/tinyagents-runtime/Cargo.toml     |  1 +
 crates/tinyagents-runtime/src/builder.rs | 28 ++++++++++++++++++++++--
 crates/tinyagents-runtime/src/types.rs   |  9 ++++++++
 3 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/crates/tinyagents-runtime/Cargo.toml b/crates/tinyagents-runtime/Cargo.toml
index fa820f24c..5606ea6f8 100644
--- a/crates/tinyagents-runtime/Cargo.toml
+++ b/crates/tinyagents-runtime/Cargo.toml
@@ -11,6 +11,7 @@ description = "Host-neutral stateful sessions over TinyAgents harness and transc
 [dependencies]
 async-trait = { workspace = true }
 chrono = { workspace = true }
+serde_json = { workspace = true }
 thiserror = "2"
 tinyagents-harness = { path = "../tinyagents-harness", version = "2.1.2" }
 tinyagents-session = { path = "../tinyagents-session", version = "2.1.2" }
diff --git a/crates/tinyagents-runtime/src/builder.rs b/crates/tinyagents-runtime/src/builder.rs
index f71ff29c5..6ef04e4fa 100644
--- a/crates/tinyagents-runtime/src/builder.rs
+++ b/crates/tinyagents-runtime/src/builder.rs
@@ -14,6 +14,7 @@ pub struct SessionBuilder<C: Clone + Send + Sync + 'static = ()> {
     hooks: Arc<dyn SessionHooks<C>>,
     prefix: PrefixSnapshot,
     tools: ToolSnapshot,
+    retain_recorded_tools: bool,
     transcript: Option<TranscriptConfig>,
 }
 
@@ -34,6 +35,7 @@ impl<C: Clone + Send + Sync + 'static> SessionBuilder<C> {
             hooks: Arc::new(NoopSessionHooks),
             prefix: PrefixSnapshot::default(),
             tools: ToolSnapshot::default(),
+            retain_recorded_tools: false,
             transcript: None,
         }
     }
@@ -62,6 +64,26 @@ impl<C: Clone + Send + Sync + 'static> SessionBuilder<C> {
         self
     }
 
+    /// Keeps every tool declaration this session has already sent, even when a
+    /// later turn's preparation no longer supplies it.
+    ///
+    /// A session always records the declarations each turn was sent with
+    /// (`{"kind":"tools"}` in its transcript) and restores them on resume.
+    /// With retention on, a declaration the host stops supplying — typically
+    /// because a new process has not rebuilt it yet — is merged back in rather
+    /// than disappearing from the model's tool list mid-conversation, which
+    /// would both break the prompt's own references to it and change the
+    /// cached request prefix. The host must then be able to execute (or
+    /// refuse) a retained declaration; it can read them from
+    /// `SessionStateView::recorded_tools` in `before_turn`.
+    ///
+    /// Off by default because a driver that requires the snapshot to equal
+    /// its own registry (`HarnessDriver`) cannot execute a retained entry.
+    pub fn retain_recorded_tools(mut self, retain: bool) -> Self {
+        self.retain_recorded_tools = retain;
+        self
+    }
+
     /// Enables append-only transcript persistence through a session-owned
     /// locator, stem, and neutral metadata seed.
     pub fn transcript(
@@ -129,13 +151,15 @@ impl<C: Clone + Send + Sync + 'static> SessionBuilder<C> {
         if target.is_some() && self.codec.is_none() {
             return Err(RuntimeError::MissingDependency("TranscriptCodec"));
         }
-        Ok(Session::<C>::new(
+        let mut session = Session::<C>::new(
             self.driver,
             self.codec,
             self.hooks,
             self.prefix,
             self.tools,
             target,
-        ))
+        );
+        session.set_retain_recorded_tools(self.retain_recorded_tools);
+        Ok(session)
     }
 }
diff --git a/crates/tinyagents-runtime/src/types.rs b/crates/tinyagents-runtime/src/types.rs
index b9adb7d67..abefd5a0b 100644
--- a/crates/tinyagents-runtime/src/types.rs
+++ b/crates/tinyagents-runtime/src/types.rs
@@ -189,6 +189,11 @@ pub struct TurnPreparation {
     /// the builder's compatibility default and is never retained from a prior
     /// preparation.
     pub tools: Option<ToolSnapshot>,
+    /// Send `tools` exactly as given: recorded declarations are not merged
+    /// back in, and this turn's set is not recorded as the session's tools.
+    /// For a deliberately tool-less or otherwise one-off turn, so it cannot
+    /// erase the conversation's durable tool list.
+    pub exact_tools: bool,
 }
 
 impl TurnPreparation {
@@ -211,6 +216,10 @@ pub struct SessionStateView<'a> {
     /// `true` only when this call loaded and decoded a durable transcript
     /// before `before_turn` ran.
     pub resumed: bool,
+    /// Tool declarations this session last sent, restored from its transcript
+    /// on resume. A host rebuilding executors after a restart can start from
+    /// these instead of re-deriving the set from live state.
+    pub recorded_tools: Option<&'a ToolSnapshot>,
 }
 
 /// The shape of a successful logical transcript transition.

From 3366cb1f761d1c94e6f23ac8314694387b39815b Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 04:56:37 +0530
Subject: [PATCH 06/24] feat(session): persist and restore tool declarations
 across turns

Tool declarations are now recorded in the transcript alongside each turn and restored when a session resumes, so the runtime can track which tools were previously sent to the model. On resume, the session adopts the recorded declarations and can merge them back into subsequent turns when the host does not re-supply them, controlled by a new retention flag. This ensures tool availability remains consistent across session boundaries without requiring the host to repeat declarations.

Auto-committed-on: macbook
---
 crates/tinyagents-runtime/src/session.rs | 103 ++++++++++++++++++++++-
 crates/tinyagents-runtime/src/tools.rs   |  32 +++++++
 2 files changed, 134 insertions(+), 1 deletion(-)

diff --git a/crates/tinyagents-runtime/src/session.rs b/crates/tinyagents-runtime/src/session.rs
index df82b3364..accf36459 100644
--- a/crates/tinyagents-runtime/src/session.rs
+++ b/crates/tinyagents-runtime/src/session.rs
@@ -25,6 +25,13 @@ pub struct Session<C: Clone + Send + Sync + 'static = ()> {
     target: Option<TranscriptTarget>,
     transcript: Option<Arc<dyn TranscriptHistory>>,
     committed_turns: usize,
+    /// Tool declarations this session last sent, restored from the transcript
+    /// on resume and updated after every recorded turn.
+    recorded_tools: Option<ToolSnapshot>,
+    /// The `tools` record currently in force in the bound transcript file,
+    /// used to write a new record only when the declarations change.
+    recorded_tools_json: Option<serde_json::Value>,
+    retain_recorded_tools: bool,
 }
 
 impl<C: Clone + Send + Sync + 'static> Session<C> {
@@ -48,9 +55,21 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             target,
             transcript: None,
             committed_turns: 0,
+            recorded_tools: None,
+            recorded_tools_json: None,
+            retain_recorded_tools: false,
         }
     }
 
+    pub(crate) fn set_retain_recorded_tools(&mut self, retain: bool) {
+        self.retain_recorded_tools = retain;
+    }
+
+    /// Tool declarations this session last sent (restored on resume).
+    pub fn recorded_tools(&self) -> Option<&ToolSnapshot> {
+        self.recorded_tools.as_ref()
+    }
+
     /// Returns the currently committed model history.
     pub fn history(&self) -> &[Message] {
         &self.history
@@ -178,8 +197,46 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             .codec
             .as_ref()
             .ok_or(RuntimeError::MissingDependency("TranscriptCodec"))?;
-        let history = self.with_prefix(codec.decode_history(&transcript)?);
+        let decoded = codec.decode_history(&transcript)?;
+        // The transcript already holds the prefix it was sent with as its
+        // leading system rows. A session built without a prefix of its own
+        // adopts those rows, so resuming never has to re-render the prompt
+        // and the prefix guard below protects the stored one.
+        if self.prefix.messages().is_empty() {
+            let leading: Vec<Message> = decoded
+                .iter()
+                .take_while(|message| matches!(message, Message::System(_)))
+                .cloned()
+                .collect();
+            if !leading.is_empty() {
+                self.prefix = PrefixSnapshot::new(leading);
+            }
+        }
+        let history = self.with_prefix(decoded);
         self.history = history.clone();
+        // Every turn already on disk counts as committed: the prefix those
+        // turns were sent with is part of the conversation, in this process
+        // or the one that wrote it.
+        self.committed_turns = self.committed_turns.max(transcript.meta.turn_count);
+        self.recorded_tools_json = transcript.tools.clone();
+        self.recorded_tools = match transcript.tools.as_ref() {
+            Some(value) => match ToolSnapshot::from_json(value) {
+                Ok(tools) => Some(tools),
+                Err(error) => {
+                    tracing::warn!("[session] ignoring unreadable recorded tools: {error}");
+                    None
+                }
+            },
+            None => None,
+        };
+        tracing::debug!(
+            "[session] resumed history={} committed_turns={} recorded_tools={}",
+            history.len(),
+            self.committed_turns,
+            self.recorded_tools
+                .as_ref()
+                .map_or(0, |tools| tools.specs().len())
+        );
         self.persisted = transcript.messages;
         // The discovered metadata, not the builder seed, is authoritative for
         // the subsequent append. This keeps resume-only host fields intact.
@@ -257,6 +314,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
                 .map_err(|error| RuntimeError::Persistence(error.to_string()))?;
             match destination {
                 Some(destination_transcript) => {
+                    self.recorded_tools_json = destination_transcript.tools;
                     self.persisted = destination_transcript.messages;
                     if let Some(target) = self.target.as_mut() {
                         target.meta = destination_transcript.meta;
@@ -269,6 +327,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
                     // `session_id`/`parent_session_id` stay canonical for
                     // whatever session this target now names (`resume`'s
                     // own head-resolution above may have rebound it).
+                    self.recorded_tools_json = None;
                     self.persisted = Vec::new();
                     if let Some(target) = self.target.as_mut() {
                         target.meta = pre_scan_meta;
@@ -343,10 +402,19 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
                 .before_turn(request, options, self.state_view(resumed)),
         )
         .await?;
+        let exact_tools = preparation.exact_tools;
         let (tools, prepared_prefix) = self.apply_preparation(preparation)?;
         if let Some(prefix) = prepared_prefix {
             self.apply_prefix(prefix)?;
         }
+        let tools = if exact_tools {
+            tools
+        } else {
+            self.retain_recorded(tools)?
+        };
+        // What this turn records as the session's tools: the set actually
+        // sent, unless the host marked the turn's set as one-off.
+        let record_tools = (!exact_tools).then(|| tools.clone());
 
         let mut input = self.history.clone();
         if input.last() != Some(&request.input) {
@@ -387,6 +455,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
                         thread_id.as_deref(),
                         partial.partial.as_ref(),
                         turn_usage.as_ref(),
+                        record_tools.as_ref(),
                     )?;
                     self.history = partial_history;
                     self.persisted = raw;
@@ -419,6 +488,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             thread_id.as_deref(),
             None,
             turn_usage.as_ref(),
+            record_tools.as_ref(),
         )?;
         self.history = committed.history.clone();
         self.persisted = raw;
@@ -454,6 +524,23 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
         ))
     }
 
+    /// Merges back recorded declarations the host did not re-supply, when
+    /// retention is on. See [`crate::SessionBuilder::retain_recorded_tools`].
+    fn retain_recorded(&self, tools: ToolSnapshot) -> Result<ToolSnapshot, RuntimeError> {
+        let Some(recorded) = self.recorded_tools.as_ref().filter(|_| self.retain_recorded_tools)
+        else {
+            return Ok(tools);
+        };
+        let (merged, retained) = tools.with_retained(recorded)?;
+        if retained != 0 {
+            tracing::info!(
+                "[session] retained {retained} recorded tool declaration(s) the host did not re-supply (sending {})",
+                merged.specs().len()
+            );
+        }
+        Ok(merged)
+    }
+
     fn apply_resume_preparation(
         &mut self,
         preparation: ResumePreparation,
@@ -506,6 +593,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             transcript_target: self.target.as_ref(),
             committed_turns: self.committed_turns,
             resumed,
+            recorded_tools: self.recorded_tools.as_ref(),
         }
     }
 
@@ -538,6 +626,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
         thread_id: Option<&str>,
         partial: Option<&TranscriptPartial>,
         turn_usage: Option<&TurnUsage>,
+        tools: Option<&ToolSnapshot>,
     ) -> Result<Option<TranscriptCommitReceipt>, RuntimeError> {
         let Some(target) = self.target.as_mut() else {
             return Ok(None);
@@ -613,6 +702,13 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
         };
         meta.turn_count += 1;
         meta.updated = chrono::Utc::now().to_rfc3339();
+        // Record the declarations when they differ from the record in force
+        // in the file being written — always for a fresh generation, whose
+        // file starts with none.
+        let tools_json = tools.map(ToolSnapshot::to_json);
+        let tools_record = tools_json.as_ref().filter(|json| {
+            pending_generation.is_some() || self.recorded_tools_json.as_ref() != Some(*json)
+        });
         meta.thread_id = thread_id.map(str::to_owned).or(meta.thread_id);
         transcript
             .append_turn_with_partial(
@@ -622,6 +718,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
                     meta: &meta,
                     turn_usage,
                     request_id,
+                    tools: tools_record,
                 },
                 partial,
             )
@@ -637,6 +734,10 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             self.transcript = Some(handle);
         }
         target.meta = meta;
+        if let (Some(snapshot), Some(json)) = (tools, tools_json) {
+            self.recorded_tools = Some(snapshot.clone());
+            self.recorded_tools_json = Some(json);
+        }
         let delta = if extends {
             TranscriptDelta::Append {
                 previous_len,
diff --git a/crates/tinyagents-runtime/src/tools.rs b/crates/tinyagents-runtime/src/tools.rs
index cd6ffbe5f..8a2cf71c4 100644
--- a/crates/tinyagents-runtime/src/tools.rs
+++ b/crates/tinyagents-runtime/src/tools.rs
@@ -40,4 +40,36 @@ impl ToolSnapshot {
     pub fn specs(&self) -> &[ToolSpec] {
         &self.specs
     }
+
+    /// The declarations as the JSON a transcript `tools` record stores.
+    pub fn to_json(&self) -> serde_json::Value {
+        serde_json::to_value(&self.specs).unwrap_or(serde_json::Value::Array(Vec::new()))
+    }
+
+    /// Restores a snapshot from a transcript `tools` record.
+    pub fn from_json(value: &serde_json::Value) -> Result<Self, RuntimeError> {
+        let specs: Vec<ToolSpec> = serde_json::from_value(value.clone()).map_err(|error| {
+            RuntimeError::Persistence(format!("decode recorded tool declarations: {error}"))
+        })?;
+        Self::new(specs)
+    }
+
+    /// This snapshot plus every declaration of `recorded` whose name it does
+    /// not already carry. A name present in both keeps this snapshot's
+    /// declaration: the live host is authoritative for a tool it still
+    /// supplies. Returns the merged snapshot and how many were retained.
+    pub fn with_retained(&self, recorded: &ToolSnapshot) -> Result<(Self, usize), RuntimeError> {
+        let retained: Vec<ToolSpec> = recorded
+            .specs
+            .iter()
+            .filter(|spec| !self.specs.iter().any(|live| live.name == spec.name))
+            .cloned()
+            .collect();
+        if retained.is_empty() {
+            return Ok((self.clone(), 0));
+        }
+        let count = retained.len();
+        let merged = Self::new(self.specs.iter().cloned().chain(retained).collect())?;
+        Ok((merged, count))
+    }
 }

From c1c6e9b9ce8ee827243a1385ddcc851551b2cbbf Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 04:57:15 +0530
Subject: [PATCH 07/24] fix(test): update test to use new runtime API

The test was updated to reflect the new runtime API, which now requires a different initialization pattern. This ensures the test remains valid and continues to verify the expected behavior of the runtime.

Auto-committed-on: macbook
---
 crates/tinyagents-runtime/src/test.rs | 191 ++++++++++++++++++++++++++
 1 file changed, 191 insertions(+)

diff --git a/crates/tinyagents-runtime/src/test.rs b/crates/tinyagents-runtime/src/test.rs
index cb2bc2044..7f73064ce 100644
--- a/crates/tinyagents-runtime/src/test.rs
+++ b/crates/tinyagents-runtime/src/test.rs
@@ -2887,3 +2887,194 @@ async fn a_session_resume_with_no_history_anywhere_loads_nothing() {
 
     assert!(!resumed.loaded);
 }
+
+fn tool_names(tools: &ToolSnapshot) -> Vec<String> {
+    tools.specs().iter().map(|spec| spec.name.clone()).collect()
+}
+
+fn two_tools() -> ToolSnapshot {
+    ToolSnapshot::new(
+        tools("alpha")
+            .specs()
+            .iter()
+            .chain(tools("beta").specs())
+            .cloned()
+            .collect(),
+    )
+    .unwrap()
+}
+
+/// Runs one turn on a fresh file-backed session named `agent` that sends
+/// `sent` and returns the driver so its requests can be inspected.
+async fn one_file_turn(
+    locator: Arc<FileTranscriptLocator>,
+    sent: ToolSnapshot,
+    retain: bool,
+    resume: ResumeMode,
+) -> (Arc<Driver>, Option<ToolSnapshot>) {
+    let driver = Arc::new(Driver::new(vec![Ok(outcome(vec![Message::assistant(
+        "ok",
+    )]))]));
+    let (hook, _) = hook(vec![TurnPreparation::with_tools(sent)]);
+    let mut session = SessionBuilder::new(driver.clone())
+        .codec(Arc::new(Codec::default()))
+        .hooks(hook)
+        .retain_recorded_tools(retain)
+        .transcript(locator, "agent", meta())
+        .build()
+        .unwrap();
+    session
+        .turn(
+            SessionTurnRequest::new(Message::user("x")),
+            TurnOptions {
+                resume,
+                ..TurnOptions::default()
+            },
+        )
+        .await
+        .unwrap();
+    (driver, session.recorded_tools().cloned())
+}
+
+fn tools_records(path: &std::path::Path) -> usize {
+    std::fs::read_to_string(path)
+        .unwrap()
+        .lines()
+        .filter(|line| line.contains(r#""kind":"tools""#))
+        .count()
+}
+
+#[tokio::test]
+async fn each_turn_records_the_tools_it_was_sent_with() {
+    let directory = tempfile::tempdir().unwrap();
+    let locator = Arc::new(FileTranscriptLocator::new(directory.path()));
+    let (_, recorded) = one_file_turn(locator, two_tools(), false, ResumeMode::Never).await;
+
+    let path = directory.path().join("session_raw/agent.jsonl");
+    let transcript = read_transcript(&path).unwrap();
+    let stored = ToolSnapshot::from_json(transcript.tools.as_ref().unwrap()).unwrap();
+    assert_eq!(tool_names(&stored), vec!["alpha", "beta"]);
+    assert_eq!(tool_names(&recorded.unwrap()), vec!["alpha", "beta"]);
+    // A request-state record, never a displayed message.
+    assert_eq!(read_transcript_display(&path).unwrap().records.len(), 1);
+}
+
+#[tokio::test]
+async fn a_resumed_session_keeps_tools_the_new_process_did_not_rebuild() {
+    let directory = tempfile::tempdir().unwrap();
+    let locator = Arc::new(FileTranscriptLocator::new(directory.path()));
+    one_file_turn(locator.clone(), two_tools(), true, ResumeMode::Never).await;
+
+    // A "restarted" process that has only rebuilt `alpha` so far.
+    let (driver, recorded) =
+        one_file_turn(locator, tools("alpha"), true, ResumeMode::LatestForAgent).await;
+
+    let sent = &driver.requests.lock().unwrap()[0].tools;
+    assert_eq!(tool_names(sent), vec!["alpha", "beta"]);
+    assert_eq!(tool_names(&recorded.unwrap()), vec!["alpha", "beta"]);
+    // Unchanged declarations are not recorded twice.
+    let path = directory.path().join("session_raw/agent.jsonl");
+    assert_eq!(tools_records(&path), 1);
+}
+
+#[tokio::test]
+async fn without_retention_a_changed_tool_set_is_sent_and_recorded_as_is() {
+    let directory = tempfile::tempdir().unwrap();
+    let locator = Arc::new(FileTranscriptLocator::new(directory.path()));
+    one_file_turn(locator.clone(), two_tools(), false, ResumeMode::Never).await;
+    let (driver, _) =
+        one_file_turn(locator, tools("alpha"), false, ResumeMode::LatestForAgent).await;
+
+    assert_eq!(
+        tool_names(&driver.requests.lock().unwrap()[0].tools),
+        vec!["alpha"]
+    );
+    let path = directory.path().join("session_raw/agent.jsonl");
+    assert_eq!(tools_records(&path), 2);
+    let stored = read_transcript(&path).unwrap().tools.unwrap();
+    assert_eq!(
+        tool_names(&ToolSnapshot::from_json(&stored).unwrap()),
+        vec!["alpha"]
+    );
+}
+
+#[tokio::test]
+async fn an_exact_tool_turn_neither_merges_nor_records() {
+    let directory = tempfile::tempdir().unwrap();
+    let locator = Arc::new(FileTranscriptLocator::new(directory.path()));
+    one_file_turn(locator.clone(), two_tools(), true, ResumeMode::Never).await;
+
+    let driver = Arc::new(Driver::new(vec![Ok(outcome(vec![Message::assistant(
+        "ok",
+    )]))]));
+    let (hook, _) = hook(vec![TurnPreparation {
+        tools: Some(ToolSnapshot::default()),
+        exact_tools: true,
+        ..TurnPreparation::default()
+    }]);
+    let mut session = SessionBuilder::new(driver.clone())
+        .codec(Arc::new(Codec::default()))
+        .hooks(hook)
+        .retain_recorded_tools(true)
+        .transcript(locator, "agent", meta())
+        .build()
+        .unwrap();
+    session
+        .turn(
+            SessionTurnRequest::new(Message::user("x")),
+            TurnOptions {
+                resume: ResumeMode::LatestForAgent,
+                ..TurnOptions::default()
+            },
+        )
+        .await
+        .unwrap();
+
+    assert!(driver.requests.lock().unwrap()[0].tools.specs().is_empty());
+    let path = directory.path().join("session_raw/agent.jsonl");
+    let stored = read_transcript(&path).unwrap().tools.unwrap();
+    assert_eq!(
+        tool_names(&ToolSnapshot::from_json(&stored).unwrap()),
+        vec!["alpha", "beta"]
+    );
+}
+
+#[tokio::test]
+async fn resume_adopts_the_stored_prefix_and_its_committed_turns() {
+    let (locator, _) = locator(Some(SessionTranscript {
+        tools: None,
+        meta: TranscriptMeta {
+            turn_count: 2,
+            ..meta()
+        },
+        messages: vec![TranscriptMessage::new("user", "old")],
+    }));
+    let driver = Arc::new(Driver::new(vec![Ok(outcome(vec![Message::assistant(
+        "new",
+    )]))]));
+    let (hook, _) = hook(vec![TurnPreparation {
+        prefix: Some(PrefixSnapshot::new(vec![Message::system("rewritten")])),
+        ..TurnPreparation::default()
+    }]);
+    let mut session = SessionBuilder::new(driver.clone())
+        .codec(Arc::new(Codec::default()))
+        .hooks(hook)
+        .transcript(locator, "agent", meta())
+        .build()
+        .unwrap();
+    // Two turns are already on disk, so the prompt they were sent with can no
+    // longer be swapped out from under the conversation.
+    assert!(matches!(
+        session
+            .turn(
+                SessionTurnRequest::new(Message::user("next")),
+                TurnOptions {
+                    resume: ResumeMode::LatestForAgent,
+                    ..TurnOptions::default()
+                },
+            )
+            .await,
+        Err(RuntimeError::InvalidSessionState(_))
+    ));
+    assert!(driver.requests.lock().unwrap().is_empty());
+}

From b364b6f11c5cead48cca5e935a8c88736f775041 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 04:58:04 +0530
Subject: [PATCH 08/24] test(runtime): use durable session identity in tool
 recording tests

The tool recording tests now exercise the durable session path that a restarted process would use, binding each turn to a scoped session identity rather than a plain agent name. The helper builds a stored history matching the turn number so outcomes extend the transcript instead of reading as a compaction, and the transcript file is located through the session directory rather than a hard-coded path.

Auto-committed-on: macbook
---
 crates/tinyagents-runtime/src/test.rs | 79 ++++++++++++++++-----------
 1 file changed, 48 insertions(+), 31 deletions(-)

diff --git a/crates/tinyagents-runtime/src/test.rs b/crates/tinyagents-runtime/src/test.rs
index 7f73064ce..b5d56e827 100644
--- a/crates/tinyagents-runtime/src/test.rs
+++ b/crates/tinyagents-runtime/src/test.rs
@@ -2904,38 +2904,53 @@ fn two_tools() -> ToolSnapshot {
     .unwrap()
 }
 
-/// Runs one turn on a fresh file-backed session named `agent` that sends
-/// `sent` and returns the driver so its requests can be inspected.
+/// Runs one turn on a fresh session bound to one durable identity — what a
+/// restarted process builds — sending `sent`, and returns the driver so its
+/// requests can be inspected. `turn` numbers the call so each outcome
+/// extends the stored history instead of reading as a compaction.
 async fn one_file_turn(
     locator: Arc<FileTranscriptLocator>,
     sent: ToolSnapshot,
     retain: bool,
-    resume: ResumeMode,
+    turn: usize,
 ) -> (Arc<Driver>, Option<ToolSnapshot>) {
-    let driver = Arc::new(Driver::new(vec![Ok(outcome(vec![Message::assistant(
-        "ok",
-    )]))]));
+    // The test codec decodes every stored row as a user message.
+    let mut history: Vec<Message> = (0..turn * 2).map(|_| Message::user("x")).collect();
+    history.extend([Message::user("x"), Message::assistant("x")]);
+    let driver = Arc::new(Driver::new(vec![Ok(outcome(history))]));
     let (hook, _) = hook(vec![TurnPreparation::with_tools(sent)]);
     let mut session = SessionBuilder::new(driver.clone())
         .codec(Arc::new(Codec::default()))
         .hooks(hook)
         .retain_recorded_tools(retain)
-        .transcript(locator, "agent", meta())
+        .session(locator, recorded_tools_session(), meta())
         .build()
         .unwrap();
     session
         .turn(
             SessionTurnRequest::new(Message::user("x")),
-            TurnOptions {
-                resume,
-                ..TurnOptions::default()
-            },
+            session_turn_options(ResumeMode::Session, "thread-tools"),
         )
         .await
         .unwrap();
     (driver, session.recorded_tools().cloned())
 }
 
+fn recorded_tools_session() -> SessionRef {
+    SessionRef::scoped("thread-tools", "agent-id")
+}
+
+fn recorded_tools_path(directory: &std::path::Path) -> std::path::PathBuf {
+    let dir = directory.join("session_raw");
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .map(|entry| entry.unwrap().path())
+        .filter(|path| path.extension().is_some_and(|ext| ext == "jsonl"))
+        .collect();
+    assert_eq!(files.len(), 1, "one transcript for one session: {files:?}");
+    files.remove(0)
+}
+
 fn tools_records(path: &std::path::Path) -> usize {
     std::fs::read_to_string(path)
         .unwrap()
@@ -2948,32 +2963,35 @@ fn tools_records(path: &std::path::Path) -> usize {
 async fn each_turn_records_the_tools_it_was_sent_with() {
     let directory = tempfile::tempdir().unwrap();
     let locator = Arc::new(FileTranscriptLocator::new(directory.path()));
-    let (_, recorded) = one_file_turn(locator, two_tools(), false, ResumeMode::Never).await;
+    let (_, recorded) = one_file_turn(locator, two_tools(), false, 0).await;
 
-    let path = directory.path().join("session_raw/agent.jsonl");
+    let path = recorded_tools_path(directory.path());
     let transcript = read_transcript(&path).unwrap();
     let stored = ToolSnapshot::from_json(transcript.tools.as_ref().unwrap()).unwrap();
     assert_eq!(tool_names(&stored), vec!["alpha", "beta"]);
     assert_eq!(tool_names(&recorded.unwrap()), vec!["alpha", "beta"]);
     // A request-state record, never a displayed message.
-    assert_eq!(read_transcript_display(&path).unwrap().records.len(), 1);
+    assert_eq!(
+        read_transcript_display(&path).unwrap().records.len(),
+        transcript.messages.len()
+    );
 }
 
 #[tokio::test]
 async fn a_resumed_session_keeps_tools_the_new_process_did_not_rebuild() {
     let directory = tempfile::tempdir().unwrap();
     let locator = Arc::new(FileTranscriptLocator::new(directory.path()));
-    one_file_turn(locator.clone(), two_tools(), true, ResumeMode::Never).await;
+    one_file_turn(locator.clone(), two_tools(), true, 0).await;
 
     // A "restarted" process that has only rebuilt `alpha` so far.
     let (driver, recorded) =
-        one_file_turn(locator, tools("alpha"), true, ResumeMode::LatestForAgent).await;
+        one_file_turn(locator, tools("alpha"), true, 1).await;
 
     let sent = &driver.requests.lock().unwrap()[0].tools;
     assert_eq!(tool_names(sent), vec!["alpha", "beta"]);
     assert_eq!(tool_names(&recorded.unwrap()), vec!["alpha", "beta"]);
     // Unchanged declarations are not recorded twice.
-    let path = directory.path().join("session_raw/agent.jsonl");
+    let path = recorded_tools_path(directory.path());
     assert_eq!(tools_records(&path), 1);
 }
 
@@ -2981,15 +2999,15 @@ async fn a_resumed_session_keeps_tools_the_new_process_did_not_rebuild() {
 async fn without_retention_a_changed_tool_set_is_sent_and_recorded_as_is() {
     let directory = tempfile::tempdir().unwrap();
     let locator = Arc::new(FileTranscriptLocator::new(directory.path()));
-    one_file_turn(locator.clone(), two_tools(), false, ResumeMode::Never).await;
+    one_file_turn(locator.clone(), two_tools(), false, 0).await;
     let (driver, _) =
-        one_file_turn(locator, tools("alpha"), false, ResumeMode::LatestForAgent).await;
+        one_file_turn(locator, tools("alpha"), false, 1).await;
 
     assert_eq!(
         tool_names(&driver.requests.lock().unwrap()[0].tools),
         vec!["alpha"]
     );
-    let path = directory.path().join("session_raw/agent.jsonl");
+    let path = recorded_tools_path(directory.path());
     assert_eq!(tools_records(&path), 2);
     let stored = read_transcript(&path).unwrap().tools.unwrap();
     assert_eq!(
@@ -3002,11 +3020,11 @@ async fn without_retention_a_changed_tool_set_is_sent_and_recorded_as_is() {
 async fn an_exact_tool_turn_neither_merges_nor_records() {
     let directory = tempfile::tempdir().unwrap();
     let locator = Arc::new(FileTranscriptLocator::new(directory.path()));
-    one_file_turn(locator.clone(), two_tools(), true, ResumeMode::Never).await;
+    one_file_turn(locator.clone(), two_tools(), true, 0).await;
 
-    let driver = Arc::new(Driver::new(vec![Ok(outcome(vec![Message::assistant(
-        "ok",
-    )]))]));
+    let mut history: Vec<Message> = (0..2).map(|_| Message::user("x")).collect();
+    history.extend([Message::user("x"), Message::assistant("x")]);
+    let driver = Arc::new(Driver::new(vec![Ok(outcome(history))]));
     let (hook, _) = hook(vec![TurnPreparation {
         tools: Some(ToolSnapshot::default()),
         exact_tools: true,
@@ -3016,23 +3034,22 @@ async fn an_exact_tool_turn_neither_merges_nor_records() {
         .codec(Arc::new(Codec::default()))
         .hooks(hook)
         .retain_recorded_tools(true)
-        .transcript(locator, "agent", meta())
+        .session(locator, recorded_tools_session(), meta())
         .build()
         .unwrap();
     session
         .turn(
             SessionTurnRequest::new(Message::user("x")),
-            TurnOptions {
-                resume: ResumeMode::LatestForAgent,
-                ..TurnOptions::default()
-            },
+            session_turn_options(ResumeMode::Session, "thread-tools"),
         )
         .await
         .unwrap();
 
     assert!(driver.requests.lock().unwrap()[0].tools.specs().is_empty());
-    let path = directory.path().join("session_raw/agent.jsonl");
-    let stored = read_transcript(&path).unwrap().tools.unwrap();
+    let stored = read_transcript(&recorded_tools_path(directory.path()))
+        .unwrap()
+        .tools
+        .unwrap();
     assert_eq!(
         tool_names(&ToolSnapshot::from_json(&stored).unwrap()),
         vec!["alpha", "beta"]

From 18c9f0e9c9da7c0f07feaba9035d99cb667f710c Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 04:59:09 +0530
Subject: [PATCH 09/24] fix(session): correct tools retention when host does
 not re-supply recorded tools

The tools retention logic now properly merges back recorded declarations that the host did not re-supply, ensuring that previously recorded tools are preserved when retention is enabled. Additionally, two new tests verify that the latest tools record reflects the session's tools rather than a message, and that a transcript without a tools record correctly reads as none.

Auto-committed-on: macbook
---
 crates/tinyagents-runtime/src/session.rs      |  5 +++-
 crates/tinyagents-runtime/src/test.rs         |  6 ++---
 crates/tinyagents-session/src/transcript.rs   |  3 +--
 .../tinyagents-session/src/transcript/test.rs | 27 +++++++++++++++++++
 4 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/crates/tinyagents-runtime/src/session.rs b/crates/tinyagents-runtime/src/session.rs
index accf36459..1b0d986ae 100644
--- a/crates/tinyagents-runtime/src/session.rs
+++ b/crates/tinyagents-runtime/src/session.rs
@@ -527,7 +527,10 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
     /// Merges back recorded declarations the host did not re-supply, when
     /// retention is on. See [`crate::SessionBuilder::retain_recorded_tools`].
     fn retain_recorded(&self, tools: ToolSnapshot) -> Result<ToolSnapshot, RuntimeError> {
-        let Some(recorded) = self.recorded_tools.as_ref().filter(|_| self.retain_recorded_tools)
+        let Some(recorded) = self
+            .recorded_tools
+            .as_ref()
+            .filter(|_| self.retain_recorded_tools)
         else {
             return Ok(tools);
         };
diff --git a/crates/tinyagents-runtime/src/test.rs b/crates/tinyagents-runtime/src/test.rs
index b5d56e827..d68b9cdd4 100644
--- a/crates/tinyagents-runtime/src/test.rs
+++ b/crates/tinyagents-runtime/src/test.rs
@@ -2984,8 +2984,7 @@ async fn a_resumed_session_keeps_tools_the_new_process_did_not_rebuild() {
     one_file_turn(locator.clone(), two_tools(), true, 0).await;
 
     // A "restarted" process that has only rebuilt `alpha` so far.
-    let (driver, recorded) =
-        one_file_turn(locator, tools("alpha"), true, 1).await;
+    let (driver, recorded) = one_file_turn(locator, tools("alpha"), true, 1).await;
 
     let sent = &driver.requests.lock().unwrap()[0].tools;
     assert_eq!(tool_names(sent), vec!["alpha", "beta"]);
@@ -3000,8 +2999,7 @@ async fn without_retention_a_changed_tool_set_is_sent_and_recorded_as_is() {
     let directory = tempfile::tempdir().unwrap();
     let locator = Arc::new(FileTranscriptLocator::new(directory.path()));
     one_file_turn(locator.clone(), two_tools(), false, 0).await;
-    let (driver, _) =
-        one_file_turn(locator, tools("alpha"), false, 1).await;
+    let (driver, _) = one_file_turn(locator, tools("alpha"), false, 1).await;
 
     assert_eq!(
         tool_names(&driver.requests.lock().unwrap()[0].tools),
diff --git a/crates/tinyagents-session/src/transcript.rs b/crates/tinyagents-session/src/transcript.rs
index 82c1caa18..279e2ab1d 100644
--- a/crates/tinyagents-session/src/transcript.rs
+++ b/crates/tinyagents-session/src/transcript.rs
@@ -142,8 +142,7 @@ pub use types::{
 };
 pub use writer::{
     append_interrupted_partial, append_tools_record, append_transcript_turn,
-    append_transcript_turn_with_partial,
-    write_transcript, write_transcript_if_absent,
+    append_transcript_turn_with_partial, write_transcript, write_transcript_if_absent,
 };
 
 // ── Tests ─────────────────────────────────────────────────────────────
diff --git a/crates/tinyagents-session/src/transcript/test.rs b/crates/tinyagents-session/src/transcript/test.rs
index 0a0f0d769..9ed2b2eff 100644
--- a/crates/tinyagents-session/src/transcript/test.rs
+++ b/crates/tinyagents-session/src/transcript/test.rs
@@ -626,3 +626,30 @@ fn write_transcript_if_absent_publishes_once_and_never_overwrites() {
         "first writer"
     );
 }
+
+#[test]
+fn the_latest_tools_record_is_the_sessions_tools_and_never_a_message() {
+    let dir = tempdir().unwrap();
+    let path = dir.path().join("agent.jsonl");
+    let rows = vec![TranscriptMessage::new("user", "hi")];
+    append_transcript_turn(&path, &[], &rows, &meta(), None, Some("r1")).unwrap();
+    append_tools_record(&path, &serde_json::json!([{"name": "first"}])).unwrap();
+    append_tools_record(&path, &serde_json::json!([{"name": "second"}])).unwrap();
+
+    let transcript = read_transcript(&path).unwrap();
+    assert_eq!(transcript.messages.len(), 1);
+    assert_eq!(
+        transcript.tools,
+        Some(serde_json::json!([{"name": "second"}]))
+    );
+    assert_eq!(read_transcript_display(&path).unwrap().records.len(), 1);
+}
+
+#[test]
+fn a_transcript_without_a_tools_record_reads_none() {
+    let dir = tempdir().unwrap();
+    let path = dir.path().join("agent.jsonl");
+    let rows = vec![TranscriptMessage::new("user", "hi")];
+    append_transcript_turn(&path, &[], &rows, &meta(), None, None).unwrap();
+    assert_eq!(read_transcript(&path).unwrap().tools, None);
+}

From b0ca5af724d3dc2bc19a488593ffc45599369514 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 03:29:30 +0300
Subject: [PATCH 10/24] fix(session): deduplicate prefix messages and
 consolidate tools writing

When resuming a session, the decoded history included the leading system rows that were already stored as the session's prefix, causing duplicate messages. The fix drains those rows from the decoded history after adopting them into the prefix. Additionally, the tools record is now written atomically alongside the turn data rather than as a separate append operation, preventing partial writes and ensuring tool declarations are always paired with their turn. The adoption path also preserves tool declarations when folding legacy transcripts into a session.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-runtime/src/session.rs      |  3 +-
 crates/tinyagents-session/src/transcript.rs   |  3 +-
 .../src/transcript/adoption.rs                |  8 ++-
 .../src/transcript/history.rs                 | 13 ++---
 .../src/transcript/writer.rs                  | 56 ++++++++++++++++++-
 5 files changed, 69 insertions(+), 14 deletions(-)

diff --git a/crates/tinyagents-runtime/src/session.rs b/crates/tinyagents-runtime/src/session.rs
index 1b0d986ae..963eb9be1 100644
--- a/crates/tinyagents-runtime/src/session.rs
+++ b/crates/tinyagents-runtime/src/session.rs
@@ -197,7 +197,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             .codec
             .as_ref()
             .ok_or(RuntimeError::MissingDependency("TranscriptCodec"))?;
-        let decoded = codec.decode_history(&transcript)?;
+        let mut decoded = codec.decode_history(&transcript)?;
         // The transcript already holds the prefix it was sent with as its
         // leading system rows. A session built without a prefix of its own
         // adopts those rows, so resuming never has to re-render the prompt
@@ -210,6 +210,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
                 .collect();
             if !leading.is_empty() {
                 self.prefix = PrefixSnapshot::new(leading);
+                decoded.drain(..self.prefix.messages().len());
             }
         }
         let history = self.with_prefix(decoded);
diff --git a/crates/tinyagents-session/src/transcript.rs b/crates/tinyagents-session/src/transcript.rs
index 279e2ab1d..3fcf712e5 100644
--- a/crates/tinyagents-session/src/transcript.rs
+++ b/crates/tinyagents-session/src/transcript.rs
@@ -142,7 +142,8 @@ pub use types::{
 };
 pub use writer::{
     append_interrupted_partial, append_tools_record, append_transcript_turn,
-    append_transcript_turn_with_partial, write_transcript, write_transcript_if_absent,
+    append_transcript_turn_with_partial, append_transcript_turn_with_partial_and_tools,
+    write_transcript, write_transcript_if_absent, write_transcript_if_absent_with_tools,
 };
 
 // ── Tests ─────────────────────────────────────────────────────────────
diff --git a/crates/tinyagents-session/src/transcript/adoption.rs b/crates/tinyagents-session/src/transcript/adoption.rs
index cc1b976a7..6295cc042 100644
--- a/crates/tinyagents-session/src/transcript/adoption.rs
+++ b/crates/tinyagents-session/src/transcript/adoption.rs
@@ -22,7 +22,7 @@ use super::reader::read_transcript;
 use super::session::{SessionRef, session_stem};
 use super::thread_lookup::find_root_transcripts_for_thread_reporting_unreadable;
 use super::types::{TranscriptMessage, TranscriptMeta};
-use super::writer::write_transcript_if_absent;
+use super::writer::write_transcript_if_absent_with_tools;
 
 /// What adoption did for one session.
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -126,6 +126,7 @@ pub fn adopt_legacy_session_transcripts(
     let mut earliest_created: Option<String> = None;
     let mut latest_updated: Option<String> = None;
     let mut adopted = Vec::new();
+    let mut tools = None;
 
     for path in legacy {
         // A legacy candidate must be read to be filtered, so an unreadable
@@ -162,6 +163,9 @@ pub fn adopt_legacy_session_transcripts(
         }
 
         messages.extend(transcript.messages);
+        if transcript.tools.is_some() {
+            tools = transcript.tools;
+        }
         meta.turn_count += transcript.meta.turn_count;
         meta.input_tokens += transcript.meta.input_tokens;
         meta.output_tokens += transcript.meta.output_tokens;
@@ -201,7 +205,7 @@ pub fn adopt_legacy_session_transcripts(
     // real conversation data that must not be clobbered with an adoption
     // fold that started before it existed — so a lost race here discards
     // this call's fold and reports `Ok(None)`, the same as "nothing to do".
-    if !write_transcript_if_absent(&destination, &messages, &meta)? {
+    if !write_transcript_if_absent_with_tools(&destination, &messages, &meta, tools.as_ref())? {
         tracing::debug!(
             "[transcript-adoption] session={stem} lost the race to a concurrent write; \
              discarding this fold"
diff --git a/crates/tinyagents-session/src/transcript/history.rs b/crates/tinyagents-session/src/transcript/history.rs
index 706c44bb1..31ba6de00 100644
--- a/crates/tinyagents-session/src/transcript/history.rs
+++ b/crates/tinyagents-session/src/transcript/history.rs
@@ -726,17 +726,16 @@ impl FileTranscriptHistory {
             turn.request_id,
             self.path.display()
         );
-        append_transcript_turn(
+        crate::transcript::append_transcript_turn_with_partial_and_tools(
             &self.path,
             turn.prev,
             turn.next,
             turn.meta,
             turn.turn_usage,
             turn.request_id,
+            None,
+            turn.tools,
         )?;
-        if let Some(tools) = turn.tools {
-            crate::transcript::append_tools_record(&self.path, tools)?;
-        }
         Ok(())
     }
 
@@ -754,7 +753,7 @@ impl FileTranscriptHistory {
             partial.is_some(),
             self.path.display()
         );
-        crate::transcript::append_transcript_turn_with_partial(
+        crate::transcript::append_transcript_turn_with_partial_and_tools(
             &self.path,
             turn.prev,
             turn.next,
@@ -762,10 +761,8 @@ impl FileTranscriptHistory {
             turn.turn_usage,
             turn.request_id,
             partial,
+            turn.tools,
         )?;
-        if let Some(tools) = turn.tools {
-            crate::transcript::append_tools_record(&self.path, tools)?;
-        }
         Ok(())
     }
 
diff --git a/crates/tinyagents-session/src/transcript/writer.rs b/crates/tinyagents-session/src/transcript/writer.rs
index 3d669b47d..ba56c3cfd 100644
--- a/crates/tinyagents-session/src/transcript/writer.rs
+++ b/crates/tinyagents-session/src/transcript/writer.rs
@@ -64,6 +64,17 @@ pub fn write_transcript_if_absent(
     jsonl_path: &Path,
     messages: &[TranscriptMessage],
     meta: &TranscriptMeta,
+) -> Result<bool> {
+    write_transcript_if_absent_with_tools(jsonl_path, messages, meta, None)
+}
+
+/// Like [`write_transcript_if_absent`], additionally preserving the latest
+/// recorded tool declarations when a transcript is migrated into a session.
+pub fn write_transcript_if_absent_with_tools(
+    jsonl_path: &Path,
+    messages: &[TranscriptMessage],
+    meta: &TranscriptMeta,
+    tools: Option<&serde_json::Value>,
 ) -> Result<bool> {
     if let Some(parent) = jsonl_path.parent() {
         fs::create_dir_all(parent)
@@ -74,6 +85,10 @@ pub fn write_transcript_if_absent(
     jsonl_buf.push_str(&meta_line_json(meta)?);
     jsonl_buf.push('\n');
     serialise_message_lines(messages, None, None, &mut jsonl_buf)?;
+    if let Some(tools) = tools {
+        jsonl_buf.push_str(&tools_line_json(tools)?);
+        jsonl_buf.push('\n');
+    }
 
     let published = publish_transcript_if_absent(jsonl_path, jsonl_buf.as_bytes())
         .with_context(|| format!("publish transcript {}", jsonl_path.display()))?;
@@ -122,7 +137,7 @@ pub fn append_transcript_turn(
     turn_usage: Option<&TurnUsage>,
     request_id: Option<&str>,
 ) -> Result<()> {
-    append_transcript_turn_with_partial(
+    append_transcript_turn_with_partial_and_tools(
         jsonl_path,
         prev_persisted,
         messages,
@@ -130,6 +145,7 @@ pub fn append_transcript_turn(
         turn_usage,
         request_id,
         None,
+        None,
     )
 }
 
@@ -149,6 +165,30 @@ pub fn append_transcript_turn_with_partial(
     turn_usage: Option<&TurnUsage>,
     request_id: Option<&str>,
     partial: Option<&TranscriptPartial>,
+) -> Result<()> {
+    append_transcript_turn_with_partial_and_tools(
+        jsonl_path,
+        prev_persisted,
+        messages,
+        meta,
+        turn_usage,
+        request_id,
+        partial,
+        None,
+    )
+}
+
+/// Appends a turn, optional display partial, and optional tool declarations
+/// from one serialized buffer and one file-write operation.
+pub fn append_transcript_turn_with_partial_and_tools(
+    jsonl_path: &Path,
+    prev_persisted: &[TranscriptMessage],
+    messages: &[TranscriptMessage],
+    meta: &TranscriptMeta,
+    turn_usage: Option<&TurnUsage>,
+    request_id: Option<&str>,
+    partial: Option<&TranscriptPartial>,
+    tools: Option<&serde_json::Value>,
 ) -> Result<()> {
     if let Some(parent) = jsonl_path.parent() {
         fs::create_dir_all(parent)
@@ -164,6 +204,10 @@ pub fn append_transcript_turn_with_partial(
         buf.push('\n');
         serialise_message_lines(messages, turn_usage, request_id, &mut buf)?;
         serialise_interrupted_partial(partial, request_id, &mut buf)?;
+        if let Some(tools) = tools {
+            buf.push_str(&tools_line_json(tools)?);
+            buf.push('\n');
+        }
         fs::write(jsonl_path, buf.as_bytes())
             .with_context(|| format!("create transcript {}", jsonl_path.display()))?;
         tracing::debug!(
@@ -231,6 +275,10 @@ pub fn append_transcript_turn_with_partial(
     buf.push_str(&meta_line_json(meta)?);
     buf.push('\n');
     serialise_interrupted_partial(partial, request_id, &mut buf)?;
+    if let Some(tools) = tools {
+        buf.push_str(&tools_line_json(tools)?);
+        buf.push('\n');
+    }
 
     append_bytes(jsonl_path, buf.as_bytes())?;
     render_md_companion(jsonl_path, messages, meta, turn_usage);
@@ -241,6 +289,11 @@ pub fn append_transcript_turn_with_partial(
 /// session's latest turn was sent with. The file must already exist (its
 /// first line is always `_meta`), so callers append this after the turn.
 pub fn append_tools_record(jsonl_path: &Path, tools: &serde_json::Value) -> Result<()> {
+    anyhow::ensure!(
+        jsonl_path.is_file(),
+        "transcript must exist before appending tool declarations: {}",
+        jsonl_path.display()
+    );
     let mut line = tools_line_json(tools)?;
     line.push('\n');
     append_bytes(jsonl_path, line.as_bytes())?;
@@ -461,7 +514,6 @@ fn publish_transcript_if_absent(path: &Path, contents: &[u8]) -> Result<bool> {
 fn append_bytes(path: &Path, bytes: &[u8]) -> Result<()> {
     use std::io::Write;
     let mut file = fs::OpenOptions::new()
-        .create(true)
         .append(true)
         .open(path)
         .with_context(|| format!("open transcript for append {}", path.display()))?;

From ed1cb6eb1e0e7fd055785dbdbe071487a7a3fc97 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 03:30:11 +0300
Subject: [PATCH 11/24] test(transcript): add tests for tool snapshot
 preservation and atomic append

Add two tests that verify tool record handling during transcript adoption and turn appending. The adoption test ensures that when multiple legacy transcripts exist, the newest one's tool snapshot is preserved rather than overwritten. The append test confirms that a turn and its associated tools are written atomically in a single append buffer, preventing partial writes.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 .../src/transcript/adoption_test.rs           | 28 ++++++++++++++++++-
 .../src/transcript/history.rs                 |  6 ++--
 .../tinyagents-session/src/transcript/test.rs | 26 +++++++++++++++++
 3 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/crates/tinyagents-session/src/transcript/adoption_test.rs b/crates/tinyagents-session/src/transcript/adoption_test.rs
index 711b15d8b..b33b2dccb 100644
--- a/crates/tinyagents-session/src/transcript/adoption_test.rs
+++ b/crates/tinyagents-session/src/transcript/adoption_test.rs
@@ -1,7 +1,8 @@
 use super::*;
 use crate::transcript::{
     FileTranscriptLocator, MessageUsage, TranscriptLocator, TranscriptToolCall, TurnUsage,
-    append_transcript_turn, read_transcript, write_transcript, write_transcript_if_absent,
+    append_tools_record, append_transcript_turn, read_transcript, write_transcript,
+    write_transcript_if_absent,
 };
 use tempfile::tempdir;
 
@@ -124,6 +125,31 @@ fn adoption_sums_usage_and_spans_the_whole_conversation() {
     assert_eq!(meta.updated, "2026-02-02T00:00:00Z");
 }
 
+#[test]
+fn adoption_preserves_the_newest_legacy_tool_snapshot() {
+    let dir = tempdir().unwrap();
+    let thread = "thread-tools";
+    write_legacy(dir.path(), "1000_a", "2026-01-01T00:00:00Z", "one", thread);
+    write_legacy(dir.path(), "2000_a", "2026-01-02T00:00:00Z", "two", thread);
+    let newer = dir.path().join("2000_a.jsonl");
+    append_tools_record(&newer, &serde_json::json!([{"name": "newer"}])).unwrap();
+
+    let session = SessionRef::scoped(thread, "orchestrator");
+    let adoption = adopt_legacy_session_transcripts(
+        dir.path(),
+        &session,
+        thread,
+        &legacy_meta("", "", thread),
+    )
+    .unwrap()
+    .expect("legacy roots should be adopted");
+
+    assert_eq!(
+        read_transcript(&adoption.path).unwrap().tools,
+        Some(serde_json::json!([{"name": "newer"}]))
+    );
+}
+
 #[test]
 fn adoption_never_touches_the_files_it_reads() {
     let dir = tempdir().unwrap();
diff --git a/crates/tinyagents-session/src/transcript/history.rs b/crates/tinyagents-session/src/transcript/history.rs
index 31ba6de00..016d235b8 100644
--- a/crates/tinyagents-session/src/transcript/history.rs
+++ b/crates/tinyagents-session/src/transcript/history.rs
@@ -25,9 +25,9 @@ use crate::transcript::types::TranscriptMessage;
 
 use crate::transcript::{
     SessionAdoption, SessionRef, SessionTranscript, TranscriptMeta, TurnUsage,
-    adopt_legacy_session_transcripts, append_transcript_turn, find_latest_transcript,
-    find_root_transcript_for_thread, find_root_transcript_for_thread_scoped, read_transcript,
-    resolve_keyed_transcript_path, session_stem,
+    adopt_legacy_session_transcripts, find_latest_transcript, find_root_transcript_for_thread,
+    find_root_transcript_for_thread_scoped, read_transcript, resolve_keyed_transcript_path,
+    session_stem,
 };
 
 /// Upper bound on the compaction generations one session may accumulate.
diff --git a/crates/tinyagents-session/src/transcript/test.rs b/crates/tinyagents-session/src/transcript/test.rs
index 835c4b0e6..9a03a8a1b 100644
--- a/crates/tinyagents-session/src/transcript/test.rs
+++ b/crates/tinyagents-session/src/transcript/test.rs
@@ -658,6 +658,32 @@ fn the_latest_tools_record_is_the_sessions_tools_and_never_a_message() {
     assert_eq!(read_transcript_display(&path).unwrap().records.len(), 1);
 }
 
+#[test]
+fn a_turn_and_its_tools_are_serialized_in_one_append_buffer() {
+    let dir = tempdir().unwrap();
+    let path = dir.path().join("agent.jsonl");
+    let rows = vec![TranscriptMessage::new("user", "hi")];
+
+    append_transcript_turn_with_partial_and_tools(
+        &path,
+        &[],
+        &rows,
+        &meta(),
+        None,
+        Some("r1"),
+        None,
+        Some(&serde_json::json!([{"name": "search"}])),
+    )
+    .unwrap();
+
+    let transcript = read_transcript(&path).unwrap();
+    assert_eq!(transcript.messages, rows);
+    assert_eq!(
+        transcript.tools,
+        Some(serde_json::json!([{"name": "search"}]))
+    );
+}
+
 #[test]
 fn a_transcript_without_a_tools_record_reads_none() {
     let dir = tempdir().unwrap();

From 91f90e39e1ee20b5ba96e21c56992234ce3e203b Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 03:30:43 +0300
Subject: [PATCH 12/24] chore: files changed
 crates/tinyagents-session/src/transcript/adoption_test.rs,crates/tinyagents-ses

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-session/src/transcript/adoption_test.rs | 2 +-
 crates/tinyagents-session/src/transcript/test.rs          | 4 +++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/crates/tinyagents-session/src/transcript/adoption_test.rs b/crates/tinyagents-session/src/transcript/adoption_test.rs
index b33b2dccb..55947d1b5 100644
--- a/crates/tinyagents-session/src/transcript/adoption_test.rs
+++ b/crates/tinyagents-session/src/transcript/adoption_test.rs
@@ -131,7 +131,7 @@ fn adoption_preserves_the_newest_legacy_tool_snapshot() {
     let thread = "thread-tools";
     write_legacy(dir.path(), "1000_a", "2026-01-01T00:00:00Z", "one", thread);
     write_legacy(dir.path(), "2000_a", "2026-01-02T00:00:00Z", "two", thread);
-    let newer = dir.path().join("2000_a.jsonl");
+    let newer = resolve_keyed_transcript_path(dir.path(), "2000_a").unwrap();
     append_tools_record(&newer, &serde_json::json!([{"name": "newer"}])).unwrap();
 
     let session = SessionRef::scoped(thread, "orchestrator");
diff --git a/crates/tinyagents-session/src/transcript/test.rs b/crates/tinyagents-session/src/transcript/test.rs
index 9a03a8a1b..61d1b504b 100644
--- a/crates/tinyagents-session/src/transcript/test.rs
+++ b/crates/tinyagents-session/src/transcript/test.rs
@@ -677,7 +677,9 @@ fn a_turn_and_its_tools_are_serialized_in_one_append_buffer() {
     .unwrap();
 
     let transcript = read_transcript(&path).unwrap();
-    assert_eq!(transcript.messages, rows);
+    assert_eq!(transcript.messages.len(), 1);
+    assert_eq!(transcript.messages[0].content, "hi");
+    assert_eq!(transcript.messages[0].request_id.as_deref(), Some("r1"));
     assert_eq!(
         transcript.tools,
         Some(serde_json::json!([{"name": "search"}]))

From 2e6ad1d806b91bba8b998ff106c92cc14518c52b Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 03:31:08 +0300
Subject: [PATCH 13/24] refactor(session): consolidate partial and tools
 parameters into a struct

Replaced the separate `partial` and `tools` parameters in `append_transcript_turn_with_partial_and_tools` with a single `AppendTranscriptExtras` struct, and renamed the function to `append_transcript_turn_with_extras`. This simplifies the public API by reducing parameter count and makes future additions of optional turn metadata easier without changing the function signature.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-session/src/transcript.rs   |  4 +--
 .../src/transcript/history.rs                 | 16 +++++++----
 .../tinyagents-session/src/transcript/test.rs |  8 ++++--
 .../src/transcript/writer.rs                  | 28 +++++++++++++------
 4 files changed, 36 insertions(+), 20 deletions(-)

diff --git a/crates/tinyagents-session/src/transcript.rs b/crates/tinyagents-session/src/transcript.rs
index 3fcf712e5..72a5ab4ce 100644
--- a/crates/tinyagents-session/src/transcript.rs
+++ b/crates/tinyagents-session/src/transcript.rs
@@ -142,8 +142,8 @@ pub use types::{
 };
 pub use writer::{
     append_interrupted_partial, append_tools_record, append_transcript_turn,
-    append_transcript_turn_with_partial, append_transcript_turn_with_partial_and_tools,
-    write_transcript, write_transcript_if_absent, write_transcript_if_absent_with_tools,
+    append_transcript_turn_with_partial, write_transcript, write_transcript_if_absent,
+    write_transcript_if_absent_with_tools,
 };
 
 // ── Tests ─────────────────────────────────────────────────────────────
diff --git a/crates/tinyagents-session/src/transcript/history.rs b/crates/tinyagents-session/src/transcript/history.rs
index 016d235b8..85cee889b 100644
--- a/crates/tinyagents-session/src/transcript/history.rs
+++ b/crates/tinyagents-session/src/transcript/history.rs
@@ -726,15 +726,17 @@ impl FileTranscriptHistory {
             turn.request_id,
             self.path.display()
         );
-        crate::transcript::append_transcript_turn_with_partial_and_tools(
+        crate::transcript::writer::append_transcript_turn_with_extras(
             &self.path,
             turn.prev,
             turn.next,
             turn.meta,
             turn.turn_usage,
             turn.request_id,
-            None,
-            turn.tools,
+            crate::transcript::writer::AppendTranscriptExtras {
+                partial: None,
+                tools: turn.tools,
+            },
         )?;
         Ok(())
     }
@@ -753,15 +755,17 @@ impl FileTranscriptHistory {
             partial.is_some(),
             self.path.display()
         );
-        crate::transcript::append_transcript_turn_with_partial_and_tools(
+        crate::transcript::writer::append_transcript_turn_with_extras(
             &self.path,
             turn.prev,
             turn.next,
             turn.meta,
             turn.turn_usage,
             turn.request_id,
-            partial,
-            turn.tools,
+            crate::transcript::writer::AppendTranscriptExtras {
+                partial,
+                tools: turn.tools,
+            },
         )?;
         Ok(())
     }
diff --git a/crates/tinyagents-session/src/transcript/test.rs b/crates/tinyagents-session/src/transcript/test.rs
index 61d1b504b..7f91e50b9 100644
--- a/crates/tinyagents-session/src/transcript/test.rs
+++ b/crates/tinyagents-session/src/transcript/test.rs
@@ -664,15 +664,17 @@ fn a_turn_and_its_tools_are_serialized_in_one_append_buffer() {
     let path = dir.path().join("agent.jsonl");
     let rows = vec![TranscriptMessage::new("user", "hi")];
 
-    append_transcript_turn_with_partial_and_tools(
+    writer::append_transcript_turn_with_extras(
         &path,
         &[],
         &rows,
         &meta(),
         None,
         Some("r1"),
-        None,
-        Some(&serde_json::json!([{"name": "search"}])),
+        writer::AppendTranscriptExtras {
+            partial: None,
+            tools: Some(&serde_json::json!([{"name": "search"}])),
+        },
     )
     .unwrap();
 
diff --git a/crates/tinyagents-session/src/transcript/writer.rs b/crates/tinyagents-session/src/transcript/writer.rs
index ba56c3cfd..4ef6a3133 100644
--- a/crates/tinyagents-session/src/transcript/writer.rs
+++ b/crates/tinyagents-session/src/transcript/writer.rs
@@ -137,15 +137,17 @@ pub fn append_transcript_turn(
     turn_usage: Option<&TurnUsage>,
     request_id: Option<&str>,
 ) -> Result<()> {
-    append_transcript_turn_with_partial_and_tools(
+    append_transcript_turn_with_extras(
         jsonl_path,
         prev_persisted,
         messages,
         meta,
         turn_usage,
         request_id,
-        None,
-        None,
+        AppendTranscriptExtras {
+            partial: None,
+            tools: None,
+        },
     )
 }
 
@@ -166,30 +168,38 @@ pub fn append_transcript_turn_with_partial(
     request_id: Option<&str>,
     partial: Option<&TranscriptPartial>,
 ) -> Result<()> {
-    append_transcript_turn_with_partial_and_tools(
+    append_transcript_turn_with_extras(
         jsonl_path,
         prev_persisted,
         messages,
         meta,
         turn_usage,
         request_id,
-        partial,
-        None,
+        AppendTranscriptExtras {
+            partial,
+            tools: None,
+        },
     )
 }
 
+/// Optional turn records serialized alongside a turn's logical delta.
+pub(crate) struct AppendTranscriptExtras<'a> {
+    pub partial: Option<&'a TranscriptPartial>,
+    pub tools: Option<&'a serde_json::Value>,
+}
+
 /// Appends a turn, optional display partial, and optional tool declarations
 /// from one serialized buffer and one file-write operation.
-pub fn append_transcript_turn_with_partial_and_tools(
+pub(crate) fn append_transcript_turn_with_extras(
     jsonl_path: &Path,
     prev_persisted: &[TranscriptMessage],
     messages: &[TranscriptMessage],
     meta: &TranscriptMeta,
     turn_usage: Option<&TurnUsage>,
     request_id: Option<&str>,
-    partial: Option<&TranscriptPartial>,
-    tools: Option<&serde_json::Value>,
+    extras: AppendTranscriptExtras<'_>,
 ) -> Result<()> {
+    let AppendTranscriptExtras { partial, tools } = extras;
     if let Some(parent) = jsonl_path.parent() {
         fs::create_dir_all(parent)
             .with_context(|| format!("create transcript dir {}", parent.display()))?;

From d255087cbe4f0dacc39b5c6009c49ea4779f8a61 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 03:35:25 +0300
Subject: [PATCH 14/24] refactor(session): extract recorded tools decoding into
 a helper method

Moves the inline `ToolSnapshot::from_json` call with its error handling into a dedicated `decode_recorded_tools` method, reducing duplication and making the session's resume and branch-switch paths consistently decode the tools field. Also updates the doc comments in the history module to refer to the transcript writer's turn-append function by description rather than by a specific function name, keeping the documentation accurate after internal refactoring.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-runtime/src/session.rs      | 25 +++++++++++--------
 .../src/transcript/history.rs                 |  4 +--
 2 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/crates/tinyagents-runtime/src/session.rs b/crates/tinyagents-runtime/src/session.rs
index 963eb9be1..e00cf8e6f 100644
--- a/crates/tinyagents-runtime/src/session.rs
+++ b/crates/tinyagents-runtime/src/session.rs
@@ -220,16 +220,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
         // or the one that wrote it.
         self.committed_turns = self.committed_turns.max(transcript.meta.turn_count);
         self.recorded_tools_json = transcript.tools.clone();
-        self.recorded_tools = match transcript.tools.as_ref() {
-            Some(value) => match ToolSnapshot::from_json(value) {
-                Ok(tools) => Some(tools),
-                Err(error) => {
-                    tracing::warn!("[session] ignoring unreadable recorded tools: {error}");
-                    None
-                }
-            },
-            None => None,
-        };
+        self.recorded_tools = Self::decode_recorded_tools(transcript.tools.as_ref());
         tracing::debug!(
             "[session] resumed history={} committed_turns={} recorded_tools={}",
             history.len(),
@@ -315,7 +306,8 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
                 .map_err(|error| RuntimeError::Persistence(error.to_string()))?;
             match destination {
                 Some(destination_transcript) => {
-                    self.recorded_tools_json = destination_transcript.tools;
+                    self.recorded_tools_json = destination_transcript.tools.clone();
+                    self.recorded_tools = Self::decode_recorded_tools(destination_transcript.tools.as_ref());
                     self.persisted = destination_transcript.messages;
                     if let Some(target) = self.target.as_mut() {
                         target.meta = destination_transcript.meta;
@@ -329,6 +321,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
                     // whatever session this target now names (`resume`'s
                     // own head-resolution above may have rebound it).
                     self.recorded_tools_json = None;
+                    self.recorded_tools = None;
                     self.persisted = Vec::new();
                     if let Some(target) = self.target.as_mut() {
                         target.meta = pre_scan_meta;
@@ -545,6 +538,16 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
         Ok(merged)
     }
 
+    fn decode_recorded_tools(value: Option<&serde_json::Value>) -> Option<ToolSnapshot> {
+        value.and_then(|value| match ToolSnapshot::from_json(value) {
+            Ok(tools) => Some(tools),
+            Err(error) => {
+                tracing::warn!("[session] ignoring unreadable recorded tools: {error}");
+                None
+            }
+        })
+    }
+
     fn apply_resume_preparation(
         &mut self,
         preparation: ResumePreparation,
diff --git a/crates/tinyagents-session/src/transcript/history.rs b/crates/tinyagents-session/src/transcript/history.rs
index 85cee889b..0a601f906 100644
--- a/crates/tinyagents-session/src/transcript/history.rs
+++ b/crates/tinyagents-session/src/transcript/history.rs
@@ -40,7 +40,7 @@ const MAX_GENERATIONS: u32 = 4096;
 
 /// One turn's worth of transcript write, borrowed.
 ///
-/// The fields mirror [`append_transcript_turn`]'s argument list one-for-one and
+/// The fields mirror the transcript writer's turn-append argument list one-for-one and
 /// in order, so [`TranscriptHistory::append_turn`]'s forwarding is visually
 /// checkable against the format's own signature. Nothing is transformed on the
 /// way through; that is the entire correctness claim of this seam and
@@ -802,7 +802,7 @@ impl FileTranscriptHistory {
 }
 
 impl TranscriptHistory for FileTranscriptHistory {
-    /// Pure forwarder: every argument reaches [`append_transcript_turn`]
+    /// Pure forwarder: every argument reaches the transcript writer's turn append
     /// untouched, so the bytes this writes are identical to what the free
     /// function would have written at the call site.
     ///

From 60f49130757ad433b7ba4af2d5166e766c8b6bed Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 03:36:01 +0300
Subject: [PATCH 15/24] test(session): add test for thread resume restoring
 tools from write destination

Add a test that verifies when a session is resumed using the Thread resume mode, the tool set is restored from the session's own write destination rather than from the scanned source transcript, ensuring the correct tools are available after resume.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-runtime/src/session.rs |  3 +-
 crates/tinyagents-runtime/src/test.rs    | 57 ++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/crates/tinyagents-runtime/src/session.rs b/crates/tinyagents-runtime/src/session.rs
index e00cf8e6f..f31df440a 100644
--- a/crates/tinyagents-runtime/src/session.rs
+++ b/crates/tinyagents-runtime/src/session.rs
@@ -307,7 +307,8 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             match destination {
                 Some(destination_transcript) => {
                     self.recorded_tools_json = destination_transcript.tools.clone();
-                    self.recorded_tools = Self::decode_recorded_tools(destination_transcript.tools.as_ref());
+                    self.recorded_tools =
+                        Self::decode_recorded_tools(destination_transcript.tools.as_ref());
                     self.persisted = destination_transcript.messages;
                     if let Some(target) = self.target.as_mut() {
                         target.meta = destination_transcript.meta;
diff --git a/crates/tinyagents-runtime/src/test.rs b/crates/tinyagents-runtime/src/test.rs
index d68b9cdd4..34aea3bc5 100644
--- a/crates/tinyagents-runtime/src/test.rs
+++ b/crates/tinyagents-runtime/src/test.rs
@@ -2994,6 +2994,63 @@ async fn a_resumed_session_keeps_tools_the_new_process_did_not_rebuild() {
     assert_eq!(tools_records(&path), 1);
 }
 
+#[tokio::test]
+async fn thread_resume_restores_tools_from_its_write_destination() {
+    let directory = tempfile::tempdir().unwrap();
+    let session_ref = SessionRef::scoped("thread-tools", "agent-id");
+    let locator = Arc::new(FileTranscriptLocator::new(directory.path()));
+    let destination = directory
+        .path()
+        .join("session_raw")
+        .join(format!("{}.jsonl", session_stem(&session_ref)));
+
+    locator
+        .open_session(&session_ref, meta())
+        .unwrap()
+        .append(TranscriptMessage::new("user", "destination"))
+        .unwrap();
+    tinyagents_session::transcript::append_tools_record(&destination, &two_tools().to_json())
+        .unwrap();
+
+    let mut scanned_meta = meta();
+    scanned_meta.thread_id = Some("thread-tools".into());
+    scanned_meta.created = "zzz-scanned-created".into();
+    tinyagents_session::transcript::write_transcript(
+        &directory.path().join("session_raw/scanned.jsonl"),
+        &[TranscriptMessage::new("user", "scanned")],
+        &scanned_meta,
+        None,
+    )
+    .unwrap();
+
+    let driver = Arc::new(Driver::new(vec![Ok(outcome(vec![
+        Message::user("scanned"),
+        Message::assistant("reply"),
+    ]))]));
+    let (hook, _) = hook(vec![TurnPreparation::with_tools(tools("alpha"))]);
+    let mut session = SessionBuilder::new(driver.clone())
+        .codec(Arc::new(Codec::default()))
+        .hooks(hook)
+        .retain_recorded_tools(true)
+        .session(locator, session_ref, meta())
+        .build()
+        .unwrap();
+
+    session
+        .turn(
+            SessionTurnRequest::new(Message::user("scanned")),
+            session_turn_options(ResumeMode::Thread, "thread-tools"),
+        )
+        .await
+        .unwrap();
+
+    assert_eq!(
+        tool_names(&driver.requests.lock().unwrap()[0].tools),
+        vec!["alpha", "beta"],
+        "retention must use the bound destination's snapshot, not the scanned source's"
+    );
+}
+
 #[tokio::test]
 async fn without_retention_a_changed_tool_set_is_sent_and_recorded_as_is() {
     let directory = tempfile::tempdir().unwrap();

From 2ba835f97e8402cebb592ec12927951e6a26e6c1 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 03:40:19 +0300
Subject: [PATCH 16/24] fix(session): carry recorded tools into compaction
 generation

Exact-tool turns deliberately do not replace the durable tool list, but a successor generation created by compaction must still carry that list forward; otherwise a later resume would lose the recorded tools. The change adjusts the logic so that when a pending generation exists, the tools from the recorded snapshot are preserved in the new file.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-runtime/src/session.rs | 13 +++++--
 crates/tinyagents-runtime/src/test.rs    | 43 ++++++++++++++++++++++++
 2 files changed, 53 insertions(+), 3 deletions(-)

diff --git a/crates/tinyagents-runtime/src/session.rs b/crates/tinyagents-runtime/src/session.rs
index f31df440a..f8f1e14fb 100644
--- a/crates/tinyagents-runtime/src/session.rs
+++ b/crates/tinyagents-runtime/src/session.rs
@@ -714,9 +714,16 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
         // in the file being written — always for a fresh generation, whose
         // file starts with none.
         let tools_json = tools.map(ToolSnapshot::to_json);
-        let tools_record = tools_json.as_ref().filter(|json| {
-            pending_generation.is_some() || self.recorded_tools_json.as_ref() != Some(*json)
-        });
+        let tools_record = if pending_generation.is_some() {
+            // Exact-tool turns deliberately do not replace the durable tool
+            // list. A successor generation is a fresh file, though, so it
+            // must carry that list forward or a later resume would lose it.
+            tools_json.as_ref().or(self.recorded_tools_json.as_ref())
+        } else {
+            tools_json
+                .as_ref()
+                .filter(|json| self.recorded_tools_json.as_ref() != Some(*json))
+        };
         meta.thread_id = thread_id.map(str::to_owned).or(meta.thread_id);
         transcript
             .append_turn_with_partial(
diff --git a/crates/tinyagents-runtime/src/test.rs b/crates/tinyagents-runtime/src/test.rs
index 34aea3bc5..cd10b6c30 100644
--- a/crates/tinyagents-runtime/src/test.rs
+++ b/crates/tinyagents-runtime/src/test.rs
@@ -3111,6 +3111,49 @@ async fn an_exact_tool_turn_neither_merges_nor_records() {
     );
 }
 
+#[tokio::test]
+async fn an_exact_tool_turn_carries_recorded_tools_into_a_compaction_generation() {
+    let directory = tempfile::tempdir().unwrap();
+    let locator = Arc::new(FileTranscriptLocator::new(directory.path()));
+    one_file_turn(locator.clone(), two_tools(), true, 0).await;
+
+    // Return a reduced history so persistence opens a successor generation.
+    let driver = Arc::new(Driver::new(vec![Ok(outcome(vec![
+        Message::user("x"),
+        Message::assistant("compacted"),
+    ]))]));
+    let (hook, _) = hook(vec![TurnPreparation {
+        tools: Some(ToolSnapshot::default()),
+        exact_tools: true,
+        ..TurnPreparation::default()
+    }]);
+    let mut session = SessionBuilder::new(driver)
+        .codec(Arc::new(Codec::default()))
+        .hooks(hook)
+        .retain_recorded_tools(true)
+        .session(locator, recorded_tools_session(), meta())
+        .build()
+        .unwrap();
+    session
+        .turn(
+            SessionTurnRequest::new(Message::user("x")),
+            session_turn_options(ResumeMode::Session, "thread-tools"),
+        )
+        .await
+        .unwrap();
+
+    let head = std::fs::read_dir(directory.path().join("session_raw"))
+        .unwrap()
+        .map(|entry| entry.unwrap().path())
+        .find(|path| path.to_string_lossy().contains(".g1.jsonl"))
+        .expect("compaction successor must exist");
+    let stored = read_transcript(&head).unwrap().tools.unwrap();
+    assert_eq!(
+        tool_names(&ToolSnapshot::from_json(&stored).unwrap()),
+        vec!["alpha", "beta"]
+    );
+}
+
 #[tokio::test]
 async fn resume_adopts_the_stored_prefix_and_its_committed_turns() {
     let (locator, _) = locator(Some(SessionTranscript {

From 21222e33998a3f1035cb9a453459efd7533f7f2c Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 03:40:55 +0300
Subject: [PATCH 17/24] fix(runtime): remove redundant user message from test
 driver setup

The test driver was providing an extra user message that was not needed for the compaction scenario being tested. Removing it keeps the test focused on verifying that recorded tools are carried into a new compaction generation.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-runtime/src/test.rs | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/crates/tinyagents-runtime/src/test.rs b/crates/tinyagents-runtime/src/test.rs
index cd10b6c30..651c23162 100644
--- a/crates/tinyagents-runtime/src/test.rs
+++ b/crates/tinyagents-runtime/src/test.rs
@@ -3118,10 +3118,9 @@ async fn an_exact_tool_turn_carries_recorded_tools_into_a_compaction_generation(
     one_file_turn(locator.clone(), two_tools(), true, 0).await;
 
     // Return a reduced history so persistence opens a successor generation.
-    let driver = Arc::new(Driver::new(vec![Ok(outcome(vec![
-        Message::user("x"),
-        Message::assistant("compacted"),
-    ]))]));
+    let driver = Arc::new(Driver::new(vec![Ok(outcome(vec![Message::assistant(
+        "compacted",
+    )]))]));
     let (hook, _) = hook(vec![TurnPreparation {
         tools: Some(ToolSnapshot::default()),
         exact_tools: true,

From 6ac9a821aadfb42f5fac44a017e944e3b29a9adc Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 03:45:43 +0300
Subject: [PATCH 18/24] fix(runtime): record tool declarations on every
 ordinary turn

Previously, the runtime only wrote a tool record to the transcript when the declarations differed from the session's cached snapshot. This was unsafe when multiple live sessions appended to the same transcript, as a session could skip recording its tools based on stale local state. Now every ordinary turn records its sent tool snapshot, and the session updates its in-memory cache after each successful turn rather than inside the persist method. In-memory sessions without a transcript target also retain tools correctly across turns.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-runtime/src/session.rs      | 30 +++++++-----
 crates/tinyagents-runtime/src/test.rs         | 49 ++++++++++++++++++-
 .../src/transcript/history.rs                 |  5 +-
 3 files changed, 67 insertions(+), 17 deletions(-)

diff --git a/crates/tinyagents-runtime/src/session.rs b/crates/tinyagents-runtime/src/session.rs
index f8f1e14fb..e31037573 100644
--- a/crates/tinyagents-runtime/src/session.rs
+++ b/crates/tinyagents-runtime/src/session.rs
@@ -28,8 +28,7 @@ pub struct Session<C: Clone + Send + Sync + 'static = ()> {
     /// Tool declarations this session last sent, restored from the transcript
     /// on resume and updated after every recorded turn.
     recorded_tools: Option<ToolSnapshot>,
-    /// The `tools` record currently in force in the bound transcript file,
-    /// used to write a new record only when the declarations change.
+    /// The `tools` record currently in force in the bound transcript file.
     recorded_tools_json: Option<serde_json::Value>,
     retain_recorded_tools: bool,
 }
@@ -452,6 +451,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
                         turn_usage.as_ref(),
                         record_tools.as_ref(),
                     )?;
+                    self.remember_sent_tools(record_tools.as_ref());
                     self.history = partial_history;
                     self.persisted = raw;
                     if receipt.is_some() {
@@ -485,6 +485,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             turn_usage.as_ref(),
             record_tools.as_ref(),
         )?;
+        self.remember_sent_tools(record_tools.as_ref());
         self.history = committed.history.clone();
         self.persisted = raw;
         self.committed_turns += 1;
@@ -710,9 +711,10 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
         };
         meta.turn_count += 1;
         meta.updated = chrono::Utc::now().to_rfc3339();
-        // Record the declarations when they differ from the record in force
-        // in the file being written — always for a fresh generation, whose
-        // file starts with none.
+        // Record every ordinary turn's declarations. Comparing against this
+        // session's cached snapshot is unsafe when another live Session has
+        // appended to the same transcript since our last turn; this append is
+        // performed under the history's path lock.
         let tools_json = tools.map(ToolSnapshot::to_json);
         let tools_record = if pending_generation.is_some() {
             // Exact-tool turns deliberately do not replace the durable tool
@@ -720,9 +722,7 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             // must carry that list forward or a later resume would lose it.
             tools_json.as_ref().or(self.recorded_tools_json.as_ref())
         } else {
-            tools_json
-                .as_ref()
-                .filter(|json| self.recorded_tools_json.as_ref() != Some(*json))
+            tools_json.as_ref()
         };
         meta.thread_id = thread_id.map(str::to_owned).or(meta.thread_id);
         transcript
@@ -749,10 +749,6 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             self.transcript = Some(handle);
         }
         target.meta = meta;
-        if let (Some(snapshot), Some(json)) = (tools, tools_json) {
-            self.recorded_tools = Some(snapshot.clone());
-            self.recorded_tools_json = Some(json);
-        }
         let delta = if extends {
             TranscriptDelta::Append {
                 previous_len,
@@ -767,6 +763,16 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
         Ok(Some(TranscriptCommitReceipt { path, delta }))
     }
 
+    /// Records the declarations a successfully completed ordinary turn sent.
+    /// This is deliberately outside `persist`: sessions without a transcript
+    /// target still need retention to work between their in-memory turns.
+    fn remember_sent_tools(&mut self, tools: Option<&ToolSnapshot>) {
+        if let Some(tools) = tools {
+            self.recorded_tools = Some(tools.clone());
+            self.recorded_tools_json = Some(tools.to_json());
+        }
+    }
+
     fn with_prefix(&self, history: Vec<Message>) -> Vec<Message> {
         let prefix = self.prefix.messages();
         let overlap = (0..=prefix.len().min(history.len()))
diff --git a/crates/tinyagents-runtime/src/test.rs b/crates/tinyagents-runtime/src/test.rs
index 651c23162..00abbe0e4 100644
--- a/crates/tinyagents-runtime/src/test.rs
+++ b/crates/tinyagents-runtime/src/test.rs
@@ -2989,9 +2989,54 @@ async fn a_resumed_session_keeps_tools_the_new_process_did_not_rebuild() {
     let sent = &driver.requests.lock().unwrap()[0].tools;
     assert_eq!(tool_names(sent), vec!["alpha", "beta"]);
     assert_eq!(tool_names(&recorded.unwrap()), vec!["alpha", "beta"]);
-    // Unchanged declarations are not recorded twice.
+    // Every ordinary turn records its sent snapshot so concurrent session
+    // handles cannot leave an earlier turn's declarations in force.
     let path = recorded_tools_path(directory.path());
-    assert_eq!(tools_records(&path), 1);
+    assert_eq!(tools_records(&path), 2);
+}
+
+#[tokio::test]
+async fn in_memory_sessions_retain_tools_sent_on_earlier_turns() {
+    let driver = Arc::new(Driver::new(vec![
+        Ok(outcome(vec![Message::assistant("first")])),
+        Ok(outcome(vec![
+            Message::assistant("first"),
+            Message::assistant("second"),
+        ])),
+    ]));
+    let (hook, _) = hook(vec![
+        TurnPreparation::with_tools(two_tools()),
+        TurnPreparation::with_tools(tools("alpha")),
+    ]);
+    let mut session = SessionBuilder::new(driver.clone())
+        .hooks(hook)
+        .retain_recorded_tools(true)
+        .build()
+        .unwrap();
+
+    session
+        .turn(
+            SessionTurnRequest::new(Message::user("one")),
+            TurnOptions::default(),
+        )
+        .await
+        .unwrap();
+    session
+        .turn(
+            SessionTurnRequest::new(Message::user("two")),
+            TurnOptions::default(),
+        )
+        .await
+        .unwrap();
+
+    assert_eq!(
+        tool_names(&driver.requests.lock().unwrap()[1].tools),
+        vec!["alpha", "beta"]
+    );
+    assert_eq!(
+        tool_names(session.recorded_tools().unwrap()),
+        vec!["alpha", "beta"]
+    );
 }
 
 #[tokio::test]
diff --git a/crates/tinyagents-session/src/transcript/history.rs b/crates/tinyagents-session/src/transcript/history.rs
index 0a601f906..8d3379057 100644
--- a/crates/tinyagents-session/src/transcript/history.rs
+++ b/crates/tinyagents-session/src/transcript/history.rs
@@ -62,9 +62,8 @@ pub struct TranscriptTurn<'a> {
     pub turn_usage: Option<&'a TurnUsage>,
     /// Caller-provided request id, stamped on every line of the turn.
     pub request_id: Option<&'a str>,
-    /// Tool declarations this turn was sent with, when they differ from the
-    /// ones last recorded for this transcript. `None` records nothing and
-    /// leaves the previous record in force.
+    /// Tool declarations this ordinary turn was sent with. `None` records
+    /// nothing and leaves the previous record in force (for exact-tool turns).
     pub tools: Option<&'a serde_json::Value>,
 }
 

From fc3ba20e54e70ae76d94a7a19cbcc938c182f922 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 04:13:16 +0300
Subject: [PATCH 19/24] fix: normalize legacy resume prefixes

Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-runtime/src/session.rs | 23 +++++++------
 crates/tinyagents-runtime/src/test.rs    | 44 ++++++++++++++++++++++++
 2 files changed, 56 insertions(+), 11 deletions(-)

diff --git a/crates/tinyagents-runtime/src/session.rs b/crates/tinyagents-runtime/src/session.rs
index e31037573..99fe38306 100644
--- a/crates/tinyagents-runtime/src/session.rs
+++ b/crates/tinyagents-runtime/src/session.rs
@@ -198,20 +198,21 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             .ok_or(RuntimeError::MissingDependency("TranscriptCodec"))?;
         let mut decoded = codec.decode_history(&transcript)?;
         // The transcript already holds the prefix it was sent with as its
-        // leading system rows. A session built without a prefix of its own
-        // adopts those rows, so resuming never has to re-render the prompt
-        // and the prefix guard below protects the stored one.
+        // leading system rows. They are legacy prefix material rather than
+        // conversational history: a session built without a prefix adopts
+        // them, while a session with a current prefix must discard them
+        // before combining the resumed history. Keeping them in the latter
+        // case would replay stale instructions alongside the current prompt.
+        let leading_len = decoded
+            .iter()
+            .take_while(|message| matches!(message, Message::System(_)))
+            .count();
         if self.prefix.messages().is_empty() {
-            let leading: Vec<Message> = decoded
-                .iter()
-                .take_while(|message| matches!(message, Message::System(_)))
-                .cloned()
-                .collect();
-            if !leading.is_empty() {
-                self.prefix = PrefixSnapshot::new(leading);
-                decoded.drain(..self.prefix.messages().len());
+            if leading_len != 0 {
+                self.prefix = PrefixSnapshot::new(decoded[..leading_len].to_vec());
             }
         }
+        decoded.drain(..leading_len);
         let history = self.with_prefix(decoded);
         self.history = history.clone();
         // Every turn already on disk counts as committed: the prefix those
diff --git a/crates/tinyagents-runtime/src/test.rs b/crates/tinyagents-runtime/src/test.rs
index 00abbe0e4..d2f439e9c 100644
--- a/crates/tinyagents-runtime/src/test.rs
+++ b/crates/tinyagents-runtime/src/test.rs
@@ -1733,6 +1733,50 @@ async fn changed_first_turn_prefix_replaces_a_builder_prefix_after_resume() {
     );
 }
 
+#[tokio::test]
+async fn resume_discards_stale_stored_system_rows_when_builder_has_a_prefix() {
+    let (locator, _) = locator(Some(SessionTranscript {
+        tools: None,
+        meta: meta(),
+        messages: vec![
+            TranscriptMessage::new("system", "stale"),
+            TranscriptMessage::new("user", "resumed"),
+        ],
+    }));
+    let driver = Arc::new(Driver::new(vec![Ok(outcome(vec![
+        Message::system("current"),
+        Message::user("resumed"),
+        Message::assistant("answer"),
+    ]))]));
+    let mut session = SessionBuilder::new(driver.clone())
+        .codec(Arc::new(SystemCodec))
+        .prefix(PrefixSnapshot::new(vec![Message::system("current")]))
+        .transcript(locator, "agent", meta())
+        .build()
+        .unwrap();
+
+    session
+        .turn(
+            SessionTurnRequest::new(Message::user("next")),
+            TurnOptions {
+                session: None,
+                resume: ResumeMode::LatestForAgent,
+                ..TurnOptions::default()
+            },
+        )
+        .await
+        .unwrap();
+
+    assert_eq!(
+        driver.requests.lock().unwrap()[0].history,
+        vec![
+            Message::system("current"),
+            Message::user("resumed"),
+            Message::user("next"),
+        ]
+    );
+}
+
 #[tokio::test]
 async fn hook_selected_target_and_resume_mode_apply_before_driver_handoff() {
     let (locator, _) = locator(Some(SessionTranscript {

From 1b5c53fabf5f870a2b132de6b850bae2967689ed Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 04:14:20 +0300
Subject: [PATCH 20/24] fix: satisfy resume prefix lint

Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-runtime/src/session.rs | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/crates/tinyagents-runtime/src/session.rs b/crates/tinyagents-runtime/src/session.rs
index 99fe38306..41cdeea04 100644
--- a/crates/tinyagents-runtime/src/session.rs
+++ b/crates/tinyagents-runtime/src/session.rs
@@ -207,10 +207,8 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             .iter()
             .take_while(|message| matches!(message, Message::System(_)))
             .count();
-        if self.prefix.messages().is_empty() {
-            if leading_len != 0 {
-                self.prefix = PrefixSnapshot::new(decoded[..leading_len].to_vec());
-            }
+        if self.prefix.messages().is_empty() && leading_len != 0 {
+            self.prefix = PrefixSnapshot::new(decoded[..leading_len].to_vec());
         }
         decoded.drain(..leading_len);
         let history = self.with_prefix(decoded);

From 0c2fb03f063ad8347b66a941381bcfc3e92a38a6 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 07:52:33 +0300
Subject: [PATCH 21/24] refactor(testkit): consolidate in-memory transcript
 state under a single mutex

Replace four separate `Mutex` fields on `InMemoryTranscriptHistory` with a single `Mutex<InMemoryTranscriptState>` struct, so that a turn update is observed as one atomic transition, matching the file backend's behaviour.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 .../src/testkit/in_memory_transcript.rs       | 71 ++++++++++---------
 1 file changed, 37 insertions(+), 34 deletions(-)

diff --git a/crates/tinyagents-session/src/testkit/in_memory_transcript.rs b/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
index 7d7f21849..50411ad05 100644
--- a/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
+++ b/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
@@ -31,11 +31,17 @@ use crate::transcript::{
 ///   after `append_turn` always equals `turn.next` either way.
 pub struct InMemoryTranscriptHistory {
     path: PathBuf,
-    meta: Mutex<TranscriptMeta>,
-    messages: Mutex<Vec<TranscriptMessage>>,
-    tools: Mutex<Option<serde_json::Value>>,
-    /// `None` until the first write, mirroring a file that does not exist yet.
-    written: Mutex<bool>,
+    state: Mutex<InMemoryTranscriptState>,
+}
+
+/// The complete logical transcript state. Keeping it behind one mutex makes a
+/// turn update observable as one transition, just like the file backend.
+struct InMemoryTranscriptState {
+    meta: TranscriptMeta,
+    messages: Vec<TranscriptMessage>,
+    tools: Option<serde_json::Value>,
+    /// `false` until the first write, mirroring a file that does not exist yet.
+    written: bool,
 }
 
 impl InMemoryTranscriptHistory {
@@ -45,15 +51,17 @@ impl InMemoryTranscriptHistory {
     pub fn new(label: impl Into<String>, seed_meta: TranscriptMeta) -> Self {
         Self {
             path: PathBuf::from(format!("memory://{}", label.into())),
-            meta: Mutex::new(seed_meta),
-            messages: Mutex::new(Vec::new()),
-            tools: Mutex::new(None),
-            written: Mutex::new(false),
+            state: Mutex::new(InMemoryTranscriptState {
+                meta: seed_meta,
+                messages: Vec::new(),
+                tools: None,
+                written: false,
+            }),
         }
     }
 
     fn mark_written(&self) {
-        *self.written.lock().unwrap_or_else(|e| e.into_inner()) = true;
+        self.state.lock().unwrap_or_else(|e| e.into_inner()).written = true;
     }
 }
 
@@ -63,63 +71,58 @@ impl TranscriptRead for InMemoryTranscriptHistory {
     }
 
     fn read_session(&self) -> anyhow::Result<Option<SessionTranscript>> {
-        if !*self.written.lock().unwrap_or_else(|e| e.into_inner()) {
+        let state = self.state.lock().unwrap_or_else(|e| e.into_inner());
+        if !state.written {
             return Ok(None);
         }
         Ok(Some(SessionTranscript {
-            meta: self.meta.lock().unwrap_or_else(|e| e.into_inner()).clone(),
-            messages: self
-                .messages
-                .lock()
-                .unwrap_or_else(|e| e.into_inner())
-                .clone(),
-            tools: self.tools.lock().unwrap_or_else(|e| e.into_inner()).clone(),
+            meta: state.meta.clone(),
+            messages: state.messages.clone(),
+            tools: state.tools.clone(),
         }))
     }
 }
 
 impl TranscriptHistory for InMemoryTranscriptHistory {
     fn append_turn(&self, turn: TranscriptTurn<'_>) -> anyhow::Result<()> {
-        *self.messages.lock().unwrap_or_else(|e| e.into_inner()) = turn.next.to_vec();
-        *self.meta.lock().unwrap_or_else(|e| e.into_inner()) = turn.meta.clone();
+        let mut state = self.state.lock().unwrap_or_else(|e| e.into_inner());
+        state.messages = turn.next.to_vec();
+        state.meta = turn.meta.clone();
+        // `None` means this logical turn does not replace the last durable
+        // snapshot, matching the file writer which emits no tools record.
         if let Some(tools) = turn.tools {
-            *self.tools.lock().unwrap_or_else(|e| e.into_inner()) = Some(tools.clone());
+            state.tools = Some(tools.clone());
         }
-        self.mark_written();
+        state.written = true;
         Ok(())
     }
 
     fn messages(&self) -> anyhow::Result<Vec<TranscriptMessage>> {
-        Ok(self
-            .messages
-            .lock()
-            .unwrap_or_else(|e| e.into_inner())
-            .clone())
+        Ok(self.state.lock().unwrap_or_else(|e| e.into_inner()).messages.clone())
     }
 
     fn append(&self, message: TranscriptMessage) -> anyhow::Result<()> {
-        self.messages
+        self.state
             .lock()
             .unwrap_or_else(|e| e.into_inner())
+            .messages
             .push(message);
         self.mark_written();
         Ok(())
     }
 
     fn replace(&self, messages: &[TranscriptMessage]) -> anyhow::Result<()> {
-        *self.messages.lock().unwrap_or_else(|e| e.into_inner()) = messages.to_vec();
+        self.state.lock().unwrap_or_else(|e| e.into_inner()).messages = messages.to_vec();
         self.mark_written();
         Ok(())
     }
 
     fn clear(&self) -> anyhow::Result<()> {
-        if !*self.written.lock().unwrap_or_else(|e| e.into_inner()) {
+        let mut state = self.state.lock().unwrap_or_else(|e| e.into_inner());
+        if !state.written {
             return Ok(());
         }
-        self.messages
-            .lock()
-            .unwrap_or_else(|e| e.into_inner())
-            .clear();
+        state.messages.clear();
         Ok(())
     }
 }

From 721c349dec7eef16a43c644593ce1adad0283526 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 07:52:48 +0300
Subject: [PATCH 22/24] fix(session): clear recorded tools when no snapshot is
 provided

When a turn does not include a tool snapshot, the session now explicitly clears the previously recorded tools instead of leaving stale data. This prevents a one-off exact-tools snapshot from leaking into a later retained turn, ensuring that only the tools relevant to the current turn are used for retention.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-runtime/src/session.rs | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/crates/tinyagents-runtime/src/session.rs b/crates/tinyagents-runtime/src/session.rs
index 41cdeea04..bf2dcd53c 100644
--- a/crates/tinyagents-runtime/src/session.rs
+++ b/crates/tinyagents-runtime/src/session.rs
@@ -766,9 +766,17 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
     /// This is deliberately outside `persist`: sessions without a transcript
     /// target still need retention to work between their in-memory turns.
     fn remember_sent_tools(&mut self, tools: Option<&ToolSnapshot>) {
-        if let Some(tools) = tools {
-            self.recorded_tools = Some(tools.clone());
-            self.recorded_tools_json = Some(tools.to_json());
+        match tools {
+            Some(tools) => {
+                self.recorded_tools = Some(tools.clone());
+                self.recorded_tools_json = Some(tools.to_json());
+            }
+            // An exact-tools turn is deliberately one-off. Do not let a
+            // snapshot sent before it leak back into a later retained turn.
+            None => {
+                self.recorded_tools = None;
+                self.recorded_tools_json = None;
+            }
         }
     }
 

From 1aff2c053908af3a72b0c16c1bdb7c7540373ad7 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 07:53:15 +0300
Subject: [PATCH 23/24] chore(session): reformat method bodies for readability

Reformatted the `messages` and `replace` methods in `InMemoryTranscriptHistory` to break long chained calls across multiple lines, improving code readability without changing any behaviour.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 .../src/testkit/in_memory_transcript.rs              | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/crates/tinyagents-session/src/testkit/in_memory_transcript.rs b/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
index 50411ad05..da2cb8b4b 100644
--- a/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
+++ b/crates/tinyagents-session/src/testkit/in_memory_transcript.rs
@@ -98,7 +98,12 @@ impl TranscriptHistory for InMemoryTranscriptHistory {
     }
 
     fn messages(&self) -> anyhow::Result<Vec<TranscriptMessage>> {
-        Ok(self.state.lock().unwrap_or_else(|e| e.into_inner()).messages.clone())
+        Ok(self
+            .state
+            .lock()
+            .unwrap_or_else(|e| e.into_inner())
+            .messages
+            .clone())
     }
 
     fn append(&self, message: TranscriptMessage) -> anyhow::Result<()> {
@@ -112,7 +117,10 @@ impl TranscriptHistory for InMemoryTranscriptHistory {
     }
 
     fn replace(&self, messages: &[TranscriptMessage]) -> anyhow::Result<()> {
-        self.state.lock().unwrap_or_else(|e| e.into_inner()).messages = messages.to_vec();
+        self.state
+            .lock()
+            .unwrap_or_else(|e| e.into_inner())
+            .messages = messages.to_vec();
         self.mark_written();
         Ok(())
     }

From c695e09d13efd21a1c26d7226af5b4d56634d2b8 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <enamakel@tinyhumans.ai>
Date: Thu, 24 Sep 2026 07:54:08 +0300
Subject: [PATCH 24/24] refactor(tools): embed exact-tools flag into
 ToolSnapshot

Moves the `exact_tools` boolean from `TurnPreparation` into `ToolSnapshot` itself, so the snapshot carries its own semantics about whether it should be treated as a one-off declaration set. This simplifies the preparation struct and makes the exactness property an intrinsic part of the tool snapshot rather than a separate concern.

Auto-committed-on: dragonfly
Co-authored-by: Medulla <medulla@tinyhumans.ai>
---
 crates/tinyagents-runtime/src/builder.rs |  3 ++-
 crates/tinyagents-runtime/src/session.rs |  3 +--
 crates/tinyagents-runtime/src/test.rs    |  6 ++----
 crates/tinyagents-runtime/src/tools.rs   | 13 +++++++++++++
 crates/tinyagents-runtime/src/types.rs   |  9 ---------
 5 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/crates/tinyagents-runtime/src/builder.rs b/crates/tinyagents-runtime/src/builder.rs
index 6ef04e4fa..420886031 100644
--- a/crates/tinyagents-runtime/src/builder.rs
+++ b/crates/tinyagents-runtime/src/builder.rs
@@ -75,7 +75,8 @@ impl<C: Clone + Send + Sync + 'static> SessionBuilder<C> {
     /// would both break the prompt's own references to it and change the
     /// cached request prefix. The host must then be able to execute (or
     /// refuse) a retained declaration; it can read them from
-    /// `SessionStateView::recorded_tools` in `before_turn`.
+    /// [`Session::recorded_tools`](crate::Session::recorded_tools) after
+    /// resuming a session.
     ///
     /// Off by default because a driver that requires the snapshot to equal
     /// its own registry (`HarnessDriver`) cannot execute a retained entry.
diff --git a/crates/tinyagents-runtime/src/session.rs b/crates/tinyagents-runtime/src/session.rs
index bf2dcd53c..b40d4124d 100644
--- a/crates/tinyagents-runtime/src/session.rs
+++ b/crates/tinyagents-runtime/src/session.rs
@@ -395,11 +395,11 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
                 .before_turn(request, options, self.state_view(resumed)),
         )
         .await?;
-        let exact_tools = preparation.exact_tools;
         let (tools, prepared_prefix) = self.apply_preparation(preparation)?;
         if let Some(prefix) = prepared_prefix {
             self.apply_prefix(prefix)?;
         }
+        let exact_tools = tools.is_exact();
         let tools = if exact_tools {
             tools
         } else {
@@ -601,7 +601,6 @@ impl<C: Clone + Send + Sync + 'static> Session<C> {
             transcript_target: self.target.as_ref(),
             committed_turns: self.committed_turns,
             resumed,
-            recorded_tools: self.recorded_tools.as_ref(),
         }
     }
 
diff --git a/crates/tinyagents-runtime/src/test.rs b/crates/tinyagents-runtime/src/test.rs
index d2f439e9c..bdd6a7bd5 100644
--- a/crates/tinyagents-runtime/src/test.rs
+++ b/crates/tinyagents-runtime/src/test.rs
@@ -3170,8 +3170,7 @@ async fn an_exact_tool_turn_neither_merges_nor_records() {
     history.extend([Message::user("x"), Message::assistant("x")]);
     let driver = Arc::new(Driver::new(vec![Ok(outcome(history))]));
     let (hook, _) = hook(vec![TurnPreparation {
-        tools: Some(ToolSnapshot::default()),
-        exact_tools: true,
+        tools: Some(ToolSnapshot::default().exact()),
         ..TurnPreparation::default()
     }]);
     let mut session = SessionBuilder::new(driver.clone())
@@ -3211,8 +3210,7 @@ async fn an_exact_tool_turn_carries_recorded_tools_into_a_compaction_generation(
         "compacted",
     )]))]));
     let (hook, _) = hook(vec![TurnPreparation {
-        tools: Some(ToolSnapshot::default()),
-        exact_tools: true,
+        tools: Some(ToolSnapshot::default().exact()),
         ..TurnPreparation::default()
     }]);
     let mut session = SessionBuilder::new(driver)
diff --git a/crates/tinyagents-runtime/src/tools.rs b/crates/tinyagents-runtime/src/tools.rs
index 8a2cf71c4..ef60be62c 100644
--- a/crates/tinyagents-runtime/src/tools.rs
+++ b/crates/tinyagents-runtime/src/tools.rs
@@ -11,6 +11,7 @@ use crate::RuntimeError;
 #[derive(Clone, Debug, Default)]
 pub struct ToolSnapshot {
     specs: Vec<ToolSpec>,
+    exact: bool,
 }
 
 impl ToolSnapshot {
@@ -33,9 +34,21 @@ impl ToolSnapshot {
         }
         Ok(Self {
             specs: names.into_values().collect(),
+            exact: false,
         })
     }
 
+    /// Marks this snapshot as a one-off declaration set. It is sent exactly
+    /// as supplied and is not retained for a later turn.
+    pub fn exact(mut self) -> Self {
+        self.exact = true;
+        self
+    }
+
+    pub(crate) fn is_exact(&self) -> bool {
+        self.exact
+    }
+
     /// Returns the frozen declarations in stable name order.
     pub fn specs(&self) -> &[ToolSpec] {
         &self.specs
diff --git a/crates/tinyagents-runtime/src/types.rs b/crates/tinyagents-runtime/src/types.rs
index abefd5a0b..b9adb7d67 100644
--- a/crates/tinyagents-runtime/src/types.rs
+++ b/crates/tinyagents-runtime/src/types.rs
@@ -189,11 +189,6 @@ pub struct TurnPreparation {
     /// the builder's compatibility default and is never retained from a prior
     /// preparation.
     pub tools: Option<ToolSnapshot>,
-    /// Send `tools` exactly as given: recorded declarations are not merged
-    /// back in, and this turn's set is not recorded as the session's tools.
-    /// For a deliberately tool-less or otherwise one-off turn, so it cannot
-    /// erase the conversation's durable tool list.
-    pub exact_tools: bool,
 }
 
 impl TurnPreparation {
@@ -216,10 +211,6 @@ pub struct SessionStateView<'a> {
     /// `true` only when this call loaded and decoded a durable transcript
     /// before `before_turn` ran.
     pub resumed: bool,
-    /// Tool declarations this session last sent, restored from its transcript
-    /// on resume. A host rebuilding executors after a restart can start from
-    /// these instead of re-deriving the set from live state.
-    pub recorded_tools: Option<&'a ToolSnapshot>,
 }
 
 /// The shape of a successful logical transcript transition.