Semantic Firewall
View as Markdown

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 instead.

Prerequisites

  • A firewall key (sfw_live_xxxxxxxx). 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.
export SFW_KEY=sfw_live_xxxxxxxx...your-full-key

Steps

1. Install the client

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

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).

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.

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:

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

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.