# samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness architecture

> Architecture diagram of the GitHub repository samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness
- Repository: https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness

## Overview

AgentAegis is a lifecycle interception and vetting harness for autonomous coding agents. Its principal workflow is: an agent proposes a tool action, the installed lifecycle hook runs deterministic safety and cycle checks, gathers bounded workspace/session context for semantic review when needed, and permits or vetoes execution. Post-tool events update session and decision telemetry; completion hooks run test and claim-to-disk reconciliation before semantic acceptance. README documents these major capabilities; sampled source confirms the coordinator and key module responsibilities, but not every internal dispatch.

Main entry points: [`harness/interceptor.js`](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/interceptor.js) (Hook coordinator), [`harness/acceptance-gate.js`](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/acceptance-gate.js) (Acceptance gate), [`harness/state-collector.js`](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/state-collector.js) (Context collector), [`harness/jev-client.js`](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/jev-client.js) (Jev decision client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Lifecycle control"]
  node_interceptor["Hook coordinator<br/>[interceptor.js]"]
  node_installer["Hook installer<br/>[install.js]"]
end

subgraph group_policy["Safety and context"]
  node_sensitive["Sensitive guard<br/>[sensitive-guard.js]"]
  node_jevclient["Jev decision client<br/>[jev-client.js]"]
  node_cycle["Cycle detector<br/>[cycle-detector.js]"]
  node_variance["Edit variance<br/>[diff-variance.js]"]
  node_laws["Code law linter"]
  node_context["Context collector<br/>[state-collector.js]"]
  node_manifest["Workspace detector"]
end

subgraph group_verification["Completion verification"]
  node_acceptance["Acceptance gate<br/>[acceptance-gate.js]"]
  node_runner["Runner parser<br/>[runner-parser.js]"]
end

subgraph group_state["Session and audit"]
  node_session[("Session state<br/>[cycle-detector.js]")]
  node_audit[("Decision tracker")]
end

node_agent(("Coding agent"))
node_hooks["Lifecycle hooks"]
node_testexec["Project test runner"]
node_workspace["Workspace and disk"]
node_jev["TypeSafe Jev"]

node_agent -->|"sends events"| node_hooks
node_hooks -->|"invokes hooks"| node_interceptor
node_installer -->|"configures hooks"| node_hooks
node_interceptor -->|"checks actions"| node_sensitive
node_interceptor -->|"checks repetition"| node_cycle
node_cycle -->|"classifies edits"| node_variance
node_interceptor -->|"lints artifacts"| node_laws
node_interceptor -->|"builds context"| node_context
node_context -->|"detects ecosystem"| node_manifest
node_context -->|"reads workspace"| node_workspace
node_interceptor -->|"requests review"| node_jevclient
node_acceptance -->|"runs tests"| node_testexec
node_acceptance -->|"parses output"| node_runner
node_acceptance -->|"reconciles claims"| node_workspace
node_acceptance -->|"requests approval"| node_jevclient
node_jevclient -->|"sends decisions"| node_jev
node_interceptor -->|"gates completion"| node_acceptance
node_interceptor -->|"loads and saves"| node_session
node_acceptance -->|"loads telemetry"| node_session
node_interceptor -->|"records decisions"| node_audit

click node_interceptor "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/interceptor.js"
click node_installer "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/install.js"
click node_sensitive "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/sensitive-guard.js"
click node_jevclient "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/jev-client.js"
click node_cycle "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/cycle-detector.js"
click node_variance "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/diff-variance.js"
click node_laws "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/core-laws-linter.js"
click node_context "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/state-collector.js"
click node_manifest "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/manifest-sniffer.js"
click node_acceptance "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/acceptance-gate.js"
click node_runner "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/runner-parser.js"
click node_session "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/cycle-detector.js"
click node_audit "https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/decision-tracker.js"

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_interceptor,node_installer toneBlue
class node_sensitive,node_jevclient,node_cycle,node_variance,node_laws,node_context,node_manifest toneAmber
class node_acceptance,node_runner toneMint
class node_session,node_audit toneRose
class node_agent,node_hooks,node_testexec,node_workspace,node_jev toneIndigo
```

## Components

### Lifecycle control

- [Hook coordinator](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/interceptor.js): `harness/interceptor.js`
- [Hook installer](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/install.js): `harness/install.js`

### Safety and context

- [Sensitive guard](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/sensitive-guard.js): `harness/sensitive-guard.js`
- [Jev decision client](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/jev-client.js): `harness/jev-client.js`
- [Cycle detector](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/cycle-detector.js): `harness/cycle-detector.js`
- [Edit variance](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/diff-variance.js): `harness/diff-variance.js`
- [Code law linter](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/core-laws-linter.js): `harness/core-laws-linter.js`
- [Context collector](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/state-collector.js): `harness/state-collector.js`
- [Workspace detector](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/manifest-sniffer.js): `harness/manifest-sniffer.js`

### Completion verification

- [Acceptance gate](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/acceptance-gate.js): `harness/acceptance-gate.js`
- [Runner parser](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/runner-parser.js): `harness/runner-parser.js`

### Session and audit

- [Session state](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/cycle-detector.js): `harness/cycle-detector.js`
- [Decision tracker](https://github.com/samarvscode/agentaegis_v2.0---universal-cognitive-interceptor-and-vetting-harness/blob/main/harness/decision-tracker.js): `harness/decision-tracker.js`

### Other components

- **Coding agent**
- **Lifecycle hooks**
- **Project test runner**
- **Workspace and disk**
- **TypeSafe Jev**

## Connections

- Coding agent → Lifecycle hooks: sends events
- Lifecycle hooks → Hook coordinator: invokes hooks
- Hook installer → Lifecycle hooks: configures hooks
- Hook coordinator → Sensitive guard: checks actions
- Hook coordinator → Cycle detector: checks repetition
- Cycle detector → Edit variance: classifies edits
- Hook coordinator → Code law linter: lints artifacts
- Hook coordinator → Context collector: builds context
- Context collector → Workspace detector: detects ecosystem
- Context collector → Workspace and disk: reads workspace
- Hook coordinator → Jev decision client: requests review
- Acceptance gate → Project test runner: runs tests
- Acceptance gate → Runner parser: parses output
- Acceptance gate → Workspace and disk: reconciles claims
- Acceptance gate → Jev decision client: requests approval
- Jev decision client → TypeSafe Jev: sends decisions
- Hook coordinator → Acceptance gate: gates completion
- Hook coordinator → Session state: loads and saves
- Acceptance gate → Session state: loads telemetry
- Hook coordinator → Decision tracker: records decisions