enable-subagents

Enable Subagents

Help the user configure the Claude Code environment so that subagents can normally perform the operations they need.

Important principles:

Always use Traditional Chinese (zh-TW) to communicate with the user
Check first, then update, and only add missing permissions
Preserve existing configuration, and do not overwrite the user's other settings

When to use

When you need to:

Enable subagent features of skills such as pr-review-resolver
Fix the problem of subagent permissions being blocked
Configure Claude Code permissions in a new project or new environment
Ensure plugin scripts can be executed by subagents

Background

Skills such as pr-review-resolver start subagents to perform tasks. Subagents need the following permissions:

Permission	Purpose
`Read`	Read source code to verify issues
`Edit`	Modify files when fixing issues
`Write`	Write files (create or modify files when fixing issues)
`Glob`	Search file paths
`Grep`	Search file contents
`Task`	Start background subtasks
`Bash(mkdir *)`	Create necessary directories
`Bash(git *)`	Run git commands (such as `git diff`）
`Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*)`	Run plugin scripts

When these operations are performed in a subagent, the parent session must already have the corresponding permissions, otherwise they will be blocked.

Workflow

Step 1: Choose the configuration level

Use AskUserQuestion to ask the user for their preferred configuration level:

請選擇要配置權限的層級：

**User-level** (`~/.claude/settings.json`)
- 套用到所有專案
- 適合經常使用 pr-review-toolkit 的使用者

**Project-level** (`.claude/settings.json`)
- 只影響當前專案
- 適合想要限制權限範圍的使用者
- 可加入版本控制讓團隊共享

<options>
<option>User-level（套用到所有專案）</option>
<option>Project-level（只影響當前專案）</option>
</options>

Step 2: Check the existing configuration

Based on the level selected by the user, read the corresponding settings.json:

User-level: ~/.claude/settings.json
Project-level: .claude/settings.json

If the file does not exist, prepare to create a new file.

Parse the existing permissions.allow array (if it exists).

Step 3: Identify missing permissions

List of permissions that need to be configured:

[
  "Read",
  "Edit",
  "Write",
  "Glob",
  "Grep",
  "Task",
  "Bash(mkdir *)",
  "Bash(git *)",
  "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*)"
]

Compare with the existing configuration and list the missing permissions.

Step 4: Explain and confirm

Explain to the user:

If everything is already configured: tell the user the permissions are complete and no changes are needed, then end.
If there are missing permissions：
- List each permission to be added and its purpose
- Show a complete configuration preview
- Use AskUserQuestion to confirm the user agrees to the update

Example explanation format:

目前缺少以下權限：

1. `Read` - 讓 subagent 可以讀取原始碼檔案驗證問題
2. `Write` - 讓 subagent 可以寫入臨時檔案

更新後的配置將是：

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Glob",
      "Grep",
      "Task",
      "Bash(mkdir *)",
      "Bash(git *)",
      "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*)"
    ]
  }
}

<options>
<option>確認更新配置</option>
<option>取消</option>
</options>

Step 5: Update the configuration

After the user confirms:

Create directories(if needed):
- User-level: ensure ~/.claude/ exists
- Project-level: ensure .claude/ exists
Merge configuration：
- If the file already exists, read and parse the JSON
- Preserve all existing settings
- Only add permissions.allow missing items in
- Do not delete or overwrite any existing permissions
Write the configuration：
- Use correct JSON format (2-space indentation)
- Ensure the file ends with a newline

Step 6: Verify and Notify

Re-read the configuration file to confirm the changes succeeded
Display the final configuration summary
Prompt the user: "The configuration has been updated. If Claude Code is running, it may need to be restarted to apply the new permissions."

Configuration Examples

Minimal configuration (newly created)

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Glob",
      "Grep",
      "Task",
      "Bash(mkdir *)",
      "Bash(git *)",
      "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*)"
    ]
  }
}

Merge into existing configuration

Assume the existing configuration:

{
  "theme": "dark",
  "permissions": {
    "allow": [
      "Read",
      "Bash(git *)"
    ]
  }
}

After updating:

{
  "theme": "dark",
  "permissions": {
    "allow": [
      "Read",
      "Bash(git *)",
      "Edit",
      "Write",
      "Glob",
      "Grep",
      "Task",
      "Bash(mkdir *)",
      "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*)"
    ]
  }
}

Error Handling

JSON parsing failure: Notify the user that the existing configuration file format is incorrect, and ask whether to back it up and rebuild
Write failure: Display an error message and suggest checking directory permissions
User cancels: Confirm that no changes will be made and end the skill

Verification Checklist

Before completing the configuration, confirm:

The user has selected the configuration level (User-level or Project-level)
The existing configuration has been read correctly (if it exists)
Only missing permissions were added, and existing settings were not overwritten
The user has confirmed the changes
The configuration file has been written successfully
The changes have been verified as effective
The user has been prompted that Claude Code may need to be restarted

Post-Completion Verification

After the configuration is complete, suggest that the user:

Run /pr-review-resolver to test whether the subagent works properly
If permission issues persist, check whether Claude Code needs to be restarted

Success indicators:

The subagent can read and edit files without permission prompts appearing
Plugin scripts can run normally
There is no need to manually confirm permissions on every subagent operation