# mustafaahmed007/agent-authority architecture

> Architecture diagram of the GitHub repository mustafaahmed007/agent-authority, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mustafaahmed007/agent-authority
- Repository: https://github.com/mustafaahmed007/agent-authority

## Overview

Agent Authority is a runtime control layer that gates agent tool use with task-scoped authority, policy, risk, and optional approval. Its main path runs from an agent request through the MCP gateway and authority kernel to an authorization decision and, when allowed, execution; the kernel records audit evidence for persistence and later analysis. The README documents verification, replay, graph analysis, anomaly detection, advisory learning, sandboxing, and framework integrations as additional capabilities. Links for unsampled subsystems follow that documentation; source-level evidence is strongest for the kernel, persistence contract, and MCP path.

Main entry points: [`src/agent_authority/authority.py`](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/authority.py) (Authority kernel), [`src/agent_authority/ledger.py`](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/ledger.py) (Audit ledger), [`src/agent_authority/mcp.py`](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/mcp.py) (MCP gateway), [`src/agent_authority/sandbox.py`](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/sandbox.py) (Sandbox execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gate["Authorization"]
  node_identity["Agent identity<br/>[models.py]"]
  node_delegation["Task delegation<br/>[delegation.py]"]
  node_capability["Capability models<br/>[models.py]"]
  node_authority["Authority kernel<br/>[authority.py]"]
  node_policy["Policy engine<br/>[policy.py]"]
  node_risk["Risk engine<br/>[risk.py]"]
  node_trust["Tool trust<br/>[trust.py]"]
  node_approval["Human approval<br/>[authority.py]"]
end

subgraph group_integrations["Execution integrations"]
  node_mcp["MCP gateway<br/>[mcp.py]"]
  node_stdio["MCP stdio proxy<br/>[mcp_stdio.py]"]
  node_sandbox["Sandbox execution<br/>[sandbox.py]"]
  node_docker["Docker sandbox<br/>[docker_sandbox.py]"]
  node_frameworks["Framework adapters<br/>[frameworks.py]"]
end

subgraph group_evidence["Evidence and analysis"]
  node_verification["Outcome verification<br/>[verification.py]"]
  node_ledger[("Audit ledger<br/>[ledger.py]")]
  node_replay["Audit replay<br/>[replay.py]"]
  node_graph["Authority graph<br/>[authority_graph.py]"]
  node_anomaly["Anomaly detection<br/>[anomaly.py]"]
  node_learning["Advisory learning<br/>[learning.py]"]
end

subgraph group_state["State and cryptography"]
  node_storage["Storage contract<br/>[storage.py]"]
  node_sqlite[("SQLite store<br/>[sqlite_store.py]")]
  node_crypto["Signing and hashes<br/>[crypto.py]"]
end

subgraph group_operations["Operations"]
  node_control["Control plane<br/>[control_plane.py]"]
  node_cli["CLI<br/>[cli.py]"]
end

node_agent(("Agent"))

node_agent -->|"requests tool"| node_mcp
node_mcp -->|"authorizes"| node_authority
node_stdio -->|"filters calls"| node_mcp
node_frameworks -->|"adapts calls"| node_mcp
node_authority -->|"evaluates policy"| node_policy
node_authority -->|"assesses risk"| node_risk
node_authority -->|"uses signing"| node_crypto
node_authority -->|"loads and saves"| node_storage
node_authority -->|"appends events"| node_ledger
node_ledger -->|"hashes events"| node_crypto
node_mcp -->|"records execution"| node_authority
node_authority -->|"requests approval"| node_approval
node_storage -.->|"durable implementation"| node_sqlite
node_authority -.->|"checks claims"| node_verification
node_ledger -.->|"supports replay"| node_replay
node_ledger -.->|"informs analysis"| node_graph
node_ledger -.->|"informs detection"| node_anomaly
node_anomaly -.->|"feeds signals"| node_learning
node_agent -.->|"runs restricted"| node_sandbox
node_sandbox -.->|"can use isolation"| node_docker
node_control -->|"authorizes and revokes"| node_authority
node_cli -->|"operates"| node_authority

click node_identity "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/models.py"
click node_delegation "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/delegation.py"
click node_capability "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/models.py"
click node_authority "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/authority.py"
click node_policy "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/policy.py"
click node_risk "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/risk.py"
click node_trust "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/trust.py"
click node_approval "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/authority.py"
click node_mcp "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/mcp.py"
click node_stdio "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/mcp_stdio.py"
click node_sandbox "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/sandbox.py"
click node_docker "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/docker_sandbox.py"
click node_frameworks "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/frameworks.py"
click node_verification "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/verification.py"
click node_ledger "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/ledger.py"
click node_replay "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/replay.py"
click node_graph "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/authority_graph.py"
click node_anomaly "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/anomaly.py"
click node_learning "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/learning.py"
click node_storage "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/storage.py"
click node_sqlite "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/sqlite_store.py"
click node_crypto "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/crypto.py"
click node_control "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/control_plane.py"
click node_cli "https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/cli.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_identity,node_delegation,node_capability,node_authority,node_policy,node_risk,node_trust,node_approval toneBlue
class node_mcp,node_stdio,node_sandbox,node_docker,node_frameworks toneAmber
class node_verification,node_ledger,node_replay,node_graph,node_anomaly,node_learning toneMint
class node_storage,node_sqlite,node_crypto toneRose
class node_control,node_cli,node_agent toneIndigo
```

## Components

### Authorization

- [Agent identity](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/models.py): `src/agent_authority/models.py`
- [Task delegation](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/delegation.py): `src/agent_authority/delegation.py`
- [Capability models](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/models.py): `src/agent_authority/models.py`
- [Authority kernel](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/authority.py): `src/agent_authority/authority.py`
- [Policy engine](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/policy.py): `src/agent_authority/policy.py`
- [Risk engine](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/risk.py): `src/agent_authority/risk.py`
- [Tool trust](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/trust.py): `src/agent_authority/trust.py`
- [Human approval](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/authority.py): `src/agent_authority/authority.py`

### Execution integrations

- [MCP gateway](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/mcp.py): `src/agent_authority/mcp.py`
- [MCP stdio proxy](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/mcp_stdio.py): `src/agent_authority/mcp_stdio.py`
- [Sandbox execution](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/sandbox.py): `src/agent_authority/sandbox.py`
- [Docker sandbox](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/docker_sandbox.py): `src/agent_authority/docker_sandbox.py`
- [Framework adapters](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/frameworks.py): `src/agent_authority/frameworks.py`

### Evidence and analysis

- [Outcome verification](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/verification.py): `src/agent_authority/verification.py`
- [Audit ledger](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/ledger.py): `src/agent_authority/ledger.py`
- [Audit replay](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/replay.py): `src/agent_authority/replay.py`
- [Authority graph](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/authority_graph.py): `src/agent_authority/authority_graph.py`
- [Anomaly detection](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/anomaly.py): `src/agent_authority/anomaly.py`
- [Advisory learning](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/learning.py): `src/agent_authority/learning.py`

### State and cryptography

- [Storage contract](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/storage.py): `src/agent_authority/storage.py`
- [SQLite store](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/sqlite_store.py): `src/agent_authority/sqlite_store.py`
- [Signing and hashes](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/crypto.py): `src/agent_authority/crypto.py`

### Operations

- [Control plane](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/control_plane.py): `src/agent_authority/control_plane.py`
- [CLI](https://github.com/mustafaahmed007/agent-authority/blob/main/src/agent_authority/cli.py): `src/agent_authority/cli.py`

### Other components

- **Agent**

## Connections

- Agent → MCP gateway: requests tool (evidence: `README.md`)
- MCP gateway → Authority kernel: authorizes (evidence: `src/agent_authority/mcp.py`)
- MCP stdio proxy → MCP gateway: filters calls (evidence: `src/agent_authority/mcp_stdio.py`)
- Framework adapters → MCP gateway: adapts calls (evidence: `src/agent_authority/frameworks.py`)
- Authority kernel → Policy engine: evaluates policy (evidence: `src/agent_authority/authority.py`)
- Authority kernel → Risk engine: assesses risk (evidence: `src/agent_authority/authority.py`)
- Authority kernel → Signing and hashes: uses signing (evidence: `src/agent_authority/authority.py`)
- Authority kernel → Storage contract: loads and saves (evidence: `src/agent_authority/authority.py`)
- Authority kernel → Audit ledger: appends events (evidence: `src/agent_authority/authority.py`)
- Audit ledger → Signing and hashes: hashes events (evidence: `src/agent_authority/ledger.py`)
- MCP gateway → Authority kernel: records execution (evidence: `src/agent_authority/mcp.py`)
- Authority kernel → Human approval: requests approval (evidence: `src/agent_authority/authority.py`)
- Storage contract → SQLite store: durable implementation (evidence: `README.md`)
- Authority kernel → Outcome verification: checks claims (evidence: `README.md`)
- Audit ledger → Audit replay: supports replay (evidence: `README.md`)
- Audit ledger → Authority graph: informs analysis (evidence: `README.md`)
- Audit ledger → Anomaly detection: informs detection (evidence: `README.md`)
- Anomaly detection → Advisory learning: feeds signals (evidence: `README.md`)
- Agent → Sandbox execution: runs restricted (evidence: `README.md`)
- Sandbox execution → Docker sandbox: can use isolation (evidence: `README.md`)
- Control plane → Authority kernel: authorizes and revokes (evidence: `src/agent_authority/control_plane.py`)
- CLI → Authority kernel: operates (evidence: `src/agent_authority/cli.py`)
