# Agent CLI & hooks

Guard a coding agent — Claude Code, Codex, or Gemini CLI — with pre/post tool-call inspection. You install the dependency-free `sfw` client straight from your firewall (no Python required on the agent machine), then install hooks that inspect every tool call before it runs, every tool result after, and the agent's final response.

This is the right path when the LLM lives inside a coding agent you do not control the source of. If you call a provider SDK directly, use the [Transparent proxy](/docs/guides/transparent-proxy) instead.

## Prerequisites

- A firewall key (`sfw_live_xxxxxxxx`). [Sign in](/sign-in) and open **Keys** to mint one.
- macOS or Linux for the one-line installer (Windows download noted below).
- One of: Claude Code, Codex, or Gemini CLI installed locally.

```bash
export SFW_KEY=sfw_live_xxxxxxxx...your-full-key
```

## Steps

### 1. Install the client

```bash
curl -fsSL https://your-firewall.example.com/install.sh | sh -s -- --key "$SFW_KEY"
```

The installer bakes this firewall's URL and your key into `~/.semantic-firewall/config`, so every command below needs no further setup. Omit `--key` if the firewall does not enforce auth. On Windows, download `https://your-firewall.example.com/cli/sfw-windows-amd64.exe` and add it to your PATH.

The `sfw` binary is a single dependency-free static binary versioned to this deployment. Hooks invoke it directly — there is no `python3` requirement on the agent machine.

### 2. Install hooks for your agent

```bash
sfw hook install claude-code    # or: codex, gemini
sfw hook install claude-code --block-on-flag   # stricter: block flagged inputs too
sfw hook install claude-code --fail-closed     # block if the firewall is unreachable
sfw hook status
```

Installing hooks wires the agent to inspect:

- every **tool call before it runs** — blocking injections, pseudonymizing PII in the arguments;
- every **tool result after it returns**;
- the agent's **final response**, via a `Stop` / `SubagentStop` hook that runs the message through output inspection (see [Detect a compromised agent](/docs/guides/detect-compromised-agent)).

### 3. Choose a fail mode

By default hooks **fail open** — if the firewall is unreachable, the tool call proceeds (availability first). Add `--fail-closed` to **block** instead (assurance first); only the enforcing PreToolUse / passthrough hooks honor it.

Recommended policy: **block critical · flag high · allow the rest** — tune it per key in the **Configuration** tab. Because hooks send no system prompt, set a **System goal** on the key's **Configuration** tab so semantic-drift detection has a baseline; it applies automatically.

## Verify the whole integration

`sfw verify` runs safe synthetic probes and reports what the firewall actually did — key recognized, a known injection blocked, PII sanitized, output screened — and exits non-zero if anything fails, so an agent or CI job can gate on it.

```bash
sfw verify                        # human report: key, policy, PII, output
sfw verify --json                 # machine-readable — for agents / CI
sfw verify --proxy openai         # also test that your provider key reaches upstream
```

You can also inspect arbitrary text straight from the shell:

```bash
echo "Email john.smith@acme.com about the invoice." | sfw inspect --format text
```

The PII in that line comes back pseudonymized, confirming the client and key are wired correctly.

## Manage the installation

```bash
sfw hook status       # show which agents have hooks installed and the active policy
sfw hook uninstall claude-code   # remove hooks for one agent
```

## Troubleshooting

- **`sfw: command not found`** — the installer did not add the binary to your PATH. Re-run the installer, or on Windows confirm the `.exe` is on PATH.
- **Key not recognized** — re-run the installer with `--key "$SFW_KEY"`, or check `~/.semantic-firewall/config`.
- **Tool calls proceed even when the firewall is down** — that is fail-open (the default). Reinstall with `--fail-closed` if you want blocking on unreachability.
- **Drift never fires on hook traffic** — hooks send no system prompt; set a **System goal** on the key's **Configuration** tab.
- **`sfw verify` exits non-zero** — read the report; it names the failing probe (key, injection, PII, or output). Fix that item and re-run.
- **Nothing appears in the dashboard** — confirm `sfw hook status` shows the agent installed and that the key matches the one you are viewing.