Protocol specificationv1.0.0Apache-2.0

Portable security rules for AI agents.

HushSpec is an open specification for declaring what an agent may access, invoke, and send at the tool boundary: one rule language across runtimes, frameworks, and languages.

Read the spec Get started

policy.yamlhushspec 1.0.0

hushspec: "1.0.0"
name: coding-agent-quickstart
rules:
  forbidden_paths:
    patterns: ["**/.env", "**/.ssh/**"]
  tool_access:
    allow: [read_file, search]
    block: [deploy]
    require_confirmation: [write_file]
    default: block

tested decisions

tool_call→searchallow

file_read→/workspace/.envdeny

tool_call→write_filewarn

01 The boundary

policy ≠ enforcement

Declare what, never how.

AI agents interact with tools: file systems, network APIs, shell commands, MCP servers. HushSpec is a standard way to declare which of those interactions are allowed, blocked, or require confirmation.

The separation

Policy declares the boundary. The specification defines portable decisions and evidence. Your host mediates the actual effects.

Start with the runtime integration guide to check actions before dispatch. For engines such as Clawdstrike, verify the supported policy version and capabilities in the compatibility guide.

fail-closed

Invalid input is rejected. Unknown fields and malformed shapes never pass silently.

stateless

Evaluation does not execute actions. The host supplies context and owns state, confirmation, tool dispatch, and isolation.

engine-neutral

No coupling to any runtime. The same document moves between SDKs and engines.

extensible

Posture, origins, and detection thresholds ship as optional modules outside the core.

02 The rule language

12 rule types · 3 decisions

Twelve rules, one language.

Choose from twelve rule blocks. Compose them with conditions, inheritance, and optional extensions. A valid evaluation resolves to allow, warn, or deny; invalid policies are refused before use.

forbidden_paths

Block access to sensitive filesystem paths using glob patterns

path_allowlist

Allowlist-based read, write, and patch access control

egress

Network egress control by domain with allow/block lists

secret_patterns

Detect secrets in file content before they are written or transmitted

patch_integrity

Validate diff safety with size limits and forbidden patterns

shell_commands

Block dangerous shell commands before execution

tool_access

Control tool and MCP invocations with allow/block/confirm

computer_use

Control computer use agent actions with observe/guardrail modes

remote_desktop_channels

Control clipboard, file transfer, and drive mapping side channels

input_injection

Control keyboard, mouse, and touch input injection capabilities

browser_automation

Gate browser actions and navigation destinations

code_execution

Constrain execution runtimes, network access, and timeouts

Field-level documentation for every rule lives in the rules reference.

03 The SDKs

rust · typescript · python · go

Four languages, a shared core.

All four SDKs support parsing, validation, resolution, evaluation, guards, receipts, and signing. Feature flags and lifecycle APIs differ by language. The conformance matrix separates feature availability from verified claims.

parse→validate→merge→resolve→evaluate

SDK	Parse	Validate	Merge	Resolve	Evaluate	Receipts	Detection
Rust	yes	yes	yes	yes	yes	yes	yes
TypeScript	yes	yes	yes	yes	yes	yes	yes
Python	yes	yes	yes	yes	yes	yes	yes
Go	yes	yes	yes	yes	yes	yes	yes

Each language has a complete, tested guard example with a denied effect and an explicitly confirmed warning. Signing requires Rust's signing feature and Python's signing extra. Full detail in the SDK conformance matrix.

04 Tooling

22 top-level commands

The h2h command line.

h2h, hush to hush: one binary for the whole policy lifecycle. Validate, test, lint, and diff policies in CI; sign and verify them for distribution; flip the panic switch when something goes wrong.

h2h validate policy.yaml

Validate against the HushSpec schema

h2h test --policy policy.yaml --fixtures ./tests/

Run evaluation test suites

h2h init --preset default

Scaffold a new policy project

h2h lint policy.yaml

Static analysis and best-practice checks

h2h diff old.yaml new.yaml

Compare policies, show decision changes

h2h fmt policy.yaml

Format policy files canonically

h2h audit policy.yaml

Display governance metadata and advisory checks

h2h panic activate --sentinel /tmp/hushspec.panic

Emergency deny-all kill switch

h2h sign policy.yaml --key h2h.key

Sign a policy with Ed25519

h2h verify policy.yaml --keyring trusted-keys.json

Verify policy signatures against trusted keys

h2h keygen --output-dir ./keys

Generate a new Ed25519 keypair

Selected commands shown. All commands, options and exit statuses are in the CLI reference.

05 Ready to use

7 built-in profiles

Rulesets, ready to extend.

Seven built-in rulesets cover common deployment scenarios. Reference them with extends: and layer your own rules on top; the merge semantics are part of the spec.

default

Balanced security for AI agent execution

strict

Maximum security, minimal permissions

permissive

Development-friendly, relaxed limits

ai-agent

Optimized for AI coding assistants

cicd

CI/CD pipeline security

remote-desktop

Computer use agent sessions

panic

Deny-all emergency override

06 Beyond core

3 optional modules

Extensions, kept outside.

Three optional modules add state machines, origin-aware profiles, and detection thresholds without bloating the core. A conforming engine may implement none of them.

extensions.posturePostureA declarative state machine for capabilities and budgets. Transition between security postures on violations, timeouts, or approvals.Read the extension extensions.originsOriginsOrigin-aware policy projection. Apply different security profiles based on whether work arrives from Slack, GitHub, email, or other sources.Read the extension extensions.detectionDetectionDetection thresholds, portable heuristic_injection@1 behavior, and explicit boundaries for engine-specific detectors.Read the extension

Declare the boundary once. Any engine can enforce it.

Get started

Open specification · The normative spec, JSON Schemas, four SDKs,
the CLI, conformance fixtures, and built-in rulesets, all Apache-2.0.