에이전트 훅

st hooks install — Claude Code, Codex, Gemini CLI, opencode, Pi, Kimi Code, Qwen Code가 무엇을 하고 있는지 st가 알게 하는 한 번의 설정.

st는 터미널을 공유하지, 그 안에서 무엇이 실행되는지는 모릅니다. 훅을 걸면 알게 됩니다 — 에이전트가 일하는 중인지, 권한을 기다리는지, 끝났는지. 그래야 폰이 "지금 뭘 기다리고 있다"를 말해 줄 수 있습니다.

st hooks install      # 걸기, 또는 최신으로 고치기
st hooks install gemini   # 이름을 댄 에이전트만: claude, codex, gemini, opencode, pi, kimi, qwen
st hooks status       # 지금 어떤지
st hooks uninstall    # 되돌리기
st hooks auto off     # 알아서 고치지 않게

앱에서도 설치할 수 있습니다. 장치 화면의 ⚠ 훅을 눌러 st와 에이전트 훅을 열고 훅 설치를 누르거나, 훅 없이 에이전트가 실행 중인 터미널 위에 뜨는 띠에서 설치를 누릅니다.

바꾸는 파일

st hooks install만 실행하면 이 장치에 설치된 에이전트 가운데 훅을 걸 수 있는 것에 모두 겁니다. 설치되지 않은 에이전트는 건너뜁니다. st hooks status는 찾기는 했지만 st가 아직 훅을 걸지 못하는 에이전트(GitHub Copilot CLI, Aider, goose)도 그 이유와 함께 보여 줍니다.

Claude Code에서 듣는 이벤트는 열네 개입니다: UserPromptSubmit, Stop, StopFailure, PermissionRequest, Notification, SubagentStart, SubagentStop, SessionStart, SessionEnd, TeammateIdle, TaskCreated, TaskCompleted, PreToolUse, PostToolUse. Gemini CLI에서는 일곱 개입니다: SessionStart, BeforeAgent, AfterAgent, Notification, SessionEnd, BeforeTool, AfterTool.

설정에 들어가는 것

직접 넣어도 됩니다. 명령어가 하는 일이 이게 전부입니다.

~/.claude/settings.json의 hooks 아래, 이벤트 열네 개마다 같은 모양으로:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "/opt/homebrew/bin/st hook claude --hv 2", "timeout": 10 }
        ]
      }
    ]
  }
}

command의 경로는 st가 실제로 있는 자리입니다. PATH의 st가 지금 실행 중인 바로 그 바이너리면 그 경로를 쓰고, 아니면 이 실행 파일의 경로를 씁니다. 공백이 있으면 따옴표를 붙입니다.

Gemini CLI의 ~/.gemini/settings.json도 같은 모양입니다. 명령은 st hook gemini --hv 1이고, 타임아웃은 밀리초 단위(10000)로 적습니다.

Codex는 ~/.codex/hooks.json의 훅을 신뢰한 뒤에만 실행합니다. 그래서 st가 훅마다 신뢰 정보를 ~/.codex/config.toml에 함께 적습니다. Codex의 /hooks에서 직접 승인할 때 적히는 것과 같은 내용입니다. 이 부분은 손으로 쓰기보다 명령에 맡기는 편이 쉽습니다. notify 줄도 ~/.codex/config.toml의 최상위에 들어갑니다:

notify = ["/opt/homebrew/bin/st", "hook", "codex"]

Codex가 이미 자기 notify를 쓰고 있으면 그 줄은 건드리지 않습니다. 알림 프로그램은 하나뿐이라 덮어쓰면 원래 것이 사라집니다. 그럴 때는 Codex already has a notify program; left alone이라고 알리고, hooks.json의 훅은 그대로 넣습니다. Codex가 없는 장치에서도 그냥 넘어갑니다.

고칠 파일이 있으면 먼저 사본을 남깁니다:

~/.claude/settings.json.st-backup-20260928-200347

여러 번 실행해도 됩니다. 이미 맞게 되어 있으면 already as it should be라고만 합니다.

버전과 최신으로 유지하기

st가 설치하는 훅 묶음에는 버전이 있습니다. Claude Code 명령 끝의 --hv 2입니다. 이벤트나 명령이 바뀔 때마다 올라갑니다. Codex의 묶음은 버전 3입니다(st 0.3.92 이상). Windows에서 버전 2 명령은 모든 훅에서 실패했기 때문에, PowerShell이 실행할 수 있게 명령을 적습니다. st hooks status가 에이전트마다 상태를 알려 줍니다.

st hooks install은 제자리에서 고칩니다. st 항목만 바꾸고(같은 이벤트에 두 번째로 있는 st 항목, st가 더는 듣지 않는 이벤트의 st 항목은 지움) 먼저 파일을 백업합니다. 직접 넣은 훅은 그대로입니다.

한 번 st 훅을 설치한 장치에서는 st가 훅을 최신으로 유지합니다. st가 시작할 때(업데이트 뒤에는 새 버전의 첫 시작) 오래된 묶음을 같은 방식으로 백업하고 고친 뒤 로그와 하루 동안 st ls에 알립니다. 사용자가 이벤트를 뺀 묶음은 손대지 않습니다. 끄려면:

st hooks auto off     # 다시 켜려면 st hooks auto on

또는 앱에서 장치 화면의 ⋯ 메뉴로 st와 에이전트 훅을 열고 에이전트 훅 자동 업데이트를 끕니다. 버전이 생기기 전의 st(v0.3.53 이하)도 이 훅을 문제없이 실행하지만 자기 것으로 알아보지는 못합니다.

보내는 항목

훅이 실행하는 st hook은 같은 장치의 st 에이전트에게 짧은 이벤트 하나를 보내고 끝납니다. 에이전트는 그걸 앱이 보여 주는 상태와 프롬프트로 바꾸고 그걸 담은 알림은 폰마다 그 폰의 키로 암호화됩니다.

보내는 것은 고정된 목록입니다 — 이벤트 이름, 세션 id, 알림 종류와 제목과 메시지, 도구 이름, 도구에 시킨 일(권한이 필요한 명령, 파일 경로, 계획), 서브에이전트의 id와 종류, 에이전트가 시작한 서브에이전트에 붙인 짧은 설명(80자, 맡긴 일 자체는 아님), Claude Code가 에이전트 팀을 두는 위치, 작업 제목, 오류 종류, Codex에서는 마지막 답.

대화 기록도, 프롬프트 내용도 보내지 않습니다. 도구에 시킨 일은 4000바이트에서, 나머지 항목은 500바이트에서 잘립니다.

st hook은 에이전트를 기다리게 하지 않고 아무것도 출력하지 않으며 언제나 0으로 끝납니다. PermissionRequest, PreToolUse, PostToolUse는 보기만 하고 아무 답도 하지 않습니다. 결정은 터미널의 몫입니다.

적용 시점

설치한 뒤에 시작한 세션부터입니다. 지금 실행 중인 Claude Code는 시작할 때 읽은 설정으로 계속 갑니다.

되돌리기

st hooks uninstall

st가 쓴 훅만 지웁니다. 그것 때문에 비게 된 그룹과 이벤트도 같이 지우고 직접 넣은 다른 훅은 그대로 둡니다. Codex의 notify도 st가 넣은 것일 때만 지웁니다.