diff --git a/src/agents/pi-embedded.ts b/src/agents/pi-embedded.ts
index 29195bdb3..7f3b51314 100644
--- a/src/agents/pi-embedded.ts
+++ b/src/agents/pi-embedded.ts
@@ -200,6 +200,8 @@ export async function runEmbeddedPiAgent(params: {
           systemPrompt,
           model,
           thinkingLevel,
+          // TODO(steipete): Once pi-mono publishes file-magic MIME detection in `read` image payloads,
+          // remove `createClawdisCodingTools()` and use upstream `codingTools` again.
           tools: createClawdisCodingTools(),
         },
         messageTransformer,
diff --git a/src/agents/pi-tools.ts b/src/agents/pi-tools.ts
index ecc0ae054..f88165386 100644
--- a/src/agents/pi-tools.ts
+++ b/src/agents/pi-tools.ts
@@ -3,6 +3,8 @@ import { codingTools, readTool } from "@mariozechner/pi-coding-agent";
 
 import { detectMime } from "../media/mime.js";
 
+// TODO(steipete): Remove this wrapper once pi-mono ships file-magic MIME detection
+// for `read` image payloads in `@mariozechner/pi-coding-agent` (then switch back to `codingTools` directly).
 type ImageContentBlock = {
   type: "image";
   data: string;