Plugin hook "permission.ask" is dead code — declared (and still taught by the bundled customize-opencode skill) but never invoked since v1.3.0

[NoahBPeterson]

Description

The permission.ask plugin hook is still declared in the public Hooks type, but it has not been invoked anywhere since v1.3.0 (removed March 2026). Plugins that register it load cleanly, typecheck, and silently never fire — nothing warns, nothing errors.

This is not hypothetical: we had a sound-notification plugin that registered permission.ask to chime on permission prompts. After upgrading it became a silent no-op, and an agent sat waiting on a permission prompt unnoticed for an hour.

Evidence

The hook is declared, never called:

• Declared at packages/plugin/src/index.ts (line 261, dev):

  "permission.ask"?: (input: Permission, output: { status: "ask" | "deny" | "allow" }) => Promise<void>

• rg '"permission\.ask"' across packages/ at both v1.18.29 and dev shows zero call sites — only the declaration.

It used to work:

• At v1.1.53, packages/opencode/src/permission/index.ts called:

  await Plugin.trigger("permission.ask", info, { status: "ask" })

Removal history (between v1.1.53 and v1.3.0):

1. f015154314 — refactor(permission): effectify PermissionNext (refactor(permission): effectify PermissionNext + fix InstanceState ALS bug #17511, 2026-03-14): last version containing the trigger
2. 2fc06c5a17 — chore(permission): delete legacy permission module (chore(permission): delete legacy permission module #17534, 2026-03-15): module deleted
3. v1.3.0 — first release without the invocation

Stale references that keep plugin authors writing dead handlers:

• The type declaration itself (shows up in editor autocomplete for plugin authors)
• The bundled customize-opencode skill still lists it as a live hook: packages/core/src/plugin/skill/customize-opencode.md (line 354, dev)

  - `permission.ask`
  

  (Agents following that skill will keep generating plugins around this hook.)

Repro

1. Create a plugin: ~/.config/opencode/plugin/x.ts

   import type { Plugin } from "@opencode-ai/plugin"
   export default (async () => {
     return {
       "permission.ask": async (input, output) => {
         console.log("NEVER FIRES")
       },
     }
   }) satisfies Plugin

2. Run any command that triggers a permission prompt (e.g. bash set to ask).
3. The handler is never invoked. Meanwhile the bus event permission.asked fires normally (same flow the TUI renders).

Expected

Either:

• Remove "permission.ask" from the Hooks type (and from the bundled customize-opencode skill), so plugin authors aren't led into a silent no-op, or
• Re-wire the hook if it's still intended as an interception point.

Either way, the skill should point plugin authors at the replacement: reacting to the permission.asked bus event via the event hook.

Environment

• opencode v1.18.29 (verified broken; broken since v1.3.0)
• macOS (darwin)

[github-actions]

This issue might be a duplicate of an existing issue. Please check:

• permission.ask plugin hook is defined but not triggered #7006: permission.ask plugin hook is defined but not triggered — describes the same root cause (hook declared but never invoked by the permission system), with a suggested fix for wiring it up.

If your issue is specifically about the stale documentation in the bundled customize-opencode skill (which keeps teaching plugin authors to use this dead hook), that aspect may not be fully covered by #7006 and could warrant keeping this open or splitting it off.