diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
index 93dfbb3a2b..55eeb0cefb 100644
--- 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
index 4fe0310cc9..c300eb6eb9 100644
--- 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
index f39e52e3e2..3f4810b4f0 100644
--- 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
diff --git a/pkg/workflow/js/check_workflow_timestamp.cjs b/pkg/workflow/js/check_workflow_timestamp.cjs
index bb8fe998c0..07a77f3797 100644
--- a/pkg/workflow/js/check_workflow_timestamp.cjs
+++ b/pkg/workflow/js/check_workflow_timestamp.cjs
@@ -69,7 +69,7 @@ async function main() {
   // Check if workflow file is newer than lock file
   if (workflowMtime > lockMtime) {
     const warningMessage = `🔴🔴🔴 WARNING: Lock file '${lockFile}' is outdated! The workflow file '${workflowFile}' has been modified more recently. Run 'gh aw compile' to regenerate the lock file.`;
-    
+
     core.error(warningMessage);
 
     // Add summary to GitHub Step Summary