# Teaching Script — DD-16: ZeroClaw — The Rust Microkernel Harness

**Deep-Dive**: DD-16 · **Duration**: 60 minutes · **Word count**: ~3,200 words (~140 wpm)
**Use**: Verbatim transcript with [SLIDE N] cues. Each cue marks the slide change.

---

[SLIDE 1] Title

Welcome to Deep-Dive 16. This is ZeroClaw — the Rust microkernel harness. Thirty-two thousand stars on GitHub, Apache-2.0, single Rust binary. By the end of this hour, you will be able to explain ZeroClaw's trait-driven kernel, recite its six-layer safety model in order, analyze its thickness paradox, and score it on the twelve-module rubric.

Here is what makes ZeroClaw important to this course. It is the Rust answer to the Claw family. It is explicitly positioned as the lightweight, provider-agnostic, self-hostable alternative to OpenClaw. No telemetry, no SaaS, no license server. But the headline is not "thin harness." The headline is a specific architectural decision that makes everything else possible.

[SLIDE 2] The thesis — trait-driven kernel is the cleanest extensibility model

The defining architectural decision is documented as ADR-002 — trait-driven extensibility. The kernel depends ONLY on the `zeroclaw-api` traits. Those traits are `ModelProvider`, `Channel`, `Tool`, `Memory`, `Observer`, `RuntimeAdapter`, and `Peripheral`. The kernel never depends on concrete implementations.

This is the cleanest separation of concerns in the entire roster. Adding a provider, a channel, or a tool is a trait impl wired through a factory — it is never a core patch. The provider-specific code lives outside the kernel, behind a feature flag, and the kernel never sees it.

The second half of the thesis is the six-layer safety model. Channel access control, autonomy level, workspace boundary, shell policy, OS sandbox, and tool receipts. Each layer blocks a different attack class. They compose as a cascade, not a toggle. This is the deepest safety surface in the thin-harness category.

The load-bearing claim for this deep-dive: ZeroClaw's six-layer safety model is the reference architecture for thin-harness security. Its tool-receipt system — HMAC-SHA256 over successful tool calls — is the only harness that directly addresses the fabricated-tool-claim attack from Module 11 at the protocol layer. And the trait-driven kernel is what makes the twenty-five-plus provider slots possible without core bloat.

[SLIDE 3] The trait-driven kernel — how adding a provider works

Let me walk you through what happens when you add a new LLM provider to ZeroClaw. Step one: you write a `ModelProvider` trait impl for the new vendor. Step two: you register it in the provider factory. Step three: you add a Cargo feature flag so it only compiles when someone needs it. Step four: you reference it by name in `zeroclaw.toml`.

Notice what is NOT in that list. You do not patch the core. You do not add provider-specific code to the kernel. You do not touch `zeroclaw-runtime`. The kernel imports the trait, never the implementation. This is why twenty-five-plus provider slots scale without the codebase collapsing — each one is an isolated trait impl behind a feature flag.

The same pattern applies to channels, tools, memory backends, and peripherals. The trait-driven kernel is not just a code-organization decision. It is the property that makes the entire breadth of the harness possible. Without it, you get the bloat problem that kills most "support everything" harnesses.

[SLIDE 4] The 6-layer safety cascade

Now the heart of the deep-dive — the six-layer safety model. This is ZeroClaw's most engineered aspect, and the reason it scores five out of five on Module 6.

Layer one is channel pairing and access control. `allowed_users`, `allowed_chats`, webhook IP allowlists. This is enforced at the channel adapter — BEFORE the runtime ever sees the event. If the message comes from a user or chat that is not on the list, it never enters the agent loop.

Layer two is autonomy level. Three modes: `readonly`, `supervised` (the default), and `full`. Tools are risk-classified. Low-risk tools run automatically. Medium-risk tools ask the operator for approval. High-risk tools are blocked entirely. This is Module 6's risk-tiering principle applied per-tool, not one gate for all actions.

Layer three is the workspace boundary and path rules. `workspace_only` confines reads and writes to the workspace. `forbidden_paths` always blocks `/etc`, `/sys`, `~/.ssh`, regardless of anything else. A tool call that tries to read `/etc/passwd` dies here.

Layer four is shell command policy. `allowed_commands` is a strict allowlist. `forbidden_commands` is an explicit denylist. The pattern-matcher runs BEFORE the shell executes the command. This is the correct layer for shell injection defense — block at the policy gate, not detect at the audit log.

Layer five is the OS-level sandbox. Auto-detected at runtime. Landlock, Bubblewrap, Firejail, or Docker on Linux. Seatbelt on macOS. AppContainer on Windows. The harness detects what is available and uses it.

Layer six is tool receipts. HMAC-SHA256 over every successful tool call and its result, fed back into the conversation. This detects fabricated-tool-claim attacks from Module 11. If the model says "the file says X" but no receipt exists for that file read, the harness can flag the fabrication.

Each layer is independently defeatable, but the default ships all six on. This is Module 6's risk-tiering principle taken to its logical conclusion. Not one gate. A cascade.

[SLIDE 5] Where security runs in the loop

Now I want you to internalize WHERE the security check runs in the agent loop, because the placement is load-bearing.

Here is the loop. Channel delivers a message. Runtime receives it. Provider dot chat streams the model. The model emits a tool call. Security dot validate runs the six layers. If allowed, the tool invokes. The result goes back to the provider. The reply goes back to the channel.

The security check runs BETWEEN the model emitting a tool call and the tool executing. That is the placement. It is not a pre-filter on user input — the model might generate a benign-looking input that produces a dangerous tool call. It is not a post-hoc audit log — detecting a bad command after it ran is too late. It is a gate between model-intent and tool-execution.

A block at this gate surfaces as `ToolResult::Err`. The model sees the error and can react to it — try a different approach, ask for clarification, or report failure to the user. It is NOT a silent failure. The model is told, in band, that its action was blocked and why.

The model cannot bypass layer four — the shell policy runs before the shell. The model cannot bypass layer six — the receipt is computed by the harness, not the model. The security check is in the one place where every model-emitted action must pass through it.

[SLIDE 6] Tool receipts vs the fabricated-tool-claim attack

Let me dwell on layer six, because it is the most novel defense in the roster.

The attack: the model claims "the file says X" or "the tool returned Y" — fabricating a tool result to justify a downstream action. Maybe it wants to exfiltrate data and needs a plausible reason to call an egress tool. Maybe it wants to escalate and needs a fake justification. Most harnesses have no in-context evidence to contradict this fabrication. The model said it; the conversation proceeds as if it were true.

The defense: every successful tool call gets an HMAC-SHA256 receipt over the call and its result. That receipt is fed back into the conversation. Now the model's claim has to survive a check. If the model says "the file says X" but no receipt exists for that file read, the harness can flag the fabrication. The receipt is in-context evidence that the tool actually ran and actually returned what the model claims.

Here is the honest limitation. The receipts use ephemeral keys. They are an in-context integrity signal TODAY — they defend against fabrication within the current session. They are NOT yet a chained, cross-signed, durable audit log. If you need post-hoc forensics — proving to a third party what happened after the session ends — the receipt system does not give you that yet. Treat it as a defense against fabrication, not a forensic record. Making it durable is fix number two on the architect's list.

[SLIDE 7] The thickness paradox

Now I have to give you the honest tension at the center of ZeroClaw, because it is the most common misreading of the harness.

The philosophy is uncompromisingly thin. Single binary. No telemetry, no SaaS, no license server. No hidden system prompts — the docs say, "the model sees what you configure." Self-hostable, operator-owned. That is the philosophy.

The implementation is medium-thick. Approximately seven hundred to eight hundred thousand lines of Rust across one thousand and fifteen files. The binary is twenty-six megabytes. The config schema alone is 1.3 megabytes of Rust. Twenty-five-plus provider slots, thirty-plus channel impls. And then there is the hardware support — GPIO, I2C, SPI, USB. That is thickness most thin harnesses do not carry.

So the correct reading is NOT "thin harness means small codebase." That is the anti-pattern. The correct reading is: thin by design intent, medium-thick by implementation, with an active refactor closing the gap.

That refactor is RFC 5574 — the microkernel roadmap. It is shrinking `zeroclaw-runtime` so the kernel is just loop plus policy, with everything else behind feature flags. The foundation reportedly builds with `--no-default-features`. When it is complete, the default surface will be genuinely thin, with providers, channels, and hardware as opt-in features. That is the direction. For now, read "thin" as a design intent, not a line-of-code count.

[SLIDE 8] Explicit-only memory — a security choice, not a missing feature

The next thing you need to internalize is ZeroClaw's memory design, because it is the opposite of a harness we covered earlier — Hermes, DD-08 — and the difference is a deliberate security choice.

In ZeroClaw, prompt context, tool output, files, and logs are NOT durable memory by default. A turn only becomes memory if the agent calls `memory_store` explicitly. Backends include SQLite, Postgres, Qdrant for vectors, and per-agent Markdown files.

The security property this gives you: an indirect injection cannot silently persist itself. If a malicious instruction arrives inside a tool output, it can influence the current turn — but it cannot write itself to durable memory without an explicit `memory_store` call, which the security cascade gets to inspect.

Now compare Hermes. Hermes uses model-initiated free writes — the agent writes to memory freely across turns. That enables compounding capability. The agent can self-evolve skills, remember procedures, build up a knowledge base. But it creates a larger poisoning surface. A successful injection persists and compounds.

The trade is capability versus security. ZeroClaw trades compounding capability for a smaller poisoning surface. Both designs are defensible. The choice depends on whether your deployment values compounding — in which case Hermes-style free writes are worth the risk — or hardening — in which case ZeroClaw's explicit-only memory is the right call. Do not read ZeroClaw's design as a missing feature. Read it as the opposite trade.

[SLIDE 9] Score: 34/60

Let us score it. ZeroClaw earns thirty-four out of sixty on the twelve-module rubric.

The win is Module 6, Permission and Safety: five out of five. The six-layer model is the deepest in the thin-harness category. No other thin harness matches this safety surface. Module 2, Tools: four out of five — browser, HTTP, hardware probes, all trait-extended. Module 5, Sandbox: four out of five — auto-detected OS-level sandboxes across Linux, macOS, and Windows. Module 12, Prompt: four out of five — the minimal-prompt philosophy, operator-owned, no hidden prompts.

The losses are Module 3, Context Management: two out of five. Basic history trimming only. No sophisticated context-budget system. This is where PicoClaw, DD-17, does better with its turn-boundary trimming. And Module 9, Verification: two out of five — limited.

If you are keeping notes, the headline is: deepest safety surface in the thin-harness category, but the context-management story is underdeveloped.

[SLIDE 10] 3 things it does better, 3 things to fix

Three things ZeroClaw does better. One: the trait-driven kernel — the cleanest separation of concerns in the roster. Adding anything is a trait impl, not a core patch. Two: the six-layer safety model — deepest safety surface in the thin-harness category. Auto-detects OS sandbox, shell allowlisting, tool receipts. Three: provider agnosticism — twenty-five-plus slots with routing, retry, key rotation, and per-vendor OAuth. No other harness matches this breadth.

Three things to fix. One: close the microkernel gap. Seven hundred thousand lines of Rust contradicts the thin philosophy. RFC 5574 is the right direction — finish it. Two: durable audit log. Tool receipts use ephemeral keys. Make them chained, cross-signed, and persistent. Three: context management. Basic history trimming is insufficient. Add turn-boundary trimming like PicoClaw's, and build a real context-budget system.

[SLIDE 11] What you can now do

Let us close with what you should be able to do now.

One: explain ZeroClaw's trait-driven kernel — ADR-002 — and why it is the cleanest separation of concerns in the roster.

Two: recite the six-layer safety model in order. Channel pairing, autonomy level, workspace boundary, shell policy, OS sandbox, tool receipts. And explain how the layers compose as a cascade rather than a toggle.

Three: analyze the thickness paradox. Thin by philosophy, medium-thick by implementation, with RFC 5574 closing the gap.

Four: evaluate the tool-receipt system as a defense against fabricated-tool-claim attacks from Module 11. And name its limitation — ephemeral keys mean it is not yet a durable audit log.

Five: score ZeroClaw — thirty-four out of sixty. Explain the wins — Module 6 at five out of five — and the losses — Module 3 at two out of five. And judge when to build on it: when Rust-native safety, provider agnosticism, and self-hosting are requirements.

The lab: you will build a minimal simulation of ZeroClaw's six-layer safety cascade in Python. You will model each layer as a gate function, send a sequence of tool calls through the cascade, and confirm which calls are blocked at which layer. Then you will implement the tool-receipt system — HMAC over tool calls — and confirm it detects a fabricated tool claim.

That is ZeroClaw. Next is DD-17, PicoClaw — the Go thin-harness cousin. Same family, different language, different tradeoffs.

---

End of script.