Skip to content

session-start-loader.sh

SessionStart — re-orientation context after compact/resume; injects the task from session.txt into context and shows the user a boxed status report at startup.

Source: .claude/hooks/session-start-loader.sh, wired in .claude/settings.json.

#!/bin/bash
# Session start hook for swarm context loading
# Loads project context and swarm state

INPUT=$(cat)

# jq is required to parse tool input past this point. Rather than failing
# silently when it's missing (hooks are guardrails, not a security boundary
# — but a silent gap is worse than a visible one), surface exactly what
# degrades so the current session knows what it can't rely on.
if ! command -v jq >/dev/null 2>&1; then
    cat << 'EOF'

[HOOK DEGRADATION]
jq is not installed — the following guardrails are degraded for this session:
- Secret detection & file-lock coordination (pre-tool-use-validator.sh): skipped entirely
- Dangerous-command warnings (dangerous-command-guard.sh): skipped entirely
- Commit quality gate (pre-commit-verification.sh): skipped entirely — commits are not gate-blocked
- Task-completion quality gate (task-quality-gate.sh): skipped entirely
Unaffected: pre-push-main-blocker.sh's branch-block does not depend on jq and
keeps working either way; permissions.deny (.claude/settings.json) is
enforced at the permission layer regardless of jq or any hook.
Install jq to restore full hook coverage.
EOF
    exit 0
fi

SOURCE=$(echo "$INPUT" | jq -r '.source // "startup"' 2>/dev/null || echo "startup")
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || true)

PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
STATE_DIR="$PROJECT_DIR/.claude/hooks/.state"
LOCK_DIR="$PROJECT_DIR/.claude/hooks/.locks"
mkdir -p "$STATE_DIR" "$LOCK_DIR" 2>/dev/null || true

# Clean up session files older than 24 hours
find "$STATE_DIR" -name "session_*.json" -type f -mtime +1 -delete 2>/dev/null || true

# Clean stale locks (>5 min old)
if [ -d "$LOCK_DIR" ]; then
    find "$LOCK_DIR" -name "*.lock" -mmin +5 -delete 2>/dev/null || true
fi

# Initialize session tracking
SESSION_SHORT=$(echo "$SESSION_ID" | cut -c1-8)
echo "{\"session_id\": \"$SESSION_ID\", \"started\": \"$(date -Iseconds)\", \"source\": \"$SOURCE\"}" > "$STATE_DIR/session_$SESSION_SHORT.json"

# Build context message
CONTEXT=""

# Post-compaction / resume re-orientation: on "compact", prior context was
# just summarized away; on "resume", this is picking up a session from
# scratch. Either way, don't trust what's already "known" — re-check state
# before continuing (see debugging-protocol.md's Stale Context Check).
if [ "$SOURCE" = "compact" ] || [ "$SOURCE" = "resume" ]; then
    CONTEXT="$CONTEXT

[POST-COMPACTION RE-ORIENTATION]
- Check the native task list for in-flight work before starting anything new
- If a plan artifact is active (docs/plans/plan-*.md), re-read it before continuing
- Re-read any file before editing it — do not trust memory of its contents (Stale Context Check, .claude/rules/debugging-protocol.md)"
fi

# Check for active swarm agents
ACTIVE_AGENTS=$(find "$STATE_DIR" -maxdepth 1 -name 'session_*.json' -type f 2>/dev/null | wc -l | tr -d ' ')
if [ "$ACTIVE_AGENTS" -gt 1 ]; then
    CONTEXT="$CONTEXT

[SWARM STATUS]
- Active agents in project: $ACTIVE_AGENTS
- Coordinate via the task tracker to avoid conflicts
- Check file locks before major edits"
fi

# Check for pending work from previous sessions
if [ -f "$STATE_DIR/handoff.json" ]; then
    HANDOFF=$(cat "$STATE_DIR/handoff.json" 2>/dev/null || true)
    HANDOFF_MSG=$(echo "$HANDOFF" | jq -r '.message // empty' 2>/dev/null || true)
    if [ -n "$HANDOFF_MSG" ]; then
        CONTEXT="$CONTEXT

[HANDOFF FROM PREVIOUS SESSION]
$HANDOFF_MSG"
        # Clear handoff after reading
        rm -f "$STATE_DIR/handoff.json"
    fi
fi

# Current task from session.txt (.claude/rules/session-file.md); /task-resume continues it.
# The model gets the raw file as context; the user gets a status report on screen
# (systemMessage) right at startup, before typing anything.
REPORT=""
SESSION_FILE="$PROJECT_DIR/session.txt"
if [ -s "$SESSION_FILE" ]; then
    field() { sed -n "s/^$1:[[:space:]]*//p" "$SESSION_FILE" | head -1 | tr -d '\r'; }
    # Cut to 70 characters (UTF-8 aware) so every table row stays one line
    cut70() { local LC_ALL=C.UTF-8 v=$1; [ ${#v} -gt 70 ] && v="${v:0:69}…"; printf '%s' "$v"; }
    # First ";"-item of a field
    short() { local v; v=$(field "$1"); cut70 "${v%%;*}"; }
    TASK_STATUS=$(field status)
    if [ "$TASK_STATUS" = "done" ]; then
        ICON="✅"
        TITLE="Task gần nhất (session.txt)"
        HINT="Đã xong · gõ yêu cầu mới để bắt đầu task khác"
        NOTE="- Last task is done. The user already saw it in a status report from this hook; do not resume it."
    else
        ICON="📌"
        TITLE="Task đang dở (session.txt)"
        HINT="▶ /task-resume để làm tiếp"
        NOTE="- Unfinished task from a previous session. The user already saw a status report from this hook; in your first reply, if the user did not run /task-resume, add one line reminding them that /task-resume continues it. Continue only if they run /task-resume or ask to."
    fi
    CONTEXT="$CONTEXT

[CURRENT TASK — session.txt]
$(head -c 2000 "$SESSION_FILE" | tr -d '\r')
$NOTE
- Keep session.txt current while working (.claude/rules/session-file.md)."

    if [ "$SOURCE" != "compact" ]; then
        PROGRESS=$(field progress | tr -cd '0-9')
        PROGRESS=${PROGRESS:-0}
        [ "$PROGRESS" -gt 100 ] && PROGRESS=100
        FILLED=$((PROGRESS / 10))
        BAR="$(printf '%*s' "$FILLED" '' | sed 's/ /█/g')$(printf '%*s' $((10 - FILLED)) '' | sed 's/ /░/g')"
        # Two-column table: label | value. "sep" rows become ├──┼──┤ lines between groups.
        LC_ALL=C.UTF-8
        LABELS=() VALUES=() COMMITS=() SEP=0
        row() {
            [ "$SEP" = 1 ] && [ ${#LABELS[@]} -gt 0 ] && { LABELS+=("sep"); VALUES+=(""); COMMITS+=(""); }
            SEP=0; LABELS+=("$1"); VALUES+=("$2"); COMMITS+=("${3:-}")
        }
        # One row per ";"-item of a field (at most 8); the label shows on the first row only.
        # A trailing commit hash ("... 6a0a5849" or "... (6a0a5849)") moves to its own column.
        rows() {
            local label=$2 n=0 it commit
            while IFS= read -r it; do
                it="${it#"${it%%[![:space:]]*}"}"; it="${it%"${it##*[![:space:]]}"}"
                [ -z "$it" ] || [ "$it" = "-" ] && continue
                commit=""
                if [[ $it =~ ^(.*[^[:space:]])[[:space:]]+\(?([0-9a-f]{7,40})\)?$ ]]; then
                    it=${BASH_REMATCH[1]}; commit=${BASH_REMATCH[2]:0:8}
                fi
                n=$((n + 1)); [ $n -le 8 ] && { row "$label" "$(cut70 "$it")" "$commit"; label=""; }
            done < <(field "$1" | tr ';' '\n')
            [ $n -gt 8 ] && row "" "… +$((n - 8)) more"
        }
        row "$ICON Task" "$(short task)"
        row "Status" "${TASK_STATUS:-?} · [$BAR] $PROGRESS% · $(field updated)"
        SEP=1; rows done "✅ Done"
        SEP=1; rows doing "🔄 Doing"
        SEP=1
        BLOCKER=$(short blocker); [ -n "$BLOCKER" ] && row "⛔ Blocked" "$BLOCKER"
        NEXT=$(short next)
        [ "$TASK_STATUS" != "done" ] && [ -n "$NEXT" ] && [ "$NEXT" != "-" ] && row "→ Next" "$NEXT"

        # Display width: these emoji take 2 terminal columns, everything else 1
        # (counted per emoji: Git Bash sees 📌/🔄 as two UTF-16 units, so ${#s} alone is off)
        dw() {
            local s=$1 e r n=0
            for e in ✅ 🔄 ⛔ 📌; do
                r=${s//"$e"/}; n=$(( n + (${#s} - ${#r}) / ${#e} )); s=$r
            done
            echo $(( ${#s} + 2 * n ))
        }
        pad() { printf '%s%*s' "$1" $(( $2 - $(dw "$1") )) ''; }
        line() { printf '%*s' $(($1 + 2)) '' | sed 's/ /─/g'; }
        # hr <left> <mid> <right>; the commit column is drawn only when some row has a commit
        hr() {
            printf '%s%s%s%s' "$1" "$(line $LW)" "$2" "$(line $VW)"
            [ "$CW" -gt 0 ] && printf '%s%s' "$2" "$(line $CW)"
            printf '%s\n' "$3"
        }
        LW=0 VW=0 CW=0
        for i in "${!LABELS[@]}"; do
            [ "${LABELS[$i]}" = "sep" ] && continue
            w=$(dw "${LABELS[$i]}"); [ "$w" -gt "$LW" ] && LW=$w
            w=$(dw "${VALUES[$i]}"); [ "$w" -gt "$VW" ] && VW=$w
            w=${#COMMITS[$i]}; [ "$w" -gt "$CW" ] && CW=$w
        done
        # The UI prefixes the first line with "SessionStart:startup says: ", so the
        # table starts on line two, under a title line that absorbs the prefix.
        REPORT=$(
            printf '%s\n' "$TITLE"
            hr "┌" "┬" "┐"
            for i in "${!LABELS[@]}"; do
                if [ "${LABELS[$i]}" = "sep" ]; then hr "├" "┼" "┤"; continue; fi
                printf '│ %s │ %s │' "$(pad "${LABELS[$i]}" "$LW")" "$(pad "${VALUES[$i]}" "$VW")"
                [ "$CW" -gt 0 ] && printf ' %s │' "$(pad "${COMMITS[$i]}" "$CW")"
                printf '\n'
            done
            hr "└" "┴" "┘"
            printf '%s' "$HINT"
        )
    fi
fi

# Output: JSON when there is a report for the user, plain text (context only) otherwise
if [ -n "$REPORT" ]; then
    jq -n --arg msg "$REPORT" --arg ctx "$CONTEXT" \
        '{systemMessage: $msg, hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}'
elif [ -n "$CONTEXT" ]; then
    echo "$CONTEXT"
fi

exit 0