Session Lifecycle and Bootstrap

Relevant source files

• .claude-plugin/marketplace.json
• .claude-plugin/plugin.json
• .gitattributes
• .opencode/plugins/superpowers.js
• RELEASE-NOTES.md
• agents/code-reviewer.md
• docs/windows/polyglot-hooks.md
• hooks/hooks.json
• hooks/run-hook.cmd
• hooks/session-start
• tests/opencode/setup.sh
• tests/opencode/test-plugin-loading.sh

This document details the session initialization process, focusing on how the SessionStart hook injects the using-superpowers skill content before the agent's first turn. This bootstrap mechanism establishes the agent's "prime directive" to check for and use skills.

For information about skill discovery after bootstrap, see Skills Discovery and Resolution. For platform-specific integration details, see Multi-Platform Integration.

Overview

The session lifecycle in Superpowers follows a strict sequence:

1. Session Start Event - Platform triggers when session begins, resumes, or context is cleared
2. Hook Execution - session-start.sh runs synchronously before agent receives user input
3. Bootstrap Injection - Full using-superpowers skill content embedded in session context
4. Agent Initialization - Agent begins with skills protocol already in context
5. First User Turn - Agent must apply mandatory skill-checking protocol

Critical timing requirement: The hook must complete before the agent's first response. This ensures the bootstrap context is present when the agent processes its first user message.

Sources: RELEASE-NOTES.md25-27 hooks/session-start.sh1-51 hooks/hooks.json1-16

Hook System Architecture

Diagram: Session Start Hook Execution Flow

The hook configuration in hooks.json uses a regex matcher to trigger on session lifecycle events. The async: false setting forces synchronous execution, ensuring completion before the agent's first turn.

Sources: hooks/hooks.json1-16 hooks/session-start.sh1-51

Synchronous vs Asynchronous Execution

Synchronous Execution (Current)

As of v4.3.0, the SessionStart hook runs synchronously (async: false in hooks/hooks.json10):

Why synchronous is critical:

• Guarantees hook completes before agent's first response
• Ensures using-superpowers content is in context from the start
• Agent applies mandatory skill-checking protocol to first user message

Historical Async Issues

Prior to v4.3.0, the hook ran asynchronously (async: true):

Problem: When async, the hook could fail to complete before the model's first turn, meaning using-superpowers instructions weren't in context for the first message.

Windows-specific issue (v4.2.0): On Windows, synchronous hooks blocked the TUI from entering raw mode, freezing all keyboard input. This was temporarily worked around by using async execution, but v4.3.0 resolved the underlying compliance issue with skill enforcement.

Sources: RELEASE-NOTES.md25-27 RELEASE-NOTES.md47-49 hooks/hooks.json10

Bootstrap Content Preparation

Diagram: Bootstrap Content Preparation Pipeline

Sources: hooks/session-start.sh11-35

JSON Escaping Implementation

The escape_for_json function hooks/session-start.sh23-31 must handle large content (the entire using-superpowers skill) efficiently:

Implementation (Optimized in v4.2.0):

Performance characteristics:

• Uses bash parameter substitution (${s//old/new})
• Each pattern is a single C-level pass
• 7x faster than character-by-character loop on macOS
• Dramatically faster on Windows Git Bash (60+ seconds → ~8 seconds for large content)

Previous O(n²) implementation (removed in v4.2.0):

Sources: hooks/session-start.sh23-31 RELEASE-NOTES.md51-53

Context Injection Format

The hook outputs JSON with two shapes for cross-platform compatibility:

Platform usage:

• Cursor: Reads additional_context
• Claude Code: Reads hookSpecificOutput.additionalContext
• Both shapes included for maximum compatibility

Session context structure:

<EXTREMELY_IMPORTANT>
You have superpowers.

**Below is the full content of your 'superpowers:using-superpowers' 
skill - your introduction to using skills. For all other skills, 
use the 'Skill' tool:**

[Full using-superpowers SKILL.md content]

[Optional legacy warning if ~/.config/superpowers/skills exists]
</EXTREMELY_IMPORTANT>

The <EXTREMELY_IMPORTANT> wrapper signals critical bootstrap information. The explicit statement "For all other skills, use the 'Skill' tool" prevents agents from trying to read skill files directly instead of using the platform's skill tool.

Sources: hooks/session-start.sh35-49 RELEASE-NOTES.md176-183

Session Lifecycle Sequence

Diagram: Complete Session Lifecycle Sequence

Key timing constraints:

1. Hook must complete before agent processes first user message
2. No gap between bootstrap injection and first turn
3. Agent has full skill protocol when evaluating first request

Sources: hooks/session-start.sh1-51 hooks/hooks.json1-16

Legacy Skills Directory Warning

The hook checks for the deprecated ~/.config/superpowers/skills directory hooks/session-start.sh12-15:

Historical context: Prior to v4.0.0, Superpowers maintained a separate skills repository at ~/.config/superpowers/skills. Since v4.0.0, skills are embedded in the plugin repository at ${CLAUDE_PLUGIN_ROOT}/skills/.

Warning content:

• Tells user that custom skills in the old location won't be read
• Instructs to move custom skills to ~/.claude/skills/ (platform's native location)
• Provides clear removal instructions

This prevents confusion when users upgrade from very old versions (v3.x) that used the separate repository structure.

Sources: hooks/session-start.sh11-15 RELEASE-NOTES.md557-567

Cross-Platform Execution

Current Implementation (Claude Code 2.1.x+)

hooks.json calls session-start.sh directly hooks/hooks.json9:

Platform behavior:

• Unix/macOS: Executes .sh file directly (has shebang #!/usr/bin/env bash)
• Windows: Claude Code 2.1.x auto-detects .sh extension and prepends bash command

Historical: Polyglot Wrapper (Deprecated)

Prior to Claude Code 2.1.x, a polyglot run-hook.cmd wrapper provided cross-platform compatibility hooks/run-hook.cmd1-44 This file was both a valid Windows CMD script and a bash script.

Why deprecated: Claude Code 2.1.x changed hook execution on Windows to auto-detect .sh files. The command bash "run-hook.cmd" session-start.sh attempted to execute the .cmd file as a bash script, causing failures.

Current approach is simpler:

• Single .sh file with Unix shebang
• Platform handles execution wrapper automatically
• No polyglot complexity needed

Git Bash Dependency (Windows)

On Windows, the .sh file executes via Git Bash (typically C:\Program Files\Git\bin\bash.exe). This is automatically handled by Claude Code's hook execution system.

Sources: hooks/run-hook.cmd1-44 RELEASE-NOTES.md41-46 RELEASE-NOTES.md137-141

Plugin Root Resolution

The script determines its location using BASH_SOURCE fallback hooks/session-start.sh7-8:

Why the fallback: ${BASH_SOURCE[0]:-$0} handles environments where BASH_SOURCE is unbound. In Claude Code's hook execution context, BASH_SOURCE may not be set, so $0 provides the script path.

Path resolution:

1. Get directory containing the script (hooks/)
2. Navigate up one level to plugin root
3. Use absolute path for reliability

This resolved a v2.0.1 bug where hooks failed silently with "Plugin hook error" when BASH_SOURCE was unbound.

Sources: hooks/session-start.sh7-8 RELEASE-NOTES.md542-547

Error Handling

The script uses set -euo pipefail hooks/session-start.sh4 for strict error handling:

Flags:

• -e: Exit on first error
• -u: Treat unset variables as errors
• -o pipefail: Propagate errors through pipes

Fallback for skill reading hooks/session-start.sh18:

If the skill file is missing or unreadable, the error message is captured and included in the bootstrap context rather than causing hook failure.

Sources: hooks/session-start.sh4 hooks/session-start.sh18

Bootstrap Content Structure

The injected context has three components:

1. Header

<EXTREMELY_IMPORTANT>
You have superpowers.

**Below is the full content of your 'superpowers:using-superpowers' 
skill - your introduction to using skills. For all other skills, 
use the 'Skill' tool:**

Establishes that:

• The skill content follows (agent doesn't need to load it)
• Other skills should be loaded via the Skill tool
• This is critical foundational information

2. Skill Content

Full markdown content of skills/using-superpowers/SKILL.md, including:

• The Rule (mandatory skill checking)
• Mandatory First Response Protocol
• Skill priority system
• Tool mapping guidance
• Red flags and rationalizations table

3. Optional Legacy Warning

<important-reminder>
IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:
⚠️ **WARNING:** Superpowers now uses Claude Code's skills system...
</important-reminder>

Only included if ~/.config/superpowers/skills directory exists.

Sources: hooks/session-start.sh33-35

Integration with Skill System

After bootstrap completes, the agent has:

1. Full using-superpowers content - Already loaded, no tool invocation needed
2. Mandatory protocol awareness - Must check for skills before responding
3. Tool mapping knowledge - Knows how to use platform-specific skill tools
4. Priority system understanding - Project > personal > superpowers

The agent then uses the Skill tool (see Tool Mapping Layer) to load other skills as needed.

Sources: hooks/session-start.sh35