## Required commands

### `info`

Returns metadata and declares which optional capabilities your plugin supports.

```
entire-agent-myagent info
```

```
{
  "protocol_version": 1,
  "name": "myagent",
  "type": "MyAgent",
  "description": "MyAgent - AI-powered code editor",
  "is_preview": true,
  "protected_dirs": [".myagent"],
  "hook_names": ["session-start", "session-end", "stop"],
  "capabilities": {
    "hooks": true,
    "transcript_analyzer": true,
    "transcript_preparer": false,
    "token_calculator": false,
    "text_generator": false,
    "hook_response_writer": false,
    "subagent_aware_extractor": false
  }
}
```

| Field                | Description                                                                 |
| -------------------- | --------------------------------------------------------------------------- |
| `protocol_version`   | Must match the CLI’s expected version (currently `1`)                     |
| `name`               | Registry name (must match the `<name>` in the binary name)                |
| `type`               | Display name / type identifier                                              |
| `description`        | Human-readable description                                                  |
| `is_preview`         | Whether the agent is in preview                                            |
| `protected_dirs`     | Directories the CLI should not modify (excluded from checkpoints and diffs) |
| `hook_names`         | Agent lifecycle hooks this plugin handles                                   |
| `capabilities`       | Object declaring which optional capabilities are supported                  |

### `detect`

Returns whether the agent is available in the current environment. Return `{ "present": false }` if the agent’s dependencies are not met — the CLI will skip enabling the agent.

```
entire-agent-myagent detect
```

```
{"present": true}
```

### `get-session-id`

Extracts a session ID from a hook input event. **stdin:** [HookInput](https://docs.entire.io/agents/external-agent-plugins/data-model#hookinput) JSON

```
{"session_id": "abc123"}
```

### `get-session-dir --repo-path <path>`

Returns where agent sessions are stored.

```
{"session_dir": "/path/to/sessions"}
```

### `resolve-session-file --session-dir <dir> --session-id <id>`

Resolves the session file path from a session directory and ID.

```
{"session_file": "/path/to/session/file.jsonl"}
```

### `read-session`

Reads session data from a hook input event. **stdin:** [HookInput](https://docs.entire.io/agents/external-agent-plugins/data-model#hookinput) JSON **stdout:** [AgentSession](https://docs.entire.io/agents/external-agent-plugins/data-model#agentsession) JSON

### `write-session`

Persists session data to disk. The plugin is responsible for choosing the storage location and format. **stdin:** [AgentSession](https://docs.entire.io/agents/external-agent-plugins/data-model#agentsession) JSON. Exit `0` on success.

### `read-transcript --session-ref <path>`

Reads a transcript file and returns its raw bytes on stdout.

### `chunk-transcript --max-size <n>`

Splits a transcript (raw bytes on stdin) into chunks.

```
{"chunks": ["<base64-encoded-chunk>", "..."]}
```

### `reassemble-transcript`

Reassembles chunks back into a transcript. Called during `entire checkpoint rewind` to reconstruct transcript data from stored chunks. **stdin:**

```
{"chunks": ["<base64-encoded-chunk>", "..."]}
```

**stdout:** Raw transcript bytes.

### `format-resume-command --session-id <id>`

Returns the command a user would run to resume a session.

```
{"command": "myagent --resume abc123"}
```

## Optional capabilities

Set capabilities to `true` in your `info` response to enable these. The CLI will never call subcommands for capabilities you don’t declare.

### `hooks`

Manage agent lifecycle hooks for Entire integration.

| Subcommand            | Description                                                       |
| --------------------- | -----------------------------------------------------------------|
| `parse-hook --hook <name>` | Parse a raw hook payload (stdin) into an [Event](https://docs.entire.io/agents/external-agent-plugins/data-model#event). Return `null` if not relevant. |
| `install-hooks [--local-dev] [--force]` | Install hooks. `--local-dev` installs hooks pointing to a local development build. `--force` overwrites existing hook files. Returns `{"hooks_installed": 3}`. |
| `uninstall-hooks`    | Remove installed hooks. Exit `0` on success.                     |
| `are-hooks-installed` | Check hook status. Returns `{"installed": true}`.               |

### `transcript_analyzer`

Extract data from agent transcripts.

| Subcommand             | Description                                                                                        |
| ---------------------- | --------------------------------------------------------------------------------------------------|
| `get-transcript-position --path <path>` | Returns `{"position": 12345}` (byte offset).                                                          |
| `extract-modified-files --path <path> --offset <n>` | Returns `{"files": [...], "current_position": 12345}`.                            |
| `extract-prompts --session-ref <path> --offset <n>` | Returns `{"prompts": ["prompt text", ...]}`.                                                   |
| `extract-summary --session-ref <path>` | Returns `{"summary": "...", "has_summary": true}`.                                   |

### `transcript_preparer`

| Subcommand                    | Description                                            |
| ----------------------------- | ----------------------------------------------------|
| `prepare-transcript --session-ref <path>` | Pre-process a transcript file. Exit `0` on success. |

### `token_calculator`

| Subcommand                    | Description                                                                                                                                         |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------|
| `calculate-tokens --offset <n>` | Calculate token usage from transcript bytes (stdin). `--offset` is the byte offset into the transcript to start counting from. |

Output:

```
{
  "input_tokens": 1500,
  "output_tokens": 500,
  "cache_creation_tokens": 0,
  "cache_read_tokens": 200,
  "api_call_count": 3
}
```

Only `input_tokens` and `output_tokens` are required. Other fields default to `0`.

### `text_generator`

| Subcommand                     | Description                                                       |
| ------------------------------ | ---------------------------------------------------------------|
| `generate-text --model <model>` | Generate text from a prompt (stdin). Returns `{"text": "..."}`. |

### `hook_response_writer`

| Subcommand                        | Description                                                       |
| -------------------------------- | ---------------------------------------------------------------|
| `write-hook-response --message <msg>` | Write a message in the agent’s native hook format (stdout). |

### `subagent_aware_extractor`

For agents that spawn subagents.

| Subcommand                        | Description                                                                                                          |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------|
| `extract-all-modified-files --offset <n> --subagents-dir <dir>` | Extract modified files from main + subagent transcripts (stdin: main transcript). Returns `{"files": [...]}`. |
| `calculate-total-tokens --offset <n> --subagents-dir <dir>` | Calculate total tokens across main + subagent transcripts (stdin: main transcript). Same format as `calculate-tokens`, with optional `subagent_tokens` nested object. |