AgentGuard v1.4.0

[Caua-ferraz]

AgentGuard 1.4.0 — Release Notes

Released: 2026-10-15
Headline: Guard every coding agent, prove the audit log wasn't touched, and test your policy like code.

Check these before you upgrade.

• A require_prior deny or approval rule now fires when AgentGuard can't read the history it depends on; before, a lookup error quietly skipped it.
• Shell rules now see commands hidden inside bash -c, eval and wrappers such as timeout or env, so some commands that used to pass now ask for approval.
• GET /v1/audit now answers 400 to a since or until that isn't an RFC 3339 time, where 1.3 ignored both parameters. See MIGRATION.md.

---

Why this release exists

1.3 made AgentGuard easy to install and put Claude Code behind it. 1.4 is about the questions people ask next:

1. "We don't only use Claude Code." Cursor, Gemini CLI and Codex CLI are now guarded the same way. And if the AgentGuard server is down, you choose whether their calls go ahead or stop.
2. "How do I know the audit log is real?" Sealing chains every entry to the previous one with an HMAC. Change, delete or reorder a line and agentguard audit verify names the exact place.
3. "How do I know my policy does what I think?" agentguard test runs it against test cases in CI, including the raw tool calls your coding agents send.
4. "What did this agent and its subagents actually do?" Sessions tie the calls together, and the dashboard replays them step by step.
5. "Can we hand this to an auditor?" agentguard report writes the evidence for a period, mapped to SOC 2 criteria.

It also brings remote MCP servers to the MCP gateway, adds an OpenAI Agents SDK adapter, and fixes several ways a tool call could get past the policy unchecked. Two of them were found while preparing this release, and both affect 1.3: commands hidden inside bash -c or eval, and disguised spellings of a blocked address.

---

What's new

Cursor, Gemini CLI and Codex CLI

agentguard setup can now connect Cursor, Gemini CLI and Codex CLI as well as Claude Code. Each one gets a hook that checks its tool calls on your AgentGuard server before they run:

Agent	Checked
Claude Code	shell, file reads and edits, web fetches, MCP tools
Cursor	shell, file reads and writes, MCP tools
Gemini CLI	shell, file reads and writes, web_fetch (every URL in the request), MCP tools
Codex CLI	shell, apply_patch (every file the patch touches), MCP tools

Allowed calls carry on under the agent's own permissions. Denied calls are blocked and the agent sees why. Calls that need approval wait up to 5 minutes for you in the dashboard or with agentguard approve. When one action touches several things, such as a patch that edits three files, each one is checked and the strictest answer wins. Gemini's web_fetch URLs are read the way Gemini itself parses them, so a disguised host can't slip past a network rule.

Fail open or fail closed. When connecting an agent, setup asks what should happen if AgentGuard isn't running:

• Let calls through with a warning: the default, as in 1.3.
• Block them (agentguard hook <agent> --fail-closed): an unreachable server, a rejected API key or an unreadable call is denied with rule deny:hook:fail_closed.

Each agent has a ready-made rule block (configs/cursor.yaml, configs/gemini-cli.yaml, configs/codex.yaml), and setup offers to add it to your policy. The audit log and dashboard tag every call with its agent (claude_code, cursor, gemini_cli, codex_cli). See CODING_AGENTS.md.

A tamper-evident audit log

agentguard server --audit-seal --audit-seal-key-file /var/lib/agentguard/audit-seal.key
agentguard audit verify --audit-log /var/lib/agentguard/audit.jsonl \
  --key-file /var/lib/agentguard/audit-seal.key

• The chain. With --audit-seal, every entry carries a sequence number, the previous entry's hash and its own HMAC-SHA256. The chain also links across rotated and gzipped files.

• Verifying it. agentguard audit verify checks it offline. Edit a byte, delete a line, swap two lines or cut the file short, and it exits 1 with the file and line where the chain breaks. A log with no sealed entries gets "NOT SEALED" and exit 1 too, since nothing could be verified.

• Anchors. AgentGuard publishes the head of the chain every 5 minutes and on every rotation, in three places:

  • a log line, which ends up in journald, syslog or your SIEM;
  • a Prometheus gauge;
  • GET /v1/audit/head.

  Pass one to audit verify --anchor and even someone holding the key can't rewrite history before it.

• New installs are sealed by default. agentguard setup generates a key that only you can read.

• Off unless you turn it on otherwise. Existing installs keep byte-identical logs until you turn sealing on. The audit format version is unchanged.

Policies as code: agentguard test

# policy_test.yaml
policy: policy.yaml   # yours, with the Codex block setup adds
tests:
  - name: plain ls is allowed
    request: {scope: shell, command: "ls -la"}
    expect: ALLOW
  - name: Codex can't patch an .env file
    hook: codex
    input: {cwd: /home/dev/app, tool_name: apply_patch,
            tool_input: {command: "*** Begin Patch\n*** Update File: .env\n..."}}
    expect: REQUIRE_APPROVAL

agentguard test runs every case against your policy. Each case starts fresh, so earlier cases can't change later ones. A case can seed the history a require_prior rule needs, or give a coding agent's raw tool call through hook:, which goes through the same mapping as the real hook.

The command fits CI: --output junit for test reports, --run to filter cases, and exit 1 when anything fails. AgentGuard's own CI runs 158 cases against the shipped policies. See POLICY_REFERENCE.md § Testing policies.

Sessions and replay

• Parent and child sessions. A request can now name the session that started it (parent_session_id). It can be set in four places:
  • the Python SDK: Guard(parent_session_id=...);
  • the TypeScript SDK: parentSessionId;
  • the LLM proxy: the X-AgentGuard-Parent-Session header;
  • the hooks, which also record which subagent made each call.
• Session API. GET /v1/sessions lists sessions with their agents, subagents, transports and counts by decision. GET /v1/sessions/{id} returns one session's calls and its child sessions.
• Audit filters. GET /v1/audit and agentguard audit gain since, until, session and parent-session filters.

The dashboard has a new Sessions tab. Pick a session and replay it with one lane per agent and subagent:

• Controls: play, pause, step, back and 1x–50x speed.
• Approvals appear next to the call they unblocked.
• Parent and child sessions link to each other.
• #session=<id> links can be shared.

Compliance evidence: agentguard report

agentguard report --since 7d --output html --out-file week.html

The report covers one period. It comes as Markdown, JSON or a single HTML page, and contains:

• the policy in force, identified by SHA-256;
• whether the audit log verified;
• decisions by type, scope, agent and transport;
• the rules that denied or held the most calls;
• approvals;
• the sessions and agents seen;
• posture checks, such as sealing on and secrets masked.

A section maps this evidence to SOC 2 criteria CC6.1, CC6.6, CC7.2, CC7.3 and CC8.1. It is labelled as supporting evidence for an auditor, not a certification.

It reads the audit log files, rotated ones included, and verifies them. Or it can read a running server with --url. It exits 1, still writing the report, if the audit log fails verification. See COMPLIANCE.md.

Remote MCP servers in the MCP gateway

agentguard-mcp-gateway \
  --upstream-http "docs:https://mcp.example.com/mcp" \
  --upstream-header 'docs:Authorization=Bearer ${DOCS_TOKEN}'

• Remote servers. The gateway can now guard MCP servers that speak Streamable HTTP, alongside the ones it starts locally.
• Secrets. Header values can come from environment variables, so tokens stay out of client configs and logs.
• Recovery. Expired sessions are renewed. A server that goes away is retried until it comes back, and the host is told to refresh its tool list.
• Protocol. MCP 2025-06-18 is supported.

OpenAI Agents SDK adapter

from agents import Agent
from agentguard import Guard
from agentguard.adapters.openai_agents import guard_tools

agent = Agent(name="ops", tools=guard_tools([run_shell, read_file], Guard()))

guard_tool and guard_tools check each tool call before it runs, and agentguard_tool_guardrail plugs into the SDK's own guardrails. A denied call raises AgentGuardDenied, and the tool never runs. Install it with pip install "agentguardproxy[openai-agents]"; it supports openai-agents 0.3.3 up to 1.0.

---

Security fixes

• A command hidden inside another shell skipped the shell rules. bash -c 'rm -rf /', eval rm -rf /, timeout 5 bash -c '…' and env sudo … each read as one harmless-looking command. Under the coding-agent blocks, which allow everything except what they deny or send to approval, they passed without the approval rm -rf and sudo need. This has affected Claude Code since 1.3.

  • AgentGuard now checks the commands inside:
    • sh/bash/zsh and other shells' -c scripts;
    • eval, and here-strings fed to a shell;
    • commands behind launchers: env, sudo, pkexec, nohup, timeout, xargs, chroot, npx, uv run, poetry run and more.
  • Rules like the fork bomb and curl … | sh match inside them too, and a deny on any part wins.
  • A script inside bash -c that AgentGuard can't read (arithmetic, a heredoc, case) asks for approval rather than passing.

• A disguised address got past network rules. A deny on the cloud metadata address 169.254.169.254 didn't catch the same address written another way:

  • http://0xa9fea9fe/, http://2852039166/ or http://[::ffff:a9fe:a9fe]/;
  • fullwidth digits, or ideographic dots;
  • an invisible character inside it;
  • metadata.google.internal. with a trailing dot.

  Browsers, Node and curl all reach the metadata endpoint with those. AgentGuard now writes every host one standard way before matching, so the rule holds. The shipped agent blocks also deny GCE's metadata short name and AWS's IPv6 endpoint fd00:ec2::254.

• A tools/call without an id skipped the policy. The MCP gateway passed any message without an id straight to the MCP servers as a notification, so a tools/call sent that way reached them unchecked. This affected local and remote servers. Only real notifications are forwarded now.

• Tool arguments could hide the real command. The Python adapters (LangChain, CrewAI, MCP, OpenAI Agents) read command before cmd and path before file_path. A model sending {"command": "ls", "cmd": "rm -rf /"} to a tool that reads cmd got ls checked and rm -rf / run. Arguments that disagree like this are now denied. The OpenAI Agents adapter also checks exactly the arguments the tool will receive.

• require_prior failed open. If the history behind a require_prior condition couldn't be read, a deny or approval rule gated on it never fired. It now fires; an allow rule still doesn't.

Other fixes

• Audit replay.
  • Replay and its checkpoint could confuse two rotated audit files created in the same clock tick, which happens on Windows. Each file now has its own random id.
  • An audit line longer than 4 MiB stopped the startup replay, so the counters missed every later entry. The line is now counted as corrupt and skipped.
• Store backend. A since filter put entries that fell in the same second as the bound on the wrong side.
• Postgres. Starting a node took table locks on every boot, even when the schema was current. That no longer happens, and new indexes are built in the background, one replica at a time.
• SQLite. A disk fault while reading the database's shared-memory file crashed the server. With the updated SQLite driver, that one query fails and the server keeps running.

---

Breaking changes

None in the public API: no field, route, flag, subcommand or schema version was removed or renamed. Some behavior is stricter:

• require_prior with an unreadable history: deny and approval rules fire, and allow rules don't match. With no history configured at all, nothing changes.
• GET /v1/audit answers 400 to a since/until that isn't RFC 3339, or to an until before since. 1.3 ignored both parameters.
• Python adapters deny tool arguments whose command/cmd or path/file_path disagree.
• Shell commands are checked through bash -c, eval and launchers. A command that ran unchecked inside them now gets the same verdict as on its own.
  • Under an allowlist, sudo X is denied when X is denied.
  • A bash -c script AgentGuard can't split asks for approval.
• Domain rules match every spelling of a host. A rule without a port now matches its host on any port, through the domain field as well as URLs.
• The MCP gateway drops a message without an id unless it is a notifications/* message.

---

Upgrade notes

1. Check require_prior rules if your history lookups can fail. Run agentguard test with cases for them.
2. Upgrade. Rerun the one-line installer, agentguard setup → Update, or go install github.com/Caua-ferraz/AgentGuard/cmd/...@v1.4.0. The SQLite or Postgres store adds two columns on first start. Postgres builds the new indexes in the background; on SQLite a large audit table can make that first start slower.
3. Turn on sealing for an existing install with --audit-seal --audit-seal-key-file <file>. Keep the key somewhere the agent can't write.
4. Connect more agents from agentguard setup.

Details: MIGRATION.md § v1.3.x → v1.4.0.

---

Known limitations

• With the file audit backend, /v1/audit and /v1/sessions read only the live file. Use agentguard report or audit verify for rotated files.
• The audit log doesn't record approval time-outs or who resolved an approval, so the report marks them unknown.
• A Codex patch sent through a shell heredoc is denied as an unparseable command. That is the safe side, but you may see it.
• Sessions named . or .. can't be opened from the dashboard; use GET /v1/audit?session_id=.
• Some programs that run commands aren't looked into. These include find -exec, su -c, ssh host 'cmd', docker run, make and piping a script into a shell (… | bash), as well as interpreters (python -c, node -e). xargs rm -rf is checked as rm -rf without the arguments xargs adds. The full list is in POLICY_REFERENCE.md § Compound shell commands.
• Domain rules compare names, not where a name resolves. A DNS name that points at a blocked address isn't the address to a rule; block those at the network level.

---

Get started

curl -fsSL https://github.com/Caua-ferraz/AgentGuard/releases/latest/download/install.sh | sh
agentguard setup

# or
docker run -d -p 8080:8080 -e AGENTGUARD_API_KEY="$KEY" \
  -v agentguard-audit:/var/lib/agentguard ghcr.io/caua-ferraz/agentguard:1.4.0

pip install --upgrade "agentguardproxy==1.4.0"
npm install @lictorate/agentguard@1.4.0

Full change list: CHANGELOG.md § 1.4.0.

---

This discussion was created from the release AgentGuard v1.4.0.