Plugin hooks: support a per-hook name/description and show it in the hook-trust UI (currently opaque 'Hook 1..N')

Open 💬 1 comment Opened Jul 7, 2026 by markdbodman

Summary

When a plugin bundles multiple hooks via hooks.json, the Codex hook-management / trust UI lists them as an opaque numbered list — "Hook 1", "Hook 2", … — with no name or description. An operator granting hook trust must approve code execution for entries they cannot identify.

Why this matters (trust UX / security)

Hook trust is a code-execution grant. Presenting it as unnamed "Hook N" rows means the operator approves blind — they cannot tell a benign formatter from something invasive. A per-hook name + one-line description would let them make an informed trust decision, which is the whole point of the trust gate.

Current behavior

  • Hook objects in hooks.json accept { "type": "command", "command": "…", "timeout": N } — there is no name / label / description field. (Confirmed against the bundled example plugins figma and replayio, whose hook objects are {type, command} only.)
  • The Extensions → Hooks list, and the trust prompt, render each entry as Hook <n>.

Requested

  1. Accept an optional name (and ideally description) field on a hook object in hooks.json.
  2. Render that name/description in the hook list and in the trust prompt, so operators approve named, described hooks rather than Hook N.
  3. Fall back to the current positional label when absent (back-compat; no change for existing plugins).

Example

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "name": "lease-punt-guard",
            "description": "Blocks a runtime-bound gate in a source-only checkout",
            "type": "command",
            "command": "node hooks/lease-punt-guard.mjs"
          }
        ]
      }
    ]
  }
}

Context

We ship a set of governance PreToolUse guards as a plugin across Claude Code / Codex / Grok. On Codex they load and function correctly, but at trust-grant time the operator is shown ~8 anonymous "Hook N" rows and has to approve execution without knowing what each does. The same request is being filed on the Grok/xAI plugin side. Thanks for considering it.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗