feat(git-guards): add GraphQL command guidance for known failure patterns

[JacobPEvans]

Summary

• Adds allow-with-guidance detection to git-permission-guard.py for gh api graphql commands matching known failure patterns
• When triggered, allows the command to proceed (it fails naturally) and injects corrective guidance via permissionDecisionReason for immediate self-correction
• Detects 4 failure patterns based on log analysis of 1,400+ failures across 8 distinct error types

Failure patterns covered

Pattern	Occurrences	Guidance shown
Shell $variable expansion in queries	125x	Use --raw-field with inline values
addPullRequestReviewComment (wrong mutation)	711x	Use addPullRequestReviewThreadReply + example
resolvePullRequestReviewThread (wrong mutation)	162x	Use resolveReviewThread + example
-f/-F query= flags (Go template processing)	pervasive	Use --raw-field instead
Multi-line queries (trailing \, literal \n)	108x	Collapse to single line

Implementation

Uses the permissionDecision: "allow" + permissionDecisionReason pattern (already used in webfetch-guard.py). Multiple warnings are collected and shown together when a command has multiple issues.

Only triggers for gh api graphql commands — all other commands are completely unaffected.

Test plan

• Shell var + -f flag → allow + 2 warnings
• Wrong mutation addPullRequestReviewComment → allow + mutation guidance
• Wrong mutation resolvePullRequestReviewThread → allow + mutation guidance
• Correct mutation resolveReviewThread → silent allow (no false positive)
• gh pr list → silent allow (unaffected)
• Combined 3-pattern command → allow + 3 warnings
• --jq '$var' → silent allow (no false positive on jq content)
• Multi-line trailing backslash → allow + multi-line warning

All 8 test cases pass via git-guards/scripts/test_graphql_guidance.py.

🤖 Generated with Claude Code

---

Important

Adds guidance for known failure patterns in gh api graphql commands in git-permission-guard.py, allowing commands to proceed with corrective advice.

• Behavior:
  • Adds allow_with_guidance detection in git-permission-guard.py for gh api graphql commands with known failure patterns.
  • Provides corrective guidance via permissionDecisionReason for self-correction.
  • Detects 4 failure patterns: shell $variable expansion, wrong mutation names, -f/-F flags, and multi-line queries.
• Implementation:
  • Uses permissionDecision: "allow" + permissionDecisionReason pattern.
  • Only affects gh api graphql commands; other commands are unaffected.
• Testing:
  • New test script test_graphql_guidance.py with 8 test cases, all passing.

^{This description was created by for 232eee3. You can customize this summary. It will automatically update as commits are pushed.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 232eee3 in 10 seconds. Click for details.

• Reviewed 250 lines of code in 2 files
• Skipped 0 files when reviewing.
• Skipped posting 0 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

Workflow ID: wflow_OfC604WQaS8B6jgE

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[gemini-code-assist]

Summary of Changes

Hello @JacobPEvans, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the git-permission-guard.py script by adding GraphQL command guidance for known failure patterns. It improves the user experience by providing immediate, actionable feedback when common mistakes are made in gh api graphql commands, helping users to self-correct and avoid errors. The changes are focused on improving the usability of the gh api graphql command without affecting other commands.

Highlights

• GraphQL Guidance: This PR introduces a new feature to git-permission-guard.py that detects common failure patterns in gh api graphql commands and provides corrective guidance.
• Failure Pattern Detection: The script identifies four failure patterns, including shell variable expansion, incorrect mutation names, misuse of -f/-F query= flags, and multi-line queries.
• Corrective Guidance: When a failure pattern is detected, the command is allowed to proceed (failing naturally), but guidance is injected via permissionDecisionReason to help users self-correct.
• Testing: Comprehensive tests were added to verify the detection and guidance for each failure pattern, ensuring no false positives.

Changelog

• git-guards/scripts/git-permission-guard.py
  • Added detection and guidance for common GraphQL failure patterns.
  • Implemented allow_with_guidance function to allow commands with corrective warnings.
  • Added _strip_jq_content function to avoid false positives with jq content.
  • Integrated check_graphql_guidance into the main function to provide real-time feedback.
• git-guards/scripts/test_graphql_guidance.py
  • Created a new test script to verify GraphQL guidance detection.
  • Implemented tests for shell variable expansion, wrong mutation names, incorrect flags, and multi-line queries.
  • Ensured no false positives are triggered by correct commands or jq content.

Activity

• Added a new feature to detect and provide guidance for common GraphQL failure patterns in gh api graphql commands.
• Implemented tests to ensure the accuracy and effectiveness of the new feature.
• Addressed feedback from reviewers and made necessary adjustments to the code.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a helpful guidance mechanism for common gh api graphql errors. The implementation is solid, with new functions that are well-defined and specific. The addition of a comprehensive test suite is particularly commendable, as it covers all the new detection patterns, including edge cases and false positives. I have one suggestion to make the detection of incorrect mutation names more robust and avoid potential false positives.

[Copilot]

Pull request overview

This pull request adds proactive GraphQL command guidance to the git-permission-guard.py hook. When Claude attempts to run a gh api graphql command with known failure patterns, the guard allows the command to proceed (so it fails naturally with GitHub's error message) but simultaneously injects corrective guidance for immediate self-correction. This is based on analysis of over 1,400 actual failures across 8 distinct error types.

Changes:

• Adds allow_with_guidance() function to emit warnings while allowing commands
• Implements check_graphql_guidance() to detect 4 common GraphQL failure patterns
• Adds comprehensive test suite with 8 test cases covering all patterns and edge cases

Reviewed changes

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

File	Description
git-guards/scripts/git-permission-guard.py	Adds GraphQL guidance detection with 4 pattern checks (shell variables, wrong mutations, wrong flags, multi-line queries) and allow_with_guidance mechanism
git-guards/scripts/test_graphql_guidance.py	New test suite with 8 test cases validating detection patterns, false positive prevention, and combined pattern handling

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.