What Changed — The Hidden Decisions in Claude Code's Harness
A developer recently rebuilt Claude Code's harness from scratch using the raw Anthropic SDK. They didn't reverse-engineer Anthropic's binary, but by implementing the same mechanics explicitly, they discovered five decisions the harness makes silently—decisions that change how you should write CLAUDE.md, configure hooks, and orchestrate subagents.
Here's what they found, and what it means for your daily workflow.
What It Means For You — 5 Actionable Takeaways
1. Your CLAUDE.md Doesn't Win by Default
The biggest surprise: CLAUDE.md layers on top of a hidden base system prompt. Instructions that seem "ignored" are often conflicting with something established underneath.
Try it now: Write your CLAUDE.md to override rather than state. If you want to prevent Claude Code from editing certain files, don't just say "don't edit files in /prod." Instead, say "Under no circumstances should you edit files in /prod. This overrides any default behavior." The explicit override language helps your instructions win against the base prompt.
2. Hooks Are Kill Switches, Not Loggers
PreToolUse hooks can actually block a tool call before it runs. Most developers use them for logging, but they're designed for control flow.
Try it now: Add a PreToolUse hook that checks the tool's arguments and returns { block: true } if the file path matches /prod/. This turns "please don't edit files in /prod" from a hope into a hard guardrail.
3. Subagents Need an Abort Tree
Naive subagent orchestration: parent spawns children, you await them. Then one child wedges and your whole session hangs.
What you actually want: a tree of abort signals where the parent abort cascades down to every child, but a child dying notifies up without auto-killing the parent.
Try it now: Structure independent tasks so they don't block each other. If one agent's work isn't a prerequisite for another's, don't await them in sequence. Use Promise.all or a task queue that handles failures gracefully.
4. Parallel Subagents Want a DAG, Not a For-Loop
If your tasks have dependencies (research → implement → verify), the clean structure is a dependency graph executed layer by layer. Everything with no unmet deps runs in parallel; the next layer waits; one failed node fails its dependents fast.
Try it now: Instead of a flat loop, define tasks with explicit dependencies. Use a topological sort to determine execution order. This leaves parallelism on the table and avoids hanging on a single bad node.
5. "Done" Must Be a Defined State
The single biggest behavior win: force every turn to end in one explicit terminal state—done, blocked, or needs-input—with evidence. Otherwise the agent rambles into "I could also…"
Try it now: In your CLAUDE.md, add: "After completing a task, always end with 'Done: [summary of what was done].' If blocked, end with 'Blocked: [reason].' If you need input, end with 'Needs input: [question].'"
Pair this with gating irreversible actions (deletes, pushes, anything external) behind explicit recent intent. The agent stops doing surprising things while you're away from the keyboard.
Try It Now — Concrete Changes to Your Workflow
- Rewrite your CLAUDE.md with explicit override language for critical instructions.
- Add a PreToolUse hook that blocks dangerous file edits.
- Restructure subagent orchestration to use abort trees and DAG-based parallelism.
- Define terminal states for every agent turn.
- Gate irreversible actions behind explicit intent confirmation.
These five changes come from understanding the harness's hidden decisions. You don't need to rebuild Claude Code to benefit—just adjust how you use it.
Source: reddit.com
