Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
Recall Injection Lifecycle - implementation plan
Feature branch: feat/recall-injection-lifecycle. Design: design.md in this directory.
Every task follows TDD: write the listed tests first, watch them fail, implement until they pass. Each task ends in one atomic conventional commit, and bun run fmt:check, bun run lint and bun run typecheck must be green before the commit. Commit with git commit --only <owned files> and never use git add ., because lanes run in parallel in one working tree.
Lanes and file ownership
There are four lanes, and no file belongs to more than one of them. A lane never edits another lane's files. When it needs something from another lane, it imports only the exports pinned in the contract below.
| Lane | Tasks | Owns (exclusive) |
|---|---|---|
| S - substrate | S1, S2, S3 | hooks/lib/session-state.ts, hooks/lib/injection-ledger.ts (new), src/core/config.ts, tests/hooks/session-state.test.ts, tests/hooks/injection-ledger.test.ts (new), tests/core/config-recall-inject.test.ts (new) |
| A - recall | A1, A2, A3, A4 | src/core/brain/recall-inject.ts, hooks/recall-inject.ts, tests/core/brain/recall-inject.test.ts, tests/core/brain/recall-inject-slices.test.ts (new), tests/hooks/recall-inject.test.ts, tests/hooks/recall-inject-dedupe.test.ts (new) |
| B - slice declaration | B1 | src/core/brain/policy/blocks/recall-inject.ts (new), src/core/brain/policy/validate.ts, src/core/brain/types.ts, tests/core/brain/policy/recall-inject-block.test.ts (new) |
| C - active digest and re-delivery | C1, C2, C3, C4 | src/core/brain/reground-parts.ts (new), hooks/active-inject.ts, hooks/reground-deliver.ts (new), hooks/hooks.json, plugins/codex/hooks/hooks.json (generated), tests/core/brain/reground-parts.test.ts (new), tests/hooks/active-inject-ledger.test.ts (new), tests/hooks/active-inject-reground.test.ts (new), tests/hooks/reground-deliver.test.ts (new), tests/hooks/hooks-json-shape.test.ts, tests/core/install/adapters/grok-hook-parity.test.ts |
| D - docs (after all lanes) | D1 | docs/decision-models/recall-inject.md, docs/cli-reference.md, docs/observability.md, hooks/README.md |
Order: S1 -> S2 -> S3 are committed first. B1 and C1 have no dependency and may start at once. A1 needs nothing from S, but A2 needs S. A3 needs B1. C2 needs S. D1 runs last.
Cross-lane contract (pinned)
hooks/lib/session-state.ts (S1)
export const HOOK_STATE_STALE_LOCK_MS = 30_000;
export type HookStateMutator<T> = (
state: Record<string, unknown>,
nowMs: number,
) => { readonly state: Record<string, unknown>; readonly result: T };
export type HookStateUpdateOutcome<T> =
| { readonly status: "ok"; readonly result: T }
| { readonly status: "busy" }
| { readonly status: "failed" };
export function updateHookState<T>(
vault: string,
sessionId: string | null | undefined,
mutate: HookStateMutator<T>,
opts?: { readonly tryOnce?: boolean; readonly nowMs?: number },
): HookStateUpdateOutcome<T>;
export function pruneHookStateFiles(
vault: string,
opts?: { readonly maxAgeMs?: number; readonly maxFiles?: number; readonly nowMs?: number },
): number; // defaults: 7 days, 200 files; returns files removed; never throws
hooks/lib/injection-ledger.ts (S2)
export const LEDGER_KEY_RECALL = "osb.recall_inject.injected";
export const LEDGER_KEY_ACTIVE = "osb.active_inject.emitted";
export const LEDGER_KEY_REGROUND = "osb.reground.queue";
export const LEDGER_TTL_MS = 86_400_000; // 24 h, refreshed on every write
export function isRealSessionId(sessionId: unknown): sessionId is string;
export function recallNoteKey(note: {
readonly path: string;
readonly origin?: string;
readonly startLine: number;
readonly endLine: number;
}): string; // `${origin ?? ""}:${path}#L${startLine}-L${endLine}`
export function readRecallInjected(vault: string, sessionId: string, nowMs?: number): ReadonlySet<string>;
export function recordRecallInjected(
vault: string,
sessionId: string,
keys: ReadonlyArray<string>,
nowMs?: number,
): boolean; // merges into the existing set
export function readActiveEmittedPaths(vault: string, sessionId: string, nowMs?: number): ReadonlySet<string>;
export function digestNotePaths(input: {
readonly emittedText: string;
readonly activeBodyEmitted: boolean;
readonly lessonsBodyEmitted: boolean;
}): ReadonlyArray<string>; // `pref-<slug>` tokens -> Brain/preferences/pref-<slug>.md, plus Brain/active.md / Brain/lessons.md
export function beginInjectionEpoch(
vault: string,
sessionId: string,
input: {
readonly epoch: string;
readonly emittedPaths: ReadonlyArray<string>;
readonly regroundParts: ReadonlyArray<string>; // parts 2..n; empty deletes the queue
readonly partCeilingChars: number;
},
nowMs?: number,
): boolean; // one locked write: set ACTIVE, delete RECALL, set or delete REGROUND
export type RegroundTake =
| {
readonly status: "part";
readonly part: string;
readonly index: number; // 1-based position in the full split (first queued part is 2)
readonly total: number;
readonly epoch: string;
readonly partCeilingChars: number;
}
| { readonly status: "empty" }
| { readonly status: "busy" }
| { readonly status: "failed" };
export function takeRegroundPart(vault: string, sessionId: string, nowMs?: number): RegroundTake; // tryOnce
src/core/config.ts (S3)
export interface RecallInjectCapsResolution {
readonly caps: {
readonly maxNotes?: number;
readonly maxChars?: number;
readonly timeBudgetMs?: number;
readonly confidenceFloor?: number;
};
readonly invalid: ReadonlyArray<string>; // config key names whose value was rejected
}
export function resolveRecallInjectCaps(configPath?: string): RecallInjectCapsResolution;
export function resolveRecallInjectDedupe(configPath?: string): boolean; // default true
export function resolveRegroundPartsEnabled(configPath?: string): boolean; // default false
export const REGROUND_PART_CHARS_DEFAULT = 9000;
export function resolveRegroundPartChars(
runtime: "claudecode" | "codex",
configPath?: string,
): number;
The config keys and env overrides follow. Env always wins over the config value.
| Config key | Env override | Range / default |
|---|---|---|
recall_inject_max_notes |
OPEN_SECOND_BRAIN_RECALL_INJECT_MAX_NOTES |
integer 1..10 |
recall_inject_max_chars |
OPEN_SECOND_BRAIN_RECALL_INJECT_MAX_CHARS |
integer 200..8000 |
recall_inject_time_budget_ms |
OPEN_SECOND_BRAIN_RECALL_INJECT_TIME_BUDGET_MS |
integer 250..6000 |
recall_inject_confidence_floor |
OPEN_SECOND_BRAIN_RECALL_INJECT_CONFIDENCE_FLOOR |
number 0..1 |
recall_inject_dedupe |
OPEN_SECOND_BRAIN_RECALL_INJECT_DEDUPE |
boolean, default true |
reground_parts_enabled |
OPEN_SECOND_BRAIN_REGROUND_PARTS_ENABLED |
boolean, default false |
reground_part_chars |
OPEN_SECOND_BRAIN_REGROUND_PART_CHARS |
integer 2000..100000, default 9000 |
reground_part_chars_claudecode |
OPEN_SECOND_BRAIN_REGROUND_PART_CHARS_CLAUDECODE |
as above, wins over reground_part_chars |
reground_part_chars_codex |
OPEN_SECOND_BRAIN_REGROUND_PART_CHARS_CODEX |
as above, wins over reground_part_chars |
src/core/brain/types.ts (B1)
export interface RecallSliceSpec {
readonly name: string; // ^[a-z][a-z0-9]{0,23}$
readonly heading: string; // defaults to name
readonly pathPrefix: string | null;
readonly types: ReadonlyArray<string>; // frontmatter `type` values; empty = no class filter
readonly limit: number | null; // 1..10
readonly maxChars: number | null; // 100..8000
}
export interface BrainRecallInjectConfig {
readonly slices: ReadonlyArray<RecallSliceSpec>; // declared order, at most 6
}
// BrainConfig gains: readonly recall_inject?: BrainRecallInjectConfig;
_brain.yaml shape (B1):
recall_inject:
slices: [decisions, lessons]
slice_decisions_heading: Recent decisions
slice_decisions_path_prefix: Brain/decisions/
slice_decisions_types: [decision]
slice_decisions_limit: 2
slice_decisions_max_chars: 400
slice_lessons_path_prefix: Brain/lessons
src/core/brain/recall-inject.ts additions (A1, A3)
// RecallAbstainReason gains: | "all_already_injected" | "all_slices_abstained"
// RecallInjectOptions gains:
// readonly alreadyInjected?: ReadonlySet<string>; // recallNoteKey values
// readonly activeDigestPaths?: ReadonlySet<string>; // vault-relative paths, path-only match
// readonly slices?: ReadonlyArray<RecallSliceSpec>;
// readonly sliceRetriever?: (slice: RecallSliceSpec, limit: number) => RecallRetriever;
// The inject decision variant gains:
// readonly injectedNotes: ReadonlyArray<{ path: string; origin?: string; startLine: number; endLine: number }>;
// readonly slices?: ReadonlyArray<{ name: string; outcome: "inject" | RecallAbstainReason; notes: number }>;
export interface RecallRetrieverFilter {
readonly limit?: number;
readonly pathPrefix?: string;
readonly types?: ReadonlyArray<string>;
}
// defaultRecallRetriever(configPath, vault, limitOrFilter: number | RecallRetrieverFilter = RECALL_INJECT_MAX_NOTES)
src/core/brain/reground-parts.ts (C1)
export const REGROUND_MAX_PARTS = 8;
export interface RegroundSplit {
readonly parts: ReadonlyArray<string>; // parts[0] is emitted now; a lone part equals the joined input byte for byte
readonly utf16Chars: number; // length of the unsplit joined context
readonly partsDropped: number;
readonly overBudget: boolean; // any part > ceiling, or partsDropped > 0
}
export function splitRegroundParts(
blocks: ReadonlyArray<string>, // standing, scoped, memory, in priority order
ceilingChars: number,
join: (blocks: ReadonlyArray<string>) => string, // active-inject's joinBlocks, so the fit case is identical
): RegroundSplit;
Tasks
Task S1: Locked multi-key hook-state update, stale-lock takeover, prune
- Lane: S
- Files:
hooks/lib/session-state.ts,tests/hooks/session-state.test.ts - Tests first (in
tests/hooks/session-state.test.ts):updateHookStateapplies a mutator under the scope lock and preserves other keys.- With
tryOnce: trueand a held lock it returnsbusywithin 20 ms, with no retry loop. - Without
tryOnceit keeps today's 20 x 5 ms retry. - A lockfile with mtime older than
HOOK_STATE_STALE_LOCK_MSis taken over. - Writes leave no partial file: the state file is replaced by rename, and no
*.tmpis left behind. writeHookStampstill round-trips withreadHookStamp(existing cases unchanged).pruneHookStateFilesremoves only files older thanmaxAgeMs, stops atmaxFiles, ignores lockfiles and non-JSON files, and returns 0 on a missing directory.
- What: implement the S1 contract. Writes go through
atomicWriteFileSync(src/core/fs-atomic.ts), includingwriteHookStamp. Stale takeover unlinks the lockfile only when its mtime is older than the threshold, then makes one freshacquireLockSyncattempt. - Acceptance:
bun test tests/hooks/session-state.test.ts tests/hooks/nav-inject.test.ts tests/hooks/pretool-orient.test.ts - Depends on: none
Task S2: Injection ledger module
- Lane: S
- Files:
hooks/lib/injection-ledger.ts(new),tests/hooks/injection-ledger.test.ts(new) - Tests first:
isRealSessionIdrejectsundefined,null,""and non-strings.recallNoteKeyis stable and includes the origin and the line span.recordRecallInjectedmerges sets andreadRecallInjectedreturns them untilLEDGER_TTL_MSpasses.digestNotePathsmaps every`pref-<slug>`token and addsBrain/active.mdandBrain/lessons.mdonly when flagged. Repeated tokens are deduped.beginInjectionEpochsets the active set, clears the recall set, and replaces or deletes the queue in one write.takeRegroundPartreturns parts 2..n in order, thenempty. It returnsbusywhile the lock is held, and a subsequent take still returns the undelivered part, so nothing is lost or duplicated.- Two interleaved takers in one process never receive the same index.
- Each key is isolated per session id.
- What: implement the S2 contract on top of
updateHookStateandreadHookStamp.takeRegroundPartpassestryOnce: true. The ledger is the only module that spells the three key strings. - Acceptance:
bun test tests/hooks/injection-ledger.test.ts - Depends on: S1
Task S3: Config resolvers for recall caps, dedupe and re-delivery
- Lane: S
- Files:
src/core/config.ts,tests/core/config-recall-inject.test.ts(new) - Tests first:
- Each key resolves from config and from env, and env wins.
- Out-of-range, non-numeric and non-integer values land in
invalidand are omitted fromcaps. - Unset keys produce empty
capsand emptyinvalid. resolveRecallInjectDedupedefaults to true and treats"false"as false.resolveRegroundPartsEnableddefaults to false.resolveRegroundPartCharsprecedence is runtime key, thenreground_part_chars, then 9000, and an invalid value falls through to the next level.- No resolver throws on a malformed config file.
- What: implement the S3 contract, using
resolveNavTierCadenceMinutesas the lenient pattern andresolveConfigFlagfor the booleans.resolveRecallInjectDedupeneeds a default-true variant: a missing value is true, and only an explicit falsy literal is false. - Acceptance:
bun test tests/core/config-recall-inject.test.ts tests/core/config-read-failure.test.ts - Depends on: none (it is ordered after S2 only to keep the substrate commits contiguous)
Task B1: recall_inject: policy block and slice types
- Lane: B
- Files:
src/core/brain/types.ts,src/core/brain/policy/blocks/recall-inject.ts(new),src/core/brain/policy/validate.ts,tests/core/brain/policy/recall-inject-block.test.ts(new) - Tests first:
- The YAML from the contract parses to two
RecallSliceSpecs in declared order, with the heading defaulting to the name. - A vault without the block yields no
recall_injectkey onBrainConfig. - Each of these is a named hard error:
- an unknown slice field
- a
slice_*key for an undeclared name - a duplicate name
- a bad name pattern
- more than 6 slices
limitoutside 1..10max_charsoutside 100..8000typesthat is not an array
- An unknown non-slice key warns through
warnUnknownKeysand does not error. path_prefixis normalised to forward slashes, and a value containing..is rejected.
- The YAML from the contract parses to two
- What: add the types and
parseRecallInjectBlock(ctx)modelled onpolicy/blocks/active.ts(openBlock,requireIntegerInRange,warnUnknownKeysfor non-slice_keys), and register it inpolicy/validate.tsnext toparseActiveBlock. - Acceptance:
bun test tests/core/brain/policy/recall-inject-block.test.ts tests/core/brain/policy-active.test.ts tests/core/brain/policy-safe-loaders.test.ts - Depends on: none
Task A1: Pure-core dedupe and cross-lane filter
- Lane: A
- Files:
src/core/brain/recall-inject.ts,tests/core/brain/recall-inject.test.ts - Tests first, using the existing fake retriever:
- With
alreadyInjectedholding a candidate's key, that candidate is dropped after the floor check and the next one is kept. matchQualityand the floor verdict are identical with and without the set, which pins the coupling.- When every surviving candidate is filtered, the result is
abstainwithall_already_injectedand the samematchQuality. - A different line span of an injected path is not filtered.
activeDigestPathsfilters by path on any span.injectedNoteslists exactly the notes rendered: a note cut by themaxCharsfit and a note removed by the decision filter are both absent.- With neither option set, the brief is byte-identical to a fixture captured before the change.
- With
- What: add the options, the filter between the floor check and
ranked.slice(0, maxNotes), the new abstain reason, andinjectedNoteson the inject variant, computed from the notesrenderRecallBriefactually emitted and afterapplyDecisionFilter. The key function is a local mirror ofrecallNoteKeywith the same format string. The contract test in A2 pins that both produce equal keys. - Acceptance:
bun test tests/core/brain/recall-inject.test.ts tests/core/brain/recall-inject-decision.test.ts tests/core/bench/failure-modes.test.ts - Depends on: none
Task A2: Hook wiring for caps, dedupe and cross-lane read
- Lane: A
- Files:
hooks/recall-inject.ts,tests/hooks/recall-inject.test.ts,tests/hooks/recall-inject-dedupe.test.ts(new) - Tests first:
- Flag off: still no stdout, and no
hook-state/directory is created (extends the existing no-op test). - An invalid
recall_inject_max_noteslands in the audit line'sconfig_invalid, and the decision still runs on the constant. recall-inject-dedupe.test.tsbuilds an indexed temp vault (tests/helpers/search-fixtures.ts) and spawns the hook twice with onesession_idand one prompt. The first run injects. The second run abstains withall_already_injectedand recordsdedupedin its audit line.- The same pair with no
session_idinjects both times. - With
recall_inject_dedupe: false, both runs inject. - A ledger seeded through
beginInjectionEpochwith a preference path suppresses that note. recallNoteKeyfrom the ledger equals the core's key for the same note.
- Flag off: still no stdout, and no
- What: read
payload.session_id. PassresolveRecallInjectCaps().capsintodecideRecallInject, and pass the caps'maxNotesas the retriever limit. WhenisRealSessionIdand dedupe are both on, readreadRecallInjectedandreadActiveEmittedPathsand pass them. After the stdout write, callrecordRecallInjectedwith the keys ofdecision.injectedNotes. Every ledger touch sits after the:209opt-out. - Acceptance:
bun test tests/hooks/recall-inject.test.ts tests/hooks/recall-inject-dedupe.test.ts tests/hooks/recall-inject-decision-model.test.ts - Depends on: A1, S2, S3
Task A3: Pure-core slice execution and sectioned rendering
- Lane: A
- Files:
src/core/brain/recall-inject.ts,tests/core/brain/recall-inject-slices.test.ts(new) - Tests first, with fake per-slice retrievers:
- Two slices render inside one fence under their headings, in declared order.
- A slice below its own floor is omitted and recorded with outcome
below_floor. - The global
maxNotesandmaxChars(fence included) bound the sum, and the slice declared later is the one clamped. - A note found by both slices appears once, in the first.
- Dedupe options apply across slices.
- All slices abstaining gives
all_slices_abstainedwith per-slice outcomes. - The slices share one time budget: a slow slice past the budget makes the decision
errorwith the timeout fault, not a partial inject. - A hostile heading is neutralised like a title.
slicesundefined or empty takes exactly today's path, byte for byte.
- What: implement the slice path in
decideRecallInject, theRecallRetrieverFilterform ofdefaultRecallRetriever(mappingpathPrefixandtypesontoSearchOptions.pathPrefixandproperties: Map([["type", types]])), and a sectioned variant ofrenderRecallBriefthat shares the fence and the neutralisers. - Acceptance:
bun test tests/core/brain/recall-inject-slices.test.ts tests/core/brain/recall-inject.test.ts - Depends on: A1, B1
Task A4: Hook wiring for slices
- Lane: A
- Files:
hooks/recall-inject.ts,tests/hooks/recall-inject-dedupe.test.ts - Tests first (in the indexed-fixture suite):
- A vault with a
recall_inject:block holding onepath_prefixslice injects only notes under that prefix, under the slice heading, and the audit line carriessliceswith per-slice counts. - A vault whose
_brain.yamlfails to load falls back to the unsliced path, and the audit line recordsslices_config: "invalid".
- A vault with a
- What: load
loadBrainConfig(vault).recall_inject?.slicesinside the existing try boundary, and passslicesplus asliceRetrieverbuilt fromdefaultRecallRetriever(configPath, vault, {limit, pathPrefix, types}). - Acceptance:
bun test tests/hooks/recall-inject-dedupe.test.ts tests/hooks/recall-inject.test.ts - Depends on: A2, A3
Task C1: Pure re-delivery splitter
- Lane: C
- Files:
src/core/brain/reground-parts.ts(new),tests/core/brain/reground-parts.test.ts(new) - Tests first:
- If the joined input fits the ceiling, the result is one part that equals
join(blocks)byte for byte. - Over the ceiling, every part is at most the ceiling in
.lengthwith the header and trailer included. - Block order is preserved and the standing block starts part 1.
- Splitting prefers block, then paragraph, then line boundaries.
- A single 30,000-char line is hard-cut.
- More than
REGROUND_MAX_PARTSparts givespartsDropped > 0andoverBudget. - Astral characters (surrogate pairs) are never cut in half.
utf16Charsequalsjoin(blocks).length.
- If the joined input fits the ceiling, the result is one part that equals
- What: implement the C1 contract with the header and trailer texts from
design.md. - Acceptance:
bun test tests/core/brain/reground-parts.test.ts - Depends on: none
Task C2: active-inject records the injection epoch and the emitted set
- Lane: C
- Files:
hooks/active-inject.ts,tests/hooks/active-inject-ledger.test.ts(new) - Tests first:
- With
recall_inject_enabledon and asession_id, a SessionStart writesosb.active_inject.emittedholding the pref paths present in the emitted body and clears a pre-seededosb.recall_inject.injected. - A preference cut by the budget is absent from the set.
- With both recall and reground flags off, no
hook-state/file is written and stdout is byte-identical to the existingactive-inject.test.tsexpectations. - Without a
session_id, nothing is written. - On
startup, a 10-day-old scope file is pruned. - A ledger write failure (read-only state directory) leaves stdout unchanged and the exit code 0.
- With
- What: after the stdout write and beside
recordInjectionSize, callbeginInjectionEpoch(epoch is${source}:${Date.now()}) withdigestNotePathsover the emitted text, gated as described indesign.md. CallpruneHookStateFilesonsource === "startup"after a successful ledger write. In this taskregroundPartsis always empty. - Acceptance:
bun test tests/hooks/active-inject-ledger.test.ts tests/hooks/active-inject.test.ts tests/hooks/active-inject-meter.test.ts tests/hooks/active-inject-scoped-rules.test.ts - Depends on: S1, S2, S3
Task C3: active-inject splits an oversized payload and meters it
- Lane: C
- Files:
hooks/active-inject.ts,tests/hooks/active-inject-reground.test.ts(new) - Tests first:
- With
reground_parts_enabledon, a Claude Code-shaped payload (atranscript_pathunder/.claude/projects/) and standing rules plus a body totalling 20,000 chars, stdout carries only part 1, and the ledger holds parts 2..n under the new epoch. - The same with
reground_part_chars_claudecode: 5000produces more parts. - A grok-shaped or unknown payload emits the single full payload and queues nothing.
- Under the ceiling, the output is byte-identical with the flag on.
- The receipt carries
utf16_chars,part_ceiling_chars,parts_total,parts_droppedandover_budgetonly when the flag is on. - The receipt with the flag off deep-equals the existing meter expectation.
- The emitted set from C2 includes pref paths from the queued parts.
- With
- What: resolve the runtime with
detectHookRuntime. When the flag is on and the runtime isclaudecodeorcodex, callsplitRegroundParts([standingBlock, scopedBlock, memoryContext], resolveRegroundPartChars(runtime), joinBlocks), writeparts[0], and passparts.slice(1)tobeginInjectionEpoch. Then extendrecordInjectionSizewith the meter fields. - Acceptance:
bun test tests/hooks/active-inject-reground.test.ts tests/hooks/active-inject-ledger.test.ts tests/hooks/active-inject.test.ts tests/hooks/active-inject-meter.test.ts - Depends on: C1, C2
Task C4: reground-deliver carrier hook and registration
- Lane: C
- Files:
hooks/reground-deliver.ts(new),hooks/hooks.json,plugins/codex/hooks/hooks.json(generated),tests/hooks/reground-deliver.test.ts(new),tests/hooks/hooks-json-shape.test.ts,tests/core/install/adapters/grok-hook-parity.test.ts - Tests first (spawned hook):
- Flag off: no stdout, no vault resolution and no
hook-state/directory. - Flag on with a queue seeded through
beginInjectionEpoch:- each PostToolUse spawn emits the next part as
hookSpecificOutput.additionalContextwithhookEventName: "PostToolUse", then nothing once the queue is empty - a UserPromptSubmit spawn emits the next part with
hookEventName: "UserPromptSubmit" - a held scope lock makes the spawn emit nothing and exit 0 within its budget, and the part is delivered by the next spawn
- every delivery appends one audit line with
part,total,epoch,bytes,utf16_chars,part_ceiling_charsandover_budget
- each PostToolUse spawn emits the next part as
- Any other
hook_event_nameemits nothing. hooks-json-shapeasserts the PostToolUse*and UserPromptSubmit*entries end in theo2b-hook reground-deliverfallback.- The grok parity test declares
PostToolUse:reground-deliverandUserPromptSubmit:reground-deliveras divergences with the reason "chunked re-delivery splits only for Claude Code and Codex; grok keeps the single SessionStart payload".
- Flag off: no stdout, no vault resolution and no
- What: write the hook. It reads stdin, checks the flag with
resolveRegroundPartsEnabledbefore anything else, then checksisRealSessionId, resolves the vault, callstakeRegroundPart, writes stdout onpart, and appends the audit line through the hook-audit root builder (tests/hooks/audit-root.test.tsenforces this). It arms the process ceiling like its siblings. Register it inhooks/hooks.json: a new PostToolUse group with matcher*, and a fourth command appended to the UserPromptSubmit*group. Then runbun run sync-plugin-mirrors. - Acceptance:
bun test tests/hooks/reground-deliver.test.ts tests/hooks/hooks-json-shape.test.ts tests/hooks/audit-root.test.ts tests/core/install/adapters/grok-hook-parity.test.ts tests/scripts/sync-plugin-mirrors.test.ts && bun run sync-plugin-mirrors:check - Depends on: S2, S3, C3
Task D1: Documentation
- Lane: D
- Files:
docs/decision-models/recall-inject.md,docs/cli-reference.md,docs/observability.md,hooks/README.md - What:
docs/cli-reference.mdgets every config key from the S3 table, with env names, ranges and defaults (besiderecall_inject_enabledat :739 and the context-delivery keys at :816), plus therecall_inject:_brain.yamlblock with the contract example.docs/decision-models/recall-inject.mdcovers dedupe semantics, the cross-lane digest filter, the two new abstain reasons and slice clamping.docs/observability.mdcovers the new receipt and audit fields.hooks/README.mdgets rows for the tworeground-deliverregistrations.- The root
README.mdlists no hook config keys and stays unchanged.
- Acceptance:
bun test tests/docsandbun run link-ratchet:check - Depends on: A4, B1, C4
Version bump and CHANGELOG
None of these tasks bumps the version or edits CHANGELOG.md. The bump to the next minor version, the CHANGELOG.md entry with its compare link (including the disclosure that recall_inject_dedupe defaults to true for existing opt-in users) and bun run scripts/sync-version.ts all happen later in the osb-pr-prepare phase, inside the same pull request.