Permission parser incorrectly validates bash heredoc content

Bug Report: Permission Parser Incorrectly Validates Bash Heredoc Content

Environment

• Claude Code Version: 2.1.39
• Platform: macOS (Darwin 25.2.0)
• Project: /Users/jmw/dev/advisors

Summary

The permission parser scans conversation history files (.jsonl) and incorrectly treats bash heredoc content as permission patterns, applying :* validation rules to heredoc delimiters and content. This results in validation errors and conversation files being skipped.

Error Message

PART2_EOF)": The :* pattern must be at the end. Move :* to the end for prefix
matching, or use * for wildcard matching. Examples: Bash(npm run:*) - prefix
matching (legacy), Bash(npm run *) - wildcard matching

Files with errors are skipped entirely, not just the invalid settings.

Description

When Claude Code scans old conversation files looking for granted permissions, it encounters bash commands that use heredocs (e.g., cat <<'PART2_EOF' > file.js). The parser incorrectly interprets:

1. The heredoc delimiter (e.g., PART2_EOF)) as part of a permission pattern
2. Content within the heredoc that may contain :* characters
3. Applies the stricter :* validation rules (requiring :* to be at the end)

This causes the parser to reject the entire conversation file with validation errors.

Expected Behavior

• Bash heredoc content should be excluded from permission pattern validation
• Only the actual bash command structure (not heredoc content) should be parsed for permissions
• Heredoc delimiters should not be interpreted as permission pattern syntax

Actual Behavior

• Parser validates heredoc delimiters and content as if they were permission patterns
• Throws validation error: "The :* pattern must be at the end"
• Skips entire conversation files with the error message: "Files with errors are skipped entirely"
• Error text includes snippets of heredoc content mixed with validation messages

Steps to Reproduce

1. Execute a bash command using a heredoc delimiter containing specific text:

``bash
cat <<'PART2_EOF' > file.js
export default mockGeneratedDocuments;
PART2_EOF
``

1. Approve the command when prompted
2. Complete the conversation
3. Start a new Claude Code session or wait for conversation file scanning
4. Parser scans old conversation .jsonl files and throws validation error

Impact

• Severity: Medium (non-blocking but confusing)
• Validation warnings appear in Claude Code output
• Old conversation files are skipped during permission scanning
• Users may be confused by error messages showing heredoc content

Workaround

Delete affected conversation .jsonl files:

# Find affected files
grep -l "PART2_EOF" ~/.claude/projects/<project>/*.jsonl

# Remove them
rm -f ~/.claude/projects/<project>/<session-id>.jsonl
rm -rf ~/.claude/projects/<project>/<session-id>/

Root Cause Analysis

The stricter :* validation introduced in recent Claude Code versions is being applied retroactively to conversation history. When the parser encounters bash commands with heredocs in old conversations:

1. It doesn't properly parse bash heredoc syntax
2. It treats heredoc delimiters as part of the permission pattern
3. It applies pattern validation rules to heredoc content
4. This creates false positives for the :* position validation

Suggested Fix

• Update permission parser to recognize and skip bash heredoc syntax
• Add heredoc boundary detection (e.g., <<'EOF', <<EOF, <<-EOF)
• Exclude content between heredoc delimiters from pattern validation
• Only validate the actual command structure, not heredoc content

Additional Context

The error was discovered when cleaning up old conversation files. Multiple session files contained this error related to bash commands that wrote TypeScript/JavaScript files using heredocs with delimiters like PART1_EOF and PART2_EOF.

Files Affected

In testing, 4 conversation files were found with this issue:

• 7ad735cc-b1dd-4cd2-a38e-889f958000d9.jsonl
• 9abcda8b-b160-4bf4-a00a-48e55ef05ddf.jsonl
• 99471ef8-adb5-40c8-b3eb-3fa0fbda6c9b.jsonl
• 6243a8d2-107d-4e7e-a7d9-ac46e3cd6b9a.jsonl

All contained bash heredoc commands that triggered the validation error.