DEV Community: aicoding-guide

Gemini CLI v0.62: gemini-3.8-flash and gemini-3.5-flash-lite added

aicoding-guide — Thu, 01 Oct 2026 19:15:51 +0000

Originally published at https://aicoding-guide.com.

Gemini CLI v0.62.0 is mostly fixes with one model addition in the middle of them.

The thing to know: gemini-3.8-flash and gemini-3.5-flash-lite are now available. Alongside that, a fix retains the OAuth refresh token on refresh, and several fixes land on Windows shell execution.

One caveat about the source: the v0.62.0 release notes are a list of PR titles with no per-change descriptions. This article sticks to what the PR and the official configuration reference confirm, and says so where confirmation wasn't possible.

Key point
What you will learn

The two new model IDs and which tier each leads

Setting a model with model.name in settings.json

The OAuth, Windows and proxy fixes in this release

The two new models

PR #29443 adds both as the latest GA release in their respective tiers.

Model ID	Tier	Position
`gemini-3.8-flash`	flash	Latest GA in the Flash tier
`gemini-3.5-flash-lite`	flash-lite	Latest GA in the Flash Lite tier

The same PR promotes gemini-3.5-flash and gemini-3.1-flash-lite to base tier, with the two new models established as the "latest" alternatives. Existing model selections don't disappear — they move within the hierarchy.

Both IDs are also confirmable in the official configuration reference as of October 1, 2026: gemini-3.8-flash appears among the modelConfigs aliases, and gemini-3.5-flash-lite among the model definitions.

Whether you can pick them depends on your auth type
Per the PR description, access is gated behind the LATEST_FLASH_GA_LAUNCHED and LATEST_FLASH_LITE_GA_LAUNCHED experiment flags, with immediate access for non-experiment auth types such as USE_GEMINI, USE_VERTEX_AI and GATEWAY. That gating mechanism could not be confirmed in the official documentation. If the models don't show up for you, a staged rollout is the likely reason.

Setting the model in settings.json

Per the configuration reference, the model used for conversations is set with model.name.

{
  "model": {
    "name": "gemini-3.8-flash"
  }
}

The model object documents these keys:

Key	Default	What the reference says
`model.name`	unset	The Gemini model to use for conversations
`model.maxSessionTurns`	`-1`	Maximum user/model/tool turns to keep in a session; `-1` means unlimited
`model.compressionThreshold`	`0.5`	The fraction of context usage at which to trigger context compression

Settings files load in this order, each overriding the one before it:

System defaults: /etc/gemini-cli/system-defaults.json on Linux, C:\ProgramData\gemini-cli\system-defaults.json on Windows, /Library/Application Support/GeminiCli/system-defaults.json on macOS
User settings: ~/.gemini/settings.json
Project settings: .gemini/settings.json
System overrides: /etc/gemini-cli/settings.json, or the OS equivalent

For finer control, modelConfigs holds aliases — "named presets for model configs" that can inherit from one another with extends — and modelDefinitions, which carries each model's metadata: tier (flash-lite, flash, pro, custom), family (gemini-3, gemini-2.5, gemma-4, auto), isPreview, and features.

For the project context file, see Setting up GEMINI.md in Gemini CLI.

Authentication and login persistence

Two authentication fixes are in the list:

"retain oauth refresh token on refresh and make credential deletion idempotent" (#29339)
"update auth error documentation link to valid anchor and add fallback" (#29377)

The first reads as closing a path where the refresh token was lost during a token refresh. It coincides with reports since v0.60.0 of sandboxed sessions not keeping login state, but the release notes carry no description, so whether those reports are resolved could not be confirmed. If you are re-authenticating on every launch, v0.62.0 is worth trying first.

On the MCP side, "format MCP tool call titles as structured signatures and segregate explanations" (#29341) changes how tool calls are presented.

Windows, proxy and the rest

The remaining fixes concern the execution environment.

Area	What the PR title says
PTY	Improve file descriptor cleanup and execution lifecycle management (#29340)
ConPTY (Windows)	Synchronize process exit lifecycle and harden PTY output finalization (#29379)
Terminal	Improve terminal buffer memory management and format Windows diagnostic paths (#29380)
Proxy	Normalize proxy-agent esbuild interop for environment proxy resolution (#29401)
VS Code companion	Preserve terminal focus when closing diff tabs (#29378)
ACP mode	Emit `tool_call` update prior to `request_permission` (#29439)
UI	Guard against negative layout dimensions in border rendering (#29347)
Logs	Suppress uncaught AbortError logs during request cancellation (#29343)

If shell command execution has been unreliable on Windows, the three PTY and ConPTY fixes are the ones to look at; if you couldn't connect through a proxy, #29401 is yours. For all of them, the release notes give no description, so exactly which symptoms clear could not be confirmed.

Summary

The headline in v0.62.0 is gemini-3.8-flash and gemini-3.5-flash-lite, both confirmable in the official configuration reference
gemini-3.5-flash and gemini-3.1-flash-lite move to base tier, with the new pair as the latest
Set the model with model.name in settings.json; user settings live at ~/.gemini/settings.json
A fix retains the OAuth refresh token on refresh — worth taking if your login keeps dropping
If the new models don't appear, a staged rollout is the likely cause, though that mechanism isn't in the official docs

Codex CLI v0.158: MCP OAuth client secrets and approval for elevated commands

aicoding-guide — Wed, 30 Sep 2026 19:10:03 +0000

Originally published at https://aicoding-guide.com.

Codex CLI v0.158.0 lands changes that touch MCP, the sandbox and approvals — the parts you notice in daily use.

Two items matter most: terminal input approval is now on by default for commands running with elevated permissions, and Codex can now connect to MCP servers that require pre-registered OAuth client secrets.

This article works from the v0.158.0 release notes as the primary source, covering what affects your configuration, and then what followed in v0.159.0 and v0.159.2.

Key point
What you will learn

Approval becoming the default for elevated commands

MCP OAuth client secret support, and where the configuration reference has not caught up

The sandbox fixes on Windows, Linux and macOS

Approvals: a changed default

From the v0.158.0 New Features:

Terminal input approval is enabled by default for commands running with elevated permissions; runtime-only grants no longer cause unnecessary reviews.

If you run commands with administrator or otherwise elevated permissions, expect an approval where there was none before. In the other direction, grants given only for the duration of a run should stop triggering repeat reviews.

Two related fixes ship alongside it:

"Approved commands retain explicit filesystem denials" (v0.159.0 Bug Fixes)
"Approval reviews now retry when new user input arrives, so a status question does not automatically abort a pending action" (v0.158.0 Bug Fixes)

For how approval policies and the sandbox combine, see Codex approval modes and sandbox.

MCP: OAuth client secrets

From the New Features:

Connect to MCP servers that require pre-registered OAuth client secrets, including through codex mcp add --oauth-client-secret.

Servers that do not support Dynamic Client Registration make you register an OAuth app in their developer portal and take a client ID and secret back. Until now there was no way to hand Codex that secret, so those servers were out of reach.

This flag is not in the configuration reference yet
--oauth-client-secret appears in the v0.158.0 release notes, but it was not in the official configuration reference as of September 30, 2026. The OAuth keys that page does document for an MCP server are oauth.client_id, oauth.callback_port and oauth.callback_url, and it says nothing about where a client secret is stored. Treat the flag name and behavior as a release-note claim.

What the reference does document today stops at the client ID and the callback:

[mcp_servers.example]
url = "https://mcp.example.com/mcp"

[mcp_servers.example.oauth]
client_id = "your-client-id"
callback_port = 8080

The same release also secures direct exec-server WebSocket connections with bearer tokens, including connections configured through app-server.

Sandbox fixes

Three of the Bug Fixes concern the sandbox, split across platforms.

Platform	What the release notes say
Windows	Sandbox failures involving ordinary Windows 10 paths, rejected stored credentials, and large permission policies
Linux	Sandbox startup with nested writable roots
Linux and macOS	Git metadata protections preserved across writable roots
macOS	Patch operations now recognize system path aliases covered by existing permissions, avoiding unnecessary approval prompts

If you configure several writable roots, a nested arrangement failed to start on Linux before this release. Configuration is covered in Extending where Codex can write with writable_roots.

v0.159.0 widens the protection further: .aws directories are "protected by default under writable roots". That said, which directories are protected by default inside a writable root could not be confirmed on the official sandboxing page — read it as a release-note claim.

TUI changes, and what followed in v0.159

v0.158.0 makes copy-on-select and right-click paste configurable in the fullscreen TUI, and copied transcript selections keep their Markdown formatting. Mermaid flowcharts render quoted labels and ampersands, and unsupported diagrams explain why they fall back to source.

The v0.159.0 New Features:

Opt-in instant_interrupt, letting new input steer Codex during model responses or long-running code-mode calls
A compact welcome screen for new sessions, with consistent headers
The warnings viewer dismisses reviewed warnings when closed; press k to keep one
You can scroll the transcript while deciding whether to implement a plan
Native Mermaid rendering covers more flowchart edges, labels and node groups

instant_interrupt also was not in the configuration reference as of September 30, 2026, so where it goes and what value it takes are unconfirmed. For the file's structure generally, see Configuring Codex with config.toml.

v0.159.2 is a Windows-only patch with a single fix: console windows no longer flash when Codex launches background processes and sandboxed commands.

Summary

v0.158.0 turns on terminal input approval by default for commands running with elevated permissions
Codex can now reach MCP servers that require pre-registered OAuth client secrets (codex mcp add --oauth-client-secret)
Sandbox fixes land on Windows, Linux and macOS; Linux nested writable roots start correctly from v0.158.0
v0.159.0 adds opt-in instant_interrupt and TUI work; v0.159.2 is the Windows console-window fix alone
--oauth-client-secret and instant_interrupt were both absent from the configuration reference on September 30, 2026

Auto-approve MCP tools in Claude Code permissions: the mcp__ syntax and its wildcard limits

aicoding-guide — Tue, 29 Sep 2026 19:20:36 +0000

Originally published at https://aicoding-guide.com.

Add an MCP server and Claude Code asks for approval every time one of its tools runs. Stopping for a read-only lookup on every call gets old fast.

In short: put mcp__<server> in permissions.allow to auto-approve every tool from that server, or mcp__<server>__<tool> for one tool. The catch is that an allow wildcard requires a literal mcp__<server>__ prefix — a pattern like mcp__* is skipped entirely.

For registering the servers themselves, see Adding MCP servers to Claude Code.

Key point
What you will learn

The three rule shapes: whole server, wildcard, single tool

Why allow wildcards need an anchor, and how deny and ask differ

That mcp__ rules with parentheses are silently skipped from settings files

The three rule shapes

The docs put it this way: MCP rules use the server name as configured in Claude Code, optionally followed by the name of a tool from that server.

Rule	What it matches
`mcp__puppeteer`	Any tool provided by the `puppeteer` server
`mcp__puppeteer__*`	The same set, written as a wildcard
`mcp__puppeteer__puppeteer_navigate`	Only the `puppeteer_navigate` tool from that server

In settings.json:

{
  "permissions": {
    "allow": [
      "mcp__puppeteer",
      "mcp__github__get_issue",
      "mcp__github__list_pull_requests"
    ]
  }
}

The server name is whatever you passed to claude mcp add, or the key in .mcp.json. The separator is two underscores, both between mcp and the server and between the server and the tool.

Glossary
Server name: the name you chose in claude mcp add <name> .... Rename the server and every rule for it changes too, so when a team shares .claude/settings.json, agree on the names in .mcp.json first.

Allow wildcards need an anchor

This is the part that catches people. The docs state that allow rules accept tool-name globs only after a literal mcp__<server>__ prefix, and that the server segment must be glob-free so the rule names a specific server you configured.

Pattern	Result in `allow`
`mcp__puppeteer__*`	Works. Matches every tool from `puppeteer`
`mcp__github__get_*`	Works. Matches that server's `get_` tools
`mcp__*`	Skipped with a warning; auto-approves nothing
`` / `B`	Skipped, same as above

So there is no way to say "allow all MCP tools" in one allow rule. List each server.

{
  "permissions": {
    "allow": [
      "mcp__puppeteer__*",
      "mcp__github__get_*",
      "mcp__linear__*"
    ]
  }
}

Deny and ask follow different rules

Deny and ask rules do accept globs in the tool-name position. The pattern must match the full tool name: "*" matches every tool, and "mcp__*" matches every MCP tool across all servers.

{
  "permissions": {
    "deny": [
      "mcp__*"
    ]
  }
}

Rules are evaluated in order: deny, then ask, then allow. The first match in that order determines the outcome, and rule specificity doesn't change it. A broad deny wins over a narrower allow, and an allow rule can't carve an exception out of a deny.

Goal	Where and what
Allow a server's tools wholesale	`allow`: `mcp__<server>`
Block one dangerous tool	`deny`: `mcp__<server>__<tool>`
Block all MCP tools	`deny`: `mcp__*`
Prompt every time	`ask`: any of the same patterns

A deny rule that names a bare tool removes the tool from Claude's context, so Claude never sees it. A scoped rule leaves the tool available and blocks matching calls when Claude attempts them.

One thing to watch: a deny or ask rule whose tool name matches no known tool normally produces a startup warning to catch typos, but tool names containing _ or * are exempt from that check. Every mcp__ name qualifies, so a misspelled server name fails silently.

Where rules live, and what gets ignored

Write rules in settings.json and inspect them with /permissions. The dialog lists every rule and the settings.json file it came from. You can open it while Claude is working: adding or removing a rule applies from Claude's next tool call in the same turn (v2.1.234 or later). For the files and their precedence, see Configuring permissions in Claude Code's settings.json, and for driving the dialog, The /permissions command.

mcp__ rules with parentheses are skipped
The Bash(npm run build) style of narrowing by argument does not work for MCP tools. When Claude Code loads a settings file, it skips any mcp__ rule that has parentheses. Skipped rules are listed in the invalid-settings dialog when an interactive session starts, and in claude doctor output. To match a parameter on an MCP tool, pass a deny rule with --disallowedTools instead.

There is a second case where an allow rule has no effect. If your organization has set a claude.ai connector tool to ask and that setting reaches your session, allow rules for that tool don't apply: Claude Code prompts on every call, even in auto and bypassPermissions modes. In dontAsk mode, which never prompts, it denies the call instead. Tools from connectors Claude Code fetches itself appear as mcp__claude_ai_<server>__<tool>.

Summary

allow takes mcp__<server> for a whole server and mcp__<server>__<tool> for one tool
An allow wildcard only works after mcp__<server>__; mcp__* and * are skipped with a warning
Deny and ask accept full tool-name globs, so deny: ["mcp__*"] blocks every MCP tool
Evaluation is deny → ask → allow, first match wins, regardless of specificity
Parenthesised mcp__ rules are skipped from settings files; use --disallowedTools to match a parameter

Sign in to a remote MCP server in Claude Code: /mcp and claude mcp login

aicoding-guide — Sun, 27 Sep 2026 19:21:56 +0000

Originally published at https://aicoding-guide.com.

Hosted MCP servers like Sentry, Linear and Notion are not usable the moment you register their URL. They need a browser sign-in first, and claude mcp list shows them as ! Needs authentication until you do it.

In short: add the server with claude mcp add --transport http <name> <url>, then either run /mcp in a session and choose Authenticate on that server, or run claude mcp login <name> from your shell. Tokens are stored securely and refreshed automatically.

This article is part of a series. For every way to register a server, see Adding MCP servers to Claude Code.

Key point
What you will learn

The two ways to sign in: /mcp and claude mcp login

--callback-port for a fixed redirect URI, and how to pass a pre-registered client ID

What to do when a token expires or the browser never opens

Add the server and sign in from /mcp

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Right after adding, claude mcp list shows ! Needs authentication. That is expected; the sign-in clears it.

Start a session, run /mcp, select the server from the list, press Enter and choose Authenticate. Your browser opens the service's sign-in page, where you approve the connection. Back in Claude Code the server's status changes to connected.

Claude Code marks a remote server as needing authentication when it answers with 401 Unauthorized or 403 Forbidden. There is also a startup notice listing servers that need sign-in, so you do not have to open /mcp to find them (v2.1.193 or later).

Glossary
Dynamic Client Registration: an OAuth mechanism where the client registers itself with the authorization server instead of you registering an app by hand. When a server supports it, passing the URL to claude mcp add is all the setup the sign-in needs.

Sign in from the command line

To sign in without opening a session, use claude mcp login.

claude mcp login sentry

To clear stored credentials later, run claude mcp logout <name>.

Over SSH, or on Linux without a display server, the command detects that no local browser is available and prints the authorization URL rather than trying to open one. Open that URL on your own machine, then paste the full redirect URL from the address bar back at the prompt. The paste step needs an interactive terminal, so connect with ssh -t. Pass --no-browser to force the URL prompt even when a browser is detected.

claude mcp login sentry --no-browser

Non-interactive runs (claude -p, the Agent SDK) have no /mcp panel, so Claude Code cannot run the OAuth flow there. As of v2.1.196, with tool search enabled, it tells Claude that the server's tools are unavailable until you authorize it, so Claude can name the server instead of acting as though it were not configured. Do the sign-in itself from an interactive session or with claude mcp login.

Use pre-registered OAuth credentials

If a server does not support Dynamic Client Registration, you get an error such as "Incompatible auth server: does not support dynamic client registration". Register an OAuth app through the service's developer portal and pass the credentials yourself.

Servers that require a registered redirect URI expect the form http://localhost:PORT/callback. Pick a port, register it, and pass the same port to --callback-port: by default Claude Code picks a random free port, which will never match.

Flag / key	What it does
`--callback-port <port>`	Fixes the callback port. Usable on its own
`--client-id <id>`	The client ID of your registered OAuth app
`--client-secret`	Prompts for the secret with masked input
`MCP_CLIENT_SECRET`	Supplies the secret through the environment, skipping the prompt

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

In JSON, the same settings live in an oauth object. The secret stays out of the JSON and is passed with the separate --client-secret flag.

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

oauth also takes scopes, which pins the scopes requested during authorization (a single space-separated string, matching RFC 6749), and authServerMetadataUrl, which overrides metadata discovery.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes takes precedence over authServerMetadataUrl and over whatever the server advertises at /.well-known. If the authorization server advertises offline_access, Claude Code appends it so the token can be refreshed without another browser sign-in.

The secret can only be set when you add the server
The client secret is stored in your system keychain (macOS) or a credentials file, never in your config. You can set it only at add time: when you authenticate with claude mcp login or from /mcp, Claude Code uses the stored secret and neither prompts for one nor reads MCP_CLIENT_SECRET. To change it, run claude mcp remove <name> and add the server again with --client-secret and the same --scope. Use claude mcp get <name> to check whether credentials are configured.

Which file each scope writes to is covered in claude mcp add scopes: local, project and user, and passing a static token through a header in Passing tokens from environment variables in .mcp.json.

When sign-in expires or fails

When a request to a server you already signed in to returns 401, Claude Code refreshes the stored token, reconnects and retries the request once. It flags the server in /mcp only if that retry also fails.

When the server rejects the stored refresh token, a notice pointing at /mcp appears immediately. Open /mcp and choose Re-authenticate on that server.

Symptom	What to do
The browser does not open	Copy the URL shown in the terminal and open it manually
The redirect fails with a connection error after you authenticate	Paste the full callback URL from the address bar into the URL prompt Claude Code shows
A server with a configured `Authorization` header returns 401 or 403	It will not fall back to OAuth; the connection is reported as failed. Check the token, or remove the header
A tool call fails with 403 `insufficient_scope`	Add the scope the server names to `oauth.scopes`, then authenticate again from `/mcp`

That last row catches people out: Claude Code requests the scopes you pinned, not the scope the server asked for, so signing in again without adding it gives you a token that still lacks it.

One gap worth naming: the on-disk location of OAuth access and refresh tokens could not be confirmed in the official documentation. It says only that tokens are "stored securely and refreshed automatically", and names the keychain or a credentials file for the client secret alone.

Summary

Add with claude mcp add --transport http <name> <url>, then sign in from /mcp → Authenticate or with claude mcp login <name>
Revoke with claude mcp logout <name> or "Clear authentication" in the /mcp menu
On a headless box, claude mcp login --no-browser prints the URL and takes the redirect URL back
Without Dynamic Client Registration, use --client-id and --callback-port, plus --client-secret if the app has one
A rejected refresh token means Re-authenticate in /mcp; a missing scope means editing oauth.scopes first

This week in Claude Code, Codex and Gemini CLI (week of September 27, 2026)

aicoding-guide — Sat, 26 Sep 2026 19:13:54 +0000

Originally published at https://aicoding-guide.com.

The headline this week: Claude Opus 5.5 (claude-opus-5-5) is now Claude Code's default Opus model (v2.1.280). The official pricing table lists it at $4/MTok input and $20/MTok output, below Claude Opus 5's $5/$25.

On the permissions side, the same release fixed writes through a symlinked path being approved against the wrong location. On the settings side, "attribution": false became a valid shorthand, and auto mode's classifier moved to the server.

Covered here: Claude Code 2.1.278 and 2.1.280 through 2.1.283, Codex CLI 0.156.1 and 0.157.0, and Gemini CLI 0.61.0.

Key point
What you will learn

Claude Opus 5.5's model ID and the prices you can verify in the official table

The symlink write fix and what changed in auto mode

Codex adding GPT-6 Sol and Luna, and Gemini CLI 0.61.0's security fixes

Claude Code

2.1.280: Claude Opus 5.5 becomes the default Opus model

The changelog reads: "Added Claude Opus 5.5 (claude-opus-5-5), now the default Opus model — 1M context, $4/$20 per Mtok with $0.20/Mtok cache reads". The official pricing page lists the same numbers.

Item	Claude Opus 5.5	Claude Opus 5
Model ID	`claude-opus-5-5`	`claude-opus-5`
Input	$4 / MTok	$5 / MTok
Output	$20 / MTok	$25 / MTok
Cache reads	$0.20 / MTok	$0.50 / MTok
5-minute cache writes	$5 / MTok	$6.25 / MTok

The pricing page notes that cache hits on Opus 5.5 cost 0.05x the base input price, where most other models use the standard 0.1x multiplier. The longer your sessions run, the more that gap matters.

Because it is now the default Opus model, a setup that simply selects opus in /model switches to 5.5 after the update. To pin a version, name the model ID in /model or set ANTHROPIC_DEFAULT_OPUS_MODEL.

If your organization pins which models can be used
2.1.283 added the availableModelsMatch managed setting. With "exact", an availableModels entry allows only the model version it names, so new releases stay blocked until you list them. A companion deniedModels setting blocks specific models even when availableModels allows them.

2.1.280: writes through a symlinked path

Three permission-related fixes landed together.

Writes through a symlinked path were judged by their in-tree spelling rather than where they landed. The prompt now names the real destination, and acceptEdits, allow rules and auto mode no longer approve a write that lands outside the tree.
Auto mode retried an action over and over when a safety check declined to review it. The action is now denied once, noting that retrying won't help.
Auto mode also denied actions over and over without pause when a safety check gave no answer. Retries now back off, and the turn stops with a message after ten in a row.

If your allow rules are written around paths that look in-tree, writes could previously land somewhere you did not intend. For how those rules are written, see Configuring permissions in Claude Code's settings.json.

2.1.281: `"attribution": false` as a shorthand

You can now write "attribution": false in settings.json to hide all commit and PR attribution at once.

{
  "attribution": false
}

The changelog attaches a caveat: older CLI versions skip a settings file that holds it, so keep the object form in files shared across versions. If your team commits .claude/settings.json, stay with the object form below until you can confirm everyone is on 2.1.281 or later.

{
  "attribution": {
    "commit": "",
    "pr": "",
    "sessionUrl": false
  }
}

Each sub-key is explained in Removing Co-Authored-By from Claude Code commits.

2.1.278: auto mode's classifier moved to the server

For Claude API and Enterprise users, and on Bedrock, Vertex, Foundry and gateways, auto mode now defaults to the server-side classifier. Per the changelog, that classifier does not charge for its own overhead, and you get a warning if the session falls back to a billed path.

On Bedrock, Vertex, Foundry and gateways you can opt out with CLAUDE_CODE_AUTO_MODE_SERVER=0. /status gained an "Auto mode server" row showing whether this session's classifier runs on the server.

For where auto mode sits among the permission modes, see Changing Claude Code's default permission mode.

2.1.282 and 2.1.283: prose width and prompt auditing

A maxProseWidth setting caps the width of Claude's prose in wide terminals. Tables and code blocks keep the full width.
/doctor prompt-audit (also /checkup prompt-audit) audits your CLAUDE.md files, skills, agents and commands for prompting patterns written for older models.
2.1.282 fixed every request failing with a 400 error in conversations whose history holds web search results the API cannot decrypt — for example, from a turn answered through a third-party gateway.
2.1.280 added CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH, which changes the 2,048-character cap on MCP tool descriptions and server instructions for every MCP server in the session.

Codex CLI

0.156.1 and 0.157.0: GPT-6 Sol and Luna

0.156.1 was a hotfix that lets you "choose GPT-6 Sol or GPT-6 Luna from the model picker", with the rate-limit switch prompt now recommending GPT-6 Luna. 0.157.0 follows with "Added GPT-6 Sol and Luna, including Amazon Bedrock support and migration prompts for older models".

0.157.0: changes to how you drive the CLI

From the release notes' New Features, the items that touch day-to-day use:

Change	What it does
Fullscreen transcripts	Enabled by default; Shift-click extends a text selection
Background server	Starts automatically for eligible interactive sessions, with recovery choices when server settings are incompatible
`f` shortcut	Forks a conversation open in another app, preserving drafts and queued prompts
`/import`	Now available in remote sessions and local background-server sessions
Terminal rendering	Unicode bullets, checkboxes, aligned equations and optimization notation

Among the bug fixes, network restrictions are now enforced across redirects and on ongoing HTTP and WebSocket traffic, with cancellation when a policy change revokes access. Configured proxies are also honored for realtime connections and standalone web search, including search redirects.

Gemini CLI

0.61.0: almost entirely security work

v0.61.0's release notes list four substantive changes, all of them fixes.

Prevent indirect prompt injection via build file modifications and untrusted flags (#29250)
Harden sandbox filesystem boundaries and isolate runtime state (#29214)
Preserve explicit versioned Flash model IDs (#29252) — a version-pinned ID was being resolved to something else.
Ensure AgentLoopContext properties survive an object spread (#29335)

There are no new features. The release notes carry no detailed description of the fixes, so exactly which attack paths were closed could not be confirmed from the official release notes. If you run Gemini CLI without the sandbox, this is a good moment to turn it on.

What to check now

Update Claude Code to 2.1.283 or later, which includes the 2.1.280 symlink write fix.
If you select opus in /model, confirm that landing on Claude Opus 5.5 is what you want. To pin a version, name the model ID or set ANTHROPIC_DEFAULT_OPUS_MODEL.
Before writing "attribution": false into a shared .claude/settings.json, confirm everyone is on 2.1.281 or later. Keep the object form if versions are mixed.
If you use auto mode on Bedrock, Vertex, Foundry or a gateway, check the "Auto mode server" row in /status. Set CLAUDE_CODE_AUTO_MODE_SERVER=0 to opt out of the server-side classifier.
Update Gemini CLI to 0.61.0, and review your sandbox settings if it is not enabled.

Summary

Claude Opus 5.5 (claude-opus-5-5) is Claude Code's default Opus model, listed at $4/MTok input and $20/MTok output
2.1.280 makes symlinked writes judged by where they land, and fixes two auto mode retry loops
"attribution": false in 2.1.281 is convenient, but older CLI versions skip the whole settings file that holds it
Codex 0.157.0 adds GPT-6 Sol and Luna and turns on fullscreen transcripts by default
Gemini CLI 0.61.0 is prompt-injection and sandbox hardening, with no new features

Block git push --force in Claude Code with a deny rule

aicoding-guide — Fri, 25 Sep 2026 19:08:06 +0000

Originally published at https://aicoding-guide.com.

Let Claude Code drive Git and sooner or later a conflict resolution ends in git push --force, taking someone else's commits with it. The way to stop that is a permissions.deny entry in settings.json.

Four lines in your project's .claude/settings.json cover the common spellings.

Key point
What you will learn

The deny rules that block a force push

How to cover -f, --force-with-lease and reordered options

What a deny rule does not protect against

The rules

{
  "permissions": {
    "deny": [
      "Bash(git push --force:*)",
      "Bash(git push -f:*)",
      "Bash(git push --force-with-lease:*)",
      "Bash(git push * --force:*)"
    ]
  }
}

Bash rules match the command text, with * standing in for any text. Bash(git push --force:*) therefore matches git push --force origin main and anything else beginning that way.

Glossary
Deny precedence: rules are evaluated deny, then ask, then allow, and the first match decides. Rule specificity does not change that order, so an allow rule can never carve an exception out of a deny rule. Deny rules also apply in every permission mode, including bypassPermissions, where allow rules have no effect at all.

Covering the spellings

Because the match is against the command text, a different option order does not hit the same rule. These are the forms worth listing:

Command	Pattern that matches it
`git push --force origin main`	`Bash(git push --force:*)`
`git push -f origin main`	`Bash(git push -f:*)`
`git push origin main --force`	`Bash(git push * --force:*)`
`git push --force-with-lease`	`Bash(git push --force-with-lease:*)`

--force-with-lease is safer than a bare --force, but it still overwrites the remote. If your team allows it, move that one line into ask rather than deny.

A deny rule is a safety net, not a wall
cd repo && git push --force, or a push buried in a shell script, does not start with the text your rule matches. For a branch that genuinely must not be rewritten, set branch protection on the remote — GitHub's "do not allow force pushes" — and treat the deny rule as what it is: a way to reduce local accidents.

Confirming it works

Save the settings and start (or restart) Claude Code.
Run /permissions and check that the four lines appear under deny, along with the settings file each came from.
Ask Claude to run git push --force origin test-branch.
The call should be refused, with the reason shown.

Related rules

The same approach covers other commands that destroy work:

{
  "permissions": {
    "deny": [
      "Bash(git reset --hard:*)",
      "Bash(git checkout -- .:*)",
      "Bash(git clean -f:*)"
    ]
  }
}

For the overall rule design — allow, ask and deny, and how the scopes interact — see Claude Code permissions in settings.json. For a file-oriented example of the same mechanism, see Stop Claude Code reading your .env.

Summary

Put Bash(git push --force:*) and its siblings in permissions.deny in .claude/settings.json
The match is on command text, so -f, --force-with-lease and reordered options each need a line
Deny always beats allow, in every mode, and personal settings cannot undo a project deny
Pair it with branch protection on the remote for anything you truly cannot lose

Claude Code permission modes compared: default, acceptEdits, plan, auto, dontAsk, bypassPermissions

aicoding-guide — Fri, 25 Sep 2026 19:08:04 +0000

Originally published at https://aicoding-guide.com.

A permission mode sets what Claude can do in a session without asking you first. It is the baseline that applies to anything your allow and deny rules don't already decide.

There are six modes. Two of them cannot be set from project settings at all, which is the detail that most often explains "my defaultMode isn't doing anything".

Key point
What you will learn

What each of the six modes runs without asking

Which mode a session starts in, and the order that decides it

The two values that silently do not apply in project settings

The six modes

Mode	What runs without asking	Best for
`default`	Reads only	Reviewing every action yourself, sensitive work
`acceptEdits`	Reads, file edits, and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`)	Iterating on code you're reviewing
`plan`	Reads, plus classifier-approved commands when auto mode is available	Exploring a codebase before changing it
`auto`	Everything, with background safety checks	Long tasks, reducing prompt fatigue
`dontAsk`	Reads and pre-approved tools; anything that would prompt is denied	Locked-down CI and scripts
`bypassPermissions`	Everything	Isolated containers and VMs only

The mode that reviews every action is labelled Manual in the CLI, the VS Code and JetBrains extensions and the desktop app. Its config value is default, and the CLI also accepts manual as an alias (v2.1.200 or later).

Modes set the baseline only. Deny rules block in every mode, including bypassPermissions, and allow rules have no effect in bypassPermissions. The mode decides what happens to everything your rules don't match.

Which mode a session starts in

On Pro, Max and Team plans the built-in starting permission mode is auto. For a new terminal session, Claude Code takes the mode from the first of these that applies:

The --permission-mode flag, or --dangerously-skip-permissions
permissions.defaultMode in a settings file
The built-in default

Two values silently don't apply in project settings
Set "auto" in .claude/settings.json or .claude/settings.local.json and it does not take effect — and Claude Code then uses the built-in default rather than a defaultMode from ~/.claude/settings.json. Set "bypassPermissions" in those two files and it doesn't take effect either: the session starts in Manual mode. Every other value applies from any settings file.

Writing the setting

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Put it in ~/.claude/settings.json for a personal default across projects, .claude/settings.json to share with the project, or .claude/settings.local.json for yourself in this repository — keeping the exception above in mind.

Picking one

Everyday development: acceptEdits. Edits stop interrupting you, and you review them together with git diff afterwards
An unfamiliar codebase, or design work: plan. Nothing is changed, so you can hand over investigation safely, then switch once you agree with the plan
Shared project settings: stay on the cautious side. Anyone who wants to move faster can override in their own settings.local.json
CI and disposable containers: dontAsk for a strict allowlist, or bypassPermissions only where Claude Code cannot damage anything

For what bypassPermissions actually turns off and the conditions the documentation sets for it, see When bypassPermissions is safe to use. For non-interactive runs, see Running Claude Code headless in CI.

Switching temporarily

How	Scope
`Shift+Tab`	The current session; cycles through the available modes
`claude --permission-mode plan`	The starting mode for that session
`claude -p ... --permission-mode acceptEdits`	One non-interactive run

None of these rewrite a settings file. "Normally acceptEdits, today just investigating" is a Shift+Tab or a flag, not a config change.

Summary

Six modes: default (Manual), acceptEdits, plan, auto, dontAsk, bypassPermissions
Deny rules apply in every mode; allow rules do nothing in bypassPermissions
On Pro, Max and Team plans, sessions start in auto unless a flag or defaultMode says otherwise
auto and bypassPermissions do not take effect from .claude/settings.json or .claude/settings.local.json
Shift+Tab and --permission-mode switch temporarily without touching your settings

claude mcp add --scope: local vs project vs user, and which to pick

aicoding-guide — Thu, 24 Sep 2026 19:17:24 +0000

Originally published at https://aicoding-guide.com.

When you add an MCP server with claude mcp add, it is not obvious which --scope to pass. The names suggest the answer, but local and user are stored in the same file, which makes the distinction easy to miss.

Three things separate them: where they are stored, who they are shared with, and which one wins a name clash. In short: local (the default) for yourself in this project, project to share with your team, user for yourself everywhere.

Key point
What you will learn

How the three scopes differ in storage and reach

Why project writes .mcp.json and triggers an approval prompt

Which scope wins when the same name appears in several

The three scopes side by side

Scope	Reach	Stored in	Shared with the team
`local` (default)	This project, you only	`~/.claude.json`, under that project's path	No
`project`	Everyone on the project	`.mcp.json` at the project root	Yes, through version control
`user`	All your projects	`~/.claude.json`	No

Both local and user land in ~/.claude.json. The difference is where inside it: the documentation says Claude Code stores a local server in ~/.claude.json under that project's path, so the same server won't appear in your other projects.

Omitting --scope gives you local. These two are equivalent:

claude mcp add --transport http stripe https://mcp.stripe.com
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Which to pick

Situation	Scope
A server with credentials you don't want in version control	`local`
An experimental configuration	`local`
Everyone on the team should get the same server	`project`
A server you use in every project (search, notes)	`user`

The documentation describes local's use cases the same way: personal development servers, experimental configurations, and servers with credentials you don't want in version control.

# Shared with the team (written to .mcp.json)
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# Available in all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Project scope and .mcp.json

Adding with --scope project creates or updates .mcp.json at the project root.

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Commit that file to share the configuration. For how to add MCP servers in general, see Adding MCP servers to Claude Code.

Project scope comes with an approval prompt
The documentation states that for security reasons Claude Code prompts for approval in interactive sessions before using project-scoped servers from .mcp.json files. To reset those approval choices, run claude mcp reset-project-choices.

The cases where the prompt does not appear are documented too:

In claude -p runs, Agent SDK sessions and cloud sessions, Claude Code can't show the prompt, so it loads project-scoped servers without asking
It also skips the prompt in a session started in bypassPermissions mode with skipDangerousModePermissionPrompt set in user or managed settings

To keep a server out anyway, the documentation gives three options:

Option	Effect
Add it to `disabledMcpjsonServers`	Blocks it in every permission mode
Exclude project settings with `--setting-sources` (SDK: `settingSources`)	Project settings are not read at all
Start with `--strict-mcp-config`	Only the servers you pass with `--mcp-config` are used

When the same name appears twice

When a server is defined in more than one place, Claude Code connects once, using the definition from the highest-precedence source. The whole entry from that source is used; fields are not merged across scopes.

Local scope
Project scope
User scope
Plugin-provided servers
claude.ai connectors

The three scopes match duplicates by name. Define the same name in two scopes with different endpoints and Claude Code warns about the conflict in claude mcp list output and in /mcp.

Glossary
Scope: how far a piece of configuration reaches. For MCP it is set by two questions: just you or everyone, and this project or all of them.

Listing and removing

claude mcp list
claude mcp get <name>

Removing takes a scope:

claude mcp remove <name> --scope <scope>

Summary

--scope defaults to local: yours, in this project only
local and user share ~/.claude.json, but local is stored under the project's path
project writes .mcp.json at the project root and travels through version control
Project-scoped servers need approval in interactive sessions; reset with claude mcp reset-project-choices
On a name clash the order is local, project, user, plugin, connector — and only one definition is used

Block rm -rf with a Claude Code PreToolUse hook, and know its limits

aicoding-guide — Tue, 22 Sep 2026 19:20:30 +0000

Originally published at https://aicoding-guide.com.

Some commands you never want running unreviewed, and rm -rf is the classic one. A PreToolUse hook lets a script inspect the call and refuse it before the tool runs.

What makes this hook worth using is its position in the chain: the documentation states that PreToolUse hooks fire before any permission-mode check, in every permission mode including dontAsk, and that a hook returning permissionDecision: "deny" blocks the tool even in bypassPermissions mode or with --dangerously-skip-permissions.

Key point
What you will learn

Two ways to block: exit code 2 and permissionDecision

Why changing permission mode doesn't get around it, and what hooks still can't do

Where string matching breaks down, and what to pair it with

Blocking with exit code 2

The shortest form. Write a message to stderr and exit 2: the tool call is denied and that stderr is fed back to Claude.

#!/usr/bin/env bash
# .claude/hooks/block-rm-rf.sh
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$CMD" | grep -Eq '(^|[;&|[:space:]])rm[[:space:]]+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r)'; then
  echo "Blocked: recursive force-remove is not allowed here. Name the paths individually." >&2
  exit 2
fi

exit 0

On macOS and Linux the script has to be executable:

chmod +x .claude/hooks/block-rm-rf.sh

Register it in .claude/settings.json. As in the documentation's example, you can run a logging hook alongside the guardrail:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

The documentation walks through what happens: both hooks execute in parallel, the logging hook exits 0 and reports no decision, and the guardrail exits 2 to deny the call. The deny takes precedence, so the command is blocked — and the log entry is still written, because the logging hook already ran.

Blocking with permissionDecision

Instead of an exit code, print JSON to stdout. This lets you pass a structured reason.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Recursive deletes are blocked here. Run git clean -n first, then remove paths individually."
  }
}

PreToolUse accepts three values:

Value	Effect
`allow`	Skip the interactive permission prompt. Deny and ask rules still apply
`deny`	Cancel the tool call and send the reason to Claude
`ask`	Show the permission prompt as normal

With deny, permissionDecisionReason is fed back to Claude, so writing why and what to do instead keeps the work moving rather than just stopping it.

allow cannot override a deny rule
The reverse does not hold. A hook returning allow does not bypass deny rules from settings, and it cannot suppress prompts for MCP tools marked requiresUserInteraction or for connector tools your organization set to ask. As the documentation puts it: hooks can tighten restrictions but not loosen them past what permission rules allow.

Cover file edits too

rm arrives through the Bash tool, but an Edit or Write that clobbers an important file is the same class of accident. The documentation shows a path-based guard:

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

Register that one with a matcher of Edit|Write. For the shape of the JSON these scripts read, see The JSON your Claude Code hooks receive on stdin; for matcher values, see Every value you can put in a Claude Code hook matcher.

Where string matching breaks

This is the part to be honest about. Matching the command text is easy to slip past.

Written as	Matched by a naive `rm -rf` check
`rm -rf build`	Yes
`rm -r -f build`	No
`rm --recursive --force build`	No
`FLAGS="-rf"; rm $FLAGS build`	No
`find . -delete`	Not an `rm` at all

The script above handles -rf and -fr orderings, and that is still not exhaustive. A hook is an effective guardrail against mistakes; it is not a mechanism for stopping deliberate evasion.

For anything you need genuinely enforced, layer these underneath:

Permission deny rules: the documentation states that hook decisions don't bypass permission rules — Claude Code evaluates deny and ask rules regardless of what a PreToolUse hook returns. See Claude Code permissions in settings.json
The sandbox: OS-level restriction that also covers files a script opens indirectly

Worth knowing too: rm and rmdir targeting a critical path are never auto-approved in any mode, and no allow rule or PreToolUse hook allow approves them.

Glossary
PreToolUse: the event that fires immediately before a tool runs. Denying here means the tool call never happens.

Checking it works

After registering, run /hooks and confirm the hook appears under the right event. To test the script by itself, pipe sample JSON into it:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /tmp/x"}}' | ./.claude/hooks/block-rm-rf.sh; echo "exit=$?"

exit=2 is what you want to see.

Summary

PreToolUse hooks fire before permission-mode checks, so a deny holds even in bypassPermissions
Two ways to block: exit 2 for brevity, permissionDecision JSON to pass a reason
Multiple hooks on one event run in parallel, and a deny wins
A hook's allow cannot override a deny rule — hooks tighten, they don't loosen
String matching misses rm -r -f and variable expansion; use deny rules and the sandbox for real enforcement

Get a desktop notification when Claude Code finishes, with a Stop hook

aicoding-guide — Sun, 20 Sep 2026 19:07:56 +0000

Originally published at https://aicoding-guide.com.

Watching a terminal to see whether a long task has finished is wasted time. A notification at the moment it completes frees you to do something else in the meantime.

The event that fires when Claude finishes responding is the Stop hook. The Notification hook in the documentation's getting-started walkthrough is a different thing: it tells you Claude is waiting for input. This article keeps the two apart and gives the setup for all three platforms.

Key point
What you will learn

How Stop differs from Notification, and which one you want

The notification command and config for macOS, Linux and Windows

The exit-code trap that can keep Claude from stopping

Stop or Notification?

The names are similar; the timing is not.

Event	Fires when	Matcher
`Stop`	Claude finishes responding	Not supported
`SubagentStop`	A subagent finishes	Matches on agent type
`Notification`	Claude Code sends a notification (permission prompt, idle, and so on)	Matches on notification type

"Tell me when the work is done" is Stop. "Tell me when it's stuck on a permission prompt" is Notification. Configuring both is fine.

The notification types you can match on include permission_prompt, idle_prompt, auth_success, agent_needs_input and agent_completed. The full list of matcher values per event is in Every value you can put in a Claude Code hook matcher.

A matcher on Stop is ignored
Stop does not support a matcher. Adding one is not an error — it is silently ignored, and the hook fires every time. To narrow it, branch inside the hook script instead.

Configuration by platform

These go in ~/.claude/settings.json. Create the file if it does not exist.

macOS

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code finished\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

If nothing appears, Script Editor — which osascript routes notifications through — probably lacks notification permission. The documentation notes that in that case the command fails silently and macOS never prompts you to grant it. Run this once in Terminal so Script Editor shows up in your notification settings, then enable Allow Notifications for Script Editor under System Settings > Notifications.

osascript -e 'display notification "test"'

Linux

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code finished'"
          }
        ]
      }
    ]
  }
}

notify-send needs a desktop notification daemon, which headless servers, SSH sessions and most containers do not have. Test the command directly first. If it is not found, install libnotify-bin on Debian and Ubuntu, or your distribution's equivalent.

notify-send 'Claude Code' 'test'

Windows (PowerShell)

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code finished', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

Run /hooks afterwards to see the configured hooks per event and which file each came from. Note that the /hooks menu is read-only: to add, modify or remove hooks, edit the settings JSON directly or ask Claude to do it.

The exit-code trap

This is the part specific to Stop. A Stop hook that exits with code 2 blocks the stop, and the conversation continues. If your notification command fails and returns 2, Claude keeps going when you did not intend it to.

When all you want is a notification, make sure the command exits 0.

{
  "type": "command",
  "command": "notify-send 'Claude Code' 'Claude Code finished' || true"
}

|| true turns a failed notification into a 0 exit.

There is also a cap on blocking. The documentation states that Claude Code overrides a Stop hook after it blocks eight times in a row without progress. If you write a hook that deliberately blocks, read stop_hook_active from the JSON on stdin and exit early once you have already triggered a continuation.

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

Putting content in the notification

A Stop hook's stdin carries last_assistant_message and stop_reason, so the notification can say what actually finished.

#!/usr/bin/env bash
# ~/.claude/hooks/notify-done.sh
INPUT=$(cat)
MSG=$(echo "$INPUT" | jq -r '.last_assistant_message // empty' | head -c 120)
notify-send 'Claude Code' "${MSG:-Claude Code finished}" || true
exit 0

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/notify-done.sh"
          }
        ]
      }
    ]
  }
}

For the full shape of that JSON, see The JSON your Claude Code hooks receive on stdin. For building hooks generally, see Run lint and format automatically after every edit.

Glossary
stop_reason: a string describing why Claude stopped. A normal end of turn carries end_turn.

Summary

Use Stop for "work finished" and Notification for "waiting on you"
Stop takes no matcher; one written there is silently ignored
macOS uses osascript, Linux notify-send, Windows a PowerShell MessageBox
A Stop hook exiting 2 blocks the stop; append || true when you only want a notification
If you block deliberately, check stop_hook_active to stay under the eight-block cap
last_assistant_message lets the notification say what finished

This week in Claude Code, Codex and Gemini CLI (week of September 20, 2026)

aicoding-guide — Sat, 19 Sep 2026 19:08:56 +0000

Originally published at https://aicoding-guide.com.

The headline this week is that Claude Code now reads AGENTS.md directly (v2.1.277). Until now you had to import it from a CLAUDE.md; in a repository without one, it is simply read.

Second: the 2.1.268 change this digest reported last week as a permission-bypass fix was reverted in 2.1.273. If you relied on that behavior, it is back to what it was.

Covered here: Claude Code 2.1.270 through 2.1.277, Codex CLI 0.155.0 and 0.155.1, and Gemini CLI 0.60.0.

Key point
What you will learn

Claude Code's AGENTS.md support and which file wins

The deny-rule fix from last week that got reverted

Codex voice conversations and Touch ID, plus Gemini CLI's security fixes

Claude Code

2.1.277: AGENTS.md support

The changelog states it plainly: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead. The documentation now has an AGENTS.md section, and the resolution is this:

Your repository has	Claude reads
An `AGENTS.md`, and no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it	Your `AGENTS.md`
An `AGENTS.md` and a `CLAUDE.md` or `CLAUDE.local.md`	Your `CLAUDE.md` files only
A `CLAUDE.md` that already imports `AGENTS.md`	Your `CLAUDE.md`, with `AGENTS.md` through the import

Three files count for that check: CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md in your working directory or above. Your ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md and .claude/rules/ files do not count and keep loading alongside AGENTS.md.

To change the default, run /config and set Project instructions:

Value	What Claude reads
`claude-md-or-agents-md`	The default: `CLAUDE.md`, or `AGENTS.md` when you have none
`claude-md-and-agents-md`	Both, each directory's `CLAUDE.md` first and its `AGENTS.md` after
`claude-md`	`CLAUDE.md` only
`managed-only`	Only your organization's managed `CLAUDE.md` and auto memory

You can set it in a settings file instead, under the built-in agents-md plugin's ID. Project and local settings files are ignored for this value.

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Some sessions don't get this
The documentation lists the cases where Claude reads CLAUDE.md only and Project instructions doesn't appear in /config: a version before v2.1.277; a session that doesn't fetch feature flags from Anthropic, such as Amazon Bedrock or another third-party provider or with telemetry disabled; your first session after installing or upgrading; and setting disableAllHooks or allowManagedHooksOnly, or disabling the built-in agents-md plugin. Import AGENTS.md from a CLAUDE.md in those environments.

For how the three tools' context files relate, see CLAUDE.md vs AGENTS.md vs GEMINI.md.

2.1.276: upgrade now if you use a gateway

A 2.1.275 regression made every request fail with 400 … Input tag 'advisor_20260301' when ANTHROPIC_BASE_URL points at a proxy or gateway. 2.1.276 fixes it. If that describes your setup, upgrading is mandatory.

2.1.275: a send-now key and claude.ai syncing

Send-now key: ctrl+enter (or ctrl+x ctrl+s) interrupts the current turn and sends all queued messages at once
Skill and plugin syncing: the skills and plugins enabled on your claude.ai account now sync to terminal sessions signed in with it. Opt out with syncClaudeAiSkills: false or syncClaudeAiPlugins: false
/plugin install <plugin> --marketplace <source> offers to add the marketplace before installing

2.1.273: last week's deny-rule fix was reverted

Last week this digest reported that Read and Edit deny rules failing to apply on a line containing env -C or eval had been fixed. That 2.1.268 change was reverted in 2.1.273. The changelog reads: "Reverted a 2.1.268 change that checked Read and Edit deny rules on Bash lines the permission checker can't analyze". Commands like time -p make build prompt again rather than being denied.

Permission fixes did land in the same release, though:

Fixed Bash commands the permission checker cannot fully analyze skipping the prompt under permissions.blockReadsOutsideWorkingDirectories, and a subshell hiding a dangerous rm in bypass mode
Fixed the context meter and auto-compact counting advisor-tool turns at roughly twice their real context size, which made auto-compact fire at about half the real window

The first one bears directly on protecting .env with deny rules — see Stop Claude Code reading your .env with a Read deny rule. For compaction thresholds, see autoCompactWindow.

2.1.274: MCP fixes

Fixed Streamable HTTP MCP tool calls timing out after about 5 minutes even with a longer per-server timeout set
Added CLAUDE_CODE_MCP_STARTUP_WAIT_MS to bound how long the first non-interactive turn waits for connecting MCP servers (0 means don't wait)
Fixed MCP servers configured as http that only speak legacy HTTP+SSE failing to connect when they answer the first request with 422 or another 4xx

For MCP configuration, see Adding MCP servers to Claude Code.

2.1.271 and 2.1.270

Per-command allowed_domains for Bash, PowerShell and Monitor in auto mode with sandboxing: the hosts a command needs are reviewed with it and opened for it alone, and other hosts are refused
omitClaudeMd in agent frontmatter and --agents JSON lets custom and plugin subagents run without user, project and local CLAUDE.md files. Managed policy files still load
Several Bash permission-check gaps closed: files a wildcard expands to, files read by fmt and column after an unrecognized option, shell variable declaration flags misrepresenting the command, and commands with two directory changes
2.1.270 fixed a 2.1.269 regression where read-only git commands started asking for permission after a session had been running a while

Codex

CLI 0.155.0

Experimental /voice conversations with live transcripts and microphone controls, enabled through /experimental on supported builds
The TUI shows live reasoning summaries in the status row and completion timestamps after successful turns
Task hiding, archiving and deletion in the agents overview, plus worktree ownership details and confirmed deletion of clean managed worktrees
Touch ID verification for MCP requests in local TUI sessions on supported Macs
Amazon Bedrock can obtain AWS credentials from configured commands, with caching and expiration-based refresh

On the fixes side, Windows-process escapes from restricted WSL sandboxes are now blocked, and brokered shell snapshots were hardened against credential exposure.

CLI 0.155.1

New local TUI sessions leave reasoning summaries disabled by default again, fixing request rejection by providers that do not support them. Explicit reasoning-summary settings are still respected.

For how approvals and the sandbox interact, see What does Codex --full-auto actually do?.

Gemini CLI

0.60.0

Nearly every line in the release notes is a security fix.

Area	Change
Web fetch	Improved destination validation and connection routing
MCP OAuth	Enforces RFC 9207 issuer identification
macOS Seatbelt	Isolates the temporary directory for the sandbox
Extensions	Hardened path resolution and boundary validation; prompts for consent on environment changes and sanitizes runtime-altering environment variables
chrome-devtools-mcp	Removed a hardcoded Google CrUX API key
Workspace boundaries	Stronger boundary checks and symlink resolution in command safety and file discovery
System config	Strict permission and ownership checks on system-wide configuration paths
Windows	Mitigates NTFS 8.3 short name (SFN) paths

Glossary
NTFS 8.3 short names: the PROGRA~1-style aliases Windows generates for long filenames. Because the same file can be reached by a second spelling, they are a route around path checks.

What to check now

[ ] On 2.1.275 behind a proxy or gateway, upgrade to 2.1.276 or later
[ ] In repositories with an AGENTS.md and no CLAUDE.md, know that v2.1.277 changes what gets loaded
[ ] If you keep both files, note that AGENTS.md is not read by default; use claude-md-and-agents-md if you want both
[ ] If you relied on deny rules covering eval or env -C lines, revisit that assumption for 2.1.273 and later
[ ] If auto-compact was firing early, check whether 2.1.273 improved it
[ ] To keep claude.ai skills and plugins out of terminal sessions, set syncClaudeAiSkills and syncClaudeAiPlugins to false

Summary

Claude Code v2.1.277 reads AGENTS.md directly, in repositories that have no CLAUDE.md
The default is claude-md-or-agents-md; change Project instructions in /config to load both
The 2.1.268 deny-rule change was reverted in 2.1.273, correcting what this digest said last week
2.1.275 has a gateway regression that fails every request with a 400; 2.1.276 fixes it
Codex 0.155.0 adds experimental /voice and Touch ID for MCP requests; 0.155.1 restores the reasoning-summary default
Gemini CLI 0.60.0 is almost entirely security work, including RFC 9207 enforcement in MCP OAuth

Stop Claude Code reading your .env with a Read deny rule

aicoding-guide — Fri, 18 Sep 2026 19:10:05 +0000

Originally published at https://aicoding-guide.com.

Your .env holds API keys and database passwords. Claude Code reads files inside the working directory without asking, so by default the contents of .env end up in the model's input.

The reliable way to stop that is a Read deny rule in settings.json. Deny rules are evaluated before allow rules and block regardless of permission mode.

Key point
What you will learn

The deny rule that keeps .env out of reach

How pattern shape changes what the rule actually covers

Where deny rules do not reach, and what to use instead

The rule

Put this in your project's .claude/settings.json:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Read(./.env.*) covers derived files such as .env.local and .env.production. A Read deny rule also blocks the Edit and Write tools on the same path, including creating a new file there, so these three lines stop both reading and rewriting. NotebookEdit is not covered — add an Edit deny rule for paths no tool may change.

Glossary
Deny precedence: rules are evaluated in order — deny, then ask, then allow — and the first match determines the outcome. Rule specificity does not change that order, so an allow rule cannot carve an exception out of a deny rule.

Pattern shape decides the anchor

Read and Edit rules use gitignore pattern syntax. The leading characters decide where the pattern is anchored.

Pattern	Anchored at	Example
`path` or `./path`	Current directory	`Read(./.env)`
`/path`	The settings source that defines it	`Read(/config/.env)`
`~/path`	Home directory	`Read(~/.aws/credentials)`
`//path`	Filesystem root	`Read(//etc/shadow)`

Depth is a separate question. Bare filenames follow gitignore semantics and match at any depth:

Deny rule	Blocks	Does not block
`Read(./.env)`	`.env` in the current directory	`.env` in a subdirectory
`Read(.env)` or `Read(**/.env)`	any `.env` at or under the current directory	`.env` in a parent directory or another project
`Read(//**/.env)`	any `.env` anywhere on the filesystem	nothing; it is anchored at the filesystem root

In a monorepo where packages/api/.env and packages/web/.env both exist, Read(./.env) is not enough. Write Read(.env) to match at any depth.

The anchor moves when you write the rule in user settings
Read(/secrets/**) in ~/.claude/settings.json anchors at the settings source, so it matches ~/.claude/secrets/** — not your project's secrets directory. A single leading slash is not an absolute path. To cover every project, use // for a filesystem-absolute path or ~/ for a home-relative one.

Where deny rules reach

Read and Edit deny rules apply to:

Claude's built-in file tools (Read, Edit, Write), with Grep, Glob, @file mentions in your prompt and IDE-shared open files covered where possible
File commands Claude Code recognizes in Bash: cat, head, tail, sed and tee. These normally run without a prompt, but a deny rule blocks them
Bash redirection targets, both > file and < file. Input-target checking requires Claude Code v2.1.257 or later

Symlinks are checked on both paths — the link and its target — and a deny rule applies when either one matches.

Scripts that open files themselves are not covered
Deny rules do not apply to a command that reads files without naming them, such as grep -r pattern . run from the directory holding the file, or to a Python or Node script that opens files itself. python -c "print(open('.env').read())" is just a command execution as far as the permission checker is concerned. For OS-level enforcement that blocks all processes, enable the sandbox.

Note also that the protected paths list — the set of writes never auto-approved — includes .envrc, not .env, and covers writes only. Reads need your own deny rule.

Confirming it works

Save the settings and start Claude Code.
Run /permissions. It lists the active rules and which settings file each came from.
Ask Claude to read .env. You should get File is covered by a Read deny rule in your permission settings.

If you wrote a pattern that can't be used for file checks, Claude Code warns at startup with ... is not matched by file permission checks. That warning means the path syntax needs fixing — for example, a path rule written for Write, NotebookEdit or Glob, which Claude Code accepts but never consults.

For the wider rule design, see Claude Code permissions in settings.json. For keeping secrets away from all three tools, see Stop AI coding tools from reading your API keys and secrets.

Summary

Put Read(./.env) and Read(./.env.*) in permissions.deny in .claude/settings.json
A Read deny also covers Edit and Write, but not NotebookEdit
Read(./.env) is current-directory only; Read(.env) matches at any depth
Deny beats allow and applies in every mode, including bypassPermissions
Scripts that open files themselves slip past it — use the sandbox for OS-level enforcement

DEV Community: aicoding-guide

Gemini CLI v0.62: gemini-3.8-flash and gemini-3.5-flash-lite added

The two new models

Setting the model in settings.json

Authentication and login persistence

Windows, proxy and the rest

Summary

Codex CLI v0.158: MCP OAuth client secrets and approval for elevated commands

Approvals: a changed default

MCP: OAuth client secrets

Sandbox fixes

TUI changes, and what followed in v0.159

Summary

Auto-approve MCP tools in Claude Code permissions: the mcp__ syntax and its wildcard limits

The three rule shapes

Allow wildcards need an anchor

Deny and ask follow different rules

Where rules live, and what gets ignored

Summary

Sign in to a remote MCP server in Claude Code: /mcp and claude mcp login

Add the server and sign in from /mcp

Sign in from the command line

Use pre-registered OAuth credentials

When sign-in expires or fails

Summary

This week in Claude Code, Codex and Gemini CLI (week of September 27, 2026)

Claude Code

2.1.280: Claude Opus 5.5 becomes the default Opus model

2.1.280: writes through a symlinked path

2.1.281: "attribution": false as a shorthand

2.1.278: auto mode's classifier moved to the server

2.1.282 and 2.1.283: prose width and prompt auditing

Codex CLI

0.156.1 and 0.157.0: GPT-6 Sol and Luna

0.157.0: changes to how you drive the CLI

Gemini CLI

0.61.0: almost entirely security work

What to check now

Summary

Block git push --force in Claude Code with a deny rule

The rules

Covering the spellings

Confirming it works

Related rules

Summary

Claude Code permission modes compared: default, acceptEdits, plan, auto, dontAsk, bypassPermissions

The six modes

Which mode a session starts in

Writing the setting

Picking one

Switching temporarily

Summary

claude mcp add --scope: local vs project vs user, and which to pick

The three scopes side by side

Which to pick

Project scope and .mcp.json

When the same name appears twice

Listing and removing

Summary

Block rm -rf with a Claude Code PreToolUse hook, and know its limits

Blocking with exit code 2

Blocking with permissionDecision

Cover file edits too

Where string matching breaks

Checking it works

Summary

Get a desktop notification when Claude Code finishes, with a Stop hook

Stop or Notification?

Configuration by platform

macOS

Linux

Windows (PowerShell)

The exit-code trap

Putting content in the notification

Summary

This week in Claude Code, Codex and Gemini CLI (week of September 20, 2026)

Claude Code

2.1.277: AGENTS.md support

2.1.276: upgrade now if you use a gateway

2.1.275: a send-now key and claude.ai syncing

2.1.281: `"attribution": false` as a shorthand