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

python -m pip install "agent-self-edit-gate==0.1.1"
git clone --depth 1 --branch v0.1.1 \
  https://github.com/korovin-aa97/agent-self-edit-gate.git
cd agent-self-edit-gate
bash examples/demo.sh

The demo performs an allowed exact edit, verifies its two receipts, and proves
that a protected .github/workflows path is denied.

Install from PyPI for normal use:

python -m pip install "agent-self-edit-gate==0.1.1"
selfedit-gate --version

Quickstart

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

evaluation_root=$(mktemp -d)
mkdir -p "$evaluation_root/.agents"
cp profiles/generic.toml "$evaluation_root/selfedit-policy.toml"
printf '%s\n' 'Review code carefully.' > "$evaluation_root/.agents/reviewer.md"
cd "$evaluation_root"

selfedit-gate --policy selfedit-policy.toml check .agents/reviewer.md

root = "." is relative to the policy file, so copy a reviewed profile into the
repository root instead of using it in place from the cloned profiles/
directory. For an exact edit, put the one expected old fragment and replacement
in regular files:

printf '%s\n' 'Review code carefully.' > old.txt
printf '%s\n' 'Review code and cite evidence.' > new.txt
selfedit-gate --policy selfedit-policy.toml replace .agents/reviewer.md old.txt new.txt
selfedit-gate --policy selfedit-policy.toml verify-receipts

For a bounded whole-file update:

printf '%s\n' 'Review code, tests, and docs.' > proposed-reviewer.md
selfedit-gate --policy selfedit-policy.toml write \
  .agents/reviewer.md proposed-reviewer.md
printf '%s\n' 'Review all evidence.' | \
  selfedit-gate --policy selfedit-policy.toml write .agents/reviewer.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

The hero condenses the protocol to requested edit → guarded write → verifiable
receipt. The complete order is:

1. Receive the requested edit.
2. Classify its path, with deny rules taking precedence.
3. Bound the content and hash the current target.
4. Persist and fsync an intent receipt.
5. Recheck the policy and target identity.
6. Atomically replace the target and fsync its directory.
7. Persist and fsync a commit receipt.
8. Verify the result independently.

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.