Skip to content

feat: add hooks authoring instruction 🤖🤖🤖#1507

Open
yeelam-gordon wants to merge 5 commits intogithub:stagedfrom
yeelam-gordon:hooks-instruction-guide
Open

feat: add hooks authoring instruction 🤖🤖🤖#1507
yeelam-gordon wants to merge 5 commits intogithub:stagedfrom
yeelam-gordon:hooks-instruction-guide

Conversation

@yeelam-gordon
Copy link
Copy Markdown
Contributor

@yeelam-gordon yeelam-gordon commented Apr 25, 2026

Summary

Add \instructions/hooks.instructions.md\ — a portable, deeply researched guide for writing GitHub Copilot hooks correctly.

What it covers

  • Folder structure and config schema with all field documentation
  • Script contract: stdin JSON, exit codes, stdout/stderr channel semantics
  • Payload schemas for all common events (sessionStart, sessionEnd, userPromptSubmitted, preToolUse, postToolUse, errorOccurred, agentStop)
  • Per-event deny mechanisms: structured JSON deny for preToolUse, non-zero exit for others
  • Matcher support for host-level tool-name filtering
  • Three impactful examples: commit gate (self-correcting feedback loop), auto-format after edits, dangerous command blocker
  • Bash and PowerShell templates for reading stdin and emitting deny JSON
  • Cross-platform guidance (Python through both bash/powershell entries)
  • Anti-patterns, design rules, and portability notes (GitHub Copilot vs Claude Code)

How it was built

  • Multi-agent research across official GitHub docs, repo samples, and Claude Code docs
  • Local E2E testing of hook behavior (stdin/env separation, structured deny, matcher filtering)
  • 3 rounds of 10-agent scenario testing — each agent created a real hook from the instruction and reported gaps
  • Round 1: found 4 critical gaps (missing payload schemas, no PowerShell examples, toolArgs double-parse unclear, no external refs)
  • Round 2: fixed all gaps, 9/10 high confidence
  • Round 3: 10/10 high confidence, zero gaps — converged

Checklist

  • Targets \staged\ branch
  • Ran
    pm start\ to update generated README
  • File follows naming convention (\hooks.instructions.md)
  • Tested with representative scenarios

@yeelam-gordon
feat: add hooks authoring instruction
7d84319 
Add hooks.instructions.md with portable guidance for writing GitHub Copilot hooks:
- Folder structure, config schema, and all field documentation
- Script contract: stdin JSON, exit codes, stdout/stderr channels
- Payload schemas for all common events (sessionStart, sessionEnd, userPromptSubmitted, preToolUse, postToolUse, errorOccurred, agentStop)
- Per-event deny mechanisms (structured JSON for preToolUse, non-zero exit for others)
- Matcher support for host-level tool filtering
- Three impactful examples: commit gate, auto-format, dangerous command blocker
- Bash and PowerShell templates
- Cross-platform guidance (Python through both entries)
- Anti-patterns, design rules, and portability notes (GitHub Copilot vs Claude Code)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings April 25, 2026 22:48
Copilot AI reviewed Apr 25, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new instruction document intended to guide authors in writing GitHub Copilot hooks, and registers it in the instructions index so it’s discoverable alongside other instruction files.

Changes:

  • Added instructions/hooks.instructions.md with hook configuration guidance, script I/O contract, event payload examples, and sample hook patterns.
  • Updated docs/README.instructions.md to include the new “Hook Authoring Guidelines” entry and install links.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File Description
instructions/hooks.instructions.md New, comprehensive hook authoring guide (config schema, event behaviors, payloads, examples).
docs/README.instructions.md Adds the new instruction to the published instructions catalog.

Comment thread instructions/hooks.instructions.md Outdated
Comment thread instructions/hooks.instructions.md
Comment thread instructions/hooks.instructions.md Outdated
Comment thread instructions/hooks.instructions.md Outdated
@yeelam-gordon
fix: address PR review comments
7a1b62f 
- Document both toolArgs (JSON string) and tool_input/toolInput (object) variants with defensive parsing
- Update sessionStart stdout to reflect additionalContext injection support
- Document preToolUse stdout output fields: modifiedArgs/updatedInput, additionalContext
- Add matcher field note about local verification
- Remove undocumented notification event from event table

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@yeelam-gordon
Copy link
Copy Markdown
Contributor Author

yeelam-gordon commented Apr 25, 2026

Addressed all 4 review comments:

  1. toolArgs vs toolInput: Now documents both variants with defensive parsing examples in Bash and PowerShell
  2. matcher citation: Added note that it was locally verified in Copilot CLI v1.0.36 but not yet in repo samples
  3. sessionStart stdout: Updated table to show additionalContext injection support; added stdout output schema
  4. notification event: Removed from the event table

Also documented preToolUse stdout output fields (modifiedArgs/updatedInput, additionalContext) from the Learning Hub docs.

Requesting re-review.

kukuguzka
kukuguzka suggested changes Apr 25, 2026
View reviewed changes
Copy link
Copy Markdown

@kukuguzka kukuguzka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2a6b71346eb1b00d229447a719959d8f2cc43499

@yeelam-gordon yeelam-gordon requested a review from Copilot April 26, 2026 09:14
Copilot AI reviewed Apr 26, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

Comment thread instructions/hooks.instructions.md
Comment thread instructions/hooks.instructions.md Outdated
Comment thread instructions/hooks.instructions.md Outdated
Comment thread instructions/hooks.instructions.md Outdated
Comment thread instructions/hooks.instructions.md Outdated
@yeelam-gordon
fix: address round 2 review comments
414cd09 
- Defensive toolArgs parsing in all 3 example scripts (handle toolArgs string, tool_input, toolInput)
- PowerShell type check: test -is [string] before ConvertFrom-Json, init to null
- commit-gate.sh: add package.json existence guard before jq
- block-dangerous.sh: truncate command in deny reason and stderr to avoid leaking secrets
- Consistent defensive parsing helper across all Bash examples

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@yeelam-gordon yeelam-gordon requested a review from Copilot April 26, 2026 09:37
@yeelam-gordon
Copy link
Copy Markdown
Contributor Author

yeelam-gordon commented Apr 26, 2026

2a6b71346eb1b00d229447a719959d8f2cc43499

@kukuguzka, what is this stand for?

Copilot AI reviewed Apr 26, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

Comment thread instructions/hooks.instructions.md Outdated
Comment thread instructions/hooks.instructions.md Outdated
Comment thread instructions/hooks.instructions.md Outdated
Comment thread instructions/hooks.instructions.md
yeelam-gordon and others added 2 commits April 26, 2026 17:45
@yeelam-gordon
fix: handle toolArgs as string or object in jq, fix short_cmd scoping
744e3d5 
- All 3 Bash example jq blocks now check toolArgs type before fromjson
- short_cmd defined before the deny/log branch to avoid set -u error
- Consistent defensive pattern across commit-gate, format-on-save, block-dangerous

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@yeelam-gordon
Merge branch 'staged' into hooks-instruction-guide
a0f7445
@yeelam-gordon
Copy link
Copy Markdown
Contributor Author

yeelam-gordon commented Apr 28, 2026

@aaronpowell, it is super strange we don't have hook's instruction.
I tried to use it to build my hook already, overall looks good.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@aaronpowell aaronpowell Awaiting requested review from aaronpowell aaronpowell is a code owner

+1 more reviewer

@kukuguzka kukuguzka kukuguzka requested changes

Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@yeelam-gordon @kukuguzka