# The Ideal Harness

> Agent harness / control-plane around a stateless LLM: deterministic policy floor on PreToolUse/PostToolUse hooks, secret redaction, injection fencing, tool-result compression, code-graph memory, orchestration. Five plugin modules for Claude Code (Tier 1) or any MCP host (Tier 2). MIT.

- **Type:** MCP server
- **Install:** `agentstack add mcp-bharat3645-the-ideal-harness`
- **Verified:** Pending review
- **Seller:** [bharat3645](https://agentstack.voostack.com/s/bharat3645)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bharat3645](https://github.com/bharat3645)
- **Source:** https://github.com/bharat3645/The-Ideal-Harness

## Install

```sh
agentstack add mcp-bharat3645-the-ideal-harness
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:**

4. **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.
5. **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](https://github.com/bharat3645)
- **Source:** [bharat3645/The-Ideal-Harness](https://github.com/bharat3645/The-Ideal-Harness)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bharat3645-the-ideal-harness
- Seller: https://agentstack.voostack.com/s/bharat3645
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.