MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-04-20 18:14:29 -07:00
Code Issues Packages Projects Releases Wiki Activity

Automated documentation audit results (#22755)

Browse Source
This commit is contained in:
Sam Roberts
2026-04-09 19:07:00 -07:00
committed by GitHub
parent 69bf2d75ef
commit e09410b6e5
55 changed files with 404 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/hooks/best-practices.md
+18 -17
View File
@@ -367,7 +367,7 @@ chmod +x .gemini/hooks/*.js
```
**Windows Note**: On Windows, PowerShell scripts (`.ps1`) don't use `chmod`, but
you may need to ensure your execution policy allows them to run (e.g.,
you may need to ensure your execution policy allows them to run (for example,
`Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`).
### Version control
@@ -401,12 +401,12 @@ git add .gemini/settings.json
Understanding where hooks come from and what they can do is critical for secure
usage.
| Hook Source | Description |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| **System** | Configured by system administrators (e.g., `/etc/gemini-cli/settings.json`, `/Library/...`). Assumed to be the **safest**. |
| **User** (`~/.gemini/...`) | Configured by you. You are responsible for ensuring they are safe. |
| **Extensions** | You explicitly approve and install these. Security depends on the extension source (integrity). |
| **Project** (`./.gemini/...`) | **Untrusted by default.** Safest in trusted internal repos; higher risk in third-party/public repos. |
| Hook Source | Description |
| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| **System** | Configured by system administrators (for example, `/etc/gemini-cli/settings.json`, `/Library/...`). Assumed to be the **safest**. |
| **User** (`~/.gemini/...`) | Configured by you. You are responsible for ensuring they are safe. |
| **Extensions** | You explicitly approve and install these. Security depends on the extension source (integrity). |
| **Project** (`./.gemini/...`) | **Untrusted by default.** Safest in trusted internal repos; higher risk in third-party/public repos. |
#### Project Hook Security
@@ -422,9 +422,10 @@ When you open a project with hooks defined in `.gemini/settings.json`:
5. **Trust**: The hook is marked as "trusted" for this project.
> **Modification detection**: If the `command` string of a project hook is
> changed (e.g., by a `git pull`), its identity changes. Gemini CLI will treat
> it as a **new, untrusted hook** and warn you again. This prevents malicious
> actors from silently swapping a verified command for a malicious one.
> changed (for example, by a `git pull`), its identity changes. Gemini CLI will
> treat it as a **new, untrusted hook** and warn you again. This prevents
> malicious actors from silently swapping a verified command for a malicious
> one.
### Risks
@@ -441,17 +442,17 @@ When you open a project with hooks defined in `.gemini/settings.json`:
**Verify the source** of any project hooks or extensions before enabling them.
- For open-source projects, a quick review of the hook scripts is recommended.
- For extensions, ensure you trust the author or publisher (e.g., verified
publishers, well-known community members).
- For extensions, ensure you trust the author or publisher (for example,
verified publishers, well-known community members).
- Be cautious with obfuscated scripts or compiled binaries from unknown sources.
#### Sanitize environment
Hooks inherit the environment of the Gemini CLI process, which may include
sensitive API keys. Gemini CLI provides a
Hooks inherit the environment of Gemini CLI process, which may include sensitive
API keys. Gemini CLI provides a
[redaction system](../reference/configuration.md#environment-variable-redaction)
that automatically filters variables matching sensitive patterns (e.g., `KEY`,
`TOKEN`).
that automatically filters variables matching sensitive patterns (for example,
`KEY`, `TOKEN`).
> **Disabled by Default**: Environment redaction is currently **OFF by
> default**. We strongly recommend enabling it if you are running third-party
@@ -511,7 +512,7 @@ chmod +x .gemini/hooks/my-hook.sh
```
**Windows Note**: On Windows, ensure your execution policy allows running
scripts (e.g., `Get-ExecutionPolicy`).
scripts (for example, `Get-ExecutionPolicy`).
**Verify script path:** Ensure the path in `settings.json` resolves correctly.
docs/hooks/index.md
+9 -8
View File
@@ -63,9 +63,9 @@ Hooks communicate via `stdin` (Input) and `stdout` (Output).
2. **Pollution = Failure**: If `stdout` contains non-JSON text, parsing will
fail. The CLI will default to "Allow" and treat the entire output as a
`systemMessage`.
3. **Debug via Stderr**: Use `stderr` for **all** logging and debugging (e.g.,
`echo "debug" >&2`). Gemini CLI captures `stderr` but never attempts to parse
it as JSON.
3. **Debug via Stderr**: Use `stderr` for **all** logging and debugging (for
example, `echo "debug" >&2`). Gemini CLI captures `stderr` but never attempts
to parse it as JSON.
#### Exit codes
@@ -74,7 +74,7 @@ execution:
| Exit Code | Label | Behavioral Impact |
| --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **0** | **Success** | The `stdout` is parsed as JSON. **Preferred code** for all logic, including intentional blocks (e.g., `{"decision": "deny"}`). |
| **0** | **Success** | The `stdout` is parsed as JSON. **Preferred code** for all logic, including intentional blocks (for example, `{"decision": "deny"}`). |
| **2** | **System Block** | **Critical Block**. The target action (tool, turn, or stop) is aborted. `stderr` is used as the rejection reason. High severity; used for security stops or script failures. |
| **Other** | **Warning** | Non-fatal failure. A warning is shown, but the interaction proceeds using original parameters. |
@@ -84,8 +84,9 @@ You can filter which specific tools or triggers fire your hook using the
`matcher` field.
- **Tool events** (`BeforeTool`, `AfterTool`): Matchers are **Regular
Expressions**. (e.g., `"write_.*"`).
- **Lifecycle events**: Matchers are **Exact Strings**. (e.g., `"startup"`).
Expressions**. (for example, `"write_.*"`).
- **Lifecycle events**: Matchers are **Exact Strings**. (for example,
`"startup"`).
- **Wildcards**: `"*"` or `""` (empty string) matches all occurrences.
## Configuration
@@ -151,8 +152,8 @@ Hooks are executed with a sanitized environment.
**Project-level hooks** are particularly risky when opening untrusted projects.
Gemini CLI **fingerprints** project hooks. If a hook's name or command changes
(e.g., via `git pull`), it is treated as a **new, untrusted hook** and you will
be warned before it executes.
(for example, via `git pull`), it is treated as a **new, untrusted hook** and
you will be warned before it executes.
See [Security Considerations](../hooks/best-practices.md#using-hooks-securely)
for a detailed threat model.
docs/hooks/reference.md
+10 -10
View File
@@ -20,8 +20,8 @@ including JSON schemas and API details.
## Configuration schema
Hooks are defined in `settings.json` within the `hooks` object. Each event
(e.g., `BeforeTool`) contains an array of **hook definitions**.
Hooks are defined in `settings.json` within the `hooks` object. Each event (for
example, `BeforeTool`) contains an array of **hook definitions**.
### Hook definition
@@ -52,7 +52,7 @@ All hooks receive these common fields via `stdin`:
"session_id": string, // Unique ID for the current session
"transcript_path": string, // Absolute path to session transcript JSON
"cwd": string, // Current working directory
"hook_event_name": string, // The firing event (e.g. "BeforeTool")
"hook_event_name": string, // The firing event (for example "BeforeTool")
"timestamp": string // ISO 8601 execution time
}
```
@@ -81,12 +81,12 @@ Most hooks support these fields in their `stdout` JSON:
For `BeforeTool` and `AfterTool` events, the `matcher` field in your settings is
compared against the name of the tool being executed.
- **Built-in Tools**: You can match any built-in tool (e.g., `read_file`,
- **Built-in Tools**: You can match any built-in tool (for example, `read_file`,
`run_shell_command`). See the [Tools Reference](../reference/tools) for a full
list of available tool names.
- **MCP Tools**: Tools from MCP servers follow the naming pattern
`mcp_<server_name>_<tool_name>`.
- **Regex Support**: Matchers support regular expressions (e.g.,
- **Regex Support**: Matchers support regular expressions (for example,
`matcher: "read_.*"` matches all file reading tools).
### `BeforeTool`
@@ -194,7 +194,7 @@ request format.
(generation params).
- **Relevant Output Fields**:
- `hookSpecificOutput.llm_request`: An object that **overrides** parts of the
outgoing request (e.g., changing models or temperature).
outgoing request (for example, changing models or temperature).
- `hookSpecificOutput.llm_response`: A **Synthetic Response** object. If
provided, the CLI skips the LLM call entirely and uses this as the response.
- `decision`: Set to `"deny"` to block the request and abort the turn.
@@ -271,14 +271,14 @@ telemetry.
### `Notification`
Fires when the CLI emits a system alert (e.g., Tool Permissions). Used for
external logging or cross-platform alerts.
Fires when the CLI emits a system alert (for example, Tool Permissions). Used
for external logging or cross-platform alerts.
- **Input Fields**:
- `notification_type`: (`"ToolPermission"`)
- `message`: Summary of the alert.
- `details`: JSON object with alert-specific metadata (e.g., tool name, file
path).
- `details`: JSON object with alert-specific metadata (for example, tool name,
file path).
- **Relevant Output Fields**:
- `systemMessage`: Displayed alongside the system alert.
- **Observability Only**: This hook **cannot** block alerts or grant permissions