# Gemini CLI

Gemini CLI on this machine hands every tool call to your Straza policy, and you have seen a destructive command denied with a reason.

- Who: The person at the machine where Gemini CLI runs
- Where: Terminal on that machine

In short: Gemini CLI passes every tool call to `straza hook` through its BeforeTool event, and the Straza background service decides it against a signed policy snapshot. Gemini runs no hooks when they are switched off, or in a folder it does not trust, and `straza doctor` checks both. An enterprise server requires the managed install by default.


You wire Gemini CLI to Straza on the workstation where it runs. At the end, Gemini hands every tool call to Straza before it runs it, and you have seen a destructive command denied with a reason.

Before Gemini runs a tool, it passes the call to `straza hook`, which hands it to `straza service`, the Straza background service on the machine, to decide against a signed policy snapshot the service holds. Gemini names the events its own way, such as `BeforeTool` for a tool call. It reads every answer as a strict JSON document on stdout, either `{"decision":"allow"}` or `{"decision":"deny"}` with a reason. Gemini can also turn hooks off in two ways, so this page has one step more than the Claude Code page.

## Before you start

- Gemini CLI on this machine.
- A role whose policy allows your local tools. A fresh enterprise server holds no PolicySet and denies every local tool that no rule allows, so an admin first sets up the role and the PolicySet of [Give agents their local tools](https://docs.straza.ai/guides/operate/enterprise-shape/index.md#give-agents-their-local-tools) and gives you its `developer` role. The seeded `developer` role of the [demo stack](https://docs.straza.ai/evaluate/try-it-on-the-demo-stack/index.md) is such a role already. A standalone server needs no role, because its seeded `standalone-starter` PolicySet applies to every identity.

## Enroll this machine

Enroll the machine once, as [Enroll a machine](https://docs.straza.ai/guides/govern-an-agent/enroll-a-machine/index.md) shows. The machine is ready for the next step when `straza status` names your identity and `straza doctor` warns only about the session and the wiring. Start Gemini from a shell that exports the same `STRAZA_HOME` as a `straza service` you started yourself, because its hooks look for that service through it. On a machine with a system service or a managed install, the hooks ignore `STRAZA_HOME` and reach the system service. On an enterprise server the service also has to hold your key under its own OS account, as that page explains.

## Install the hook wiring

Run the installer as yourself, on the machine where Gemini runs. It takes no server address. The hooks reach `straza service`, which keeps the server that `straza enroll --server` named.

Terminal, on the agent's machine:

```sh
straza install gemini
```

You should see: A line that starts `installed Straza hooks for gemini into`, a line that starts `registered Straza MCP server for gemini in`, and a note on stderr about folder trust, which the next step answers.

The installer merges the Straza hook entries into `~/.gemini/settings.json` and registers the `straza mcp` gateway server in the same file. Everything else in it stays as it was. Restart Gemini so it loads the new settings.

What the installer writes:

The wiring registers `straza hook --harness gemini` on four Gemini events: `SessionStart`, `BeforeAgent`, `BeforeTool` with a `*` matcher, and `AfterAgent`. Together they cover enforcement and conversation recording.

The command above is the user-mode install. A fleet machine takes the managed install instead. So does any machine whose server runs the enterprise profile, because an enterprise server refuses a user-mode session by default. Either install works against a standalone server and the demo stack.

Terminal, as an administrator:

```sh
sudo straza install --managed --server https://straza.example.com gemini
```

`--server` names the server that the root-owned layout pins for every user of the machine, and the install refuses to run without it. Use your own address in place of the example. Each person still enrolls once as themselves, so every call is decided and audited as the person who made it. The background service reads that server from the managed layout when a person enrolls, so after an administrator points the layout at another server, each person runs `straza enroll` again, as [Move a machine to another server](https://docs.straza.ai/guides/govern-an-agent/enroll-a-machine/index.md#move-a-machine-to-another-server) shows. It reads the snapshot keys the layout pins each time it fetches a new policy and when it starts.

| Install | Who can change the wiring | Sessions attest as |
|---|---|---|
| User mode | You | `advisory` |
| Managed | An administrator only. The system settings pin `hooksConfig.enabled = true`, which Gemini ranks above a user's opt-out | `managed`, when the server holds the hashes of its files |

A user-mode hook is advisory, because an agent that can run any command can also turn the hook off. The managed install writes the root-owned layout that the server checks for tampering at every check-in. When Gemini's folder trust is on, a managed install still needs the folder trusted, as the next step shows. [Attestation levels](https://docs.straza.ai/guides/govern-an-agent/enroll-a-machine/index.md#attestation-levels) explains how the server sets the level.

## Check that Gemini runs the hooks

Gemini runs no hooks at all when `hooksConfig.enabled` is `false`. When its folder trust is on, it also runs none in a folder it does not trust. The install warns about both in this note:

```text
NOTE: gemini refuses to start headless in an untrusted folder, and runs NO hooks anywhere if hooksConfig.enabled=false; `straza doctor` checks both (gemini-hooks). Trust the working folder inside gemini before relying on governance.
```

Run the doctor in the folder where you use Gemini, so it checks that folder's trust.

Terminal, in the folder where you use Gemini:

```sh
straza doctor
```

You should see: `[ ok ]` on the `gemini-hooks` line.

If this fails:

`has no trust record`
: Folder trust is on and this folder is not trusted yet. Open Gemini in this folder once and trust it in its dialog.

`is recorded UNTRUSTED in`
: Gemini records this folder as untrusted. Trust it in Gemini's dialog, or remove its `DO_NOT_TRUST` record from the file the line names.

`hooks are switched OFF`
: A settings file sets `hooksConfig.enabled = false`, and the line names that file. Remove the setting, or use the managed install, which pins it to `true`.

`GEMINI_CLI_SYSTEM_SETTINGS_PATH redirects gemini's system settings to`
: Gemini reads another system settings file than the managed one. Unset the variable, or point it at the managed file.

## Open a session

Straza decides a tool call inside a session. Gemini opens one with a SessionStart event each time it starts. To check the wiring without Gemini, send that event to the hook by hand.

Terminal, on the agent's machine:

```sh
printf %s '{"hook_event_name":"SessionStart"}' | straza hook --harness gemini
```

You should see: `"decision":"allow"` and an `additionalContext` that begins `Straza governs this session as` with your username in quotes, and then says how the agent treats a denied call.

That context is the banner the model reads at the start of each session. [What the agent reads back](https://docs.straza.ai/guides/govern-an-agent/what-the-agent-reads-back/index.md) quotes it in full.

If this fails:

`attestation level "advisory" is below the required level "managed"`
: The server requires a managed install. Run `sudo straza install --managed --server <server-url> gemini`, as the install step shows.

## Check a deny and an allow

Send the hook a shell call of a destructive command, the way Gemini sends it.

Terminal, on the agent's machine:

```sh
printf %s '{"hook_event_name":"BeforeTool","tool_name":"run_shell_command","tool_input":{"command":"rm -rf /tmp/x"}}' | straza hook --harness gemini
```

You should see: A JSON document with `"decision":"deny"` and the policy's reason. Gemini acts on that field and ignores the exit code.

```text
{"decision":"deny","reason":"Straza: destructive command denied by the agent guardrails"}
```

That reason comes from the demo stack's guardrails policy. On a standalone server, the seeded `standalone-starter` PolicySet denies the same command for every identity, with the reason `Straza starter policy: this sample rule denies commands that start with rm -rf. Delete files individually, or an admin can edit the standalone-starter PolicySet.`

Now send a safe command.

Terminal, on the agent's machine:

```sh
printf %s '{"hook_event_name":"BeforeTool","tool_name":"run_shell_command","tool_input":{"command":"git status"}}' | straza hook --harness gemini
```

You should see: `{"decision":"allow"}`

A standalone server allows the command too, because its default allows a local tool that no rule matches. Both decisions land in the session's audit trail.

If this fails:

`Straza: no active Straza session. Restart the session so straza can check in`
: No session is open on this machine. Send the SessionStart event of the step before, or restart Gemini.

## Remove the wiring

Run `straza uninstall gemini` to remove the hook entries and the MCP registration. It leaves the rest of your settings intact. A managed install comes off with `sudo straza uninstall --managed gemini`, which leaves the `hooksConfig.enabled = true` pin in place.

## When a hook seems silent

On Gemini the usual cause is folder trust or the hooks switch. Run `straza doctor` in the working folder and read its `gemini-hooks` line, as the step above shows. Straza fails closed, so a missing snapshot or a background service that does not answer denies with a reason and never lets a call through.

When the server cannot be reached, the service keeps deciding for the offline grace and then denies, as [Working offline](https://docs.straza.ai/guides/govern-an-agent/enroll-a-machine/index.md#working-offline) explains.

## When Gemini CLI adds a tool

When a Gemini CLI release adds a tool that this Straza client does not know yet, the hook sends the tool as `other` with its own name and its input. Its audit record keeps that input as sent in `arguments`, as every tool's record does, so it can hold a secret the tool takes. An enterprise server denies it with a reason that names the tool and the rule that allows it, and a standalone server allows it by default. An admin allows, holds or denies exactly that tool with a rule of `tools: [other]` and `toolNames: {allow: [<name>]}`, with no Straza release, as [Harness tools by name](https://docs.straza.ai/reference/policyset-grammar/index.md#harness-tools-by-name) shows. A later Straza release puts the tool into its kind, and the rule keeps governing it.

Write the rule in the console:

In Policies, the **Denied by default** view lists the tool when a call to it was denied in the last 24 hours. **Write a rule** on its row opens **New policy** with **Harness tool** and the tool's name answered under **Which calls**, and the wizard writes the same rule, as [Policies](https://docs.straza.ai/guides/console/policies/index.md#read-the-policy-list) shows.

## Next

- [Write your first deny](https://docs.straza.ai/guides/write-policy/first-deny/index.md) turns one dangerous command into a deny with your own reason.
- [What the agent reads back](https://docs.straza.ai/guides/govern-an-agent/what-the-agent-reads-back/index.md) lists every answer the model can get from Straza.
- For work where an advisory hook is not enough, route the agent's tool calls through the gateway, as [Any MCP client](https://docs.straza.ai/guides/govern-an-agent/any-mcp-client/index.md) shows, or run it in the sandbox image of [Hookless processes](https://docs.straza.ai/guides/govern-an-agent/hookless-processes/index.md). [The trust model](https://docs.straza.ai/evaluate/security-model/index.md) explains why those two hold at a boundary.


Walked on v1.1.0-117-g106081a8 on 2026-10-06, except straza install, the doctor's gemini-hooks line and straza uninstall, which were not run. An Alpine 3.20 container against a standalone server, as the local user alice enrolled by the device flow, where the SessionStart, BeforeTool deny, allow and no-session payloads and the managed-attestation refusal were fired and the four hook events were read from the server's rendered managed config, while straza install, the doctor's gemini-hooks line and straza uninstall were not run because this box never runs straza install and has no Gemini, and the demo stack's guardrails reason was read from its seed policy and the agent-sam log instead of fired, because the demo stack takes no writes.

