claude-code - 💡(How to fix) Fix `matcher: "PowerShell"` works but is not documented as a supported value on tool events

Summary

The Claude Code hooks reference (https://code.claude.com/docs/en/hooks) does not list "PowerShell" as a supported value for matcher on tool events (PreToolUse, PostToolUse, etc.), yet it works in practice and Windows-side plugins rely on it. This creates a stability risk: an undocumented value plugin authors depend on could be removed or renamed without notice.

What is documented today

For tool-event matchers (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied), the docs show matcher syntax with these examples:

• "Bash" (literal tool name)
• "Edit|Write" (pipe-separated list)
• "mcp__.*" (regex for MCP tool families)

"PowerShell" does not appear anywhere on the hooks reference page as a matcher value.

The asymmetry

PowerShell is documented on the same page in two adjacent contexts:

Documenting PowerShell as a permission-rule tool name and as a shell value, but not as an event matcher, leaves Windows plugin authors without an officially supported way to register a hook that fires specifically on PowerShell tool calls.

Minimal config

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "PowerShell",
        "hooks": [
          { "type": "command", "command": "py /path/to/dispatcher.py" }
        ]
      }
    ]
  }
}

This works empirically — the hook fires on PowerShell tool invocations on Windows — but the matcher value is not documented.

Why this matters

Cross-platform Claude Code plugins that target Windows users need a stable, documented way to filter hooks on PowerShell tool calls. The same plugin typically registers two matcher entries (one for Bash, one for PowerShell) so the hook fires regardless of which shell tool Claude chooses on a given platform. Relying on an undocumented matcher value means a future doc-driven schema cleanup could remove or rename it without warning, silently breaking installed plugins on Windows.

Distinct from #57137

Issue #57137 covers if: "PowerShell(<specific>)" silently never matching. This issue is about the matcher value at the entry level, not the if filter form, and is independent of #57137.

Asks

Either:

1. Document "PowerShell" as a supported matcher value on the hooks reference page (alongside Bash, Edit|Write, etc.), and confirm the canonical list of tool names valid as matchers.
2. Or specify the supported alternative for registering a hook that fires only on PowerShell tool calls, and migrate the schema if "PowerShell" is going to be retired.

Either resolution would let plugin authors target Windows users with confidence.

Environment

• Claude Code: 2.1.132
• OS: Windows 11 (build 10.0.22631)