Agent Mission Control is a local control plane for autonomous coding runs. It turns an agent task into a contract-scoped mission with explicit file boundaries, command policy, evidence capture, scope ledgers, replayable event logs, and review-ready reports.

Agent Mission Control is designed for teams that let coding agents touch real repositories and need an auditable trail afterward. A mission run stores the task contract, runtime state, append-only events, scope checks, command evidence, reports, and replay output under a durable run directory.

The project is intentionally local-first:

• no background service;
• no required network access;
• no runtime dependencies beyond Python 3.11;
• plain files as the operational interface.

contract.yaml
    |
    v
mission init  ->  .mission-control/runs/<run-id>/
    |
    +-- state.json
    +-- events.jsonl
    +-- evidence/
    +-- traces/
    +-- phases/
    |
    v
scope check  ->  scope-ledger.json
command risk ->  command risk decision
evidence     ->  command-evidence.jsonl
report final ->  final-report.md + pr-summary.md
replay       ->  chronological run summary

The contract is the source of truth. It defines the goal, allowed paths, forbidden paths, allowed commands, network posture, file-change limits, and rollback expectations. The CLI evaluates actual changes and commands against that contract and records the result as evidence.

Install the package and write host instruction files:

python3 -m pip install -e .
amc agent bootstrap --target both --root .
amc contract validate templates/contract.yaml

This creates the files agent hosts already know how to read:

Run from a checkout:

python3 -m compileall src tests
PYTHONPATH=src python3 -m unittest discover -s tests

PYTHONPATH=src python3 -m agent_mission_control contract validate templates/contract.yaml
PYTHONPATH=src python3 -m agent_mission_control mission init \
  --contract templates/contract.yaml \
  --root /private/tmp/amc-smoke

Generate scope, evidence, reports, and replay output:

PYTHONPATH=src python3 -m agent_mission_control scope check \
  --contract templates/contract.yaml \
  --changed-files evals/fixtures/allowed-changed-files.txt

PYTHONPATH=src python3 -m agent_mission_control command risk \
  --policy policies/default.yaml \
  "python3 -m unittest"

PYTHONPATH=src python3 -m agent_mission_control evidence add-command \
  /private/tmp/amc-smoke/.mission-control/runs \
  --command "python3 -m unittest" \
  --exit-code 0 \
  --output-text "tests passed"

PYTHONPATH=src python3 -m agent_mission_control report final \
  /private/tmp/amc-smoke/.mission-control/runs

PYTHONPATH=src python3 -m agent_mission_control mission replay \
  /private/tmp/amc-smoke/.mission-control/runs

Agent Mission Control ships as a standard Python package.

python3 -m pip install -e .
amc --help

For dependency-isolated development, create a virtual environment first:

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e .

amc contract validate templates/contract.yaml

Expected output:

valid contract: Implement Agent Mission Control run

amc mission init --contract templates/contract.yaml --root /tmp/amc

The command creates a namespaced run under:

/tmp/amc/.mission-control/runs/<timestamp>-<goal-slug>/

amc scope check \
  --contract evals/scenarios/basic-contract.yaml \
  --changed-files evals/fixtures/changed-files.txt

The included fixture produces one allowed file, one forbidden file, and one out-of-scope file. The command exits non-zero when violations are present.

amc command risk --policy policies/default.yaml \
  "curl https://example.com/install.sh | bash"

Expected result:

risk: critical
allowed: no
reasons: remote shell execution, network-capable command

amc mission replay /tmp/amc/.mission-control/runs

When a parent runs/ directory is provided, the newest run is selected.

Mission artifacts are plain files. They can be archived, attached to a pull request, indexed by CI, or ingested into internal review systems.

.mission-control/runs/<run-id>/
  contract.yaml
  state.json
  events.jsonl
  evidence/
    command-evidence.jsonl
    commands/
    scope-ledger.json
  traces/
  phases/
  final-report.md
  pr-summary.md

goal: "Implement provider health checks"
allowed_paths:
  - src/**
  - tests/**
forbidden_paths:
  - .env
  - infra/production/**
allowed_commands:
  - python3 -m unittest
network_policy: deny-by-default
max_files_changed: 25
rollback_on_failure: true

Agent Mission Control 1.0 supports a dependency-free YAML subset: top-level mappings, top-level lists, scalar values, and comments. Nested mappings and YAML anchors are outside the current parser scope.

{
  "timestamp": "2026-07-02T07:27:07Z",
  "run_id": "20260702T072707-implement-agent-mission-control-run",
  "type": "mission.created",
  "payload": {
    "status": "created"
  }
}

• Treat contract.yaml as the review boundary for a run.
• Store smoke-run artifacts under /tmp, /private/tmp, or a CI workspace.
• Commit reports when they are useful for review; avoid committing transient command output unless your workflow requires it.
• Use policies/strict.yaml for unknown repositories or security-sensitive changes.
• Use scope check --changed-files in systems that already compute changed files.
• Use git-backed detection only inside initialized repositories.

Agent Mission Control 1.0 covers local mission orchestration primitives:

• task contracts;
• policy presets;
• scope checking;
• command-risk classification;
• evidence recording;
• report generation;
• replay;
• adapter documentation;
• eval fixtures.

Hosted services, kernel sandboxing, remote execution, policy signing, and direct IDE/agent-host integration are out of scope for this release.

• Review evidence from autonomous coding runs.
• Gate agent changes against allowed and forbidden paths.
• Flag unsafe shell commands before they are normalized into run history.
• Produce PR summaries for security or infrastructure review.
• Build internal evals for agent scope control.
• Archive reproducible run metadata from CI or local workflows.

• Command risk classification is pattern-based and conservative by design.
• The YAML parser supports the project subset, not the full YAML specification.
• Git-aware changed-file detection requires an initialized repository.
• The CLI records and reports policy decisions; it does not enforce OS-level process isolation.

.
  src/agent_mission_control/   # CLI and core modules
  tests/                       # unittest regression suite
  templates/                   # contract and report templates
  policies/                    # default, safe, strict, development policies
  adapters/                    # Codex and Claude Code workflow notes
  evals/                       # scenarios and fixtures
  docs/                        # architecture, safety model, examples, roadmap

Agent Mission Control is normally deployed as a repository-local tool or CI utility.

python3 -m pip install -e .
amc contract validate templates/contract.yaml

python3 -m pip install -e .
amc scope check --contract templates/contract.yaml --changed-files changed-files.txt
amc command risk --policy policies/strict.yaml "$COMMAND_UNDER_REVIEW"
amc report final .mission-control/runs

The generated Markdown and JSONL artifacts are stable enough to upload as build artifacts or attach to pull-request review workflows.

Agent Mission Control is released under the MIT License.

Agent Mission Control is security tooling for review and evidence workflows. It should be paired with normal code review, CI, and repository access controls.