tracegate 0.1.0

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 --format codex ~/.codex/archived_sessions/session.jsonl
PYTHONPATH=src python3 -m tracegate.cli import codex ~/.codex/archived_sessions/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.
• import codex converts a Codex session 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.

Cost
----
$1.12

Example policy gate

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

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 and Codex session JSONL traces.

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

forbidden_tools:
  - shell

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

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

Current checks:

• limits.max_cost_usd
• limits.max_runtime_minutes
• 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.

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. Claude Code transcript adapter
2. OpenAI trace adapter
3. LangGraph run adapter
4. SARIF or GitHub Actions output for CI annotations
5. HTML report for humans
6. 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.