[DOCS] Improve robustness of hook command paths in Subagent documentation

Documentation Type

Unclear/confusing documentation

Documentation Location

docs/en/sub-agents.md

Section/Topic

Conditional rules with hooks

Current Documentation

In the section "Conditional rules with hooks," the YAML example configuration for the subagent uses a relative path for the hook command:

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"

What's Wrong or Missing?

The example uses a relative path (./scripts/...) for the hook command. This approach is fragile because it relies on the user's Current Working Directory (CWD) being the project root when they launch Claude Code. If a user runs Claude from a subdirectory, this hook will fail to execute.

Furthermore, while the main [Hooks guide](docs/en/hooks.md) recommends using $CLAUDE_PROJECT_DIR for robustness and reminds users to ensure scripts are executable (chmod +x), the sub-agent documentation omits these best practices in this specific example, leading to potential confusion for users implementing subagents for the first time.

Suggested Improvement

Update the YAML example to use the $CLAUDE_PROJECT_DIR environment variable. This ensures the script is found regardless of where the session is initiated.

Proposed Change:

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "$CLAUDE_PROJECT_DIR/scripts/validate-readonly-query.sh"

It may also be beneficial to add a small note reminding the user to ensure the script is executable (e.g., chmod +x scripts/validate-readonly-query.sh).

Impact

High - Prevents users from using a feature

Additional Context

The Hooks reference (docs/en/hooks.md) correctly advises using project-specific environment variables for robustness in its examples:

"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"

However, the Subagents documentation (docs/en/sub-agents.md) uses a relative path in the "Conditional rules with hooks" section:

command: "./scripts/validate-readonly-query.sh"

This creates an inconsistency between documentation pages. If a user starts Claude Code from a subdirectory (e.g., inside src/), the relative path ./scripts/... will fail to resolve, whereas $CLAUDE_PROJECT_DIR ensures the hook works from anywhere within the project tree.

Additionally, users following this guide in isolation may forget that the script needs execution permissions. A brief reminder to run chmod +x scripts/validate-readonly-query.sh would prevent "permission denied" errors.