> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle

> When the Entire CLI calls each agent integration command

The CLI calls integration subcommands in five phases.

## Phase 1: Discovery (CLI Startup)

Every time the CLI starts, it scans `$PATH` for binaries matching `entire-agent-<name>`.

1. **`info`**: The CLI calls this command once per discovered binary. It reads your metadata, validates the protocol version, and registers the agent. If this fails, the CLI skips the agent.

## Phase 2: Enable (`entire enable`)

When a user enables your agent for a repository:

1. **`detect`**: The CLI calls this command to check whether your agent is available in the current environment.
2. **`install-hooks [--local-dev] [--force]`**: The CLI calls this command to install your hooks into the agent, such as by writing hook configuration files. It calls this command only when you declare the `hooks` capability.

## Phase 3: Agent Session (Hooks Firing)

After you enable the agent, its hooks fire during normal usage and the CLI processes them. This phase requires the `hooks` capability. Agents that don't declare it won't participate in the hook lifecycle.

Every hook invocation follows this flow:

```
Hook fires → parse-hook normalizes → CLI dispatches Event by type
```

1. **`parse-hook --hook <name>`**: The CLI calls this command on every hook invocation with the raw payload on stdin. Return a normalized [Event](/agents/agent-integration-protocol/data-model#event), or `null` if the hook has no lifecycle significance and the CLI should take no action.

The CLI then routes the event by type:

### SessionStart (Type 1)

The agent fires this event when it begins a new session.

1. **`get-session-id`**: Extract the session ID from the hook input (stdin).
2. **`get-session-dir --repo-path <path>`**: Return where sessions are stored.
3. **`resolve-session-file --session-dir <dir> --session-id <id>`**: Resolve the session file path.
4. **`read-session`**: Read existing session data (stdin: [HookInput](/agents/agent-integration-protocol/data-model#hookinput)).
5. **`write-session`**: Persist updated session data.
6. **`write-hook-response --message <msg>`**: *(optional, if `hook_response_writer` capability)* Write a startup message in your agent's native format.

### TurnStart (Type 2)

The agent fires this event when the user submits a new prompt.

1. **`extract-modified-files --path <path> --offset <n>`**: *(if `transcript_analyzer` capability)* Extract files changed since last checkpoint.
2. The CLI creates a git checkpoint of the current state.

### TurnEnd (Type 3)

The agent fires this event when it finishes responding.

1. **`prepare-transcript --session-ref <path>`**: *(if `transcript_preparer` capability)* Prepare the transcript.
2. **`read-transcript --session-ref <path>`**: Read the raw transcript bytes.
3. **`chunk-transcript --max-size <n>`**: Split large transcripts into storable chunks.
4. **`get-transcript-position --path <path>`**: *(if `transcript_analyzer` capability)* Get the current byte offset.
5. **`extract-modified-files --path <path> --offset <n>`**: *(if `transcript_analyzer` capability)* Extract newly modified files.
6. **`calculate-tokens --offset <n>`**: *(if `token_calculator` capability)* Calculate token usage.
7. The CLI stores a checkpoint in git history.

### Compaction (Type 4)

The agent fires this event when it compresses its context window. The CLI follows the same flow as **TurnEnd** and saves the checkpoint before resetting the offset.

### SessionEnd (Type 5)

The agent fires this event when the session ends. The CLI creates a final checkpoint and cleans up session state.

### SubagentStart / SubagentEnd (Types 6 and 7)

The agent fires these events when it spawns or completes a subagent. If you declare the `subagent_aware_extractor` capability, the CLI calls:

* **`extract-all-modified-files --offset <n> --subagents-dir <dir>`**
* **`calculate-total-tokens --offset <n> --subagents-dir <dir>`**

## Phase 4: User Commands

Some CLI commands invoke your integration outside the hook flow:

| Command                 | Subcommands called                                                                            |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `entire session resume` | `read-transcript`, `reassemble-transcript`, `extract-modified-files`, `format-resume-command` |
| `entire status`         | `get-transcript-position`                                                                     |

## Phase 5: Disable (`entire disable --uninstall`)

1. **`uninstall-hooks`**: The CLI calls this command to remove your installed hooks when you declare the `hooks` capability.

## Error Handling

* **Timeout:** Each subcommand has a default timeout of 30 seconds.
* **Output limits:** The CLI caps stdout and stderr at 10 MB each. Account for this limit when you implement `read-transcript` for large sessions.
* **No retries:** The CLI does not retry failed subcommand calls. It treats a nonzero exit code with a message on stderr as a failure.
* **Graceful degradation:** If `parse-hook` returns `null`, the CLI takes no action. If the repo has Entire disabled, hooks exit silently.