Hook Execution System

Relevant source files

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

• HOOKS.md
• plugins/token-optimizer/skills/token-optimizer/references/agent-prompts.md
• plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md
• skills/token-optimizer/references/optimization-checklist.md
• skills/token-coach/SKILL.md

The Hook Execution System is a specialized framework within the Token Optimizer project designed to intercept host platform events (such as tool usage, session starts, or context compactions) to perform automated token management, security checks, and analytics. By executing scripts at specific lifecycle stages, the system enables features like "Smart Compaction," redundant read caching, and automated session metrics collection without blocking the primary user workflow.

The system follows a "fail-open" execution model, ensuring that even if a hook script fails or times out, the host platform's core functionality remains uninterrupted. It utilizes a centralized dispatcher to handle consent validation, path sanitization, and subprocess isolation, maintaining a strict security boundary between the hook logic and the user's source code.

System Architecture

The Hook Execution System operates through a layered dispatch mechanism. When the host platform triggers a tool call or lifecycle event, the request flows through a shell resolver to a Python-based dispatcher.

Execution Model and Security

The system is built on several key architectural properties to ensure stability and security:

• Fail-Open Dispatcher: The run.py dispatcher always exits with code 0 to prevent blocking the host platform's tool calls, regardless of internal script errors.
• Timeouts: A 120-second timeout is enforced per hook invocation. If a child process exceeds this, it is killed to prevent SQLite lock starvation.
• Isolation: Each hook script runs as an isolated subprocess using subprocess.Popen without shell execution (shell=False) to prevent command injection.
• Sanitization: The system sanitizes session IDs and checkpoint names to prevent path traversal attacks.

Sources: HOOKS.md:15-22, HOOKS.md:65-73

Hook Inventory and Lifecycle Events

Hooks are categorized by the platform event that triggers them. Each hook serves a specific purpose, ranging from performance optimization to context preservation.

Event	Script	Purpose
PreToolUse[Read]	read_cache.py	Detects redundant file reads and serves structure maps.
PreCompact	measure.py	Generates context-aware compaction instructions and captures checkpoints.
SessionStart	measure.py	Verifies system health, warms quality caches, and restores checkpoints.
PostToolUse	archive_result.py	Archives tool outputs (redacting credentials) for later retrieval.
Stop	measure.py	Performs final session metrics flush and captures a closing checkpoint.

Sources: HOOKS.md:24-60

Key Hook Modules

• Smart Compaction (PreCompact/PostCompact): This system preserves critical context (decisions, error-fix sequences) across compaction events. It captures a state checkpoint before compaction and re-injects the critical parts afterward to prevent information loss.
  Sources: skills/token-optimizer/references/optimization-checklist.md:325-345
• Read Cache (PreToolUse): Intercepts file read operations to detect if the content is already known, saving significant tokens on repetitive file analysis.
  Sources: HOOKS.md:27-29, plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md:215-220
• Session Metrics (SessionEnd): Runs asynchronously at the end of a session to flush metrics to a local SQLite database (trends.db) and generate a performance dashboard.
  Sources: HOOKS.md:46-48, skills/token-coach/SKILL.md:65-75

Security Boundaries and Consent

The system implements a strict "Consent Gate" managed by the run.py dispatcher. Before any target script is executed, the dispatcher reads a local config.json to verify user permissions.

Data Privacy

• No Network Access: The hooks are designed with zero network calls (no HTTP clients or sockets imported), effectively preventing data exfiltration.
• Scoped Writes: Hook scripts are restricted to writing data only within the Token Optimizer's designated data directories. They do not modify the user's project source code.
• Credential Redaction: Scripts like archive_result.py and subprocess_env_scrub are used to ensure credentials and secrets are stripped from stored logs or subprocess environments.

Sources: HOOKS.md:93-110, plugins/token-optimizer/skills/token-optimizer/references/agent-prompts.md:480-485

Configuration and Management

Hooks are configured within the host platform's settings.json file. The Hook Execution System can be tuned through environment variables and specific configuration keys.

Optimization Variables

Variable	Description
TOKEN_OPTIMIZER_READ_CACHE	Enables/disables the read cache hook (set to 0 for native deduplication in newer versions).
trigger	In PostCompact hooks, identifies if the event was "manual" or "auto".
decision:block	In Stop hooks, can re-invoke the model to force processing before exit.
if field	Supported in v2.1.85+ to allow conditional hook execution (e.g., "if": "tool_uses").

Sources: plugins/token-optimizer/skills/token-optimizer/references/agent-prompts.md:450-460, plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md:215-225

Installation and Health

Users can manage the hook lifecycle through the measure.py utility:

• Check Status: python3 $MEASURE_PY check-hook verifies if hooks are currently active.
• Installation: python3 $MEASURE_PY setup-hook proposes and applies hook registrations to the host configuration.
• Security Reporting: python3 measure.py security-report generates a report on installed hooks, file permissions, and consent status.

Sources: plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md:120-130, HOOKS.md:127-133

Conclusion

The Hook Execution System provides a robust and secure framework for extending the capabilities of the host platform. By maintaining strict subprocess isolation, a fail-open execution model, and a centralized consent gate, it allows for sophisticated context management and performance optimization while ensuring that the developer's primary workflow and source code remain protected.