Skip to content

hooks: SessionStart format expects array wrapper for hooks property #16637

@RizwanHamid

Description

@RizwanHamid

Description

After a recent Claude Code update, the hooks configuration format appears to have changed. The settings validation now rejects the previously-working format.

Error Message

Settings Error

/home/riz/.claude/settings.json
 └ hooks
   └ SessionStart
     └ 0
       └ hooks: Expected array, but received undefined

Hooks use a new format with matchers. Example: {"PostToolUse": [{"matcher": {"tools": ["BashTool"]}, "hooks": [{"type": "command", "command": "echo Done"}]}]}
Learn more: https://code.claude.com/docs/en/hooks

Current Configuration (Breaking)

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "$HOME/.claude/hooks/session-start.sh",
        "timeout": 30
      }
    ]
  }
}

Expected Configuration (New Format)

Based on the error message, the new format appears to require:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.claude/hooks/session-start.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Questions

  1. Is this a breaking change in the hooks schema?
  2. For session-level events (SessionStart, Stop) that don't have tool matchers, what should the outer object contain besides hooks?
  3. Has the matcher format changed from string ("Bash") to object ({"tools": ["Bash"]})?

Environment

  • Claude Code CLI (latest)
  • Ubuntu Linux

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:corebugSomething isn't workinghas reproHas detailed reproduction stepsplatform:linuxIssue specifically occurs on Linux

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions