The Ideal Harness

The Ideal Harness

The control-plane OS around a stateless model — it turns probabilistic reasoning into deterministic, governed, safe action.

An agent harness with deep Claude Code integration and an MCP-portable enforcement and tooling core.

github.com/bharat3645/The-Ideal-Harness · MIT · built by Bharat

---

The problem

Every "best harness" is a partial.

• The skills project gives you reusable workflows, but no enforcement — a skill can tell the agent to run curl … | bash and nothing stops it.
• The memory project remembers, but does not compress — it hands the model whole files and burns the context window it was meant to save.
• The compression project compresses, but does not remember — it shrinks one tool result and forgets the rest of the session.
• The orchestration project sequences work, but assumes you are the harness — it lives inside one host, and the moment you switch agents the guarantees evaporate.

Each one is real and good. None of them is the whole stack. Wire four of them together and you get four overlapping notions of "state," two competing policy stories, and a safety floor that is really just a polite paragraph in a prompt.

So we built the one that has every layer, with no overlap.

What it is

The Ideal Harness is the control-plane OS around a stateless model: it turns probabilistic reasoning into deterministic, governed, safe action. It is a clean-room synthesis of best-of-breed ideas from ~30 leading harness, skill, memory, and web repos — Superpowers, gstack, gsd-core, hermes, omnigent, headroom, graphify, claude-mem, chrome-devtools-mcp, impeccable, SkillSpector, last30days, firecrawl, and others — rationalized into one coherent monorepo where every capability has exactly one home. One chosen mechanism per capability. The alternatives we rejected are documented, not silently dropped.

We read those ~30 repos to ground truth, took the best idea from each, and threw away the vaporware. What survived is six modules that share one substrate and one enforcement floor, with zero feature overlap between them.

The safety layer is not advice to the model. It is deterministic code that runs below the model, on PreToolUse / PostToolUse hooks. The model proposes; the floor disposes.

The numbers

Measured on a real codebase (the Voraxx worker source: 105 files, 33,629 LOC, indexed in 16 ms into 2,707 symbols; whole-repo secret scan covered 2,577 files). These are the only metrics we claim, and a couple of them are deliberately unflattering — the ones that can't be faked are the proof that the rest are real. The Voraxx corpus is external and is not bundled in this repo, so these exact token counts can't be re-run from here; the methodology and per-case breakdown are in [BENCHMARK.md](./BENCHMARK.md), and the compressors themselves are covered by the in-repo unit tests.

| Capability | Measurement | Result | |---|---|---| | Context (code-graph) | answer a code question via token-budgeted subgraph vs reading the files | ~1,988 tokens vs 17,323–37,369 → 8.7x–18.8x less | | Compression (structured) | 2,707-row JSON tool output | 100,728 → 196 tokens → 99.8% saved | | Compression (log) | 2,969-line grep log, mostly unique lines | 91,544 → 88,402 tokens → 3.4% saved | | Secret redaction | swept 2,577 files | flagged 40 secret-shaped strings across 18 files | | Policy engine | 10 realistic requests | 2 allow / 4 ask / 4 deny | | Drift-guard | 3 real symbols + 1 fabricated | 3 found, 1 flagged missing, 0 false hard-block | | Malicious-skill vet | skill with curl … \| bash + "ignore all previous instructions" | blocked (high severity) |

On the honest ones:

• 3.4% on the grep log is the whole point. Unique lines barely compress, so we report it plainly. Structured output collapses from 100,728 to 196 tokens; an unstructured log does not. A harness that claimed otherwise would be lying.
• The 40 secret-shaped strings include test fixtures; the named categories break down as jwt 10, private-key 5, bearer 5, aws 2, anthropic 1, github 1, with the remainder in unnamed categories. The claim is deterministic detection before anything reaches the model or the logs — not "this repo is leaking."
• The policy denials were credential reads, rm -rf, and a write to the policy file itself. The floor refuses to let the agent edit its own floor.
• The drift-guard was handed 3 real symbols and 1 invented one: it found all 3, flagged the fabricated one missing, and hard-blocked nothing real. Hallucinated symbols get caught before they become broken edits.
• The vetting scanner blocked a skill carrying curl … | bash and "ignore all previous instructions" at high severity — before it could be installed, not after it ran.

The six modules

Each is an independently installable plugin; core is required. Every engine also runs as a standalone MCP server and CLI.

| Module | Role | What lives here | |---|---|---| | core | substrate | Plugin loader, manifest + skill validation, dependency-free skill templating with multi-host generation (Claude Code, Codex, Gemini, Cursor), a bootstrap skill, and the minimal MCP stdio server every other engine reuses. | | guard | enforcement floor, below the model | Deny-wins / fail-closed policy engine (leases > user policy > team policy > default floor) with Anthropic-aligned defaults, prompt-injection wrapping, always-on secret redaction, a scoped secrets broker, a skill-vetting scanner (threat-signature DB + homoglyph / hidden-char detection), a drift-guard authority ladder that catches hallucinated symbols, a hash-chained audit journal, time/call-boxed capability leases, and an OS sandbox command builder (Seatbelt / bubblewrap) with subprocess env-scrub. PreToolUse / PostToolUse hooks make policy, outbound-secret blocking, secret redaction, and injection fencing automatic; sandbox, vetting, drift-guard, leases, and the broker are MCP tools / CLIs the host invokes (see below). | | compress | context economy | Deterministic, prompt-cache-safe tool_result compression — anomaly-preserving JSON sampling, log RLE, stack-trace collapse — gated by a token threshold, with a Compress-Cache-Retrieve (CCR) store for lossless recovery, plus the caveman output-side terse mode. | | memory | recall | A structural code-graph (optional tree-sitter tier, persisted + incrementally re-indexed) with token-budgeted subgraph retrieval, and an episodic store ranked by real BM25 relevance — with consolidation/decay, provenance (evidence) on records, and a CLI-only Obsidian export/import bridge — kept honest by a curator that reconciles claims against tool-call evidence. | | orchestrate | control flow | Durable task ledger with real, policy-gated, sandboxed verification (ledger_verify actually runs a task's check instead of trusting a self-report), worktree fan-out for parallel tasks, a retro generator, loop / no-progress guard, spend governor, API retry / backoff, session resume / checkpoint, plus subagent-driven-development and brainstorming (HARD-GATE) skills. | | web | grounding | Deliberately scoped to fetch() + a hand-rolled HTML extractor — no browser/scraping dependency (see decisions.md D012). web_fetch for any URL, web_docs for live npm registry metadata/README (fights stale-training-data hallucination on package APIs). Both policy-gated exactly like the native WebFetch tool, including the operator's own policy/lease configuration, plus an SSRF guard (blocks localhost/private/link-local/cloud-metadata targets and re-validates every redirect hop — DNS-rebinding is a stated, not hidden, residual gap; see decisions.md D026). |

Universality, told honestly

This is not a multi-backend runtime. Portability comes in two tiers, and we draw the line where it actually is.

• Tier 1 — deep, Claude Code-native. SessionStart / PreToolUse / PostToolUse hooks, automatic guardrails, the full skill + plugin experience. The floor enforces itself with no cooperation from the model.
• Tier 2 — any MCP-capable agent (Cursor / Cline / Codex / Gemini). Every engine ships as a standalone MCP server and CLI, so other hosts get the tools and the enforcement primitives. Skills port via multi-host SKILL.md generation.

What does not travel: hook-driven automatic enforcement. On a Tier-2 host, nothing fires on its own — the host must call the policy, sandbox, and vetting CLIs itself. We would rather say this out loud than pretend the floor is free everywhere.

What runs automatically on every tool call (Tier 1)

Two guard hooks fire deterministically around every tool call — no prompt, no model cooperation. This is the floor that runs on its own:

PreToolUse — before the call executes:

1. Policy check. Deny > allow > ask, fail-closed (Claude Code's own precedence). Credential reads, rm -rf, and writes to the policy file are denied; read-only git is allowed; ambiguous actions become an ask, not a silent allow. The floor is soft by default — denies downgrade to asks so the human decides, mirroring Claude Code's out-of-the-box posture — and operator-tunable, never model-tunable: IDEAL_HARNESS_FLOOR_MODE=enforce restores hard denies, ideal-harness.policy.json (project root or ~/.config/) adds a higher rule tier or disables defaults by id, and claude --dangerously-skip-permissions (or IDEAL_HARNESS_DANGEROUSLY_SKIP_PERMISSIONS=1) waives the permission gate entirely. Every softening is announced on stderr; a broken user policy falls back to the pristine defaults; an unrecognized mode value fails strict.
2. Outbound-secret block. Egress tools (Bash, Write, Edit, WebFetch) are scanned; a call that would carry a secret out is blocked before it runs.
3. Decision journal + learning loop. Every decision is appended (secret-redacted, fail-open) to .ideal-harness/guard-journal.jsonl; ideal-harness-guard learn turns repeated approvals into proposed allowlist entries the human may paste into the policy file — the harness never applies them itself.

PostToolUse — on the result, before the model reads it:

1. Secret redaction. The result is rewritten with secrets masked as [REDACTED:type] (via the updatedToolOutput contract) before the model sees it — the same detector that flagged 40 secret-shaped strings across 18 files on a 2,577-file repo.
2. Injection fencing. Web/MCP output, or any result tripping an injection cue, is wrapped in a breakout-safe `` fence so the model treats it as data, not instructions.

At SessionStart, the using-ideal-harness bootstrap skill is injected so the model knows the floor is active and how to route.

Tools the agent or host invokes — deterministic, but not automatic

These are the rest of the floor and the engines. They are real, deterministic code exposed as MCP tools and CLIs — the model or host calls them deliberately; they are not (yet) hook-applied. Auto-applying sandbox (via PreToolUse updatedInput) and compression (via PostToolUse updatedToolOutput) is the next wiring step on the roadmap. See flow.md for the exact sequence each of these follows.

• Sandbox — buildSandboxCommand wraps a shell command in a Seatbelt / bubblewrap profile with a scrubbed env (CLI / primitive); applied automatically inside ledger_verify (below).
• Compression + CCR — compress_tool_result shrinks oversized JSON / logs cache-safe; ccr_retrieve recovers the original.
• Drift-guard — verify_symbol checks a symbol against provided sources at the grep tier (reports missing, never hard-blocks — grep cannot prove absence). verify_symbol_structural checks against memory's pre-extracted structural data instead, and can hard-block a proven-absent symbol when every source considered was parsed at the tree-sitter tier (a single regex-tier fallback in the set caps the verdict back to grep authority).
• Skill vetting — vet_skill scans skill text (threat-signature DB + homoglyph / hidden-char) before you install it; vet_skill_deep scans a whole skill directory the same way plus semgrep (offline, bundled ruleset) and osv-scanner (live network to osv.dev) when either is present on PATH — both shell-outs policy-gated like a Bash call, absence degrades to "skipped," never a hard failure.
• Memory — query_graph, memory_search, memory_write (+ optional evidence), memory_consolidate, reconcile, add_file. CLI-only: vault-export / vault-import (Obsidian bridge — a human-invoked act, never a model-invocable tool, by design).
• Orchestrate — ledger_add / ledger_update / ledger_status, ledger_verify (actually spawns the task's verify.command, policy-gated + sandboxed — this is what "done" being a measurement means in practice), worktree_create / worktree_list / worktree_remove, loop_check, spend_check.
• Web — web_fetch (any URL), web_docs (npm registry metadata/README) — both gated exactly like the native WebFetch tool, including your own policy/lease rules.
• Guard operator tooling (CLI-only — human-run, never MCP) — learn (propose allowlist entries from repeated approvals), ratify (one-shot proposal), asks (batch ask digest), verify-journal (check the audit chain for tampering), lease grant|list|revoke (time/call-boxed elevated allows — grant/revoke are CLI-only on purpose: a model that could grant its own elevated access would defeat the point of the floor being human-owned).

On Tier 2 (any MCP host) every item in both lists is reachable as the same MCP servers / CLIs; only the automatic hook application above is Claude-Code-specific.

Skills & agents

Nine skills (skills//SKILL.md, model-invoked by name/description match) and four subagents (agents/.md, dispatched by orchestrate's subagent-driven-development loop). Full detail lives in each file — this is the index a first-time reader needs to know they exist and when each one fires.

| Skill | Use when | Does | |---|---|---| | grill-with-docs | Start of any non-trivial task naming a library/framework/API | Interrogates the request for scope/constraints and grounds it against real, current docs (not training-data memory); produces CONTEXT.md for brainstorming to consume. | | brainstorming | Request is non-trivial or under-specified | HARD GATE — produces a design and requires explicit approval before any code is written. | | subagent-driven-development | Any non-trivial build | Controller loop: one fresh-context subagent per ledger task, review each result, loop fixes — keeps the controller's own context lean. | | tdd | Inside one implementer's work on a single piece of code | Red/green/refactor at the single-change grain — finer than the ledger's task-level verify.command. | | design-critique | Producing or editing anything with a visual/UX surface | Pre-emit self-critique — anti-slop gates, taste dials, design-token contract check — run before the work is shown. | | caveman | Output token volume matters more than prose polish | Terse, high-signal output — drops filler, keeps all technical substance and code verbatim. | | focus | User wants to act on the answer immediately | Answer-first, numbered, state-restated output shaping. Orthogonal to caveman (structure, not token count) — combine freely. | | session-observer | Continuously, during any non-trivial session | Captures corrections, repeated patterns, and judgment calls as episodic observations for later human-reviewed skill/policy improvement. Never edits policy itself. | | using-ideal-harness | Automatic — injected at SessionStart | Bootstrap skill: what's installed, when to route to which module. |

| Agent | Use when | Does | |---|---|---| | scout | "Where is X" / "what calls Y" / map an area | Read-only locator; returns a compact file:line table. Never edits, never suggests f

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bharat3645
• Source: bharat3645/The-Ideal-Harness
• License: MIT

Install and usage instructions live in the source repository linked above.