anthropics / anthropics/claude-code

docs: hooks-guide auto-format example breaks on paths with spaces and exits 2 on unsupported files — contradicts the bundled update-config skill

Abierto Apto para principiantes
#88,188 1 comentario 0 reacciones 0 asignados Ver en GitHub
area:hooks bug documentation has repro
Lenguaje dominante
Python
Estrellas
145k
Forks
23.1k
Métricas de merge de PR
Métricas de PR pendientes

Descripción

## Summary

The "Auto-format code after edits" example in [hooks-guide](https://code.claude.com/docs/en/hooks-guide#auto-format-code-after-edits) has two defects. It appears twice on the page and is the first hook pattern most people copy.

```json
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
```

Both failures are silent or noisy in ways that surface long after the user has stopped watching the hook.

## Defect 1 — `xargs` word-splits paths containing spaces

`xargs` splits on whitespace, so one file becomes several nonexistent paths.

```console
$ echo '{"tool_input":{"file_path":"/tmp/carpeta con espacios/a.ts"}}' \
| jq -r '.tool_input.file_path' | xargs printf '[%s]\n'
[/tmp/carpeta]
[con]
[espacios/a.ts]

$ echo '{"tool_input":{"file_path":"/tmp/carpeta con espacios/a.ts"}}' \
| jq -r '.tool_input.file_path' | xargs ls
ls: /tmp/carpeta: No such file or directory
ls: con: No such file or directory
ls: espacios/a.ts: No such file or directory
```

Control: with a path that has no spaces, `xargs` works correctly. The bug is therefore intermittent by nature — the hook appears to work for months until someone edits a file under `My Project/`.

The page contains **no** warning about spaces or word-splitting. Searched the full 71 KB of the rendered page: zero occurrences of `read -r`, and nothing about quoting near the example. The only related note is 900 lines away under troubleshooting ("command not found"), suggesting `"args": []` for exec form.

## Defect 2 — no `--ignore-unknown`, so unsupported files exit 2

`exit 2` is the _blocking error_ code for hooks: stderr is fed back to Claude.

```console
$ prettier --write s.py ; echo "exit=$?"
[error] No parser could be inferred for file ".../s.py".
exit=2

$ prettier --write --ignore-unknown s.py ; echo "exit=$?"
exit=0
```

The documented command has neither `--ignore-unknown` nor `|| true`. In any polyglot repository, every edit to a `.py`, `.sh`, `.toml`, or any file Prettier has no parser for makes the hook return a blocking error on an operation that succeeded.

## Defect 3 (minor) — `npx` can hit the network

`npx prettier` with no local copy resolves by downloading from the registry. On a machine whose global Prettier lives inside an nvm release, a Node version bump removes it from `PATH` and this hook silently starts fetching Prettier on every edit.

## This contradicts a bundled first-party source

The `update-config` skill that ships with Claude Code prescribes the opposite, explicitly:

> use `jq -r` into a quoted variable or `{ read -r f; ... "$f"; }`, **NOT** unquoted `| xargs` (splits on spaces)

Two official sources of the same product disagree, and the more visible one is the incorrect one.

## Suggested fix

```json
"command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; npx prettier --write --ignore-unknown \"$f\"; } || true"
```

- `read -r` into a quoted variable — no word-splitting
- `--ignore-unknown` — unsupported files are skipped silently instead of exiting 2 (also honours `.prettierignore`)
- `|| true` — a formatter should not turn a successful edit into a hook error
- `.tool_response.filePath` first, matching the fallback the `update-config` skill uses

A one-line note that paths may contain spaces would also help readers who adapt the pattern to other formatters.

## Environment

- Claude Code 2.1.237
- macOS (arm64), APFS
- Prettier 3.9.6
- `jq` via Homebrew

## Also worth checking

The page states "When the hook succeeds, Claude Code shows nothing in the conversation." In practice a `PostToolUse` hook that rewrites the edited file surfaces a `PostToolUse hook modified after your edit (likely a formatter)` notice. I have not isolated the exact conditions, so this is an observation rather than a confirmed claim — but the sentence may be worth revisiting, since that notice is genuinely useful and users are being told it does not exist.

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Línea de trabajo

Start at the “Auto-format code after edits” example in hooks-guide, which appears twice, and compare it with the bundled update-config skill’s quoting guidance. Reproduce the reported space-containing path and unsupported-file cases, then update both copies so paths are preserved and unsupported files do not create blocking hook errors; verify the surrounding success wording against confirmed behavior.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
nodejs, shell
Área
documentation
Tipo de issue
Documentación
Dificultad
2/5
Tiempo estimado
1-3 horas
Estado de actividad
Activo
Claridad
Bastante claro
Aptitud para principiantes
76/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.