From 61f11bd0b84425def91631f214da09fb49404843 Mon Sep 17 00:00:00 2001
From: Sebastian Iancu <sebastian-iancu@users.noreply.github.com>
Date: Tue, 27 Oct 2026 14:10:21 +0100
Subject: [PATCH 1/2] fix(hooks): read the workspace from Cursor plugin hooks

A Cursor plugin hook runs in the plugin install and only accepts
additional_context from sessionStart. session-start now inspects
CURSOR_PROJECT_DIR, and format-on-save finds the fixer config there.
The formatter stays on afterFileEdit.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 AGENTS.md               |  6 +++---
 CHANGELOG.md            |  3 +++
 docs/authoring.md       |  2 +-
 docs/install.md         |  2 +-
 docs/testing.md         |  2 +-
 hooks/cursor-hooks.json |  7 +++++--
 hooks/format-on-save.sh | 14 +++++++++++++-
 hooks/session-start.sh  | 29 ++++++++++++++++++++++++-----
 scripts/validate.py     | 15 ++++++++++++---
 9 files changed, 63 insertions(+), 17 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 4d8c822..286c5de 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -50,8 +50,8 @@ Update each hit. Keep release numbers and "checked" dates in `## Sources` sectio
 - **Agent**: `agents/php-reviewer.md`. Report-only, no sub-agent dispatch. Its `tools:` include `Skill` so it can load `php-coding`.
 - **Cursor rule**: `rules/php-context.mdc` (`globs: ["**/*.php"]`) mirrors the index table.
 - **Claude hooks**: `hooks/hooks.json` wires `SessionStart` and `PostToolUse` (`matcher: "Write|Edit"`) to the shared scripts as `bash "${CLAUDE_PLUGIN_ROOT}/hooks/<script>.sh"`.
-- **Cursor hooks**: `hooks/cursor-hooks.json` wires `sessionStart` and `afterFileEdit` to the same scripts with a workspace-relative command.
-- **Shared hook scripts**: `hooks/session-start.sh` detects `composer.json` or a `*.php` file, prints one line, and names the library references whose packages appear in `composer.json` (and Laravel Boost for `laravel/framework`). `hooks/format-on-save.sh` reads the edited path from the host's stdin JSON (`tool_input.file_path` on Claude Code, `file_path` on Cursor) and runs `php-cs-fixer fix` on a `*.php` file when a project config and a fixer binary exist. Both always exit 0.
+- **Cursor hooks**: `hooks/cursor-hooks.json` (`"version": 1`) wires `sessionStart` and `afterFileEdit`. Commands are relative to the plugin install (`bash hooks/session-start.sh`), not `${CLAUDE_PLUGIN_ROOT}`.
+- **Shared hook scripts**: `hooks/session-start.sh` detects `composer.json` or a `*.php` file, prints one line, and names the library references whose packages appear in `composer.json` (and Laravel Boost for `laravel/framework`). On Cursor it inspects `CURSOR_PROJECT_DIR` and prints JSON `additional_context`. `hooks/format-on-save.sh` reads the edited path from the host's stdin JSON (`tool_input.file_path` on Claude Code, `file_path` on Cursor `afterFileEdit`) and runs `php-cs-fixer fix` on a `*.php` file when a project config and a fixer binary exist. On Cursor it looks for that config in `CURSOR_PROJECT_DIR`, not the plugin install. `afterFileEdit` is the right event for the formatter: it has no output, and the script only rewrites the file. Both always exit 0.
 - **Reference lint config**: top-level `references/php-cs-fixer.php`, `references/phpstan.neon`, `references/rector.php` (Rector optional, default-off). This is a different directory from `skills/php-coding/references/`.
 - **Eval suite**: `evals/<case>/` with `prompt.md` and `graders/`, run by `claude plugin eval`. Results go to `evals/results/`, which is gitignored.
 - **Validation**: `scripts/validate.sh` wraps the stdlib-only `scripts/validate.py`. CI (`.github/workflows/validate.yml`) installs Python 3 and runs it on pushes to `main` and on pull requests.
@@ -131,7 +131,7 @@ When a dated version fact changes, follow [Refreshing a dated fact](#refreshing-
 - **Quote `${CLAUDE_PLUGIN_ROOT}` in Claude hook commands.** A plugin path that contains a space splits into several words. `claude plugin validate .` warns on the unquoted form.
 - **A Claude hook `timeout` is in seconds, not milliseconds.** The default for a command hook is 600. — <https://code.claude.com/docs/en/hooks>
 - **Hook scripts get the edited path from stdin.** Claude Code sends it as `tool_input.file_path` and documents no `CLAUDE_FILE_PATH` variable. Keep the stdin parsing in `format-on-save.sh`.
-- **The Cursor hook uses a workspace-relative command** (`bash hooks/session-start.sh`), *not* `${CLAUDE_PLUGIN_ROOT}`. Cursor's plugin docs, checked 2026-09-30, do not say how a plugin hook path resolves. Confirm both hooks fire in a PHP workspace other than this repo.
+- **The Cursor hook command is relative to the plugin install** (`bash hooks/session-start.sh`), *not* `${CLAUDE_PLUGIN_ROOT}`. A plugin hook's working directory is that install, so `session-start.sh` and `format-on-save.sh` move to `CURSOR_PROJECT_DIR` before they read the workspace. Confirm both hooks fire in a PHP workspace other than this repo.
 - **An unquoted `: ` or ` #` in a frontmatter value is invalid YAML** (YAML 1.2.2, section 7.3.3). `scripts/validate.py` is the only check that catches it; `claude plugin validate` passed such a skill in a test on CLI 2.1.283. — <https://yaml.org/spec/1.2.2/#733-plain-style>
 - **The fixer lags PER.** `@PER-CS` still means PER 3.0. Do not claim the fixer enforces a 3.1 rule; `style.md` lists them.
 - **`AGENTS.md` and `.github/` are export-ignored** in `.gitattributes`. A shipped skill, reference, agent, rule, or hook must not depend on them.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4ae0d29..6c1ff8c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,9 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve
 
 ## [Unreleased]
 
+### Fixed
+- Hooks: Cursor `session-start.sh` reads `CURSOR_PROJECT_DIR` and returns `additional_context`. `format-on-save.sh` looks for the fixer config in that directory and stays on `afterFileEdit`. `hooks/cursor-hooks.json` has `"version": 1`.
+
 ## [0.2.0] - 2026-10-19
 
 ### Changed
diff --git a/docs/authoring.md b/docs/authoring.md
index f115c8a..64ee943 100644
--- a/docs/authoring.md
+++ b/docs/authoring.md
@@ -55,7 +55,7 @@ Each case is a directory with `prompt.md` and a `graders/` folder ([plugin evals
 
 ## Dual-host parity
 
-Skills and agents are shared. The **Cursor** manifest (`.cursor-plugin/plugin.json`) declares each component path. **Claude** discovers the default folders automatically. Keep `name`, `version`, `description`, and `author` identical across the two manifests. The Claude hook command quotes the placeholder (`bash "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"`). The Cursor hook command is workspace-relative (`bash hooks/session-start.sh`), never `${CLAUDE_PLUGIN_ROOT}`.
+Skills and agents are shared. The **Cursor** manifest (`.cursor-plugin/plugin.json`) declares each component path. **Claude** discovers the default folders automatically. Keep `name`, `version`, `description`, and `author` identical across the two manifests. The Claude hook command quotes the placeholder (`bash "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"`). The Cursor hook command is relative to the plugin install (`bash hooks/session-start.sh`), never `${CLAUDE_PLUGIN_ROOT}`. `hooks/cursor-hooks.json` has `"version": 1`. The formatter stays on `afterFileEdit`.
 
 ## Before committing
 
diff --git a/docs/install.md b/docs/install.md
index ee8c7ea..b194efc 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -51,4 +51,4 @@ Installing the plugin needs no PHP toolchain. Enforcement does. The pin is **PHP
 
 `/php-lint-setup` writes the reference config. Install the binaries with Composer in the target repo, for example `friendsofphp/php-cs-fixer`, `phpstan/phpstan:^2`, and `phpunit/phpunit:^12.5`. Download PHP from <https://www.php.net/downloads.php>.
 
-The format-on-save hook looks for `.php-cs-fixer.php` (or `.php-cs-fixer.dist.php`) in the working directory and for `vendor/bin/php-cs-fixer` or `php-cs-fixer` on `PATH`. It does not install them.
+The format-on-save hook looks for `.php-cs-fixer.php` (or `.php-cs-fixer.dist.php`) in the workspace and for `vendor/bin/php-cs-fixer` or `php-cs-fixer` on `PATH`. On Cursor the hook runs in the plugin install, so it changes to `CURSOR_PROJECT_DIR` first. It does not install the fixer.
diff --git a/docs/testing.md b/docs/testing.md
index e0bf365..28d87c7 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -45,6 +45,6 @@ Load a working copy (see [install.md](install.md)), then:
 - **`php-reviewer`** — a review request loads `php-coding`, reads the references the diff maps to, returns severity-ranked findings, and does not edit or spawn agents.
 - **`/php-lint-setup`** — writes the reference config and does not overwrite an existing file unprompted.
 - **Cursor rule** — open a `.php` file and confirm `php-context.mdc` attaches.
-- **Cursor hooks** — in a PHP workspace other than this repo, confirm the session-start line prints and a `.php` edit is reformatted. Cursor does not document how a plugin hook's relative command path resolves, so this is the only check that it works.
+- **Cursor hooks** — in a PHP workspace other than this repo, confirm the session-start line reaches the agent as `additional_context` (it names `/php-coding`) and a `.php` edit is reformatted. The formatter stays on `afterFileEdit`. The hook runs in the plugin install and reads the project from `CURSOR_PROJECT_DIR`.
 
 After editing content, reinstall or restart the session.
diff --git a/hooks/cursor-hooks.json b/hooks/cursor-hooks.json
index ccde61e..4bbe2ba 100644
--- a/hooks/cursor-hooks.json
+++ b/hooks/cursor-hooks.json
@@ -1,13 +1,16 @@
 {
+  "version": 1,
   "hooks": {
     "sessionStart": [
       {
-        "command": "bash hooks/session-start.sh"
+        "command": "bash hooks/session-start.sh",
+        "timeout": 10
       }
     ],
     "afterFileEdit": [
       {
-        "command": "bash hooks/format-on-save.sh"
+        "command": "bash hooks/format-on-save.sh",
+        "timeout": 20
       }
     ]
   }
diff --git a/hooks/format-on-save.sh b/hooks/format-on-save.sh
index 38a50d2..774e4d0 100755
--- a/hooks/format-on-save.sh
+++ b/hooks/format-on-save.sh
@@ -20,11 +20,23 @@ f="${CLAUDE_FILE_PATH:-}"
 if [ -z "$f" ] && [ ! -t 0 ]; then
   payload="$(cat)"
   f="$(printf '%s' "$payload" \
-        | grep -oE '"file_?[Pp]ath"[[:space:]]*:[[:space:]]*"[^"]+"' \
+        | grep -oE '"(file_?[Pp]ath|path)"[[:space:]]*:[[:space:]]*"[^"]+"' \
         | head -n1 \
         | sed -E 's/.*"([^"]+)"$/\1/')"
 fi
 
+# Cursor plugin hooks run in the plugin install. The fixer config and vendor
+# binary live in the workspace, which CURSOR_PROJECT_DIR names.
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
+  cd "${CURSOR_PROJECT_DIR:-.}" 2>/dev/null || exit 0
+fi
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ] && [ -n "${CURSOR_PROJECT_DIR:-}" ]; then
+  case "$f" in
+    /*|"") ;;
+    *) f="${CURSOR_PROJECT_DIR%/}/$f" ;;
+  esac
+fi
+
 [ -n "$f" ] || exit 0
 case "$f" in *.php) ;; *) exit 0 ;; esac
 [ -f "$f" ] || exit 0
diff --git a/hooks/session-start.sh b/hooks/session-start.sh
index 5dc1aea..719a82c 100755
--- a/hooks/session-start.sh
+++ b/hooks/session-start.sh
@@ -1,9 +1,20 @@
 #!/usr/bin/env bash
-# SessionStart hook (host-agnostic): print one PHP-standards context line when a PHP
-# workspace is detected, naming the php-coding references that match composer.json.
-# Always exits 0 so the assistant reads stdout and is never blocked.
+# SessionStart (Claude Code) / sessionStart (Cursor) hook: print one PHP-standards context
+# line when a PHP workspace is detected, naming the php-coding references that match
+# composer.json. Always exits 0.
+#
+# Claude Code runs the hook in the project directory and reads plain stdout.
+# Cursor runs a plugin hook from the plugin install and reads additional_context
+# from JSON, so there the hook moves to CURSOR_PROJECT_DIR.
 set -u
 
+# CURSOR_PLUGIN_ROOT is set only for a Cursor plugin hook.
+cursor=""
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
+  cursor=1
+  cd "${CURSOR_PROJECT_DIR:-.}" 2>/dev/null || exit 0
+fi
+
 is_php_workspace() {
   [ -f composer.json ] && return 0
   # Bounded search so session start stays fast; ignore vendor/ and .git/.
@@ -30,13 +41,21 @@ library_refs() {
 }
 
 if is_php_workspace; then
-  line="› PHP workspace detected: php-coding standards apply (PHP 8.4 pin, PER Coding Style 3.1, php-cs-fixer @PER-CS, PHPStan level 8). Load the php-coding skill and read the reference each change maps to."
+  if [ -n "$cursor" ]; then
+    line="› PHP workspace detected: php-coding standards apply (PHP 8.4 pin, PER Coding Style 3.1, php-cs-fixer @PER-CS, PHPStan level 8). Open /php-coding and read the reference each change maps to."
+  else
+    line="› PHP workspace detected: php-coding standards apply (PHP 8.4 pin, PER Coding Style 3.1, php-cs-fixer @PER-CS, PHPStan level 8). Load the php-coding skill and read the reference each change maps to."
+  fi
   refs="$(library_refs)"
   [ -n "$refs" ] && line="$line composer.json also maps to: $refs."
   if [ -f composer.json ] && grep -q '"laravel/framework"' composer.json; then
     line="$line Laravel framework code belongs to Laravel Boost."
   fi
-  echo "$line"
+  if [ -n "$cursor" ]; then
+    printf '{"additional_context":"%s"}\n' "$line"
+  else
+    echo "$line"
+  fi
 fi
 
 exit 0
diff --git a/scripts/validate.py b/scripts/validate.py
index fbdecdb..811b9c0 100644
--- a/scripts/validate.py
+++ b/scripts/validate.py
@@ -8,7 +8,8 @@
   * dual-host parity (name/version/description/author agree across manifests);
   * every component path declared in a manifest exists inside the plugin dir;
   * kebab-case directory/file names for skills, agents, commands, and rules;
-  * hook-config JSON validity when present;
+  * hook-config JSON validity when present; Cursor's file has ``"version": 1`` and
+    does not use ``${CLAUDE_PLUGIN_ROOT}``;
   * skill reference files: linked one level deep from SKILL.md, no orphans, a Contents list
     past 100 lines; the Cursor rule and agents name only references that exist;
   * SKILL.md / agent / command frontmatter — required keys, and ``name`` matching the
@@ -251,9 +252,17 @@ def main():
                 err(f"manifests disagree on '{field}': "
                     f"claude={claude.get(field)!r} cursor={cursor.get(field)!r}")
 
-    # Hook configs must be valid JSON when present.
+    # Hook configs must be valid JSON when present. Cursor requires "version": 1
+    # and does not expand ${CLAUDE_PLUGIN_ROOT}.
     validate_json_file(ROOT / "hooks" / "hooks.json", "Claude hooks")
-    validate_json_file(ROOT / "hooks" / "cursor-hooks.json", "Cursor hooks")
+    cursor_hooks = load_json(ROOT / "hooks" / "cursor-hooks.json", "Cursor hooks")
+    if isinstance(cursor_hooks, dict):
+        if cursor_hooks.get("version") != 1:
+            err('hooks/cursor-hooks.json: needs "version": 1, which Cursor requires of a hooks file')
+        blob = json.dumps(cursor_hooks)
+        if "CLAUDE_PLUGIN_ROOT" in blob:
+            err("hooks/cursor-hooks.json: uses CLAUDE_PLUGIN_ROOT, which Cursor does not set; "
+                "keep commands relative to the plugin install")
 
     validate_skills()
     validate_md_components("agents", require_name=True, is_agent=True)

From 9be2efde87062e273a82964f730bcfa2c2a86c9d Mon Sep 17 00:00:00 2001
From: Sebastian Iancu <sebastian-iancu@users.noreply.github.com>
Date: Tue, 27 Oct 2026 14:28:03 +0100
Subject: [PATCH 2/2] fix(hooks): keep Cursor hooks out of the plugin install

Without CURSOR_PROJECT_DIR both hooks now stay silent instead of reading
the plugin install, which ships references/*.php and read as a PHP
workspace. The session line is JSON-escaped for Cursor. format-on-save
drops the unneeded "path" key and the relative-path join the cd already
covers.

The validator keeps its "when present" guard, rejects a non-integer
version and a top-level non-object in cursor-hooks.json. The docs cite
Cursor's hooks page with a check date, testing.md replays both hooks
with Cursor's variables set, and the CHANGELOG is split per change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md               |  6 +++---
 CHANGELOG.md            |  7 ++++++-
 docs/authoring.md       |  2 +-
 docs/install.md         |  2 +-
 docs/testing.md         | 19 ++++++++++++++-----
 hooks/format-on-save.sh | 24 ++++++++++--------------
 hooks/session-start.sh  | 13 ++++++++-----
 scripts/validate.py     | 18 +++++++++++-------
 8 files changed, 54 insertions(+), 37 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 286c5de..ecd157c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -50,8 +50,8 @@ Update each hit. Keep release numbers and "checked" dates in `## Sources` sectio
 - **Agent**: `agents/php-reviewer.md`. Report-only, no sub-agent dispatch. Its `tools:` include `Skill` so it can load `php-coding`.
 - **Cursor rule**: `rules/php-context.mdc` (`globs: ["**/*.php"]`) mirrors the index table.
 - **Claude hooks**: `hooks/hooks.json` wires `SessionStart` and `PostToolUse` (`matcher: "Write|Edit"`) to the shared scripts as `bash "${CLAUDE_PLUGIN_ROOT}/hooks/<script>.sh"`.
-- **Cursor hooks**: `hooks/cursor-hooks.json` (`"version": 1`) wires `sessionStart` and `afterFileEdit`. Commands are relative to the plugin install (`bash hooks/session-start.sh`), not `${CLAUDE_PLUGIN_ROOT}`.
-- **Shared hook scripts**: `hooks/session-start.sh` detects `composer.json` or a `*.php` file, prints one line, and names the library references whose packages appear in `composer.json` (and Laravel Boost for `laravel/framework`). On Cursor it inspects `CURSOR_PROJECT_DIR` and prints JSON `additional_context`. `hooks/format-on-save.sh` reads the edited path from the host's stdin JSON (`tool_input.file_path` on Claude Code, `file_path` on Cursor `afterFileEdit`) and runs `php-cs-fixer fix` on a `*.php` file when a project config and a fixer binary exist. On Cursor it looks for that config in `CURSOR_PROJECT_DIR`, not the plugin install. `afterFileEdit` is the right event for the formatter: it has no output, and the script only rewrites the file. Both always exit 0.
+- **Cursor hooks**: `hooks/cursor-hooks.json` (`"version": 1`) wires `sessionStart` and `afterFileEdit`, each with a `timeout` in seconds. Commands are relative to the plugin install (`bash hooks/session-start.sh`), not `${CLAUDE_PLUGIN_ROOT}`.
+- **Shared hook scripts**: `hooks/session-start.sh` detects `composer.json` or a `*.php` file, prints one line, and names the library references whose packages appear in `composer.json` (and Laravel Boost for `laravel/framework`). On Cursor it inspects `CURSOR_PROJECT_DIR` and prints JSON `additional_context`. `hooks/format-on-save.sh` reads the edited path from the host's stdin JSON (`tool_input.file_path` on Claude Code, `file_path` on Cursor `afterFileEdit`) and runs `php-cs-fixer fix` on a `*.php` file when a project config and a fixer binary exist. On Cursor it looks for that config in `CURSOR_PROJECT_DIR`, not the plugin install. The formatter uses `afterFileEdit`: Cursor documents no output for it, and the script only rewrites the file. Both always exit 0.
 - **Reference lint config**: top-level `references/php-cs-fixer.php`, `references/phpstan.neon`, `references/rector.php` (Rector optional, default-off). This is a different directory from `skills/php-coding/references/`.
 - **Eval suite**: `evals/<case>/` with `prompt.md` and `graders/`, run by `claude plugin eval`. Results go to `evals/results/`, which is gitignored.
 - **Validation**: `scripts/validate.sh` wraps the stdlib-only `scripts/validate.py`. CI (`.github/workflows/validate.yml`) installs Python 3 and runs it on pushes to `main` and on pull requests.
@@ -131,7 +131,7 @@ When a dated version fact changes, follow [Refreshing a dated fact](#refreshing-
 - **Quote `${CLAUDE_PLUGIN_ROOT}` in Claude hook commands.** A plugin path that contains a space splits into several words. `claude plugin validate .` warns on the unquoted form.
 - **A Claude hook `timeout` is in seconds, not milliseconds.** The default for a command hook is 600. — <https://code.claude.com/docs/en/hooks>
 - **Hook scripts get the edited path from stdin.** Claude Code sends it as `tool_input.file_path` and documents no `CLAUDE_FILE_PATH` variable. Keep the stdin parsing in `format-on-save.sh`.
-- **The Cursor hook command is relative to the plugin install** (`bash hooks/session-start.sh`), *not* `${CLAUDE_PLUGIN_ROOT}`. A plugin hook's working directory is that install, so `session-start.sh` and `format-on-save.sh` move to `CURSOR_PROJECT_DIR` before they read the workspace. Confirm both hooks fire in a PHP workspace other than this repo.
+- **The Cursor hook command is relative to the plugin install** (`bash hooks/session-start.sh`), *not* `${CLAUDE_PLUGIN_ROOT}`. Cursor runs a plugin hook from its install, which `CURSOR_PLUGIN_ROOT` names, and sets `CURSOR_PROJECT_DIR` to the workspace root, checked 2026-10-27. So `session-start.sh` and `format-on-save.sh` move to `CURSOR_PROJECT_DIR` before they read the workspace, and do nothing without it: the install ships `references/*.php`. Confirm both hooks fire in a PHP workspace other than this repo. — <https://cursor.com/docs/agent/hooks>
 - **An unquoted `: ` or ` #` in a frontmatter value is invalid YAML** (YAML 1.2.2, section 7.3.3). `scripts/validate.py` is the only check that catches it; `claude plugin validate` passed such a skill in a test on CLI 2.1.283. — <https://yaml.org/spec/1.2.2/#733-plain-style>
 - **The fixer lags PER.** `@PER-CS` still means PER 3.0. Do not claim the fixer enforces a 3.1 rule; `style.md` lists them.
 - **`AGENTS.md` and `.github/` are export-ignored** in `.gitattributes`. A shipped skill, reference, agent, rule, or hook must not depend on them.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6c1ff8c..ab24c98 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,8 +9,13 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve
 
 ## [Unreleased]
 
+### Added
+- Validator: `scripts/validate.py` fails a `hooks/cursor-hooks.json` without `"version": 1` or with `${CLAUDE_PLUGIN_ROOT}`.
+
 ### Fixed
-- Hooks: Cursor `session-start.sh` reads `CURSOR_PROJECT_DIR` and returns `additional_context`. `format-on-save.sh` looks for the fixer config in that directory and stays on `afterFileEdit`. `hooks/cursor-hooks.json` has `"version": 1`.
+- Hooks: on Cursor, `session-start.sh` and `format-on-save.sh` read the workspace from `CURSOR_PROJECT_DIR`, not the plugin install, and stay silent without it.
+- Hooks: on Cursor, `session-start.sh` returns its line as JSON `additional_context` and names `/php-coding`.
+- Hooks: `hooks/cursor-hooks.json` declares `"version": 1` and a `timeout` per hook.
 
 ## [0.2.0] - 2026-10-19
 
diff --git a/docs/authoring.md b/docs/authoring.md
index 64ee943..ea78fcb 100644
--- a/docs/authoring.md
+++ b/docs/authoring.md
@@ -55,7 +55,7 @@ Each case is a directory with `prompt.md` and a `graders/` folder ([plugin evals
 
 ## Dual-host parity
 
-Skills and agents are shared. The **Cursor** manifest (`.cursor-plugin/plugin.json`) declares each component path. **Claude** discovers the default folders automatically. Keep `name`, `version`, `description`, and `author` identical across the two manifests. The Claude hook command quotes the placeholder (`bash "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"`). The Cursor hook command is relative to the plugin install (`bash hooks/session-start.sh`), never `${CLAUDE_PLUGIN_ROOT}`. `hooks/cursor-hooks.json` has `"version": 1`. The formatter stays on `afterFileEdit`.
+Skills and agents are shared. The **Cursor** manifest (`.cursor-plugin/plugin.json`) declares each component path. **Claude** discovers the default folders automatically. Keep `name`, `version`, `description`, and `author` identical across the two manifests. The Claude hook command quotes the placeholder (`bash "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"`). The Cursor hook command is relative to the plugin install (`bash hooks/session-start.sh`), never `${CLAUDE_PLUGIN_ROOT}`. `hooks/cursor-hooks.json` has `"version": 1`. The formatter uses `afterFileEdit`, for which Cursor documents no output.
 
 ## Before committing
 
diff --git a/docs/install.md b/docs/install.md
index b194efc..ce6c900 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -51,4 +51,4 @@ Installing the plugin needs no PHP toolchain. Enforcement does. The pin is **PHP
 
 `/php-lint-setup` writes the reference config. Install the binaries with Composer in the target repo, for example `friendsofphp/php-cs-fixer`, `phpstan/phpstan:^2`, and `phpunit/phpunit:^12.5`. Download PHP from <https://www.php.net/downloads.php>.
 
-The format-on-save hook looks for `.php-cs-fixer.php` (or `.php-cs-fixer.dist.php`) in the workspace and for `vendor/bin/php-cs-fixer` or `php-cs-fixer` on `PATH`. On Cursor the hook runs in the plugin install, so it changes to `CURSOR_PROJECT_DIR` first. It does not install the fixer.
+The format-on-save hook looks for `.php-cs-fixer.php` (or `.php-cs-fixer.dist.php`) and `vendor/bin/php-cs-fixer` in its working directory, then for `php-cs-fixer` on `PATH`. Claude Code runs it in the session's current directory. Cursor runs it in the plugin install, so the hook changes to `CURSOR_PROJECT_DIR` first. It does not install the fixer.
diff --git a/docs/testing.md b/docs/testing.md
index 28d87c7..fb9c1d8 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -12,13 +12,22 @@ Checked 2026-09-30 against php-cs-fixer 3.95.27 (`describe @PER-CS` prints `@PER
 
 ## Hook smoke tests
 
-Both scripts always exit 0. Run them from the root of a PHP project, with `P` set to this repo's path:
+Both scripts always exit 0. Run them from the root of a PHP project, with `P` set to this repo's path. Claude Code runs a hook in the project and reads plain stdout:
 
 ```bash
 P=/path/to/php-coding-plugin
-bash "$P/hooks/session-start.sh"                                                     # one standards line; nothing outside a PHP workspace
-printf '{"tool_input":{"file_path":"src/Foo.php"}}' | bash "$P/hooks/format-on-save.sh"   # Claude Code payload
-printf '{"file_path":"/abs/path/src/Foo.php"}' | bash "$P/hooks/format-on-save.sh"          # Cursor afterFileEdit payload
+bash "$P/hooks/session-start.sh"                                                         # one standards line; nothing outside a PHP workspace
+printf '{"tool_input":{"file_path":"src/Foo.php"}}' | bash "$P/hooks/format-on-save.sh"  # Claude Code payload
+```
+
+Cursor runs a plugin hook in the plugin install, with `CURSOR_PLUGIN_ROOT` and `CURSOR_PROJECT_DIR` set. Replay that from the same project root:
+
+```bash
+W="$PWD"
+(cd "$P" && CURSOR_PLUGIN_ROOT="$P" CURSOR_PROJECT_DIR="$W" bash hooks/session-start.sh) | python3 -m json.tool   # {"additional_context": "..."}
+printf '{"file_path":"%s/src/Foo.php"}' "$W" \
+  | (cd "$P" && CURSOR_PLUGIN_ROOT="$P" CURSOR_PROJECT_DIR="$W" bash hooks/format-on-save.sh)                     # Cursor afterFileEdit payload
+(cd "$P" && CURSOR_PLUGIN_ROOT="$P" bash hooks/session-start.sh)                                                 # no CURSOR_PROJECT_DIR: prints nothing
 ```
 
 With a `.php-cs-fixer.php` and a fixer binary present, the named file is reformatted. Without either, nothing happens.
@@ -45,6 +54,6 @@ Load a working copy (see [install.md](install.md)), then:
 - **`php-reviewer`** — a review request loads `php-coding`, reads the references the diff maps to, returns severity-ranked findings, and does not edit or spawn agents.
 - **`/php-lint-setup`** — writes the reference config and does not overwrite an existing file unprompted.
 - **Cursor rule** — open a `.php` file and confirm `php-context.mdc` attaches.
-- **Cursor hooks** — in a PHP workspace other than this repo, confirm the session-start line reaches the agent as `additional_context` (it names `/php-coding`) and a `.php` edit is reformatted. The formatter stays on `afterFileEdit`. The hook runs in the plugin install and reads the project from `CURSOR_PROJECT_DIR`.
+- **Cursor hooks** — in a PHP workspace other than this repo, confirm the session-start line reaches the agent as `additional_context` (it names `/php-coding`) and a `.php` edit is reformatted. Both hooks run in the plugin install and read the project from `CURSOR_PROJECT_DIR`.
 
 After editing content, reinstall or restart the session.
diff --git a/hooks/format-on-save.sh b/hooks/format-on-save.sh
index 774e4d0..bc4cfe6 100755
--- a/hooks/format-on-save.sh
+++ b/hooks/format-on-save.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# PostToolUse / afterFileEdit hook (host-agnostic): format the just-edited PHP file.
+# PostToolUse (Claude Code) / afterFileEdit (Cursor) hook: format the just-edited PHP file.
 #
 # Runs `php-cs-fixer fix` on that single file when a project config is present
 # (`.php-cs-fixer.php` or `.php-cs-fixer.dist.php`) and a fixer binary is available.
@@ -8,33 +8,29 @@
 # never block an edit. The fixer owns style; this hook does not pass a second ruleset.
 #
 # File-path resolution, in order:
-#   1. $CLAUDE_FILE_PATH          — set by Claude Code for Write/Edit hooks (fast path).
-#   2. tool payload JSON on stdin — Claude (`tool_input.file_path`) or Cursor
+#   1. $CLAUDE_FILE_PATH          — explicit override for tests and manual runs; no host sets it.
+#   2. tool payload JSON on stdin — Claude Code (`tool_input.file_path`) or Cursor
 #      `afterFileEdit` (`file_path`). Extracted without a jq/python dependency.
+# A relative path resolves against the working directory: on Cursor, CURSOR_PROJECT_DIR.
 set -u
 
 f="${CLAUDE_FILE_PATH:-}"
 
-# Fall back to the JSON the host pipes in on stdin (Cursor; newer Claude payloads).
+# Otherwise read the JSON payload both hosts pipe in on stdin.
 # Guard on a non-tty stdin so a manual run without a pipe doesn't block on `cat`.
 if [ -z "$f" ] && [ ! -t 0 ]; then
   payload="$(cat)"
   f="$(printf '%s' "$payload" \
-        | grep -oE '"(file_?[Pp]ath|path)"[[:space:]]*:[[:space:]]*"[^"]+"' \
+        | grep -oE '"file_?[Pp]ath"[[:space:]]*:[[:space:]]*"[^"]+"' \
         | head -n1 \
         | sed -E 's/.*"([^"]+)"$/\1/')"
 fi
 
-# Cursor plugin hooks run in the plugin install. The fixer config and vendor
-# binary live in the workspace, which CURSOR_PROJECT_DIR names.
+# Cursor plugin hooks run in the plugin install (https://cursor.com/docs/agent/hooks). The fixer
+# config and vendor binary live in the workspace, which CURSOR_PROJECT_DIR names; without it
+# there is no workspace to format against.
 if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
-  cd "${CURSOR_PROJECT_DIR:-.}" 2>/dev/null || exit 0
-fi
-if [ -n "${CURSOR_PLUGIN_ROOT:-}" ] && [ -n "${CURSOR_PROJECT_DIR:-}" ]; then
-  case "$f" in
-    /*|"") ;;
-    *) f="${CURSOR_PROJECT_DIR%/}/$f" ;;
-  esac
+  [ -n "${CURSOR_PROJECT_DIR:-}" ] && cd "$CURSOR_PROJECT_DIR" 2>/dev/null || exit 0
 fi
 
 [ -n "$f" ] || exit 0
diff --git a/hooks/session-start.sh b/hooks/session-start.sh
index 719a82c..46b912c 100755
--- a/hooks/session-start.sh
+++ b/hooks/session-start.sh
@@ -3,16 +3,18 @@
 # line when a PHP workspace is detected, naming the php-coding references that match
 # composer.json. Always exits 0.
 #
-# Claude Code runs the hook in the project directory and reads plain stdout.
+# Claude Code runs the hook in its current directory and reads plain stdout.
 # Cursor runs a plugin hook from the plugin install and reads additional_context
-# from JSON, so there the hook moves to CURSOR_PROJECT_DIR.
+# from JSON, so there the hook moves to CURSOR_PROJECT_DIR
+# (https://cursor.com/docs/agent/hooks).
 set -u
 
-# CURSOR_PLUGIN_ROOT is set only for a Cursor plugin hook.
+# CURSOR_PLUGIN_ROOT is set only for a Cursor plugin hook. Without CURSOR_PROJECT_DIR the hook
+# stays silent: the plugin install ships references/*.php and would read as a PHP workspace.
 cursor=""
 if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
   cursor=1
-  cd "${CURSOR_PROJECT_DIR:-.}" 2>/dev/null || exit 0
+  [ -n "${CURSOR_PROJECT_DIR:-}" ] && cd "$CURSOR_PROJECT_DIR" 2>/dev/null || exit 0
 fi
 
 is_php_workspace() {
@@ -52,7 +54,8 @@ if is_php_workspace; then
     line="$line Laravel framework code belongs to Laravel Boost."
   fi
   if [ -n "$cursor" ]; then
-    printf '{"additional_context":"%s"}\n' "$line"
+    # One JSON string: escape backslashes and double quotes.
+    printf '{"additional_context":"%s"}\n' "$(printf '%s' "$line" | sed 's/\\/\\\\/g; s/"/\\"/g')"
   else
     echo "$line"
   fi
diff --git a/scripts/validate.py b/scripts/validate.py
index 811b9c0..a724c77 100644
--- a/scripts/validate.py
+++ b/scripts/validate.py
@@ -221,7 +221,8 @@ def validate_manifest_paths(manifest: dict, label: str):
 
 def validate_json_file(path: Path, label: str):
     if path.is_file():
-        load_json(path, label)
+        return load_json(path, label)
+    return None
 
 
 def main():
@@ -253,14 +254,17 @@ def main():
                     f"claude={claude.get(field)!r} cursor={cursor.get(field)!r}")
 
     # Hook configs must be valid JSON when present. Cursor requires "version": 1
-    # and does not expand ${CLAUDE_PLUGIN_ROOT}.
+    # and does not set CLAUDE_PLUGIN_ROOT (https://cursor.com/docs/agent/hooks).
     validate_json_file(ROOT / "hooks" / "hooks.json", "Claude hooks")
-    cursor_hooks = load_json(ROOT / "hooks" / "cursor-hooks.json", "Cursor hooks")
-    if isinstance(cursor_hooks, dict):
-        if cursor_hooks.get("version") != 1:
+    cursor_hooks = validate_json_file(ROOT / "hooks" / "cursor-hooks.json", "Cursor hooks")
+    if cursor_hooks is not None and not isinstance(cursor_hooks, dict):
+        err("hooks/cursor-hooks.json: top level must be a JSON object")
+    elif cursor_hooks is not None:
+        version = cursor_hooks.get("version")
+        # type() rather than ==, since True == 1 and 1.0 == 1 in Python.
+        if type(version) is not int or version != 1:
             err('hooks/cursor-hooks.json: needs "version": 1, which Cursor requires of a hooks file')
-        blob = json.dumps(cursor_hooks)
-        if "CLAUDE_PLUGIN_ROOT" in blob:
+        if "CLAUDE_PLUGIN_ROOT" in json.dumps(cursor_hooks):
             err("hooks/cursor-hooks.json: uses CLAUDE_PLUGIN_ROOT, which Cursor does not set; "
                 "keep commands relative to the plugin install")