Harbor Engine

Harbor is the only engine that communicates with the outside world. It adapts Warden’s internal signals and verdicts into formats that specific assistants understand, exposes functionality through MCP tools, handles CLI commands, and (in the future) bridges to external orchestration systems.

If Reflex is the guard, Anchor is the compass, and Dream is the memory, Harbor is the voice.

The Assistant Trait

Harbor abstracts over different AI assistants through a Rust trait:

pub trait Assistant {
    /// Detect whether this assistant is currently running
    fn detect(&self) -> bool;

    /// Return the path to this assistant's settings/config file
    fn settings_path(&self) -> Option<PathBuf>;

    /// Format a deny message in this assistant's expected format
    fn deny_format(&self, reason: &str, pattern: Option<&str>) -> String;

    /// Format a context injection for this assistant's system prompt mechanism
    fn inject_format(&self, signals: &[Signal], budget: u8) -> String;

    /// Return the assistant's name for logging
    fn name(&self) -> &'static str;
}

The trait has five methods, each addressing a specific integration concern:

• detect — checks whether the assistant process is running (via process list inspection) or whether its configuration files exist. This is how Warden auto-discovers which assistant it is working with.
• settings_path — returns the path to the assistant’s configuration file so Warden can read project-specific settings, hook configurations, and allowlists.
• deny_format — each assistant displays tool-call denials differently. Claude Code expects a JSON object with a result field. Other assistants may expect plain text or a specific error code.
• inject_format — context injections must match the assistant’s system prompt mechanism. Claude Code uses the system field in hook responses. MCP-based assistants receive injections as tool responses.
• name — used for logging and status display.

Current Adapters

Claude Code

The primary adapter. Claude Code is a CLI-based AI coding assistant that supports hooks through a JSON-based protocol. The adapter:

• Detects Claude Code by checking for the claude process and the ~/.claude/ configuration directory
• Reads settings from ~/.claude/settings.json and project-level .claude/settings.json
• Formats denials as JSON objects matching Claude Code’s hook response schema
• Formats injections as system field content in the hook response, which Claude Code prepends to the assistant’s context

This adapter is the most mature and handles edge cases like View Transitions (where the assistant restarts but the session continues) and concurrent sessions (where multiple Claude Code instances run in different projects).

Gemini CLI

An experimental adapter for Google’s Gemini CLI assistant. The adapter:

• Detects Gemini CLI by checking for the gemini process
• Reads settings from the Gemini CLI configuration path
• Formats denials and injections using Gemini CLI’s hook response format

The Gemini CLI adapter is functional but less tested than the Claude Code adapter. It covers the core hook protocol but does not yet support all signal types for context injection.

Future Adapters

The Assistant trait is designed to be extended. Planned adapters include:

• Cursor — VS Code-based AI coding assistant with its own extension protocol
• Windsurf — Codeium’s AI coding environment
• Aider — terminal-based AI pair programming tool
• Continue — open-source AI coding assistant for VS Code and JetBrains
• OpenHands — open-source AI software development agent

Each adapter requires implementing the five trait methods. The core logic — pattern matching, session tracking, trust scoring — remains identical across assistants. Only the formatting and detection logic changes.

MCP Tools

Harbor exposes 6 tools through the Model Context Protocol (MCP), allowing assistants to query Warden directly:

MCP tools are read-only. They expose Warden’s state but do not modify it. This prevents the assistant from gaming the system by, for example, resetting its own trust score.

The MCP server runs as part of the Warden daemon and communicates over stdio or a Unix domain socket (configurable). It implements the MCP specification’s tool-calling protocol, including JSON Schema descriptions for each tool’s parameters and return types.

MCP integration flow

When an assistant queries warden_status, the flow is:

Assistant → MCP Client → Warden Daemon → Harbor → Anchor (read state)
                                                 → Reflex (read denial log)
                                                 → Dream (read artifacts)
                                       → Format response
                                       → MCP Response → Assistant

The response is a structured JSON object, not free-form text. The assistant can parse it programmatically or present it to the user as-is.

CLI Commands

Harbor handles all warden CLI commands that the user runs directly in the terminal:

CLI commands go through a different path than hook calls. They bypass Reflex entirely (there is no tool call to evaluate) and interact directly with the daemon’s state through IPC.

The CLI output is designed for human consumption — colored, formatted, and concise. MCP tool output is designed for machine consumption — structured JSON.

Bridge: External Integrations (Vision)

The Bridge module is Harbor’s planned extension point for connecting Warden to external systems beyond AI assistants. The vision includes:

LangChain Integration

Expose Warden’s safety and session-tracking capabilities as a LangChain tool or callback handler. LangChain agents could use Warden to validate tool calls before execution, receiving the same safety guarantees as direct assistant integrations.

CrewAI Integration

In multi-agent CrewAI workflows, Warden could serve as a shared safety layer — each agent’s tool calls pass through the same Reflex patterns and session tracking. Trust scores would be per-agent, allowing Warden to identify which agent in a crew is struggling.

AutoGen Integration

Similar to CrewAI, but adapted for AutoGen’s conversation-based multi-agent framework. Warden would intercept code execution requests and file operations across all agents in the conversation.

Webhook Integration

A generic webhook bridge that sends Warden events (denials, trust drops, session summaries) to external endpoints. This enables integration with Slack, PagerDuty, custom dashboards, and any system that can receive HTTP POST requests.

Design Principle

Bridge exists in the architecture but is not yet implemented. The key design constraint is that Harbor is the only engine that talks to the outside world. Reflex, Anchor, and Dream have no network access, no file system access outside .warden/, and no ability to spawn processes. All external communication routes through Harbor, which acts as a controlled gateway.

This isolation is both a security measure (a bug in Dream cannot exfiltrate data) and an architectural constraint (engines can be tested in isolation without mocking external dependencies).

Interaction with Other Engines

Harbor is the final stage in the hook processing pipeline:

• Reads from Reflex — verdict (Approve/Deny/Modify) and safety signals
• Reads from Anchor — session state, trust score, injection budget, and context signals
• Reads from Dream — resume packets and applicable artifacts for new sessions

Harbor’s only write operation is formatting and delivering the hook response. It does not modify session state, does not update trust scores, and does not create artifacts. It is a pure output formatter — the last mile between Warden’s internal analysis and the assistant’s input protocol.