mason: route agent boolean tool args through coerceBoolean

Sweep strict === true reads on files, callgraph, dryRun, pty, background,
and replaceAll in OpenCode and Pi plugins so stringified "true" and 1/1
are honored at the runtime boundary. Add dryRun and replaceAll string
regression tests.

Co-authored-by: Alfonso <289616620+alfonso-aft@users.noreply.github.com>

Author: ualtinok

packages/opencode-plugin/src/__tests__/ast.test.ts

@@ -0,0 +1,62 @@
+/**
+ * Unit tests for AST tool argument shaping.
+ */
+
+/// <reference path="../bun-test.d.ts" />
+
+import { describe, expect, test } from "bun:test";
+import type { BridgePool } from "@cortexkit/aft-bridge";
+import type { ToolContext } from "@opencode-ai/plugin";
+import { astTools } from "../tools/ast.js";
+import type { PluginContext } from "../types.js";
+
+function createSdkContext(directory: string): ToolContext {
+  return {
+    sessionID: "test-session",
+    messageID: "test-message",
+    agent: "build",
+    abort: new AbortController().signal,
+    directory,
+    worktree: directory,
+    metadata: () => {},
+  } as ToolContext;
+}
+
+describe("AST tool adapters", () => {
+  test('ast_grep_replace treats string dryRun "true" as preview (dry_run true)', async () => {
+    const calls: Array<{ command: string; params: Record<string, unknown> }> = [];
+    const bridge = {
+      send: async (command: string, params: Record<string, unknown> = {}) => {
+        calls.push({ command, params });
+        return { success: true, dry_run: true, text: "preview" };
+      },
+    };
+    const pool = { getBridge: () => bridge } as unknown as BridgePool;
+    const ctx: PluginContext = {
+      pool,
+      client: {
+        lsp: { status: async () => ({ data: [] }) },
+        find: { symbols: async () => ({ data: [] }) },
+      },
+      config: {} as PluginContext["config"],
+      storageDir: "/tmp/aft-test",
+    };
+    const tools = astTools(ctx);
+    const dir = "/tmp/aft-ast-test";
+    const sdkCtx = createSdkContext(dir);
+
+    await tools.ast_grep_replace.execute(
+      {
+        pattern: "foo($A)",
+        rewrite: "bar($A)",
+        lang: "javascript",
+        dryRun: "true" as unknown as boolean,
+      },
+      sdkCtx,
+    );
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.command).toBe("ast_replace");
+    expect(calls[0]?.params.dry_run).toBe(true);
+  });
+});

packages/opencode-plugin/src/__tests__/hoisted-tools.test.ts

@@ -900,6 +900,29 @@ describe("Hoisted tool execute handlers", () => {
     });
   });
 
+  test('edit forwards string replaceAll "true" to Rust replace_all', async () => {
+    tmpDir = await makeTempDir();
+    sdkCtx = createMockSdkContext(tmpDir);
+
+    const { calls, tools } = createMockHoistedHarness(async () => ({
+      success: true,
+      replacements: 1,
+    }));
+
+    await tools.edit.execute(
+      {
+        filePath: "repeated.ts",
+        oldString: "oldName",
+        newString: "newName",
+        replaceAll: "true" as unknown as boolean,
+      },
+      sdkCtx,
+    );
+
+    const applyCall = calls.find((c) => c.command === "edit_match" && c.params.preview !== true);
+    expect(applyCall?.params.replace_all).toBe(true);
+  });
+
   /// Diff-payload contract: the plugin requests full before/after from Rust
   /// (include_diff_content) for UI metadata, but the AGENT-facing result must
   /// strip the file content down to counts only. Echoing before/after into the

packages/opencode-plugin/src/tools/ast.ts

@@ -8,6 +8,7 @@ import { tool } from "@opencode-ai/plugin";
 
 const z = tool.schema;
 
+import { coerceBoolean } from "@cortexkit/aft-bridge";
 import type { ToolDefinition } from "@opencode-ai/plugin";
 import type { PluginContext } from "../types.js";
 import { callBridge, isEmptyParam, optionalInt, resolvePathArg } from "./_shared.js";
@@ -226,7 +227,8 @@ export function astTools(ctx: PluginContext): Record<string, ToolDefinition> {
       dryRun: z.boolean().optional().describe("Preview changes without applying (default: false)"),
     },
     execute: async (args, context): Promise<string> => {
-      const isDryRun = args.dryRun === true;
+      // Coerce at the boundary: dryRun "true" must stay preview-only (coerceBoolean).
+      const isDryRun = coerceBoolean(args.dryRun);
       const paths = await resolveAstPaths(ctx, context, args.paths);
 
       const externalDenied = await checkAstPathsPermission(ctx, context, paths);
@@ -269,7 +271,9 @@ export function astTools(ctx: PluginContext): Record<string, ToolDefinition> {
       // Use isEmptyParam — see ast_search above for rationale.
       if (!isEmptyParam(paths)) params.paths = paths;
       if (!isEmptyParam(args.globs)) params.globs = args.globs;
-      params.dry_run = args.dryRun === true;
+      // Normalize dryRun at the plugin-to-bridge boundary with coerceBoolean so
+      // a string "true" still sets dry_run to a real boolean and the replace stays preview-only.
+      params.dry_run = coerceBoolean(args.dryRun);
       const response = await callBridge(ctx, context, "ast_replace", params);
 
       // Error response (e.g. invalid pattern)

packages/opencode-plugin/src/tools/bash.ts

@@ -1,6 +1,7 @@
 import {
   appendPipeStripNote,
   type BridgeRequestOptions,
+  coerceBoolean,
   formatForegroundResult,
   formatSeconds,
   isTerminalStatus,
@@ -255,11 +256,13 @@ export function createBashTool(
       // command still runs to completion, just inline.
       const isSubagent = await resolveIsSubagent(ctx.client, context.sessionID, context.directory);
       const backgroundDisabled = !bashCfg.background;
-      const requestedPty = !backgroundDisabled && args.pty === true;
+      // Coerce at the boundary: stringified pty/background flags (coerceBoolean).
+      const requestedPty = !backgroundDisabled && coerceBoolean(args.pty);
       // pty:true silently implies background:true (Rust bash.rs handles the
       // auto-promote). Agents don't need to set both flags. When background is
       // disabled, those args are omitted from the schema and defensively ignored.
-      const requestedBackground = !backgroundDisabled && (args.background === true || requestedPty);
+      const requestedBackground =
+        !backgroundDisabled && (coerceBoolean(args.background) || requestedPty);
       // ptyRows/ptyCols are silently ignored when pty is false so agents
       // that defensively pass them on normal bash calls don't get stuck in
       // a retry loop. pty: true silently implies background: true (Rust

packages/opencode-plugin/src/tools/bash_watch.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import {
   type BridgeRequestOptions,
+  coerceBoolean,
   isBridgeTransportTimeout,
   isTerminalStatus,
   sleep,
@@ -77,7 +78,8 @@ export function createBashWatchTool(ctx: PluginContext): ToolDefinition {
     },
     execute: async (args, context) => {
       const taskId = args.taskId as string;
-      const requestedAsync = args.background === true;
+      // Coerce at the boundary: stringified background must enable async mode (coerceBoolean).
+      const requestedAsync = coerceBoolean(args.background);
       const waitFor = parseWaitPattern(args.pattern);
       const bashCfg = resolveBashConfig(ctx.config);
       const isSubagent = await resolveIsSubagent(ctx.client, context.sessionID, context.directory);

packages/opencode-plugin/src/tools/hoisted.ts

@@ -899,7 +899,8 @@ function createEditTool(ctx: PluginContext, writeToolName = "write"): ToolDefini
         command = "edit_match";
         params.match = args.oldString;
         params.replacement = args.newString ?? "";
-        if (args.replaceAll !== undefined) params.replace_all = args.replaceAll;
+        // Coerce at the boundary: stringified replaceAll must forward true (coerceBoolean).
+        if (coerceBoolean(args.replaceAll)) params.replace_all = true;
         if (args.occurrence !== undefined) params.occurrence = args.occurrence;
       } else {
         // No mode-selecting parameter matched. We deliberately do NOT fall

packages/opencode-plugin/src/tools/reading.ts

@@ -1,4 +1,5 @@
 import {
+  coerceBoolean,
   formatZoomMultiTargetResult,
   formatZoomText,
   unwrapRustZoomBatchEnvelope,
@@ -82,7 +83,8 @@ export function readingTools(ctx: PluginContext): Record<string, ToolDefinition>
       },
       execute: async (args, context): Promise<string> => {
         const target = args.target;
-        const filesMode = args.files === true;
+        // Coerce at the boundary: stringified "true" must enable files mode (coerceBoolean).
+        const filesMode = coerceBoolean(args.files);
         const hasUrl =
           typeof target === "string" &&
           (target.startsWith("http://") || target.startsWith("https://"));
@@ -293,7 +295,8 @@ export function readingTools(ctx: PluginContext): Record<string, ToolDefinition>
         const hasUrl = !isEmptyParam(args.url);
         const hasTargets = hasTargetsProvided(args.targets);
         const hasSymbols = !isEmptyParam(args.symbols);
-        const wantCallgraph = args.callgraph === true;
+        // Coerce at the boundary: stringified "true" must request callgraph (coerceBoolean).
+        const wantCallgraph = coerceBoolean(args.callgraph);
 
         // TUI title + scalar metadata for the tool-call header. OpenCode's UI
         // only auto-renders SCALAR args (strings, numbers, booleans) — arrays

packages/pi-plugin/src/__tests__/ast.test.ts

@@ -74,4 +74,20 @@ describe("AST tool adapters", () => {
       dry_run: true,
     });
   });
+
+  test('ast_grep_replace treats string dryRun "true" as preview (dry_run true)', async () => {
+    const { api, tools } = makeMockApi();
+    const { bridge, calls } = makeMockBridge(() => ({ success: true, text: "preview" }));
+    registerAstTools(api, makePluginContext(bridge), { astSearch: false, astReplace: true });
+
+    await executeTool(tools.get("ast_grep_replace")!, {
+      pattern: "foo($A)",
+      rewrite: "bar($A)",
+      lang: "javascript",
+      dryRun: "true" as unknown as boolean,
+    });
+
+    expect(calls[0].command).toBe("ast_replace");
+    expect(calls[0].params.dry_run).toBe(true);
+  });
 });

packages/pi-plugin/src/tools/ast.ts

@@ -3,6 +3,7 @@
  * 8 languages: typescript, tsx, javascript, python, rust, go, pascal, r.
  */
 
+import { coerceBoolean } from "@cortexkit/aft-bridge";
 import { StringEnum } from "@earendil-works/pi-ai";
 import type {
   AgentToolResult,
@@ -347,8 +348,8 @@ export function registerAstTools(pi: ExtensionAPI, ctx: PluginContext, surface:
         // Use isEmptyParam — see ast_search above for rationale.
         if (!isEmptyParam(paths)) req.paths = paths;
         if (!isEmptyParam(params.globs)) req.globs = params.globs;
-        // Rust ast_replace defaults to dry_run=true; apply by default to match description.
-        req.dry_run = params.dryRun === true;
+        // Coerce at the boundary: dryRun "true" must stay preview-only (coerceBoolean).
+        req.dry_run = coerceBoolean(params.dryRun);
         const response = await callBridge(bridge, "ast_replace", req, extCtx);
         return textResult((response.text as string | undefined) ?? JSON.stringify(response));
       },

packages/pi-plugin/src/tools/bash.ts

@@ -3,6 +3,7 @@ import {
   appendPipeStripNote,
   type BinaryBridge,
   type BridgeRequestOptions,
+  coerceBoolean,
   formatForegroundResult,
   formatSeconds,
   isBridgeTransportTimeout,
@@ -380,9 +381,10 @@ DO NOT use bash for code search or code exploration. If you are about to run gre
       const ptyCols = backgroundDisabled
         ? undefined
         : coerceOptionalInt(params.ptyCols, "ptyCols", 1, 140);
-      const requestedPty = !backgroundDisabled && params.pty === true;
+      // Coerce at the boundary: stringified pty/background flags (coerceBoolean).
+      const requestedPty = !backgroundDisabled && coerceBoolean(params.pty);
       const effectiveBackground =
-        !backgroundDisabled && (params.background === true || requestedPty);
+        !backgroundDisabled && (coerceBoolean(params.background) || requestedPty);
       // Hard-kill timeout sent to the bridge. For an EXPLICIT background task a
       // small `timeout` is a legitimate kill cap, so honor it verbatim. For the
       // FOREGROUND auto-promote path a `timeout` below the foreground wait
@@ -665,7 +667,8 @@ export function createBashWatchTool(ctx: PluginContext) {
     ) {
       const bridge = bridgeFor(ctx, extCtx.cwd);
       const waitFor = parseWaitPattern(params.pattern);
-      if (params.background === true) {
+      // Coerce at the boundary: stringified background must enable async mode (coerceBoolean).
+      if (coerceBoolean(params.background)) {
         if (!waitFor) {
           throw new Error(
             "invalid_request: Use auto-reminder; bash_watch without pattern in async mode is redundant",