Document --tools flag investigation for Claude Code CLI v2.0.31

[Copilot]

Claude Code CLI v2.0.31 introduced a --tools flag for simple tool specification. Investigated whether gh-aw should migrate from --allowed-tools to the new flag.

Decision

Continue using --allowed-tools. The new --tools flag only supports basic tool names ("Bash,Edit,Read") without pattern support.

Why --allowed-tools is Required

gh-aw needs fine-grained patterns that --tools cannot provide:

• 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/*)

Example from current implementation:

// Claude engine generates patterns like:
allowedTools := "Bash(ls),Edit,mcp__github__get_issue,Read(/tmp/gh-aw/cache-memory/*)"
claudeArgs = append(claudeArgs, "--allowed-tools", allowedTools)

Changes

• Code documentation: Added inline comments in claude_engine.go and claude_tools.go explaining flag choice
• User documentation: Added note to engines.md explaining --tools vs --allowed-tools tradeoffs

Flag Comparison

Capability	--tools	--allowed-tools
Basic tools	✅	✅
Command patterns	❌	✅
MCP prefixes	❌	✅
Path restrictions	❌	✅

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[ca] Update Claude Code CLI to v2.0.31</issue_title>
<issue_description># Update Claude Code CLI to v2.0.31

Summary

Claude Code has been updated from 2.0.30 → 2.0.31. This update includes a new CLI flag for tool specification.

Version Details

• Previous: 2.0.30
• New: 2.0.31
• Released: 2025-10-31 (redacted) UTC (Oct 31, 2025 at (redacted) PM UTC)
• Time Since Previous: ~1 day (2.0.30 was released Oct 30, 2025)

Changes

New Features

New CLI Flag: --tools

• Description: Specify the list of available tools from the built-in set
• Usage: --tools <tools...>
• Options:
  • "" - Disable all tools
  • "default" - Use all tools
  • Tool names - e.g. "Bash,Edit,Read"
• Constraint: Only works with --print mode
• Impact: Provides fine-grained control over which tools are available during non-interactive execution

Breaking Changes

None detected.

Bug Fixes

Not specified in release notes.

Security Updates

No CVEs or security patches mentioned.

CLI Discovery

New command-line flag identified via claude --help comparison:

+ --tools <tools...>                                Specify the list of available tools from the built-in set. Use "" to disable all tools, "default" to use all tools, or specify tool names (e.g. "Bash,Edit,Read"). Only works with --print mode.

Previous help output: /tmp/gh-aw/cache-memory/claude-code-2.0.30-help.txt
Current help output: /tmp/gh-aw/cache-memory/claude-code-2.0.31-help.txt

Impact Assessment

• Risk Level: Low
• Affected Features:
  • Claude engine execution in --print mode
  • Tool restriction/allowance during non-interactive sessions
• Migration Required: No
• gh-aw Compatibility: Fully compatible - new flag is optional

Files Modified

• pkg/constants/constants.go - Updated DefaultClaudeCodeVersion constant
• 22 workflow .lock.yml files - Recompiled with new version

Verification

✅ make recompile completed (64/65 workflows compiled successfully)
✅ Git status shows 23 files modified (1 constants + 22 workflows)
✅ No breaking changes detected
✅ Help output cached for future comparisons

Note: 1 workflow compilation error (changeset-generator.firewall.md) is unrelated to this version update - it's a pre-existing issue.

Changelog Links

• NPM Package: https://www.npmjs.com/package/`@anthropic-ai/claude-code`/v/2.0.31
• NPM View: npm view @anthropic-ai/claude-code@2.0.31

Recommendations

1. ✅ Update constants file (completed)
2. ✅ Recompile workflows (completed)
3. ⏳ Review and merge this update
4. 📝 Consider documenting the new --tools flag in Claude engine documentation if we expose it to users
5. 🧪 Test the new flag in non-interactive mode if relevant to gh-aw workflows

Intermediate Versions

Only one version between 2.0.30 and 2.0.31:

• 2.0.31 (2025-10-31 (redacted) UTC) - Current update

Context

• Repository: githubnext/gh-aw
• Workflow Run: #18998462979
• Date: 2025-11-01

AI generated by CLI Version Checker</issue_description>

Comments on the Issue (you are @copilot in this section)

@pelikhan /scout investigate the use of --tools in the Claude agentic engine

• Fixes [ca] Update Claude Code CLI to v2.0.31 #2938

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull Request Overview

This PR improves code documentation and formatting by adding comprehensive comments explaining the rationale for using --allowed-tools over the simpler --tools flag in Claude Code CLI integration, and removes trailing whitespace.

• Added detailed documentation explaining why --allowed-tools is used instead of the newer --tools flag
• Documented the fine-grained control capabilities that --allowed-tools provides for security and flexibility
• Removed trailing whitespace in JavaScript file

Reviewed Changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated no comments.

File	Description
pkg/workflow/js/check_workflow_timestamp.cjs	Removed trailing whitespace from line 72
pkg/workflow/claude_tools.go	Added function documentation explaining --allowed-tools rationale and usage
pkg/workflow/claude_engine.go	Added inline comment explaining why --allowed-tools is preferred over --tools
docs/src/content/docs/reference/engines.md	Added user-facing documentation note comparing --allowed-tools vs --tools

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.