Skip to main content
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, 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).
  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:
CommandSubcommands called
entire checkpoint rewindread-transcript, reassemble-transcript, extract-modified-files
entire statusget-transcript-position
entire session resumeformat-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.