Claude Code 2.1.248 adds --restricted mode and cache TTL controls

Anthropic shipped Claude Code 2.1.248 on August 27, 2026, and the change operators will actually wire into jobs is a least-privilege launch switch. --restricted, or CLAUDE_CODE_RESTRICTED=1, removes the built-in tools that run commands or code and drops WebFetch unless those tools are named in --tools. File tools remain, but only inside the working directory. The mode refuses bypassPermissions and ignores user, project, and local settings files.

That is the practical control for unattended runs and untrusted trees. Permission modes already trade convenience against oversight—Manual (default) when you want to review every action, dontAsk when CI should see only a pre-approved allowlist, bypassPermissions when you are inside an isolated container or VM and intend to skip checks. None of those modes, by themselves, yank exec and fetch tools off the session, pin file access to the working directory, and refuse to load settings a cloned repo might have planted. Restricted mode does all three at launch.

A launch posture, not another permission cycle

Start a session with --restricted and Claude Code no longer offers the built-in command and code runners. WebFetch is gone unless you put it back by name in --tools. Whatever file tools remain cannot wander outside the working directory. bypassPermissions is refused, so a wrapper, a flag, or a settings file cannot quietly skip every check. User, project, and local settings files are ignored, which cuts off a common path for a repository to redefine permissions, hooks, or MCP servers before anyone has reviewed them.

The v2.1.248 GitHub notes and the official changelog describe the same behavior. The permission-modes documentation still frames bypassPermissions as a skip-all-checks posture meant for isolated containers and VMs only. Restricted mode will not take that posture.

This is not a sandbox and not a container. It is a launch posture: fewer tools, a tighter filesystem scope, no settings from the tree, and no way to opt into bypass. For CI jobs and checkouts you do not yet trust, that is the difference between hoping the default permission mode is conservative enough and knowing the dangerous tools are not loaded. Pair it with whatever isolation your runner already provides; do not treat the flag as a substitute for a boundary.

Per-agent cache TTL, and fewer hourly misses

The same drop adds experimental.cacheTtl to agent frontmatter. The documented values are "5m" and "1h". The field sets a per-agent prompt cache TTL, used when no subagent TTL setting is configured. If you already set a subagent TTL, this frontmatter field is not the one that wins.

Long sessions also pick up two cache bugs that were expensive in the wrong way. Tool definitions were being re-rendered after an OAuth token refresh, which caused a prompt-cache miss—and lost extended-thinking context—roughly once an hour. A separate miss hit --resume when the ScheduleWakeup tool definition changed after the account entered usage overage, wiping the cache on the resumed session’s first turn. Both are fixed in 2.1.248.

Runners, Bedrock, Vertex, Foundry, and credits

Self-hosted runner registration can override the label the runner registers with. Pass claude self-hosted-runner --client-label <label>, or set SELF_HOSTED_RUNNER_CLIENT_LABEL. The default remains the hostname.

Cross-session messaging (SendMessage / ListAgents) between sessions on the same machine now works on Bedrock, Vertex, and Foundry, and when telemetry is disabled. That closes a gap for teams who run Claude Code against those providers rather than a first-party Anthropic path. Related changes in the same release: /loop’s self-paced dynamic mode and the no-prompt autonomous default are now always available, including on Bedrock, Vertex, and Foundry. SendMessage from a subagent to another session now notes that any reply is delivered to the parent session’s conversation, not to the subagent.

Enterprise members billed through AWS Marketplace, self-serve Enterprise, and Enterprise trials get /usage-credits, so they can request a higher usage limit from their admin. Rate-limit, usage, and fast-mode messages that told people to run /usage-credits when the command is not available for their organization—for example when it is hidden with DISABLE_EXTRA_USAGE_COMMAND—are fixed.

Server-managed settings get diagnostics: a startup warning when settings fail to load, and a /doctor and /status line explaining a load failure or why they were not fetched (Bedrock, Vertex, a third-party provider, or a custom ANTHROPIC_BASE_URL). /web-setup now warns when the GitHub CLI token lacks the workflow scope, because pushes to very large repositories can be rejected without it.

Fixes that sit next to the security story

The rest of 2.1.248 is a large fix list. A few items belong in the same conversation as --restricted.

/ultrareview and locally seeded cloud sessions no longer upload uncommitted edits to prod.env-style and *.tfvars files, or to editor swap, temp, and backup copies of credential files such as key.pem.tmp and id_rsa.swo; those stay on the machine. claude agents no longer skips the workspace trust prompt when the CI environment variable is set. An invalid crossSessionInbound value is no longer silently ignored: the client warns and holds cross-session messages under user settings, or refuses them under managed settings, until the value is fixed.

On Linux user namespaces, root-equivalent trust for unmapped owners in cross-session messaging is now limited to canonical system directories. Messaging also falls back to a private per-user /tmp directory when the default one cannot be used, and the notice plus /status name the directory to fix.

The Workflow tool’s prompt footprint shrank: its description is now about 1k tokens instead of 5.7k, with the script-writing reference moved into a bundled workflow-authoring skill.

If you run Claude Code in CI or against untrusted checkouts, install 2.1.248, confirm it with claude --version, and read the permission-modes page next to the changelog before you put --restricted on a job. Then dry-run a throwaway clone and verify that command tools, WebFetch, and local settings are actually gone.