> ## 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 external agent plugin command

Understanding when each subcommand is called helps you build a correct integration. Here's the full sequence from the CLI's perspective.

## Phase 1: Discovery (CLI startup)

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

1. **`info`** — Called once per discovered binary. The CLI reads your metadata, validates the protocol version, and registers the agent. If this fails, the agent is silently skipped.

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

When a user enables your agent for a repository:

1. **`detect`** — Called to check whether your agent is available in the current environment.
2. **`install-hooks [--local-dev] [--force]`** — Called to install your hooks into the agent (e.g., writing hook config files). Only called if you declare the `hooks` capability.

## Phase 3: Agent session (hooks firing)

Once enabled, your agent's 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 → Event dispatched by type
```

1. **`parse-hook --hook <name>`** — Called on every hook invocation with the raw payload on stdin. Return a normalized [Event](/agents/external-agent-plugins/data-model#event), or `null` if the hook has no lifecycle significance (the CLI will do nothing).

The CLI then routes the event by type:

### SessionStart (type 1)

Fired when the agent 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/external-agent-plugins/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)

Fired 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)

Fired when the agent finishes responding.

1. **`prepare-transcript --session-ref <path>`** — *(if `transcript_preparer` capability)* Pre-process 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)

Fired when the agent compresses its context window. Follows the same flow as **TurnEnd** (save + reset offset).

### SessionEnd (type 5)

Fired when the session terminates. The CLI creates a final checkpoint and cleans up session state.

### SubagentStart / SubagentEnd (types 6–7)

Fired when the agent 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 plugin outside the hook flow:

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

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

1. **`uninstall-hooks`** — Called to remove your installed hooks. Only called if you declare the `hooks` capability.

## Error handling

* **Timeout:** Each subcommand has a 30-second default timeout.
* **Output limits:** Stdout and stderr are each capped at 10 MB. Be mindful of this when implementing `read-transcript` for large sessions.
* **No retries:** The CLI does not retry failed subcommand calls. A non-zero exit code with a message on stderr is treated as a failure.
* **Graceful degradation:** If `parse-hook` returns `null`, the CLI takes no action. If the repo has Entire disabled, hooks exit silently.