Claude Code v2.1.248: Restricted Mode & Cache TTL

Claude Code v2.1.248 shipped with a new restricted execution mode, per-agent cache TTL configuration, and a batch of stability fixes for prompt caching and session management.

Restricted Mode

You can now run Claude Code with --restricted (or set CLAUDE_CODE_RESTRICTED=1). This removes all built-in tools that execute commands or code, plus WebFetch unless explicitly named in --tools. File operations stay inside the working directory, bypassPermissions is refused, and user/project/local settings files are ignored. This is useful for untrusted code reviews or CI environments.

Cache TTL Per Agent

You can now set a prompt-cache TTL in agent frontmatter via experimental.cacheTtl: "5m" or "1h". This applies when no subagent TTL is configured, giving you finer control over cache expiration for specific agents.

Self-Hosted Runner and Settings Diagnostics

The claude self-hosted-runner command gains a --client-label flag (or SELF_HOSTED_RUNNER_CLIENT_LABEL) to override the default label (hostname). Startup now warns if server-managed settings fail to load, and /doctor and /status explain the failure reason. Also, /usage-credits lets Enterprise members request higher limits from admins (AWS Marketplace, self-serve, trials).

Cross-Session Messaging

Added SendMessage and ListAgents for cross-session messaging on the same machine, now supported on Bedrock, Vertex, Foundry, and when telemetry is disabled.

Key Fixes

Prompt-cache misses in long sessions (roughly hourly) caused by tool re-rendering after OAuth refresh — fixed.
ScheduleWakeup tool definition changing on overage, causing cache misses on --resume — fixed.
Desktop/Cowork sessions disappearing after 30 days — fixed; new desktopSessionCleanupPeriodDays setting caps the exemption.
Login loop when another process held the token refresh lock — now returns a retryable error.
Windows: agents list now responds to keyboard after detaching or in win32-input-mode.
/login with ANTHROPIC_API_KEY set falls back to API-key sign-in instead of failing with OAuth.
Model names in /model render as code (e.g., [1m] literal).
Agents skip workspace trust prompt when CI is set — fixed to show it.
Agent view no longer resurrects stale background sessions; stopped sessions show as stopped.
Duplicate processes on resumed sessions — prevented.
Deletion of sessions with merged-but-unpushed branches — allowed.
Invalid hook answers now show hook name and schema error.
Invalid JSON from hooks reported as errors, not silently treated as text.
/mcp lists connector entries under actual scope, and MCP servers with headersHelper re-run helper on 401 instead of OAuth fallback.