Skip to content

v2.0.4 — harden permissionDecision guidance in hooks-management

Choose a tag to compare

View all tags
@rodion-m rodion-m released this 20 Apr 11:44
· 207 commits to main since this release
v2.0.4
e7fb0b3

hooks-management: permissionDecision guidance that agents can't miss on first read

Follow-up to v2.0.3: agents were still reaching for exit 2 or inventing their own confirmation schemes (env-var flags, osascript dialogs, bypass tokens) because the JSON decision control lived near the bottom of the SKILL.md and was only briefly mentioned elsewhere.

What changed

  • Decision Control section moved up — now appears immediately after Common Patterns, before Codex / Validation, so it reads during a top-to-bottom pass.
  • Quick Reference explicitly names JSON decision control as the default mechanism for PreToolUse and calls out anti-patterns to avoid.
  • Script template for PreToolUse rewritten — JSON ask / deny are the primary path; exit 2 is positioned as a fallback for simple blocking only.
  • "User Says" translation table gained three rows: "require manual approval", "ask before dangerous", "block unless confirmed" — all pointing to permissionDecision: "ask".
  • New gotcha documented: "ask" is silently bypassed when permissions.allow already matches the tool. Symptom = hook appears to do nothing; fix = narrow the allow rule.

Why

Agents invoking this skill kept falling into two traps: (1) using exit 2 when the intent was "ask the user", producing a UX worse than the native confirm prompt, and (2) reinventing confirmation with home-grown env vars or osascript dialogs that don't integrate with Claude Code's permission system. The fixes above put the right pattern on the first page the agent reads.

No behaviour changes in scripts, validators, or any other skill. Docs-only.

Assets 2
Loading