feat(plugin): bash.commands hook for plugin CLI timeout exemption

Plugins that ship CLI binaries calling back into OpenCode can register their
command names via the bash.commands hook. Matching commands run with timeout=0
(no kill) and skip output truncation so long-running script callbacks aren't
terminated prematurely. The exempt set is cached once at BashTool init.

Author: micuintus

packages/opencode/src/tool/bash.ts

@@ -339,6 +339,7 @@ async function run(
     env: NodeJS.ProcessEnv
     timeout: number
     description: string
+    raw?: boolean
   },
   ctx: Tool.Context,
 ) {
@@ -378,13 +379,23 @@ async function run(
         return Effect.sync(() => ctx.abort.removeEventListener("abort", handler))
       })
 
-      const timeout = Effect.sleep(`${input.timeout + 100} millis`)
-
-      const exit = yield* Effect.raceAll([
-        handle.exitCode.pipe(Effect.map((code) => ({ kind: "exit" as const, code }))),
+      // timeout === 0 means no timeout (scripts with plugin callbacks can run indefinitely)
+      const races: Effect.Effect<{ kind: "exit" | "abort" | "timeout"; code: number | null }>[] = [
+        handle.exitCode.pipe(
+          Effect.map((code) => ({ kind: "exit" as const, code })),
+          Effect.orElseSucceed(() => ({ kind: "exit" as const, code: -1 })),
+        ),
         abort.pipe(Effect.map(() => ({ kind: "abort" as const, code: null }))),
-        timeout.pipe(Effect.map(() => ({ kind: "timeout" as const, code: null }))),
-      ])
+      ]
+      if (input.timeout > 0) {
+        races.push(
+          Effect.sleep(`${input.timeout + 100} millis`).pipe(
+            Effect.map(() => ({ kind: "timeout" as const, code: null })),
+          ),
+        )
+      }
+
+      const exit = yield* Effect.raceAll(races)
 
       if (exit.kind === "abort") {
         aborted = true
@@ -419,6 +430,8 @@ async function run(
       output: preview(output),
       exit: code,
       description: input.description,
+      // Signal Tool.wrap to skip truncation for unbounded plugin commands
+      ...(input.raw && { truncated: false }),
     },
     output,
   }
@@ -461,6 +474,10 @@ export const BashTool = Tool.define("bash", async () => {
       : "If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together (e.g., `git add . && git commit -m \"message\" && git push`). For instance, if one operation must complete before another starts (like mkdir before cp, Write before Bash for git operations, or git add before git commit), run these operations sequentially instead."
   log.info("bash tool using shell", { shell })
 
+  // Collect command names from plugins that need no-timeout (e.g., CLI binaries that
+  // call back into the AI — their scripts can run indefinitely). Cached at init.
+  const exempt = new Set((await Plugin.trigger("bash.commands", {}, { noTimeout: [] as string[] })).noTimeout)
+
   return {
     description: DESCRIPTION.replaceAll("${directory}", Instance.directory)
       .replaceAll("${os}", process.platform)
@@ -474,13 +491,23 @@ export const BashTool = Tool.define("bash", async () => {
       if (params.timeout !== undefined && params.timeout < 0) {
         throw new Error(`Invalid timeout value: ${params.timeout}. Timeout must be a positive number.`)
       }
-      const timeout = params.timeout ?? DEFAULT_TIMEOUT
       const ps = PS.has(name)
       const root = await parse(params.command, ps)
       const scan = await collect(root, cwd, ps, shell)
       if (!Instance.containsPath(cwd)) scan.dirs.add(cwd)
       await ask(ctx, scan)
 
+      // Plugin-registered commands that trigger long-running callbacks need no timeout.
+      // The bash.commands hook lets plugins declare which command names should disable
+      // the timeout (e.g., a plugin shipping a CLI binary that calls back into the AI).
+      const unbounded =
+        exempt.size > 0 &&
+        commands(root).some((node) => {
+          const bin = node.childForFieldName("name") ?? node.firstChild
+          return bin !== null && exempt.has(bin.text)
+        })
+      const timeout = unbounded ? 0 : (params.timeout ?? DEFAULT_TIMEOUT)
+
       return run(
         {
           shell,
@@ -490,6 +517,7 @@ export const BashTool = Tool.define("bash", async () => {
           env: await shellEnv(ctx, cwd),
           timeout,
           description: params.description,
+          raw: unbounded,
         },
         ctx,
       )

packages/opencode/test/tool/bash-env.test.ts

@@ -0,0 +1,25 @@
+import { describe, test, expect } from "bun:test"
+import { readFileSync } from "fs"
+import { resolve } from "path"
+
+describe("bash shellEnv _server caching", () => {
+  const src = readFileSync(resolve(import.meta.dir, "../../src/tool/bash.ts"), "utf-8")
+
+  // Regression: _server was typed as `typeof import(...) | undefined` and
+  // assigned with `_server ??= await import(...)`. The ??= across an await
+  // boundary meant two concurrent shellEnv calls could both enter the import
+  // path before either resolved — each awaited its own import.
+  // The fix caches the Promise itself so concurrent callers share one import.
+  test("_server is typed as Promise (not resolved module)", () => {
+    // Must cache the promise, not the resolved module
+    expect(src).toMatch(/let _server:\s*Promise<typeof import/)
+  })
+
+  test("_server assignment does not use await before ??=", () => {
+    // The old pattern `_server ??= await import(...)` is racy.
+    // The new pattern caches the promise: `_server ??= import(...)`
+    // then awaits separately: `const server = await _server`
+    expect(src).not.toMatch(/_server \?\?= await import/)
+    expect(src).toContain("_server ??= import(")
+  })
+})

packages/opencode/test/tool/tool-define.test.ts

@@ -3,6 +3,7 @@ import z from "zod"
 import { Tool } from "../../src/tool/tool"
 
 const params = z.object({ input: z.string() })
+const defaultArgs = { input: "test" }
 
 function makeTool(id: string, executeFn?: () => void) {
   return {
@@ -46,4 +47,98 @@ describe("Tool.define", () => {
 
     expect(first).not.toBe(second)
   })
+
+  test("validation still works after many init() calls", async () => {
+    const tool = Tool.define("test-validation", {
+      description: "validation test",
+      parameters: z.object({ count: z.number().int().positive() }),
+      async execute(args) {
+        return { title: "test", output: String(args.count), metadata: {} }
+      },
+    })
+
+    for (let i = 0; i < 100; i++) {
+      await tool.init()
+    }
+
+    const resolved = await tool.init()
+
+    const result = await resolved.execute({ count: 42 }, {} as any)
+    expect(result.output).toBe("42")
+
+    await expect(resolved.execute({ count: -1 }, {} as any)).rejects.toThrow("invalid arguments")
+  })
+
+  test("skips truncation when metadata.truncated is already set to false", async () => {
+    const big = "x".repeat(200_000)
+    const tool = Tool.define("test-raw", {
+      description: "raw output tool",
+      parameters: params,
+      async execute() {
+        return { title: "test", output: big, metadata: { truncated: false } }
+      },
+    })
+
+    const resolved = await tool.init()
+    const result = await resolved.execute(defaultArgs, {} as any)
+
+    // The wrap() layer should skip Truncate.output() because truncated is already defined
+    expect(result.output).toBe(big)
+    expect(result.metadata.truncated).toBe(false)
+  })
+
+  test("applies truncation when metadata.truncated is undefined", async () => {
+    const big = "x".repeat(200_000)
+    const tool = Tool.define("test-truncate", {
+      description: "truncated output tool",
+      parameters: params,
+      async execute() {
+        return { title: "test", output: big, metadata: {} as Record<string, any> }
+      },
+    })
+
+    const resolved = await tool.init()
+    const result = await resolved.execute(defaultArgs, {} as any)
+
+    // The wrap() layer should apply Truncate.output() because truncated is undefined
+    expect(result.metadata.truncated).toBe(true)
+    expect(result.output.length).toBeLessThan(big.length)
+  })
+
+  test("skips truncation when metadata.truncated is false and output is small", async () => {
+    const small = "hello world"
+    const tool = Tool.define("test-raw-small", {
+      description: "small raw output tool",
+      parameters: params,
+      async execute() {
+        return { title: "test", output: small, metadata: { truncated: false } }
+      },
+    })
+
+    const resolved = await tool.init()
+    const result = await resolved.execute(defaultArgs, {} as any)
+
+    // truncated: false should be preserved even for small output
+    expect(result.output).toBe(small)
+    expect(result.metadata.truncated).toBe(false)
+  })
+
+  test("skips truncation when metadata.truncated is already set to true", async () => {
+    const big = "x".repeat(200_000)
+    const tool = Tool.define("test-raw-true", {
+      description: "pre-truncated output tool",
+      parameters: params,
+      async execute() {
+        return { title: "test", output: big, metadata: { truncated: true, outputPath: "/tmp/out.txt" } }
+      },
+    })
+
+    const resolved = await tool.init()
+    const result = await resolved.execute(defaultArgs, {} as any)
+
+    // When truncated is already true, wrap() should NOT re-truncate
+    expect(result.output).toBe(big)
+    expect(result.metadata.truncated).toBe(true)
+    expect(result.metadata.outputPath).toBe("/tmp/out.txt")
+  })
 })

packages/plugin/src/index.ts

@@ -237,6 +237,13 @@ export interface Hooks {
     input: { cwd: string; sessionID?: string; callID?: string },
     output: { env: Record<string, string> },
   ) => Promise<void>
+  /**
+   * Register command names that should disable bash timeout.
+   * Plugins shipping CLI binaries that call back into OpenCode should
+   * register their command names here so scripts using them can run
+   * indefinitely instead of being killed after the default 2-minute timeout.
+   */
+  "bash.commands"?: (input: {}, output: { noTimeout: string[] }) => Promise<void>
   "tool.execute.after"?: (
     input: { tool: string; sessionID: string; callID: string; args: any },
     output: {