Permission Manager

Permission Manager Skill

Your responsibility is to configure Claude Code permissions in .claude/settings.json to allow repository operations while preventing dangerous commands. This eliminates frequent permission prompts and enhances security.

You manage permissions for:

• Git commands (branch, commit, push, fetch, etc.)
• GitHub CLI (gh) commands (pr, issue, repo operations)
• Safe file operations
• Deny rules for dangerous commands (rm -rf, format, dd, etc.)

1. Safety First

   • ALWAYS create backup of existing settings.json
   • ALWAYS validate JSON structure before writing
   • ALWAYS preserve existing non-repo settings
   • NEVER remove unrelated permissions

2. Minimal Permissions

   • ONLY allow commands repo plugin actually needs
   • ALWAYS use specific command patterns, not wildcards
   • ALWAYS include explicit deny rules for dangerous operations
   • NEVER grant broader permissions than necessary

3. User Control

   • ALWAYS show what permissions will be changed (with detailed categorization and reasoning)
   • ALWAYS require explicit "yes" confirmation for permission changes (no exceptions)
   • ALWAYS explain security implications and benefits of each permission category
   • ALWAYS show delta analysis (NEW vs PRESERVED vs CUSTOM permissions)
   • NEVER make silent permission changes
   • NEVER proceed without user typing "yes"

4. Error Handling

   • ALWAYS validate settings.json exists or can be created
   • ALWAYS check file permissions
   • ALWAYS handle malformed JSON gracefully
   • ALWAYS provide rollback on failure

Request Format:

{
  "operation": "configure-permissions",
  "parameters": {
    "mode": "setup|validate|reset",
    "project_path": "/path/to/project"
  }
}

Modes:

• setup - Configure permissions for first time or update
• validate - Check current permissions are sufficient
• reset - Remove repo-specific permissions (restore defaults)

1. DISPLAY START MESSAGE:

🔐 STARTING: Permission Manager
Mode: {mode}
Project: {project_path}
Settings file: {project_path}/.claude/settings.json
───────────────────────────────────────

2. LOAD CURRENT SETTINGS:

Check if .claude/settings.json exists:

if [ -f ".claude/settings.json" ]; then
    # Backup existing file
    cp .claude/settings.json .claude/settings.json.backup
    echo "✓ Backed up existing settings"
else
    # Create directory structure
    mkdir -p .claude
    echo "✓ Created .claude directory"
fi

Read current settings (or create default):

{
  "permissions": {
    "bash": {
      "allow": [],
      "deny": []
    }
  }
}

3. DEFINE REPO PERMISSIONS:

Commands to ALLOW (repo plugin needs):

ALLOW_COMMANDS = [
  // Git core operations
  "git status",
  "git branch",
  "git checkout",
  "git switch",
  "git commit",
  "git push",
  "git pull",
  "git fetch",
  "git remote",
  "git tag",
  "git log",
  "git diff",
  "git stash",
  "git merge",
  "git rebase",
  "git rev-parse",
  "git for-each-ref",
  "git ls-remote",
  "git show-ref",

  // GitHub CLI operations (11 commands)
  "gh pr create",
  "gh pr view",
  "gh pr list",
  "gh pr comment",
  "gh pr review",
  "gh pr merge",
  "gh pr close",
  "gh pr status",
  "gh issue create",
  "gh issue view",
  "gh issue list",
  "gh issue comment",
  "gh issue close",
  "gh repo view",
  "gh repo clone",
  "gh auth status",
  "gh auth login",
  "gh auth refresh",
  "gh api",

  // GitHub Actions workflow operations - read only (2 commands)
  "gh workflow list",
  "gh workflow view",

  // GitHub secrets management - read only (1 command)
  "gh secret list",

  // GitHub Apps management (2 commands)
  "gh app list",
  "gh app view",

  // Safe utility commands
  "cat",
  "head",
  "tail",
  "grep",
  "find",
  "ls",
  "pwd",
  "which",
  "echo",
  "jq"
]

Commands to DENY (dangerous operations):

DENY_COMMANDS = [
  // Destructive file operations
  "rm -rf /",
  "rm -rf *",
  "rm -rf .",
  "dd if=",
  "mkfs",
  "format",
  "> /dev/sd",

  // Git dangerous operations
  "git push --force origin main",
  "git push --force origin master",
  "git push -f origin main",
  "git push -f origin master",
  "git reset --hard origin/",
  "git clean -fdx",
  "git filter-branch",
  "git rebase --onto",

  // GitHub dangerous operations
  "gh repo delete",
  "gh repo archive",
  "gh api --method DELETE",
  "gh secret delete",
  "gh secret remove",

  // System operations
  "sudo",
  "su",
  "chmod 777",
  "chown",
  "kill -9",
  "pkill",
  "shutdown",
  "reboot",
  "init",

  // Network operations
  "curl | sh",
  "wget | sh",
  "curl | bash",
  "wget | bash"
]

4. MERGE PERMISSIONS:

Merge new permissions with existing settings:

• Preserve existing allow rules not related to repo
• Preserve existing deny rules
• Add repo-specific allow rules
• Add repo-specific deny rules
• Remove duplicates
• Sort alphabetically for readability

5. SHOW CHANGES:

Display comprehensive permission changes to user with detailed categorization and reasoning:

╔════════════════════════════════════════════════════════════════════╗
║  Permission Configuration Philosophy                               ║
╚════════════════════════════════════════════════════════════════════╝

We carefully balance agent autonomy with safety:

✓ MAXIMIZE AUTONOMY: Auto-approve safe operations so you're not
  constantly clicking 'yes' for routine git/GitHub commands.

⚠️  PROTECT CRITICAL PATHS: Require explicit approval for operations
  on protected branches (main/master/production) to prevent accidents.

✗ BLOCK CATASTROPHIC MISTAKES: Deny destructive operations that could
  destroy your repo, system, or execute remote code.

This configuration lets the agent work efficiently while keeping you safe.

───────────────────────────────────────────────────────────────────
📊 Permission Changes Summary
───────────────────────────────────────────────────────────────────

New Permissions to Add:
  ✅ 10 safe git read operations
     (git status, git branch, git log, git diff, git show, ...)
  ✅ 13 git write operations
     (git add, git checkout, git switch, git fetch, git pull, ...)
  ✅ 7 GitHub read operations
     (gh pr view, gh pr list, gh pr status, gh issue view, gh issue list, ...)
  ✅ 11 GitHub write operations
     (gh pr create, gh pr comment, gh pr review, gh pr close, gh issue create, ...)
  ✅ 15 safe utility commands
     (cat, head, tail, grep, find, ...)
  ⚠️  9 protected branch operations (require approval)
     (git push origin main, git push origin master, git push origin production, ...)
  ❌ 7 destructive file operations
     (rm -rf /, rm -rf *, rm -rf ., rm -rf ~, ...)
  ❌ 12 dangerous git operations
     (git push --force origin main, git push --force origin master, git push --force origin production, ...)
  ❌ 3 dangerous GitHub operations
     (gh repo delete, gh repo archive, gh secret delete)
  ❌ 10 system operations
     (sudo, su, chmod 777, chown, kill -9, ...)
  ❌ 4 remote code execution patterns
     (curl | sh, wget | sh, curl | bash, wget | bash)

Existing Permissions (Preserved):
  ✅ {count} commands already allowed
  ⚠️  {count} commands already require approval
  ❌ {count} commands already denied

Custom Permissions (Your additions - will be preserved):
  • {count} custom allowed commands
  • {count} custom denied commands

───────────────────────────────────────────────────────────────────
📋 Detailed Permission Breakdown
───────────────────────────────────────────────────────────────────

══════ NEW AUTO-ALLOWED COMMANDS (No prompts) ══════

Git Read Operations (10 commands)
  Check repository state without modifying anything
  Why: These are 100% safe - they only read info, never modify your repo
    • git status
    • git branch
    • git log
    ... and 7 more

Git Write Operations (13 commands)
  Normal git workflow operations on any branch
  Why: Safe for daily work - commits, pushes to feature branches, merges, etc.
    • git commit
    • git push
    ... and 11 more

[... similar detailed categorization for all command types ...]

══════ NEW BLOCKED COMMANDS (Always denied) ══════

Destructive File Operations (7 commands)
  Commands that could destroy your filesystem
  Why: These could wipe your entire disk or critical directories - always blocked
    • rm -rf /
    • dd if=
    ... and 5 more

[... etc ...]

───────────────────────────────────────────────────────────────────
Benefits of This Configuration:

  ✓ Smooth workflow - No interruptions for routine operations
  ✓ Smart protection - Approval required only for risky operations
  ✓ Safety net - Catastrophic mistakes blocked automatically
  ✓ Team friendly - Prevents accidentally breaking shared branches
  ✓ Security first - Blocks common attack patterns and dangerous commands

───────────────────────────────────────────────────────────────────

Do you want to apply these permission changes?
Type yes to apply, or no to cancel:

6. WAIT FOR CONFIRMATION:

CRITICAL: User confirmation is ALWAYS REQUIRED. The script will pause and wait for explicit "yes" confirmation.

If user does not type "yes", abort:

❌ Permission update cancelled
No changes made to settings.json

If user types "yes", proceed:

Applying changes...

7. WRITE UPDATED SETTINGS:

Use the permission update script:

bash plugins/repo/skills/permission-manager/scripts/update-settings.sh \
  --project-path "$PROJECT_PATH" \
  --mode "$MODE"

Validate written file:

# Validate JSON structure
jq empty .claude/settings.json 2>/dev/null
if [ $? -ne 0 ]; then
    echo "ERROR: Invalid JSON written"
    # Restore backup
    mv .claude/settings.json.backup .claude/settings.json
    exit 1
fi

8. DISPLAY COMPLETION MESSAGE:

✅ COMPLETED: Permission Manager
───────────────────────────────────────
Settings file: .claude/settings.json
Backup saved: .claude/settings.json.backup

Changes applied:
  • {count} commands allowed
  • {count} commands denied
  • {count} existing rules preserved

Next steps:
  1. Test repo commands: /repo:branch create test-123 "test branch"
  2. Verify no prompts appear
  3. Review settings: cat .claude/settings.json

If issues occur:
  • Restore backup: mv .claude/settings.json.backup .claude/settings.json
  • Or reset: /repo:init-permissions --mode reset
───────────────────────────────────────

The permission configuration is complete when:

1. File Created/Updated:

   • .claude/settings.json exists
   • Valid JSON structure
   • Backup created (.backup file)

2. Permissions Configured:

   • All required git commands allowed
   • All required gh commands allowed
   • Dangerous commands denied
   • Existing permissions preserved

3. User Informed:

   • Changes clearly displayed
   • Confirmation received
   • Next steps provided
   • Rollback instructions given

4. Validation Passed:

   • JSON structure valid
   • No syntax errors
   • Permissions logically consistent

Success Response:

{
  "status": "success",
  "operation": "configure-permissions",
  "result": {
    "settings_file": ".claude/settings.json",
    "backup_file": ".claude/settings.json.backup",
    "changes": {
      "allowed_added": 35,
      "denied_added": 22,
      "preserved": 10
    }
  }
}

Failure Response:

{
  "status": "failure",
  "operation": "configure-permissions",
  "error": "Failed to write settings.json: Permission denied",
  "error_code": 3
}

File Permission Error:

ERROR: Cannot write to .claude/settings.json
Reason: Permission denied

Solutions:
  1. Check directory permissions: ls -la .claude/
  2. Create directory manually: mkdir -p .claude && chmod 755 .claude
  3. Run as appropriate user

Invalid JSON Error:

ERROR: Existing settings.json contains invalid JSON
Backup: .claude/settings.json.backup

Solutions:
  1. Fix JSON manually: vim .claude/settings.json
  2. Reset to defaults: /repo:init-permissions --mode reset
  3. Restore backup: mv .claude/settings.json.backup .claude/settings.json

User Cancellation:

INFO: User cancelled permission update
No changes made to settings.json

Why These Permissions:

Allowed Commands:

• git * - Core repository operations (commits, branches, etc.)
• gh pr * - Pull request lifecycle management
• gh issue * - Issue tracking integration
• cat, grep, jq - Safe read-only file operations

Denied Commands:

• rm -rf / - Filesystem destruction
• git push --force origin main - Protected branch corruption
• gh repo delete - Repository deletion
• sudo - Privilege escalation
• curl | sh - Remote code execution

Permission Philosophy:

1. Principle of Least Privilege - Only what's needed
2. Defense in Depth - Explicit denies catch mistakes
3. User Transparency - Always show what's changing
4. Easy Rollback - Backup before every change

Risk Mitigation:

• Backups created automatically
• User confirmation required
• Dangerous patterns explicitly blocked
• Validation before write
• Rollback instructions provided

Called By:

• /repo:init-permissions command
• repo-manager agent (permission operations)
• /repo:init command (optional during setup)

Calls:

• scripts/update-settings.sh - Settings file manipulation
• scripts/validate-permissions.sh - Permission validation
• Standard tools: Bash, Read, Write, jq

Creates:

• .claude/settings.json - Main settings file
• .claude/settings.json.backup - Backup before changes

Example 1: First-time Setup

INPUT: /repo:init-permissions

OUTPUT:
🔐 Permission Manager
Mode: setup
No existing settings found

Will allow: git, gh commands
Will deny: dangerous operations

[Shows full permission list]
Continue? yes

✅ Created .claude/settings.json
   61 commands allowed
   13 commands require approval
   40 commands denied

Example 2: Update Existing Settings

INPUT: /repo:init-permissions

OUTPUT:
🔐 Permission Manager
Existing settings found (backed up)

NEW ALLOWS: git tag, gh pr merge
NEW DENIES: rm -rf /, git push --force
PRESERVED: 12 existing rules

Continue? yes

✅ Updated .claude/settings.json

Example 3: Validation Mode

INPUT: /repo:init-permissions --mode validate

OUTPUT:
🔐 Validating Permissions

✓ git commands: allowed
✓ gh pr commands: allowed
✓ Dangerous commands: denied
✓ Settings file: valid JSON

All permissions correctly configured

Example 4: Reset

INPUT: /repo:init-permissions --mode reset

OUTPUT:
🔐 Resetting Permissions

This will remove all repo-specific permissions.
Continue? yes

✅ Removed repo permissions
   Restored to defaults
   Backup: .claude/settings.json.backup

Summary

This skill provides secure, transparent permission management for the repo plugin:

• Eliminates prompts - Pre-approve safe repo operations
• Prevents disasters - Explicitly deny dangerous commands
• User controlled - Always requires confirmation
• Safe updates - Backups before every change
• Easy rollback - Simple restoration if needed

The permission model follows security best practices:

• Principle of least privilege
• Defense in depth with explicit denies
• User transparency and control
• Comprehensive audit trail