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

[ecosquirrel-dev]

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.

2. 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.

[github-actions]

Found 3 possible duplicate issues:

1. Feature Request: SessionStart hook for pre-session initialization #17278
2. [FEATURE] Add a --append-system-prompt-file <path> argument #6153
3. Plugin SessionStart hooks don't surface hookSpecificOutput.additionalContext to Claude #16538

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically closed as a duplicate of #17278.

If this is incorrect, please re-open this issue or create a new one.

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.