Document matcher support for command hooks

[torumakabe]

Describe the feature or problem you'd like to solve

The hooks reference does not clearly document matcher support for flat command hooks.

Proposed solution

This makes it hard to use matcher for common cases like running a postToolUse formatter/linter only after file-edit tools. The Copilot CLI v1.0.63 changelog mentions that PostToolUse matchers are honored, and also mentions preToolUse.matcher, but the reference does not make the supported events or matching semantics clear.

Could the docs clarify:

• Which hook events support matcher on flat command hook entries
• Whether this includes preToolUse, postToolUse, and postToolUseFailure
• For camelCase hooks, whether matcher is matched against runtime toolName
• Whether matching is case-sensitive and full-match/anchored regex
• How this differs from PascalCase / Claude-format matchers such as Edit|Write

A small example for an edit-only postToolUse hook would be enough, e.g. whether this is the intended form:

{
  "version": 1,
  "hooks": {
    "postToolUse": [
      {
        "type": "command",
        "matcher": "^(?:edit|create|apply_patch)$",
        "bash": "uv run .github/hooks/scripts/post-edit-quality-feedback.py",
        "powershell": "uv run .github/hooks/scripts/post-edit-quality-feedback.py",
        "timeoutSec": 60
      }
    ]
  }
}

It would also help to point to the relevant built-in runtime tool names and argument shapes used by hook payloads. The hooks reference includes a runtime-to-Claude tool name table under PascalCase PreToolUse, but it is not obvious whether that table should be used for camelCase hook matchers.

Related issues I found:

• Documentation unclear: how to map toolName (glob/grep/view) to --allow-tool patterns #1482 — toolName / permission pattern mapping is unclear
• Document safe parsing for preToolUse.toolArgs when it is a JSON-encoded string #3349 — safe parsing for preToolUse.toolArgs

This issue is specifically about documenting command hook matcher support and semantics. The feature is useful for reducing unnecessary hook executions and simplifying hook scripts, but it is currently hard to rely on from the docs alone.

Example prompts or workflows

No response

Additional context

No response

[examon]

It looks like this was addressed in v1.0.63. The hooks reference now documents matcher support for command hooks, including which events accept it (such as postToolUse), that matching is case-sensitive and anchored as ^(?:pattern)$ against the runtime toolName, how this differs from the Claude-format Edit|Write matchers, and an edit-focused postToolUse example. If you believe this isn't resolved, please comment with details and we'll take another look.

[torumakabe]

@examon Thanks for taking a look. I may be missing something, but I still don't see postToolUse documented as accepting matcher in the public hooks reference:

https://docs.github.com/en/copilot/reference/hooks-reference#matcher-filtering

That section lists notification, permissionRequest, preCompact, preToolUse, and subagentStart, but not postToolUse or postToolUseFailure.

I also don't see the edit-focused postToolUse example mentioned in your comment. Could you point me to the exact section that documents postToolUse.matcher, or reopen this if the docs update has not landed publicly yet?