Skip to main content
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:
  1. parse-hook --hook <name>: The CLI calls this command on every hook invocation with the raw payload on stdin. Return a normalized 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).
  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:

​
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.