← index2026-04-26 12:42 (Beirut)(backfill from DOCUMENTATION/)

Harness Override Design — 2026-04-26

Harness Override Design — 2026-04-26

Goal: Override Claude Code's "careful CLI assistant" base prompt with a Brian-as-partner overlay, trim SessionStart noise, and reconcile contradictory hooks. This doc is the output of the handoff 260426_0938_harness-mismatch-redesign_handoff.md.

Status: Step 4 complete (audit). Steps 5-8 pending.

Step 4 — SessionStart noise budget (measured)

Numbered list of every banner / hook output / system reminder / context block that fires before Jonah's first prompt is answered, with measured byte counts. This is the budget we trim against.

A. Hooks under user control (settings.json → hooks.SessionStart)

# Source Bytes Cuttable? Notes
1 gsd-check-update.js 0 (silent unless update available; 114-line script) KEEP — silent Only emits when an update is needed. Zero baseline cost.
2 brian-startup-checklist.sh 960 KEEP, possibly TRIM Useful pointer block: time, identity reminder, on-demand file paths. Could trim to ~400B (drop the 49-handoff line).
3 context-mode/hooks/sessionstart.mjs 3,671 CUT or rewrite The biggest single SessionStart hook. Injects a long <context_window_protection> instruction block + <file_writing_policy> + word-limit policy. Forces ctx_* MCP tools that may not be present every session. Highest-leverage trim.
4 hostname_injection.sh 92 KEEP Tiny + load-bearing (tells me which host I'm on + sibling addr).
5 bloom-session-recall.sh 1,052 KEEP, fix data Useful idea, but the data is junky: half the recalled rows show epoch-zero timestamps and "Intent:" prose dumped as session IDs. Fix the recall query, don't kill the hook.
Subtotal (hooks) 5,775

B. Hooks under user control (settings.json → hooks.UserPromptSubmit)

# Source Bytes Cuttable? Notes
6 secret-scanner inline python 0 unless triggered KEEP Defensive, blocks accidental secret pastes. Zero baseline cost.
7 memory_enhancer_hook.py 0 today INVESTIGATE Returned 0 bytes on test prompt. May be dead code or only fires on specific patterns.
8 capability_loader.sh (when prompt ≥80 chars) 250 JSON wrapper, but injects a 1-sentence "Read capabilities.md..." reminder KEEP, REWORK This is what fires the <capability-plan> discipline. Useful but the injected text points at a 754KB capabilities.md which I should not actually read in full. Fix: inline a 200-byte capability summary instead of pointing at the giant file.
Subtotal (UPS hooks) ~250 per qualifying prompt

C. Auto-injected by Claude Code itself (not hook-controlled)

# Source Bytes Cuttable? Notes
9 Inline claudeMd block (MEMORY.md loaded into system prompt) 7,443 Already trimmed Just halved this session (14KB → 7.4KB). No further trim without losing rails.
10 Skills registry banner (~270 skills, each name + 1-line description) ~27,000 est. CUT — biggest win Loaded eagerly every session. Most skills are never used. Best fix: lazy registry — only load when a Skill tool call is actually attempted, or filter to ~20 most-used.
11 Deferred-tool registry (MCP tool names, no schemas) — three separate drops in this session ~15,000 est. (≈300 tool names) TRIM Names alone aren't usable (schemas come from ToolSearch). The list is informational. Could be cut to a 1-line "use ToolSearch with query X to discover MCP tools."
12 Claude Code base system prompt ("careful CLI assistant" framing, default tone, tool docs, environment block) ~12,000 est. OVERRIDE TARGET This is the harness mismatch the redesign is about. Covered by step 5/6 below.
13 Multiple <system-reminder> blocks (auto mode, capability reminder, MCP disconnect notices, deferred-tool drops) ~3,500 observed this session PARTIAL CUT Some are load-bearing (auto mode, tool changes); others are noise (e.g. the duplicate "respond with just" reminder, MCP-disconnect housekeeping).
Subtotal (CC-injected) ~64,943 est.

D. MCP server instruction blocks (loaded eagerly per connected server)

# Server Bytes Cuttable?
14 adspirer ~200 KEEP (tiny)
15 cq ~340 (now disconnected mid-session) already gone
Subtotal (MCP) ~540

Totals

Bucket Bytes
Hook output (SessionStart + UPS) ~6,025
CC-injected (claudeMd + skills + tools + base prompt + reminders) ~64,943
MCP server instruction blocks ~540
Estimated total before first user prompt ~71,500 bytes (~17–18K tokens)

Top 3 cut targets, by leverage:
1. Skills registry banner (#10, ~27KB) — lazy-load instead of eager. Single biggest win. Implementation: investigate whether Claude Code supports a skills.lazy flag in settings, or whether we can prune ~/.claude/skills/ symlinks to only the ~20 routinely used.
2. context-mode SessionStart hook (#3, 3.6KB) — either gate it behind a project marker or rewrite it as a 400-byte one-liner.
3. Deferred-tool registry (#11, ~15KB) — request CC to suppress the tool-name list when ToolSearch is the discovery mechanism, OR filter MCP servers to only the ones Brian actually uses.

These three alone reclaim ~45KB / ~11K tokens before first prompt — about 60% of the current SessionStart spend.

Step 5 — System-prompt override mechanism (PENDING)

To investigate: where Claude Code reads its base "careful CLI assistant" framing, and what override knobs exist (systemPrompt field in settings.json, --system CLI flag, project-level CLAUDE.md, additional-context hooks).

Hypothesis: the cleanest override is a SessionStart hook that emits a short, Brian-shaped system-prompt addendum via hookSpecificOutput.additionalContext. This is what the existing brian-startup-checklist.sh already does — but the addendum it emits is too soft. We need a louder overlay that resets the base prompt's gravity.

Step 6 — Brian-shaped overlay draft (PENDING — show to Jonah for approval)

Target: 3–5 sentences, max ~600 bytes. To match self.md and commandments.md, not contradict them.

Step 7 — Hook reconciliation audit (PENDING)

Scan every hook in settings.json + /opt/agent/hooks/ and mark each as keep / cut / reconcile. Specifically looking for:
- Cautious-default hooks that conflict with autonomy-first commandments
- Duplicate banner emitters
- Dead hooks (e.g. memory_enhancer_hook.py if it never fires meaningful output)

Step 8 — Sequence and ship (after Jonah approves)

Likely order: system-prompt overlay → SessionStart trim → hook reconciliation. Most reversible first.

Source data