Hooks Reference
===============================================================================

PreToolUse
-------------------------------------------------------------------------------

``.env`` File Protection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Blocks any ``Read``, ``Grep``, or ``Bash`` tool call whose input contains a
path matching ``*.env*``.

.. list-table::
   :header-rows: 1
   :widths: 20 30 50

   * - Property
     - Value
     - Notes
   * - Event
     - ``PreToolUse``
     - Runs before the tool is invoked
   * - Matcher
     - ``Read|Grep|Bash``
     - Pipe-separated tool names
   * - Decision
     - ``deny``
     - Stops execution and returns an error message
   * - Reason
     - ``.env files are protected and cannot be read.``
     - Shown to the user when blocked

The hook inspects the following fields from the tool input JSON:

- ``file_path`` (Read)
- ``path`` (Grep)
- ``glob`` (Grep)
- ``command`` (Bash)

A call is blocked if any of those values contains the string ``.env``.

Complementary deny rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The declarative ``permissions.deny`` rules in ``.claude/settings.json`` enforce
the same restrictions at the tool-dispatch level, before the hook runs:

.. code-block:: json

   {
     "permissions": {
       "deny": [
         "Read(**/.env*)",
         "Grep(**/.env*)",
         "Bash(cat */.env*)",
         "Bash(cat .env*)"
       ]
     }
   }

Both layers are necessary. See :doc:`quickstart` for setup instructions.


UserPromptSubmit
-------------------------------------------------------------------------------

``/develop`` Suggestion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fires before Claude processes each user message. If the prompt describes a
development task, injects an ``additionalContext`` message recommending the
``/develop`` skill.

.. list-table::
   :header-rows: 1
   :widths: 20 30 50

   * - Property
     - Value
     - Notes
   * - Event
     - ``UserPromptSubmit``
     - Runs before Claude responds to the user's message
   * - Matcher
     - *(none)*
     - Fires on every prompt; filtering is done inside the script
   * - Script
     - ``~/.claude/plugins/marketplaces/bytecode-solutions/hooks/suggest_develop.py``
     - Resolved via the marketplace installation path; source lives in ``hooks/suggest_develop.py``

**Detection logic**

The hook matches prompts containing development-intent keywords:
``implement``, ``build``, ``develop``, ``feature``, ``module``, ``component``,
``service``, ``class``, ``function``, ``endpoint``, ``api``, ``refactor``,
``create``, ``new``, and ``add <x> to/for/in``.

Prompts that belong to other skills are excluded to avoid double-suggesting:
``run tests``, ``run linters``, ``run coverage``, ``run security``,
``check tests/linters/coverage/security/vulnerability``, ``lint``, ``audit``,
``scan``.

**Behaviour**

- If a match is found, outputs a JSON ``additionalContext`` message that Claude
  reads before responding, a nudge to recommend ``/develop``, not a forced
  invocation.
- All errors are silently suppressed (``contextlib.suppress``) so the hook
  never blocks the user's prompt.