Your AI agent's diff looks fine. That's the problem.

Give an agent a simple task:

Add an optional loyalty discount to retail pricing. Enterprise pricing and the public API must stay unchanged.

Twenty minutes later it's done. Tests are green, the summary is confident. Along the way it also "cleaned up" a shared pricing helper — and in the diff, that looks like diligence, not scope creep.

Here's the uncomfortable part: the diff can't tell you the difference. Did the agent stay inside the intended subsystem? Did it touch the enterprise path? Did it introduce another clone of that helper? Did it modify the public API despite claiming otherwise? A green diff answers none of that.

So you either re-read every agent patch line by line — and lose the speed you adopted agents for — or you trust the checkmark and accumulate structural drift you'll find months later.

I've spent the last months building a third option. Today it shipped: CodeClone 2.1.0a1, the first public alpha of a Structural Change Controller for AI-assisted Python development.

Code review starts too late

By the time a diff exists, the agent has already made the important decisions: which files were relevant, which dependencies to follow, which abstractions to reuse, how far the task should spread through the repository.

The diff records the result of those decisions. It does not control them.

The missing layer looks like this:

Task

  → Intent

  → Blast Radius

  → Bounded Edit

  → Verification

  → Diff

CodeClone started as a deterministic structural analysis engine for Python — clones, complexity, coupling, cohesion, dead code, public API surface, all in one canonical report shared by the CLI, HTML report, SARIF, CI gates, and MCP server. Version 2.1 builds a change-control workflow on top of those facts:

analyze → start → edit → finish

The loop, on the loyalty-discount task

Before the edit, the agent declares its intent over MCP: "modify retail pricing to support an optional loyalty discount" with a concrete file scope. CodeClone answers with:

• the structural blast radius of that scope — what depends on it, what shares its structure;


• the split between allowed files and review context (files you should know about but not touch);


• explicit do-not-touch boundaries — the enterprise path and the public API surface go here;


• the available regression budget;


• and the one field that matters: edit_allowed: true | false.

The agent edits. Nothing about CodeClone writes or rewrites code — the agent works normally, just inside a declared boundary. Hosts that support hooks (Claude Code, Cursor) can hard-block file edits until a valid controlled change is active.

After the edit, finish resolves what actually changed and checks it against what was declared: scope reconciliation, structural regression verification between the before/after analysis runs, validation of the agent's own review claims, and an auditable review receipt.

Now the reviewer isn't reverse-engineering intent from a diff. They're reviewing a contract: here's what the agent said it would do, here's what it did, here's the evidence they match.

"What was declared" vs. "what happened"

The record connecting the two is called the Patch Trail, and it lets a reviewer distinguish situations that look identical in a diff:

The agent changed exactly what it declared.

The agent declared a broad scope but changed only part of it.

The agent crossed an explicit boundary.

The agent expanded scope and recorded that expansion.

The patch passed tests but failed its structural contract.

That last line is the whole point. A correct patch can still be produced through an uncontrolled process. "Tests passed" was never evidence that the change was well-bounded.

No LLM grading its own homework

One design rule runs through everything: CodeClone never asks a model whether a change is safe.

"LLM reviews LLM" has a correlated failure mode — the same plausible rationalization that convinced the coding agent will convince the reviewing agent. So every boundary, gate, and verification here comes from deterministic repository facts: same input, same answer, every time.

That includes the agent's prose. A claim like "no structural regressions" requires structural evidence from the before/after runs — a claim-validation step flags anything the evidence doesn't support. An agent cannot talk its way past a scope check.

Agents forget — twice

Two more pieces shipped in this alpha, and they exist because agents forget in two different ways.

Within a session, they grep. Watch an agent in a large repo: grep, read, grep again, rebuild the architecture from scratch, every time — slow, token-hungry, and wrong just often enough to be dangerous. Live Implementation Context replaces the ritual: one call returns bounded structural context from the current analysis run — call relationships, contracts in play, test anchors, freshness, and any active intent boundaries in the workspace. No separate index to maintain, nothing to go stale. And it's deliberately read-only: context informs the agent, it never authorizes an edit.

Across sessions, they start cold. The next agent re-learns that this schema is public, that this helper is intentionally duplicated, that this refactor was attempted before and failed — or worse, it doesn't, and repeats the failure. Engineering Memory is a local SQLite-backed, typed, evidence-linked knowledge layer: architecture decisions, risk notes, contract anchors, rationales from previous controlled changes.

The governance rule makes it safe: agents propose, humans promote. Agent-created knowledge stays a draft until a human approves it (there's a VS Code Memory view for exactly that). And memory can warn an agent that its plan contradicts a recorded decision — but it can never authorize an edit, expand a scope, or override a finding.

Also in the alpha

A few things I'll write about separately, in one paragraph each:

Agent trajectories. Since intents, tool calls, verification results, and Patch Trails are all recorded, CodeClone can rebuild deterministic trajectories of how agents actually worked. This is already showing that different agents have different failure signatures under the same governance layer — some repair every small regression, some leave unfinished intent state behind. Not a model leaderboard; a concrete way to improve prompts, tool descriptions, and recovery paths.

Multi-agent coordination. Real workspaces have a Claude session, a Codex run, and a human with unsaved changes in the same tree. Intents queue instead of colliding, ownership is lease-bound, abandoned work is recoverable, and no agent can claim another's changes as its own evidence.

Platform Observability. An opt-in, dev-only diagnostics layer that watches CodeClone itself — DB query shapes, MCP payload pressure, worker chains, costly no-ops. It already caught real problems in this release (semantic reindexing firing too eagerly; a relationship-analysis pass that could fold into the main module walk).

Integrations. Native setups for Claude Code, Claude Desktop, Codex, Cursor, and VS Code, over a 38-tool MCP surface with deterministic next-step guidance built into the schemas.

Try it

The alpha is on PyPI as a prerelease:

python -m pip install --pre codeclone

# or

uv tool install --prerelease allow codeclone

Then:

codeclone setup doctor   # guided environment check

codeclone .              # first analysis run

For agents and IDEs, the MCP server ships as an extra:

uv tool install --prerelease allow "codeclone[mcp]"

codeclone-mcp --transport stdio

Everything runs locally — no hosted service, no cloud account, no code leaving your machine. If you're upgrading from 2.0.x, the workspace moved from .cache/codeclone/ to .codeclone/, and the full contract changes are in the [changelog(