Document --tools flag investigation for Claude Code CLI v2.0.31 (#2947)

Copilot · web-flow · commit 258cb9f66cbb · 2025-11-01T10:32:18.000-07:00
diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
@@ -168,6 +168,16 @@ gh secret set ANTHROPIC_API_KEY -a actions --body "<your-anthropic-api-key>"
 gh secret set GH_AW_GITHUB_TOKEN -a actions --body "<your-github-pat>"
 ```
 
+:::note[Tool Specification: `--allowed-tools` vs `--tools`]
+Claude Code CLI v2.0.31 introduced a simpler `--tools` flag for basic tool specification (e.g., `--tools "Bash,Edit,Read"`). However, gh-aw uses the more powerful `--allowed-tools` flag which supports:
+
+- **Specific bash commands**: `Bash(git:*)`, `Bash(ls)`
+- **MCP tool prefixes**: `mcp__github__get_issue`, `mcp__github__*`
+- **Path-specific access**: `Read(/tmp/gh-aw/cache-memory/*)`
+
+The `--tools` flag is too simplistic for gh-aw's fine-grained security and flexibility requirements. Tool permissions are automatically configured based on your workflow's `tools:` section.
+:::
+
 ### OpenAI Codex
 
 OpenAI Codex CLI with MCP server support. Designed for code-focused tasks.
diff --git a/pkg/workflow/claude_engine.go b/pkg/workflow/claude_engine.go
@@ -108,6 +108,12 @@ func (e *ClaudeEngine) GetExecutionSteps(workflowData *WorkflowData, logFile str
 	}
 
 	// Add allowed tools configuration
+	// Note: Claude Code CLI v2.0.31 introduced a simpler --tools flag, but we continue to use
+	// --allowed-tools because it provides fine-grained control needed by gh-aw:
+	// - Specific bash commands: Bash(git:*), Bash(ls)
+	// - MCP tool prefixes: mcp__github__get_issue
+	// - Path-specific tools: Read(/tmp/gh-aw/cache-memory/*)
+	// The --tools flag only supports basic tool names (e.g., "Bash,Edit,Read") without patterns.
 	allowedTools := e.computeAllowedClaudeToolsString(workflowData.Tools, workflowData.SafeOutputs, workflowData.CacheMemoryConfig)
 	if allowedTools != "" {
 		claudeArgs = append(claudeArgs, "--allowed-tools", allowedTools)
diff --git a/pkg/workflow/claude_tools.go b/pkg/workflow/claude_tools.go
@@ -97,7 +97,15 @@ func (e *ClaudeEngine) expandNeutralToolsToClaudeTools(tools map[string]any) map
 	return result
 }
 
-// computeAllowedClaudeToolsString
+// computeAllowedClaudeToolsString generates the tool specification string for Claude's --allowed-tools flag.
+//
+// Why --allowed-tools instead of --tools (introduced in v2.0.31)?
+// While --tools is simpler (e.g., "Bash,Edit,Read"), it lacks the fine-grained control gh-aw requires:
+// - Specific bash commands: Bash(git:*), Bash(ls)
+// - MCP tool prefixes: mcp__github__get_issue, mcp__github__*
+// - Path-specific access: Read(/tmp/gh-aw/cache-memory/*)
+//
+// This function:
 // 1. validates that only neutral tools are provided (no claude section)
 // 2. converts neutral tools to Claude-specific tools format
 // 3. adds default Claude tools and git commands based on safe outputs configuration
