feat(hooklife): auto-activation hook (SessionStart + UserPrompt) for per-session rule injection (caveman activate-mode analog) #176

Summary

Add a per-session auto-activation hook to SIN-Code's internal/hooklife/ subsystem that injects a chosen rule block (verbosity mode, project profile, skill activation) at the start of every session, without requiring the user to type /terse or similar. Inspired by JuliusBrussee/caveman's SessionStart hook (src/hooks/caveman-activate.js):

Runs once per Claude Code session start. Three things:

1. Writes the active mode to $CLAUDE_CONFIG_DIR/.caveman-active via safeWriteFlag (creates if missing)
2. Emits caveman ruleset as hidden stdout — Claude Code injects SessionStart hook stdout as system context, invisible to user
3. Checks settings.json for statusline config; if missing, appends nudge to offer setup on first interaction

Silent-fails on all filesystem errors — never blocks session start.

The hook reads a config file at ~/.config/sin-code/auto-activate.json (or per-project .sin-code/auto-activate.json) and injects the chosen rule block on every session start.

Motivation

Caveman's SessionStart hook is the engine of the "always-on" UX. Without it, the user has to type /caveman every session. With it, the rule is silently active from message one. The README frames it as the "no nag" guarantee:

Lobster terse from message one. No /caveman per session. No nag.

The mechanism is flag-file + hook + system-prompt injection:

1. A flag file at $CLAUDE_CONFIG_DIR/.caveman-active is written by the hook.
2. The hook itself emits the rule body to stdout, which Claude Code injects as system context.
3. The UserPromptSubmit hook reads the flag and re-injects the rule per turn (per-turn reinforcement).

For SIN-Code, the equivalent is:

1. A flag file at ~/.config/sin-code/active-rules.json is written when a rule is activated.
2. The hooklife.SessionStart hook reads the flag and emits the rule body to its Decision.Output, which the agent loop prepends to the system prompt.
3. The hooklife.PreTurn hook (analogous to UserPromptSubmit) re-injects the rule per turn.

The user activates a rule with sin-code rules enable <name>, and the rule is active for all subsequent sessions. They deactivate with sin-code rules disable <name>. No nag, no per-session invocation.

Current State in SIN-Code

What this tells us: SIN-Code has the hooklife infrastructure (registry, runner, phases, built-ins). It does not have a SessionStart hook that emits a rule body to stdout, nor a PreTurn hook that re-injects. Both are well-bounded additions to the existing package.

What caveman does (precise)

From https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md:

src/hooks/caveman-activate.js — SessionStart hook

Runs once per Claude Code session start. Three things:

1. Writes the active mode to $CLAUDE_CONFIG_DIR/.caveman-active via safeWriteFlag (creates if missing)
2. Emits caveman ruleset as hidden stdout — Claude Code injects SessionStart hook stdout as system context, invisible to user
3. Checks settings.json for statusline config; if missing, appends nudge to offer setup on first interaction

Silent-fails on all filesystem errors — never blocks session start.

And:

src/hooks/caveman-mode-tracker.js — UserPromptSubmit hook

Reads JSON from stdin. Three responsibilities:

1. Slash-command activation. If prompt starts with /caveman, writes mode to flag file via safeWriteFlag:

   • /caveman → configured default (see caveman-config.js, defaults to full)
   • /caveman lite → lite
   • /caveman ultra → ultra
     ...

2. Natural-language activation/deactivation. Matches phrases like "activate caveman", "turn on caveman mode", ...

3. Per-turn reinforcement. When flag is set to a non-independent mode (i.e. not commit/review/compress), emits a small hookSpecificOutput JSON reminder so the model keeps caveman style after other plugins inject competing instructions mid-conversation. The full ruleset still comes from SessionStart — this is just an attention anchor.

The three components are:

1. Flag file: safeWriteFlag for symlink-safe writes. Refuses if flag target or its immediate parent is a symlink. Atomic temp + rename. Creates with 0600. Silent-fails on all errors.
2. SessionStart emission: writes the ruleset to stdout; the agent loader prepends it to the system prompt.
3. PreTurn re-injection: a small attention anchor per turn.

Detailed Implementation Plan

Phase 1 — Flag file and config

1. Add cmd/sin-code/internal/hooklife/autoactivate/flag.go (new subpackage) with:

   type Flag struct {
       Version int                       `json:"version"`
       Rules   map[string]RuleActivation `json:"rules"`
   }
   type RuleActivation struct {
       Level     string    `json:"level"`     // e.g. "terse" | "ultra" | "skill:sin-instinct"
       ActivatedAt time.Time `json:"activated_at"`
       ExpiresAt  *time.Time `json:"expires_at,omitempty"`
   }
   func DefaultPath() string // ~/.config/sin-code/active-rules.json
   func Read() (*Flag, error)
   func Write(f *Flag) error // safeWriteFlag-style: symlink-refuse, atomic
   func AddRule(level string) error
   func RemoveRule(level string) error

2. Add cmd/sin-code/internal/hooklife/autoactivate/safe_write.go with safeWrite:

   • os.OpenFile with O_NOFOLLOW where supported.
   • Refuses if the flag file or its parent is a symlink.
   • Atomic temp + rename.
   • 0600 mode.
   • Silent-fail on all errors (return the error but never panic).

3. Add config keys in cmd/sin-code/internal/config.go:25-43:

   RulesAutoActivate  []string `toml:"rules.auto_activate"` // default: []
   RulesAutoActivateOn   []string `toml:"rules.auto_activate_on"`   // events: "session_start" | "pre_turn"
   RulesAutoDeactivateOn []string `toml:"rules.auto_deactivate_on"`

Phase 2 — SessionStart hook

4. Add cmd/sin-code/internal/hooklife/autoactivate/hook.go with:

   type SessionStartHook struct{}
   func (SessionStartHook) ID() string { return "auto-activate-session-start" }
   func (SessionStartHook) Phases() []Phase { return []Phase{SessionStart} }
   func (SessionStartHook) Run(ctx context.Context, ev Event) Decision {
       flag, err := Read()
       if err != nil || flag == nil || len(flag.Rules) == 0 {
           return Decision{Verdict: Allow} // silent-fail
       }
       var body strings.Builder
       for level := range flag.Rules {
           body.WriteString(renderRuleBody(level))
           body.WriteString("\n\n")
       }
       return Decision{
           Verdict: Allow,
           Output:  body.String(), // agent loop prepends to system prompt
       }
   }

5. renderRuleBody looks up the level:

   • If level is terse/ultra/verbose/normal, call style.RenderSystemBlock(level) (issue feat(agent): add verbosity/compression mode (terse/ultra) with system-prompt injection #167).
   • If level is skill:<name>, look up the bundled skill in skills/flatfs.go:1-215 and return the SKILL.md body.
   • If level is profile, return docs/agent-profiles/sin-profile.md (issue feat(profile): single-source-of-truth sin-profile.md + per-agent renderers (Claude/Codex/Gemini/Cursor/Windsurf/Cline/Copilot) + CI sync #175).
   • Unknown level: empty string + warning log.

Phase 3 — PreTurn hook

6. Add PreTurnHook:

   type PreTurnHook struct{}
   func (PreTurnHook) ID() string { return "auto-activate-pre-turn" }
   func (PreTurnHook) Phases() []Phase { return []Phase{UserPrompt} }
   func (PreTurnHook) Run(ctx context.Context, ev Event) Decision {
       flag, err := Read()
       if err != nil || flag == nil || len(flag.Rules) == 0 {
           return Decision{Verdict: Allow}
       }
       // Per-turn attention anchor. The full ruleset is in SessionStart;
       // this is just a reminder so the model doesn't drift.
       var body strings.Builder
       body.WriteString("# Auto-activated rules\n")
       body.WriteString("Apply these rules for the rest of the session:\n")
       for level := range flag.Rules {
           body.WriteString("- ")
           body.WriteString(level)
           body.WriteString("\n")
       }
       return Decision{Verdict: Allow, Output: body.String()}
   }

7. Wire both hooks into the Registry at startup. This is the "always-on" path. The loopbuilder (per AGENTS.md §4) instantiates the Registry; we add the two new hooks alongside the existing built-ins.

Phase 4 — CLI

8. Add sin-code rules subcommand in cmd/sin-code/rules_cmd.go:

   • sin-code rules list — show the active rules.
   • sin-code rules enable <level> — add a rule.
   • sin-code rules disable <level> — remove a rule.
   • sin-code rules enable terse — terse mode (issue feat(agent): add verbosity/compression mode (terse/ultra) with system-prompt injection #167).
   • sin-code rules enable skill:sin-instinct — auto-inject sin-instinct.
   • sin-code rules enable profile — auto-inject the per-project profile.
   • sin-code rules --expires-in 1h terse — temporary activation (sets ExpiresAt).

9. Add a sin-code rules preview <level> command that prints the rule body without activating it. This is the "what would the model see" view.

10. Add the slash commands in the chat REPL:

    • /rules — show the active rules.
    • /terse / /verbose — already in issue feat(agent): add verbosity/compression mode (terse/ultra) with system-prompt injection #167; here we also call sin-code rules enable terse (or disable).

Phase 5 — Tests

11. Unit test for safeWrite:

    • Refuses to overwrite a symlink.
    • Atomic on crash.
    • Mode is 0600.

12. Unit test for Read / Write / AddRule / RemoveRule:

    • Round-trip preserves the flag.
    • AddRule is idempotent (does not duplicate).
    • RemoveRule removes the key.

13. Unit test for SessionStartHook.Run:

    • Empty flag → Allow, empty Output.
    • With terse rule → Output contains the terse ruleset.
    • Unknown level → Allow, empty Output (silent-fail).

14. Unit test for PreTurnHook.Run:

    • Empty flag → Allow, empty Output.
    • With terse rule → Output contains the attention-anchor line.

15. Integration test for sin-code rules:

    • enable terse writes the flag.
    • list shows it.
    • disable terse removes it.
    • preview terse prints the body without modifying.

16. Race test: go test -race -count=1 ./cmd/sin-code/internal/hooklife/... must pass.

Phase 6 — Docs

17. docs/auto-activate.md: the flag file, the hooks, the CLI, the lifetime.
18. Update AGENTS.md §14.2 (hooks) to reference the new hooks.
19. Update README.md to mention sin-code rules.
20. Update CHANGELOG.md Unreleased section.

Acceptance Criteria

• cmd/sin-code/internal/hooklife/autoactivate/ package exists with the flag file, the SessionStart hook, and the PreTurn hook.
• safeWrite refuses symlinks and is atomic.
• sin-code rules enable|disable|list|preview works.
• The SessionStart hook emits the rule body to Decision.Output when the flag has rules.
• The UserPrompt hook emits the attention-anchor per turn.
• The hooks silent-fail on all filesystem errors (no panic, no block).
• docs/auto-activate.md exists.
• All unit and integration tests pass with -race.
• golangci-lint, govulncheck, gosec (SARIF) green.

Risk and Rollback

• Risk: the rule body bloats the system prompt. Mitigation: the rule body is opt-in (sin-code rules enable). The user is in control. The default config has rules.auto_activate = [].
• Risk: the per-turn attention anchor competes with the user's own system prompt. Mitigation: the anchor is a small block (~50 chars for one rule); it is below the typical system-prompt size.
• Risk: the flag file is owned by the user; another process could clobber it. Mitigation: safeWrite refuses symlinks, uses 0600, and writes atomically. A racing process can still corrupt the file, but the corruption is visible (JSON parse fails) and the hook falls back to Allow with empty Output.
• Rollback: revert the PR. The flag file is a new artifact; deleting it is harmless. The hooks are new code paths; the existing built-ins are unchanged.

References

• Caveman SessionStart hook: https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md
• Caveman mode-tracker hook: https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md
• Caveman safeWriteFlag: https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md
• SIN-Code hooklife builtins: cmd/sin-code/internal/hooklife/builtin.go:1-183
• SIN-Code hooklife registry: cmd/sin-code/internal/hooklife/registry.go:1-46
• SIN-Code learning bridge: cmd/sin-code/internal/learning/learner.go:13
• SIN-Code adapters: cmd/sin-code/internal/adapters/
• SIN-Code config: cmd/sin-code/internal/config.go:25-43
• SIN-Code verbosity mode: issue feat(agent): add verbosity/compression mode (terse/ultra) with system-prompt injection #167
• SIN-Code agent profiles: issue feat(profile): single-source-of-truth sin-profile.md + per-agent renderers (Claude/Codex/Gemini/Cursor/Windsurf/Cline/Copilot) + CI sync #175
• SIN-Code AGENTS.md §14.2 (hooks), §9 (test discipline)