tracegate 0.1.5

Inspect and policy-check AI agent runs.

Tracegate

Policy gates for AI agent traces.

tracegate is an audit and policy CLI for AI agent runs.

It does not try to be a new agent runtime. The first useful version is forensic: give it a trace from an existing agent system and it tells you what happened, what tools were used, what looked risky, what it cost, and whether the run violated policy.

That is the practical starting point for a "control plane for agents":

Existing agent run -> normalized trace -> inspection -> policy findings -> CI exit code

Why this exists

Teams are already using Claude Code, Codex, OpenAI Agents, LangGraph, CrewAI, and custom agent loops. The common questions are not just orchestration questions:

• What did the agent do?
• Which tools did it use?
• Did it read or edit sensitive files?
• Did network content influence shell or GitHub actions?
• How much did it cost?
• Can this run pass a production policy gate?

tracegate starts with those governance questions.

Current commands

Run from this repository without installing:

PYTHONPATH=src python3 -m tracegate.cli inspect examples/run.json
PYTHONPATH=src python3 -m tracegate.cli describe examples/run.json
PYTHONPATH=src python3 -m tracegate.cli check examples/run.json examples/policy.yaml
PYTHONPATH=src python3 -m tracegate.cli guard examples/run.json examples/policy.yaml
PYTHONPATH=src python3 -m tracegate.cli summarize examples/run.json --json
PYTHONPATH=src python3 -m tracegate.cli summarize examples/run.json --json --include-raw
PYTHONPATH=src python3 -m tracegate.cli inspect examples/run.json --verbose
PYTHONPATH=src python3 -m tracegate.cli diff safe.json risky.json
PYTHONPATH=src python3 -m tracegate.cli inspect --format codex ~/.codex/archived_sessions/session.jsonl
PYTHONPATH=src python3 -m tracegate.cli import codex ~/.codex/archived_sessions/session.jsonl --out run.json
PYTHONPATH=src python3 -m tracegate.cli inspect --format claude ~/.claude/projects/<project>/<session>.jsonl
PYTHONPATH=src python3 -m tracegate.cli import claude ~/.claude/projects/<project>/<session>.jsonl --out run.json

After packaging/installing, the same commands are available as:

tracegate inspect examples/run.json
tracegate guard examples/run.json examples/policy.yaml

Command aliases:

• inspect, describe, and summarize inspect a trace.
• check, guard, and policy evaluate a trace against policy.
• diff compares attack surface and risk between two traces.
• import codex converts a Codex session JSONL file into generic tracegate trace JSON.
• import claude converts a Claude Code project transcript JSONL file into generic tracegate trace JSON.

check / guard / policy exit with code 1 when policy violations are found, which makes them usable in CI.

Example inspection

PYTHONPATH=src python3 -m tracegate.cli inspect examples/run.json

Example output:

Agent: PR Reviewer
Run ID: run-123

Observed Access
---------------
Filesystem: observed (3)
GitHub: observed (1)
Shell: observed (1)
WebFetch: observed (1)

Actions
-------
2 file reads
1 file writes/edits
1 shell commands
1 network fetches
1 GitHub actions

Security
--------
LOW: Prompt injection marker observed: ignore previous instructions
MED: Network content was fetched before a shell command executed.

Risk Posture
------------
MEDIUM

Reason
------
Shell access was used 1 times.
Filesystem read access was used 2 times.
Filesystem write access was used 1 times.
Network fetch access was used 1 times.

Shell Activity
--------------
1 commands

Read-only:            0
Execution:            1
Network:              0
Privilege escalation: 0
Destructive:          0

LOW   low-risk commands: 0
MED   medium-risk commands: 1
HIGH  high-risk commands: 0

Attack Surface
--------------
External Content:   PRESENT
Filesystem:         LOCAL READ/WRITE
Sensitive Files:    NONE
Privileged Actions: SHELL EXECUTION
Network Access:     PRESENT
Credential Access:  NONE

Known Patterns
--------------
SAFE: Filesystem -> Shell (1)
  Local file context preceded local shell execution.
HIGH: WebFetch -> Shell (1)
  External content preceded shell execution.
HIGH: WebFetch -> GitHub (1)
  External content preceded repository action.

Capability Profile
------------------
Filesystem Read:    LOW
Filesystem Write:   HIGH
Shell:              LOW
Network:            HIGH
GitHub:             HIGH
MCP/Discovery:      NONE

Overall Exposure: HIGH

Trust Boundaries
----------------
User Input
  ↓
External Content (1)
  ↓
Filesystem Reads (2)
  ↓
Agent Reasoning
  ↓
Shell Commands (1)
  ↓
Filesystem Writes (1)
  ↓
GitHub Actions (1)

Cost
----
$1.12

Example policy gate

PYTHONPATH=src python3 -m tracegate.cli guard examples/run.json examples/policy.yaml

Example diff

PYTHONPATH=src python3 -m tracegate.cli diff safe.json risky.json

Example output:

New Attack Surface
------------------
+ External Content
+ SHELL EXECUTION

Risk Change
-----------
LOW -> HIGH

Reason
------
External content can now influence privileged or write-capable actions.

New Patterns
------------
+ HIGH: WebFetch -> Shell

Example output:

FAILED

Violations
----------
HIGH: Run cost $1.12 exceeds policy limit $1.00.
HIGH: Tool Shell is forbidden by policy.
HIGH: Flow WebFetch -> Shell is forbidden by policy.
HIGH: Flow WebFetch -> GitHub is forbidden by policy.

Input Formats

The current adapters accept generic tracegate JSON/JSONL traces, Codex session JSONL traces, and Claude Code project transcript JSONL traces.

Claude Code Sessions

Claude Code support is opt-in with --format claude:

PYTHONPATH=src python3 -m tracegate.cli inspect --format claude ~/.claude/projects/<project>/<session>.jsonl
PYTHONPATH=src python3 -m tracegate.cli guard --format claude ~/.claude/projects/<project>/<session>.jsonl examples/policy.yaml

You can also convert a Claude Code transcript to normalized generic trace JSON:

PYTHONPATH=src python3 -m tracegate.cli import claude ~/.claude/projects/<project>/<session>.jsonl --out run.json

The Claude adapter currently maps:

• Bash tool uses to Shell
• Read tool uses to filesystem reads
• Edit, MultiEdit, and Write tool uses to filesystem edits/writes
• Playwright browser navigation MCP tool uses to network fetches
• user/assistant/system messages to message events
• other tool uses to generic tool events
• discovery/planning tools such as ToolSearch, ListMcpResourcesTool, TaskCreate, and TaskUpdate to Tool Discovery

Codex Sessions

Codex support is opt-in with --format codex:

PYTHONPATH=src python3 -m tracegate.cli inspect --format codex ~/.codex/archived_sessions/session.jsonl
PYTHONPATH=src python3 -m tracegate.cli guard --format codex ~/.codex/archived_sessions/session.jsonl examples/policy.yaml

You can also convert a Codex session to normalized generic trace JSON:

PYTHONPATH=src python3 -m tracegate.cli import codex ~/.codex/archived_sessions/session.jsonl --out run.json

The Codex adapter currently maps:

• exec_command function calls to Shell
• apply_patch custom tool calls to filesystem edits
• user/agent messages to message events
• other function/custom tool calls to generic tool events

Generic Trace Format

JSON object:

{
  "id": "run-123",
  "agent": "PR Reviewer",
  "cost_usd": 1.12,
  "runtime_minutes": 7,
  "events": [
    { "type": "file_read", "path": "src/app.py" },
    { "type": "network_fetch", "url": "https://example.com" },
    { "type": "tool_call", "tool": "shell", "input": { "command": "pytest" } },
    { "type": "git_action", "tool": "github", "action": "create_pr" }
  ]
}

JSON array:

[
  { "type": "file_read", "path": "src/app.py" },
  { "type": "tool_call", "tool": "shell", "input": { "command": "pytest" } }
]

JSONL:

{"type":"file_read","path":"src/app.py"}
{"type":"tool_call","tool":"shell","input":{"command":"pytest"}}

Supported event categories today:

• Filesystem: file_read, file_write, file_edit, write_file, read_file
• Shell: tool: shell, tool: bash, type: shell_command
• Web fetch: network_fetch, web_fetch, webfetch, tool: WebFetch
• GitHub: tool: github, tool: gh, git_action

Unknown event types are still preserved and counted.

Policy format

Policies can be YAML or JSON. The YAML parser intentionally supports only the simple policy shape used by this project, so use JSON if you need richer syntax.

limits:
  max_cost_usd: 5
  max_runtime_minutes: 30

max_shell_commands: 5
allow_network: false
allow_file_writes: false

forbidden_tools:
  - shell

forbidden_paths:
  - ".env*"
  - "secrets/*"

forbidden_flows:
  - WebFetch->Shell
  - WebFetch->GitHub

Current checks:

• limits.max_cost_usd
• limits.max_runtime_minutes
• max_shell_commands
• allow_network
• allow_file_writes
• forbidden_tools
• forbidden_paths using shell-style globs matched against both full path and basename
• forbidden_flows

If a policy sets a cost or runtime limit and the trace does not include that telemetry, tracegate reports a policy finding. Unknown cost or runtime should not silently pass a governance gate.

JSON output is sanitized by default. It includes normalized event metadata, but omits each event's raw payload and redacts shell command text so traces can be attached to CI logs with less risk. Use --include-raw only when you explicitly want a forensic export that may contain prompts, command text, URLs, or other sensitive trace data.

Human inspection output hides exact shell commands by default. Use --verbose when you need command-level evidence in the terminal report.

Built-in security findings

Inspection currently flags:

• Prompt injection markers such as "ignore previous instructions"
• Web fetch followed by shell execution
• Web fetch followed by GitHub action
• Sensitive-looking file paths such as .env, *.pem, *.key, *secret*, *credential*, *id_rsa*, and *kubeconfig*

These are heuristics, not a full security engine. The point is to expose the risk pattern in a run report and make it enforceable through policy.

Tests

PYTHONPATH=src python3 -m unittest discover -s tests

What should come next

The next valuable additions are adapters, not a scheduler:

1. OpenAI trace adapter
2. LangGraph run adapter
3. SARIF or GitHub Actions output for CI annotations
4. HTML report for humans
5. Admission-style preflight checks for proposed agent configs

The adoption path should stay simple: do not require teams to migrate runtimes before they can get audit, policy, and observability value.