Agent Hooks: The Integration Layer Between Entire CLI and Your Agent

Imagine you prompt an agent to "add pagination to the API."

A few minutes later, it updates api/routes.go, finishes its turn, and leaves you with a clean diff. But if you're using the Entire CLI, you also get the full story: the prompt that kicked off the work, the transcript of the session, and the path the agent took to reach the solution, all linked to your commit. This happens in the background by design through a mechanism called agent hooks.

Hooks are callbacks that fire at key moments during an agent session: when a session starts, a prompt is submitted, or a turn ends. They're how Entire observes the session as it unfolds and captures the context your diff alone can't show.

What are Agent Hooks?

Entire uses two kinds of hooks to bridge the gap between an agent session and your code history.

• Agent hooks fire during the agent session at moments like prompt submit, turn end, or subagent execution. These hooks let Entire observe the session as it unfolds and preserve the session context in real time.
• Git hooks fire during repository operations like commit and push. These hooks let Entire take that captured session context and link it into Git history by adding an Entire-Checkpoint trailer to the user commit, then storing the richer metadata on entire/checkpoints/v1.

By combining the two, Entire ensures that the why captured by agent hooks is never separated from the what stored in Git.

Translating Agent Hooks

Entire supports both built-in agents and external agent plugins. But agents do not expose hooks in the same way. Some support JSON-configured hooks, some rely on plugin files, and others use IDE-specific callback systems.

The Entire CLI handles that with agent-specific code for each built-in agent and external agent plugin. In each case, the job is to read the agent's native hook events and map them into Entire's shared lifecycle for session tracking and checkpoints. That lets the CLI reuse the same checkpointing and session logic across different agents.

Wiring Entire CLI into an Agent

To track an agent session, you need to run entire enable. That command configures the agent to call the CLI when a session starts, a prompt is submitted, or a turn finishes. The agent does that by invoking Entire through hook commands like:

$entire hooks <agent> <hookName>

Entire receives the event, translates it into its shared lifecycle, updates session state, and stores temporary Checkpoint context that Git hooks later condense into commit-linked metadata. The setup stays idempotent and resilient. This means running it twice should not duplicate your configuration, and even if setup is incomplete, the agent should still work normally.

What Happens When a Hook Fires?

When a hook fires, the agent invokes Entire CLI through a command like:

$entire hooks <agent> <hookName>

Once the above command runs, a few things happen:

1. The agent passes a raw event payload that may include the session identifier, transcript location, prompt data, tool activity, or other metadata.
2. The built-in agent or external agent plugin parses that payload and maps it to Entire's shared lifecycle, giving Entire a consistent way to understand events like session start, prompt submit, turn end, or subagent activity.
3. Entire updates session state and captures the context needed to build a checkpoint, preserving that data in temporary session storage until it can be linked to a commit.
4. Git hooks later attach that stored context to your repository history, connecting the code that changed to the agent session that produced it.

This is what allows a commit to reflect not only what changed, but also the session that explains why it changed.

Why This Structure Works

Different agents already expose different hook and transcript behaviors, so Entire keeps the agent-specific parts small and localized: installation, event parsing, and transcript discovery.

Both built-in agents and external agent plugins map into the same shared lifecycle. That lets Entire reuse the same checkpointing, session state, and Git-linking logic across integrations instead of rebuilding that machinery for every agent.

That separation matters beyond the CLI itself. Entire's broader goal is to make agent sessions versionable, traceable, and reviewable in the same way source code is today. Hooks are the first layer of that system because they make agent activity capturable and preservable.

Try Entire in Your Workflow

Building with agents should not mean losing sight of how your code evolves. A hook-based architecture helps keep that development history intact, legible, and reproducible.

If you want to add support for an agent that Entire does not natively support, you can build an external agent using the external agent plugin interface. Our previous post, Bring Your Own Agent to Entire, walks through the process.

Install the Entire CLI to start tracking your sessions today. You can also explore our documentation or join our Discord server to build alongside our community.