Agent Self-Edit Gate

Policy-enforced self-edit gateway for coding agents: let agents improve prompts and skills without rewriting permissions, hooks, or enforcement.

[!IMPORTANT] The CLI is an enforcement boundary only when a sandbox, OS policy, or protected broker makes it the agent's only writer. With unrestricted shell or filesystem access, an agent can bypass it. Read the threat model before deployment.

Coding-agent behaviour and authority often live side by side:

.claude/skills/reviewer/SKILL.md   behaviour: may improve
.claude/settings.json             authority: must not self-edit
.codex/agents/reviewer.toml       behaviour: may improve
.codex/config.toml                authority: must not self-edit

Agent Self-Edit Gate puts a deterministic write path between “the agent wants to edit itself” and “the repository accepts that edit.” Policy is plain TOML; decisions never depend on an LLM. Accepted writes are atomic and leave a two-phase, hash-chained receipt.

15-second demo

git clone --branch v0.1.0 https://github.com/korovin-aa97/agent-self-edit-gate.git
cd agent-self-edit-gate
python -m pip install .
cp selfedit-policy.example.toml selfedit-policy.toml

selfedit-gate check .claude/agents/reviewer.md
# mutable: .claude/agents/reviewer.md (behaviour)

selfedit-gate check .claude/settings.json
# selfedit-gate: E_ZONE_DENIED: ... is immutable by zone authority

PyPI publication follows once trusted publishing is activated. Until then, install the GitHub release wheel or directly from the tagged source:

python -m pip install \
  "agent-self-edit-gate @ git+https://github.com/korovin-aa97/agent-self-edit-gate@v0.1.0"

Quickstart

Agent Self-Edit Gate supports Python 3.12+ on Linux and macOS.

python -m venv .venv
source .venv/bin/activate
git clone --branch v0.1.0 https://github.com/korovin-aa97/agent-self-edit-gate.git
cd agent-self-edit-gate
python -m pip install .
cp profiles/generic.toml selfedit-policy.toml
selfedit-gate --policy selfedit-policy.toml check AGENTS.md

For an exact edit, put the one expected old fragment and replacement in files:

printf '%s\n' 'Run tests before handoff.' > old.txt
printf '%s\n' 'Run lint, types, and tests before handoff.' > new.txt
selfedit-gate --policy selfedit-policy.toml replace AGENTS.md old.txt new.txt
selfedit-gate --policy selfedit-policy.toml verify-receipts

For a bounded whole-file update:

selfedit-gate --policy selfedit-policy.toml write AGENTS.md proposed-AGENTS.md
cat proposed-AGENTS.md | selfedit-gate --policy selfedit-policy.toml write AGENTS.md -

Add --json before the command for machine-readable success or stable error codes. Refusals exit 2; a successful command exits 0. See the error-code reference for automation.

Policy in one screen

schema_version = 1

[gate]
root = "."
receipt_log = ".selfedit-gate/receipts.jsonl"
max_bytes = 262144
max_changed_bytes = 65536
allow_create = false

[[zones]]
name = "behaviour"
mode = "mutable"
patterns = ["AGENTS.md", ".agents/**/*.md"]
extensions = [".md"]

[[zones]]
name = "authority"
mode = "immutable"
patterns = ["selfedit-policy.toml", ".selfedit-gate/**", ".github/**"]

Protected and immutable matches always override mutable matches. The gate also refuses traversal, symlink components, unsupported extensions, non-UTF-8/NUL content, oversized files/diffs, ambiguous replacement anchors, owner/type changes, policy swaps, target races, and audit failures.

See the complete policy reference and ready-to-copy generic, Claude Code, and Codex profiles.

What happens on a write

flowchart LR
    A["Requested edit"] --> B["Classify path\ndeny before allow"]
    B --> C["Bound content\nand hash target"]
    C --> D["fsync intent\nreceipt"]
    D --> E["Recheck policy\nand target identity"]
    E --> F["Atomic replace\nand directory fsync"]
    F --> G["fsync commit\nreceipt"]
    G --> H["Independent verifier"]

Every receipt names the exact policy, before bytes, proposed bytes, operation, and prior receipt hash. A crash between intent and commit leaves a dangling intent that verification refuses. Details and canonicalization rules are in the receipt protocol.

Where enforcement comes from

The deployment guide describes each pattern without pretending a CLI can sandbox its own caller.

Scope compared with adjacent tools

The dated landscape check cites direct sources and explains the positioning. This is not a generic “AI firewall.”

Security limits

• Receipts are tamper-evident hash chains, not signatures or identities.
• Allowed prompt content can still be malicious; the gate controls where and how much, not semantic safety.
• Network filesystems and Windows are unsupported in v0.1.
• v0.1 has not received an independent professional security audit.
• Recovery from a dangling intent is deliberately manual.

Please use GitHub private vulnerability reporting, not a public issue, for suspected vulnerabilities.

Development

git clone https://github.com/korovin-aa97/agent-self-edit-gate.git
cd agent-self-edit-gate
uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run mypy src tests
uv run pytest --cov=selfedit_gate --cov-report=term-missing
uv build

The runtime has no third-party dependencies. See CONTRIBUTING.md, the changelog, and the public roadmap.

Origin and license

Built from operating a mixed Claude/Codex production fleet, then extracted as a narrow standalone tool without fleet orchestration, telemetry, or hosted control plane.

Licensed under Apache-2.0.