claude-code - 💡(How to fix) Fix [FEATURE] Add `platform` field to hooks for OS-conditional execution

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

When .claude/settings.json is committed to a cross-platform monorepo, hooks using shell-specific syntax fail on the "wrong" OS. A SessionStart hook checking for a CLI tool needs two variants — bash for macOS/Linux, PowerShell for Windows. On macOS the PowerShell hook errors out, on Windows the bash hook errors out. Both errors are harmless but noisy and confusing.

Proposed Solution

Add an optional platform field to hook definitions. Accepted values: "darwin", "win32", "linux" (matching Node.js process.platform), or an array like ["darwin", "linux"]. If omitted, the hook runs on all platforms — fully backward-compatible, zero breaking changes. Implementation is a single process.platform check before executing each hook.

Alternative Solutions

1. Write a wrapper script that detects OS internally — adds complexity, another file to maintain
2. Duplicate hooks for both shells and ignore errors — current workaround, works but produces confusing error output on every session start
3. Use only bash everywhere — not viable, PowerShell is the native shell on Windows and some commands have no bash
   equivalent.

Priority

Low - Nice to have

Feature Category

Configuration and settings

Use Case Example

A cross-platform monorepo has this in .claude/settings.json:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup|resume",
      "hooks": [
        {
          "type": "command",
          "command": "command -v bun >/dev/null 2>&1 || echo 'WARNING: bun not found'",
          "shell": "bash"
        },
        {
          "type": "command",
          "command": "if (-not (Get-Command bun -ErrorAction SilentlyContinue)) { Write-Host 'WARNING: bun not found'
}",
          "shell": "powershell"
        }
      ]
    }]
  }
}

With a platform field, this becomes clean and error-free:

{
  "type": "command",
  "command": "command -v bun >/dev/null 2>&1 || echo 'WARNING: bun not found'",
  "shell": "bash",
  "platform": ["darwin", "linux"]
},
{
  "type": "command",
  "command": "if (-not (Get-Command bun ...)) { Write-Host 'WARNING: ...' }",
  "shell": "powershell",
  "platform": "win32"
}

Additional Context

• Values should match Node.js process.platform: "darwin", "win32", "linux" (or an array)
  • If platform is omitted, the hook runs on all platforms (fully backward-compatible)
  • Implementation is trivial: a single process.platform check before hook execution
  • Related: #4446 requested broader conditional hooks but was closed. This is a much narrower, immediately useful
    subset
  • This affects any team sharing .claude/settings.json across macOS/Windows/Linux developers