feat: Add SessionStart hook as project-scoped --append-system-prompt alternative

Summary

Add a new hook event SessionStart that fires once at the beginning of each Claude Code session. Its stdout is injected into the conversation context — functioning as a project-scoped, committed, automatically-applied equivalent of --append-system-prompt.

Motivation

--append-system-prompt solves context injection at session start, but has two key limitations:

1. VSCode Extension: When using Claude Code as a VSCode extension, sessions are started through the IDE — there is no way to pass --append-system-prompt or any CLI arguments. This makes the flag unusable for the majority of interactive sessions.

1. CLI usage: Even when using the CLI directly, the flag requires passing it on every invocation. This is user-dependent and not tied to the project.

Critical [C] rules in CLAUDE.md (e.g., "load flow diagrams at session start") rely entirely on the model remembering to execute them, which is unreliable even when documented in multiple places.

A SessionStart hook would make this automatic, project-scoped, and team-consistent — regardless of whether the session is started via CLI or VSCode.

Decisions (Pre-clarified)

| Decision | Choice | Rationale |
|---|---|---|
| Hook event name | SessionStart | Clear, matches existing PreToolUse/PostToolUse naming |
| stdout behavior | Inject into context | Matches --append-system-prompt behavior |
| Matcher field | Not required | No tool to match against at session start |
| Config location | settings.json / settings.local.json | Consistent with existing hook config |

Specification

Comparison with --append-system-prompt

| | --append-system-prompt | SessionStart hook |
|---|---|---|
| Scope | Per CLI invocation | Per project (committed in settings) |
| VSCode support | Not available | Works in all environments |
| Team consistency | Each dev must remember the flag | Automatic for everyone |
| Dynamic content | Static string only | Can run commands (cat, scripts) |
| Config location | CLI args | settings.json / settings.local.json |
| Reproducibility | User-dependent | Guaranteed |

Proposed Configuration

// .claude/settings.json (committed, shared with team)
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat .claude/flows/*.md"
          }
        ]
      }
    ]
  }
}

Proposed Behavior

• Fires once per session, before the first user message is processed
• stdout is injected into conversation context (like --append-system-prompt)
• stderr is shown as informational output to the user
• No matcher field needed (no tool to match against)
• Non-zero exit code: warn but don't abort session
• Works in both CLI and VSCode extension environments

Equivalent CLI usage today (CLI only)

claude --append-system-prompt "$(cat .claude/flows/*.md)"

This workaround is not possible in VSCode — the hook would close that gap.

Documentation Updates

| File | Change |
|---|---|
| Claude Code hooks docs | Add SessionStart to hook events table |
| CLI reference | Cross-reference with --append-system-prompt |
| VSCode extension docs | Document hook support in IDE context |

Files & Directories to Check

| Path | Reason |
|---|---|
| CLAUDE.md | Contains [C] rule for session-start flow loading |
| .claude/settings.local.json | Existing hook configuration |
| .claude/flows/*.md | Example files that need loading at session start |
| docs/standards/mcp.md | Documents hook/settings configuration patterns |

Acceptance Criteria

• [ ] SessionStart hook event fires once at the beginning of each new session
• [ ] Works in both CLI and VSCode extension environments
• [ ] stdout from the hook command is injected into conversation context
• [ ] stderr is displayed as informational output
• [ ] No matcher field required in configuration
• [ ] Works in both settings.json (shared) and settings.local.json (local)
• [ ] Documented alongside existing PreToolUse/PostToolUse events

Risks & Mitigation

| Risk | Impact | Mitigation |
|---|---|---|
| Large stdout bloats context | High token usage per session | Document size recommendations, warn if output exceeds threshold |
| Slow commands delay session start | Poor UX | Add timeout (e.g., 5s default), show progress indicator |
| Command fails silently | Missing context without user awareness | Show stderr warnings, log failures |

Alternative Approach

Instead of (or in addition to) a SessionStart hook, the VSCode extension could be extended to allow users to configure CLI arguments (like --append-system-prompt) for new sessions — e.g., via VSCode settings or a workspace-level config. This would make existing CLI flags accessible in the IDE without introducing a new hook event type.