DEV Community: UB3DQY

I thought my AI memory hook was broken. It turned out to be Windows, WSL, uv, and one missing login

UB3DQY — Mon, 13 Apr 2026 23:29:37 +0000

Part of the series Debugging Claude Agent SDK pipelines. One of the layers I'll mention near the end — hidden account-level Gmail / Calendar MCP integrations blocking my subprocesses — deserved its own write-up: Hidden Gmail and Calendar integrations quietly broke my Claude SDK pipeline.

I noticed something weird in Codex.

UserPromptSubmit kept saying completed, but Stop kept saying failed.

If you're building a memory tool, that's a bad combination. It means the assistant can still read old context, but it may be failing to write new context back into long-term memory. In other words: it looks smart in the moment, but its memory may be quietly falling apart behind the scenes.

I assumed this would be a small hook bug.

It wasn't.

It turned into one of those debugging sessions where every layer was technically "working" and the system as a whole still wasn't.

What I was building

I'm working on a markdown-first memory system for Claude Code and Codex. The shape is simple enough:

when a session ends, a hook grabs the transcript
a background script decides whether the conversation is worth saving
if it is, it writes a distilled note into a daily log
later, that gets compiled into wiki pages and injected back into future sessions

The part that mattered here was the Codex Stop hook. That's the capture path. If that hook fails, new memory may never make it into the wiki.

So when I saw Stop failed in the UI over and over again, I treated it as a real product problem, not a cosmetic one.

The first bug was real

The first issue was exactly where I expected it to be: in the hook.

The parser only understood one transcript shape. Codex was emitting another one. The hook would fire, look at the transcript, fail to extract meaningful context, and then skip capture.

That part was straightforward to fix:

teach the parser the real Codex transcript shape
add a fallback for when transcript_path is missing
stop using the old turn-count gate and switch to a content-based threshold
raise the timeout so the hook had room to finish

After that, things got better. The logs stopped saying SKIP: empty context, and I started seeing the line I wanted:

Spawned flush.py for session ...

At that point I thought I was done.

I was not done.

The second bug was weirder

Now the hook was successfully spawning the downstream capture process, which should have been a win.

And then it still ended with:

BrokenPipeError: [Errno 32] Broken pipe

This was one of those bugs that is annoying precisely because it happens after the important part.

The capture process had already started. Memory might already be on its way to being saved. But the hook still looked failed in the Codex UI, which meant I couldn't trust the system yet.

The cause turned out to be simple in hindsight:

the hook took longer than the local timeout
Codex closed stdout
the hook tried to print its final success JSON into a pipe that no longer existed

So yes, the system was partly working. It just wasn't finishing cleanly.

That fix was also small: protect the final stdout write against a closed pipe.

At this point I had fixed the parser bug and the broken pipe. Surely now the memory pipeline would work.

Still no.

The third bug wasn't in the hook at all

Once I got past the broken pipe, the downstream process itself started failing.

The hook would spawn flush.py, and then flush.py would die with the deeply unhelpful classic:

Command failed with exit code 1

No useful stderr. No obvious explanation. Just enough information to waste an afternoon.

This is the moment where I finally stopped assuming I was debugging "the hook" and started treating the whole thing like what it really was: a chain of separate runtimes.

Because that's what it was.

Not one program. A chain:

Codex UI
hook runner
Python process
subprocess launcher
WSL boundary
bundled Claude CLI
local authentication state

Each link could fail for a different reason.

And that is exactly what had happened.

One of the real bugs was hiding in the boundary

At that stage, the most immediate root cause of the exit code 1 failure wasn't inside my Python code at all.

The Claude CLI inside the WSL runtime wasn't authenticated.

That was the immediate bug in this part of the investigation. There was still another layer around hidden account-level MCP integrations, but that turned into its own separate story. I wrote that one up separately here: Hidden Gmail and Calendar integrations quietly broke my Claude SDK pipeline.

I had already authenticated Claude on the Windows side. Claude Code on Windows was fine. But Codex hooks were spawning work inside WSL, and that runtime had its own separate ~/.claude state.

So from one side of the system, Claude was logged in.

From the other side, it wasn't.

And because the failure was happening in a subprocess several layers down, what bubbled back up was just a generic process failure.

That was the moment the whole debugging session clicked for me:

I wasn't dealing with a broken feature. I was dealing with a system that crossed OS boundaries, process boundaries, and auth boundaries, and I was still mentally treating it like one runtime.

It wasn't one runtime.

It was several. They just happened to be glued together tightly enough to look like one.

And then Windows joined in

While I was cleaning that up, Claude Code on Windows started throwing a completely different kind of error on every hook run:

error: failed to remove file `.venv\\lib64`: Access is denied. (os error 5)

That turned out to be another boundary problem.

I had Windows-side and WSL-side tooling both touching the same project environment. uv was trying to be helpful. Windows was trying to be Windows. A POSIX-style lib64 symlink was involved. None of this was improving my mood.

So now I had two parallel truths:

the Codex capture path was broken because WSL auth was missing
the Claude-side hook launcher was unstable because the shared .venv state was getting churned across environments

Both bugs were real.
Neither bug lived in the same place.
Both looked, from the outside, like "the AI tool is flaky again."

The part that actually mattered

Here's the practical lesson I walked away with:

When a system crosses runtime boundaries, the bug is often not in the place where the symptom shows up.

The symptom showed up as:

Stop failed

The actual causes were spread across multiple layers:

transcript shape mismatch
timeout mismatch
unprotected stdout write
missing WSL-side Claude auth
shared Windows/WSL environment churn

If I had kept looking only at the final error message, I would have kept "fixing" the wrong layer.

What I changed

I didn't rewrite the system. I just stopped letting it be vague.

I added enough visibility so each boundary could tell me when it was the one failing:

transcript parsing now understands real Codex output
the stop hook has a fallback when transcript data is missing
success output no longer crashes on a closed pipe
the flush path logs more useful process diagnostics
I verified the actual runtime where the subprocess was running, instead of assuming it matched the one I was sitting in

And maybe the most boring but important fix of all:

I authenticated Claude in the runtime that was actually doing the work

Not "somewhere on the machine."
Not "the CLI works for me."
The exact runtime.

The lesson I'll keep

The real lesson wasn't "add more logging."

It was this:

if your tool crosses process boundaries, OS boundaries, and auth boundaries, you do not have one runtime anymore.

You have a chain of semi-independent runtimes, and each one can fail in its own extremely specific way.

That sounds obvious when written down. It was much less obvious when I was staring at one repeated Stop failed message and assuming there had to be one neat root cause behind it.

There wasn't.

There were several small, ordinary failures, all stacked on top of each other. That's what made the bug feel slippery.

And honestly, that is what a lot of debugging looks like in real life. Not one dramatic mistake. Just three or four boring mismatches, each living at a different seam, and all of them combining into one system that feels unreliable.

Sometimes the hardest part is realizing that one ugly symptom actually belongs to more than one story.

If you're building something similar

Don't just test whether the hook runs.

Test whether:

it runs in the runtime you think it runs in
it has the credentials you think it has
it can finish within the timeout you actually configured
and the final side effect really happens

Because "the script executed" is not the same thing as "the system worked."

And if your tool is supposed to remember things for you, that difference matters a lot.

I'm building this as part of llm-wiki, a markdown-first memory layer for Claude Code and Codex. The part I underestimated wasn't the prompt design or the summarization logic. It was the plumbing around the boundaries.

Which, in hindsight, is exactly where these systems like to break.

Hidden Gmail and Calendar integrations quietly broke my Claude SDK pipeline

UB3DQY — Mon, 13 Apr 2026 16:49:42 +0000

I lost a few hours to one of those bugs that feels fake when you first describe it out loud.

My Claude Agent SDK pipeline kept failing with the most generic error possible:

Command failed with exit code 1

No useful stderr. No clear traceback. No obvious repro beyond "real sessions fail, synthetic tests sometimes pass."

At first I thought it was just another boring auth problem. Then I thought it was a subprocess visibility problem. Then I thought it was WSL. All of those were plausible. None of them were the whole story.

The actual cause was stranger:

after claude auth login, my account quietly picked up account-level Gmail and Google Calendar MCP integrations that I had never explicitly enabled, could not see in the Claude web UI, and could not remove from the CLI. Those integrations wanted an interactive Google OAuth flow, and that was enough to break every non-interactive Claude SDK subprocess I was using for automation.

The workaround was one CLI flag:

extra_args={"strict-mcp-config": None}

That was the end of the bug.

Finding it was the hard part.

Where this showed up

I use Claude Agent SDK inside a small memory pipeline.

The shape is straightforward:

a hook fires at the end of a Codex session
the hook spawns flush.py
flush.py calls Claude Agent SDK
the result gets written into a daily markdown log

This is exactly the kind of automation that should be boring once it's set up.

Instead, real Codex sessions started failing. The hook would fire, the downstream script would start, and then the Agent SDK step would die with:

Fatal error in message reader: Command failed with exit code 1

That was enough to break the memory pipeline completely. No flush, no daily log entry, no durable memory from those sessions.

And because the error was happening in a subprocess layer, the surface signal was awful. It just looked like "the SDK sometimes fails."

Why this was so annoying to debug

There were at least three reasons this bug wasted my time.

1. The first fix appeared to work

At one point I thought I had solved it just by running:

claude auth login

And for a moment, it looked like I had.

Synthetic tests passed. The bundled Claude binary responded. The pipeline looked alive again.

That "fix" turned out to be fake.

It worked briefly because the environment had not yet fully populated the auth-related cache state that was about to cause the real failure.

So I got the worst possible debugging gift: a temporary false victory.

2. The important error wasn't where I was looking

I had already added stderr visibility around the SDK call, expecting to catch the real CLI failure there.

That didn't help much, because the Google MCP auth path wasn't producing a nice actionable stderr message.

The auth prompt was effectively happening on the wrong channel for my diagnostic setup. The SDK stderr callback got nothing useful. ProcessError.stderr was empty. All I had was the outer shell of the failure.

From the outside, it still looked like "exit code 1, good luck."

3. The integrations were invisible

This was the part that really crossed from "normal debugging" into "what exactly is this system doing?"

In Claude.ai web settings, I could see the usual visible things. But I could not see any Gmail or Google Calendar integrations anywhere I would expect:

not in Settings → Connectors
not in Settings → Customize → Skills
not in Customize → Connectors

And yet on disk, after claude auth login, I could see this:

{
  "claude.ai Gmail": {"timestamp": 1776092446619},
  "claude.ai Google Calendar": {"timestamp": 1776092446683}
}

That came from:

~/.claude/mcp-needs-auth-cache.json

And the CLI confirmed the same story:

claude.ai Gmail:           https://gmail.mcp.claude.com/mcp - ! Needs authentication
claude.ai Google Calendar: https://gcal.mcp.claude.com/mcp - ! Needs authentication

At that point the bug finally started making sense.

What was actually happening

Here is the version I wish someone had handed me before I started digging:

When you authenticate Claude via OAuth, your account may receive account-level MCP integrations as part of its backend claims.

In my case, that included:

claude.ai Gmail
claude.ai Google Calendar

Those integrations were not local project config.
They were not something I had added manually in the repo.
And they were not removable with normal local MCP commands.

For example:

claude mcp remove "claude.ai Gmail"

returned:

No MCP server found with name: "claude.ai Gmail"

Which makes sense once you realize the CLI isn't managing them as local entries. They are attached at the account/backend layer.

Then the next failure follows naturally:

bundled Claude CLI starts inside a non-interactive SDK subprocess
it checks account-level MCP claims
it sees Gmail and Calendar need additional Google auth
it tries to initiate an interactive OAuth flow
there is no TTY / browser / normal user interaction path
subprocess stalls or exits with code 1

That was the whole bug.

Not my prompt.
Not my retry logic.
Not the summary logic.
Not even the main auth state in the obvious sense.

Just hidden MCP integrations pulling a subprocess into an auth flow it had no way to complete.

Why this matters beyond my repo

This is not really about my particular memory pipeline.

It matters because subprocess-based Claude SDK automation is a completely normal pattern. People use it for:

capture pipelines
background summarizers
hook-triggered analysis
scheduled jobs
internal tools

All of those run in contexts where interactive browser auth is either awkward or impossible.

If account-level integrations that require fresh OAuth can quietly attach themselves after login, and if they are invisible in the UI, then the failure mode becomes:

everything looks fine in your normal interactive CLI
your automation suddenly fails in the background
the error surface is generic
and the root cause is not where you would reasonably look first

That is a nasty class of bug.

The workaround that fixed it

The workaround was to isolate the subprocess from account-level MCP discovery.

In practice, that meant passing:

ClaudeAgentOptions(
    allowed_tools=[],
    max_turns=2,
    extra_args={"strict-mcp-config": None},
)

That translates to the bundled Claude binary getting:

--strict-mcp-config

And once I did that, the subprocess stopped trying to discover or auth those account-level MCP integrations.

The pipeline started running cleanly again.

That was the actual fix.

Deleting the cache file:

rm ~/.claude/mcp-needs-auth-cache.json

did not really fix anything. It just bought a little time until the state was regenerated.

The part I still don't love

The workaround is fine. I'm happy to use it in automation.

What I don't love is the product behavior that made it necessary.

From a developer point of view, a few things feel wrong here.

Hidden integrations are a bad default

If my account has Gmail and Calendar MCP integrations attached, I should be able to see them in the UI and turn them off.

Right now, from the outside, it feels like they exist in a shadow layer of account state that can affect automation without being visible where a user would normally manage integrations.

Opt-out without visible opt-in is rough

I didn't explicitly wire Gmail or Calendar into this project. Yet they still ended up influencing subprocess behavior after OAuth login.

That is a surprising default for anyone using Claude as a programmable toolchain component instead of just a chat app.

Non-interactive contexts should fail more gracefully

If the process is clearly non-interactive, the CLI should not wander into a user-hostile auth path and then collapse into a generic exit code.

At minimum, I would want:

a clear message saying an MCP integration requires interactive authentication
the name of the integration
and ideally a way to skip it automatically in SDK subprocess mode

What I wish the docs said

The one warning I really needed was something like this:

If you use Claude Agent SDK in non-interactive subprocesses, account-level MCP integrations attached through OAuth may trigger additional authentication flows. If those integrations are not fully authenticated, subprocess calls may fail. Use strict MCP config isolation for automation workloads.

That single paragraph would have saved me hours.

The short version

If you hit a mysterious Claude Agent SDK subprocess failure with a generic exit code 1, and your interactive CLI mostly works, check whether hidden account-level MCP integrations are involved before you start rewriting your own code.

In my case, the real sequence was:

I thought the pipeline was unauthenticated
then I thought stderr visibility was missing
then I thought WSL was the root cause
and the real issue turned out to be hidden Gmail and Calendar MCP integrations trying to force Google OAuth inside a non-interactive subprocess

The fix was not glamorous:

extra_args={"strict-mcp-config": None}

But at least now I know what class of failure I was dealing with.

And honestly, that's often the hardest part.

I'm building this as part of a markdown-first memory system for Claude Code and Codex. I keep expecting the hard parts to be prompt design or summarization quality. More often than not, the real work is figuring out which invisible layer is making the obvious layer look broken.

How I shipped a broken capture pipeline and didn't notice for 3 days

UB3DQY — Sun, 12 Apr 2026 23:00:36 +0000

TL;DR

I built a hook-based capture system for Claude Code. Every session-end was supposed to get summarized and written into a daily log. My doctor.py gate said 13/13 PASS. Lint was clean. CI was green on every commit.

Then a user asked a simple question: "Is the wiki actually capturing this conversation?"

I checked the log. 57% of my recent sessions had been silently dropped for three days. The gate never told me. Every smoke test was passing. The system was broken in the one place no test was actually looking.

This is what happened, how I caught it, and what I changed so I would not miss the same kind of bug again.

The setup

The project is a memory system for Claude Code and Codex CLI. A session-end hook reads the transcript, hands it off to a background Python script, that script asks the Agent SDK whether the conversation is worth saving, and the result gets appended to daily/YYYY-MM-DD.md. Fairly normal hook plumbing.

I had a doctor.py script with 13 smoke checks across the pipeline. session-start.py produced valid JSON. user-prompt-wiki.py could look up articles. stop.py exited cleanly. I had structural lint. I had a green CI gate on every push.

I had shipped eight commits over two days, each with doctor --quick green, each with CI passing. I was telling myself the system was in good shape.

The moment of doubt

Someone I was working with asked a very simple question: "Just to confirm, is the wiki actually storing this conversation?"

I almost said yes immediately. The hooks were wired. Every prompt I sent was coming back with wiki snippets injected at the top. UserPromptSubmit was clearly doing its job. From the outside, the system looked alive.

But I have been burned by "it looks alive" enough times that I checked instead of trusting the feeling. I opened scripts/flush.log, the file where the session-end and pre-compact hooks write their operational log, and scrolled to the recent entries:

2026-04-12 16:36:39 INFO [session-end] SessionEnd fired: session=...
2026-04-12 16:36:39 INFO [session-end] SKIP: only 2 turns (min 4)
2026-04-12 16:39:27 INFO [session-end] SessionEnd fired: session=...
2026-04-12 16:39:27 INFO [session-end] SKIP: only 2 turns (min 4)
2026-04-12 16:42:07 INFO [session-end] SessionEnd fired: session=...
2026-04-12 16:42:07 INFO [session-end] SKIP: only 2 turns (min 4)

That was the moment my confidence disappeared.

What I was looking at

The hooks were firing. SessionEnd fired is printed before any filtering happens, so those lines meant the hook chain from Claude Code to my Python script was intact. The wiring was not the problem.

But then immediately after, on every single recent entry: SKIP: only 2 turns (min 4).

My session-end code had this:

MIN_TURNS_TO_FLUSH = 4

# ... later ...

if turn_count < MIN_TURNS_TO_FLUSH:
    logging.info("SKIP: only %d turns (min %d)", turn_count, MIN_TURNS_TO_FLUSH)
    return

This was supposed to protect against flushing trivial sessions, the "one question, one answer, exit" pattern that is probably not worth archiving. The threshold 4 felt reasonable when I wrote it. It felt reasonable when I reviewed it. It passed every test.

What I had not really internalized was the shape of my own usage. A typical Claude Code session for me is: open terminal, ask one specific question, get one specific answer, close terminal. That is exactly 2 turns. The rule I wrote to skip "trivial" sessions was skipping my normal session shape.

I ran the numbers over the full log:

SessionEnd fired:       109
Spawned flush.py:        52  (48%)
Skipped (various):       57  (52%)
Most recent skip reason: "SKIP: only 2 turns (min 4)"

Over half the sessions from the last three days had been silently dropped. Not edge cases. Not weird corner traffic. Just normal usage. The daily log for those days had looked thinner than it should have been, and I had noticed that in the background, but never chased it because doctor --quick was green and I trusted it.

Why the gate didn't catch it

The actual bug was trivial. Change a number. That part took no time. The question that mattered was: why did my gate tell me everything was fine while half the data was disappearing?

Let me walk through what doctor --full actually tested:

check_session_start_smoke — runs session-start.py with an empty JSON input, verifies it prints a valid hook-output JSON. ✅
check_user_prompt_smoke — runs user-prompt-wiki.py, verifies it returns additionalContext with articles. ✅
check_stop_smoke — runs stop.py, verifies it exits cleanly on empty stdin. ✅
check_index_freshness, check_structural_lint, check_env_settings, check_path_normalization — the rest of the usual health-check surface.

Notice what those tests are really asking. Each one asks: "Does this script run without crashing?" That is a useful question. It catches real bugs: ImportError after a refactor, JSONDecodeError from bad stdin, FileNotFoundError after a rename. But it is not the question I actually cared about: "Does a real transcript, processed by this chain, end up in the daily log?"

That question has three subtly different parts:

Does the hook fire when Claude Code ends a session? (Yes — I could see it in the log.)
Does the hook's filter logic produce a "worth-saving" verdict for realistic input? (Turns out: no, because of the bug above.)
Does the downstream chain actually write the result to the daily log? (Unknown, because step 2 always said no.)

doctor --full tested a weak version of (1) by running the script with an empty payload. It did not test (2), because that needs a realistic transcript. It did not test (3), because the chain never got that far. Every link passed in isolation, and the chain as a whole was still broken.

This is the old difference between smoke tests and end-to-end tests. In theory everybody knows it. In a personal tool, it is easy to get lazy about it. You know what the chain is supposed to do, so testing the whole thing can feel redundant. It is not redundant at all. The chain breaks in exactly the places where each individual component still passes its own tiny check.

Two things I added to stop this happening again

The code fix itself was boring: replace the turn-based threshold with a content-based one. Short but substantial sessions, two turns and a couple thousand characters of real discussion, now get captured. Tiny sessions, two turns and thirty characters of "ok thanks", still get skipped, but by character count instead of turn count. That is not really the point of the post.

The interesting part is what I added to doctor.py afterward, because that is what turns this from a one-off fix into something the project can actually defend itself with.

1. Observability check: `check_flush_capture_health`

This one reads scripts/flush.log over a rolling 7-day window and summarizes what the capture pipeline has actually been doing:

def check_flush_capture_health() -> CheckResult:
    # parse flush.log, count SessionEnd fired vs Spawned flush.py
    ...
    detail = f"Last 7d: {spawned}/{session_fired} flushes spawned (skip rate {skip_rate:.0%})"

    if spawned == 0:
        return CheckResult(
            "flush_capture_health", False,
            f"{detail}. Pipeline appears broken: SessionEnds fired but nothing was spawned."
        )
    if skip_rate > 0.5:
        return CheckResult(
            "flush_capture_health", True,
            f"{detail} [attention: high skip rate — consider lowering WIKI_MIN_FLUSH_CHARS]"
        )
    return CheckResult("flush_capture_health", True, detail)

Important design choice: this check only FAILs when the pipeline is observably broken. If SessionEnds fired but nothing was spawned, that is a correctness bug. It does not FAIL on high skip rate, because skip rate is historical data about past usage, not necessarily a problem with the current code. A fresh clone has no history and should pass. A repo with lots of short sessions may have a high skip rate and still be behaving correctly. Blocking the merge gate on historical observability would be a mistake.

The check prints an [attention] marker in the detail line when the skip rate goes above 50%. On the first run in my own repo after I added it, it printed:

[PASS] flush_capture_health: Last 7d: 50/121 flushes spawned (skip rate 59%)
       [attention: high skip rate — consider lowering WIKI_MIN_FLUSH_CHARS]

That one line would have saved me three days.

2. End-to-end acceptance test: `check_flush_roundtrip`

This is the answer to the "why didn't any test catch this?" question. It only runs in doctor --full, because it is more expensive than the fast smoke checks.

The test writes a dummy 6-turn transcript, about 2000 characters of realistic content, to a temp file. Then it invokes hooks/session-end.py as a real subprocess with a realistic hook-input JSON on stdin:

test_session_id = f"doctor-roundtrip-{uuid.uuid4().hex[:8]}"
transcript_path = SCRIPTS_DIR / f"doctor-transcript-{test_session_id}.jsonl"

# ... write dummy turns ...

hook_input = {
    "session_id": test_session_id,
    "source": "doctor-roundtrip",
    "transcript_path": str(transcript_path),
    "cwd": str(ROOT_DIR),
}

env = os.environ.copy()
env["WIKI_FLUSH_TEST_MODE"] = "1"

proc = subprocess.run(
    [sys.executable, str(session_end_script)],
    input=json.dumps(hook_input),
    ...
)

Notice the WIKI_FLUSH_TEST_MODE=1 environment variable. That is the trick. The downstream script, flush.py, checks it at startup and, if it is set, skips the real Agent SDK call and writes a marker file to a known location instead:

# In flush.py
if os.environ.get("WIKI_FLUSH_TEST_MODE") == "1":
    TEST_MARKER_FILE.write_text(
        f"FLUSH_TEST_OK session={session_id} ts=...",
        encoding="utf-8",
    )
    return

The test then polls for that marker file with a 15-second timeout, verifies it contains the right session ID, and cleans up. If any link in the chain is broken — if session-end.py does not spawn flush.py, if flush.py fails to import, if the environment is not inherited correctly — the marker never appears and the test fails with a clear message.

This is an actual end-to-end test, not a smoke test. It exercises the real subprocess invocation, real environment inheritance, real stdin/stdout piping, and real timing. The only thing it fakes is the API call itself, because that would cost money and pollute the real daily log.

On my machine right now:

[PASS] flush_roundtrip: session-end -> flush.py chain completed in test mode

If I had had this test two weeks earlier, I would have caught the MIN_TURNS = 4 bug on the first realistic transcript. It would not have needed to be clever. A visible skip where a spawn was expected would have been enough.

The lessons, short enough to remember

1. Smoke tests are not end-to-end tests, and they do not substitute for one. I had nine smoke checks in doctor.py, and all of them were correct in isolation. None of them ran the actual production chain from a realistic input to a verifiable output. If you have a multi-process pipeline, you need at least one test that exercises the whole thing. It does not have to be fast and it does not have to run on every commit. It just has to exist somewhere meaningful in your gate.

2. Observability is a design choice, not an afterthought. My hooks were writing perfectly good operational logs. I just was not reading them, and my gate was not reading them either. Adding a check that summarizes those logs took about forty lines of code and would have turned a silent three-day outage into a visible [attention] marker from day one. Logs you do not read are not much better than logs you never wrote.

3. If a test could have caught the bug, it belongs in the gate — even if adding it feels obvious in hindsight. The wrong question is "why didn't I add this on day one?" The better question is "what class of future bugs does this protect me from now?" Hindsight is always perfect about the bug you already know. What you want is general immunity to the class of bugs you just learned about.

If you are building similar hook-based systems, the code for the project where this happened is at github.com/ub3dqy/llm-wiki. It is a markdown-first memory system for Claude Code and Codex CLI, and both fixes described here — the content-based threshold and the roundtrip test — live in scripts/doctor.py and hooks/session-end.py. No API keys, no vector database, and it boots with uv run python scripts/setup.py.