[DOCS] WorktreeCreate hook stdin field is `name`, not the documented `worktree_path`

Open 💬 0 comments Opened Jul 14, 2026 by wshallwshall

Summary

The hooks reference documents the WorktreeCreate stdin payload as containing worktree_path:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "hook_event_name": "WorktreeCreate",
  "worktree_path": "/path/where/worktree/should/be/created"
}

There is no worktree_path field. The actual field is name, and it carries the worktree name, not a path.

A hook written against the documented schema silently reads an empty value. Because WorktreeCreate aborts on any non-zero exit, the failure surfaces as Error creating worktree: WorktreeCreate hook failed: <command>: no output — which gives no hint that the payload field simply doesn't exist.

Environment

Claude Code 2.1.207, native install, Windows 11.

Actual payload

Captured by teeing stdin to a file from inside the hook (claude -p --worktree wt-hooked):

{
  "session_id": "412cbaa3-…",
  "transcript_path": "C:\\Users\\…\\.claude\\projects\\…-repo\\412cbaa3-….jsonl",
  "cwd": "C:\\Users\\…\\repo",
  "hook_event_name": "WorktreeCreate",
  "name": "wt-hooked"
}

So: session_id, transcript_path, cwd, hook_event_name are all as documented — only worktree_path is wrong, and it's replaced by name.

Suggested fix

Either document the real field:

| Field | Description |
|---|---|
| name | The requested worktree name (not a path). The hook chooses the location and prints it on stdout. |

...or add worktree_path alongside name, since a hook that just wants the default location currently has to reconstruct <repo>/.claude/worktrees/<name> by hand.

A one-line note that the hook is responsible for deciding the path (rather than being handed one) would also help — that's the part the current wording obscures.

View original on GitHub ↗