Hook Layer

Relevant source files

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

• .agents/hooks/README.md
• src/cli/lib/install.js
• assets/install-manifest.json
• README.md
• AGENTS.md
• test/cli.test.js

The Hook Layer in Delano provides a mechanism for injecting automated behaviors and context-awareness into agent sessions and tool execution. It primarily operates through file-backed configurations and scripts that bridge the gap between the shared runtime and specific agent environments, such as Codex.

The purpose of this layer is to ensure that agents have immediate access to current project state and delivery metrics without manual intervention. By utilizing hooks, the system can automatically track sessions, log user prompts, and fix environment-specific issues like Git worktree health during runtime.

Sources: README.md, .agents/hooks/README.md, AGENTS.md

Hook Architecture and Core Components

The Hook Layer is structured as a collection of shared assets located within the .agents/hooks/ directory. These assets are managed by the Delano CLI and distributed via the install command.

Distribution and Integration

During the installation process, the CLI identifies assets matching the codex-hooks category. It treats .codex/hooks.json specially: if the file already exists in the target repository, the CLI merges Delano's hooks into the existing configuration rather than overwriting it.

Sources: src/cli/lib/install.js:14-18, src/cli/lib/install.js:464-478

Key Hook Scripts

The following table summarizes the primary hook assets included in the runtime:

Asset	Type	Description
codex-session-status.js	Script	Injects compact open-project context upon session start/resume.
session-tracker.js	Script	Tracks and records active agent session data.
user-prompt-logger.js	Script	Handles privacy-safe logging of user prompts.
post-tool-logger.js	Script	Logs outcomes and evidence after tool execution.
bash-worktree-fix.sh	Shell	Fixes Git worktree issues during runtime operations.
.codex/hooks.json	Config	Manifest defining when and how these hooks are triggered by Codex.

Sources: assets/install-manifest.json:17-22, src/cli/lib/install.js:415-419, README.md

Codex Integration Flow

The integration with the Codex agent environment is a primary focus of the hook layer. The system uses a SessionStart hook to provide the agent with a summary of the current project state.

The diagram below illustrates the process of activating and executing a Delano hook within a Codex session:

Configuration and Merging Logic

The Delano CLI employs specific logic to ensure that existing user configurations for hooks are not destroyed. This is managed via the mergeCodexHooksConfig function, which appends Delano hooks to the SessionStart array if they are not already present.

Validation and Safety

• Existence Check: The CLI checks if a command referencing codex-session-status.js is already in the hook list to prevent duplicate injections.
• Privacy: Hooks are designed to respect privacy boundaries; for example, user-prompt-logger.js ensures prompts are handled according to opt-in rules.
• Permissions: Shell scripts like bash-worktree-fix.sh are handled with specific mode-setting logic during installation to maintain execution permissions.

Sources: src/cli/lib/install.js:571-591, test/cli.test.js:338-369, AGENTS.md

Example Configuration Snippet

The hook configuration defines matchers and timeouts for specific triggers.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$(git rev-parse --show-toplevel)/.agents/hooks/codex-session-status.js\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Sources: src/cli/lib/install.js:540-547, test/cli.test.js:379-385

Summary

The Hook Layer acts as the automated "connective tissue" of the Delano runtime. By integrating directly with agent execution cycles (specifically Codex), it ensures that the "Local Dossier" philosophy is maintained—keeping planning and evidence current without requiring the operator to manually refresh the agent's context.

Sources: README.md, PRODUCT.md