docs(policy-engine): add tool argument keys reference and shell policy cross-links by harshpujari · Pull Request #25292 · google-gemini/gemini-cli

harshpujari · 2026-04-13T14:22:06Z

Summary

This PR addresses the remaining documentation gaps identified in #18750 (complementary to #22081 which adds links from the policy engine page):

Added a "Tool argument keys" section to docs/reference/tools.md — A compact reference table listing JSON argument keys for all 24 built-in tools, with a practical argsPattern example. This makes toolName and argsPattern usable without guesswork.
Added a "Policy engine shorthands" section to docs/tools/shell.md — Documents that commandPrefix and commandRegex exist as policy-rule convenience fields, clarifies they are not run_shell_command arguments, and links to the policy engine reference.

Details

Issue items addressed

Issue item	What this PR does
1. No reference list of available tool names	Adds a table with all 24 built-in tool names and their argument keys
2. `commandPrefix` absent from shell tool page	Adds a "Policy engine shorthands" section to the shell tool page
3. `argsPattern` requires knowing JSON argument structure	The argument keys table provides exactly this information

Relationship with #22081

PR #22081 adds cross-links from the policy engine page to the tools reference. This PR adds the reference content at those link targets and a cross-reference from the shell tool page back to the policy engine. The two PRs are complementary and non-overlapping.

How to validate

Open docs/reference/tools.md and verify the new "Tool argument keys" subsection under "Available tools" contains a complete table of tools and their JSON argument keys.
Verify the TOML example for blocking .env writes is syntactically correct.
Open docs/tools/shell.md and verify the new "Policy engine shorthands" subsection appears between "Arguments" and "Return values".
Verify all internal links resolve to existing anchors.

Pre-merge checklist

Documentation-only change. Passes prettier --check and pre-commit hooks.

Fixes #18750

…y cross-links Add a "Tool argument keys" section to the tools reference page listing JSON argument keys for all built-in tools, making toolName and argsPattern usable without guesswork. Add a "Policy engine shorthands" section to the shell tool page documenting commandPrefix and commandRegex as policy-rule convenience fields. Fixes google-gemini#18750

gemini-code-assist · 2026-04-13T14:22:20Z

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 improves the developer experience by filling documentation gaps related to the policy engine. It provides clear references for tool argument structures and clarifies the usage of specific policy rule shorthands, ensuring users can configure security policies more effectively without ambiguity.

Highlights

Tool Argument Reference: Added a comprehensive table to the tools reference documentation detailing the JSON argument keys for all 24 built-in tools to assist with policy engine configuration.
Shell Policy Documentation: Introduced a new section in the shell tool documentation clarifying the use of policy engine shorthands like commandPrefix and commandRegex.

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.

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 adds documentation for tool argument keys and policy engine shorthands for shell commands. Several critical issues were identified in the new documentation: the argument keys for glob, grep_search, and read_file do not match the actual codebase definitions, which would cause policy rules to fail. Additionally, the regex example for blocking .env files requires multiple levels of escaping to be valid in a TOML/JSON context, and the documented commandPrefix and commandRegex shorthands are currently unimplemented in the policy engine, making their inclusion misleading.

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

gemini-code-assist · 2026-04-13T14:27:19Z

+```toml
+[[rule]]
+toolName = "write_file"
+argsPattern = '"file_path":".*\.env"'


According to the repository's general rules, regular expressions embedded in TOML strings require multiple levels of escaping for literal characters like dots to account for TOML, JSON, and regex parsing layers. In a literal TOML string (single quotes), a literal dot for the regex engine should be represented as \\..

Suggested change

argsPattern = '"file_path":".*\.env"'

argsPattern = '"file_path":".*\\.env"'

References

When a regular expression is embedded within a JSON string, which is itself embedded within a TOML string, multiple levels of escaping are required. For example, to represent a literal dot for the regex engine, it must be written as \. in the TOML file to account for escaping at the TOML, JSON, and regex parsing layers.

The argsPattern value is in a TOML single-quoted (literal) string, which has no escape processing per the TOML spec. The string '\.env' gives the regex \.env, where \. correctly matches a literal dot. Using '\\.env' would give regex \\.env, which matches a literal backslash followed by any character — not the intended behavior. The existing policy engine docs use the same single-quote convention without double escaping (e.g., argsPattern = '"command":"(git|npm)').

Fix JSON argument keys for glob (dir_path not path, add respect_gemini_ignore), grep_search (dir_path not path, include_pattern not include, add all optional params), and read_file (start_line/end_line not offset/limit) to match actual parameter names in base-declarations.ts.

Nagajyothi-tammisetti · 2026-04-14T04:57:55Z

Hi, I reviewed this PR and found a few areas that might need clarification/improvement:

Verified argument keys for tools like glob, grep_search, read_file — I can help validate against source code.
Regex escaping might need clearer explanation with examples.
Policy engine shorthands could benefit from clarification in docs.

I’d be happy to contribute improvements if needed.

harshpujari · 2026-04-14T13:10:18Z

Thanks for looking! The argument keys were already corrected in c3736ba, and the other two points are addressed in my replies to the automated review above — the escaping is correct per the TOML spec for literal strings, and commandPrefix/commandRegex are implemented in toml-loader.ts as syntactic sugar that compiles to argsPattern.

DavidAPierce

LGTM. Correctly documents the JSON argument keys for built-in tools and clarifies
the behavior of policy engine shorthands for shell commands.

…y cross-links (google-gemini#25292) Co-authored-by: David Pierce <davidapierce@google.com>

harshpujari requested review from a team as code owners April 13, 2026 14:22

gemini-code-assist Bot reviewed Apr 13, 2026

View reviewed changes

harshpujari and others added 3 commits April 14, 2026 18:42

Merge branch 'main' into docs/policy-engine-tool-reference

a34cb50

Merge branch 'main' into docs/policy-engine-tool-reference

9ee0d88

Merge branch 'main' into docs/policy-engine-tool-reference

94ae399

DavidAPierce approved these changes May 1, 2026

View reviewed changes

DavidAPierce added this pull request to the merge queue May 1, 2026

Merged via the queue into google-gemini:main with commit dc5b311 May 1, 2026
26 of 27 checks passed

TirthNaik-99 pushed a commit to TirthNaik-99/gemini-cli that referenced this pull request May 4, 2026

docs(policy-engine): add tool argument keys reference and shell polic…

1588188

…y cross-links (google-gemini#25292) Co-authored-by: David Pierce <davidapierce@google.com>

kimjune01 pushed a commit to kimjune01/gemini-cli-claude that referenced this pull request May 6, 2026

docs(policy-engine): add tool argument keys reference and shell polic…

cb46ddc

…y cross-links (google-gemini#25292) Co-authored-by: David Pierce <davidapierce@google.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(policy-engine): add tool argument keys reference and shell policy cross-links#25292

docs(policy-engine): add tool argument keys reference and shell policy cross-links#25292
DavidAPierce merged 5 commits intogoogle-gemini:mainfrom
harshpujari:docs/policy-engine-tool-reference

harshpujari commented Apr 13, 2026

Uh oh!

gemini-code-assist Bot commented Apr 13, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

gemini-code-assist Bot Apr 13, 2026

Uh oh!

harshpujari Apr 13, 2026

Uh oh!

Uh oh!

Nagajyothi-tammisetti commented Apr 14, 2026

Uh oh!

harshpujari commented Apr 14, 2026

Uh oh!

DavidAPierce left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	argsPattern = '"file_path":".*\.env"'
	argsPattern = '"file_path":".*\\.env"'

Conversation

harshpujari commented Apr 13, 2026

Summary

Details

Issue items addressed

Relationship with #22081

How to validate

Pre-merge checklist

Uh oh!

gemini-code-assist Bot commented Apr 13, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

gemini-code-assist Bot Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

harshpujari Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Nagajyothi-tammisetti commented Apr 14, 2026

Uh oh!

harshpujari commented Apr 14, 2026

Uh oh!

DavidAPierce left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants