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

3.3 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision 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. accepted 2026-11-02 Michał Kopeć 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 0.8 0.8 2026-11-02 365 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.