Claude Code v2.1.248: 제한 모드 & 캐시 TTL

Claude Code v2.1.248에는 새로운 제한 실행 모드, 에이전트별 캐시 TTL 구성, 그리고 프롬프트 캐싱 및 세션 관리를 위한 일련의 안정성 수정 사항이 포함되어 출시되었습니다.

제한 모드

이제 --restricted 플래그(또는 CLAUDE_CODE_RESTRICTED=1 환경 변수)로 Claude Code를 실행할 수 있습니다. 이 모드는 명령어나 코드를 실행하는 모든 내장 도구와 WebFetch를 제거합니다(단, --tools에 명시적으로 포함된 경우는 제외). 파일 작업은 작업 디렉토리 내에서만 이루어지며, bypassPermissions는 거부되고, 사용자/프로젝트/로컬 설정 파일은 무시됩니다. 이는 신뢰할 수 없는 코드 검토나 CI 환경에서 유용합니다.

에이전트별 캐시 TTL

이제 에이전트 프론트매터에서 experimental.cacheTtl을 통해 프롬프트 캐시 TTL을 설정할 수 있습니다: "5m" 또는 "1h" 형식입니다. 이는 서브에이전트 TTL이 설정되지 않은 경우 적용되며, 특정 에이전트에 대한 캐시 만료를 더 세밀하게 제어할 수 있습니다.

자체 호스트 러너 및 설정 진단

claude self-hosted-runner 명령에 --client-label 플래그(또는 SELF_HOSTED_RUNNER_CLIENT_LABEL 환경 변수)가 추가되어 기본 라벨(호스트 이름)을 재정의할 수 있습니다. 시작 시 서버 관리 설정 로드에 실패하면 경고가 표시되며, /doctor 및 /status에서 실패 이유를 설명합니다. 또한, /usage-credits를 통해 Enterprise 구성원이 관리자에게 더 높은 한도를 요청할 수 있습니다(AWS Marketplace, 셀프 서비스, 평가판).

세션 간 메시징

같은 머신에서 세션 간 메시징을 위한 SendMessage 및 ListAgents가 추가되었으며, 이제 Bedrock, Vertex, Foundry 및 원격 측정이 비활성화된 경우에도 지원됩니다.

주요 수정 사항

프롬프트 캐시 누락: 장기 세션(약 1시간 간격)에서 OAuth 새로 고침 후 도구 재렌더링으로 인한 누락이 수정되었습니다.
ScheduleWakeup 도구 정의가 초과 시 변경되어 --resume 시 캐시 누락이 발생하던 문제가 수정되었습니다.
데스크톱/동료 세션이 30일 후 사라지던 문제가 수정되었습니다. 새로운 desktopSessionCleanupPeriodDays 설정으로 예외 기간을 제한할 수 있습니다.
로그인 루프: 다른 프로세스가 토큰 새로 고침 잠금을 보유할 때 발생하던 문제가 재시도 가능한 오류를 반환하도록 수정되었습니다.
Windows: 에이전트 목록이 분리 후 또는 win32 입력 모드에서 키보드 응답이 되도록 수정되었습니다.
/login: ANTHROPIC_API_KEY가 설정된 경우 OAuth 실패 대신 API 키 로그인으로 대체됩니다.
/model의 모델 이름이 코드로 렌더링됩니다(예: [1m] 리터럴).
CI가 설정된 경우 에이전트가 작업 공간 신뢰 프롬프트를 건너뛰던 문제가 수정되어 이제 표시됩니다.
에이전트 보기가 더 이상 오래된 백그라운드 세션을 부활시키지 않으며, 중지된 세션은 중지된 것으로 표시됩니다.
재개된 세션에서 중복 프로세스가 실행되는 것을 방지했습니다.
병합되었지만 푸시되지 않은 브랜치가 있는 세션 삭제를 허용했습니다.
잘못된 후크 응답에 대해 후크 이름과 스키마 오류를 표시하도록 수정했습니다.
후크에서의 잘못된 JSON이 텍스트로 조용히 처리되지 않고 오류로 보고됩니다.
/mcp가 실제 범위 아래에 커넥터 항목을 나열하고, headersHelper가 있는 MCP 서버는 OAuth 폴백 대신 401 시 헬퍼를 다시 실행합니다.