aegis-hooks

Aegis

Hooks-based policy enforcement + accountability for AI coding agents. Aegis evaluates every action an agent attempts — at the runtime's hook boundary, before the action executes — against declarative policy and returns allow / deny / ask. Enforcement runs outside the model's context window in a separate process, so a prompt injection or jailbreak cannot override a denied action: the model isn't the thing being asked. (It's a policy layer, not a sandbox — see Limitations.)

It ships secure-by-default: with zero configuration it blocks the catastrophic, irreversible actions an agent can take with your privileges — destructive SQL and migrations, secret exfiltration, recursive deletes, history-rewriting git, persistence installs, and uncontrolled sub-agent fan-out — and it detects rogue agent sessions (unidentified processes claiming an agent name without a valid cryptographic token) and reaps them in enforce mode. Everything beyond that is configurable, and the rule engine is a plugin platform: individuals, orgs, and MCP providers add their own guards without forking.

---

Contents

• Threat model
• How it works: the hook boundary
• Architecture
• Built-in guard catalog
• Forced install review
• MCP server-config protection
• Evasion resistance
• Identity and rogue-agent defense
• Context injection & shipped skills
• Policy
• Configuration & state
• Extending Aegis (plugins)
• Embedding Aegis in your MCP server
• Enforcement surfaces
• Performance & operations
• Accountability
• Who it's for
• Aegis vs. alternatives
• Install
• CLI reference
• Design principles
• Limitations
• License

---

Threat model

An autonomous coding agent runs with your privileges: your shell, your repo, your database credentials, your cloud keys. It also reads untrusted input all day — web pages, dependencies, issue threads, tool output — any of which can carry a prompt-injection payload. If an agent is hijacked, the blast radius is everything you can touch.

The usual mitigation is a system prompt ("don't run destructive commands"). That is advisory. The instruction lives in the model's context window, where it can be overridden, out-argued, or injected around. It is a request, not a control.

Aegis moves enforcement to a boundary the model cannot reach.

Assumes the agent is untrusted at the point of action — not because the model is malicious, but because it runs with full privileges and ingests attacker-controlled text. Every tool call is treated as potentially hostile and gated where the model has no influence.

Defends against: a hijacked or injected agent doing damage with your credentials — secret theft, exfiltration, data/schema destruction, history rewrites, persistence; an agent encoding/wrapping/splitting its way around an instruction-level guard; an agent trying to disable the guard or impersonate another identity.

Trust boundary. The control runs in a separate process the runtime invokes, reading policy from disk. The model can emit any text it wants; it cannot change the exit code Aegis returns. That is the line.

Non-goals (stated plainly). Aegis is a policy layer, not a sandbox. It does not contain a process that has already reached a shell and is running relative commands from an attacker-chosen directory, and it does not replace OS isolation. For hostile code or hard multi-tenant isolation, run the agent under a restricted OS user / container and let Aegis enforce policy on top — defense in depth, not a silver bullet.

How it works: the hook boundary

Modern agent runtimes expose hooks — the runtime calls out to an external program at lifecycle points (before a tool runs, after it runs, at session start, at stop). Aegis is that program.

On PreToolUse, the runtime hands Aegis the pending tool call and asks "may I run this?". Aegis evaluates it and answers:

• allow — exit 0, the tool runs.
• deny — exit code 2; the runtime refuses the action and feeds Aegis's reason back to the model as context.
• ask — surfaced to the human operator for interactive confirmation. The runtime pauses the agent and presents the pending action in its permission UI (Claude Code shows a [y/n] prompt with the tool call details and Aegis's reason). The human approves or rejects; the agent never decides. Use ask for actions that are dangerous but situationally legitimate — production deploys, schema changes on a staging DB, force-pushes to a feature branch — where you want a human in the loop without a blanket deny.

(Exit code 2 is Claude Code's block contract; other runtimes signal a block their own way — the adapter maps the decision to each.)

The decision is made in a separate process, from policy on disk, with no dependence on anything the model said. A jailbroken model still cannot run a denied command, because the model is not the thing being asked — the runtime is.

agent runtime ──PreToolUse(tool, args)──> aegis hook ──> policy engine ──> allow/deny/ask
     ^                                                         |
     └──────────────── deny (exit 2) + reason <───────────────┘

A blocked call, end to end

1. You run aegis install --project . — it merges a PreToolUse hook (and the rest of the runtime's hook surface — 26 events) into the project's .claude/settings.json.
2. Mid-session the agent decides to run psql -c "DROP TABLE users".
3. Before executing, Claude Code invokes aegis hook PreToolUse, piping it the tool call as JSON on stdin.
4. Aegis normalizes it to an Event (shell, with the command text) and runs the engine; the migration guard matches DROP TABLE.
5. Aegis writes the reason to stderr and exits 2. Claude Code refuses to run the command and hands the model the reason — which it can act on (choose a safe path) but not override.
6. A record lands in the audit log; aegis report now shows the denial, attributed to the session/identity.

No model cooperation was needed at any step. If the agent retries with bash -c "psql ..." or a base64-encoded variant, step 4 still matches — see Evasion resistance.

Architecture

A hook payload flows through one pipeline:

native hook payload -> adapter -> normalized Event -> policy engine -> Decision -> audit

Event model (events.py) — runtime-agnostic, so one policy works across runtimes. Every call normalizes to an Event with a HookEvent and an ActionClass taxonomy (read / edit / write / shell / git / subagent / mcp / net / other). A policy can target a whole class ("deny all shell") without knowing each runtime's tool names.

Aegis covers the runtime's full hook surface (26 Claude Code events), not just tool calls. BLOCKABLE (in events.py) marks the 13 events where a deny actually stops the action; the rest are observational (recorded for accountability). Beyond the core tool-use guards, lifecycle rules (aegis/lifecycle/) cover:

Policy engine (engine.py) — evaluates an Event in three stages, first-deny-wins, fail-open per rule (one broken rule can never brick the agent):

1. Built-in rules — the secure-by-default guard set (below). Disable with AEGIS_NO_BUILTINS=1.
2. Plugin rules — custom guards registered by you/your org/an MCP provider.
3. Declarative rules — your YAML policy (highest priority first, first match wins).

The order is deliberate: built-ins run first and only ever deny or abstain, so a permissive declarative rule — even tools: ["*"] for admins — can never re-open a built-in protection. To relax a built-in you disable it explicitly (AEGIS_NO_BUILTINS, or a narrower toggle), never by out-prioritizing it. This is what keeps a prompt-injected but fully-authorized agent from reading secrets or dropping tables.

Every decision is written to a structured audit log that powers accountability.

The built-in guard catalog

Two tiers. Non-escapable guards protect against the catastrophic and cannot be waved through. Escapable guards block by default but accept an explicit, recorded confirmation — append # aegis-allow to a shell command, or -- aegis-allow to SQL — so legitimate dangerous work is still possible with intent.

Agents cannot self-escape. The # aegis-allow override is honored only for human operators. A spawned agent (identified by AEGIS_AGENT_NAME) cannot wave itself past an escapable guard — the override is silently ignored. This prevents a hijacked agent from appending the escape token to its own commands.

The migration guard is worth calling out: an agent doesn't need a shell to wipe a database — it can call a DB MCP tool's execute_sql directly. Aegis reads the SQL out of the tool arguments, so DROP TABLE is caught with no shell involved — a vector most guardrails miss entirely.

Lifecycle guards (the rest of the hook surface)

Beyond the 13 core guards above, Aegis covers the full Claude Code hook surface (26 events; see Architecture) with 10 lifecycle guards in aegis/lifecycle/ — together the 23 built-in rules. Some fire unconditionally; five are opt-in via policy knobs (team / compaction / permission / mcp / completion — see Policy).

Observational events with no enforcing rule (PostToolUse, PostToolUseFailure, SubagentStop, TeammateIdle, SessionStart/SessionEnd, Setup, InstructionsLoaded, StopFailure, PostCompact, Notification, WorktreeRemove) are still recorded to the audit log for accountability — and PostToolUseFailure additionally feeds the failure-loop ledger, while SessionStart/PostCompact carry the context injection.

Containment is a known-paths denylist (the locations above) — deliberately high-signal, not exhaustive: a secret at an unlisted path, or copied first and then read, can slip it. Pair it with least privilege so the agent can't reach what isn't listed.

Forced install review

A recurring way an agent gets compromised is an unread install: it clones a repo, follows the setup notes, and runs pip install -r requirements.txt (or npm install) without ever looking at what it pulls in. Public proofs-of-concept — e.g. Mozilla 0DIN's June 2026 "clean repo" reverse-shell — ride exactly this: a repository with no malicious files, whose dependency (or a later error message) carries the payload.

Forced install review makes the install go through a real read instead of around it:

1. Deny until fully read. An install is refused until the manifest that determines what it pulls in — requirements.txt (and nested -r/-c includes), package.json
   • lockfile, pyproject.toml/poetry.lock, Gemfile, Cargo.toml, go.mod, … — has been fully read in this session. "Fully read" is enforced by a coverage ledger (aegis/review.py): each Read records the line interval it actually returned, keyed to the file's content hash; the union must span the whole file. A Read with a limit that stops short, a grep/head/tail peek, or a read of a different file with the same name does not satisfy it, and editing the file after reading re-arms the gate.
2. Then ask. Once coverage is satisfied the install is surfaced to the human as an ask with a factual digest — dependency count, unpinned specs, URL/VCS/local deps, and whether install-time scripts are present — so the approval is informed.

A targeted install of named packages (pip install requests, npm install lodash, pip install --upgrade pip) has no manifest to read and goes straight to the ask (the package names are summarized in the digest). A local-path install (pip install ./pkg) gates the build files of that directory.

Config (policy.install_review) — built in, on by default at mode: ask:

install_review:
  mode: ask            # off | monitor (log the would-be decision to the audit, allow) | ask
  deep: false          # also require reading the LOCAL setup.py / postinstall scripts
  require_pinned: false # deny unpinned specs (force exact == / a lockfile)
  allow: []            # regexes on the command that skip the gate

The read-gate is non-escapable by a spawned agent — it cannot # aegis-allow its own install (the override is honored only for a human). Bypasses for legitimate use: a human # aegis-allow, AEGIS_ALLOW_INSTALL=1, an allow: regex, or mode: monitor while you pilot. No-execute fetches (pip download, npm pack) are not installs and don't gate.

What this does and does not stop — honest kill-chain

Against the 0DIN clean-repo chain, mapped to the tool calls Aegis actually sees:

So this gate blocks the blind/poisoned-manifest step and forces a human decision; it does not by itself stop a payload that lives in a dependency's install-time code or in a later step. deep mode force-reads the local setup.py/pyproject.toml (catching a malicious pip install .), not a downloaded third-party package's code. The real containment for the in-subprocess payload is OS isolation + deny-by-default egress — pair them with this gate; it is a policy layer, not a sandbox.

Known limits (so you're not surprised)

• Coverage proves bytes entered context, not comprehension. A full read puts the whole manifest in front of the model/human; it can't prove they understood it, and a benign name (requests) tells you nothing about a typosquat.
• Coverage trusts the runtime's tool output. The ledger believes the Read content the runtime delivers at PostToolUse (same trust the hook itself rests on). It does not defend a caller that forges its own hook payloads — that's the "the hook can be skipped" case the server-side gate addresses. On a runtime that doesn't deliver Read content, coverage fails closed (install blocked) — use a human override or mode: monitor.
• Denylist detection can be laundered. Manifest contents fed through xargs/$(…), or a brand-new installer name, can dodge detection; a download-to-temp-then-execute split across two statements dodges the fetch-to-shell guard. Deny-by-default egress is the backstop.
• The ledger has no TTL. A full read earlier in the session satisfies the gate until the file's content changes.

MCP server-config protection

MCP server-definition config files (.mcp.json, ~/.claude.json's mcpServers, .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json, Windsurf's mcp_config.json) declare a command / args / url / env per server. That definition is auto-executed on every future session start — the runtime launches it as part of bringing up the agent's tool surface, with no further approval. A hijacked or prompt-injected agent that plants or edits an entry here plants a durable, cross-session backdoor that outlives the current session entirely: the next launch (yours, a teammate's, or CI's) runs whatever command/args the attacker wrote, with the same privileges any other tool already has.

This is a distinctly agentic attack surface — unique to tool-calling runtimes — that none of the other built-ins cover: self-protection guards Aegis's own config (.aegis, .claude/settings.json); containment/persistence guard OS-level persistence (cron, registry, scheduled tasks). Neither looks at MCP server definitions.

What's covered:

1. Edit/Write/MCP-tool writes to a known MCP config path (checked via the generic path argument, so this catches an MCP filesystem-server tool's write — not just Claude Code's own Edit/Write — regardless of whether that server calls its path argument file_path, path, target_file, filename, file, or uri).
2. Shell mutation of a config path: redirects/tee/Set-Content, delete/move, recursive force-delete, and in-place edits or copy-over-target (sed -i, perl -i, batch-mode vim/ex, cp, dd, or a python/node/ruby/perl one-liner that writes the file).
3. CLI registration — claude mcp add …, codex mcp add …, and the bare reference-CLI form mcp add … (anchored to command-start position so it doesn't false-positive on a commit message or grep hit that merely contains the phrase).

Reads (Read, Grep, Glob) are unaffected — only mutation is gated, so scaffolding a project from a template or auditing an existing .mcp.json works normally.

Config (policy.mcp_config) — built in, on by default at mode: deny:

mcp_config:
  mode: deny            # deny | ask | monitor | off
  allow: []              # regexes on the path/command that skip the gate

ask surfaces the change to a human for interactive approval instead of a hard deny — the same shape as install_review's digest-then-ask. monitor logs the would-be decision to the audit and allows, for piloting before enforcing.

Escapable only by a human: a trailing # aegis-allow on the shell form (the natural place for it — there's no syntax-safe way to embed a comment inside a JSON Edit/Write payload), or the env toggle AEGIS_ALLOW_MCP_CONFIG=1 for the Edit/Write/MCP-tool form. A spawned agent cannot set its own environment for a hook invocation it doesn't control, and (per Evasion resistance, below) cannot use the # aegis-allow token on its own commands either — so neither escape hatch is agent-self-usable.

Known limits: this is a known-paths denylist — an unlisted or newly-invented runtime's config file, or a symlink pointing outside the recognized set, isn't covered. A third-party MCP CLI that isn't Claude Code / Codex / Cursor / Windsurf / Gemini and doesn't use the bare mcp add phrasing can register a server without tripping the CLI check (the config-file write itself is still the backstop in that case). Like the other denylist guards here, pair with least privilege and deny-by-default egress for defense in depth.

Evasion resistance

A denylist that scans only the raw command loses to a determined agent. Aegis normalizes before it matches:

• De-obfuscation — token-splitting quotes/escapes are stripped (r"m" -rf), PowerShell -EncodedCommand/-enc base64 is decoded, base64 -d pipelines are decoded, and inner interpreter code is expanded (bash -c "...", powershell -c, cmd /c, python -c, node -e) — recursively. The guards scan the de-obfuscated surface, so wrapping or encoding can't hide a delete, a DROP, or a key read.
• Alternate tools — find -delete / -exec rm, shred, truncate -s 0, dd of=/dev/... are caught alongside rm.
• Obfuscation is itself a signal — encoded commands, base64-piped-to-a-shell, FromBase64String, and char-code construction are denied outright.
• No self-escape — the # aegis-allow override is honored only for a human / orchestrator. A spawned agent (AEGIS_AGENT_NAME set) cannot wave itself past an escapable guard.

Honest limit: this raises the cost of evasion sharply — it is not a sandbox. The ceiling is deny-by-default plus OS-level privilege separation (run agents under a restricted token). Aegis is the policy layer; pair it with least privilege.

Identity and rogue-agent defense

A name in an environment variable is forgeable — any process can claim to be any agent. Aegis issues cryptographic identities and enforces them.

Identity is attribution + authorization, not injection immunity. A signed key proves who an agent is and what it may do — it does nothing to stop an authorized agent that gets prompt-injected (the key stays valid; the attacker just drives the agent). What stops a hijacked-but-signed agent is the action layer: the built-in guards evaluate the action, not the caller, and run before your declarative rules, so a signed admin that tries to read your keys or drop a table is denied by containment/migration regardless of role — and, like any agent, it can't # aegis-allow its way past an escapable guard. Identity's job against injection is to shrink blast radius (least-privilege RBAC) and give exact attribution, not to make the agent immune.

• Signed identity (identity.py) — Ed25519 tokens bound to {agent, role, session, project, caps, exp}, minted with aegis issue and verified against the issuer public key. RBAC roles derive from the verified token, not a forgeable env string.
• Attestation gate + honeypot (attest.py) — at SessionStart, a process that claims an agent identity (AEGIS_AGENT_NAME) without a valid token is rogue. The denial carries an attestation challenge: a directive a human ignores but an autonomous, instruction-following agent obeys — self-reporting its model/operator via aegis attest, where it's classified (verified / forged / unregistered / noise), logged, and blocklisted. A rogue agent identifies itself into the trap. (This catches instruction-following rogues; a targeted attacker whose agent ignores the challenge won't self-report — the identity gate + reaper are the backstop.)
• The reaper (reaper.py) — under enforcement, a rogue session isn't just denied a tool call; its process tree is terminated.
• Phased rollout — MONITOR by default (record + allow, so tokens can roll out fleet-wide first); AEGIS_IDENTITY_ENFORCE=1 flips it to deny-and-reap.
• Server-side gate (gate.py) — the same refusal as plain Python, so it holds even on a surface that bypasses hooks (an HTTP API, a hosted control plane, an MCP server). The hook can be skipped; an import-level refusal cannot.

Token lifecycle. Your spawner mints a token — aegis issue <agent> --role reader --caps read,plan — and sets it as AEGIS_AGENT_TOKEN in the agent's environment at launch (alongside AEGIS_AGENT_NAME). The hook reads both: a name with a valid token is a real, attributable identity whose role/caps drive RBAC; a name without one is rogue. Tokens carry an expiry (exp, default 12h) and are signed by an issuer key in ~/.aegis/identity/ — verifiers only need the public half. Roll out in phases: stay in MONITOR (rogue sessions logged, allowed) until issuance covers every spawn path, then AEGIS_IDENTITY_ENFORCE=1 to deny-and-reap.

The spawner contract — assign identity at launch

Identity is assigned by whatever launches the agent (your orchestrator, CI job, or shell), by setting a few environment variables before the agent runs. Set them and every action is attributed, scoped, and — with a token — cryptographically proven:

# 1. Mint a signed identity bound to a role + project (recommended):
export AEGIS_AGENT_TOKEN="$(aegis issue code-reviewer --role reader --caps read,plan --project "$PWD")"
# 2. Label + scope the session (these alone are a quick, unsigned setup):
export AEGIS_AGENT_NAME="code-reviewer"   # who (also drives the rogue gate)
export AEGIS_SESSION_ID="$CI_RUN_ID"      # which run (Claude Code sets this itself)
export AEGIS_PROJECT="$PWD"               # confine file edits to this repo
# 3. Launch the agent. Every hook now records who / which-session and hard-blocks
#    writes outside the project.

Precedence, weakest to strongest: a vanilla install attributes records to the runtime (agent: claude-code) and the OS user; AEGIS_AGENT_NAME / agent_label add a real label; a signed token makes the identity unforgeable and carries the project binding that confines edits. Even with nothing set you never see null.

For a repo that wants zero per-launch setup, declare the defaults in policy:

agent_label: ci-bot     # label records when no AEGIS_AGENT_NAME is set
project: .              # hard-block Edit/Write outside this repo (reads stay free)

Context injection & shipped skills

Enforcement (the hooks) stops a bad action; guidance is what makes the agent take the good one on the first try. Aegis ships both halves:

Context injection. On SessionStart — and again on PostCompact, the moment where a summarizer typically keeps the task and silently drops the governance — Aegis injects a compact policy-posture digest into the model's context: what is never available, which escapes are human-only, which opt-in gates are active, and what to do when blocked. The rules the agent runs under survive compaction instead of falling out of context mid-session. On by default; disable with inject: {mode: off}. Injection is advisory (the model can ignore it); the hooks remain the enforcement — the digest exists so the agent complies on the first try instead of discovering the policy one deny at a time.

Shipped skills. aegis install also writes four agent skills next to the hooks (.claude/skills/aegis-*; skip with --no-skills):

The skills follow the same merge-never-clobber contract as the hook installer: each carries a managed-by marker, install never overwrites a user's same-named skill, and uninstall removes only marked files. They are guidance the agent can't quietly subvert — self-protect blocks agents from rewriting aegis-* skill files.

Policy

Declarative YAML. First matching rule by priority wins; otherwise default_action applies. Rules match on any combination of event, tool glob, action class, identity/role, and argument constraints (glob or regex):

default_action: allow          # use "deny" for deny-by-default
on_error: allow                # engine error -> fail open (allow) or closed (deny)

egress:                        # network egress governance
  default: deny
  allow: ["api.github.com", "*.internal"]

rules:
  - name: admin-allow-all
    priority: 300
    action: allow
    tools: ["*"]
    roles: [admin]             # role comes from the verified identity token

  - name: block-secret-files
    priority: 150
    action: deny
    actions: [read, edit, write]
    argument_patterns: { file_path: "*.env*" }

  - name: confirm-prod
    priority: 120
    action: ask
    actions: [shell]
    regex: { command: "\\b(kubectl|helm)\\b.*\\bprod\\b|terraform\\s+apply" }

Validate with aegis validate.

Top-level fields (besides rules): default_action, on_error (allow/deny), egress (network governance), plugins (custom guard modules), workspace ({root, allow} confinement), project (bind file mutations to a repo — hard-block out-of-project edits), agent_label (default record label when no AEGIS_AGENT_NAME is set), install_review (forced dependency-manifest review — see Forced install review), mcp_config (MCP server-config protection mode/allowlist — see MCP server-config protection), inject (context injection on/off — see Context injection & shipped skills), and failures (failure-loop guard {mode, max_repeats}). workspace/project give a repo zero-config attribution + confinement.

Five opt-in lifecycle knobs enable the gated lifecycle guards (see Lifecycle guards); each is a small mapping, off unless set:

team:        { require_verification: true }  # gate TaskCompleted on a verification signal
compaction:  { block_auto: true }            # block auto context compaction (PreCompact)
permission:  { deny_escalation: true }       # auto-deny a spawned agent's permission prompts
mcp:         { block_elicitation: true }     # block MCP elicitation side-channels
completion:  { require_tests: true }         # Stop gate: no stopping after edits w/o a test run
             # optional: patterns: ["./run-my-checks\\.sh"]  # custom test runners

And two on-by-default reliability knobs, tunable or disable-able:

inject:      { mode: off }                     # posture digest on SessionStart/PostCompact
failures:    { mode: deny, max_repeats: 3 }    # deny|ask|monitor|off identical failed retries

Configuration & state

Resolution is env -> project-local -> home, so a repo can ship its own guardrails while a user or org sets global defaults:

Switches: AEGIS_NO_BUILTINS (turn off the default guard set), AEGIS_IDENTITY_ENFORCE (deny + reap rogue sessions), AEGIS_ALLOW_SUBAGENTS, AEGIS_ALLOW_INSTALL (bypass the forced install-review gate), AEGIS_ALLOW_RETRY (bypass the failure-loop guard), AEGIS_ALLOW_STRAND (permit branching with unmerged work), AEGIS_ALLOW_MCP_CONFIG (human confirmation to write an MCP server config via Edit/Write/MCP-tool — see MCP server-config protection), AEGIS_WORKSPACE / AEGIS_PROJECT (confinement root; AEGIS_PROJECT also binds the identity), AEGIS_FAIL_CLOSED (deny on an unparseable payload instead of fail-open).

Agent environment (set by your spawner at agent launch):

Extending Aegis

A rule is just (event, policy) -> Decision | None. Ship a module that registers rules and point Aegis at it via AEGIS_PLUGINS or a policy plugins: list — no fork:

# acme_guards.py
from aegis.plugins import register_rule
from aegis.policy import Decision, Action

@register_rule
def no_prod_writes(event, policy):
    if event.action.value == "write" and "prod" in str(event.args.get("file_path", "")):
        return Decision(Action.DENY, "no-prod-writes", "writes to prod require review")
    return None

Because rules receive policy, a custom guard can read its own configuration out of the policy file — orgs distribute one policy with both their rules and their config.

Embedding Aegis in your MCP server

Hooks govern the agent runtime. If you build an MCP server, you can also enforce policy on the tool side — inside your server, where a client cannot bypass it. It's the same engine (built-ins + your plugins + your declarative rules + the server-side identity gate), invoked at the tool boundary instead of at a hook.

Setup

1. Install Aegis in the server's environment (the same interpreter that runs the MCP server):

   pip install -e /path/to/AEGIS        # PyPI packaging planned
   

2. Give it a policy — optional; built-ins apply with none. Aegis resolves the policy dir from AEGIS_POLICIES -> ./.aegis/policies -> ~/.aegis/policies:

   mkdir -p .aegis/policies
   cp /path/to/AEGIS/policies/example.yaml .aegis/policies/
   aegis validate
   

3. Guard your tools — decorate the handlers, or call check / guard inline.
4. Map the decision to your protocol — return an error to the client on a block.

Wire it into your tools (FastMCP — runnable copy in examples/mcp_server.py)

from mcp.server.fastmcp import FastMCP
from aegis import mcp as aegis

app = FastMCP("vault")

@app.tool()
@aegis.guarded                       # tool name defaults to the function name
def get_secret(key: str) -> str:
    return read_secret(key)          # only runs if policy allows

# or enforce inline, with full control of the response:
@app.tool()
def run_sql(query: str) -> str:
    d = aegis.check("run_sql", {"query": query})
    if d.blocked:
        return f"refused by Aegis policy: {d.message}"   # agent sees a clean refusal
    return execute(query)

aegis.guarded evaluates the handler's keyword arguments as the tool arguments (how FastMCP invokes tools) and raises aegis.Denied on a block — let it propagate (FastMCP surfaces it as a tool error) or catch it:

try:
    aegis.guard("delete_record", {"id": rec_id})
except aegis.Denied as e:
    return {"error": e.decision.message, "rule": e.decision.rule}

Identity (multi-tenant servers)

By default the caller identity comes from the environment (AEGIS_AGENT_NAME / AEGIS_AGENT_TOKEN). A server that authenticates its callers should pass identity explicitly so RBAC rules apply:

aegis.check("run_sql", {"query": q}, identity_name=req.user, roles=req.roles)

With AEGIS_IDENTITY_ENFORCE=1, the server-side gate refuses a rogue caller before any rule runs — a guarantee that holds even though the client controls the hooks. An MCP provider ships stronger safety to its users without trusting the client to behave.

Enforcement surfaces

The same policy enforces across three surfaces, so coverage doesn't depend on any single integration:

• Agent-runtime hooks — Claude Code today (native hooks; aegis install merges into .claude/settings.json without clobbering existing config). Any runtime with a command hook via the generic JSON adapter. (Adapter status: ADAPTERS.md.)

• MCP transport — enforce inside an MCP server (above).

• git / CI — the universal change-boundary floor. Runtime hooks need a runtime you can hook; this surface doesn't. It enforces the same policy on the diff, so it covers any agent — or human — that produces commits, including agents whose runtime has no usable hook surface.

  • aegis install-git [--repo .] writes .git/hooks/pre-commit and pre-push, appending to any existing hook scripts (non-clobber).
  • pre-commit evaluates each staged file (git diff --cached) as a git action; a violation — committing a .env, or any path your policy forbids — blocks the commit before it's recorded.
  • pre-push evaluates the push itself (operation + branch); a rule denying branch: main stops a direct push to main.
  • aegis ci --base origin/<base> evaluates the files changed vs a base ref for pull-request enforcement: it prints GitHub ::error file=...:: annotations and exits non-zero to fail the check. The shipped .github/workflows/aegis.yml runs it on every PR.

  Git operations are modeled as action: git events (operation = commit/push, plus file and branch), so the same rules and built-ins apply — you author one policy and it enforces in the editor, at commit, at push, and in CI:

  - name: no-commit-secrets
    action: deny
    actions: [git]
    argument_patterns: { operation: commit, file: "*.env*" }
  - name: no-direct-push-to-main
    action: deny
    actions: [git]
    argument_patterns: { operation: push, branch: main }
  

  Scope: git/CI sees a change at commit / push / PR time (the diff), not every keystroke — it's the floor that complements the live runtime hooks, not a replacement for them.

Performance & operations

A hook runs once per tool call: the runtime spawns aegis hook, which starts a short-lived Python process, loads policy, evaluates, and exits. For a single project that's negligible — but two things matter:

• cryptography is imported lazily (only when a token is actually verified), so the common no-identity path stays light.
• Global install has a real cost. In ~/.claude/settings.json the hook fires for every tool call in every session; stacked with other global hooks, the per-call process spawns add up and can bog a busy machine. Prefer project-scoped installs for the repos you actually want guarded. A persistent-daemon hook (one process, many calls) is the planned path to comfortable always-on global enforcement.
• Uninstall is path-aware. Installed hooks are tagged (_source: aegis) and matched by command, so aegis uninstall removes them whether they were wired by bare name or absolute path. To purge by hand, delete entries whose command contains aegis from the relevant settings.json.
• Fail-open is deliberate. If the hook can't run (missing interpreter, moved install), the action proceeds unguarded rather than blocking your work — so a pipx install (a stable path) is the durable way to run it. A payload Aegis can't parse is handled the same way — logged to stderr and recorded in the audit (rule: payload-parse-error) rather than silently allowed; set AEGIS_FAIL_CLOSED=1 (or on_error: deny) to block unparseable payloads.

Accountability

Every decision is appended to a structured audit log — one JSON record per line: {ts, event, tool, action, decision, rule, identity, agent, session_id, cwd, args, usage}, at ~/.aegis/audit.jsonl (override with AEGIS_AUDIT). Point a whole team's logs at one directory and the reports aggregate fleet-wide.

• aegis report — the rap sheet: per-session and per-identity rollups, the full denial trail, token/cost totals, and a verdict per session (flags: many-denials, mostly-denied, high-failure-rate — the session thrashed on failing tool calls — and orphaned-subagent — sub-agents started but never reconciled).
• aegis who --tool <T> --path <P> — blame: which identities/sessions touched a tool or path.
• aegis detections — caught rogue-agent attestations.

Token & cost tracking

Aegis captures token usage and cost metadata from every hook payload — whatever the runtime sends (input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens, num_turns, total_cost, cost_usd, duration_ms, model) — and writes it into the audit record's usage field. Extraction is best-effort and never fails: if the runtime sends no usage data, the field is omitted.

The report aggregates usage at every level:

• Summary — fleet-wide totals across all sessions.
• Per-session — how many tokens and how much cost each agent session consumed.
• Per-identity — the same rollup grouped by who ran the session.

$ aegis report
...
  Token usage:  380 in / 180 out  ·  cache: 10 read  ·  12 turns  ·  $0.05
  Sessions:
    s1 (alice / bot-a)   2 calls   180 in / 80 out
    s2 (bob / bot-b)     2 calls   200 in / 100 out   $0.05

This gives you the answer to "how much did that agent session cost?" and "which identity is burning the most tokens?" — from the same audit stream that already tracks what each agent did and whether it was allowed.

Grounding: gate what an agent claims

Enforcement governs what an agent does; grounding governs what an agent claims. The two halves share one trust model — measure against ground truth, never take the model's word — and one data source: the audit trail above.

aegis.grounding (the folded-in Receipts engine) checks every claim in an agent's answer against a tamper-evident ledger of evidence. Three deterministic rules:

• Binding — a claim must cite real evidence, or be demoted to an explicit assumption. A guess stated as fact is illegal.
• Effort honesty — "I searched / read / reviewed" must be backed by evidence of a matching kind; total-coverage words ("all", "entire", "thoroughly") require machine-checkable coverage counts. This is the "I reviewed the entire codebase" detector.
• Support — the cited evidence must actually back the claim (transparent token overlap by default; a pluggable LLM/NLI judge for semantic checking).

The seam with enforcement: Aegis already records every tool call and its output to the audit trail, so ledger_from_audit() turns that stream into the evidence ledger — an agent's final answer is gated against what it actually did, no separate instrumentation.

from aegis.grounding import Gate, Answer, Claim, ClaimKind, ledger_from_audit

ledger = ledger_from_audit("~/.aegis/audit.jsonl")   # what the agent actually did
print(Gate(ledger).finalize(Answer(
    summary="The service listens on port 8080.",
    claims=[Claim("the port is 8080", evidence_ids=[...], kind=ClaimKind.FACT)],
)))   # renders, or raises with a precise fix list

As a CI gate on a portable trace file (exit 1 when any claim is ungrounded):

aegis grounding audit trace.json          # or --from-audit to use the audit trail

Deterministic and dependency-free by default; the LLM support judge and free-text claim extractor are optional (pip install "aegis-hooks[anthropic]"). This engine was previously the standalone receipts-gate package, now folded into Aegis.

Who it's for

• Solo devs using AI agents — you're giving Claude/Copilot/Cursor shell access to your machine. Aegis is the guardrail between "please help me refactor" and rm -rf / or your SSH keys ending up in a curl upload. Install it, get the secure-by-default set, never think about it until it saves you.

• Teams and orgs — you have 5, 50, or 500 agents running across repos. You need one policy that governs all of them, accountability that shows who did what, and identity that distinguishes your CI agent from your code-review agent from a rogue process. Ship a policy YAML in your org's base repo config; Aegis enforces it everywhere.

• MCP server authors / tool providers — you're building tools that agents call. You can't trust the client runtime to enforce limits — embed Aegis in your server and the guards hold regardless of what the client does. An execute_sql tool that refuses DROP TABLE inside the server is safer than one that hopes the agent's system prompt says "don't drop tables."

• Security / platform teams — you need to prove agents can't exfiltrate secrets, can't wipe databases, can't install persistence, and you need an audit trail that shows it. Aegis gives you the enforcement + the receipts.

Aegis vs. alternatives

Aegis + a sandbox is the strongest posture. Aegis enforces policy (what actions are allowed); a sandbox enforces isolation (what the process can reach). They're complementary: Aegis catches the DROP TABLE that a sandbox can't distinguish from a SELECT; the sandbox contains the novel evasion that Aegis's denylist hasn't seen.

Install

Requirements: Python 3.10+. Cross-platform engine; the shell-guard patterns cover bash, PowerShell, and cmd (a few are Windows-specific, e.g. DPAPI / registry autorun).

pip install aegis-hooks     # or: pipx install aegis-hooks  (puts `aegis` on PATH for good)

From source:

git clone https://github.com/Thepizzapie/AEGIS && cd AEGIS
pip install -e .            # or: pipx install .

aegis on PATH — read this. pip install -e . inside a venv only wires aegis into that venv, but the runtime hooks call aegis from wherever the agent runs. So either install with pipx (a stable global aegis), or install scoped with an absolute command: aegis install --project <repo> --command "/abs/path/to/.venv/bin/aegis hook".

Wire it into a repo (merge-safe — it never clobbers existing hooks):

aegis install --project /path/to/your/repo
aegis validate

Prefer project-scoped over global. aegis install --global governs every Claude Code session and spawns a process per tool call — on a busy machine that adds up. Scope it to the repos you actually want guarded. Remove anytime with aegis uninstall --project <repo> (or --global).

Try it (no Claude Code needed)

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | aegis hook PreToolUse
# [Aegis] Recursive force delete is blocked. Append '# aegis-allow' to confirm.
echo $?            # -> 2  (the action is refused)
aegis report       # the decision is in the audit trail

Works the same under PowerShell — a piped UTF-8 BOM is tolerated; use $LASTEXITCODE instead of echo $?.

CLI reference

Design principles

• Outside the context window. Enforcement is a property of the runtime boundary, not a request to the model. That is the whole point.
• Secure by default. The dangerous defaults are on with zero config; relaxing them is a deliberate, recorded act.
• Fail-open per rule. A buggy or slow rule can never wedge or brick a session — it is skipped, never fatal.
• Escapable with intent, or not at all. Catastrophic/irreversible actions (secrets, self-removal, rogue sessions) are non-negotiable; merely dangerous ones accept a recorded # aegis-allow.
• Runtime-agnostic core. Adapters translate; the engine and policy are shared.

Limitations

• Not a sandbox. Aegis gates tool calls; it doesn't isolate a process. An agent already at a raw shell can run relative commands Aegis only sees as a shell action — pair it with an OS-restricted user/container for hostile-code isolation.
• Denylist guards are heuristic. The built-in shell guards match known-dangerous command shapes; they raise the cost of evasion sharply but are not exhaustive by construction. Known-uncovered forms include: exfiltration via cloud CLIs (aws s3 cp, gsutil, rclone) or an in-process requests.post; in-place policy edits via sed -i / perl -i or a chmod 000 on the policy file; and git -c inline-config force-push. These fail safe for file mutations routed through the runtime's Edit/Write tools (caught by path, not verb), but a raw shell can still reach them. Deny-by-default (allowlist) is the stronger posture for high-security setups and is supported per-surface (network egress today; a shell allowlist preset is planned). If you find a bypass, that's a bug worth reporting.
• Identity is as strong as the keystore. v1 persists the issuer key on disk; a process with your full privileges could read it. True unforgeability needs the key in a broker process plus OS privilege separation — the module isolates the key source so that hardening is a swap, not a rewrite.
• Deep hooks are per-runtime. Native support is Claude Code today; other runtimes are covered by the generic JSON adapter or the git/CI floor.

License

Apache-2.0 — see LICENSE for details.

For questions about team, enterprise, or MCP-provider licensing, open an issue or get in touch.