context-mode 1.0.140 → 1.0.142

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.140"
+    "version": "1.0.142"
   },
   "plugins": [
     {
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "1.0.140",
+      "version": "1.0.142",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.140",
+  "version": "1.0.142",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.140",
+  "version": "1.0.142",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.openclaw-plugin/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.140",
+  "version": "1.0.142",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.140",
+  "version": "1.0.142",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/README.md

@@ -439,7 +439,7 @@ Full configs: [`configs/cursor/hooks.json`](configs/cursor/hooks.json) | [`confi
 
 **Verify:** In the OpenCode session, type `ctx stats`. Context-mode tools should appear and respond.
 
-**Upgrade note:** If an existing config still has `mcp.context-mode`, run `context-mode upgrade`. OpenCode now gets `ctx_*` tools from the plugin; the upgrade removes only `mcp.context-mode` and preserves any other MCP servers.
+**Upgrade note:** If an existing config has BOTH `plugin: ["context-mode"]` AND `mcp.context-mode`, OpenCode will register zero `ctx_*` tools — the plugin path correctly suppresses MCP duplicates, but the legacy MCP entry confuses the loader. Run `context-mode upgrade` to remove the legacy `mcp.context-mode` entry; your other MCP servers are preserved. v1.0.140+ emits a stderr diagnostic with the same guidance when this happens.
 
 **Routing:** Hooks enforce routing programmatically via `tool.execute.before` and `tool.execute.after`. The optional [`AGENTS.md`](configs/opencode/AGENTS.md) file provides routing instructions for model awareness. The `experimental.session.compacting` hook builds resume snapshots when the conversation compacts. The `experimental.chat.system.transform` hook injects the routing block and prior-session snapshots at session start, enabling session continuity across restarts. The `chat.message` hook captures user prompts and decisions (UserPromptSubmit equivalent).
 
@@ -483,7 +483,7 @@ Full configs: [`configs/opencode/opencode.json`](configs/opencode/opencode.json)
 
 **Verify:** In the KiloCode session, type `ctx stats`. Context-mode tools should appear and respond.
 
-**Upgrade note:** If an existing config still has `mcp.context-mode`, run `context-mode upgrade`. KiloCode now gets `ctx_*` tools from the plugin; the upgrade removes only `mcp.context-mode` and preserves any other MCP servers.
+**Upgrade note:** If an existing config has BOTH `plugin: ["context-mode"]` AND `mcp.context-mode`, KiloCode will register zero `ctx_*` tools — the plugin path correctly suppresses MCP duplicates, but the legacy MCP entry confuses the loader. Run `context-mode upgrade` to remove the legacy `mcp.context-mode` entry; your other MCP servers are preserved. v1.0.140+ emits a stderr diagnostic with the same guidance when this happens.
 
 **Routing:** Hooks enforce routing programmatically via `tool.execute.before` and `tool.execute.after`. The optional [`AGENTS.md`](configs/opencode/AGENTS.md) file provides routing instructions for model awareness. The `experimental.session.compacting` hook builds resume snapshots when the conversation compacts. The `experimental.chat.system.transform` hook injects the routing block and prior-session snapshots at session start, enabling session continuity across restarts. The `chat.message` hook captures user prompts and decisions (UserPromptSubmit equivalent).
 

package/build/adapters/opencode/plugin.js

@@ -28,25 +28,7 @@ import { extractEvents, extractUserEvents } from "../../session/extract.js";
 import { buildResumeSnapshot } from "../../session/snapshot.js";
 import { OpenCodeAdapter } from "./index.js";
 import { PLATFORM_ENV_VARS } from "../detect.js";
-// Read package.json version once at module load (not on every hook call).
-// Used in the resume-injection visible signal so users can confirm in
-// OPENCODE_DEBUG logs which plugin version actually injected.
-const VERSION = (() => {
-    try {
-        const pkgRoot = dirname(fileURLToPath(import.meta.url));
-        // Search both the legacy depths (when bundled flat under build/) and
-        // the post-refactor depths (when compiled to build/adapters/opencode/).
-        // `../../../package.json` is the canonical location after the
-        // `src/opencode-plugin.ts → src/adapters/opencode/plugin.ts` move.
-        for (const rel of ["../../../package.json", "../package.json", "./package.json"]) {
-            const p = resolve(pkgRoot, rel);
-            if (existsSync(p))
-                return JSON.parse(readFileSync(p, "utf8")).version ?? "unknown";
-        }
-    }
-    catch { /* fall through */ }
-    return "unknown";
-})();
+import { zod3ShapeToV4 } from "./zod3tov4.js";
 // Synthetic message tags emitted by harnesses (CCv2 inline filter). When the
 // user "message" is actually a system-generated nudge (e.g. tool-result, system
 // reminder), capturing it as user_prompt would flood the DB with noise.
@@ -264,9 +246,12 @@ async function createContextModePlugin(ctx) {
                 : typeof inputSchema?._def?.shape === "function"
                     ? inputSchema._def.shape()
                     : {};
+            const argsForHost = platform === "kilo"
+                ? zod3ShapeToV4(shape)
+                : shape;
             tools[registered.name] = {
                 description: String(config.description ?? ""),
-                args: shape,
+                args: argsForHost,
                 async execute(args, toolCtx) {
                     toolCtx.metadata?.({ title: String(config.title ?? registered.name) });
                     const project = toolCtx.directory || projectDir;

package/build/adapters/opencode/zod3tov4.d.ts

@@ -0,0 +1 @@
+export declare function zod3ShapeToV4(shape: Record<string, unknown>, depth?: number): Record<string, unknown>;

package/build/adapters/opencode/zod3tov4.js

@@ -0,0 +1,111 @@
+/**
+ * Zod 3 → Zod 4 shape conversion (KiloCode only).
+ *
+ * KiloCode's runtime bundles Zod v4 internally. When it receives plugin tool
+ * definitions whose `args` contain Zod v3 schemas (with `_def` but no `_zod`),
+ * it crashes with `undefined is not an object (evaluating 'n._zod.def')`.
+ *
+ * This module converts Zod 3 schema shapes into Zod 4 equivalents so KiloCode
+ * can process them natively. Only called when `platform === "kilo"`.
+ * OpenCode uses Zod 3 natively and receives the original shapes unchanged.
+ */
+import z from 'zod/v4';
+export function zod3ShapeToV4(shape, depth = 0) {
+    const result = {};
+    for (const [key, value] of Object.entries(shape)) {
+        result[key] = zod3ToV4(value, depth);
+    }
+    return result;
+}
+function zod3ToV4(v, depth = 0) {
+    if (depth > 10)
+        return z.unknown();
+    if (v == null || typeof v !== "object")
+        return z.unknown();
+    const obj = v;
+    if (!obj._def || typeof obj._def !== "object")
+        return z.unknown();
+    const def = obj._def;
+    let result;
+    switch (def.typeName) {
+        case "ZodString":
+            result = z.string();
+            break;
+        case "ZodNumber":
+            result = z.number();
+            break;
+        case "ZodBoolean":
+            result = z.boolean();
+            break;
+        case "ZodAny":
+            result = z.any();
+            break;
+        case "ZodUnknown":
+            result = z.unknown();
+            break;
+        case "ZodNever":
+            result = z.never();
+            break;
+        case "ZodNull":
+            result = z.null();
+            break;
+        case "ZodUndefined":
+            result = z.undefined();
+            break;
+        case "ZodLiteral":
+            result = z.literal(def.value);
+            break;
+        case "ZodArray":
+            result = z.array(zod3ToV4(def.type ?? def.elementType, depth + 1));
+            break;
+        case "ZodEnum": {
+            const values = def.values;
+            result = Array.isArray(values) && values.length > 0
+                ? z.enum(values)
+                : z.never();
+            break;
+        }
+        case "ZodObject": {
+            const raw = def.shape;
+            const inner = typeof raw === "function" ? raw() : raw;
+            result = z.object(inner ? zod3ShapeToV4(inner, depth + 1) : {});
+            break;
+        }
+        case "ZodOptional":
+            result = z.optional(zod3ToV4(def.innerType ?? def.type, depth + 1));
+            break;
+        case "ZodNullable":
+            result = z.nullable(zod3ToV4(def.innerType ?? def.type, depth + 1));
+            break;
+        case "ZodDefault": {
+            const val = typeof def.defaultValue === "function"
+                ? def.defaultValue()
+                : def.defaultValue;
+            result = zod3ToV4(def.innerType ?? def.type, depth + 1).default(val);
+            break;
+        }
+        case "ZodRecord":
+            result = z.record(z.string(), zod3ToV4(def.valueType, depth + 1));
+            break;
+        case "ZodUnion": {
+            const opts = def.options;
+            if (!opts || opts.length === 0)
+                return z.never();
+            if (opts.length === 1)
+                return zod3ToV4(opts[0], depth + 1);
+            result = z.union(opts.map(o => zod3ToV4(o, depth + 1)));
+            break;
+        }
+        case "ZodEffects":
+            // Host schema only. Original Zod 3 schema still parses in execute().
+            result = zod3ToV4(def.schema, depth + 1);
+            break;
+        default:
+            // Never leak raw Zod 3 schemas back to KiloCode.
+            result = z.unknown();
+            break;
+    }
+    return def.description && typeof result.describe === "function"
+        ? result.describe(String(def.description))
+        : result;
+}

package/build/adapters/pi/extension.d.ts

@@ -10,6 +10,34 @@
  * Lifecycle: session_start, tool_call, tool_result, before_agent_start,
  * session_before_compact, session_compact, session_shutdown.
  */
+/**
+ * Strip heredoc + single-quoted + double-quoted content from a shell command
+ * so the routing regex only sees command tokens, not user-provided strings.
+ *
+ * Mirrors hooks/core/routing.mjs:196–209. Inlined here because the Pi
+ * extension is bundled as a standalone build artifact (.pi/extensions/...)
+ * and cannot import hooks/core/* at runtime — they live in a sibling tree
+ * and may not be present in every Pi installation.
+ *
+ * Exported for unit tests.
+ */
+export declare function stripQuotedContent(cmd: string): string;
+/**
+ * Returns true iff `segment` is a curl/wget invocation that is SAFE to allow
+ * through the Pi routing block — i.e. it cannot flood the model's context
+ * window because the response body is written to disk (or appended to a file)
+ * and no verbose/trace flag is dumping headers to stderr.
+ *
+ * Mirrors hooks/core/routing.mjs:672–701. Segments that are NOT curl/wget
+ * return `true` (nothing to evaluate). The caller is expected to split chained
+ * commands on `&&`, `||`, `;` and call this per segment.
+ *
+ * Issue #625 — without this, the only escape hatch when the MCP bridge dies
+ * is `gh` CLI or a full Pi restart. Neither is acceptable as baseline UX.
+ *
+ * Exported for unit tests.
+ */
+export declare function isSafeCurlWget(segment: string): boolean;
 /**
  * Settles when the MCP bridge bootstrap has finished — resolves on
  * success AND on failure (the bootstrap is best-effort; failures are

package/build/adapters/pi/extension.js

@@ -33,9 +33,22 @@ const PI_TOOL_MAP = {
 };
 // ── Routing patterns ─────────────────────────────────────
 // Inline HTTP client patterns to block in bash — self-contained, no routing module needed.
-const BLOCKED_BASH_PATTERNS = [
-    /\bcurl\s/,
-    /\bwget\s/,
+//
+// Issue #625 — split into two classes so we can apply different policies:
+//
+//   * BLOCKED_HTTP_PATTERNS — language-level HTTP calls (fetch, requests, http,
+//     urllib, Invoke-WebRequest). These always flood context with raw response
+//     bodies, so they remain unconditionally blocked.
+//
+//   * curl / wget — handled separately by isSafeCurlWget() below. Mirrors the
+//     reference logic in hooks/core/routing.mjs:660–722. Silent + file-output
+//     forms are allowed as an MCP-down escape hatch (the body never enters
+//     context). Unsafe forms (stdout, verbose, missing file output) still
+//     block. This prevents an unrecoverable session trap when the bridge dies.
+//
+// Both are evaluated AFTER stripQuotedContent() so quoted CLI arguments
+// (e.g. `gh issue list --search "curl wget"`) no longer false-positive.
+const BLOCKED_HTTP_PATTERNS = [
     /\bfetch\s*\(/,
     /\brequests\.get\s*\(/,
     /\brequests\.post\s*\(/,
@@ -44,6 +57,68 @@ const BLOCKED_BASH_PATTERNS = [
     /\burllib\.request/,
     /\bInvoke-WebRequest\b/,
 ];
+/**
+ * Strip heredoc + single-quoted + double-quoted content from a shell command
+ * so the routing regex only sees command tokens, not user-provided strings.
+ *
+ * Mirrors hooks/core/routing.mjs:196–209. Inlined here because the Pi
+ * extension is bundled as a standalone build artifact (.pi/extensions/...)
+ * and cannot import hooks/core/* at runtime — they live in a sibling tree
+ * and may not be present in every Pi installation.
+ *
+ * Exported for unit tests.
+ */
+export function stripQuotedContent(cmd) {
+    return cmd
+        .replace(/<<-?\s*["']?(\w+)["']?[\s\S]*?\n\s*\1/g, "") // heredocs
+        .replace(/'[^']*'/g, "''") // single-quoted
+        .replace(/"[^"]*"/g, '""'); // double-quoted
+}
+/**
+ * Returns true iff `segment` is a curl/wget invocation that is SAFE to allow
+ * through the Pi routing block — i.e. it cannot flood the model's context
+ * window because the response body is written to disk (or appended to a file)
+ * and no verbose/trace flag is dumping headers to stderr.
+ *
+ * Mirrors hooks/core/routing.mjs:672–701. Segments that are NOT curl/wget
+ * return `true` (nothing to evaluate). The caller is expected to split chained
+ * commands on `&&`, `||`, `;` and call this per segment.
+ *
+ * Issue #625 — without this, the only escape hatch when the MCP bridge dies
+ * is `gh` CLI or a full Pi restart. Neither is acceptable as baseline UX.
+ *
+ * Exported for unit tests.
+ */
+export function isSafeCurlWget(segment) {
+    const s = segment.trim();
+    const isCurl = /\bcurl\b/i.test(s);
+    const isWget = /\bwget\b/i.test(s);
+    if (!isCurl && !isWget)
+        return true; // not curl/wget — nothing to evaluate
+    // Check for file output flags (-o file / --output file for curl,
+    // -O file / --output-document file for wget) OR shell redirection (> / >>).
+    const hasFileOutput = isCurl
+        ? /\s(-o|--output)\s/.test(s) || /\s>\s*/.test(s) || /\s>>\s*/.test(s)
+        : /\s(-O|--output-document)\s/.test(s) ||
+            /\s>\s*/.test(s) ||
+            /\s>>\s*/.test(s);
+    if (!hasFileOutput)
+        return false; // no file output → body flows to stdout
+    // Stdout aliases: -o -, -o /dev/stdout, -O -, -O /dev/stdout.
+    if (isCurl && /\s(-o|--output)\s+(-|\/dev\/stdout)(\s|$)/.test(s))
+        return false;
+    if (isWget && /\s(-O|--output-document)\s+(-|\/dev\/stdout)(\s|$)/.test(s))
+        return false;
+    // Verbose/trace flags dump request+response headers to stderr → context.
+    if (/\s(-v|--verbose|--trace)\b/.test(s))
+        return false;
+    // Must be silent (curl: -s/--silent, wget: -q/--quiet) so the progress bar
+    // does not spill into stderr → context.
+    const isSilent = isCurl
+        ? /\s-[a-zA-Z]*s|--silent/.test(s)
+        : /\s-[a-zA-Z]*q|--quiet/.test(s);
+    return isSilent;
+}
 // ── Module-level DB singleton ────────────────────────────
 let _db = null;
 let _sessionId = "";
@@ -318,14 +393,36 @@ export default function piExtension(pi) {
             const command = String(event?.input?.command ?? "");
             if (!command)
                 return;
-            const isBlocked = BLOCKED_BASH_PATTERNS.some((p) => p.test(command));
-            if (isBlocked) {
+            // Issue #625 — strip quoted content first so words like `curl` inside
+            // a `gh issue list --search "...curl..."` argument do not false-positive.
+            const stripped = stripQuotedContent(command);
+            // Language-level HTTP calls (fetch, requests, http, urllib,
+            // Invoke-WebRequest) always flood context — block unconditionally.
+            if (BLOCKED_HTTP_PATTERNS.some((p) => p.test(stripped))) {
                 return {
                     block: true,
                     reason: "Use context-mode MCP tools (execute, fetch_and_index) instead of inline HTTP clients. " +
-                        "Raw curl/wget/fetch output floods the context window.",
+                        "Raw fetch/requests/http output floods the context window.",
                 };
             }
+            // curl / wget — split chained command on &&, ||, ; and evaluate each
+            // segment with isSafeCurlWget(). Allowed if EVERY curl/wget segment is
+            // silent + file-output + no verbose + no stdout alias. This preserves
+            // the "do not flood context" intent while leaving a recovery path open
+            // when the MCP bridge is unreachable.
+            if (/(^|\s|&&|\||\;)(curl|wget)\s/i.test(stripped)) {
+                const segments = stripped.split(/\s*(?:&&|\|\||;)\s*/);
+                const hasUnsafeSegment = segments.some((seg) => !isSafeCurlWget(seg));
+                if (hasUnsafeSegment) {
+                    return {
+                        block: true,
+                        reason: "Use context-mode MCP tools (execute, fetch_and_index) instead of inline HTTP clients. " +
+                            "Raw curl/wget output floods the context window. " +
+                            "For an MCP-down escape hatch, use silent + file output: " +
+                            "`curl -s -o /tmp/x.json URL` or `wget -q -O /tmp/x.json URL`.",
+                    };
+                }
+            }
         }
         catch {
             // Routing failure — allow passthrough
@@ -337,7 +434,12 @@ export default function piExtension(pi) {
             if (!_sessionId)
                 return;
             const rawToolName = String(event?.toolName ?? event?.tool_name ?? "");
-            const mappedToolName = PI_TOOL_MAP[rawToolName.toLowerCase()] ?? rawToolName;
+            let mappedToolName = PI_TOOL_MAP[rawToolName.toLowerCase()] ?? rawToolName;
+            // Pi namespaces MCP-registered tools with the "context_mode_" prefix;
+            // the extract functions expect the "mcp__" prefix for MCP tool calls.
+            if (/^context_mode_/.test(rawToolName)) {
+                mappedToolName = rawToolName.replace(/^context_mode_/, "mcp__context_mode__");
+            }
             // Normalize result to string
             const rawResult = event?.result ?? event?.output;
             const resultStr = typeof rawResult === "string"
@@ -347,9 +449,16 @@ export default function piExtension(pi) {
                     : undefined;
             // Detect errors
             const hasError = Boolean(event?.error || event?.isError);
+            // Pi sends file tool parameters as "path"; the extract functions
+            // expect "file_path" (Claude Code convention). Normalise before
+            // passing to extractEvents so file reads/writes/edits are tracked.
+            const rawInput = { ...(event?.params ?? event?.input ?? {}) };
+            if (rawInput.path !== undefined && rawInput.file_path === undefined) {
+                rawInput.file_path = String(rawInput.path);
+            }
             const hookInput = {
                 tool_name: mappedToolName,
-                tool_input: event?.params ?? event?.input ?? {},
+                tool_input: rawInput,
                 tool_response: resultStr,
                 tool_output: hasError ? { isError: true } : undefined,
             };

package/build/cli.js

@@ -58,6 +58,7 @@ const HOOK_MAP = {
         userpromptsubmit: "hooks/userpromptsubmit.mjs",
     },
     "gemini-cli": {
+        beforeagent: "hooks/gemini-cli/beforeagent.mjs",
         beforetool: "hooks/gemini-cli/beforetool.mjs",
         aftertool: "hooks/gemini-cli/aftertool.mjs",
         precompress: "hooks/gemini-cli/precompress.mjs",
@@ -1252,7 +1253,27 @@ async function upgrade(opts) {
         const message = err instanceof Error ? err.message : String(err);
         s.stop(color.red("Update failed"));
         p.log.error(color.red("GitHub pull failed") + ` — ${message}`);
-        p.log.info(color.dim("Continuing with hooks/settings fix..."));
+        // Issue #628 — Windows `spawnSync cmd.exe ETIMEDOUT` (and any
+        // other Step 1/2 throw — network, npm, manifest mismatch) used
+        // to fall through to Steps 3-7 (backup, hooks, perms, doctor),
+        // all of which succeed against the OLD on-disk install. The
+        // process then exited 0 and the upgrade-checklist renderer
+        // marked `[x] Built and installed vNEW` while in-place files,
+        // installed_plugins.json registry, and per-version cache dirs
+        // stayed at vOLD. Worse: the marketplace clone synced earlier
+        // in this same run is now AHEAD of cache+registry — Claude
+        // Code's plugin manager keeps offering the same upgrade
+        // forever (drift trap; reporter had to hand-edit
+        // installed_plugins.json to escape).
+        //
+        // Algo defense: mark the process for non-zero exit and surface
+        // an actionable recovery hint. Steps 3-7 still run because the
+        // user's hooks may be broken regardless — but the overall
+        // upgrade no longer reports success.
+        process.exitCode = 1;
+        p.log.warn(color.yellow("In-place files were NOT updated") +
+            color.dim(" — old version is still on disk; hooks/settings will still be refreshed."));
+        p.log.info(color.dim("  Recovery: re-run /ctx-upgrade once network is stable, or run /context-mode:ctx-doctor for a full health check."));
         try {
             rmSync(tmpDir, { recursive: true, force: true });
         }

package/build/server.js

@@ -1163,8 +1163,13 @@ server.registerTool("ctx_execute", {
             .coerce.number()
             .optional()
             .describe("Max execution time in ms. When omitted, no server-side timer fires — the MCP host's RPC timeout governs (which is the right layer for this policy). Pass an explicit value for long-running builds (Gradle/Maven/SBT)."),
+        // background: wrapped in coerceBoolean preprocessor so the literal
+        // strings "true"/"false" arriving from OpenCode's native plugin
+        // bridge (and several LLM providers' tool-call JSON) parse as the
+        // boolean the handler expects. z.coerce.boolean() is unsafe here —
+        // Boolean("false") is true. Fixes #627.
         background: z
-            .boolean()
+            .preprocess(coerceBoolean, z.boolean())
             .optional()
             .default(false)
             .describe("Keep process running after timeout (for servers/daemons). Returns partial output without killing the process. IMPORTANT: Do NOT add setTimeout/self-close timers in background scripts — the process must stay alive until the timeout detaches it. For server+fetch patterns, prefer putting both server and fetch in ONE ctx_execute call instead of using background."),
@@ -1654,19 +1659,57 @@ const SEARCH_WINDOW_MS = 60_000;
 const SEARCH_MAX_RESULTS_AFTER = 3; // after 3 calls: 1 result per query
 const SEARCH_BLOCK_AFTER = 8; // after 8 calls: refuse, demand batching
 /**
- * Defensive coercion: parse stringified JSON arrays.
- * Works around Claude Code double-serialization bug where array params
- * are sent as JSON strings (e.g. "[\"a\",\"b\"]" instead of ["a","b"]).
- * See: https://github.com/anthropics/claude-code/issues/34520
+ * Defensive coercion: parse stringified JSON arrays, AND lift a bare
+ * non-empty string into a single-element array.
+ *
+ * Two shapes show up from the wild:
+ *   1. `"[\"a\",\"b\"]"` — Claude Code double-serialization bug
+ *      (https://github.com/anthropics/claude-code/issues/34520).
+ *   2. `"single query"` — some LLM providers / OpenCode's native plugin
+ *      bridge deliver a single string when the schema expects `string[]`
+ *      (issue #627). v1.0.139 (#621) made the bridge run the Zod schema,
+ *      so this now surfaces as `Expected array, received string`. The
+ *      ergonomic recovery is to treat it as `["single query"]`.
+ *
+ * An empty string is intentionally NOT lifted — empty input should still
+ * fail Zod's `.min(1)` check rather than masquerade as `[""]`.
  */
 function coerceJsonArray(val) {
     if (typeof val === "string") {
+        const trimmed = val.trim();
+        if (trimmed.length === 0)
+            return val; // let zod produce "non-empty" error
         try {
             const parsed = JSON.parse(val);
             if (Array.isArray(parsed))
                 return parsed;
         }
-        catch { /* not valid JSON, let zod handle the error */ }
+        catch { /* fall through — not JSON, treat as bare-string lift */ }
+        // Bare-string lift (#627): single query delivered as a plain string.
+        return [val];
+    }
+    return val;
+}
+/**
+ * Defensive coercion: accept the string literals "true"/"false" as
+ * booleans. The OpenCode native plugin bridge (and several LLM providers'
+ * tool-call JSON) stringifies primitives — `background:"false"` instead
+ * of `background:false`, `confirm:"true"` instead of `confirm:true`.
+ *
+ * We deliberately do NOT use `z.coerce.boolean()` for boolean fields:
+ * `Boolean("false")` is `true`, so Zod's coerce path silently flips the
+ * meaning. This helper recognises only the documented literal forms and
+ * passes anything else through untouched so Zod surfaces the right error.
+ *
+ * Fixes #627.
+ */
+function coerceBoolean(val) {
+    if (typeof val === "string") {
+        const t = val.trim().toLowerCase();
+        if (t === "true")
+            return true;
+        if (t === "false")
+            return false;
     }
     return val;
 }
@@ -1693,8 +1736,16 @@ server.registerTool("ctx_search", {
             .array(z.string())
             .optional()
             .describe("Array of search queries. Batch ALL questions in one call.")),
+        // limit: z.coerce.number() (not z.number()) — OpenCode's native
+        // plugin path delivers tool args straight from the LLM provider's
+        // tool-call JSON, where several providers stringify primitives
+        // (limit:"4" instead of limit:4). Since v1.0.139 / #621 we run
+        // inputSchema.parse() on that path, so a plain z.number() rejects
+        // "4" with "Expected number, received string". z.coerce mirrors what
+        // ctx_batch_execute / ctx_fetch_and_index / ctx_execute already do.
+        // Fixes #627.
         limit: z
-            .number()
+            .coerce.number()
             .optional()
             .default(3)
             .describe("Results per query (default: 3)"),
@@ -3154,7 +3205,11 @@ server.registerTool("ctx_purge", {
     // .superRefine() wrapper. See block comment above & issue #563. The
     // cross-field ambiguity check lives in the handler body below.
     inputSchema: z.object({
-        confirm: z.boolean().describe("MUST be true. Destructive operation; false returns 'purge cancelled'."),
+        // confirm: wrapped in coerceBoolean preprocessor — OpenCode's native
+        // plugin bridge can deliver `confirm:"true"` / `confirm:"false"` as
+        // string literals. Without this, v1.0.139's inputSchema.parse() path
+        // rejects valid intent as "Expected boolean, received string" (#627).
+        confirm: z.preprocess(coerceBoolean, z.boolean()).describe("MUST be true. Destructive operation; false returns 'purge cancelled'."),
         sessionId: z.string().optional().describe("UUID of a single session. Pairs with confirm:true to wipe only that " +
             "session's events + per-session FTS5 chunks. Sibling sessions and the " +
             "stats file are preserved. MUST NOT be combined with scope:'project'."),