Prompt and Request Lifecycle

Relevant source files

The following files were used as context for generating this wiki page:

• .claude/hooks/skill-eval.js
• .claude/settings.json
• README.md
• CLAUDE.md
• .claude/hooks/skill-rules.json
• .claude/hooks/skill-eval.sh

The prompt and request lifecycle in Claude Code is a structured process that governs how user input is received, processed, and acted upon. It is built around a system of hooks that can be triggered at specific events, allowing for extensive automation, validation, and context injection. This system transforms Claude from a simple code generator into an integrated development assistant that can enforce conventions, run quality checks, and intelligently apply project-specific knowledge.

The core of this lifecycle is defined in .claude/settings.json, which configures scripts to run at key moments, such as before a user's prompt is processed or after a tool (like a file editor) is used. This enables powerful workflows like automatically suggesting relevant Skills, blocking direct edits to the main branch, and running formatters or tests after code modification.

Lifecycle Overview

The entire interaction, from a user submitting a prompt to the agent completing its task, is punctuated by several key hookable events. These hooks provide extension points to customize Claude's behavior.

The following diagram illustrates the sequence of events and where hooks can intercept the process.

Lifecycle Hook Events

The lifecycle is defined by four primary events where custom logic can be executed.

Event	When It Fires	Common Use Case
UserPromptSubmit	User submits a prompt	Add context, suggest skills, analyze user intent.
PreToolUse	Before a tool is executed	Block actions (e.g., on main), validate commands.
PostToolUse	After a tool completes	Auto-format code, run tests, lint changed files.
Stop	When the agent finishes	Decide if Claude should continue with another step.

Sources: README.md:129-138

Hook Configuration

Hooks are configured within the .claude/settings.json file. Each hook is an object that specifies the execution details.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit on main branch\"}' >&2; exit 2; }",
            "timeout": 5
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/skill-eval.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Sources: .claude/settings.json:2-25, README.md:94-106, README.md:323-335

Hook Properties

Property	Description
matcher	A regex string that the tool name must match for the hook to run (e.g., Edit|Write). Not used for UserPromptSubmit.
hooks	An array of hook objects to execute.
type	The type of hook. Currently, command is supported.
command	The shell command to execute.
timeout	The maximum execution time in seconds.

Sources: README.md:94-106, .claude/settings.json:4-13

Hook Response and Exit Codes

Hooks communicate back to Claude Code by writing a JSON object to stderr and using specific exit codes.

Response JSON Format

{
  "block": true,
  "message": "Reason for blocking",
  "feedback": "Non-blocking informational message",
  "suppressOutput": true,
  "continue": false
}

Field	Description
block	If true, blocks the action (PreToolUse only).
message	A message to display to the user.
feedback	A non-blocking informational message.
suppressOutput	If true, hides the hook command's stdout.
continue	If false, stops the agent's work (Stop only).

Sources: README.md:140-149

Exit Codes

Code	Meaning
0	Success.
2	Blocking error (PreToolUse only).
Other	Non-blocking error.

Sources: README.md:151-155

Detailed Hook Implementations

UserPromptSubmit: Skill Evaluation System

This is one of the most powerful automations, firing on every prompt to suggest relevant skills. It uses a combination of a shell script, a Node.js engine, and a JSON configuration file.

The flow is as follows:

1. The UserPromptSubmit hook in .claude/settings.json calls the skill-eval.sh script.
2. skill-eval.sh executes the skill-eval.js Node.js script, passing the user's prompt as an argument.
3. skill-eval.js reads the skill definitions and trigger rules from .claude/hooks/skill-rules.json.
4. The script analyzes the prompt for keywords, file paths, and intent patterns defined in the rules.
5. It calculates a confidence score for each skill based on the matches.
6. If any skills exceed a confidence threshold, it outputs a formatted message suggesting their activation.

Sources: README.md:294-306, .claude/hooks/skill-eval.js, .claude/hooks/skill-eval.sh, .claude/hooks/skill-rules.json

This diagram shows the skill evaluation data flow.

PreToolUse: Guardrail and Validation

The PreToolUse hook acts as a guardrail, preventing actions that violate project rules. A primary example is blocking edits on the main branch.

The hook command checks the current git branch. If it's main, the script prints a JSON object with "block": true to stderr and exits with code 2. This instructs Claude Code to halt the tool execution and inform the user.

Summary

The prompt and request lifecycle is a fundamental aspect of Claude Code's architecture, enabling deep integration into a project's development workflow. Through a well-defined sequence of events and configurable hooks, developers can automate quality checks, enforce standards, and provide the AI with the necessary context to perform tasks accurately and efficiently. The skill evaluation system, built on the UserPromptSubmit hook, is a prime example of how this lifecycle turns user prompts into intelligent, context-aware actions, making Claude a highly effective automated teammate.