한국시간 8월 28일 아침에 나온 클로드 코드 v2.1.248이, 긴 세션에서 OAuth 토큰이 갱신될 때 도구 정의가 다시 만들어져 프롬프트 캐시가 한 시간에 한 번꼴로 통째로 날아가고 확장 사고(extended thinking) 맥락까지 잃던 문제를 고쳤어요 — v2.1.242부터 생긴 promptCacheTtl 로 캐시 유지 시간을 1시간으로 올려 뒀어도 이 경로에서는 매시간 전체 입력을 처음부터 다시 계산하고 있었던 셈이에요. 같은 판에 에이전트 파일 프론트매터로 experimental.cacheTtl(5m·1h)이 들어와 서브에이전트 캐시 시간을 에이전트마다 다르게 줄 수 있게 됐는데, 릴리스 노트엔 '서브에이전트 TTL 설정이 없을 때 쓰인다'고 적혀 있어 subagentPromptCacheTtl 을 이미 걸어 뒀으면 이 칸은 무시돼요. 공식 문서의 서브에이전트 프론트매터 표(지원 필드 16개)와 캐시 우선순위 목록(다섯 단계) 어디에도 이 칸은 아직 없어요.
- 프롬프트 캐시
- 매 요청에서 되풀이되는 앞부분을 서버가 기억해 뒀다가 싸게 다시 읽는 기능. 앞부분이 한 군데라도 바뀌면 그 뒤가 전부 다시 계산된다
- OAuth
- 비밀번호를 직접 넘기지 않고 발급받은 토큰으로 로그인 상태를 유지하는 인증 방식. 토큰은 만료 전에 자동으로 새로 발급된다
- 프론트매터
- 파일 맨 앞에 --- 로 감싸 적는 설정 블록. 클로드 코드는 에이전트 정의 파일의 이 자리에 이름·모델·도구 같은 값을 적는다
- experimental.cacheTtl
- v2.1.248에 들어온 에이전트별 프롬프트 캐시 유지 시간 값. 5m 또는 1h 만 받고, 아직 공식 문서에는 없다
- subagentPromptCacheTtl
- 서브에이전트·워크플로·대화 압축처럼 본 대화 밖에서 나가는 요청의 캐시 유지 시간을 정하는 설정. 본 대화 쪽은 promptCacheTtl
긴 세션을 오래 붙들고 일한다면 이 판올림은 미룰 자리가 아니에요 — 한 시간마다 전체 입력을 다시 계산하던 게 그대로 값이자 첫 응답 대기 시간이었거든요. 서브에이전트 캐시를 손볼 거면 순서를 헷갈리지 마세요: 에이전트마다 다르게 주려면 subagentPromptCacheTtl 을 비워 둬야 프론트매터 값이 먹히고, 전역 설정을 걸어 두면 에이전트별 값은 안 걸려요. 아직 experimental 이 붙은 미문서 설정이라 다음 판에 이름이 바뀔 수 있고요.
- 공식 문서가 적어 둔 기본값과 우선순위 구독 한도 안에서도 서브에이전트·워크플로·대화 압축은 5분이 기본이라고 표에 적혀 있고, 캐시 시간을 고르는 우선순위는 다섯 단계인데 그 목록 어디에도 에이전트 프론트매터 자리가 없어요. promptCacheTtl·subagentPromptCacheTtl 은 v2.1.242 이상이 필요하다고 못 박혀 있고요. Claude Code Docs
- 프론트매터 표에 아직 없는 칸 서브에이전트 문서의 '지원 프론트매터 필드' 표에는 name·description·tools·model·effort 등 16개가 적혀 있는데 캐시 시간을 정하는 칸은 없어요 — 지금은 릴리스 노트가 유일한 근거예요. Claude Code Docs
- 이틀째 걸려 있던 워크트리 삭제 건 이번 노트에 '백그라운드 세션이 도는 동안 워크트리 잠금을 쥐어서 정리 작업과 git worktree remove 가 그 워크트리를 건드리지 않는다'가 들어왔어요. 다만 8월 20일에 올라온 원 신고는 댓글 0개로 그날 이후 손대진 적이 없고 아직 열린 채이며, 노트가 짚은 범위도 '백그라운드 세션'이라 앞에서 돌리는 세션까지 닫혔는지는 확인되지 않았어요. GitHub
- 같은 판에 들어온 --restricted 가 실제로 막는 것 공식 CLI 문서는 '평가 하네스가 공용 기계에서 claude 를 돌릴 때' 쓰라고 적어 뒀어요. 명령·코드를 실행하는 내장 도구와 WebFetch 를 빼고(--tools 로 하나씩 이름을 대야만 살아나요), 파일 도구를 작업 디렉토리 안으로 가두고, 관리 설정과 --settings 만 읽고 사용자·프로젝트·로컬 설정 파일은 무시하며, bypassPermissions 를 거부해요. v2.1.248 이상이 필요하다고 적혀 있고요. Claude Code Docs