claude-code - 💡(How to fix) Fix Feature Request: Documented opt-out for built-in default-branch push guard (CLI) [1 participants]

Summary

Claude Code CLI contains an undocumented harness-level safety guard that blocks assistant-initiated git push to the default branch. The guard fires even when permissions.allow contains Bash(git push:*) and permissions.defaultMode is auto. There is no documented setting, CLI flag, or permissions mode that overrides it.

This is a sensible default for team repositories with branch protection and a PR review workflow. It adds disproportionate friction, however, in docs-only repositories, solo-owned personal projects, and spec / guideline repositories that are vendored downstream via git subtree. This issue requests a narrowly-scoped, documented opt-out — not a change in the default.

What happens

Assistant-initiated call:

git push origin main

is refused with:

Permission for this action has been denied.
Reason: Pushing directly to the default branch (main) bypasses
pull request review.

The same command succeeds when the user runs it via the ! prefix in the TUI. The guard is therefore strictly client-side / harness-level; there is no server-side block.

Related prior report: #50624 confirms the same guard message exists and separately describes a bug where the command actually executes despite the denial envelope. This issue is orthogonal to that bug — here the denial and the block are consistent, but there is no way to opt out.

Timeline

1. Earlier CLI versions: assistant-initiated git push origin main worked without intervention.
2. A few versions ago: the guard appeared. Adding Bash(git push:*) to permissions.allow in settings.json restored autonomous pushing.
3. Today (CLI 2.1.117): the permissions.allow entry is no longer honored for default-branch pushes. The guard fires unconditionally, even in defaultMode: auto with skipAutoPermissionPrompt: true.

The progression is concerning because the previously-effective workaround (explicit allowlist) has silently stopped working with no documented replacement.

Environment

• Claude Code CLI: 2.1.117
• OS: Linux
• ~/.claude/settings.json:
  • permissions.defaultMode: auto
  • permissions.allow contains Bash(git push:*)
  • skipAutoPermissionPrompt: true
• Project-level .claude/settings.json also contains Bash(git push:*)
• No hooks configured

Docs check

Searched settings.md, cli-reference.md, how-claude-code-works.md, security.md, and permissions.md. The CLI-side default-branch push guard is not documented in any of them. Only claude-code-on-the-web.md mentions a branch-scoped push restriction, and it is described as specific to web / cloud agents.

Why it matters

The friction concentrates in a specific class of repositories where the harness guard actively works against the user's authorized workflow:

• Docs-only repositories: cutting a feature branch, opening a PR, and merging just to push a typo or link fix is disproportionate. The "review" step is vestigial when the sole reviewer is the sole author.
• Solo-owned projects: the user is the only committer, reviewer, and approver. A PR workflow adds multiple UI round-trips for no review value.
• Guideline / spec repositories consumed via git subtree: updates are typically single-commit clarifications that downstream projects pull via subtree merge. PR overhead on the upstream slows propagation without a matching quality benefit.

In all three cases the user has already consciously accepted the risk of direct pushes: no branch protection configured, no CI gate required. Running in defaultMode: auto — which exists precisely to authorize autonomous execution — does not cover this case either.

Current workarounds (all unsatisfying)

• Manually run ! git push origin main in the TUI every time — breaks autonomous flows and defeats defaultMode: auto.
• Set up GitHub branch protection + PR workflow — solves a problem that docs-only / solo projects don't have.
• --dangerously-skip-permissions — too broad; disables all permission prompts, not just this guard.

Proposal

A narrowly-scoped, opt-in override that restores the previously-working behavior:

• Setting: permissions.allowDefaultBranchPush: true (project-level or user-level settings.json)
• Default: false (preserves current safe default)
• Scope: CLI only. Web / cloud agents can keep their existing restriction since it is already documented and context-appropriate.
• Documentation: a short section in settings.md or security.md describing when the guard fires, why it exists, and how to opt out.

Alternative forms also acceptable:

• A CLI flag, e.g. --allow-default-branch-push
• A safety.* namespace key distinct from permissions.*, to make clear this is a safety guard and not a permission prompt
• Restoring the previous behavior where permissions.allow with Bash(git push:*) suffices

Thanks!