Spec injection: provider-based history access instead of self-maintained state

[taosu0216]

Spec injection needs one fact at every tool event: has this spec fallen out of the model's context? #468 answers it by keeping our own state and inferring staleness from transcript line count or wall clock. Both inputs are wrong on the only platform it currently ships to.

This thread is for settling the cross-platform shape so #468 can stay scoped to the Claude Code implementation.

Scope: Claude Code, Codex, Pi, OpenCode, Cursor. Everything below was checked against current official docs and official source on 2026-07-25, with links; anything not documented is labelled as such.

Revised. An earlier version of this post proposed reading the platform transcript and scanning for Claude Code's compact_boundary record. That was wrong and is retracted — see Why not read the transcript. The event-driven design below replaces it.

---

What's broken today

Three failure modes, reproduced against the #468 branch with real python3:

The /compact branch never fires. The code reads a negative transcript-line delta as "compaction happened". Claude Code transcripts are append-only. Scanned 2,917 real transcripts under ~/.claude/projects: 51 contain a compaction boundary, none ever shrank. After a compact the spec body is gone from context, the line count is still climbing, so the hook stays silent — precisely when a refresh is due.

Line count is not turn count. A real session here: 1,112 transcript lines, 9 real user turns — ~124 lines/turn, the rest being assistant messages, tool results, attachments, snapshots. refresh_window_lines: 300, documented as "about 30 turns", is in practice ≈2.4 turns. The ratio isn't stable either: tool-heavy turns run 100+ lines, conversational turns a handful.

Subagents measure the parent's clock. Mid-session hooks receive the parent's transcript_path. While a subagent works the parent is idle, so the count barely moves — a subagent can run 100+ turns and never leave the window. Subagents are the long-horizon case this feature exists for.

One root cause: we're estimating a quantity the platform reports directly.

---

Why not read the transcript

The obvious fix is to read the conversation and look. Two of the three file-based platforms explicitly rule that out.

Claude Code — Manage sessions:

The entry format is internal to Claude Code and changes between versions, so scripts that parse these files directly can break on any release. To build on session data, use /export or the script interfaces instead.

Claude Code — Hooks, on transcript_path:

The transcript file is written asynchronously and may lag the in-memory conversation, so it may not yet include the current turn's most recent messages when a hook fires.

Codex — Hooks:

transcript_path points to a chat transcript for convenience, but the transcript format isn't a stable interface for hooks and may change over time.

Cursor documents transcript_path and CURSOR_TRANSCRIPT_PATH but never documents the format or the on-disk location — neither promising stability nor disclaiming it.

And compact_boundary, the record my earlier draft keyed on, appears nowhere in Claude Code's docs. It's an observed internal detail of a format the vendor says will change.

So: the path is contractual, parsing what's inside it is not.

---

What every platform does document: compaction events

Platform	Compaction hook	Can it inject?	Post-compaction re-entry
Claude Code	PreCompact (reason: manual/auto), PostCompact	PreCompact yes; PostCompact no — "No JSON output fields are processed"	SessionStart with source: "compact"
Codex	PreCompact, PostCompact (trigger: manual/auto)	Neither — "Plain text on stdout is ignored"	SessionStart with source: "compact"
Cursor	preCompact	No — "observational hook that cannot block or modify"	none
Pi	CompactionEntry in the session; ctx.compact() to trigger	via custom_message entries	n/a (in-process)
OpenCode	experimental.session.compacting, experimental.compaction.autocontinue	injects into the compaction prompt itself	n/a (in-process)

All five fire something at compaction time. That's the load-bearing fact.

Note the asymmetry that shapes the design: on Cursor there is no post-compaction event at all, and on Codex neither compaction hook can inject. So a design that depends on re-injecting at compaction time only works on two of five.

A design that depends on knowing compaction happened works on all five.

---

Proposal: event-driven state, not inferred state

Keep the state file — it's the correct substrate, and #468 already has it. Change what goes into it.

compaction hook fires      → record "context reset at T"
injection event fires      → decide, then record "injected spec S at T"

decision for spec S:
  no record                        → FULL
  record predates last reset       → FULL      ← the compaction case, now exact
  within refresh window            → SILENT
  otherwise                        → TICKET

Nothing is inferred. "Was it compacted away" stops being a heuristic and becomes a recorded fact, on documented surface, on every platform in scope.

This is a smaller change than it looks: #468's state file, decision function, budget and envelope layers all survive. What's deleted is the line-delta heuristic and the line/wallclock windows.

Provider contract

Adding a platform must not mean writing another injector. Only history access varies, so the contract stays narrow — a provider knows nothing about specs, budgets, or envelopes:

class HistoryProvider:
    def last_reset(self) -> Clock | None:   # from recorded compaction events
    def now(self) -> Clock:                 # tokens where available, else wall clock
    def budget(self) -> Budget:             # per-platform ceiling — see below

Everything above it — spec matching (already shared in common/spec_match.py), the decision, truncation, envelope rendering — is written once.

The three file-based platforms share one implementation plus a small dialect (which event names, which payload fields). Pi and OpenCode are genuinely different — in-process, no subprocess, messages already in hand — and writing those separately is right. They should still not re-implement the decision: gather the inputs in TS/JS, hand them to the shared Python core as JSON, get a verdict back. Both extensions already spawn Python helpers today.

---

Resolved by the docs

Three of the original open questions have answers now.

Injection ceilings are per-platform, and the units differ

Platform	Ceiling	Unit	Overflow behavior
Claude Code	10,000	characters	"saved to a file and replaced with a preview and file path"
Codex	~2,500	tokens, per entry	saved under <temp_dir>/hook_outputs/<session_id>/<uuid>.txt, model gets head-and-tail preview
Cursor	—	—	not documented
Pi	—	—	not documented (in-process)
OpenCode	—	—	not documented (in-process)

Consequences for #468's fixed 8,192-byte constant: it's too small for Claude Code, and the wrong unit for Codex. CJK is hit hardest — 2,500 tokens is roughly 1,200–2,500 Chinese characters, against Claude Code's 10,000 characters, so the same spec fits very differently on the two.

Budget must be a provider property. Cursor's needs measuring, and until then a conservative default.

Concurrency: one platform has a real fix, the rest need a lock

Claude Code has PostToolBatch:

The PostToolBatch event fires once per batch of parallel tool calls, after all calls in the batch have completed… This is distinct from PostToolUse, which fires for each individual tool call.

It fires "before the next model call" — exactly the window where injection matters — with no matcher filtering. That removes duplicate injection under parallel tool use at the root.

Codex and Cursor have no batch event and no documented parallel-tool hook semantics. OpenCode's tool.execute.after fires per call and interleaves; pairing must key on callID (source: packages/opencode/src/session/tools.ts:103-131). Pi documents the same caveat for tool_call:

In parallel tool execution mode it is still not guaranteed to include sibling tool results from the same assistant message.

So PostToolBatch is an optimization where available, and a lock around the state read/write is the portable answer.

Context-usage signals are uneven — so don't build the threshold on them

Platform	"How full is context?"
Pi	ctx.getContextUsage() → {tokens, contextWindow, percent} — a documented first-class API. Returns tokens: null right after compaction, before the next LLM response.
Cursor	preCompact payload carries context_usage_percent (0–100), context_tokens, context_window_size, message_count, messages_to_compact, is_first_compaction — but only at compaction time
Codex	TokenCount events with total_token_usage / model_context_window are persisted in the rollout (codex-rs/rollout/src/policy.rs) — but that's the transcript we're told not to parse
Claude Code	per-assistant usage in the transcript — same caveat
OpenCode	no equivalent API; would have to accumulate from assistant tokens

Two of five expose it on documented, non-transcript surface. So the portable threshold can't be token distance. The portable signal is binary and available everywhere: did a reset happen since the last injection. Token-based distance is an enhancement on Pi and Cursor, not the base mechanism.

---

Stability grading — why the state file stays

Surface	Grade
Hook payload fields (all five)	Contract — documented field tables; Codex additionally publishes generated JSON Schemas
OpenCode GET /session/:id/message	Contract — documented, SDK-generated
Pi sessionManager / getContextUsage()	Documented, no stability promise — see caveats below
Codex rollout JSONL, Claude Code transcript JSONL	Explicitly not a contract (quoted above)
Cursor transcript format & location	Undocumented
OpenCode experimental.* hooks	Prefix has no official definition — no stability statement either way

The state file isn't a portability floor any more (all five are covered). It's the landing zone for when one of the lower rows changes under us: a provider failure should degrade accuracy, never the feature.

Caveats found in the source that the docs don't mention

• Pi: documented ≠ callable. Extensions receive a ReadonlySessionManager, a hardcoded Pick<> whitelist (packages/coding-agent/src/core/session-manager.ts:190-206). buildSessionContext() is listed in the session-format docs but is not in the whitelist. Probe for methods at runtime rather than trusting the doc list.
• Pi: two CompactionEntry shapes coexist. The docs describe a retainedTail field that exists in the newer packages/agent harness but not in coding-agent's type — so on-disk sessions may carry fields the type doesn't declare.
• Pi: custom vs custom_message. Only custom_message enters LLM context; custom is extension state and is explicitly ignored by context building. Injections must use the former.
• OpenCode: the docs' "Events" list is not the hooks contract. The real interface is Hooks in packages/plugin/src/index.ts:222-335; several hooks (including experimental.chat.messages.transform) have zero documentation coverage.
• OpenCode: experimental.chat.messages.transform receives {} — no sessionID. It hands you the messages but not which session they belong to.
• OpenCode: docs describe file storage; the implementation is SQLite. packages/core/src/session/sql.ts (Drizzle), CLI opencode db, earliest migration dated 2026-01-27, while the troubleshooting page still documents a storage/ file layout. Live doc drift — another reason not to read anyone's session store directly.
• Claude Code: injected text is replayed on resume, not regenerated. Per the hooks docs, --continue/--resume replays saved hook output rather than re-running the hook, "so values like timestamps or commit SHAs become stale". Injected blocks should be time-invariant; anything time-sensitive belongs in SessionStart, which does re-run.
• Claude Code: subagent transcripts are documented at projects/<project>/<session>/subagents/ (in the .claude directory reference), and SubagentStop's transcript_path points at the subagent's own file. Cursor has the parallel agent_transcript_path. Mid-session events still hand you the parent's.

---

What this changes in #468

Currently	Under this design
Negative line delta as a compaction proxy	Compaction hook recorded as a first-class event
refresh_window_lines / refresh_window_seconds	Reset-since-last-injection (portable) + token distance where available
Subagent inherits the parent's clock	Subagent identity already available via agent_id; its own reset events are its own
Fixed 8,192-byte budget	Provider property, in the platform's own unit
Per-pid state shards	Single file per session. (Measured: 12 processes each appending 38 KB via O_APPEND to one file → 2,400 lines, zero corruption. Sharding addresses a race that doesn't occur, and not the read-before-write race that does.)
PostToolUse per tool call	PostToolBatch on Claude Code; lock elsewhere

The state file, identity resolution, decision function, budget layer and envelope rendering all stay.

Still open

1. Marker stability. The injected block needs a machine-readable marker that survives copy edits to the human-readable wording — it becomes a compatibility surface the moment history matters.
2. Where the provider layer lives. Flat modules beside common/spec_match.py, or a package?
3. Is the budget problem actually a content problem? We're pushing human-oriented prose through a small channel — 11 of the 13 specs given paths: in feat(hooks): path-scoped on-demand spec injection #468 exceed the per-spec cap, so FULL is often the first ~5% (one governed spec is 162 KB, truncated mid-table, followed by a note telling the model to go read the 162 KB file). If specs carried an explicit rules section, FULL would be small by construction and the FULL/TICKET distinction might not be needed at all. Bigger change — it touches spec authoring conventions.

---

Sources and verification

Official docs — Claude Code hooks · sessions · .claude directory · Codex hooks · Cursor hooks · Pi extensions · Pi session format · OpenCode plugins · OpenCode server API

Source — openai/codex codex-rs/protocol/src/protocol.rs, codex-rs/rollout/src/policy.rs, codex-rs/hooks/src/output_spill.rs · earendil-works/pi packages/coding-agent/src/core/session-manager.ts, .../extensions/types.ts · sst/opencode packages/plugin/src/index.ts, packages/opencode/src/session/tools.ts, packages/core/src/session/sql.ts (checked at pi a3ee1d28, opencode db88c423 / v1.18.4, 2026-07-25)

Reproduced locally on 2026-07-25 — transcript scan (2,917 files), line-to-turn ratio, O_APPEND concurrency, spec sizes, duplicate-injection race. Probe scripts available on request.

🤖 Researched and verified with Claude Code.

[taosu0216]

Match ordering: the most specific spec currently loses to the broadest one

Adding this because it's a live bug rather than a design preference, and it's the glob model's version of a problem the directory-based mechanisms have in a different form.

The contrast worth naming

Claude Code and OpenCode both resolve nested CLAUDE.md / AGENTS.md by walking up the directory tree and concatenating every file found along the way — Claude Code's memory docs say "All discovered files are concatenated into context rather than overriding each other", and OpenCode's Instruction.resolve walks from the edited file's directory up to the project root collecting each one.

They have to. In those systems a rule's scope is implicit in where the file sits, so the only way to recover the parent rule is to keep climbing. The author can't say "I apply here and no further".

Our specs declare their own scope in frontmatter, so there is no chain to walk — we match exactly what declared itself relevant. That's a real advantage of the glob model and it's worth stating explicitly, because it's also the reason the symlink-into-code-dirs idea was rejected: symlinks would have put us back into position-implies-scope.

But the same over-inclusion can reappear through broad globs, and it already has.

Reproduced on the branch

spec_match.py:299 sorts matches alphabetically:

matches.sort(key=lambda m: m.rel_path)

build_payload then spends the budget in that order. With max_spec_bytes: 8192 and max_total_bytes: 9000, roughly one FULL block fits per event — everything after it degrades to a one-line index entry.

Editing packages/cli/src/templates/shared-hooks/inject-spec-context.py matches:

spec	declared scope	size	sorts
platform-integration.md	packages/cli/src/templates/** — the whole templates tree	162,692 B	first (p)
spec-injection.md	.../shared-hooks/inject-spec-context.py — that exact file	28,535 B	second (s)

So the spec whose scope is literally this one file is crowded out by a directory-wide one, purely on alphabetical order — and the winner is 162 KB, which the 8,192-byte cap truncates to the first 5% anyway. Both specs end up useless in that event: one as a 5% fragment, the other as an index line.

Alphabetical order isn't a tie-break here, it's the whole ranking.

Two changes

Rank by specificity. A spec that matched via an exact path or a deep glob is more relevant to the current edit than one that matched via a tree-wide glob. Ranking by the specificity of the glob that matched (path segment depth, wildcard count, exact-vs-pattern) puts the precise one first and lets the broad one degrade to an index line — which is the right way round. Alphabetical order only makes sense as the final tie-break.

Discourage over-broad scopes. Rules that genuinely apply repo-wide belong in the session-start context, delivered once — not as a spec declaring ** that competes for budget on every single file touch. Since scope lives in frontmatter, this is checkable: a lint over paths: can flag globs above some breadth threshold, which is something the directory-based mechanisms can't offer at all (there, breadth is a property of where you happened to put the file).

Neither depends on the provider direction above; both apply to the current implementation as-is.