Hook System

Relevant source files

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

• src/core/HookManager.ts
• src/commands/hooks.ts
• src/core/agent.ts
• src/core/actionExecutor.ts
• tests/hookManager.spec.ts
• tests/builtinHooks.spec.ts
• tests/hooksCommand.spec.ts

The Hook System is a lifecycle management framework within Autohand that allows the execution of external shell commands or scripts in response to specific application events. This system enables users to extend the agent's functionality, enforce security policies, automate formatting, and receive notifications without modifying the core codebase.

Sources: src/core/HookManager.ts:1-10, src/commands/hooks.ts:133-136

Architecture and Core Components

The Hook System is centered around the HookManager, which orchestrates the registration, filtering, and execution of hooks. It interfaces with the AutohandAgent to intercept various stages of the agent's operation, such as tool execution or session management.

Key Components

• HookManager: The primary class responsible for managing hook settings, initializing default hooks, and executing scripts. Sources: src/core/HookManager.ts:114-118
• HookContext: A structured data object containing environment details (e.g., sessionId, tool, workspace) passed to every hook execution. Sources: src/core/HookManager.ts:11-73
• HookDefinition: A data structure defining a hook, including its trigger event, the command to run, filters, and execution mode (sync vs. async). Sources: src/core/HookManager.ts:75-88

Hook Execution Flow

The following diagram illustrates how the HookManager processes an event trigger and executes the associated hooks.

The system distinguishes between synchronous hooks, which can block execution or modify control flow, and asynchronous hooks, which run in the background.
Sources: src/core/HookManager.ts:489-530

Hook Events and Lifecycle

The system supports a wide range of events spanning session management, tool interactions, and file system changes.

Supported Events

Event	Description
session-start	Triggered when a new or resumed session begins.
session-end	Triggered when a session terminates (quit, exit, or error).
pre-tool	Executes before a tool is called; can be used for security or validation.
post-tool	Executes after a tool completes; receives the tool's output.
file-modified	Triggered when the agent modifies a file in the workspace.
stop	Triggered when a conversation turn completes.
permission-request	Specifically used to automate or block tool approval requests.
subagent-stop	Triggered when a delegated sub-agent finishes its task.

Sources: src/commands/hooks.ts:14-53, src/core/HookManager.ts:14-68

Integration with Agent and Executor

The HookManager is deeply integrated into the AutohandAgent and ActionExecutor to provide fine-grained control over the agent's behavior.

Permission and Tool Interception

The ActionExecutor utilizes hooks during the permission-request event to determine if an action should be allowed, denied, or if the user should be prompted.

Environment and Data Passing

Hooks receive context through two primary mechanisms:

1. Environment Variables: Every context field is mapped to a HOOK_ prefixed variable (e.g., HOOK_TOOL, HOOK_WORKSPACE). Sources: src/core/HookManager.ts:316-364
2. Standard Input (JSON): A full JSON representation of the HookContext is piped to the hook's stdin. Sources: src/core/HookManager.ts:369-410

Hook Management Interface

Users interact with the hook system through the /hooks slash command, which provides a CLI-based management interface.

Management Features

• Discovery: The system automatically installs default scripts (e.g., security-guard.sh, smart-commit.sh) into ~/.autohand/hooks/. Sources: src/core/HookManager.ts:169-192
• Testing: Users can test hooks with sample context to verify script logic and exit codes. Sources: src/commands/hooks.ts:391-424
• Filtering: Hooks can be restricted to specific tools or file paths using glob patterns. Sources: src/core/HookManager.ts:257-275

Security and Control Flow

Hooks can act as security gates. If a hook exits with Exit Code 2, it is treated as a "blocking error," and the calling operation (such as a tool execution) is aborted. Sources: src/core/HookManager.ts:106-107, src/core/HookManager.ts:466-470

Additionally, hooks can return a JSON object on stdout to influence the agent:

{
  "continue": false,
  "response": {
    "decision": "deny",
    "reason": "Security policy violation"
  }
}

If "continue": false is returned, the HookManager stops executing subsequent hooks in the chain for that event. Sources: src/core/HookManager.ts:415-427, src/core/HookManager.ts:517-520

Summary

The Hook System provides a robust infrastructure for externalizing logic and policies. By combining environment injection, JSON communication, and exit-code-based control flow, it allows the Autohand project to remain extensible while providing powerful automation and safety features for the end user.