diff --git a/src/agents/pi-embedded.ts b/src/agents/pi-embedded.ts
index cbfeb2f0b..39878aee0 100644
--- a/src/agents/pi-embedded.ts
+++ b/src/agents/pi-embedded.ts
@@ -140,6 +140,8 @@ async function sanitizeSessionMessagesImages(
   messages: AppMessage[],
   label: string,
 ): Promise<AppMessage[]> {
+  // We sanitize historical session messages because Anthropic can reject a request
+  // if the transcript contains oversized base64 images (see MAX_IMAGE_DIMENSION_PX).
   const out: AppMessage[] = [];
   for (const msg of messages) {
     if (!msg || typeof msg !== "object") {
diff --git a/src/agents/pi-tools.ts b/src/agents/pi-tools.ts
index e62d624e2..f1eb24485 100644
--- a/src/agents/pi-tools.ts
+++ b/src/agents/pi-tools.ts
@@ -11,6 +11,12 @@ type ToolContentBlock = AgentToolResult<unknown>["content"][number];
 type ImageContentBlock = Extract<ToolContentBlock, { type: "image" }>;
 type TextContentBlock = Extract<ToolContentBlock, { type: "text" }>;
 
+// Anthropic Messages API limitation (observed in Clawdis sessions):
+// When sending many images in a single request (e.g. via session history + tool results),
+// Anthropic rejects any image where *either* dimension exceeds 2000px.
+//
+// To keep sessions resilient (and avoid "silent" WhatsApp non-replies), we auto-downscale
+// all base64 image blocks above this limit while preserving aspect ratio.
 const MAX_IMAGE_DIMENSION_PX = 2000;
 
 function sniffMimeFromBase64(base64: string): string | undefined {