agent-change-control

agent-change-control is a small Python package for evaluating agent-generated code changes before they become merge candidates.

1. What problem does this solve?

“Agent-generated patches can pass tests and still be unsafe to merge.”

2. What does this repo do?

“Surface policy, isolated sandbox, scorecarding, and strict re-audit before merge.”

3. What does it not claim?

“Trusted local/CI evaluation only. Not hostile-code isolation.”

Alpha release. Intended for trusted local/CI evaluation, not hostile-code isolation.

It focuses on a narrow workflow:

1. classify the files a proposal wants to touch
2. generate a deterministic patch proposal object
3. run the proposal in an isolated local workspace
4. build a readable scorecard from sandbox results
5. perform a strict re-audit before anything is considered merge-eligible
6. sanitize reasoning payloads so hidden controller writes are not treated as normal model output

State Flow

flowchart LR
    proposal["proposal"] --> sandbox["sandbox"]
    sandbox --> scorecard["scorecard"]
    scorecard --> reaudit["re-audit"]
    reaudit --> accept["accept"]
    reaudit --> review["human_review"]
    reaudit --> reject["reject"]

Loading

What It Is

This package is a reusable change-control kernel for trusted local development and CI environments.

It helps answer questions like:

• Is this proposal touching protected surfaces?
• Did the sandboxed checks pass?
• Does this proposal still require human review even if tests passed?
• Does the reasoning payload contain forbidden hidden-controller style directives?

What It Is Not

This package is not:

• a hardened sandbox for hostile arbitrary code
• a full repository governance system
• a merge bot
• a guarantee that passing tests means a patch is safe

The sandbox runner is meant for trusted local or CI evaluation of proposed changes. It isolates files and commands from the original source tree, but it does not claim strong containment against malicious code.

Basic Workflow

from agent_change_control import ProposalEvaluator, ProposalGenerator

generator = ProposalGenerator()
proposal = generator.generate_patch_proposal(
    summary="Adjust a proposal draft",
    rationale="Exercise the isolated evaluation flow.",
    target_files=["proposals/sample.py"],
    mode="offline",
    file_overrides={"proposals/sample.py": "VALUE = 2\n"},
    commands=['python -c "from proposals.sample import VALUE; assert VALUE == 2"'],
)

evaluation = ProposalEvaluator().evaluate(
    proposal=proposal,
    source_dir=".",
)

print(evaluation.scorecard.verdict)
print(evaluation.strict_reaudit.status)

Why "Tests Passed" Is Not The Same As "Safe To Merge"

A proposal can pass all sandbox checks and still be ineligible for automatic merge.

Examples:

• it touches protected or offline-only surfaces
• it changes core runtime entry points
• it relies on reasoning payload fields that should never be accepted as ordinary model output

The scorecard therefore distinguishes between:

• tests_passed
• requires_human_review
• merge_eligible

Surface Policy

The default SurfacePolicy is a generic reference policy, not a private repository rule set:

• online edits to packaging and workflow control files are blocked
• proposal-like paths such as proposals/, drafts/, and experiments/ are weakly allowed
• everything else defaults to offline-only review unless you configure a different policy

You can inject your own policy when generating proposals or validating paths.

Sandbox Trust Boundary

SandboxRunner copies files into a temporary workspace, applies proposal overrides there, and runs the requested commands against the copy.

By default it runs in strict mode: if none of the requested paths can be prepared, the run fails instead of silently copying the whole repository.

This preserves the original source tree, but it does not make untrusted code safe. Use it for trusted local evaluation, not as a hostile-code security boundary.

Running The Tests

From this directory:

python -m pip install -e .[dev]
python -m pytest -q

Examples

• examples/accept_patch_flow.py shows an accept path on a weakly allowed surface.
• examples/human_review_patch_flow.py shows a passing sandbox run that still lands in human_review.