fix(read): treat utf-8 pdf names as text and quote pdftotext

A .pdf suffix without %PDF magic is only malformed when the first chunk
is binary. extractor_ready quotes the path so it pastes into bash.

Author: TheGreatAxios

src/agent/tool-aliases.ts

@@ -141,7 +141,7 @@ export function withAuthzParityDefinitions<
 
 const SHELL_WRAPPERS = new Set(["bash", "sh", "zsh"]);
 
-function shellQuote(arg: string): string {
+export function shellQuote(arg: string): string {
   if (/^[A-Za-z0-9_\-./:=@%]+$/.test(arg)) return arg;
   return `'${arg.replace(/'/g, `'\\''`)}'`;
 }

src/plugins/file-inspection-diagnosis.test.ts

@@ -22,6 +22,9 @@ describe("PDF sniffing", () => {
     expect(
       inspectionKindFromFirstChunk("report.pdf", Buffer.from("not-a-pdf\0")),
     ).toBe("pdf-malformed");
+  });
+
+  test("plain UTF-8 named .pdf without magic is not an inspection block", () => {
     expect(
       inspectionKindFromFirstChunk("report.pdf", Buffer.from("plain text")),
     ).toBeUndefined();
@@ -94,6 +97,18 @@ describe("diagnoseBlockedFileInspection", () => {
     expect(result.message).toContain(`${PDF_EXTRACTOR_BIN} ${PATH} -`);
   });
 
+  test("extractor_ready quotes a path that would break a pasted bash command", () => {
+    const spaced = "/tmp/my report.pdf";
+    const result = diagnoseBlockedFileInspection({
+      path: spaced,
+      kind: "pdf",
+      extractorAvailable: true,
+      canExecuteHostCommands: true,
+    });
+    expect(result.code).toBe("extractor_ready");
+    expect(result.message).toContain(`${PDF_EXTRACTOR_BIN} '${spaced}' -`);
+  });
+
   test("malformed PDF is not blamed on tooling or permission", () => {
     const result = diagnoseBlockedFileInspection({
       path: PATH,

src/plugins/file-inspection-diagnosis.ts

@@ -1,4 +1,5 @@
 import { extname } from "node:path";
+import { shellQuote } from "../agent/tool-aliases.js";
 
 /** Host binary that extracts text from a PDF (poppler). */
 export const PDF_EXTRACTOR_BIN = "pdftotext";
@@ -122,6 +123,6 @@ export function diagnoseBlockedFileInspection(
 
   return {
     code: "extractor_ready",
-    message: `read_file cannot decode PDFs. ${extractor} is installed — run \`${extractor} ${path} -\` via bash.`,
+    message: `read_file cannot decode PDFs. ${extractor} is installed — run \`${extractor} ${shellQuote(path)} -\` via bash.`,
   };
 }

src/plugins/read-file-guard-plugin.test.ts

@@ -179,6 +179,22 @@ describe("readFileBounded", () => {
     expect(content).not.toContain("brew install");
   });
 
+  test("UTF-8 .pdf without magic still reads as text", async () => {
+    const p = await fixture("utf8.pdf", "plain utf-8 notes\nsecond line");
+    const { content, isError } = await readFileBounded(
+      p,
+      0,
+      2000,
+      neverAbort(),
+      { whichExtractor: () => null, canExecuteHostCommands: () => false },
+    );
+    expect(isError).toBeUndefined();
+    expect(content).toContain("plain utf-8 notes");
+    expect(content).toContain("second line");
+    expect(content).not.toContain("not a valid PDF");
+    expect(content).not.toContain("malformed");
+  });
+
   test("a NUL deep in an otherwise-valid file does not discard streamed content", async () => {
     // Enough valid text (>64KB) to guarantee the NUL lands in a later chunk.
     const head = Array.from(
@@ -825,6 +841,38 @@ describe("readFileGuardPlugin", () => {
     expect(String(blockedResult.content)).toContain("run_shell");
     expect(String(blockedResult.content)).not.toContain("brew install");
   });
+
+  test("UTF-8 .pdf without magic still reads as text through the plugin", async () => {
+    await fixture("notes.pdf", "hello from a misnamed text file");
+    const result = await run({
+      id: "utf8-pdf",
+      name: "read_file",
+      arguments: { path: "notes.pdf" },
+    });
+    expect(result.isError).toBeFalsy();
+    expect(result.content).toContain("hello from a misnamed text file");
+    expect(String(result.content)).not.toContain("not a valid PDF");
+    expect(String(result.content)).not.toContain("malformed");
+  });
+
+  test("extractor_ready quotes a PDF path that contains spaces", async () => {
+    await fixture("my report.pdf", Buffer.from("%PDF-1.4\n"));
+    const plugin = readFileGuardPlugin(dir, {
+      whichExtractor: () => "/usr/bin/pdftotext",
+      canExecuteHostCommands: () => true,
+    });
+    const result = await defined(plugin.middleware)(fallback)(
+      {
+        id: "quoted-pdf",
+        name: "read_file",
+        arguments: { path: "my report.pdf" },
+      },
+      neverAbort(),
+    );
+    expect(result.isError).toBe(true);
+    const abs = join(dir, "my report.pdf");
+    expect(String(result.content)).toContain(`pdftotext '${abs}' -`);
+  });
 });
 
 describe("CL-8980 single-way path+offset resume", () => {

src/plugins/read-file-guard-plugin.ts

@@ -540,7 +540,7 @@ export function readFileGuardPlugin(
           return {
             callId: call.id,
             content: diagnoseBlockedFileInspection({
-              path: rawPath,
+              path: absolutePath,
               kind: "unreadable",
               extractorAvailable: false,
               canExecuteHostCommands: false,