Agent Permission Diff

Review coding-agent permission changes with the same discipline used for IAM and dependency changes. Agent Permission Diff reads local Claude Code, Codex CLI, and Cursor configuration, produces a redacted provider-neutral snapshot, and reports newly broadened capabilities.

Why this exists

Provider settings are powerful, distributed, and easy to change accidentally. A project may combine a sandbox mode, approval mode, shell rules, MCP servers, and user-level defaults. A text diff tells you that a line changed; this tool tells you whether the effective capability became broader, narrower, or uncertain.

This package deliberately sits below policy conversion and above raw file diffs. agent-permissions is a useful canonical policy/synchronization project; Agent Permission Diff instead creates reviewable snapshots and change evidence without rewriting provider configuration. It also complements provider-native configuration checks such as Claude settings, Claude permissions, Codex safe execution guidance, and Cursor MCP configuration.

Install

npm install --save-dev agent-permission-diff

Or run it without adding a dependency:

npx agent-permission-diff snapshot

Node.js 20 or newer is required.

Baseline workflow

Create the reviewed baseline, commit it, and inspect future changes:

npx agent-permission-diff snapshot
git add agent-permissions.lock.json
git commit -m "chore: record reviewed agent permissions"

# after a configuration change
npx agent-permission-diff diff
npx agent-permission-diff diff --markdown
npx agent-permission-diff diff --sarif > agent-permission-diff.sarif
npx agent-permission-diff diff --strict

The default scan reads project configuration only. Use --include-user when a review intentionally includes global settings. Existing baseline debt is not re-reported as a new change; the review is about the delta.

Example terminal output:

Agent Permission Diff

Configuration: project configuration
Permissions: 6
Changes: 1

1. [high] claude/write:permissions.allow - New write capability: Edit(src/**)
   Source: .claude/settings.json | Edit(src/**)

Exit status is 0 for no high/critical broadening, 1 when a high/critical broadening is found, and 2 for invalid command or policy input.

What is normalized

The adapters retain the original key, source, scope, evidence, and a confidence label (declared, effective_best_effort, or unknown). Values are redacted before output. Current categories include:

| Category | Examples | | --- | --- | | read, write | Claude Read, Edit, and Write rules | | shell | Claude Bash(...) rules | | approval, sandbox | Codex and Claude execution modes | | network, bypass | network access and bypass/danger flags | | mcp | configured MCP server commands and URLs | | unknown | fields the adapter cannot safely classify |

The mapping is intentionally conservative. It does not execute commands, contact MCP servers, or claim to reproduce every provider's hidden runtime precedence.

Commands

agent-perms snapshot [--cwd path] [--include-user]
agent-perms show [--cwd path] [--include-user] [--json|--markdown|--sarif]
agent-perms diff [--cwd path] [--include-user] [--baseline path] [--json|--markdown|--sarif]
agent-perms check --policy policy.json [--cwd path] [--include-user] [--json|--sarif]
agent-perms explain <number> [--cwd path] [--include-user]

snapshot writes agent-permissions.lock.json in the target project. --baseline accepts a different snapshot path. show and diff are read-only. check evaluates only newly broadened changes against a small, explicit policy file:

{
  "forbid": ["APD006", { "category": "network", "value": "*" }],
  "maxSeverity": "high",
  "requireDeny": ["rm -rf"]
}

Library API

import { diff, snapshot } from "agent-permission-diff";

const current = await snapshot(process.cwd(), { includeUser: true });
const changes = diff(previousSnapshot, current);

The exported types are schema-versioned so a CI service can store snapshots without depending on terminal formatting.

CI and SARIF

A simple GitHub Actions step can fail a review on high or critical broadening:

- run: npx agent-permission-diff diff --sarif > agent-permission-diff.sarif
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: agent-permission-diff.sarif

Scope and limitations

• Supported sources are the documented project/user configuration locations for Claude Code, Codex CLI, and Cursor.
• The scanner is offline and read-only; it never starts an agent or MCP process.
• Provider precedence and dynamically generated permissions can differ by version. Every finding carries source and confidence so uncertain mappings remain reviewable.
• Secrets are redacted heuristically. Do not treat the snapshot as a secret scanner.

Contributing

npm install
npm run lint
npm test
npm run test:cli

Issues and pull requests are welcome in the GitHub repository.

License

MIT © Debaditya Hait