fix(transforms): use grammatical replacement and env-extensible blocklist

- Replace 'github.com/anomalyco/opencode' with 'opencode.ai' instead of
  empty string so surrounding prose stays grammatical (no double spaces
  or dangling phrases).
- Add OPENCODE_CLAUDE_AUTH_BLOCKED_STRINGS env var (comma-separated,
  optional 'pattern=replacement' form) so users can self-mitigate
  future server-side additions without a release cycle.
- Restate scrub-in-place comment for clarity.
- Add tests for grammatical replacement, realistic concatenated prompt,
  and env-var parser. Fix lint formatting flagged by oxfmt --check.

Addresses review feedback from @bvironn on #198.

Author: griffinmartin

src/transforms.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict"
 import { describe, it } from "node:test"
 import {
+  parseBlockedReplacementsEnv,
   repairToolPairs,
   stripToolPrefix,
   transformBody,
@@ -35,9 +36,14 @@ describe("transforms", () => {
     assert.equal(parsed.messages[0].content[0].name, "mcp_Lookup")
   })
 
-  it("transformBody scrubs blocked URL from system text in-place", () => {
+  it("transformBody scrubs blocked URL from system text in-place with grammatical replacement", () => {
     const input = JSON.stringify({
-      system: [{ type: "text", text: "Report at https://github.com/anomalyco/opencode for bugs" }],
+      system: [
+        {
+          type: "text",
+          text: "Report at https://github.com/anomalyco/opencode for bugs",
+        },
+      ],
       tools: [{ name: "search" }],
       messages: [
         { role: "user", content: [{ type: "tool_use", name: "lookup" }] },
@@ -54,14 +60,87 @@ describe("transforms", () => {
       }>
     }
 
-    // blocked URL scrubbed, entry stays in system[]
+    // blocked URL scrubbed, entry stays in system[], surrounding prose intact.
     assert.equal(parsed.system.length, 2) // billing + scrubbed entry
     assert.ok(!parsed.system[1].text.includes("anomalyco"))
-    assert.ok(parsed.system[1].text.includes("Report at"))
+    assert.ok(!parsed.system[1].text.includes("github.com/anomalyco"))
+    // Replacement preserves grammar — no double spaces, no dangling phrases.
+    assert.equal(
+      parsed.system[1].text,
+      "Report at https://opencode.ai for bugs",
+    )
     assert.equal(parsed.tools[0].name, "mcp_Search")
     assert.equal(parsed.messages[0].content[0].name, "mcp_Lookup")
   })
 
+  it("transformBody scrubs blocked URL embedded in a realistic concatenated system prompt", () => {
+    // Mirrors how OpenCode actually emits system[]: identity prefix, then
+    // a single concatenated block containing agent prompt + env + AGENTS
+    // + skills, with the blocked URL appearing once inside the body.
+    const identity = "You are Claude Code, Anthropic's official CLI for Claude."
+    const concatenated = [
+      "You are OpenCode, the best coding agent on the planet.",
+      "Report bugs at https://github.com/anomalyco/opencode.",
+      "Working directory: /Users/test/dev/project",
+      "## AGENTS.md",
+      "Use TDD when writing new features.",
+    ].join("\n\n")
+
+    const input = JSON.stringify({
+      system: [
+        { type: "text", text: identity },
+        { type: "text", text: concatenated },
+      ],
+      messages: [{ role: "user", content: "hello" }],
+    })
+
+    const output = transformBody(input)
+    const parsed = JSON.parse(output as string) as {
+      system: Array<{ text: string }>
+      messages: Array<{ content: string | Array<{ text?: string }> }>
+    }
+
+    // billing + identity + concatenated body — body stays in system[].
+    assert.equal(parsed.system.length, 3)
+    assert.ok(parsed.system[0].text.startsWith("x-anthropic-billing-header:"))
+    assert.equal(parsed.system[1].text, identity)
+    // Body retained, blocked URL scrubbed, all other content intact.
+    assert.ok(!parsed.system[2].text.includes("github.com/anomalyco"))
+    assert.ok(parsed.system[2].text.includes("opencode.ai"))
+    assert.ok(parsed.system[2].text.includes("Working directory"))
+    assert.ok(parsed.system[2].text.includes("AGENTS.md"))
+    assert.ok(parsed.system[2].text.includes("Use TDD"))
+    // User message untouched (no relocation).
+    assert.equal(parsed.messages[0].content, "hello")
+  })
+
+  it("parseBlockedReplacementsEnv parses comma-separated patterns with optional replacements", () => {
+    assert.deepEqual(parseBlockedReplacementsEnv(undefined), [])
+    assert.deepEqual(parseBlockedReplacementsEnv(""), [])
+    assert.deepEqual(parseBlockedReplacementsEnv("   "), [])
+
+    // Bare patterns scrub to empty string.
+    assert.deepEqual(parseBlockedReplacementsEnv("foo.example,bar.example"), [
+      { pattern: "foo.example", replacement: "" },
+      { pattern: "bar.example", replacement: "" },
+    ])
+
+    // pattern=replacement form.
+    assert.deepEqual(
+      parseBlockedReplacementsEnv("foo.example=foo.ok,bar.example"),
+      [
+        { pattern: "foo.example", replacement: "foo.ok" },
+        { pattern: "bar.example", replacement: "" },
+      ],
+    )
+
+    // Whitespace around tokens is trimmed; empty patterns dropped.
+    assert.deepEqual(parseBlockedReplacementsEnv(" a = b , , c=d , =orphan "), [
+      { pattern: "a", replacement: "b" },
+      { pattern: "c", replacement: "d" },
+    ])
+  })
+
   it("transformBody keeps safe non-core system text in system[]", () => {
     const input = JSON.stringify({
       system: [
@@ -82,7 +161,10 @@ describe("transforms", () => {
 
     // Safe text stays in system[]
     assert.equal(parsed.system.length, 2) // billing + safe text
-    assert.equal(parsed.system[1].text, "Use opencode-claude-auth plugin instructions as-is.")
+    assert.equal(
+      parsed.system[1].text,
+      "Use opencode-claude-auth plugin instructions as-is.",
+    )
   })
 
   it("transformBody keeps safe URL/path system text in system[]", () => {
@@ -105,7 +187,10 @@ describe("transforms", () => {
 
     // Safe URLs stay in system[]
     assert.equal(parsed.system.length, 2)
-    assert.equal(parsed.system[1].text, "OpenCode docs: https://example.com/opencode/docs and path /var/opencode/bin")
+    assert.equal(
+      parsed.system[1].text,
+      "OpenCode docs: https://example.com/opencode/docs and path /var/opencode/bin",
+    )
   })
 
   it("transformBody injects billing header as system[0] with computed cch", () => {

src/transforms.ts

@@ -22,6 +22,53 @@ function unprefixName(name: string): string {
 const SYSTEM_IDENTITY =
   "You are Claude Code, Anthropic's official CLI for Claude."
 
+/**
+ * Substring → replacement entries used to scrub system[] text in place.
+ * Built-in patterns target known Anthropic billing-validator triggers.
+ * Users can extend this list at runtime via the env var
+ * `OPENCODE_CLAUDE_AUTH_BLOCKED_STRINGS`. Format is comma-separated:
+ *
+ *   foo.example,bar.example=baz
+ *
+ * Each entry is either `pattern` (replaced with empty string) or
+ * `pattern=replacement`. Whitespace around tokens is trimmed.
+ */
+type BlockedReplacement = { pattern: string; replacement: string }
+
+const BUILT_IN_BLOCKED_REPLACEMENTS: BlockedReplacement[] = [
+  // The OpenCode GitHub repo URL trips Anthropic's OAuth billing
+  // validator (verified by 15-row probe). `opencode.ai` is the
+  // project's docs URL and passes the validator, keeping any
+  // surrounding prose grammatical.
+  { pattern: "github.com/anomalyco/opencode", replacement: "opencode.ai" },
+]
+
+export function parseBlockedReplacementsEnv(
+  raw: string | undefined,
+): BlockedReplacement[] {
+  if (!raw) return []
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map((entry) => {
+      const eq = entry.indexOf("=")
+      if (eq === -1) return { pattern: entry, replacement: "" }
+      return {
+        pattern: entry.slice(0, eq).trim(),
+        replacement: entry.slice(eq + 1).trim(),
+      }
+    })
+    .filter((e) => e.pattern.length > 0)
+}
+
+const BLOCKED_REPLACEMENTS: BlockedReplacement[] = [
+  ...BUILT_IN_BLOCKED_REPLACEMENTS,
+  ...parseBlockedReplacementsEnv(
+    process.env.OPENCODE_CLAUDE_AUTH_BLOCKED_STRINGS,
+  ),
+]
+
 type SystemEntry = { type?: string; text?: string } & Record<string, unknown>
 type ContentBlock = { type?: string; text?: string } & Record<string, unknown>
 type Message = {
@@ -169,33 +216,22 @@ export function transformBody(
     }
     parsed.system = splitSystem
 
-    // --- Relocate blocked system entries to user messages ---
+    // --- Scrub blocked substrings from system[] entries ---
     // Anthropic's billing validator rejects specific URLs in system[]
-    // (e.g. the OpenCode GitHub repo URL). Instead of moving ALL
-    // non-core system content (which regresses instruction priority
-    // and prompt-cache efficiency), only relocate entries that contain
-    // a blocked string. Everything else stays in system[].
-    const BLOCKED_SYSTEM_STRINGS = [
-      "github.com/anomalyco/opencode",
-    ]
-
-    function isBlocked(text: string): boolean {
-      return BLOCKED_SYSTEM_STRINGS.some((s) => text.includes(s))
-    }
-
-    // Scrub blocked strings from system entries in-place rather than
-    // relocating entire entries. OpenCode concatenates the full system
-    // prompt (identity + agent prompt + env + AGENTS + skills) into a
-    // single text block, so moving the whole entry on a substring match
-    // would frontload the entire prompt into the user message.
+    // (e.g. the OpenCode GitHub repo URL). Scrub the offending substring
+    // in place rather than relocating whole entries — relocation regresses
+    // instruction priority and prompt-cache efficiency since OpenCode
+    // concatenates the full system prompt (identity + agent prompt + env
+    // + AGENTS + skills) into a single text block.
+    //
+    // Replacements are chosen to keep the surrounding prose grammatical
+    // (e.g. `opencode.ai` is a functionally equivalent project URL that
+    // passes the validator, verified empirically via probe).
     for (const entry of parsed.system) {
-      if (
-        entry.type === "text" &&
-        typeof entry.text === "string" &&
-        isBlocked(entry.text)
-      ) {
-        for (const blocked of BLOCKED_SYSTEM_STRINGS) {
-          entry.text = entry.text.split(blocked).join("")
+      if (entry.type !== "text" || typeof entry.text !== "string") continue
+      for (const { pattern, replacement } of BLOCKED_REPLACEMENTS) {
+        if (entry.text.includes(pattern)) {
+          entry.text = entry.text.split(pattern).join(replacement)
         }
       }
     }