Agent Guardian

Agent Guardian is the pre-commit review layer for coding agents.

Its job is not to be a generic lint bundle. Its job is to answer the questions an agent actually needs answered before it keeps going:

• Did my diff leak a secret?
• Did I introduce a risky dependency or break a public export?
• Did I add generated junk, oversized artifacts, or suspicious code patterns?
• Is this change safe enough to continue, or should I stop and fix it now?

The long-term goal is a deterministic, diff-first safety layer that agents run constantly during implementation, not just at the end.

Product thesis

Strong coding agents do not fail only because they cannot write code. They also fail because they move too quickly through risky changes without a reliable review loop.

Traditional linting and SAST tools are not enough:

• they often scan the whole repo instead of the actual change surface
• they produce noise from pre-existing debt
• they are not designed for agent handoffs or session continuity
• they rarely answer the operational question: "should I keep going right now?"

Agent Guardian exists to provide that loop.

What "good" looks like

In the ideal flow:

1. An agent edits code.
2. Agent Guardian reviews the staged, unstaged, and untracked change surface.
3. It returns a compact verdict with precise blocking findings.
4. The agent fixes critical issues before handing off or committing.
5. Important findings and decisions are recorded into Agent Memory.
6. The next agent resumes with both implementation context and review context.

The next session should not need to rediscover the same obvious risks.

Current status

The current implementation already has a useful nucleus:

• deterministic checks for secrets, dependencies, API surface, complexity, patterns, and large files
• a TypeScript CLI and MCP server
• schema validation with zod
• unit tests around the current heuristics
• local .mcp.json wiring into the rest of Agent Toolkit

But it is not yet the definitive product.

The dogfood demo proves the full loop works end to end:

npm run demo:dogfood

See docs/DEMO.md for details on the demo scenario and how to use Guardian in Claude Code and Codex workflows.

Recent completions (AG-201 through AG-205):

• untracked files are now reviewed alongside staged and unstaged changes
• findings are diff-aware — only changed lines are flagged, not legacy debt
• every built check is individually callable through MCP
• review config persists to .guardian.json at the repo root with deep-merge layering
• config discovery uses git rev-parse --show-toplevel — works from any subdirectory
• partial config updates preserve sibling fields (deep merge, not shallow replace)
• accepted debt can be suppressed via deterministic baseline entries
• review outcomes are automatically recorded into local .agent-memory
• review fingerprints include full finding identity (file, line, message, severity) so materially different outcomes are never falsely deduplicated
• active-task resolution is deterministic: exactly one active task required, multiple active tasks cause an explicit skip rather than arbitrary selection
• deduplication prevents identical consecutive events; clean passes after warnings/fails are recorded as verification events
• memory write failures never block or corrupt the review result

Recent completions (AG-207 through AG-211):

• dependency delta analysis scoped to the change surface with optional audit enrichment
• SARIF 2.1.0 output for CI code-scanning upload (--format sarif)
• review-comment JSON output for PR annotation adapters (--format review-comments)
• CLI --format text|json|sarif|review-comments and --output <path> flags
• coordinator-aware preflight_edit MCP tool that checks for overlapping claims
• barrel-file and re-export aware API surface modeling (export *, export { } from)
• explicit verdict/policy profiles: advisory, balanced, strict

Docs

• ROADMAP.md - product roadmap and delivery phases
• PAIN-POINTS.md - the concrete agent failures this tool must remove
• docs/IDEAL-GUARDIAN.md - what the finished product should feel like
• docs/BACKLOG.md - execution order for the next implementation slices
• docs/DEMO.md - dogfood demo: how to run it, what it proves

Relationship to Agent Memory

agent-memory-kit stores durable execution context.

agent-guardian should eventually store durable review context:

• what risk was found
• what was fixed or waived
• what remains open
• what patterns keep recurring across sessions

As of AG-205, reviewChanges() automatically records review outcomes into the local .agent-memory directory. The adapter discovers the active task, writes structured events with provenance, and deduplicates identical consecutive results. Memory write failures are handled gracefully and never block the review result.

Development workflow

This repo uses Agent Memory in local mode via .mcp.json.

On a fresh clone or empty memory directory:

npm run bootstrap:memory

Recommended workflow for every serious iteration:

1. boot_context()
2. Read README.md, ROADMAP.md, PAIN-POINTS.md, and docs/
3. If memory is empty or unresolved, run npm run bootstrap:memory
4. Execute the next task from docs/BACKLOG.md
5. Record decisions, blockers, and verification in memory
6. Run npm run verify
7. finalize_node(summary="...")

Treat memory as mandatory for product and architecture work. If the repo direction changed and memory stayed silent, the next agent starts colder than it should.

Current status

The core Guardian hardening sequence (AG-201 through AG-206) is complete:

• AG-201 trustworthy diff collection
• AG-202 diff-aware findings
• AG-203 full MCP tool coverage
• AG-204 persistent config and baselines
• AG-205 memory-backed review recording
• AG-206 end-to-end dogfood demo

Pain-point closure sequence:

• AG-207 dependency delta analysis ✓
• AG-208 SARIF / review-comment output ✓
• AG-209 coordinator-aware guarded actions ✓
• AG-210 barrel/re-export API surface modeling ✓
• AG-211 verdict / policy profiles ✓

All planned work items are complete. Agent Guardian is feature-complete.

Long-term promise

The real promise is not "more checks."

It is:

"Give coding agents a fast, trustworthy review loop that catches costly mistakes before those mistakes become commits, handoffs, or production bugs."