claudekit / updates / claude-code-2-1-248
[ PATCH · ]

Claude Code 2.1.248

The new `--restricted` flag (or `CLAUDE_CODE_RESTRICTED=1`) removes the built-in tools that run commands or code and `WebFetch`, keeps file tools inside the working directory, refuses `bypassPermissions`, and ignores user, project and local settings files. A prompt-cache miss that hit long sessions roughly once an hour — tool definitions being re-rendered after an OAuth token refresh, which also lost extended-thinking context — is fixed, and agent frontmatter gains `experimental.cacheTtl` for a per-agent prompt cache TTL. Claude Desktop and Cowork sessions no longer disappear after 30 days, `claude agents` stops resurrecting weeks-old background sessions or starting a second process on a conversation already open elsewhere, and `/ultrareview` and locally seeded cloud sessions no longer upload uncommitted `prod.env`-style files, `*.tfvars`, or editor swap, temp and backup copies of credential files.

Claude Code
Official announcement →

This article is a summary based on official documentation.

What changed

Claude Code 2.1.248 shipped on August 27, 2026. It adds --restricted, a mode that strips the tools which execute anything and refuses to let settings files widen that back out, and it tracks down the hourly prompt-cache miss that had been quietly costing long sessions their extended-thinking context. The agent view and claude agents get a round of fixes — resurrected sessions, duplicate processes, refused deletes — and credential-file copies stop leaving your machine with cloud sessions.

New features

  • --restricted mode

    Narrowing what Claude Code can do meant assembling permission rules yourself, and a settings file could widen them again. --restricted (or CLAUDE_CODE_RESTRICTED=1) removes the built-in tools that run commands or code and WebFetch (unless named in --tools), keeps file tools inside the working directory, refuses bypassPermissions, and ignores user, project and local settings files.

  • experimental.cacheTtl in agent frontmatter

    Prompt cache TTL for subagents could only be set globally. Agent frontmatter now takes experimental.cacheTtl ("5m" or "1h"), used as a per-agent prompt cache TTL when no subagent TTL setting is configured.

  • Server-managed settings diagnostics

    When server-managed settings didn’t apply, nothing said so. There is now a startup warning when the settings fail to load, plus a /doctor and /status line explaining a load failure or why they weren’t fetched (Bedrock/Vertex/third-party provider, custom ANTHROPIC_BASE_URL).

  • Cross-session messaging on Bedrock, Vertex, and Foundry

    Messaging another session on the same machine wasn’t available in some setups. SendMessage and ListAgents now work between sessions on the same machine on Bedrock, Vertex, and Foundry, and when telemetry is disabled.

  • /usage-credits for more Enterprise organizations

    Members of Enterprise organizations billed through AWS Marketplace, self-serve Enterprise, and Enterprise trials had no path to ask for more headroom. /usage-credits now works for them, so they can request a higher usage limit from their admin.

  • A label for self-hosted runners

    A self-hosted runner registered under its hostname, which made several of them hard to tell apart. claude self-hosted-runner --client-label <label> (or SELF_HOSTED_RUNNER_CLIENT_LABEL) overrides the label the runner registers with.

  • GitHub token scope warning in /web-setup

    Pushes to very large repositories can be rejected when the GitHub CLI token lacks the workflow scope, and setup gave no hint of it. /web-setup now warns about the missing scope.

Key improvements

  • A smaller prompt footprint for the Workflow tool

    The Workflow tool’s description took about 5.7k tokens in every session, used or not. It is now about 1k tokens, with the script-writing reference moved into a bundled workflow-authoring skill.

  • /ultrareview <PR#> checks access before launch

    A repository access problem only surfaced after the cloud session had started. It now checks before launch that the GitHub account connected to your Claude account can access the repository, and explains how to fix it.

  • Fewer PR badge checks

    The prompt-footer PR badge checked GitHub often even while the pull request was unchanged. It now checks less often in that case; a push or a gh pr command still refreshes it right away.

  • Fewer managed settings approval prompts

    Client-side timeout, MCP startup-mode, and stream-watchdog env vars triggered the settings-approval prompt. They no longer do.

  • A fallback directory for cross-session messaging

    Cross-session messaging failed outright when the default directory couldn’t be used. It now falls back to a private per-user /tmp directory, and the notice and /status name the directory to fix.

  • Agent view dispatch input keys match the prompt

    shift+enter behaved differently in the agent view dispatch input than in the prompt. shift+enter now inserts a newline, and ctrl+enter dispatches and attaches.

  • /loop is always available

    Self-paced dynamic mode and the no-prompt autonomous default were limited in some setups. Both are now always available, including on Bedrock, Vertex, and Foundry.

  • Telemetry export failures are labeled clearly

    Anthropic telemetry export failures logged as [3P telemetry] OTEL diag error, which read like your own OTel collector failing. They now log at debug level as [Anthropic telemetry].

  • SendMessage from a subagent says where the reply goes

    A subagent messaging another session had no way to know where a reply would land. The result now notes that any reply is delivered to the parent session’s conversation, not to the subagent.

Bug fixes

Prompt cache & session continuity

  • A prompt-cache miss (and lost extended-thinking context) roughly once an hour in long sessions — fixed; tool definitions were being re-rendered after an OAuth token refresh.
  • The ScheduleWakeup tool definition changing between a session and its --resume when the account had entered usage overage, causing a full prompt-cache miss on the resumed session’s first turn — fixed.
  • Claude Desktop and Cowork sessions disappearing after 30 days — transcript cleanup now keeps desktop-written sessions while they are in the app (unless org policy manages retention), and the new desktopSessionCleanupPeriodDays setting caps the exemption.
  • Being sent to the login screen when another Claude Code process held the token refresh lock while the session token had expired — the request now fails with a retryable error instead.

Agent view & background sessions

  • Agent view resurrecting a weeks-old background session after the machine was off — such a session now shows as stopped at its real end, and opening it asks before resuming its saved conversation.
  • claude agents starting a second process on a conversation you already resumed in another terminal — the row now says it is open in a terminal.
  • Agent view sometimes opening an older conversation, and dropping the typed prompt, when starting a new session — fixed.
  • claude agents and claude rm refusing to delete a session (“has commits that are not pushed anywhere”) when its worktree branch was already merged into your checked-out default branch (e.g. local main) but not yet pushed — fixed.
  • A backgrounded worktree session losing its checkout — the background session now holds the worktree’s lock while it runs, so cleanup and git worktree remove leave it alone.
  • Background sessions waiting silently when a PermissionRequest or PreToolUse hook prints an invalid answer — the claude agents row now names the hook and the schema error.
  • Hooks silently treating a stdout {…} object that isn’t valid JSON as plain text — it’s now reported as a hook error with the parse message.
  • [Windows] The claude agents list not responding to the keyboard after detaching from a session, or when launched in a terminal tab left in win32-input-mode — fixed.
  • claude agents skipping the workspace trust prompt when the CI environment variable is set — fixed.
  • claude agents crashing on launch when the PR-status cache held a malformed entry — fixed.

Sign-in, MCP & settings

  • The recommended Console sign-in in /login failing with an OAuth error before showing a sign-in URL on machines where it can’t be used (for example when ANTHROPIC_API_KEY or an API key helper is set) — it now falls back to the API-key sign-in.
  • /login to a Claude apps gateway hanging when the managed-settings security approval dialog was required — fixed.
  • Gateway model discovery (CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY) never running when apiKeyHelper is the only credential — fixed.
  • /mcp listing a project .mcp.json entry that declares the claude.ai connector type under the trusted “claude.ai” heading — it now appears under its real scope.
  • MCP servers whose headersHelper supplies the Authorization header falling into OAuth discovery on a 401 instead of re-running the helper and retrying the call as documented — fixed.
  • An invalid crossSessionInbound value being silently ignored — it now warns and holds cross-session messages (user settings) or refuses them (managed settings) until fixed.

Remote & cloud sessions

  • /ultrareview and locally seeded cloud sessions uploading uncommitted edits to prod.env-style and *.tfvars files, or to editor swap, temp, and backup copies of credential files (e.g. key.pem.tmp, id_rsa.swo) — they now stay on your machine.
  • Remote Control sessions occasionally never showing a permission prompt or the latest messages on the connected device after the CLI silently reconnected — fixed.
  • Cloud sessions occasionally failing at startup when the container’s session credentials were not yet readable — fixed.
  • claude remote-control rejecting its own flags (e.g. --spawn, --name) when a global flag or a wrapper-injected option precedes the subcommand — fixed.

Terminal & display

  • @-mentions of other sessions not matching names typed with non-Latin characters (for example Korean entered through an IME) — fixed.
  • claude logs leaving mouse tracking, bracketed paste and the alternate screen switched on in the terminal it was run from — fixed.
  • Model names in /model and fast-mode switch notices not rendering as code, so suffixes like [1m] displayed as a link — fixed; they display literally.
  • The trust dialog’s list of repo permission rules showing a garbled character when a long rule was cut off in the middle of an emoji — fixed.
  • The permission mode indicator staying hidden behind the “Press Ctrl-C again to exit” hint when you press shift+tab right after ctrl+c — fixed.
  • Startup warnings (e.g. “N MCP servers need authentication”) rendering one column right of the rest of the transcript — fixed.
  • Rate-limit, usage, and fast-mode messages telling you to run /usage-credits when that command isn’t available for your organization (e.g. hidden with DISABLE_EXTRA_USAGE_COMMAND) — fixed.
  • [VSCode] A chat tab getting stuck on “No conversation found” when its session was never saved — it now starts a new conversation instead.

Notes

  • --restricted ignores settings files too — beyond removing execution tools, it skips user, project and local settings files and refuses bypassPermissions, so work that relies on your usual settings behaves differently under it.
  • Desktop session retention changed — sessions written by Claude Desktop and Cowork are exempt from the 30-day transcript cleanup while they are in the app. desktopSessionCleanupPeriodDays caps that exemption, and org policy managing retention takes precedence.
  • Credential-file copies stay local — /ultrareview and locally seeded cloud sessions no longer upload prod.env-style files, *.tfvars, or editor swap, temp and backup copies such as key.pem.tmp and id_rsa.swo.
  • shift+enter changed in the agent view — it now inserts a newline; use ctrl+enter to dispatch and attach.
  • The Workflow script reference moved — how to write a workflow script now lives in the bundled workflow-authoring skill rather than in the tool description.
  • An invalid crossSessionInbound value no longer passes silently — cross-session messages are held (user settings) or refused (managed settings) until the value is fixed.