Skip to main content

ADR-001: Agent Security Layer Architecture

Status: Proposed Date: 2026-02-18 Deciders: CODITECT Architecture Team Source Research: ClawGuard AI Agent Security Ecosystem Evaluation (2026-02-18)

Context​

The CODITECT platform executes AI agents that invoke tools, read files, call external APIs, and manipulate system state. As agent autonomy increases — particularly through Ralph Wiggum autonomous loops and multi-agent orchestration — the attack surface for prompt injection, secret exfiltration, and destructive command execution grows proportionally.

A comparative evaluation of 3 open-source tools from the ClawGuard ecosystem was conducted:

  • ClawGuardian (superglue-ai): TypeScript hook-based OpenClaw plugin (score: 85/100). Production-ready with 45,205 lines of tests, severity-based action routing (block/redact/confirm/warn/log), stateless design.
  • clawguard (JaydenBeard): Node.js/Express activity monitor dashboard (score: 78/100). Most comprehensive risk pattern library (55+ patterns), real-time WebSocket monitoring, kill switch capability, multi-gateway support.
  • ClawGuard (maxxie114): Python/FastAPI email sanitization server (score: 65/100). Solid Pydantic-modeled pattern library, limited scope (email input only).

Additionally, lauty1505/clawguard was identified as a trojanized fork containing an injected binary (Software-tannin.zip) and was immediately excluded. This incident itself validates the need for supply chain awareness within AI agent security tooling.

CODITECT currently has no dedicated security interception layer between agent instructions and tool execution. The hook system (118 hooks in hooks/) provides a technical foundation, but it is not purpose-built for security filtering.

The key architectural question is: how should CODITECT implement a security interception layer — by adopting an existing tool, building natively, or introducing a proxy layer?

Decision​

Build a CODITECT-native agent security layer inspired by the ClawGuardian hook architecture, rather than adopting ClawGuardian directly or introducing a third-party proxy.

The native layer will:

  1. Implement security interception at three agent lifecycle points mirroring ClawGuardian's model:

    • Pre-execution (system prompt inspection before agent initialization)
    • Pre-tool-call (input filtering and risk scoring before each tool invocation)
    • Post-tool-result (output redaction before results are persisted or returned)

  2. Be implemented in Python to align with CODITECT's existing script ecosystem (scripts/ — 581 scripts, all Python).

  3. Integrate with the existing CODITECT hook system (hooks/) as a first-class hook category: security-pre-tool, security-post-tool, security-pre-agent.

  4. Carry no dependency on OpenClaw, MoltBot, ClawdBot, or any external agent framework.

  5. Be configurable per tenant via CODITECT's existing tenant configuration infrastructure.

Consequences​

Positive​

  • Full control over implementation: No upstream breakage risk from ClawGuardian's openclaw >=2026.1.0 peer dependency version drift.
  • Native Python: Aligns with CODITECT's existing toolchain, enabling shared utilities (scripts/core/paths.py, org.db logging, tenant config).
  • Hook system integration: Security events become first-class hook events, enabling MoE routing, session logging, and alerting through existing infrastructure.
  • Tenant isolation: Per-tenant security policy configuration (fail-open/fail-closed, severity thresholds, pattern sets) is achievable without architectural debt.
  • No transitive supply chain risk: ClawGuardian itself is MIT-licensed and appears sound, but building natively eliminates any dependency on an external package ecosystem.

Negative​

  • Maintenance burden: The CODITECT team owns the full security pattern library and lifecycle hook implementation. ClawGuardian's 45K-line test suite would need to be replicated for the native layer.
  • Slower initial coverage: ClawGuardian ships with production-ready PII, API key, cloud credential, and destructive command patterns. The native implementation starts from scratch (though patterns can be ported from the YAML pattern library — see ADR-002).
  • Risk of security gaps during development: The native layer must be treated as security-critical code from day one, requiring dedicated security review cycles.

Neutral​

  • The ClawGuardian codebase remains available as a reference implementation and pattern source. Porting its TypeScript patterns to CODITECT's YAML pattern format (ADR-002) is straightforward.
  • JaydenBeard's 55+ shell command risk patterns are directly portable and should be incorporated into the initial pattern library.

Alternatives Considered​

Alternative A: Adopt ClawGuardian Directly​

Approach: Import @yourclaw/clawguardian as a dependency. Wrap CODITECT agent tool calls in an OpenClaw-compatible adapter to trigger its hooks.

Rejected because:

  • Introduces a hard peer dependency on openclaw >=2026.1.0, a third-party framework CODITECT does not use.
  • ClawGuardian is stateless and assumes OpenClaw manages all state — CODITECT's state model (org.db, sessions.db) would not be natively wired.
  • Any breaking change in the OpenClaw plugin contract would cascade to CODITECT's security layer with no control over the timeline.
  • Node.js runtime dependency is undesirable in a Python-primary codebase.

Alternative B: Proxy Layer (Middleware Gateway)​

Approach: Run ClawGuardian or a custom security gateway as a sidecar service. All agent tool calls pass through the proxy via HTTP.

Rejected because:

  • Introduces network latency on every tool call — unacceptable for interactive sessions.
  • Adds operational complexity (sidecar lifecycle management, health checks, failover).
  • A proxy that is unavailable creates an automatic fail-open condition unless carefully engineered — moving the reliability problem rather than solving it.
  • Mixes deployment concerns with security policy concerns.

Alternative C: No Dedicated Security Layer (Rely on Existing Hooks)​

Approach: Use existing CODITECT hooks (PreToolUse, PostToolUse) with ad-hoc security checks added to relevant scripts.

Rejected because:

  • Existing hooks (task_id_validator.py, task-tracking-enforcer.py) are governance hooks, not security hooks. Mixing concerns increases fragility.
  • Security patterns scattered across hook scripts are ungovernable — no centralized pattern library, no unified severity model, no per-tenant policy.
  • The lauty1505/clawguard trojan incident demonstrates that security tooling itself requires structured, auditable, supply-chain-verified implementation.

Implementation Notes​

  • Primary module: scripts/core/security/ (new directory)
  • Hook registration: hooks/security-pre-tool.json, hooks/security-post-tool.json, hooks/security-pre-agent.json
  • Pattern library: config/security-patterns/ (YAML format — see ADR-002)
  • Risk scoring: Hybrid numeric + categorical model (see ADR-004)
  • Fail behavior: Fail-open by default, configurable per tenant (see ADR-003)
  • Supply chain controls: See ADR-005

References​

  • ClawGuardian source: submodules/core/coditect-core/analyze-new-artifacts/clawguard-ai-agent-security/ (superglue-ai)
  • Research context: analyze-new-artifacts/clawguard-ai-agent-security/artifacts/research-context.json
  • Related ADRs: ADR-002 (Pattern Library Format), ADR-003 (Fail Behavior), ADR-004 (Risk Scoring), ADR-005 (Supply Chain Detection)
  • Existing hooks: submodules/core/coditect-core/hooks/ (118 hooks)