protect-context

protect-context · Agent Guardrail Suite

Durable context, real evidence, and a brake pedal for AI coding agents.

protect-context keeps the rules, decisions, and proof-of-work an agent needs in front of it — then makes scope creep, unverified claims, and repeated failures visible *before* they cost you a session.

One project-local .agent-guard/ store · three interfaces backed by the same logic:

The suite is advisory-first. It records evidence and makes unsafe or repetitive behavior visible; it is not a sandbox and does not prove that a change is correct. SPEC.md is the frozen v1.0 contract.

Contents

• Why this exists
• What it does
• Quick start
• Install the pi extension
• Install the MCP server
• Install the Python CLI
• From source
• A 30-second tour
• Interface comparison
• Reference
• pi commands and tools
• MCP tools
• CLI
• Configuration
• Environment variables
• Runtime store and concurrency
• The 12 failure modes and what ships
• How it works
• Session lifecycle
• The brief
• Local recall
• Evidence and loop detection
• Scope audit
• Trust and provenance
• Context budget
• Development and validation
• Troubleshooting
• Limitations and security boundary
• Design sources
• Non-goals
• License

Why this exists

Long agent sessions fail in boring, expensive ways:

• the constraints you stated at minute two are gone by minute forty;
• "done" is claimed with no command output behind it;
• a "quick fix" quietly rewrites six unrelated files;
• decisions get re-litigated because nothing recorded the reasoning;
• the same failing command is retried until the context window dies.

protect-context treats those as state problems, not intelligence problems. A durable store plus three small habits — brief before work, evidence after work, journal when something is decided — removes most of the failure surface without turning the agent into a different agent.

What it does

Quick start

Python 3.10+ is required for the CLI and MCP server. Node 22.19+ is required only to validate the TypeScript extension from a checkout — pi supplies the extension's runtime modules, and the extension has zero npm runtime dependencies.

Install the pi extension

Installed from npm. The package declares "pi": { "extensions": ["./extension/index.ts"], "image": "./preview.png" } and the pi-package keyword required by the Pi package gallery:

pi install npm:protect-context

Try it for one run without adding it to settings

pi -e npm:protect-context

Install it through pi, not through npm install. The extension declares pi's host modules (@earendil-works/pi-ai, @earendil-works/pi-coding-agent, typebox) as "*" peer dependencies, as Pi requires; Pi suppresses peer installation for managed npm packages, while a plain npm install protect-context does not. The second path downloads the whole pi runtime and surfaces advisories from that tree, which belong to the host and not to this zero-runtime-dependency extension.

Remove any hand-installed copy first — a directory such as ~/.pi/agent/extensions/protect-context or .pi/extensions/protect-context, or pi remove npm:protect-context if that copy came from npm. Two copies register the same tool names, and pi drops the second one:

Error: Failed to load extension "…/.pi/npm/node_modules/protect-context/extension/index.ts":

Tool "guard_verify" conflicts with /home/you/.pi/agent/extensions/protect-context/index.ts

One error is reported per tool (guard_verify, guard_note, guard_contract_check, guard_status, guard_journal, guard_recall), so nothing from the npm copy loads until the other copy is gone.

Or copy/symlink the checkout into a trusted extension directory:

# Personal

mkdir -p ~/.pi/agent/extensions cp -r extension ~/.pi/agent/extensions/protect-context

Project-local (read after the project is trusted)

mkdir -p .pi/extensions cp -r extension .pi/extensions/protect-context

Start a session and you get a single-line status widget, a brief before the first turn, and five slash commands. No configuration file is needed: the extension seeds .agent-guard/config.json with the frozen defaults on first session start.

Install the MCP server

For pi with pi-mcp-adapter, add .mcp.json at the project root:

{

"mcpServers": { "protect-context": { "command": "/absolute/path/to/protect-context/.venv/bin/python", "args": ["-m", "protect_context.mcp_server"] } } }

The same stdio shape works in any generic MCP host. No checkout is needed either: uvx protect-context mcp runs the same server straight from PyPI. Set PC_SESSION_ID when several host sessions need distinct evidence and loop views:

{

"mcpServers": { "protect-context": { "command": "/absolute/path/to/protect-context/.venv/bin/python", "args": ["-m", "protect_context.mcp_server"], "env": { "PC_SESSION_ID": "my-session" } } } }

The MCP surface exposes the nine frozen v1.0 tools plus later read surfaces (guard_journal, guard_orientation, and guard_recall). Tools carry conservative MCP annotations; in particular guard_verify is marked destructive and open-world because it can run any shell command. Annotations are host hints, not enforcement — configure the host to require human approval for that tool.

Install the Python CLI

pip install protect-context      # or: pipx install protect-context

protect-context init # seed .agent-guard/ in the current project protect-context status protect-context verify "pytest -q" protect-context mcp # serve the MCP tools on stdio

The CLI and MCP server are distributed through PyPI; the npm package ships only the pi extension. Both read the same .agent-guard/ directory, so a project can use the extension in pi and scripted verification in CI at the same time.

From source

# Python package, CLI, MCP server, and Python tests

python3 -m venv .venv .venv/bin/python -m pip install -e ".[dev]"

Reproducible extension development checks (dev dependencies only)

npm ci --ignore-scripts npm run check

If the machine's default Node is older than 22.19, run the same checks with an ephemeral Node 22 binary after npm ci:

npx -y node@22 node_modules/typescript/bin/tsc --noEmit -p extension/tsconfig.json

npx -y node@22 --experimental-strip-types --test extension/test/*.test.ts

A 30-second tour

Excerpts from a real session in this repository.

Ask for the current state:

$ protect-context status

PC status · session default · git 91fad4d Δdiff +88/-8 · 6 files · verdict ok loops: none contract 12 constraints conventions: README.md Nudge: verify changes with guard_verify and cite the evidence id before claiming success.

Record proof instead of asserting it:

$ protect-context verify --timeout 180 npm run check

PC verify ev-0005 · exit 0 · ok · 1440ms cwd: /path/to/project cmd: npm run check digest: … Nudge: cite this evidence id when claiming success.

A pipeline or || true is still recorded with the shell's real exit code, but the report says UNTRUSTED and the CLI exits 1. That exit 0 is not proof.

Re-run the same failing command a third time and the brake engages:

$ protect-context verify "npm test"

PC verify blocked · npm test · 3 prior failures Nudge: change approach or gather new information — do not re-run unchanged.

What pi injects before the agent starts working (sections elided):

contract:

01-obey-instructions: Obey the owner's explicit instructions and stated constraints exactly; when instructions conflict, ask instead of guessing. 02-evidence-before-success: Never claim success without citing a fresh verification run (evidence id or pasted output) for the exact claim. … decisions:

• Use the atomic-mkdir lease, not fcntl alone; Python must interoperate with the extension. [locking,spec]

last verify: ev-0005 exit=0 'npm ru