Seven features from the 2026-10-31 agent-knowledge research, no schema change (kb_schema_version stays 1.5): - F1 session-start hook: session_start.py --hook, start_hook.py, opt-in via session.start_hook in ckb.yaml (D-0011) - F2 kept answers in outputs/answers/, lint check 16 (D-0013) - F3 ingest check-in before writing; batch mode skips it - F5 open threads in workload notes, collected at session start (D-0012) - F6 dedup_inbox.py: duplicates reported before ingest - F19 lint check 15 for secrets and <private> spans, --secrets before every sync commit, redaction in saved conversations (D-0013) - F20 context budget: lint_report.py --budget, budget in ckb.yaml Smoke test covers every new script. Docs updated in EN and PL. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
68 lines
3.3 KiB
Markdown
68 lines
3.3 KiB
Markdown
---
|
|
type: decision
|
|
tldr: Session start can run as a Claude Code SessionStart hook that injects the Rule E brief before the first message and again after every compaction; it is opt-in per KB in ckb.yaml, installed per machine in the gitignored settings.local.json, and Rule E stays the fallback for every other agent.
|
|
status: accepted
|
|
decided_on: 2026-11-02
|
|
decided_by: Michał Kopeć
|
|
affects: AGENTS.md, ckb.yaml, .agents/skills/ckb-lint/scripts/session_start.py, .agents/skills/ckb-lint/scripts/start_hook.py, .agents/skills/ckb-lint/SKILL.md, docs/MANUAL.md
|
|
confidence: 0.8
|
|
quality: 0.8
|
|
last_updated: 2026-11-02
|
|
freshness_window_days: 365
|
|
retention: high
|
|
---
|
|
|
|
# D-0011 — The session-start brief can be injected by a hook
|
|
|
|
**Status:** Accepted · **Decided:** 2026-11-02 · **Deciders:** Michał Kopeć
|
|
|
|
## Context
|
|
|
|
Rule E asks the agent to run `session_start.py` as its first action
|
|
(D-0009). That works only while the instruction is followed, and it fires
|
|
once: when a long session is compacted, the brief is summarised away with
|
|
everything else. Claude Code's `SessionStart` hook fires on startup, resume,
|
|
`/clear` and compaction, and can add text to the context before the model
|
|
acts. m3talux/superbrain and claude-mem use the same mechanism for the same
|
|
reason (research report, 2026-10-31, feature F1).
|
|
|
|
## Decision
|
|
|
|
1. **`session_start.py --hook`** reads the hook's JSON on stdin and prints
|
|
the same brief as `additionalContext`, headed `ckb session brief
|
|
(SessionStart hook, <source>)`. On `compact` and `resume` it says
|
|
`announce: no`, because the title was already announced. It looks the
|
|
stored title up by the hook's `session_id`, since a new session has no
|
|
transcript yet. When none is stored, the `title:` line gives the
|
|
`save_conversation.py --set-title` command.
|
|
2. **Opt-in per KB, installed per machine.** `session: start_hook: true` in
|
|
`ckb.yaml` says the KB wants it. `start_hook.py --check|--install|--remove`
|
|
manages the entry in `.claude/settings.local.json`, which is gitignored.
|
|
The brief prints a `start hook:` line only when the two disagree, and the
|
|
agent asks before changing anything. This is the same pattern as the
|
|
autosave hook.
|
|
3. **Rule E stays.** One sentence in `AGENTS.md` tells the agent not to run
|
|
the script again when the hooked brief is already in context. Every other
|
|
agent keeps running Rule E by hand.
|
|
4. **The hook can never block a session**: its command discards stderr and
|
|
always exits 0.
|
|
|
|
## Alternatives considered
|
|
|
|
- **Commit the hook in `.claude/settings.json`** was rejected: a committed
|
|
hook runs code on every clone of a shared KB, without the cloner choosing it.
|
|
- **Replace Rule E with the hook** was rejected: hooks are Claude Code only,
|
|
and the template supports any agent that reads `AGENTS.md`.
|
|
- **A `PreCompact` hook** was rejected: `SessionStart` with source
|
|
`compact` already fires after compaction, and that is when the brief is
|
|
needed.
|
|
|
|
## Consequences
|
|
|
|
- In Claude Code with the hook on, the brief costs no tool call and survives
|
|
compaction.
|
|
- The title is stored by a second, explicit command instead of by the
|
|
script, because the agent picks the title only after reading the first
|
|
message.
|
|
- Two hooks now share `settings.local.json`. Each installer touches only its
|
|
own entry, and the smoke test checks that.
|