fix(hooks): harden Cursor policy controls

Close shell and file-read guard bypasses, bound audit logging, and add regression coverage.
Run hook and skill tooling through locked Python 3.14 CI.

Author: d-padmanabhan

.github/workflows/ci-skill-evals.yaml

@@ -0,0 +1,68 @@
+---
+name: Python Tooling and Skill Eval Checks
+
+# yamllint disable-line rule:truthy
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/ci-skill-evals.yaml"
+      - "evals/**"
+      - "hooks/cursor/**"
+      - "pyproject.toml"
+      - "skills/**"
+      - "uv.lock"
+  pull_request:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/ci-skill-evals.yaml"
+      - "evals/**"
+      - "hooks/cursor/**"
+      - "pyproject.toml"
+      - "skills/**"
+      - "uv.lock"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: skill-evals-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deterministic:
+    name: Validate Python tools and skill evals
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v9
+
+      - name: Install locked development tools
+        run: uv sync --frozen --dev
+
+      - name: Lint and format-check Python
+        run: |
+          uv run ruff check evals hooks/cursor
+          uv run ruff check hooks/cursor/*.py --select D --config "lint.pydocstyle.convention='google'"
+          uv run ruff format --check evals hooks/cursor
+          uv run pylint hooks/cursor/*.py
+
+      - name: Validate skills and eval definitions
+        run: uv run python -m evals.skill_eval validate
+
+      - name: Run Python unit tests
+        run: |
+          uv run python -m unittest discover -s evals/tests -v
+          uv run python -m unittest discover -s hooks/cursor/tests -v

hooks/cursor/README.md

@@ -4,6 +4,14 @@ This directory contains **optional** hook scripts and example `hooks.json` confi
 
 Hooks are deterministic programs that run at defined points in the agent loop and can block, allow, or modify actions.
 
+### Requirements
+
+- [uv](https://docs.astral.sh/uv/) available on `PATH`
+- Python 3.14 or newer, managed through `uv`
+- Hook scripts copied with executable mode
+
+The scripts use only the Python standard library at runtime. Repository development tools are declared in [`pyproject.toml`](../../pyproject.toml) and locked in [`uv.lock`](../../uv.lock).
+
 ### Files
 
 - `guard_before_shell.py`: Intended for `beforeShellExecution`
@@ -12,7 +20,8 @@ Hooks are deterministic programs that run at defined points in the agent loop an
 - `guard_before_read_file.py`: Intended for `beforeReadFile`
   - Denies reading common secret files (for example `.env`, private keys)
 - `audit_log.py`: Intended for `preToolUse` (or other events)
-  - Writes a redacted JSONL audit record to `.cursor/hooks/state/hook-audit.jsonl` (project) or `~/.cursor/hooks/state/hook-audit.jsonl` (user)
+  - Writes a bounded, redacted JSONL audit record to `.cursor/hooks/state/hook-audit.jsonl` (project) or `~/.cursor/hooks/state/hook-audit.jsonl` (user)
+- `hook_io.py`: Shared fail-safe JSON input/output helpers used by both guard scripts
 - `hooks.project.example.json`: Example project config (paths like `.cursor/hooks/...`)
 - `hooks.user.example.json`: Example user config (paths like `./hooks/...`)
 
@@ -26,3 +35,25 @@ cp -R /path/to/agent-engineering-handbook/hooks/cursor/*.py .cursor/hooks/
 cp /path/to/agent-engineering-handbook/hooks/cursor/hooks.project.example.json .cursor/hooks.json
 chmod +x .cursor/hooks/*.py
 ```
+
+The example configuration executes each script directly. Its `uv run` shebang selects the declared Python runtime without requiring a project-specific virtual environment.
+
+### Security model
+
+These hooks are defense-in-depth controls, not a sandbox:
+
+- Guard scripts reject malformed input instead of silently allowing it.
+- Audit records redact common secret keys and values, bound untrusted data, and use `0700` directory and `0600` file permissions.
+- Example configurations retain `"failClosed": false` so a missing runtime or broken optional hook does not disable Cursor. Organizations that treat hooks as mandatory policy enforcement should test the scripts in their environment and deliberately change this setting.
+- Shell parsing is conservative but cannot prove arbitrary shell code safe. Remote-write authorization and normal code review remain required.
+
+### Development
+
+```bash
+uv sync --dev
+uv run ruff check hooks/cursor
+uv run ruff check hooks/cursor/*.py --select D --config "lint.pydocstyle.convention='google'"
+uv run ruff format --check hooks/cursor
+uv run pylint hooks/cursor/*.py
+uv run python -m unittest discover -s hooks/cursor/tests -v
+```