tracegate 0.1.6

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.

TraceGate checks whether coding-agent runs stayed inside their allowed trust boundary.

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 new capabilities, new inferred flows, 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

Facts
-----
Shell commands: 1
Filesystem reads: 2
Filesystem writes: 1
Network fetches: 1
GitHub actions: 1

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

Risk Posture
------------
HIGH

Reason
------
Shell was used 1 time, including 1 execution command.
Filesystem read access was used 2 times.
Filesystem write access was used 1 time.
Network fetch access was used 1 time.
GitHub actions were used 1 time.

Assessment
----------
This session includes external content followed by action-capable behavior.
The agent ran local execution commands.
No credential access, privilege escalation, or destructive commands were observed.

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

Config inspection:     0
Local data inspection: 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
Agent Config Access:   NONE
Execution Surface:     SHELL
Privilege Escalation:  NONE
Destructive Actions:   NONE
Network Access:        PRESENT
Credential Access:     NONE

Inferred Patterns
-----------------
HIGH [HIGH confidence]: WebFetch -> Shell (1)
  External content preceded shell execution.

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 Capabilities
----------------
+ External Content
+ Shell Execution

New Flows
---------
+ HIGH: WebFetch -> Shell (HIGH confidence)

Risk
----
LOW -> HIGH

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

Example output:

Policy
------
FAIL

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
allow_git_actions: false
allow_sensitive_files: false

forbidden_tools:
  - shell

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

forbidden_flows:
  - ExternalContent->Shell
  - ExternalContent->FileWrite
  - ExternalContent->GitHub

Current checks:

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

Passing policies include a control summary:

Policy
------
PASS

Assessment
----------
This run stayed inside the configured trust boundary.

Checks
------
Shell commands: 11 / 20
Network access: none
File writes: none
GitHub actions: none
Sensitive files: none
Forbidden flows: none

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.