Agent: repair malformed tool calls and session files

docs/reference/transcript-hygiene.md

@@ -11,11 +11,15 @@ title: "Transcript Hygiene"
 
 This document describes **provider-specific fixes** applied to transcripts before a run
 (building model context). These are **in-memory** adjustments used to satisfy strict
-provider requirements. They do **not** rewrite the stored JSONL transcript on disk.
+provider requirements. These hygiene steps do **not** rewrite the stored JSONL transcript
+on disk; however, a separate session-file repair pass may rewrite malformed JSONL files
+by dropping invalid lines before the session is loaded. When a repair occurs, the original
+file is backed up alongside the session file.
 
 Scope includes:
 
 - Tool call id sanitization
+- Tool call input validation (drop malformed tool_use/tool_call blocks missing input or arguments)
 - Tool result pairing repair
 - Turn validation / ordering
 - Thought signature cleanup
@@ -36,6 +40,11 @@ All transcript hygiene is centralized in the embedded runner:
 
 The policy uses `provider`, `modelApi`, and `modelId` to decide what to apply.
 
+Separate from transcript hygiene, session files are repaired (if needed) before load:
+
+- `repairSessionFileIfNeeded` in `src/agents/session-file-repair.ts`
+- Called from `run/attempt.ts` and `compact.ts` (embedded runner)
+
 ---
 
 ## Global rule: image sanitization
@@ -50,6 +59,19 @@ Implementation:
 
 ---
 
+## Global rule: malformed tool calls
+
+Assistant tool-call blocks that are missing both `input` and `arguments` are dropped
+before model context is built. This prevents provider rejections from partially
+persisted tool calls (for example, after a rate limit failure).
+
+Implementation:
+
+- `sanitizeToolCallInputs` in `src/agents/session-transcript-repair.ts`
+- Applied in `sanitizeSessionHistory` in `src/agents/pi-embedded-runner/google.ts`
+
+---
+
 ## Provider matrix (current behavior)
 
 **OpenAI / OpenAI Codex**