docs(policy-engine): link to tools reference for tool names and args

[Aaxhirrr]

Summary

Update the Policy Engine docs to reference the Tools Reference page for valid tool names and argument structures, instead of duplicating a tool list in the policy page.

Details

• Added a link in Tool Name to the Tools Reference (./tools.md#available-tools) for valid toolName values.
• Added a link in Arguments pattern to the same Tools Reference section so users can find argument keys used by argsPattern.
• Added a schema-level note near TOML rule schema pointing to the Tools Reference for toolName values and argument structures.
• Clarified in Special syntax for run_shell_command that commandPrefix and commandRegex are policy-rule shorthands, not run_shell_command invocation arguments.
• Added links there to:
  • Shell tool docs (../tools/shell.md)
  • Tools Reference (./tools.md#available-tools)

Related Issues

• Fixes Review: Gemini CLI Policy Engine Documentation #18750

How to Validate

1. Open docs/reference/policy-engine.md.
2. In Tool Name, verify there is a link to ./tools.md#available-tools.
3. In Arguments pattern, verify there is a link to ./tools.md#available-tools.
4. In TOML rule schema, verify the note references valid toolName values and argument structures via the Tools Reference.
5. In Special syntax for run_shell_command, verify it explicitly says commandPrefix/commandRegex are policy shorthands (not shell tool args) and links to:
   • ../tools/shell.md
   • ./tools.md#available-tools

Pre-Merge Checklist

Just a doc issue.

[gemini-code-assist]

Summary of Changes

Hello, 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 policy engine documentation by providing direct links to the Tools Reference page for toolName and argsPattern, improving discoverability of available tools and their parameters. It also clarifies the usage of commandPrefix and commandRegex as policy shorthands, preventing potential confusion with run_shell_command tool arguments.

Highlights

• Tool Name Links: Added direct links from toolName and argsPattern to the Tools Reference page for easier access to tool details.
• Clarification on Policy Shorthands: Clarified that commandPrefix and commandRegex are policy shorthands and not arguments for the run_shell_command tool.

Changelog

• docs/reference/policy-engine.md
  • Added links to the Tools reference for tool names and arguments.
  • Clarified that commandPrefix and commandRegex are policy shorthands.

Activity

• The pull request addresses issue Review: Gemini CLI Policy Engine Documentation #18750.

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 enhances the policy engine documentation. It introduces direct links to the tools reference page for toolName and argsPattern, which will help users look up tool names and their corresponding arguments. Additionally, it clarifies that commandPrefix and commandRegex are shorthands for creating policy rules, not arguments for the run_shell_command tool itself. The changes are accurate and improve the documentation's clarity. I have no further comments.

_{Note: Security Review has been skipped due to the limited scope of the PR.}

[Aaxhirrr]

This should do it.
@g-samroberts would appreciate a quick review when you have a moment. Thank you.

[jkcinouye]

@g-samroberts Is there any context on this or could we review? :)

[g-samroberts]

Thanks for your contribution, @Aaxhirrr! If you could just add these suggestions, and then do npm run format to make sure the linter will pass, I can merge this in.

[Aaxhirrr]

Thanks, @g-samroberts . I’ve applied the final suggested wording changes and pushed them to this PR. Always happy to contribute.

[chrstnb]

Build failed: Build process failed with link errors:

15:24:19 [ERROR] ✗ Found 39 invalid links in 1 file.
15:24:19 [ERROR] [starlight-links-validator-integration] An unhandled error occurred while running the "astro:build:done" hook

[Aaxhirrr]

Build failed: Build process failed with link errors:

15:24:19 [ERROR] ✗ Found 39 invalid links in 1 file.
15:24:19 [ERROR] [starlight-links-validator-integration] An unhandled error occurred while running the "astro:build:done" hook

Hi @chrstnb , thank you for flagging this. I think i've found the root cause. That was an oversight on my part.

I had actually added the new links in Policy Engine links using Markdown-style relative paths. That looked fine in the repo, but the docs preview/build expects site-route links instead, so those links ended up failing validation there.

I’ve now updated those links to use the site route format already used elsewhere in the docs and pushed the fix to this PR.

Could you please rerun/recheck the docs build when you get a chance? and lmk if everything looks fine, or if there still is an issue, and ill get right on to it.

Thanks again.

[Aaxhirrr]

/gemini review

[gemini-code-assist]

Code Review

This pull request updates the docs/reference/policy-engine.md file to improve its clarity and navigability. It adds several internal links to the "Tools reference" document, providing readers with direct access to lists of built-in tool names, argument keys for argsPattern, and details on toolName values and argument structures within the TOML rule schema. Additionally, it clarifies the distinction between policy-rule shorthands and tool invocation arguments for run_shell_command by linking to the "Shell tool" and "Tools reference". A minor correction was also made to the "Customizing Plan Mode Policies" link by removing the .md extension. There is no feedback to provide from the review comments.

_{Note: Security Review has been skipped due to the limited scope of the PR.}