opencode-overclock 0.2.2 → 0.3.0

package/README.md

@@ -1,106 +1,208 @@
 # opencode-overclock
 
-Power-ups for [opencode](https://opencode.ai). Background tasks, scheduling, sandboxed bash, tool hooks, usage telemetry, checkpoints. Each = module, toggleable. Module dies when opencode ships native equal/better.
+Power-ups for [opencode](https://opencode.ai): background tasks, cron-style scheduling,
+sandboxed bash, quality-gate hooks, cost telemetry, checkpoints — and an ASCII pet.
 
-## Install
+Everything is a separate module you can turn off individually, so you can take one feature and
+ignore the rest. When opencode ships a native equivalent, the matching module goes away.
 
 ```sh
 opencode plugin opencode-overclock       # this project
-opencode plugin -g opencode-overclock    # global
+opencode plugin -g opencode-overclock    # every project
 ```
 
-Requires opencode >= 1.18.9.
+## What you get
+
+| Module        | What it does                                                                                                                                          | Tools it adds                                              |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `tasks`       | Run shell commands in the background. The agent gets the result posted back into the session when they finish, and a nudge if one blocks on a prompt. | `task_run` `task_status` `task_output` `task_kill`         |
+| `sched`       | Recurring prompts on a cron expression or an interval (`"5m"`). Survives restarts; an interval on the current session makes a loop.                   | `schedule_create` `schedule_list` `schedule_delete`        |
+| `guard`       | Your own quality gates: run a command after the agent edits files, and feed failures back to it once the session goes idle.                           | —                                                          |
+| `usage`       | Per-day and per-session cost and token totals, collected from the event bus.                                                                          | `usage_report`                                             |
+| `checkpoints` | Rewind a session to any earlier message, files included, on top of opencode's own snapshots. Reverting asks for permission first.                     | `checkpoint_list` `checkpoint_revert` `checkpoint_restore` |
+| `sandbox`     | Wrap every bash call in bwrap: read-only `/`, writable project and `/tmp`, network off by default. Off unless you enable it.                          | `bash_unsandboxed` (escape hatch)                          |
+| `buddy`       | An ASCII pet next to the prompt that reacts to what the session is doing. Purely cosmetic.                                                            | —                                                          |
 
-One package, two surfaces: the **server** plugin (tools + hooks) and the **TUI** plugin (notifications + slash commands). They register in _separate_ config files, so use the command above rather than editing config by hand — it writes both:
+On top of the tools, the TUI side adds desktop notifications when a turn finishes or the agent
+needs you, plus `/oc-tasks`, `/oc-usage`, `/oc-schedules` and `/oc-buddy`.
+
+**Please read this before installing:** overclock gives the agent the ability to run shell
+commands in the background (`task_run`) and to schedule recurring prompts (`schedule_create`).
+That is the point of the plugin, but it is worth an explicit yes rather than a surprise. It
+tells you what it enabled on a project's first run. The tool definitions cost roughly 800
+tokens of context.
+
+## Install
+
+The command at the top of this page is the reliable way to install, because one package ships
+**two** surfaces that register in two different config files:
 
 ```jsonc
-// opencode.json  -> server surface
+// opencode.json  -> server surface: the tools and hooks
 { "plugin": ["opencode-overclock"] }
-// tui.json       -> TUI surface  (omit this and notifications/slash commands silently never load)
+// tui.json       -> TUI surface: notifications, slash commands, the buddy
 { "plugin": ["opencode-overclock"] }
 ```
 
-Local dev: copy or symlink into `.opencode/plugins/` — see [Dev](#dev). Note that a plugin _path_ only works there; `plugin` array entries resolve by npm name from the registry, and an unpublished name fails silently.
+Adding only the `opencode.json` entry by hand is the most common mistake: the tools work and
+the notifications silently never load.
+
+Requires **opencode >= 1.18.4**. That floor comes from the buddy sprite, which renders against
+the `@opentui/solid` version opencode bundles from 1.18.4 onward. If you don't care about the
+buddy, the server surface alone works back to 1.15.11 — the first release where opencode calls
+a plugin's `dispose` hook, without which this plugin's timers and watchers are never cleaned up.
 
-## Config
+## Configuration
 
-`.opencode/overclock.json` (optional, missing = defaults):
+Everything is optional. With no config file you get every module except `sandbox`, and `guard`
+sits inert until you give it hooks — so the one thing worth configuring on day one is a quality
+gate. A reasonable `.opencode/overclock.json` to start from:
 
 ```json
 {
   "features": {
-    "tasks": true,
-    "sched": true,
-    "sandbox": { "net": false },
     "guard": {
-      "hooks": [{ "name": "typecheck", "tools": ["edit", "write"], "run": "bun run typecheck" }]
-    }
+      "hooks": [
+        {
+          "name": "typecheck",
+          "tools": ["edit", "write"],
+          "run": "npm run typecheck",
+          "pathFilter": "src/**/*.ts"
+        }
+      ]
+    },
+    "tasks": { "killOnExit": true }
   }
 }
 ```
 
-`true`/`false` toggle. Object = on + options. Defaults: all on except sandbox; guard inert without `hooks`.
+That gives you a typecheck after every edit (reported back to the agent when the session goes
+idle), background tasks that don't outlive the session, plus scheduling, telemetry, checkpoints
+and the buddy on their defaults. Swap `run` for whatever your project uses.
+
+Each entry is `true`, `false`, or an object of options (which also means "on"). To turn
+something off:
+
+```json
+{ "features": { "buddy": false } }
+```
+
+| Module                          | Options                                                                                         |
+| ------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `tasks`                         | `killOnExit` bool · `stallDetection` bool · `stallThresholdMs` num · `stallCheckIntervalMs` num |
+| `sched`                         | `skipIfBusy` bool                                                                               |
+| `sandbox`                       | `net` bool                                                                                      |
+| `guard`                         | `hooks` array                                                                                   |
+| `usage`, `checkpoints`, `buddy` | —                                                                                               |
+
+Typos are reported at startup with a "did you mean", because a misspelled key like
+`killOnExist` would otherwise read as "not set" and quietly run the default. A bad config never
+takes the plugin down; the affected setting falls back to its default.
+
+### Quality gate options (`guard`)
 
-Unknown keys, unknown feature names, and wrong option types are reported at startup with a
-"did you mean" — a typo like `killOnExist` would otherwise read as "not set" and silently
-run the default. Bad config never takes the plugin down; it falls back to defaults.
+Each hook runs a command after the agent uses one of the tools it watches, and reports failures
+back to the agent. `name`, `tools` and `run` are required. Also available: `pathFilter` (glob), `mode` (`inject`,
+the default, waits for the session to be idle before reporting; `append` reports immediately),
+`debounceMs` (2000), `timeoutMs` (60000), `onSuccess` (`silent` or `notify`), and `maxDeferMs`
+(300000, how long `inject` waits for an idle session before reporting anyway).
 
-| Feature                | Options                                                                                         |
-| ---------------------- | ----------------------------------------------------------------------------------------------- |
-| `tasks`                | `killOnExit` bool · `stallDetection` bool · `stallThresholdMs` num · `stallCheckIntervalMs` num |
-| `sched`                | `skipIfBusy` bool                                                                               |
-| `sandbox`              | `net` bool                                                                                      |
-| `guard`                | `hooks` array                                                                                   |
-| `usage`, `checkpoints` | —                                                                                               |
-| `buddy`                | — (TUI surface; `features.buddy: false` hides it)                                               |
+### Restricting tool names
 
-Each `guard` hook takes `name` · `tools` (array) · `run` — plus optional `pathFilter` (glob),
-`mode` (`inject` default, or `append`), `debounceMs` (2000), `timeoutMs` (60000), `onSuccess`
-(`silent`/`notify`), and `maxDeferMs` (300000 — how long `inject` waits for an idle session
-before reporting anyway).
+If your setup only accepts certain tool names, list them in `toolAllowlist`. Any tool whose
+name isn't permitted is withheld from the model rather than offered and refused, since a single
+unrecognised name can fail an entire request.
 
-On a project's first run, overclock reports what it added. Worth knowing that installing it
-grants the agent **background shell execution** (`task_run`) and **recurring scheduling**
-(`schedule_create`). The tool definitions themselves cost ~800 tokens of context in total.
+```json
+{
+  "toolAllowlist": ["TaskCreate", "TaskList", "TaskOutput", "TaskStop", "MyExtraTool"],
+  "toolNames": { "task_run": "TaskCreate", "task_status": "TaskList" }
+}
+```
+
+`toolNames` maps this plugin's tools onto names you allow. Keys are declared names (the table
+under [What you get](#what-you-get)); values are what the model sees.
+
+Startup tells you exactly where you stand: what was renamed, what was withheld and which of
+your allowed names are still free to use for it, and any name that collides with an opencode
+built-in (`bash`, `task`, …) or differs from one only by capitalisation — the first replaces
+that built-in, the second reads as a duplicate to anything matching case-insensitively.
+Descriptions mentioning a renamed tool are rewritten too, so the agent never gets instructions
+naming a tool it wasn't given. Permission ids keep their declared names, so existing permission
+config still applies.
+
+#### Named lists
+
+`toolAllowlist` entries can also name a bundled list, which expands to every name it permits.
+Mix and match freely — `["claude-code", "MyExtraTool"]` is a bundled list plus one of your own.
+
+`claude-code` is the tool set Claude Code registers. opencode's ids are snake_case and Claude
+Code's are PascalCase, so the two vocabularies don't overlap and these names are free to use.
+A bundled list also supplies default names for tools where it contains the same operation:
+
+| Module  | Declared          | Sent as      |
+| ------- | ----------------- | ------------ |
+| `tasks` | `task_run`        | `TaskCreate` |
+| `tasks` | `task_status`     | `TaskList`   |
+| `tasks` | `task_output`     | `TaskOutput` |
+| `tasks` | `task_kill`       | `TaskStop`   |
+| `sched` | `schedule_create` | `CronCreate` |
+| `sched` | `schedule_list`   | `CronList`   |
+| `sched` | `schedule_delete` | `CronDelete` |
+
+That's the whole table, and it stops there on purpose. Nothing in the `claude-code` set means
+"revert a session checkpoint" or "report token spend", so `checkpoints`, `usage` and
+`bash_unsandboxed` get no default name: handing them an unrelated one would tell the model the
+wrong thing about what they do. They're withheld until you choose a name yourself, and startup
+says which names are free:
+
+```json
+{
+  "toolAllowlist": "claude-code",
+  "toolNames": { "usage_report": "StructuredOutput" }
+}
+```
+
+`toolNames` overrides any row above too, if a different name reads better for you. The table is
+checked against the source by a test, so the two can't drift apart.
 
-## Features
+## Notes on the TUI surface
 
-| Module        | Tools                                                      | Does                                                                                                                      |
-| ------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `tasks`       | `task_run` `task_status` `task_output` `task_kill`         | background shell cmds; exit -> result posted back into session; stall watchdog nudges on interactive prompts              |
-| `sched`       | `schedule_create` `schedule_list` `schedule_delete`        | cron exprs or intervals ("5m"); interval + current session = loop; restart-safe                                           |
-| `sandbox`     | `bash_unsandboxed` (escape hatch)                          | bwrap-wrap every bash call: `/` ro, project + `/tmp` rw, net configurable. Opt-in                                         |
-| `guard`       | —                                                          | user hooks: after matching tool calls, run configured cmds (debounced), failures fed back to model once the session idles |
-| `usage`       | `usage_report`                                             | per-day + per-session cost/token telemetry off `message.updated` events                                                   |
-| `checkpoints` | `checkpoint_list` `checkpoint_revert` `checkpoint_restore` | session revert/unrevert over opencode's shadow-git snapshots; revert gated by permission ask                              |
-| `buddy`       | —                                                          | ASCII pet beside the prompt (TUI): hatches once per install, idles/blinks, reacts to session events; `/oc-buddy` pets it  |
+The TUI plugin sends a desktop notification (with sound) when a turn completes or the agent
+needs permission, asks a question, or errors — each individually switchable through plugin
+options. Its slash commands read the state files under `.opencode/overclock/`, so they work
+without going through the model.
 
-TUI plugin (`src/tui.ts`, separate surface): OS notifications on idle/permission/question/error via `attention.notify`, slash commands for tasks/usage/schedules off the `.opencode/overclock/` state mirrors, and the buddy (`src/buddy/`) in the prompt-right slots. The buddy rolls species/rarity/name/stats once (persisted in TUI kv), hides below 100 columns, and needs `@opentui/solid` resolvable at runtime -- if it isn't, the buddy silently sits this one out while the rest of the TUI plugin loads.
+The buddy hatches once per install with a random species, rarity and name, persists in the
+TUI's key-value store, hides itself below 100 columns, and needs `@opentui/solid` resolvable at
+runtime. If it isn't, the buddy quietly sits out and the rest of the TUI plugin still loads.
 
-## Layout
+## Contributing
 
 ```
 src/
-  index.ts          entry: config -> init modules -> merge hooks
+  index.ts          entry: load config, init modules, merge hooks
   tui.ts            TUI plugin (notifications + slash commands), separate export
   types.ts          FeatureModule contract
   config.ts         config loader
   merge.ts          hook composition (many modules, same hook -> sequential)
+  tools.ts          gateway tool policy: alias presets, allowlists, rename/withhold
+  validate.ts       overclock.json checks + startup summary
   lib/              state dir + json, session inject + toast
   features/         one file per module + registry
 test/               bun test
 ```
 
-## Add feature
+Adding a feature:
 
-1. `src/features/<name>.ts`, export `FeatureModule`
-2. Register in `src/features/index.ts`
+1. Write `src/features/<name>.ts` exporting a `FeatureModule`.
+2. Register it in `src/features/index.ts`.
+3. If it adds tools, add each one to the `claude-code` table in `src/tools.ts`. A test fails
+   otherwise, since an unmapped tool is invisible behind a whitelisting gateway.
 
-## Docs
-
-- [docs/opencode-plugin-surface.md](docs/opencode-plugin-surface.md) — opencode plugin/hook/event surface map + upstream drift watchlist (research)
-
-## Dev
+Background reading:
+[docs/opencode-plugin-surface.md](docs/opencode-plugin-surface.md) maps opencode's
+plugin/hook/event surface and tracks upstream drift.
 
 ```sh
 bun install
@@ -118,31 +220,38 @@ npm publish
 bun run verify:published    # runtime load, by name, from the registry
 ```
 
-`verify` cannot exercise the runtime load path — opencode resolves `plugin` entries by npm
-name from the registry, and a miss is silent. `verify:published` is the only check that
-proves an installed-from-npm session actually gets the tools; run it after every publish.
+`verify` can't exercise the runtime load path: opencode resolves `plugin` entries by npm name
+from the registry, and a miss is silent. `verify:published` is the only check that proves an
+installed-from-npm session actually gets the tools, so run it after every publish.
 
-### Live loop
+### Working on it locally
 
-`.opencode/plugins/dev.ts` re-exports `src/index.ts`, `dev-tui.ts` re-exports `src/tui.ts` -> opencode session in this repo runs both surfaces from source.
+`.opencode/plugins/dev.ts` re-exports `src/index.ts` and `dev-tui.ts` re-exports `src/tui.ts`,
+so an opencode session in this repo runs both surfaces from source. Note that only this
+auto-loaded directory accepts a path — `plugin` array entries resolve by npm name from the
+registry, and an unpublished name fails silently.
 
-1. `opencode` here. Plugin live.
-2. Edit `src/`. No hot reload -> restart opencode.
-3. State inspect: `.opencode/overclock/` (gitignored).
+1. Run `opencode` here. The plugin is live.
+2. Edit `src/`. There's no hot reload, so restart opencode.
+3. Inspect state under `.opencode/overclock/` (gitignored).
 
 Gotcha: if `~/.config/opencode/tui.json` also loads `opencode-overclock` from npm, that copy
-wins the `overclock-tui` id and the local dev TUI plugin (and any unpublished feature, e.g.
-the buddy) silently never loads. Remove the global entry while developing, or run with
-`XDG_CONFIG_HOME` pointed elsewhere.
+wins the `overclock-tui` id and your local dev TUI plugin (along with any unpublished feature)
+silently never loads. Remove the global entry while developing, or point `XDG_CONFIG_HOME`
+somewhere else.
 
-### Headless e2e
+### Headless end-to-end
 
 ```sh
 timeout 90 opencode run -m anthropic/claude-sonnet-5 "Use task_run to run 'echo hi' ..." < /dev/null
 ```
 
-Gotchas:
+- `< /dev/null` is required; an open stdin hangs.
+- A dev build can hang on exit after the work is done, so wrap it in `timeout` and judge by
+  artifacts (`.opencode/overclock/`, log tails) rather than the exit code.
+- Plugin stderr goes to `opencode run --print-logs` or `~/.local/share/opencode/log/`. Grep for
+  `[overclock]`.
+
+## License
 
-- `< /dev/null` required. Open stdin -> hang.
-- Dev build hang on exit AFTER work done -> wrap in `timeout`, judge by artifacts (`.opencode/overclock/`, log tails), not exit code.
-- Plugin stderr: `opencode run --print-logs` or `~/.local/share/opencode/log/`. Grep `[overclock]`.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-overclock",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Power-ups for opencode: background tasks, scheduling, sandboxed bash, tool hooks, usage telemetry, checkpoints. Modular, toggleable.",
   "type": "module",
   "repository": {
@@ -35,7 +35,7 @@
     "prepublishOnly": "tsc --noEmit && bun test"
   },
   "engines": {
-    "opencode": ">=1.18.9"
+    "opencode": ">=1.18.4"
   },
   "dependencies": {
     "@opencode-ai/plugin": "1.18.9",

package/src/features/tasks.ts

@@ -245,7 +245,7 @@ export const tasks: FeatureModule = {
   },
   defaultEnabled: true,
   requires: ["session.promptAsync", "session.messages"],
-  async init(ctx, options) {
+  async init(ctx, options, shared) {
     const logDir = await ensureStateDir(ctx.directory, "tasks")
     const stateDir = await ensureStateDir(ctx.directory)
     const killOnExit = options.killOnExit !== false
@@ -284,7 +284,7 @@ export const tasks: FeatureModule = {
                 task.sessionID,
                 `[background task ${task.id} "${task.description}" appears to be waiting for interactive input]\n` +
                   `last output:\n${tail.trimEnd()}\n\n` +
-                  `The command is likely blocked on a prompt. Kill it with task_kill and re-run non-interactively ` +
+                  `The command is likely blocked on a prompt. Kill it with ${shared.toolName("task_kill")} and re-run non-interactively ` +
                   `(e.g. pipe input like \`echo y | cmd\`, or pass a --yes/--force flag).`,
               )
             },

package/src/index.ts

@@ -7,6 +7,7 @@ import { toast } from "./lib/inject.ts"
 import { firstRun } from "./lib/state.ts"
 import { validateConfig, summarise } from "./validate.ts"
 import { createBusyTracker } from "./lib/busy.ts"
+import { EMPTY_POLICY, resolveToolPolicy, type ToolPolicy } from "./tools.ts"
 import type { FeatureModule, SharedDeps } from "./types.ts"
 
 /**
@@ -16,22 +17,17 @@ import type { FeatureModule, SharedDeps } from "./types.ts"
 export const Overclock: Plugin = async (ctx) => {
   const config = await loadConfig(ctx.directory)
 
-  // A mistyped key is otherwise a silent no-op -- the feature runs with defaults and the
-  // user believes their setting took effect. Warn, never throw: bad config degrades to
-  // defaults rather than taking the plugin down.
+  // Collected now, reported once the tool policy is known so a single pass covers both.
   const issues = validateConfig(config, features)
-  for (const issue of issues) {
-    console.warn(`[overclock] config: ${issue.path ? `${issue.path}: ` : ""}${issue.message}`)
-  }
-  if (issues.length) {
-    void toast(
-      ctx.client,
-      `overclock: ${issues.length} config issue${issues.length > 1 ? "s" : ""} (see logs) -- using defaults for those`,
-      "warning",
-    )
-  }
 
-  const shared: SharedDeps = { busy: createBusyTracker() }
+  // Resolved after the init loop, against the modules that actually loaded -- warning about a
+  // tool belonging to a disabled feature would be noise. Modules only call `toolName` at
+  // runtime (a hook or timer, long after init), so reading it through this binding is safe.
+  let policy: ToolPolicy = EMPTY_POLICY
+  const shared: SharedDeps = {
+    busy: createBusyTracker(),
+    toolName: (declared) => policy.rename[declared] ?? declared,
+  }
   // First part, so the tracker is current before any module's own event hook reads it.
   const parts: Partial<Hooks>[] = [{ event: async ({ event }) => shared.busy.onEvent(event) }]
   const skipped: string[] = []
@@ -57,15 +53,33 @@ export const Overclock: Plugin = async (ctx) => {
     }
   }
 
+  const resolved = resolveToolPolicy(config, enabled)
+  policy = resolved.policy
+  issues.push(...resolved.issues)
+
+  // A mistyped key is otherwise a silent no-op -- the feature runs with defaults and the
+  // user believes their setting took effect. Warn, never throw: bad config degrades to
+  // defaults rather than taking the plugin down.
+  for (const issue of issues) {
+    console.warn(`[overclock] config: ${issue.path ? `${issue.path}: ` : ""}${issue.message}`)
+  }
+  if (issues.length) {
+    void toast(
+      ctx.client,
+      `overclock: ${issues.length} config issue${issues.length > 1 ? "s" : ""} (see logs)`,
+      "warning",
+    )
+  }
+
   // Say what was added. This plugin grants the agent background shell execution and
   // recurring scheduling; that should not be discovered by accident. Log every start
   // (stderr, invisible unless you look), toast only on a project's first run.
-  console.warn(`[overclock] ${summarise(enabled, skipped)}`)
+  console.warn(`[overclock] ${summarise(enabled, skipped, policy)}`)
   if (await firstRun(ctx.directory)) {
-    void toast(ctx.client, `overclock active: ${summarise(enabled, skipped)}`, "info")
+    void toast(ctx.client, `overclock active: ${summarise(enabled, skipped, policy)}`, "info")
   }
 
   if (skipped.length)
     void toast(ctx.client, `overclock: ${skipped.join(", ")} disabled (SDK drift)`, "warning")
-  return mergeHooks(parts)
+  return mergeHooks(parts, policy)
 }

package/src/merge.ts

@@ -1,21 +1,52 @@
 import type { Hooks } from "@opencode-ai/plugin"
+import { EMPTY_POLICY, type ToolPolicy } from "./tools.ts"
+
+/**
+ * Rewrite declared tool names appearing inside a description ("reversible via
+ * checkpoint_restore", "Kill it with task_kill"). Left alone, a remap leaves the model
+ * reading instructions that name a tool it was never offered. Word-anchored so a name
+ * that is a substring of a longer identifier is not clobbered.
+ */
+export function renameInText(text: string, rename: Record<string, string>): string {
+  let out = text
+  for (const [from, to] of Object.entries(rename)) {
+    if (from === to) continue
+    out = out.replace(new RegExp(`\\b${from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "g"), to)
+  }
+  return out
+}
 
 /**
  * Compose many Partial<Hooks> into one Hooks.
  * - fn hooks: call sequentially, module order. Each sees prior mutations of `output`.
  * - `tool` map: shallow merge. Name collision -> later module wins, warn.
+ * - `policy`: declared tool name -> model-visible name, plus tools to withhold. Applied here
+ *   because every module's tool map funnels through this one merge, so one pass covers the
+ *   whole surface and a module never has to know a policy exists.
  */
-export function mergeHooks(parts: Partial<Hooks>[]): Hooks {
+export function mergeHooks(parts: Partial<Hooks>[], policy: ToolPolicy = EMPTY_POLICY): Hooks {
   const merged: Record<string, unknown> = {}
   const tools: Record<string, unknown> = {}
+  const { rename, withheld } = policy
 
   for (const part of parts) {
     for (const [key, value] of Object.entries(part)) {
       if (value === undefined) continue
       if (key === "tool") {
-        for (const [name, def] of Object.entries(value as Record<string, unknown>)) {
+        const renaming = Object.keys(rename).length > 0
+        for (const [declared, def] of Object.entries(value as Record<string, unknown>)) {
+          // Withheld = no allowlist slot. Dropping it here is the point: one unlisted name
+          // makes the gateway reject the whole request, so the rest of the plugin still works.
+          if (withheld.has(declared)) continue
+          const name = rename[declared] ?? declared
           if (tools[name]) console.warn(`[overclock] tool collision: ${name} (later module wins)`)
-          tools[name] = def
+          const d = def as { description?: unknown }
+          // Clone rather than mutate: the module owns its tool objects and may hold the
+          // same reference elsewhere.
+          tools[name] =
+            renaming && typeof d.description === "string"
+              ? { ...d, description: renameInText(d.description, rename) }
+              : def
         }
         continue
       }

package/src/tools.ts

@@ -0,0 +1,244 @@
+import type { ConfigIssue, FeatureModule, OverclockConfig } from "./types.ts"
+
+/**
+ * Tool ids opencode registers itself (observed on 1.18.4 via `/experimental/tool/ids`).
+ *
+ * Only used to warn: a tool registered under one of these *replaces* the built-in in the final
+ * tool map, and a name that differs only by case (`Task` vs `task`) is worse still -- the host
+ * offers both, and a consumer that matches case-insensitively sees a duplicate. Drift in this
+ * list only makes the warning less complete, never wrong.
+ */
+export const HOST_TOOL_IDS: readonly string[] = [
+  "apply_patch",
+  "bash",
+  "edit",
+  "glob",
+  "grep",
+  "invalid",
+  "question",
+  "read",
+  "skill",
+  "task",
+  "todowrite",
+  "webfetch",
+  "websearch",
+  "write",
+]
+
+export interface KnownAllowlist {
+  /** every name the list permits */
+  names: readonly string[]
+  /**
+   * declared tool name -> the name from this list it is offered under. Only for names that
+   * mean the same operation; nothing is invented, so this table stays short.
+   */
+  aliases: Readonly<Record<string, string>>
+  /**
+   * Tools with no honest alias in this list, and why. Recorded rather than left blank so the
+   * absence is a decision someone made, not an oversight -- a test requires every tool to be
+   * in `aliases` or here, and the reason is shown when such a tool gets withheld.
+   */
+  unaliased: Readonly<Record<string, string>>
+}
+
+/**
+ * Named allowlists, usable anywhere a tool name is accepted in `toolAllowlist`.
+ *
+ * `claude-code` is Claude Code's registered tool set. opencode's own ids are snake_case and
+ * disjoint from it, so every name here is free for this plugin to use.
+ *
+ * `aliases` only covers tools where a name in the list denotes the same operation, so nothing
+ * here is a guess: background tasks and cron already exist in this vocabulary. Anything else is
+ * listed in `unaliased` with the reason, because picking an unrelated name on a user's behalf
+ * would mislead the model about what the tool does. Map those yourself with `toolNames`.
+ *
+ * Adding a tool: give it an alias or an `unaliased` reason in the same commit. A test fails
+ * otherwise, so the decision surfaces in CI rather than as a rejected request mid-session.
+ */
+export const KNOWN_ALLOWLISTS: Readonly<Record<string, KnownAllowlist>> = {
+  "claude-code": {
+    names: [
+      "Read",
+      "Write",
+      "Edit",
+      "MultiEdit",
+      "NotebookEdit",
+      "Glob",
+      "Grep",
+      "Bash",
+      "Agent",
+      "Task",
+      "Workflow",
+      "TodoWrite",
+      "TaskCreate",
+      "TaskGet",
+      "TaskList",
+      "TaskUpdate",
+      "TaskStop",
+      "TaskOutput",
+      "TeamCreate",
+      "TeamDelete",
+      "SendMessage",
+      "EnterPlanMode",
+      "ExitPlanMode",
+      "EnterWorktree",
+      "ExitWorktree",
+      "ListMcpResourcesTool",
+      "WaitForMcpServers",
+      "ToolSearch",
+      "Skill",
+      "CronCreate",
+      "CronDelete",
+      "CronList",
+      "ScheduleWakeup",
+      "AskUserQuestion",
+      "StructuredOutput",
+      "ValidationResult",
+      "ReportFindings",
+      "LSP",
+    ],
+    aliases: {
+      task_run: "TaskCreate",
+      task_status: "TaskList",
+      task_output: "TaskOutput",
+      task_kill: "TaskStop",
+      schedule_create: "CronCreate",
+      schedule_list: "CronList",
+      schedule_delete: "CronDelete",
+    },
+    unaliased: {
+      bash_unsandboxed: "the only fitting name is `Bash`, which is also an opencode built-in",
+      checkpoint_list: "no name in this list denotes session checkpoints",
+      checkpoint_revert: "no name in this list denotes session checkpoints",
+      checkpoint_restore: "no name in this list denotes session checkpoints",
+      usage_report: "no name in this list denotes cost/token telemetry",
+    },
+  },
+}
+
+export interface ToolPolicy {
+  /** declared name -> model-visible name */
+  rename: Record<string, string>
+  /** declared names withheld from the model entirely (no allowed name to use) */
+  withheld: Set<string>
+}
+
+export const EMPTY_POLICY: ToolPolicy = { rename: {}, withheld: new Set() }
+
+/** Entries like "claude-code" name a bundled list; a literal tool id would not look like this. */
+function looksLikeListName(entry: string): boolean {
+  return /^[a-z0-9]+(-[a-z0-9]+)+$/.test(entry)
+}
+
+/**
+ * Expand `toolAllowlist` into the names it permits plus the aliases any named list brings.
+ * Entries are either a known list name or a literal tool name, so extending a bundled list is
+ * `["claude-code", "MyExtraTool"]` -- no separate key, no re-listing what the bundle covers.
+ */
+export function resolveAllowlist(value: unknown): {
+  names?: string[]
+  aliases: Record<string, string>
+  /** declared tool -> why no bundled list offered a name for it */
+  unaliased: Record<string, string>
+  issues: ConfigIssue[]
+} {
+  const aliases: Record<string, string> = {}
+  const unaliased: Record<string, string> = {}
+  if (value === undefined) return { aliases, unaliased, issues: [] }
+
+  const entries = typeof value === "string" ? [value] : value
+  if (!Array.isArray(entries) || !entries.every((v) => typeof v === "string")) {
+    return {
+      aliases,
+      unaliased,
+      issues: [
+        {
+          path: "toolAllowlist",
+          message: `must be a name or an array of names (a known list is ${Object.keys(KNOWN_ALLOWLISTS).join(", ")}), got ${Array.isArray(value) ? "array with non-strings" : typeof value}`,
+        },
+      ],
+    }
+  }
+
+  const names: string[] = []
+  const issues: ConfigIssue[] = []
+  for (const entry of entries as string[]) {
+    const known = KNOWN_ALLOWLISTS[entry]
+    if (known) {
+      names.push(...known.names)
+      Object.assign(aliases, known.aliases)
+      Object.assign(unaliased, known.unaliased)
+      continue
+    }
+    // A typo'd list name would otherwise pass as a literal tool name, withhold everything, and
+    // suggest the typo itself as a free name. Cheap to catch, confusing to debug.
+    if (looksLikeListName(entry)) {
+      issues.push({
+        path: "toolAllowlist",
+        message: `"${entry}" looks like a known list but is not one (known: ${Object.keys(KNOWN_ALLOWLISTS).join(", ")}) -- treating it as a literal tool name`,
+      })
+    }
+    names.push(entry)
+  }
+  return { names, aliases, unaliased, issues }
+}
+
+/**
+ * Fold the allowlist's aliases + explicit renames into one policy, and report what a human
+ * needs to act on. Every check here exists because the failure it catches is otherwise
+ * invisible until a request comes back rejected:
+ * - a tool with no permitted name is withheld, and the still-free names are listed so picking
+ *   one is a single config line;
+ * - a name that collides with a host built-in (or its case-twin) is called out, since that
+ *   replaces the built-in or reads as a duplicate.
+ */
+export function resolveToolPolicy(
+  config: Pick<OverclockConfig, "toolNames" | "toolAllowlist">,
+  features: readonly FeatureModule[],
+): { policy: ToolPolicy; issues: ConfigIssue[] } {
+  const { names: allowlist, aliases, unaliased, issues } = resolveAllowlist(config.toolAllowlist)
+
+  // Explicit names win: a bundled list is a starting point, not a straitjacket.
+  const rename: Record<string, string> = { ...aliases, ...(config.toolNames ?? {}) }
+
+  const final = new Map<string, string>() // declared -> model-visible
+  for (const name of features.flatMap((f) => f.tools ?? [])) {
+    final.set(name, rename[name] ?? name)
+  }
+
+  for (const [name, visible] of final) {
+    const twin = HOST_TOOL_IDS.find((id) => id.toLowerCase() === visible.toLowerCase())
+    if (!twin) continue
+    issues.push({
+      path: `tool "${name}"`,
+      message:
+        twin === visible
+          ? `"${visible}" is an opencode built-in -- registering it replaces that built-in`
+          : `"${visible}" differs from opencode's built-in "${twin}" only by case; anything matching case-insensitively sees one name twice`,
+    })
+  }
+
+  const withheld = new Set<string>()
+  if (allowlist) {
+    const allowed = new Set(allowlist)
+    const taken = new Set([...final.values()].filter((v) => allowed.has(v)))
+    const builtin = new Set(HOST_TOOL_IDS.map((id) => id.toLowerCase()))
+    // Suggesting a name that would immediately earn a built-in collision warning is worse than
+    // suggesting nothing, so case-twins of opencode's own ids are not offered.
+    const free = allowlist.filter((n) => !taken.has(n) && !builtin.has(n.toLowerCase()))
+    for (const [name, visible] of final) {
+      if (allowed.has(visible)) continue
+      withheld.add(name)
+      const why = unaliased[name] ? ` (${unaliased[name]})` : ""
+      issues.push({
+        path: `tool "${name}"`,
+        message:
+          `"${visible}" is not in toolAllowlist${why} -- withheld from the model. ` +
+          `Pick a name for it via toolNames (free: ${free.slice(0, 4).join(", ") || "none left"}), ` +
+          `or add one to toolAllowlist`,
+      })
+    }
+  }
+
+  return { policy: { rename, withheld }, issues }
+}

package/src/types.ts

@@ -9,16 +9,50 @@ import type { BusyTracker } from "./lib/busy.ts"
 export interface SharedDeps {
   /** live per-session busy/idle state; the entry owns the subscription that feeds it */
   busy: BusyTracker
+  /**
+   * Declared tool name -> the name the model was actually offered (see `toolNames` config).
+   * Needed wherever a module names one of its own tools in text the model reads: under a
+   * remap the declared name is not a tool the model has.
+   */
+  toolName(declared: string): string
 }
 
 /** Per-feature config from .opencode/overclock.json. `false` = off, object = options. */
 export type FeatureConfig = boolean | Record<string, unknown>
 
+/** A problem found in overclock.json. Lives here so config consumers need not import validate. */
+export interface ConfigIssue {
+  /** dotted location in overclock.json, e.g. "features.tasks.killOnExit" */
+  path: string
+  message: string
+}
+
 /** Option value kinds a module declares, so a typo in overclock.json can be caught. */
 export type OptionType = "boolean" | "number" | "string" | "array" | "object"
 
 export interface OverclockConfig {
   features?: Record<string, FeatureConfig>
+  /**
+   * Model-visible tool ids: declared name -> replacement. The key of the `tool` hook map is
+   * literally the name sent to the provider, so this is the whole remap. Exists for hosts
+   * behind a proxy that whitelists tool names and rejects unknown ones.
+   *
+   * A replacement that collides with a built-in tool *overrides* that built-in in the final
+   * tool map -- borrow a name you do not mind losing. Permission ids are deliberately not
+   * remapped: they key the user's opencode permission config, not the wire format.
+   */
+  toolNames?: Record<string, string>
+  /**
+   * The only tool names the model may be offered. Entries are literal names or the name of a
+   * bundled list (see KNOWN_ALLOWLISTS), so extending one is `["claude-code", "MyExtraTool"]`.
+   * A bundled list also supplies default aliases for this plugin's tools; `toolNames` overrides
+   * those per tool.
+   *
+   * Any tool whose final name is not permitted is withheld from the model rather than offered
+   * and rejected -- a single unrecognised name can fail a whole request, so a loud gap at
+   * startup beats a session that cannot reach the provider.
+   */
+  toolAllowlist?: string[] | string
 }
 
 /**

package/src/validate.ts

@@ -1,10 +1,7 @@
-import type { FeatureModule, OptionType } from "./types.ts"
+import type { ConfigIssue, FeatureModule, OptionType } from "./types.ts"
+import type { ToolPolicy } from "./tools.ts"
 
-export interface ConfigIssue {
-  /** dotted location in overclock.json, e.g. "features.tasks.killOnExit" */
-  path: string
-  message: string
-}
+export type { ConfigIssue }
 
 /** Levenshtein, capped -- only used to turn a typo into a "did you mean". */
 function distance(a: string, b: string): number {
@@ -52,6 +49,48 @@ function isPlainObject(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null && !Array.isArray(v)
 }
 
+/**
+ * Check the `toolNames` remap. A rename that silently does nothing is the worst outcome
+ * here: the proxy keeps rejecting the tool and the config looks correct. So an unknown
+ * source name is an issue, and two sources aiming at one target is an issue -- the merge
+ * would keep only the last.
+ */
+function validateToolNames(toolNames: unknown, features: readonly FeatureModule[]): ConfigIssue[] {
+  if (toolNames === undefined) return []
+  if (!isPlainObject(toolNames)) {
+    return [{ path: "toolNames", message: `"toolNames" must be an object, got ${typeOf(toolNames)}` }]
+  }
+
+  const issues: ConfigIssue[] = []
+  const declared = features.flatMap((f) => f.tools ?? [])
+  const targets = new Map<string, string>()
+
+  for (const [from, to] of Object.entries(toolNames)) {
+    if (!declared.includes(from)) {
+      issues.push({ path: `toolNames.${from}`, message: unknownKey(from, declared, "tool") })
+      continue
+    }
+    if (typeof to !== "string" || to.trim() === "") {
+      issues.push({
+        path: `toolNames.${from}`,
+        message: `must be a non-empty string, got ${typeOf(to)}`,
+      })
+      continue
+    }
+    const prior = targets.get(to)
+    if (prior) {
+      issues.push({
+        path: `toolNames.${from}`,
+        message: `"${to}" is already the target of "${prior}" -- only one would survive the merge`,
+      })
+      continue
+    }
+    targets.set(to, from)
+  }
+
+  return issues
+}
+
 /**
  * Check overclock.json against the feature registry.
  *
@@ -66,11 +105,13 @@ export function validateConfig(config: unknown, features: readonly FeatureModule
     return [{ path: "", message: `config must be an object, got ${typeOf(config)}` }]
   }
 
-  const TOP = ["features"]
+  const TOP = ["features", "toolNames", "toolAllowlist"]
   for (const key of Object.keys(config)) {
     if (!TOP.includes(key)) issues.push({ path: key, message: unknownKey(key, TOP, "top-level key") })
   }
 
+  issues.push(...validateToolNames(config.toolNames, features))
+
   const { features: featuresCfg } = config
   if (featuresCfg === undefined) return issues
   if (!isPlainObject(featuresCfg)) {
@@ -130,14 +171,27 @@ export function validateConfig(config: unknown, features: readonly FeatureModule
  * capability: installing overclock hands the agent background shell execution and
  * recurring scheduling, and that should not be something a user discovers by accident.
  */
-export function summarise(enabled: readonly FeatureModule[], skipped: readonly string[]): string {
-  const toolCount = enabled.reduce((n, f) => n + (f.tools?.length ?? 0), 0)
+export function summarise(
+  enabled: readonly FeatureModule[],
+  skipped: readonly string[],
+  policy: ToolPolicy = { rename: {}, withheld: new Set() },
+): string {
+  const { rename, withheld } = policy
+  const offered = enabled.flatMap((f) => (f.tools ?? []).filter((t) => !withheld.has(t)))
+  // Report the name the model is actually offered, not the declared one -- under a remap the
+  // declared name appears nowhere on the wire, so listing it would misdescribe the session.
   const parts = enabled.map((f) => {
-    const tools = f.tools?.length ? ` (${f.tools.join(", ")})` : ""
-    return `${f.name}${tools}`
+    const names = (f.tools ?? []).filter((t) => !withheld.has(t)).map((t) => rename[t] ?? t)
+    return `${f.name}${names.length ? ` (${names.join(", ")})` : ""}`
   })
   const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`
-  let line = `${plural(enabled.length, "module")}, ${plural(toolCount, "tool")}: ${parts.join(" · ")}`
+  let line = `${plural(enabled.length, "module")}, ${plural(offered.length, "tool")}: ${parts.join(" · ")}`
+  const applied = offered.filter((t) => rename[t] && rename[t] !== t).map((t) => `${t}->${rename[t]}`)
+  if (applied.length) line += ` | renamed: ${applied.join(", ")}`
+  // Withheld tools are the one case where the session is quietly less capable than the config
+  // implies, so they are named here rather than left to the issue log alone.
+  const held = enabled.flatMap((f) => (f.tools ?? []).filter((t) => withheld.has(t)))
+  if (held.length) line += ` | withheld: ${held.join(", ")}`
   if (skipped.length) line += ` | skipped: ${skipped.join(", ")}`
   return line
 }