--- 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, )`. 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.