ckb/docs/decisions/0011-session-start-hook.md
Michał Kopeć cb56da51e5 Template 1.22.0: agent-knowledge release 1
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>
2026-11-02 19:25:02 +01:00

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.