hanzo-protocol

Core protocol types for Hanzo AI agents.

Overview

This crate defines the fundamental types used throughout the Hanzo AI ecosystem, including:

AskForApproval - Human-in-the-loop approval policies
SandboxPolicy - Filesystem and execution sandboxing
Protocol messages - Internal communication types
Configuration - Agent configuration schemas

Installation

[dependencies]
hanzo-protocol = "0.6"

Key Types

AskForApproval

Controls when the agent pauses to request human confirmation:

use hanzo_protocol::AskForApproval;

let policy = AskForApproval::OnRequest; // Model decides when to ask

match policy {
    AskForApproval::Never => { /* Full autonomy */ }
    AskForApproval::OnFailure => { /* Ask only on errors */ }
    AskForApproval::OnRequest => { /* Model decides */ }
    AskForApproval::UnlessTrusted => { /* Ask for risky operations */ }
}

Policy	Description
`Never`	Full autonomy - never ask
`OnFailure`	Ask only when operations fail
`OnRequest`	Model decides based on risk assessment
`UnlessTrusted`	Ask unless operation is known-safe

SandboxPolicy

Controls what operations are physically allowed:

use hanzo_protocol::SandboxPolicy;

let policy = SandboxPolicy::WorkspaceWrite {
    writable_roots: vec![],
    network_access: true,
    exclude_tmpdir_env_var: false,
    exclude_slash_tmp: false,
    allow_git_writes: true,
};

match policy {
    SandboxPolicy::DangerFullAccess => { /* No restrictions */ }
    SandboxPolicy::ReadOnly => { /* Read-only filesystem */ }
    SandboxPolicy::WorkspaceWrite { .. } => { /* Write to workspace only */ }
}

Policy	Filesystem	Network	Processes
`DangerFullAccess`	Full	Full	Full
`WorkspaceWrite`	Read all, write workspace	Configurable	Allowed
`ReadOnly`	Read only	Blocked	Limited

Modules

Module	Description
`config_types`	Configuration schemas
`protocol`	Core protocol definitions
`models`	Data models
`mcp_protocol`	MCP-specific types
`responses`	Response structures
`tool_config`	Tool configuration

Example: Agent Configuration

use hanzo_protocol::{AskForApproval, SandboxPolicy, AgentConfig};

let config = AgentConfig {
    approval_policy: AskForApproval::OnRequest,
    sandbox_policy: SandboxPolicy::WorkspaceWrite {
        writable_roots: vec!["/home/user/project".into()],
        network_access: true,
        exclude_tmpdir_env_var: false,
        exclude_slash_tmp: false,
        allow_git_writes: true,
    },
    timeout_ms: 30000,
    ..Default::default()
};

TypeScript Bindings

This crate uses ts-rs to generate TypeScript type definitions:

cargo test --features ts-rs
# Generates TypeScript bindings in ./bindings/

Related Crates

hanzo-mcp-types - MCP type definitions
hanzo-mcp-client - Async MCP client
hanzo-zap - Zero-copy Agent Protocol

hanzo-protocol 0.6.0