Understanding the 10 Blocks in the ClosedClaw .claws File Specification

The .claws file format bundles ten numbered blocks (0–9) that define cryptographic identity, package metadata, natural language intent, typed interfaces, sandboxed execution logic, telemetry, persistent state, formal verification proofs, token compression mappings, and neural fingerprints into a single literate executable.

The ClosedClaw project (asafelobotomy/closedclaw) defines a "literate executable" format that merges declaration, code, and runtime metadata into one artifact. Understanding the .claws file specification requires examining its ten distinct blocks, each serving a specific purpose in the lifecycle of an AI agent skill—from hardware-bound trust anchors to behavioral drift detection.

Blocks 0–2: Trust, Metadata, and Intent

The first three blocks establish identity, declare capabilities, and describe behavioral constraints in natural language.

Block 0: Cryptographic Identity

Block 0 serves as the hardware-bound trust anchor for the .claws file. According to the specification in docs/experiments/proposals/claws-file-format.md, this block contains the SHA256 signature, signing key ID, and device binding flags that cryptographically tie the executable to specific hardware. This ensures that the tool’s code cannot be tampered with or replayed on unauthorized devices, providing the foundational security layer for all subsequent IO operations.

Block 1: Manifest

Block 1 declares the package metadata and runtime capabilities. It specifies the tool’s unique identifier (id), semantic version, schema_version, target runtime (e.g., deno_wasi_v2), and memory_strategy (such as ephemeral). Crucially, this block defines the capability permissions—for example, capability: "env.read" with specific keys—that constrain what system resources the Engine block can access. This declarative approach allows the kernel to enforce security policies before any code execution begins.

Block 2: The Vibe

Block 2 captures the natural language intent and behavioral constraints of the tool, functioning as a literate programming layer. It documents the tool’s purpose, trigger phrases that activate the skill, desired tone (e.g., "Friendly, concise"), and hard constraint rules (such as "Message length ≤ 200 characters"). While not executable code, this block provides the semantic context that guides how the LLM interprets outputs and handles edge cases, effectively serving as a contract between the human developer and the AI agent.

Blocks 3–4: Interface and Execution

These blocks bridge declaration and implementation, defining typed data contracts and the sandboxed logic that fulfills them.

Block 3: Claw-IDL

Block 3 defines the typed interface for all inputs and outputs, serving as the formal contract between the agent and the tool. As specified in docs/experiments/proposals/claws-file-format.md, the Claw Interface Definition Language (IDL) declares every argument with dialect annotations that control IO behavior:

• @dialect:context.* – Pulls default values from the agent’s long-term memory when arguments are missing.
• @dialect:secret – Masks sensitive values in logs and telemetry to prevent data leakage.
• @dialect:file – Returns a secure WASI file handle instead of a raw path string, preventing directory traversal attacks.
• @dialect:social.confidence_score – Enforces built-in refusal thresholds when model confidence falls below specified limits.

These annotations allow the kernel to validate inputs against the IDL before they reach the Engine and sanitize outputs before they return to the agent.

Block 4: Engine

Block 4 contains the executable logic that consumes the typed inputs from Block 3 and produces JSON outputs. The code—written in TypeScript, Rust, or Python—is compiled to WebAssembly (WASM) and executed in a sandboxed environment. As implemented in the runtime, the Engine receives typed arguments (such as InvoiceArgs) automatically mapped from the IDL declarations.

The block enforces runtime safety checks—for example, throwing "MessageTooLong" errors when constraints are violated—and returns a JSON payload that becomes the tool’s formal output for downstream agents. This separation of interface (Block 3) and implementation (Block 4) enables hot-swapping logic without changing the external contract, facilitating automated self-healing when telemetry indicates degradation.

Blocks 5–6: Observability and Persistence

These mutable blocks capture execution metadata and enable resumable computation across invocations.

Block 5: Telemetry

Block 5 provides observability and result reporting, maintaining a mutable JSON structure that the kernel updates after each execution. According to the specification, this block tracks execution_count, success_rate, avg_latency_ms, and errors.

The block operates as read-only for the agent—only the kernel can write to it—enabling the LLM to reason about tool performance without tampering with audit trails. This data drives automated confidence scoring, rate-limiting decisions, and self-healing triggers that can rewrite the Engine block when success rates degrade below acceptable thresholds.

Block 6: State Hydration

Block 6 manages persistent, resumable state through serialized VM snapshots or KV-cache fragments. This block serves dual IO purposes: it provides input to resumed executions (restoring previous context and cursor positions) and acts as output for long-running jobs (saving partial results before shutdown).

By maintaining a checkpoint_id and kv_cache_fragment, the block enables stateful agent workflows that can survive process restarts or migrate between compatible runtime nodes (such as different Deno WASI v2 instances) without losing conversational context or computation progress.

Blocks 7–9: Verification, Compression, and Security

The final blocks provide mathematical safety guarantees, optimize token economics, and detect anomalous execution patterns.

Block 7: Formal Verification Proof

Block 7 contains mathematical safety guarantees that formally verify the Engine’s IO behavior. As referenced in the canonical example from the specification, this block stores proofs that verify the Engine only reads declared inputs (such as environment variables specified in Block 1) and only writes to declared outputs, with no side effects outside the capability sandbox.

The kernel checks these proofs before execution, ensuring that interface contracts are mathematically enforced rather than merely conventionally followed, providing formal guarantees against unauthorized system access or data exfiltration.

Block 8: Lexicon

Block 8 provides token-level compression for IO efficiency, functioning as a stenographic mapping layer. This optional block defines terse symbols that expand to full semantic names—such as mapping "msg" to "message" or "tok" to "logToken"—reducing token costs when the LLM reads or writes data in the Telemetry and State blocks.

By compressing frequently used identifiers, the Lexicon minimizes API costs while preserving runtime readability, making it particularly valuable for high-throughput agents that frequently serialize state or telemetry data.

Block 9: Neural Fingerprint

Block 9 captures a behavioral signature of the model’s activation patterns during execution, serving as a meta-IO security layer. This block records the neural_digest and drift_thresholds (including soft_drift, hard_drift, and critical_shutdown limits) that characterize normal execution behavior.

The runtime compares live activation patterns against this fingerprint to detect anomalous IO such as prompt injection or logic hijacking, triggering alerts or automatic shutdowns when behavioral drift exceeds defined thresholds, providing a behavioral defense layer beyond static code analysis.

Complete .claws File Example

The following YAML structure from docs/experiments/proposals/claws-file-format.md demonstrates all ten blocks in a minimal echo tool:

---

# CRYPTOGRAPHIC IDENTITY

signature: "sha256:deadbeef..."
signed_by: "hardware_key_id"
device_binding: true
---

# MANIFEST

id: "net.closedclaw.sample.echo"
version: "0.1.0"
schema_version: "3.0"
runtime: "deno_wasi_v2"
memory_strategy: "ephemeral"
permissions:
  - capability: "env.read"
    keys: ["ECHO_PREFIX"]
---

# THE VIBE

# Purpose: Returns a prefixed echo of the user‑provided message.

# Trigger: When the user says “echo …”.

# Tone: Friendly, concise.

# Constraint: Message length ≤ 200 characters.

---

# CLAW‑IDL

interface EchoArgs {
  // Pull from conversation memory if missing
  @dialect:context.message   message: string;
  // Optional secret used only for logging
  @dialect:secret            logToken?: string;
}
---

# ENGINE

<script lang="typescript">
import { Env, Log } from "@closedclaw/std";

export async function echo(args: EchoArgs) {
  const prefix = Env.get("ECHO_PREFIX") ?? "";
  if (args.message.length > 200) {
    throw new Error("MessageTooLong");
  }
  Log.info(`Echo called`, { token: args.logToken });
  return { result: `${prefix}${args.message}` };
}
</script>
---

# TELEMETRY

{
  "execution_count": 0,
  "success_rate": 1.0,
  "avg_latency_ms": 0,
  "errors": []
}
---

# STATE

{
  "checkpoint_id": "",
  "kv_cache_fragment": ""
}
---

# FORMAL VERIFICATION PROOF

/* omitted for brevity – kernel checks that `echo` only reads `Env` and writes to output */
---

# LEXICON

{
  "mode": "compact",
  "mappings": {
    "msg": "message",
    "tok": "logToken"
  }
}
---

# NEURAL FINGERPRINT

{
  "signature_version": "2.0",
  "neural_digest": "...",
  "drift_thresholds": { "soft_drift": 0.85, "hard_drift": 0.75, "critical_shutdown": 0.65 }
}

This structure demonstrates how Block 3 (Claw-IDL) declares the expected input shape, Block 4 (Engine) implements the transformation, Block 5 records execution metrics, Block 6 persists intermediate state, Block 8 compresses field names, and Block 9 provides the behavioral fingerprint for runtime drift detection.

Summary

The ClosedClaw .claws file specification organizes agent capabilities into ten distinct blocks that separate concerns across identity, interface, execution, and observability:

• Block 0 (Cryptographic Identity): Hardware-bound trust anchor with SHA256 signatures and device binding.
• Block 1 (Manifest): Package metadata, runtime targeting, and capability permissions.
• Block 2 (The Vibe): Natural language intent, triggers, and behavioral constraints.
• Block 3 (Claw-IDL): Typed interface definitions with dialect annotations for secure IO.
• Block 4 (Engine): Sandboxed WASM executable logic consuming IDL inputs.
• Block 5 (Telemetry): Mutable execution metrics and observability data.
• Block 6 (State Hydration): Persistent checkpoints for resumable computation.
• Block 7 (Formal Verification Proof): Mathematical guarantees of IO safety.
• Block 8 (Lexicon): Token compression mappings for cost-efficient IO.
• Block 9 (Neural Fingerprint): Behavioral signatures for anomaly detection.

Together, these blocks create a self-describing, verifiable, and observable execution environment that enables safe agent interoperability.

Frequently Asked Questions

What is the difference between Block 3 (Claw-IDL) and Block 4 (Engine)?

Block 3 (Claw-IDL) declares the contract—it specifies what data types the tool expects, which arguments are secrets, and where context values should be pulled from. Block 4 (Engine) contains the implementation—the actual WASM-compiled code that executes the logic. This separation allows the kernel to validate inputs against the IDL before the Engine runs, and enables hot-swapping the Engine logic without changing the external interface.

How does Block 9 (Neural Fingerprint) improve security?

Block 9 stores a neural_digest representing the model’s expected activation patterns during normal execution. The runtime monitors live activations and compares them against the stored fingerprint using drift_thresholds (soft, hard, and critical). If the model’s behavior deviates significantly—indicating potential prompt injection or logic hijacking—the system triggers alerts or automatic shutdowns, providing a behavioral layer of defense beyond traditional input validation.

Can Block 6 (State Hydration) be used across different runtime environments?

Yes. Block 6 stores serialized VM snapshots or KV-cache fragments in a portable format defined by the checkpoint_id and kv_cache_fragment fields. Because the state is serialized at the WASM sandbox level rather than the host level, it can be migrated between compatible runtime nodes (such as different Deno WASI v2 instances) without losing conversational context or computation progress, enabling distributed and resilient agent workflows.

Why is Block 8 (Lexicon) optional if it improves token efficiency?

Block 8 is optional because not all tools require high-frequency IO optimization. Simple tools with few arguments or low invocation rates may not benefit from the added complexity of maintaining a stenographic mapping. However, for high-throughput agents where Telemetry and State blocks are updated frequently, the Lexicon provides significant cost savings by compressing common field names (e.g., mapping "msg" to "message"), making it a valuable optimization for production deployments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}