architect/standards/HOOKS_SESSION.md

Стандарт: хуки и запуск сессий

Версия: 1.0
Дата: 2026-03-25

Проблема

Claude Code загружает settings.json из ближайшей папки .claude/ относительно текущей рабочей директории (CWD).

Если claude --resume запускается не из /opt/claude-workspace, то:
- .claude/settings.json не находится
- Хуки SessionStart не срабатывают
- CLAUDE.md не инжектируется в контекст сессии
- Claude не знает правил, режимов, протоколов

Симптом: инструкции работают при старте новой сессии, но теряются при resume.

Правило

Любой скрипт, запускающий claude или claude --resume, обязан сначала выполнить cd /opt/claude-workspace.

# ПРАВИЛЬНО
WORKSPACE="/opt/claude-workspace"
cd "$WORKSPACE"
claude --resume "$session_id"

# НЕПРАВИЛЬНО — хук не сработает если CWD != workspace
claude --resume "$session_id"

Как работает цепочка

session (bash) → cd /opt/claude-workspace
                      ↓
              claude --resume SESSION_ID
                      ↓
              Ищет .claude/settings.json
              → находит /opt/claude-workspace/.claude/settings.json
                      ↓
              Запускает хуки из settings.json:
              SessionStart → session-setup.sh
                      ↓
              session-setup.sh читает CLAUDE.md
              → возвращает additionalContext
                      ↓
              Claude получает все инструкции ✅

Скрипты запуска (должны содержать cd)

Скрипт cd workspace Статус
/usr/local/bin/start ✅ cd "$WORKSPACE" OK
/usr/local/bin/session ✅ cd "$WORKSPACE" OK (добавлено 2026-03-25)
/usr/local/bin/master ✅ cd $WORKSPACE (tmux) OK

При добавлении нового скрипта запуска — обязательно добавить:

WORKSPACE="/opt/claude-workspace"
cd "$WORKSPACE"

Хук SessionStart

Файл: .claude/hooks/session-setup.sh
Регистрация: .claude/settings.json

"hooks": {
    "SessionStart": [{
        "hooks": [{
            "type": "command",
            "command": "/opt/claude-workspace/.claude/hooks/session-setup.sh",
            "timeout": 15
        }]
    }]
}

Хук срабатывает при:
- Запуске новой сессии (source: startup)
- Возобновлении сессии (source: resume)
- После сжатия контекста /compact (source: compact)

Проверка что хук работает: в CLAUDE.md есть маркер ## 🔴 SESSION HOOK TEST — Claude должен ответить HOOK OK в начале первого сообщения.

Диагностика если хук не работает

# 1. Проверить что hook существует
ls -la /opt/claude-workspace/.claude/hooks/session-setup.sh

# 2. Проверить регистрацию в settings.json
cat /opt/claude-workspace/.claude/settings.json | python3 -m json.tool | grep -A10 hooks

# 3. Запустить hook вручную
echo '{"source":"resume"}' | bash /opt/claude-workspace/.claude/hooks/session-setup.sh | head -5

# 4. Проверить CWD скрипта запуска
grep -n "cd.*workspace\|WORKSPACE" /usr/local/bin/session /usr/local/bin/start

История изменений

Дата Событие
2026-02-17 Создан хук session-setup.sh, зарегистрирован в settings.json
2026-03-25 Диагностирована причина: session не делал cd workspace. Починено.