fix: clean permission model — feature branches are free, only merge asks

Hooks: on feature branches, commit/push are fully free (no prompts).
Only merging into main prompts for approval. Bypass mode allows
everything including merges.

Updated both local hooks and all end-user templates (branch-context,
merge-guard). Updated AGENTS.md git workflow section.

Author: vivek7405

AGENTS.md

@@ -93,20 +93,26 @@ Every code change MUST include — **automatically, without the user asking:**
 
 ### Git workflow (mandatory, never skip)
 
-1. **Commit often.** After each logical unit of work — a completed function,
-   a passing test, a doc update. Don't batch unrelated changes.
+**The model:** Always work on a feature branch. On a feature branch,
+commit and push freely — no permissions needed. The only gate is
+merging back into main, which requires user approval (unless in
+bypass/autonomous mode).
 
-2. **Meaningful commit messages.** Describe what changed and why, not "update
+1. **Create a feature branch first.** Before any code change:
+   `git checkout -b feature/<task-slug>`. Never edit directly on main.
+
+2. **On the feature branch: commit and push freely.** No prompts, no
+   approval needed. Commit after each logical unit of work. Push after
+   each commit. This is fully autonomous.
+
+3. **Meaningful commit messages.** Describe what changed and why, not "update
    files" or "fix stuff". Format: imperative mood, under 72 chars for the
    first line. Example: `Add contact form with email validation`.
 
-3. **No AI attribution in commits.** NEVER add `Co-Authored-By: Claude`,
+4. **No AI attribution in commits.** NEVER add `Co-Authored-By: Claude`,
    `Generated by AI`, `AI-assisted`, or any similar trailer or prefix.
    The commit is the user's work — the agent is a tool.
 
-4. **Feature branches.** Never commit directly to main. Create a branch
-   for each feature or fix (`feature/contact-form`, `fix/login-redirect`).
-
 5. **Pull requests.** Create a PR for every feature branch. Use the PR
    template (`.github/pull_request_template.md`) which includes a test
    and documentation checklist.

packages/cli/templates/.claude/hooks/guard-branch-context.sh

@@ -2,15 +2,14 @@
 #
 # guard-branch-context.sh — Claude Code PreToolUse hook
 #
-# Fires before Edit and Write tool calls. If the current branch is `main`
-# or `master`, asks the user for confirmation before allowing file edits.
-#
-# Respects bypass/dangerous mode — user has opted into full autonomy.
+# Rules:
+#   - On main/master → ask (agent should create a feature branch first)
+#   - On any other branch → allow (feature branches are free to edit)
+#   - Bypass mode → allow everything
 
-# Read the tool input from stdin
 INPUT=$(cat /dev/stdin)
 
-# Respect bypass/dangerous mode
+# Bypass mode — full autonomy
 SETTINGS="$HOME/.claude/settings.json"
 if [ -f "$SETTINGS" ]; then
   BYPASS=$(jq -r '.skipDangerousModePermissionPrompt // false' "$SETTINGS" 2>/dev/null)
@@ -19,21 +18,15 @@ if [ -f "$SETTINGS" ]; then
   fi
 fi
 
-# Check if we're in a git repo
 if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   exit 0
 fi
 
-# Get current branch
 BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+[ -z "$BRANCH" ] && exit 0
 
-if [ -z "$BRANCH" ]; then
-  exit 0
-fi
-
-# If on main or master, ask before allowing edits
 if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
-  jq -n --arg reason "guard-branch-context: You are on the '$BRANCH' branch. Create a feature branch before editing (e.g., git checkout -b feature/<name>). Approve to continue on '$BRANCH'." '{
+  jq -n --arg reason "You are on '$BRANCH'. Create a feature branch first (git checkout -b feature/<name>), or approve to edit on '$BRANCH'." '{
     hookSpecificOutput: {
       hookEventName: "PreToolUse",
       permissionDecision: "ask",
@@ -43,5 +36,4 @@ if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
   exit 0
 fi
 
-# Not on main — allow
 exit 0

packages/cli/templates/.claude/hooks/guard-main-merge.sh

@@ -2,27 +2,16 @@
 #
 # guard-main-merge.sh — Claude Code PreToolUse hook
 #
-# Intercepts Bash tool calls and routes any command that looks like a merge
-# or push to main through interactive user approval. This prevents AI agents
-# from accidentally merging or pushing to main without explicit consent.
-#
-# Decision matrix:
-#   `git merge ...`              → ask (catches merge into any branch)
-#   `git push ... main ...`      → ask (catches push origin main, push HEAD:main, etc.)
-#   anything else                → allow
-#
-# Shipped by default with every webjs app via `webjs create`.
-# Wired in via .claude/settings.json under hooks.PreToolUse.
+# Rules:
+#   - git merge → ask (merging to parent branch needs approval)
+#   - git push on a feature branch → allow (free to push)
+#   - git push targeting main → ask
+#   - Bypass mode → allow everything
 
-# Read the tool input from stdin (JSON shape: { tool_input: { command: ... }, ... })
 COMMAND=$(jq -r '.tool_input.command // empty' < /dev/stdin)
+[ -z "$COMMAND" ] && exit 0
 
-# Empty command — let it pass.
-if [ -z "$COMMAND" ]; then
-  exit 0
-fi
-
-# Respect bypass/dangerous mode — user has opted into full autonomy.
+# Bypass mode — full autonomy
 SETTINGS="$HOME/.claude/settings.json"
 if [ -f "$SETTINGS" ]; then
   BYPASS=$(jq -r '.skipDangerousModePermissionPrompt // false' "$SETTINGS" 2>/dev/null)
@@ -31,7 +20,6 @@ if [ -f "$SETTINGS" ]; then
   fi
 fi
 
-# Normalize whitespace so multi-line / heredoc commands match the same way.
 NORMALIZED=$(printf '%s' "$COMMAND" | tr -s '[:space:]' ' ')
 
 ask_with_reason() {
@@ -45,15 +33,12 @@ ask_with_reason() {
   exit 0
 }
 
-# Catch `git merge` anywhere in the command.
 if [[ "$NORMALIZED" == *"git merge"* ]]; then
-  ask_with_reason "guard-main-merge: this command contains 'git merge'. Every merge requires your explicit approval. After merging, should the source branch be DELETED or KEPT? Approve to proceed (then tell the agent your preference)."
+  ask_with_reason "This command contains 'git merge'. Merging requires approval. After merging, should the source branch be deleted or kept? Approve to proceed."
 fi
 
-# Catch `git push` targeting main.
 if [[ "$NORMALIZED" == *"git push"* ]] && [[ "$NORMALIZED" == *"main"* ]]; then
-  ask_with_reason "guard-main-merge: this command looks like 'git push' targeting main. Approve to proceed."
+  ask_with_reason "This looks like 'git push' targeting main. Approve to proceed."
 fi
 
-# Everything else passes through.
 exit 0