# System Engine Hooks, Rules, and Instruction Files

Different AI coding tools expose different customization mechanisms. Some are real lifecycle hooks that execute commands at fixed points in the runtime. Others are persistent instruction files that are added to the model context as guidance. These should not be described as the same mechanism.

## A. Claude Code CLI Hook (`.claude/settings.json`)

Claude Code supports lifecycle hooks in `.claude/settings.json`, including `UserPromptSubmit`. This event runs after the user submits a prompt and before Claude processes it.

A `UserPromptSubmit` command hook can:

- read the submitted prompt from JSON on stdin;
- write plain text to stdout, which Claude Code can add as context;
- return structured JSON to add `additionalContext`, set a session title, or block the prompt.

The following example injects additional context on every submitted prompt:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":\"CRITICAL ARCHITECTURAL CONSTRAINT ACTIVE\\n\\nImplement systems chronologically, layer by layer: Domain -> Infrastructure -> Application -> API. For the active layer, present the plan first, then ask for explicit permission before writing code.\"}}'"
          }
        ]
      }
    ]
  }
}
```

Important limits:

- This is a Claude Code hook, not a universal AI-engine hook.
- It can add context or block a prompt, but it does not override higher-priority system, developer, policy, or runtime instructions.
- A bare `echo` hook may add context in Claude Code, but structured JSON with `additionalContext` is more explicit and less ambiguous.

## B. Codex Lifecycle Hooks (`.codex/hooks.json` or `.codex/config.toml`)

Codex has its own lifecycle hook system. Codex does not use `.cursorrules` or `.github/copilot-instructions.md` as hooks.

Project or user hooks should be configured in one of these Codex-supported locations:

- `.codex/hooks.json`
- `.codex/config.toml` with inline `[hooks]` tables
- user-level equivalents such as `~/.codex/hooks.json` or `~/.codex/config.toml`

For durable repository guidance in Codex, use `AGENTS.md`.

Example Codex hook:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "printf '%s\\n' 'CRITICAL ARCHITECTURAL CONSTRAINT ACTIVE\\n\\nImplement systems chronologically, layer by layer: Domain -> Infrastructure -> Application -> API. For the active layer, present the plan first, then ask for explicit permission before writing code.'"
          }
        ]
      }
    ]
  }
}
```

Important limits:

- Codex project-local hooks load only from trusted project `.codex/` configuration.
- Non-managed command hooks may require review and trust before they run.
- Hooks are lifecycle automation, not a guarantee that injected text overrides higher-priority instructions.

## C. Cursor and Copilot Instruction Files, Not Hooks

Cursor and GitHub Copilot support persistent instruction files, but these files are not executable lifecycle hooks and should not be described as intercepting every message or modifying the system prompt.

Use the appropriate instruction file for the tool:

- Cursor: prefer `.cursor/rules/*.mdc`, User Rules, Team Rules, or `AGENTS.md`.
- GitHub Copilot: use `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, or `AGENTS.md` where supported.
- Codex: use `AGENTS.md` for durable repository guidance; use `.codex/hooks.json` or `.codex/config.toml` for lifecycle hooks.

Corrected instruction-file wording:

```markdown
# Architectural Execution Guidance

When implementing a C# system in this repository:

1. Prefer chronological layer order: Domain -> Infrastructure -> Application -> API.
2. Do not implement multiple architectural layers in one large pass unless the user explicitly asks for that.
3. Before writing code for a layer, present the intended code layout and ask: "Do I have permission to implement the [Layer Name] layer now?"
4. Wait for explicit approval before generating implementation code for that layer.
```

Important limits:

- Instruction files guide model behavior; they are not command hooks.
- They are subject to each product's context loading, settings, trust model, and precedence rules.
- They should be written as repository guidance, not as claims about system-prompt injection.

## Bottom Line

The original Claude Code section was directionally valid but imprecise. The combined "Codex / Cursor / Copilot Prompt Hook" section was incorrect because it mixed real lifecycle hooks with persistent instruction files.