0007. plan 훅은 Belloga 앱 안의 터미널에서 시작된 세션에만 안내를 넣는다

• 상태: 채택
• 날짜: 2026-09-26
• 관련: planHookScript.ts, pty.ts

맥락

plan 훅은 세션을 시작할 때 plan 위치와 작성 규칙을 Claude Code에 알린다. 훅은 Claude Code의 전역 설정에 등록되므로, 처음에는 Belloga 밖의 터미널이나 다른 앱에서 켠 세션에도 같은 안내가 들어가게 했다.

그런데 Belloga 밖에서 작업하는 사용자는 그 순간 Belloga를 하네스로 쓰고 있지 않다. 그런 세션에도 Belloga 위치를 권하면, 사용자가 따로 쓰는 하네스의 규칙과 저장 위치가 부딪혀 Claude가 매번 어디에 쓸지 묻게 된다.

결정

plan 훅은 BELLOGA_PANE_ID 환경 변수가 있는 세션에만 안내를 넣는다. Belloga는 앱 안의 터미널을 열 때 이 값을 늘 넣고, Claude Code와 그 훅은 터미널의 환경을 물려받는다. 값이 없으면 훅은 아무것도 내보내지 않고 끝난다.

근거 / 검토한 대안

• 어디서 켰든 안내한다(이전 동작). 다른 앱에서 한 작업의 plan도 Belloga 위치에 쌓여, 나중에 Belloga를 열면 배지로 보인다. 그러나 Belloga를 쓰지 않는 순간에도 Belloga 규칙을 들이밀어 다른 하네스와 충돌한다.
• 설정에 “Belloga 밖의 터미널에도 안내” 토글을 둔다. 두 쓰임새를 모두 받는다. 그러나 설정 화면과 저장 항목이 늘고, 지금은 앱 밖에서도 안내받기를 원하는 쓰임새가 확인되지 않아 미뤘다.
• 기준 값으로 BELLOGA_HOOK_PORT나 BELLOGA_HOOK_TOKEN을 쓴다. 포트는 앱의 훅 서버가 뜨지 못하면 빈 값이 되어, 앱 안의 터미널인데도 안내가 빠질 수 있다. BELLOGA_PANE_ID는 터미널을 열 때마다 늘 들어가고 세션 상태 훅도 같은 값을 기준으로 쓴다.

결과

• Belloga 훅은 plan 훅과 세션 상태 훅 모두 Belloga 앱 안의 터미널에서만 동작한다.
• 다른 앱에서 한 작업의 plan은 Belloga 위치에 쌓이지 않으므로, 그 작업은 Belloga의 plan 배지에 나타나지 않는다.
• Belloga 터미널에서 다른 앱을 띄우면(예: code .) 그 앱의 세션도 환경을 물려받아 안내를 받는다. 이 경우는 막지 않는다.
• 앱 밖에서도 안내받고 싶다는 요구가 생기면 토글을 다시 검토한다. 그때는 이 기록을 대체하는 새 기록을 쓴다.