> _**CLI skill · `agent` namespace** · ~19,338 tokens_

# `agent` — run AI coding agents in a container: delegate work, subagents, memory, branches

## Purpose

This is the **programmatic control plane for running AI coding agents inside a container** — 47 services / 239 methods that let you delegate a task to a remote agent, drive it across turns, and read back its messages, diffs, and git branches, all over the API. It also exposes the agent's persistent **memory** (blocks + journal), its **capabilities** (model providers, MCP tool servers, skills, tools), a multi-agent **orchestration** layer ("God Mode": an orchestrator that plans, an executor that spawns worker sub-sessions, verifiers that gate each with a PASS/FAIL, a phase reviewer), and the **subagent roster** (configured CLI agents, RSI reviewers, verifiers).

**Workspaces is the GUI, not the namespace.** Hoody ships a full browser GUI — *Workspaces* — that is one optional human-facing client of this exact surface; everything it does (run sessions, branch/PR, wire MCP, edit memory, orchestrate) is reachable here via the SDK or raw HTTP, and vice-versa (the CLI can't authenticate to this kit — see the CLI caveat in Quirks). Hand a person the URL `https://{P}-{C}-workspaces-1.{N}.containers.hoody.icu` when they want a screen; reach for this namespace when you want automation. The kit slug is `workspaces` (`agent` ↔ `workspaces` rename; instance index `1`, i.e. the URL segment `workspaces-1`); resolve the URL with `getKitUrl('agent', container)`. Most endpoints live under `/api/v1/workspaces/*`; the one-shot `hoody agent prompt *` delegate endpoints (and a couple of cross-session listers) live under `/api/v1/agent/*`.

## When to use

- **Delegate a coding/automation task to an agent in a remote container** and collect its result — quickest path is `hoody agent prompt send` (no workspace bookkeeping); for multi-turn work use `hoody agent sessions create` + `hoody agent sessions prompt`/`hoody agent sessions prompt-async` then read `hoody agent sessions diff`.
- **Run / query subagents** — orchestrate multiple agents and phases ("God Mode") via `hoody agent orchestration *`, and inspect the subagent roster with `hoody agent meta agents`, `hoody agent config cli-agents`, `hoody agent config reviewers`, `hoody agent config verifiers`.
- Give the agent persistent context it consults across runs — memory blocks + searchable journal (`hoody agent memory *`).
- Configure what the agent can do — providers (`hoody agent providers list`), MCP tool servers (`hoody agent mcp status`), skills (`hoody agent skills update`), tools (`hoody agent tools list`), and `hoody agent config update`.
- Run an agent against a git worktree, then inspect its diff, push a branch, open a PR (`hoody agent branches *`).
- Answer an agent's mid-run clarification questions to unblock it (`hoody agent questions *`), or run an RSI multi-reviewer critique of a finished session (`hoody agent sessions rsi *`).
- Hand a human the **Workspaces GUI URL** when they want to drive any of the above through a browser.

## When NOT to use

- One-off shell command or script with no agent loop/session → see `exec` (or `terminal` for an interactive shell).
- Direct container filesystem reads/writes (the worktree itself) → see `files`.
- Projects, containers, container **claims/authorization**, auth, billing, server rentals → see `api`.
- VS Code in a browser tab (editor GUI, not an agent) → see `code`.
- Generic key/value or relational storage → see `sqlite`.
- User-authored knowledge notebooks (distinct from the agent's memory journal) → see `notes`.
- Scheduling recurring jobs → see `cron` (for a recurring agent prompt, schedule a call to `hoody agent sessions prompt`).

## Prerequisites

- Container with `hoody-workspaces` kit installed.
- **A container claim on every kit call — this is the #1 thing that breaks first calls.** Mint one with `hoody containers authorize` (`POST /api/v1/containers/{C}/authorize`) and send BOTH `X-Hoody-Container-Claim: JSON.stringify(data.container_claim)` and `X-Hoody-Token: <your API token>` on every request; a bare `Authorization: Bearer` returns `401 CLAIM_REQUIRED`. The claim is signed and **reusable until `expires_in` (~6h)** — mint once, reuse, re-authorize when it lapses. The SDK wires both headers for you via `withContainer(containerOrId, { kitAuth: { type: 'containerClaim', claim, token } })` (a 2-arg call; `kitAuth` is the second arg, and it does NOT auto-mint — pass the claim in). Raw `curl`/HTTP must attach the two headers by hand. See § Capability URL for the failure taxonomy.
- Workspace created via `hoody workspaces create` and bound via `hoody workspaces bind` before per-workspace calls (the worktree dir must already exist on disk). `workspaceID = "global"` is rejected on every route (`400`, code `global-workspace-rejected`) — it is the project-storage sentinel, not a routable workspace ID. The supported alias is `"home"`, which resolves to the auto-created default workspace; otherwise send the real 24-char hex ID. The top-level `hoody agent prompt send` needs no pre-created workspace.
- For session prompts: a provider configured via `hoody agent config update`. For `hoody agent branches pr create`/`hoody agent branches push`: a configured git remote and resolvable forge token.

## Capability URL

The kit slug is `workspaces` (instance index `1`): `https://{P}-{C}-workspaces-1.{N}.containers.hoody.icu` — get `P`/`C`/`N` from `hoody containers get`. The **root of that URL is the Workspaces GUI** (an SPA; the page itself loads with no token — hand it to a human and they log in with their Hoody account, which mints the claim for them); the API lives mostly under `/api/v1/workspaces/*` (the one-shot `hoody agent prompt *` endpoints under `/api/v1/agent/*`) and needs the claim headers above. You can also run `hoody agent open --url` to print that same browser URL. Claim failures from the kit auth gate: `401 CLAIM_REQUIRED` (no claim), `401 TOKEN_REQUIRED` (claim but no token), `403 CLAIM_MALFORMED` (unparseable), `403 CLAIM_INVALID` (bad signature / expired / wrong container), `403 BINDING_MISMATCH` (token owner ≠ claim subject), `401 TOKEN_INVALID`. → See `SKILL-CLI.md § Proxy URLs` for the slug table and capability-token methodology.

**Reaching a service you host on a container port** (any port, any namespace):

- `https://{projectId}-{containerId}-http-<port>.{node}.containers.hoody.icu` — proxy speaks HTTP to `localhost:<port>`.
- `https://{projectId}-{containerId}-https-<port>.{node}.containers.hoody.icu` — proxy speaks HTTPS to `localhost:<port>` (target needs TLS).

Edge is always `https://`. No alias, firewall edit, or proxy registration needed; capability-token gates still apply.

## Common workflows

### 1. Delegate a task to a remote agent (bootstrap + session)

Single-shot, no workspace bookkeeping: `hoody agent prompt send` (or `hoody agent prompt send-sync` to block for the final reply). Full multi-turn control:

1. `hoody workspaces create`
2. `hoody workspaces bind`
3. `hoody agent config update`
4. `hoody agent sessions create`
5. `hoody agent sessions prompt` (or `hoody agent sessions prompt-async` / `hoody agent sessions abort`)
6. `hoody agent sessions export` / `hoody agent sessions diff` (or `hoody agent sessions message list` to drain output)

### 2. Branch → push → open PR

1. `hoody agent branches create`
2. `hoody agent sessions create` + `hoody agent sessions prompt`
3. `hoody agent branches status` / `hoody agent branches diff`
4. `hoody agent branches push`
5. `hoody agent branches pr create` + `hoody agent branches pr status`
6. `hoody agent branches merge` (dry-run first) + `hoody agent branches delete`

### 3. Add MCP server and call its tools

1. `hoody agent mcp add`
2. `hoody agent mcp oauth start` → `hoody agent mcp oauth complete` (OAuth servers only; `hoody agent mcp oauth remove` to revoke)
3. `hoody agent mcp connect` + `hoody agent mcp status`
4. `hoody agent experimental mcp-resources` / `hoody agent experimental tool-schemas`
5. `hoody agent sessions prompt` + `hoody agent mcp disconnect`

### 4. Memory blocks and journal search

1. `hoody agent memory block set` (specify `scope: "workspace" | "global"`)
2. `hoody agent memory block replace`
3. `hoody agent memory journal create`
4. `hoody agent memory journal search` / `hoody agent memory journal list`

### 5. RSI review of a finished session

1. `hoody agent sessions rsi review`
2. `hoody agent sessions rsi stream`

### 6. Orchestrate / query subagents ("God Mode")

You don't spawn a worker directly — you enqueue work and the executor spawns a worker *session* per item; verifiers gate each, a phase reviewer summarizes. Inspect the roster first with `hoody agent meta agents` / `hoody agent config cli-agents` / `hoody agent config reviewers` / `hoody agent config verifiers`.

1. `hoody agent orchestration todo entry append` — enqueue a task entry (the delegation primitive); group with `hoody agent orchestration phase create`.
2. `hoody agent orchestration executor start` — turn on the dispatch loop (spawns worker sub-sessions).
3. Drive via the planner instead: `hoody agent orchestration orchestrator create-session` → `hoody agent orchestration orchestrator prompt`.
4. Query live subagents: `hoody agent orchestration executor workers list` (→ `[{sessionID, entryID, phase, status}]`); drill into any worker as a normal session with `hoody agent sessions get` / `hoody agent sessions message list`.
5. Observe: `hoody agent orchestration events stream` (SSE event bus).

### 7. Answer the agent's questions (unblock a paused session)

When an agent hits ambiguity it calls its `question` tool, which BLOCKS the session until you respond.

1. `hoody agent questions list` — pending questions across sessions (or watch `hoody agent meta events` for `question.asked`).
2. `hoody agent questions consult` — optional: get a second model's recommendation (read-only; does NOT resolve the question).
3. `hoody agent questions reply` (body field `answers`: `string[][]`) or `hoody agent questions reject` — resumes the agent.

## Quirks & gotchas

- `workspaceID` is 24-char hex (validated via `WORKSPACE_ID_RE`); only container-bound workspaces appear in `hoody workspaces list`.
- `workspaceID = "global"` is rejected everywhere with `400 { code: "global-workspace-rejected" }`; use the `"home"` alias to target the default workspace (resolved via `ensureDefaultWorkspace()`; `503 no-default-workspace` if none exists).
- `hoody agent sessions prompt` returns 409 `session_busy` envelope `{ error, code }` if cancelled mid-init.
- `hoody agent sessions prompt-async` returns 204 immediately (status set at `:1353`), runs detached; provider errors only logged, no completion signal beyond event subscription.
- `hoody agent memory block delete` requires explicit `?scope=` query param, no default.
- Core memory block labels reject `readOnly: true`.
- `hoody agent branches pr create` is rate-limited per-project (429); requires configured remote, picks first remote if no `origin` (fallback at `:1270`).
- RSI gated by `config.rsi.enabled`; disabled returns 403 `rsi_disabled`. Inline reviewers with ad-hoc `name` require `model`.
- RSI runs idempotent on `Idempotency-Key`: retry within TTL replays same `jobID`. SSE emits snapshot first.
- Kit slug is `workspaces`; API reject-lists `workspaces` for proxy hooks/permissions.
- The container claim is **reusable until `expires_in` (~6h)** — mint once via `hoody containers authorize`, reuse, re-authorize when it lapses; you do NOT need a fresh claim per call.
- `withContainer(containerOrId, options)` is a **2-arg** call — `kitAuth` goes in the second arg — and it does NOT mint the claim for you; pass the already-minted claim in `options.kitAuth`.
- **The generic CLI cannot authenticate to this kit.** `kitAuthType` only supports `jwt|password|token` — there is no `containerClaim` branch — so `hoody agent …` / `hoody workspaces …` kit subcommands do not attach the claim and return `401 CLAIM_REQUIRED`. Only *interactive* `hoody shell` auto-mints a claim (the one-shot `hoody shell <id> -- cmd` form does not). For programmatic agent-kit access use the SDK or raw HTTP; the CLI blocks in §Examples show command shape only.
- SDK-only quirk: several generated SDK methods take a non-workspace ID as their FIRST positional argument, breaking the workspace-first norm — `hoody agent mcp connect` / `hoody agent mcp disconnect`, `hoody agent providers oauth authorize`, `hoody agent permissions reply`, and all `branches` `/{id}/…` methods (`hoody agent branches diff`). The HTTP paths themselves stay workspace-first, and the CLI uses order-independent named flags.
- Orchestration: workers are spawned ONLY by the executor (no direct "spawn worker" call — you enqueue with `hoody agent orchestration todo entry append`); the verifier's `verdict` (PASS/FAIL) is authoritative. Note the MITM-overlay services that sit alongside it in this namespace (`hoody agent mitm diagnostics dry-run *` → `/mitm/diagnostics/dry-run`, `hoody agent mitm overlay rebase *` → `/mitm/overlay/rebase`) are NOT part of the multi-agent orchestration flow despite the workspace-scoped naming.

## Common errors

- `409 { error: "Prompt aborted before completion", code: "session_busy" }`.
- `409 { error: "Command aborted before completion" }`.
- `404 Workspace entry {workspaceID} not found` — create workspace before `hoody workspaces bind`/`hoody workspaces unbind`.
- `400 { error: "Invalid workspace ID: <id>", code: "invalid-workspace-id" }` — must match 24-char lowercase hex; the alias `"global"` is NOT accepted on workspace routes (returns code `global-workspace-rejected`).
- `403 { error: "rsi_disabled", message: "RSI is disabled in configuration (config.rsi.enabled = false)." }`.
- `404 { error: "unknown_reviewer" }` — supply `model` for ad-hoc reviewer name.
- `429 Rate limit exceeded` from `hoody agent branches pr create` — per-project limiter.
- `ValidationError: No git remote configured` — bind a remote before forge ops.

## Related namespaces

- `api` — projects, containers, auth, billing, server rentals.
- `exec` — one-off scripts without a session.
- `files` — direct container filesystem access.
- `terminal` — interactive shell beyond `hoody agent sessions shell`.
- `notes` — user-authored notes (separate from agent memory journal).
- `cron` — schedule recurring `hoody agent sessions prompt` triggers.

## Examples

Every step in every example was live-tested against a real `workspaces-1` kit (kit slug is `workspaces`, NOT `agent`). The endpoints used below live under `/api/v1/workspaces/...` (the one-shot `hoody agent prompt *` delegate endpoints, not exercised here, are under `/api/v1/agent/...`). Each step has a copy-pasteable code block in the mode you're reading. Set `P`, `C`, `N` (project id, container id, server name) from `hoody containers get` first, and mint a container claim once (`POST /api/v1/containers/{id}/authorize` returns it; it is reusable until `expires_in` (~6h), so reuse it across the calls below). SDK's `withContainer(container, { kitAuth: { type:'containerClaim', claim, token } })` wires the headers for you (2-arg call; it does not mint — pass the claim in).

⚠ Headers — when calling kit URLs directly (curl/HTTP), you MUST send BOTH `X-Hoody-Container-Claim: <json-stringified claim>` AND `X-Hoody-Token: <api token>` on every request. `Authorization: Bearer …` alone returns `401 { code: "CLAIM_REQUIRED" }`. Live-verified.

⚠ CLI mode caveat — the generic `hoody agent …` / `hoody workspaces …` commands do **not** attach the container claim (the CLI's kit-auth supports only `jwt|password|token`, not `containerClaim`), so they return `401 CLAIM_REQUIRED` against this kit. The `hoody …` blocks below are shown for command/argument shape; for working programmatic access use the SDK or raw HTTP (or interactive `hoody shell`, the only CLI path that auto-mints a claim). Local SDK/HTTP paths are unaffected; to just print the browser URL, run `hoody agent open --url`.

### 1. Bootstrap a workspace and run a session

**Goal:** create a fresh `examples-<random>` workspace, bind it to a container, run one async session prompt, then read messages back. Worktree must exist on disk inside the container BEFORE `hoody workspaces create` (live-verified — `400 worktree does not exist` otherwise).

**Step 1 — make the worktree directory** via the `files` kit, then create the workspace.

```bash
WNAME="examples-$(openssl rand -hex 3)"
WORKTREE="/root/$WNAME"
hoody --container "$C" files operation "${WORKTREE#/}" --mkdir   # mkdir: hidden `files operation` (positional path)
W=$(hoody workspaces create --worktree "$WORKTREE" --name "$WNAME" --color '#22c55e' --visible -o json | jq -r .id)
hoody workspaces bind --workspace-id "$W" --container-id "$C" --project-id "$P" --server-node "$N"
```
**Step 2 — create a session and fire an async prompt** (`hoody agent sessions prompt-async` returns 204 immediately; provider runs detached).

```bash
SID=$(hoody agent sessions create --workspace-id "$W" --title 'bootstrap demo' -o json | jq -r .id)
hoody agent sessions prompt-async --workspace-id "$W" --session-id "$SID" \
  --model-provider-id hoody --model-model-id hoody-free \
  --parts '[{"type":"text","text":"List the files in the worktree"}]'
```
**Step 3 — poll for messages, read the diff, abort if needed.** `hoody agent sessions prompt-async` provides no completion signal — drain via `hoody agent sessions message list` or subscribe to `hoody agent meta events` (SSE).

```bash
hoody agent sessions message list --workspace-id "$W" --session-id "$SID" --limit 20
hoody agent sessions diff --workspace-id "$W" --session-id "$SID"
hoody agent sessions abort --workspace-id "$W" --session-id "$SID"
```
### 2. Set memory blocks + journal entries (workspace vs global scope)

**Goal:** seed a free-form note for the agent to consult, replace part of it, write a journal entry, and search the journal. Reuse `$W` from example 1.

⚠ **Workspace-scoped blocks require a non-`global` projectID** — even on a `hoody workspaces bind`-ed workspace the kit may report `pid is "global"` and reject `scope:"workspace"` with `400 Cannot create workspace-scoped block "<label>": no project detected (pid is "global"). Use global scope instead.` Live-verified. Default to `scope:"global"` unless your container deployment sets a real project context.

**Step 1 — set + read a block.** `value` is the text the agent sees; `description` is metadata.

```bash
hoody agent memory block set --workspace-id "$W" --label notes \
  --scope global --value 'hello world' --description 'demo note'
```
**Step 2 — replace** uses `old_str / new_str` (NOT `search/replace`; live-verified — wrong field names → `400`):

```bash
hoody agent memory block replace --workspace-id "$W" --label notes \
  --scope global --old-str world --new-str examples
```
**Step 3 — journal create + search.** Body field names are `title` + `body` (NOT `content`). Live-verified — `{ content }` returns `400`.

```bash
hoody agent memory journal create --workspace-id "$W" \
  --title 'bootstrap done' --body 'workspace examples-xxx ready' --tags demo
hoody agent memory journal search --workspace-id "$W" --text bootstrap --limit 5
```
**Step 4 — delete the block** (DELETE requires `?scope=global|workspace` query param, no default — live-verified. The generated SDK and CLI do NOT expose a scope flag, so drop to raw `fetch()` whenever you need scoped deletion):

```bash
# Generated CLI has no --scope flag for memory block delete; use HTTP/fetch with ?scope=global instead.
curl -sX DELETE "$KIT/api/v1/workspaces/$W/memory/blocks/notes?scope=global" "${H[@]}"
```
### 3. Configure the provider that drives sessions

**Goal:** read the current per-workspace agent config (provider, default model, permissions), see which models are available from the catalog, then point `model` at a different one. Container ships with `hoody/hoody-free` by default.

**Step 1 — read the active config + list available providers.**

```bash
hoody agent config get --workspace-id "$W" -o json | jq '{provider, model, agent}'
hoody agent providers list --workspace-id "$W" -o json | jq '.all[].id'
```
**Step 2 — switch model** via `hoody agent config update` (PATCH; partial — only fields you send change):

```bash
hoody agent config update --workspace-id "$W" --model hoody/hoody-free
```
**Step 3 — list auth methods for a provider you'd add (e.g. OAuth chain for OpenAI/Anthropic).** `hoody agent providers oauth authorize` returns a URL the user opens; `hoody agent providers oauth callback` finalises with the redirect's `?code=`.

```bash
hoody agent providers auth-methods --workspace-id "$W"
hoody agent providers oauth authorize --provider-id openai --workspace-id "$W" --method 0
```
### 4. Register an MCP tool server

**Goal:** add a local-stdio MCP server (binary on PATH) and a remote one, list status, then remove. ⚠ Body shape is `{ name, config: { type: 'local' | 'remote', ... } }` — flat `{ name, type, command }` returns `400`. Live-verified.

**Step 1 — add a local stdio server.**

```bash
# The CLI's global --config flag (config-file path) hijacks the subcommand's --config
# body flag before it reaches the kit; use HTTP for mcp add (same pattern as the
# memory-block-delete fallback):
curl -sf -X POST "$KIT/api/v1/workspaces/$W/mcp" "${H[@]}" \
  -d '{"name":"demo-local","config":{"type":"local","command":["/usr/local/bin/my-mcp"],"enabled":false,"environment":{"DEBUG":"1"}}}'
```
**Step 2 — add a remote SSE/streamable-HTTP server with OAuth.**

```bash
# Same global --config collision as Step 1 — add the server via HTTP:
curl -sf -X POST "$KIT/api/v1/workspaces/$W/mcp" "${H[@]}" \
  -d '{"name":"demo-remote","config":{"type":"remote","url":"https://mcp.example.com/sse","enabled":false,"oauth":true,"headers":{"X-API-Key":"abc"}}}'
hoody agent mcp oauth start --workspace-id "$W" --name demo-remote
# After redirect, finalize:
hoody agent mcp oauth complete --workspace-id "$W" --name demo-remote --code '<from-redirect>'
```
**Step 3 — connect, status, disconnect, delete.** `hoody agent mcp connect` brings the server up; status reports `connected | disabled | failed | needs_auth | needs_client_registration` (the `failed` and `needs_client_registration` variants carry an `error` string). ⚠ There is no `removeServer` SDK method and no `DELETE /mcp/{name}` route. To "remove" a server, disconnect it and clear stored OAuth via `DELETE /mcp/{name}/auth` (returns `200 {success:true}`).

```bash
hoody agent mcp connect --name demo-local --workspace-id "$W"
hoody agent mcp disconnect --name demo-local --workspace-id "$W"
```
### 5. Branch-based agent run (worktree, diff, push, PR)

**Goal:** create a git worktree branch, send the agent prompts on it, inspect diff, push, open PR. ⚠ `hoody agent branches create` requires the workspace's `worktree` to be a real git repository (`git init` + at least one commit). Live-verified — non-git worktree returns `400`. Workflow shown in HTTP for the canonical path; CLI/SDK mirror.

**Step 1 — git-init the worktree** (one-time, via the `files` kit's git operations or shell into the container with `terminal`/`exec`), then create the branch:

```bash
B=$(hoody agent branches create --workspace-id "$W" --name feature/agent-run --base-branch master -o json | jq -r .id)
```
**Step 2 — drive the agent on this branch, then read the diff.** Sessions created on this workspace pick up the branch worktree directory automatically.

```bash
hoody agent branches diff --id "$B" --workspace-id "$W" --format full
hoody agent branches status --id "$B" --workspace-id "$W"
```
**Step 3 — push, open PR, dry-run merge.** `hoody agent branches pr create` is rate-limited per project (429); requires a configured remote (else `ValidationError: No git remote configured`). `hoody agent branches merge` accepts `dry_run:true` — always run that first.

```bash
hoody agent branches push --id "$B" --workspace-id "$W" --set-upstream
hoody agent branches pr create --id "$B" --workspace-id "$W" --title 'Add TODO.md' --body agent-generated --target master --draft
hoody agent branches merge --id "$B" --workspace-id "$W" --dry-run
```
### 6. RSI multi-reviewer review of a finished session

**Goal:** after the agent finishes a session, run the configured Recursive-Self-Improvement reviewers (or supply ad-hoc ones inline) and stream their critique. ⚠ Disabled returns `403 { error: "rsi_disabled" }`. Inline reviewers with ad-hoc `name` REQUIRE `model` (else `404 unknown_reviewer`). RSI is idempotent on `Idempotency-Key` — retry within TTL replays the same `jobID`.

**Step 1 — kick off the review.** Omit `reviewers` to run all configured ones; pass an array to scope. Inline objects override per-call.

```bash
JOB=$(hoody agent sessions rsi review --workspace-id "$W" --session-id "$SID" \
  --focus 'Check for off-by-one errors and missing tests' \
  --reviewers '[{"name":"strict","model":"hoody/hoody-free"}]' \
  -o json | jq -r .jobID)
```
**Step 2 — stream verdicts (SSE).** First event is a snapshot of state at subscription time, then incremental updates until completion.

```bash
hoody agent sessions rsi stream --workspace-id "$W" --session-id "$SID" --job-id "$JOB"
```
### 7. Image-gen and web-search availability check

**Goal:** sessions can call `imagegen` / `websearch` tools if enabled and authenticated. There's no `imageGen.create` / `webSearch.search` HTTP endpoint — the kit only exposes the *enablement* surface; actual generation runs as a tool call inside `hoody agent sessions prompt`. To trigger one, send a prompt that asks for an image / web result and let the agent invoke the tool.

**Step 1 — check availability.** Live-verified responses: `{enabled:true, model:"hoody/google/gemini-3.1-flash-image-preview", provider:"hoody", authenticated:true}` for image-gen; similar for web-search.

```bash
hoody agent image-gen status --workspace-id "$W"
hoody agent web-search status --workspace-id "$W"
```
**Step 2 — invoke via a session prompt.** Tool gating happens server-side; agent picks the right tool based on instructions.

```bash
hoody agent sessions prompt-async --workspace-id "$W" --session-id "$SID" \
  --model-provider-id hoody --model-model-id hoody-free \
  --parts '[{"type":"text","text":"Generate a 512x512 PNG..."}]'
```
### 8. Question-and-answer flow (orchestrator interrupts)

**Goal:** when an agent session emits a `question` (e.g. "should I rename `foo` → `bar`?"), it pauses until you `reply` or `hoody agent questions reject`. (`hoody agent questions consult` is a separate read-only side-channel for getting a second model's recommendation before you reply — it does not resolve the question.) List → answer → resume.

**Step 1 — list pending questions.**

```bash
hoody agent questions list --workspace-id "$W"
```
**Step 2a — answer it directly** (`reply`). **Step 2b — get a second opinion** (`hoody agent questions consult` — runs the question through `providerID/modelID` and returns a recommended answer to YOU (the caller). It is a stateless side-channel: it does NOT notify the agent or resolve the question, so you must still `reply` (or `hoody agent questions reject`) with the recommendation to unblock the session.) ⚠ `hoody agent questions consult` REQUIRES both `providerID` and `modelID` (live-verified — `400 invalid_type` for missing fields). `note` is an optional human hint.

```bash
hoody agent questions consult --request-id "$QID" --workspace-id "$W" \
  --provider-id hoody --model-id hoody-free --note 'prefer bar'
```
### 9. List and inspect available agent tools (per provider/model)

**Goal:** discover what tools the agent has access to in this workspace. `hoody agent experimental tool-ids` returns a catalog of bare tool-id strings (typical entries: bash, read, glob, grep, edit, write, task, webfetch, todowrite, websearch, imagegen, codesearch, skill, apply_patch, plus `hoody_*` capability tools); `hoody agent experimental tool-schemas` returns full JSON-Schemas tailored to the chosen `providerID/modelID` combination so you can see what arguments each tool accepts.

```bash
hoody agent experimental tool-ids --workspace-id "$W"
hoody agent experimental tool-schemas --provider hoody --model hoody-free --workspace-id "$W"
```
### 10. Tear down a workspace cleanly (cleanup template)

**Goal:** the inverse of example 1 — sessions, branches, MCP servers, memory blocks, then `hoody workspaces unbind` and `hoody workspaces delete`. Always do this for `examples-*` workspaces; they accumulate forever otherwise (worktree on disk too).

**Step 1 — cascade-delete the children** (sessions, journal, blocks, branches, MCP). Each list-then-delete loop scopes only the resources you created.

```bash
for SID in $(hoody agent sessions list --workspace-id "$W" --limit 200 -o json | jq -r '.items[].id'); do
  hoody agent sessions delete --workspace-id "$W" --session-id "$SID"
done
for ID in $(hoody agent memory journal list --workspace-id "$W" -o json | jq -r '.[].id'); do
  hoody agent memory journal delete --workspace-id "$W" --id "$ID"
done
for B in $(hoody agent branches list --workspace-id "$W" -o json | jq -r '.[].id'); do
  hoody agent branches delete --id "$B" --workspace-id "$W"
done
```
**Step 2 — unbind the container, delete the workspace entry, drop the worktree dir.** The kit does NOT delete the worktree on disk — `hoody files delete` it yourself.

```bash
hoody workspaces unbind --workspace-id "$W"
hoody workspaces delete --workspace-id "$W"
hoody --container "$C" files delete "${WORKTREE#/}"  # worktree dir
```
**Step 3 — verify it's gone.**

```bash
hoody workspaces list -o json | jq '.items | length'
```

## Reference

### `hoody agent` (209) — Hoody Agent — AI agent, workspace sessions, tools, skills, memory, and orchestration

| Command | Aliases | Category | Summary | SDK Link | Example |
|---------|---------|----------|---------|----------|---------|
| `hoody agent branches create` |  | write | Create a new branch | `agent.branches.createBranch` | `hoody agent branches create --workspace-id abc-123 --name my-resource --start-command <start_command> --base-branch <base_branch>` |
| `hoody agent branches delete` |  | destructive | Delete a branch | `agent.branches.deleteBranch` | `hoody agent branches delete --id abc-123 --workspace-id abc-123` |
| `hoody agent branches diff` |  | read | Get branch diff | `agent.branches.getBranchDiff` | `hoody agent branches diff --id abc-123 --base <base> --file /home/user/file.txt --format summary --workspace-id abc-123` |
| `hoody agent branches disk-usage` |  | read | Get branch disk usage | `agent.branches.getBranchDiskUsage` | `hoody agent branches disk-usage --id abc-123 --workspace-id abc-123` |
| `hoody agent branches list` |  | read | List all branches | `agent.branches.listBranches` | `hoody agent branches list --workspace-id abc-123` |
| `hoody agent branches merge` |  | action | Merge branch | `agent.branches.mergeBranch` | `hoody agent branches merge --id abc-123 --workspace-id abc-123 --strategy squash --message "Hello" --dry-run --delete-branch` |
| `hoody agent branches pr create` |  | write | Create pull/merge request | `agent.branches.createPR` | `hoody agent branches pr create --id abc-123 --workspace-id abc-123 --title "My Title" --body '{}' --target main --draft` |
| `hoody agent branches pr status` |  | read | Get PR/MR status | `agent.branches.getPRStatus` | `hoody agent branches pr status --id abc-123 --workspace-id abc-123` |
| `hoody agent branches pull` |  | action | Pull from remote | `agent.branches.pullBranch` | `hoody agent branches pull --id abc-123 --workspace-id abc-123 --remote origin` |
| `hoody agent branches push` |  | action | Push branch to remote | `agent.branches.pushBranch` | `hoody agent branches push --id abc-123 --workspace-id abc-123 --remote origin --force --set-upstream` |
| `hoody agent branches remote info` |  | read | Get remote info | `agent.branches.getRemoteInfo` | `hoody agent branches remote info --workspace-id abc-123` |
| `hoody agent branches remote refs` |  | read | List remote branches/tags | `agent.branches.listRemoteRefs` | `hoody agent branches remote refs --remote origin --workspace-id abc-123` |
| `hoody agent branches remote status` |  | read | Get remote tracking status | `agent.branches.getRemoteStatus` | `hoody agent branches remote status --id abc-123 --workspace-id abc-123` |
| `hoody agent branches rename` |  | write | Rename branch display name | `agent.branches.renameBranch` | `hoody agent branches rename --id abc-123 --workspace-id abc-123 --name my-resource` |
| `hoody agent branches reset` |  | action | Reset branch to base | `agent.branches.resetBranch` | `hoody agent branches reset --id abc-123 --workspace-id abc-123` |
| `hoody agent branches retry` |  | action | Retry failed branch | `agent.branches.retryBranch` | `hoody agent branches retry --id abc-123 --workspace-id abc-123` |
| `hoody agent branches status` |  | read | Get branch git status | `agent.branches.getBranchStatus` | `hoody agent branches status --id abc-123 --workspace-id abc-123` |
| `hoody agent config cli-agents` |  | read | List configured external CLI agents (gemini/codex/claude) available for `agent sessions cli-agent start`. `is_default:true` means the response is the built-in DEFAULT_CLI_AGENTS (no user override); `is_default:false` with empty list means the user explicitly cleared the list. | `agent.cliAgents.configListCliAgents` | `hoody agent config cli-agents --workspace-id abc-123` |
| `hoody agent config get` |  | read | Get configuration | `agent.config.get` | `hoody agent config get --workspace-id abc-123` |
| `hoody agent config reviewers` |  | read | List configured RSI (Recursive Self-Improvement) reviewers and whether RSI is enabled. Empty list with enabled:true means no reviewers are pre-configured but inline overrides are still accepted on `agent sessions rsi review`. | `agent.reviewers.configListReviewers` | `hoody agent config reviewers --workspace-id abc-123` |
| `hoody agent config tool-overrides` |  | read | Get workspace tool overrides | `agent.config.getToolOverrides` | `hoody agent config tool-overrides --workspace-id abc-123` |
| `hoody agent config update` |  | write | Update configuration | `agent.config.update` | `hoody agent config update --workspace-id abc-123 --permission read --tool-overrides <tool_overrides> --tool-wake-policy <tool_wake_policy> --yolo --provider <provider> --disabled-providers <disabled_providers> --enabled-providers <enabled_providers> --model claude-opus-4-6 --small-model <small_model> --default-agent <default_agent> --instructions <instructions>` |
| `hoody agent config verifiers` |  | read | List configured self-tuning verifiers and whether self-tuning is enabled. Empty list with enabled:true means no verifiers are pre-configured but inline overrides are still accepted on `agent sessions self-tuning tune` / `amplify`. | `agent.verifiers.configListVerifiers` | `hoody agent config verifiers --workspace-id abc-123` |
| `hoody agent experimental mcp-resources` |  | read | Get MCP resources | `agent.experimental.listMcpResources` | `hoody agent experimental mcp-resources --workspace-id abc-123` |
| `hoody agent experimental tool-ids` |  | read | List tool IDs | `agent.experimental.listToolIds` | `hoody agent experimental tool-ids --workspace-id abc-123` |
| `hoody agent experimental tool-schemas` |  | read | List tools | `agent.experimental.listToolSchemas` | `hoody agent experimental tool-schemas --provider <provider> --model claude-opus-4-6 --workspace-id abc-123` |
| `hoody agent files find` |  | read | Find files | `agent.files.findByName` | `hoody agent files find --query "my search" --type file --limit 10 --workspace-id abc-123` |
| `hoody agent files find-symbols` |  | read | Find symbols | `agent.files.findSymbols` | `hoody agent files find-symbols --query "my search" --workspace-id abc-123` |
| `hoody agent files list` |  | read | List files | `agent.files.list` | `hoody agent files list --path /home/user/file.txt --workspace-id abc-123` |
| `hoody agent files read` |  | read | Read file | `agent.files.readContent` | `hoody agent files read --path /home/user/file.txt --workspace-id abc-123` |
| `hoody agent files search` |  | read | Find text | `agent.files.search` | `hoody agent files search --pattern "TODO" --workspace-id abc-123` |
| `hoody agent files status` |  | read | Get file status | `agent.files.getStatus` | `hoody agent files status --workspace-id abc-123` |
| `hoody agent image-gen status` |  | read | Get image generation status | `agent.imageGen.getStatus` | `hoody agent image-gen status --workspace-id abc-123` |
| `hoody agent mcp add` |  | write | Add MCP server | `agent.mcp.addServer` | `hoody --config '{}' agent mcp add --workspace-id abc-123 --name my-resource` |
| `hoody agent mcp connect` |  | action | Connect an MCP server | `agent.mcp.connect` | `hoody agent mcp connect --name my-resource --workspace-id abc-123` |
| `hoody agent mcp disconnect` |  | action | Disconnect an MCP server | `agent.mcp.disconnect` | `hoody agent mcp disconnect --name my-resource --workspace-id abc-123` |
| `hoody agent mcp oauth authenticate` |  | action | Authenticate MCP OAuth | `agent.mcp.authenticateOAuth` | `hoody agent mcp oauth authenticate --workspace-id abc-123 --name my-resource` |
| `hoody agent mcp oauth complete` |  | action | Complete MCP OAuth | `agent.mcp.completeOAuth` | `hoody agent mcp oauth complete --workspace-id abc-123 --name my-resource --code <code>` |
| `hoody agent mcp oauth remove` |  | destructive | Remove MCP OAuth | `agent.mcp.removeOAuth` | `hoody agent mcp oauth remove --workspace-id abc-123 --name my-resource` |
| `hoody agent mcp oauth start` |  | action | Start MCP OAuth | `agent.mcp.startOAuth` | `hoody agent mcp oauth start --workspace-id abc-123 --name my-resource` |
| `hoody agent mcp status` |  | read | Get MCP status | `agent.mcp.getStatus` | `hoody agent mcp status --workspace-id abc-123` |
| `hoody agent memory block delete` |  | destructive | Delete memory block | `agent.memory.deleteBlock` | `hoody agent memory block delete --workspace-id abc-123 --label my-label` |
| `hoody agent memory block get` |  | read | Get memory block | `agent.memory.getBlock` | `hoody agent memory block get --workspace-id abc-123 --label my-label` |
| `hoody agent memory block list` |  | read | List memory blocks | `agent.memory.listBlocks` | `hoody agent memory block list --workspace-id abc-123` |
| `hoody agent memory block replace` |  | write | Replace in memory block | `agent.memory.replaceBlock` | `hoody agent memory block replace --workspace-id abc-123 --label my-label --scope global --old-str <old_str> --new-str <new_str>` |
| `hoody agent memory block set` |  | write | Set memory block | `agent.memory.setBlock` | `hoody agent memory block set --workspace-id abc-123 --label my-label --scope global --value "hello" --description "My description" --limit 10 --read-only` |
| `hoody agent memory config` |  | read | Get memory config | `agent.memory.getConfig` | `hoody agent memory config --workspace-id abc-123` |
| `hoody agent memory history get` |  | read | Get history event | `agent.memory.getHistoryEvent` | `hoody agent memory history get --workspace-id abc-123 --id abc-123` |
| `hoody agent memory history list` |  | read | List history events | `agent.memory.listHistory` | `hoody agent memory history list --workspace-id abc-123` |
| `hoody agent memory journal count` |  | read | Count journal entries | `agent.memory.countJournalEntries` | `hoody agent memory journal count --workspace-id abc-123` |
| `hoody agent memory journal create` |  | write | Write journal entry | `agent.memory.createJournalEntry` | `hoody agent memory journal create --workspace-id abc-123 --title "My Title" --body '{}' --tags "tag1,tag2" --project-id abc-123 --model claude-opus-4-6 --provider <provider>` |
| `hoody agent memory journal delete` |  | destructive | Delete journal entry | `agent.memory.deleteJournalEntry` | `hoody agent memory journal delete --workspace-id abc-123 --id abc-123` |
| `hoody agent memory journal get` |  | read | Get journal entry | `agent.memory.getJournalEntry` | `hoody agent memory journal get --workspace-id abc-123 --id abc-123` |
| `hoody agent memory journal list` |  | read | List journal entries | `agent.memory.listJournalEntries` | `hoody agent memory journal list --workspace-id abc-123` |
| `hoody agent memory journal search` |  | action | Search journal entries | `agent.memory.searchJournalEntries` | `hoody agent memory journal search --workspace-id abc-123 --text "Hello" --project-id abc-123 --tags "tag1,tag2" --limit 10` |
| `hoody agent meta agents` |  | read | List agents | `agent.meta.listAgents` | `hoody agent meta agents --workspace-id abc-123` |
| `hoody agent meta commands` |  | read | List commands | `agent.meta.listCommands` | `hoody agent meta commands --workspace-id abc-123` |
| `hoody agent meta dispose` |  | action | Dispose instance | `agent.meta.dispose` | `hoody agent meta dispose --workspace-id abc-123` |
| `hoody agent meta events` |  | read | Stream workspace meta events live (SSE). | `agent.meta.subscribeEvents` | `hoody agent meta events --workspace-id abc-123` |
| `hoody agent meta formatter-status` |  | read | Get formatter status | `agent.meta.getFormatterStatus` | `hoody agent meta formatter-status --workspace-id abc-123` |
| `hoody agent meta lsp-status` |  | read | Get LSP status | `agent.meta.getLspStatus` | `hoody agent meta lsp-status --workspace-id abc-123` |
| `hoody agent meta paths` |  | read | Get paths | `agent.meta.getPaths` | `hoody agent meta paths --workspace-id abc-123` |
| `hoody agent meta skills` |  | read | List skills | `agent.meta.listSkills` | `hoody agent meta skills --workspace-id abc-123` |
| `hoody agent meta vcs` |  | read | Get VCS info | `agent.meta.getVcs` | `hoody agent meta vcs --workspace-id abc-123` |
| `hoody agent mitm cooldowns` |  | read | List active per-(rule, session) cooldown records for this scope | `agent.workspaceMitmCooldowns.listWorkspaceMitmCooldowns` | `hoody agent mitm cooldowns --workspace-id abc-123` |
| `hoody agent mitm diagnostics dry-run` |  | read | Pure rule-firing simulation against the current snapshot. No actions execute, no cooldowns claimed | `agent.dryRun.diagnoseWorkspaceMitmDryRun` | `hoody agent mitm diagnostics dry-run --workspace-id abc-123 --event session.created --session-tags <session_tags> --depth 0 --tool-name <tool_name> --role user --message-content <message_content>` |
| `hoody agent mitm diagnostics match-trace` |  | read | Per-rule trace explaining each filter check (event/depth/tags/toolName/role/contentMatch). Debug 'why didn't this fire?' | `agent.matchTrace.diagnoseWorkspaceMitmMatchTrace` | `hoody agent mitm diagnostics match-trace --workspace-id abc-123 --event session.created --session-tags <session_tags> --depth 0 --tool-name <tool_name> --role user --message-content <message_content>` |
| `hoody agent mitm events` |  | read | Live SSE stream of MITM rule firings. Scope-bound; epoch-tagged Last-Event-ID for restart detection | `agent.events.streamWorkspaceMitmEvents` | `hoody agent mitm events --workspace-id abc-123` |
| `hoody agent mitm logs get` |  | read | Single MITM log entry by id (redacted by default; admin opts in via Hoody-MITM-Include-Secrets: 1 header for unredacted) | `agent.workspaceMitmLogEntry.getWorkspaceMitmLogEntry` | `hoody agent mitm logs get --workspace-id abc-123 --id abc-123` |
| `hoody agent mitm logs list` | ls | read | Paginated MITM rule firing log (redacted projection; admin via Hoody-MITM-Include-Secrets header for full body) | `agent.workspaceMitmLogsPaginated.listWorkspaceMitmLogsPaginated` | `hoody agent mitm logs list --page 1 --limit 50 --session-id abc-123 --workspace-id abc-123` |
| `hoody agent mitm overlay rebase` |  | action | Re-validate every overlay patch against the current base. 409 + diff if a merged rule fails validation. Returns warnings[] for ghost-shadow cases | `agent.rebase.rebaseWorkspaceMitmOverlay` | `hoody agent mitm overlay rebase --workspace-id abc-123` |
| `hoody agent mitm overlay reset` |  | destructive | Drop the entire overlay for this scope. Effective state reverts to base config only (admin + If-Match) | `agent.reset.resetWorkspaceMitmOverlay` |  |
| `hoody agent mitm plugin-descriptors` |  | read | List loaded plugins with id, source (internal/npm/file), exportName, hooks, tools, auth provider | `agent.workspaceMitmPluginDescriptors.listWorkspaceMitmPluginDescriptors` | `hoody agent mitm plugin-descriptors --workspace-id abc-123` |
| `hoody agent mitm rules create` | new | write | Create an overlay-only MITM rule (admin + If-Match) | `agent.workspaceMitmRule.createWorkspaceMitmRule` |  |
| `hoody agent mitm rules delete` | rm | destructive | Delete an overlay rule (or tombstone a base rule so it stops firing) | `agent.workspaceMitmRule.deleteWorkspaceMitmRule` | `hoody agent mitm rules delete --workspace-id abc-123 --id abc-123` |
| `hoody agent mitm rules enable` |  | write | Persistent enable/disable of a rule via overlay enabledOverride (survives restart) | `agent.enable.setWorkspaceMitmRuleEnabled` | `hoody agent mitm rules enable --workspace-id abc-123 --id abc-123 --enabled` |
| `hoody agent mitm rules list` | ls | read | List effective MITM rules with overlay provenance and effectiveEnabled flag | `agent.workspaceMitmRules.listWorkspaceMitmRules` | `hoody agent mitm rules list --workspace-id abc-123` |
| `hoody agent mitm rules patch` |  | write | Patch an overlay rule (shallow merge; explicit null deletes a field) | `agent.workspaceMitmRule.patchWorkspaceMitmRule` | `hoody agent mitm rules patch --workspace-id abc-123 --id abc-123 --body '{}'` |
| `hoody agent mitm rules replace` |  | write | Replace an overlay rule (full PUT). Sets baseContentHash for stale-detection if id matches a base rule | `agent.rules.replaceWorkspaceMitmRule` | `hoody agent mitm rules replace --workspace-id abc-123 --id abc-123 --name my-resource --enabled --description "My description" --severity info --trigger-event <trigger.event> --trigger-tags <trigger.tags> --trigger-tool-name <trigger.tool_name> --trigger-role <trigger.role> --trigger-content-match <trigger.content_match> --action <action> --cooldown-ms 0 --max-depth 1 --blocking` |
| `hoody agent mitm rules transient-enable` |  | write | Transient (TTL'd) enable/disable. Volatile — does NOT persist. Admin required for shell/webhook rules and unknown rule ids | `agent.transientEnable.setWorkspaceMitmRuleTransientEnabled` | `hoody agent mitm rules transient-enable --workspace-id abc-123 --id abc-123 --enabled --ttl-ms 300000` |
| `hoody agent mitm sessions tags patch` |  | write | Replace mitm_tags on a session. Escalation gate: shell/webhook-triggering tags require admin | `agent.sessionMitmTags.patchSessionMitmTags` | `hoody agent mitm sessions tags patch --workspace-id abc-123 --session-id abc-123 --tags "tag1,tag2"` |
| `hoody agent mitm snapshot` |  | read | Get the effective MITM state — composed view of base config + overlay + transient enables | `agent.workspaceMitmSnapshot.getWorkspaceMitmSnapshot` | `hoody agent mitm snapshot --workspace-id abc-123` |
| `hoody agent mitm tags create` | new | write | Create an overlay-only MITM tag (admin + If-Match) | `agent.workspaceMitmTag.createWorkspaceMitmTag` |  |
| `hoody agent mitm tags delete` | rm | destructive | Delete an overlay tag (or tombstone a base tag) | `agent.workspaceMitmTag.deleteWorkspaceMitmTag` | `hoody agent mitm tags delete --workspace-id abc-123 --id abc-123` |
| `hoody agent mitm tags list` | ls | read | List effective MITM tags | `agent.workspaceMitmTags.listWorkspaceMitmTags` | `hoody agent mitm tags list --workspace-id abc-123` |
| `hoody agent mitm validation-rules` |  | read | Introspect the MitmValidationRule constraint set the server applies (range, regex, enum, depends-on, max-length) | `agent.workspaceMitmValidationRules.listWorkspaceMitmValidationRules` | `hoody agent mitm validation-rules --workspace-id abc-123` |
| `hoody agent mitm webhooks verify` |  | action | Synthetic one-shot webhook delivery via safeFetch for diagnostics. Returns status + elapsedMs + truncated body preview | `agent.verify.verifyWorkspaceMitmWebhook` | `hoody agent mitm webhooks verify --workspace-id abc-123 --url https://example.com --method POST --headers <key=value> --body-json <body_json>` |
| `hoody agent open` |  | action | Open the Agent kit service (Hoody Workspaces) in your browser |  | `hoody agent open [index] [--url]` |
| `hoody agent orchestration budget edit` |  | write | Edit entry budget (sets budget_human_locked) | `agent.orchestration.budgetEdit` | `hoody agent orchestration budget edit --workspace-id abc-123 --entry-id 1 --budget-usd 10` |
| `hoody agent orchestration budget lock` |  | action | Toggle budget_human_locked on an entry | `agent.orchestration.budgetLock` | `hoody agent orchestration budget lock --workspace-id abc-123 --entry-id 1` |
| `hoody agent orchestration budget status` |  | read | Get global budget status with per-entry breakdown | `agent.orchestration.budgetGetStatus` | `hoody agent orchestration budget status --workspace-id abc-123` |
| `hoody agent orchestration budget update` |  | write | Update global budget (max project spend) | `agent.orchestration.budgetUpdateGlobal` | `hoody agent orchestration budget update --workspace-id abc-123 --max-project-spend-usd 10` |
| `hoody agent orchestration config get` |  | read | Get orchestration config | `agent.orchestration.getConfig` | `hoody agent orchestration config get --workspace-id abc-123` |
| `hoody agent orchestration config update` |  | write | Patch orchestration config (partial update) | `agent.orchestration.updateConfig` | `hoody agent orchestration config update --workspace-id abc-123 --body '{}'` |
| `hoody agent orchestration debug-dump` |  | read | Export full orchestration debug dump | `agent.orchestration.getDebugDump` | `hoody agent orchestration debug-dump --workspace-id abc-123` |
| `hoody agent orchestration events connections` |  | read | Get SSE connection count | `agent.orchestration.getEventsConnections` | `hoody agent orchestration events connections --workspace-id abc-123` |
| `hoody agent orchestration events stream` |  | read | Stream all orchestration events live (SSE). Supports `?since_seq=N` resume on reconnect. | `agent.orchestration.streamEvents` | `hoody agent orchestration events stream --workspace-id abc-123` |
| `hoody agent orchestration executor force-dispatch` |  | action | Force an executor dispatch cycle with diagnostics | `agent.orchestration.executorForceDispatch` | `hoody agent orchestration executor force-dispatch --workspace-id abc-123` |
| `hoody agent orchestration executor locks` |  | read | Get file locks per entry | `agent.orchestration.executorGetLocks` | `hoody agent orchestration executor locks --workspace-id abc-123` |
| `hoody agent orchestration executor pause` |  | action | Pause executor dispatching | `agent.orchestration.executorPause` | `hoody agent orchestration executor pause --workspace-id abc-123` |
| `hoody agent orchestration executor resume` |  | action | Resume executor dispatching | `agent.orchestration.executorResume` | `hoody agent orchestration executor resume --workspace-id abc-123` |
| `hoody agent orchestration executor reverify` |  | action | Re-run verification only (skip worker) | `agent.orchestration.executorReverifyEntry` | `hoody agent orchestration executor reverify --workspace-id abc-123 --entry-id 1` |
| `hoody agent orchestration executor start` |  | action | Start executor dispatch loop | `agent.orchestration.executorStart` | `hoody agent orchestration executor start --workspace-id abc-123` |
| `hoody agent orchestration executor status` |  | read | Get executor status | `agent.orchestration.executorGetStatus` | `hoody agent orchestration executor status --workspace-id abc-123` |
| `hoody agent orchestration executor stop-all` |  | action | Stop all workers and pause executor | `agent.orchestration.executorStopAll` | `hoody agent orchestration executor stop-all --workspace-id abc-123` |
| `hoody agent orchestration executor workers list` |  | read | List executor workers | `agent.orchestration.executorGetWorkers` | `hoody agent orchestration executor workers list --workspace-id abc-123` |
| `hoody agent orchestration executor workers stop` |  | action | Stop an executor worker | `agent.orchestration.executorStopWorker` | `hoody agent orchestration executor workers stop --workspace-id abc-123 --session-id abc-123` |
| `hoody agent orchestration import start` |  | action | Start a repo import | `agent.orchestration.startImport` | `hoody agent orchestration import start --workspace-id abc-123 --repo-url https://example.com` |
| `hoody agent orchestration import status` |  | read | Get import job status | `agent.orchestration.getImportStatus` | `hoody agent orchestration import status --workspace-id abc-123 --job-id abc-123` |
| `hoody agent orchestration log get` |  | read | Read tool call log (paginated, filterable) | `agent.orchestration.getLog` | `hoody agent orchestration log get --workspace-id abc-123` |
| `hoody agent orchestration log stream` |  | read | Stream tool-call log live (SSE). NDJSON by default; --output pretty for human display. | `agent.orchestration.streamLog` | `hoody agent orchestration log stream --workspace-id abc-123` |
| `hoody agent orchestration orchestrator create-session` |  | write | Create or resume orchestrator session | `agent.orchestration.orchestratorCreateSession` | `hoody agent orchestration orchestrator create-session --workspace-id abc-123` |
| `hoody agent orchestration orchestrator get-session` |  | read | Get orchestrator session info | `agent.orchestration.orchestratorGetSession` | `hoody agent orchestration orchestrator get-session --workspace-id abc-123` |
| `hoody agent orchestration orchestrator list-sessions` |  | read | Get all orchestrator sessions (planning + per-phase) | `agent.orchestration.orchestratorListSessions` | `hoody agent orchestration orchestrator list-sessions --workspace-id abc-123` |
| `hoody agent orchestration orchestrator phase-session` |  | read | Get phase orchestrator session info | `agent.orchestration.orchestratorGetPhaseSession` | `hoody agent orchestration orchestrator phase-session --workspace-id abc-123 --phase-id 1` |
| `hoody agent orchestration orchestrator prompt` |  | action | Send prompt to orchestrator (with @todo mention resolution) | `agent.orchestration.orchestratorSendPrompt` | `hoody agent orchestration orchestrator prompt --workspace-id abc-123 --text "Hello"` |
| `hoody agent orchestration orchestrator prompt-phase` |  | action | Send prompt to phase orchestrator session | `agent.orchestration.orchestratorPromptPhase` | `hoody agent orchestration orchestrator prompt-phase --workspace-id abc-123 --phase-id 1 --text "Hello"` |
| `hoody agent orchestration phase add-entry` |  | write | Add entry to phase | `agent.orchestration.phasesAddEntry` | `hoody agent orchestration phase add-entry --workspace-id abc-123 --phase-id 1 --entry-id 1` |
| `hoody agent orchestration phase create` |  | write | Create phases | `agent.orchestration.phasesCreate` | `hoody agent orchestration phase create --workspace-id abc-123` |
| `hoody agent orchestration phase delete` |  | destructive | Delete a phase (entries are unphased, not deleted) | `agent.orchestration.phasesDelete` | `hoody agent orchestration phase delete --workspace-id abc-123 --phase-id 1` |
| `hoody agent orchestration phase get` |  | read | Get single phase detail | `agent.orchestration.phasesGet` | `hoody agent orchestration phase get --workspace-id abc-123 --phase-id 1` |
| `hoody agent orchestration phase list` |  | read | List all phases | `agent.orchestration.phasesList` | `hoody agent orchestration phase list --workspace-id abc-123` |
| `hoody agent orchestration phase memory add` |  | write | Attach memory to a phase | `agent.orchestration.phasesAddMemory` | `hoody agent orchestration phase memory add --workspace-id abc-123 --phase-id 1 --text "Hello"` |
| `hoody agent orchestration phase memory clear` |  | destructive | Clear phase memory | `agent.orchestration.phasesClearMemory` | `hoody agent orchestration phase memory clear --workspace-id abc-123 --phase-id 1` |
| `hoody agent orchestration phase memory list` |  | read | List memory entries attached to a phase | `agent.orchestration.phasesListMemory` | `hoody agent orchestration phase memory list --workspace-id abc-123 --phase-id 1` |
| `hoody agent orchestration phase memory list-all` |  | read | Get memory for all phases | `agent.orchestration.phasesGetAllMemory` | `hoody agent orchestration phase memory list-all --workspace-id abc-123` |
| `hoody agent orchestration phase review` |  | action | Manually trigger phase review | `agent.orchestration.phasesReview` | `hoody agent orchestration phase review --workspace-id abc-123 --phase-id 1` |
| `hoody agent orchestration phase summary` |  | read | Get phase summary | `agent.orchestration.phasesGetSummary` | `hoody agent orchestration phase summary --workspace-id abc-123 --phase-id 1` |
| `hoody agent orchestration phase update-rounds` |  | write | Update phase rounds budget | `agent.orchestration.phasesUpdateRounds` | `hoody agent orchestration phase update-rounds --workspace-id abc-123 --phase-id 1 --phase-rounds 10` |
| `hoody agent orchestration phase update-status` |  | write | Manually update phase status | `agent.orchestration.phasesUpdateStatus` | `hoody agent orchestration phase update-status --workspace-id abc-123 --phase-id 1 --status pending` |
| `hoody agent orchestration phase verify` |  | action | Manually trigger phase verification | `agent.orchestration.phasesVerify` | `hoody agent orchestration phase verify --workspace-id abc-123 --phase-id 1` |
| `hoody agent orchestration purge` |  | action | Purge all orchestration data for this workspace | `agent.orchestration.purge` | `hoody agent orchestration purge --workspace-id abc-123` |
| `hoody agent orchestration questions answer` |  | action | Answer a pending question | `agent.orchestration.questionsAnswer` | `hoody agent orchestration questions answer --workspace-id abc-123 --question-id abc-123 --answers <answers>` |
| `hoody agent orchestration questions get` |  | read | Get question detail | `agent.orchestration.questionsGetDetail` | `hoody agent orchestration questions get --workspace-id abc-123 --question-id abc-123` |
| `hoody agent orchestration questions list` |  | read | List pending questions | `agent.orchestration.questionsList` | `hoody agent orchestration questions list --workspace-id abc-123` |
| `hoody agent orchestration todo entry append` |  | action | Append entries to Master TODO | `agent.orchestration.todoAppend` | `hoody agent orchestration todo entry append --workspace-id abc-123` |
| `hoody agent orchestration todo entry delete` |  | destructive | Delete a todo entry | `agent.orchestration.todoDeleteEntry` | `hoody agent orchestration todo entry delete --workspace-id abc-123 --entry-id 1` |
| `hoody agent orchestration todo entry get` |  | read | Read a todo entry | `agent.orchestration.todoGetEntry` | `hoody agent orchestration todo entry get --workspace-id abc-123 --entry-id 1` |
| `hoody agent orchestration todo entry set-priority` |  | write | Update entry priority | `agent.orchestration.todoSetPriority` | `hoody agent orchestration todo entry set-priority --workspace-id abc-123 --entry-id 1 --priority critical` |
| `hoody agent orchestration todo entry set-rounds` |  | write | Set entry budget_rounds | `agent.orchestration.todoSetRounds` | `hoody agent orchestration todo entry set-rounds --workspace-id abc-123 --entry-id 1 --budget-rounds 10` |
| `hoody agent orchestration todo entry set-status` |  | write | Update entry status | `agent.orchestration.todoSetStatus` | `hoody agent orchestration todo entry set-status --workspace-id abc-123 --entry-id 1 --status pending --context-for-next <context_for_next> --mistakes-learned <mistakes_learned>` |
| `hoody agent orchestration todo events` |  | read | Read Master TODO event log | `agent.orchestration.todoGetEvents` | `hoody agent orchestration todo events --page 1 --limit 50 --workspace-id abc-123` |
| `hoody agent orchestration todo read` |  | read | Read full Master TODO state | `agent.orchestration.todoRead` | `hoody agent orchestration todo read --workspace-id abc-123` |
| `hoody agent orchestration todo spec freeze` |  | action | Freeze entry spec | `agent.orchestration.todoFreezeSpec` | `hoody agent orchestration todo spec freeze --workspace-id abc-123 --entry-id 1` |
| `hoody agent orchestration todo spec get` |  | read | Read the spec document | `agent.orchestration.todoReadSpec` | `hoody agent orchestration todo spec get --workspace-id abc-123 --entry-id 1` |
| `hoody agent orchestration todo spec update` |  | write | Update entry spec | `agent.orchestration.todoUpdateSpec` | `hoody agent orchestration todo spec update --workspace-id abc-123 --entry-id 1 --requirements <requirements> --acceptance-criteria <acceptance_criteria> --files-to-create <files_to_create> --files-to-modify <files_to_modify> --patterns "TODO" --api-contract <api_contract> --examples <examples> --integration-points <integration_points>` |
| `hoody agent orchestration vault discover` |  | read | Discover Master TODOs stored in Vault | `agent.orchestration.vaultDiscover` | `hoody agent orchestration vault discover --workspace-id abc-123` |
| `hoody agent orchestration vault import` |  | action | Import a TODO from Vault into local storage | `agent.orchestration.vaultImport` | `hoody agent orchestration vault import --workspace-id abc-123 --source-workspace-id abc-123 --target-workspace-id abc-123` |
| `hoody agent orchestration vault sync` |  | action | Sync local Master TODO snapshot to Vault | `agent.orchestration.vaultSync` | `hoody agent orchestration vault sync --workspace-id abc-123` |
| `hoody agent permissions list` |  | read | List pending permissions | `agent.permissions.list` | `hoody agent permissions list --workspace-id abc-123` |
| `hoody agent permissions overrides` |  | read | Get workspace permission overrides | `agent.permissions.getOverrides` | `hoody agent permissions overrides --workspace-id abc-123` |
| `hoody agent permissions reply` |  | action | Respond to permission request | `agent.permissions.reply` | `hoody agent permissions reply --request-id abc-123 --workspace-id abc-123 --reply once --message "Hello"` |
| `hoody agent project current` |  | read | Get current project | `agent.project.getCurrent` | `hoody agent project current --workspace-id abc-123` |
| `hoody agent project update` |  | write | Update project | `agent.project.update` | `hoody agent project update --project-id abc-123 --workspace-id abc-123 --name my-resource --icon-url <icon.url> --icon-override <icon.override> --icon-color <icon.color> --commands-start <commands.start>` |
| `hoody agent prompt query` |  | read | Execute prompt via query | `agent.prompt.agentPromptGet` | `hoody agent prompt query --ai <ai> --session-id abc-123 --provider-id abc-123 --model-id abc-123 --endpoint https://example.com --api-key <api_key> --key <key> --wait done --auto-approve <auto_approve> --agent my-agent --system linux --workspace ws-abc --directory /home/user/src` |
| `hoody agent prompt send` |  | action | Execute prompt | `agent.prompt.agentPrompt` | `hoody agent prompt send --session-id abc-123 --model-provider-id abc-123 --model-model-id abc-123 --endpoint https://example.com --api-key <api_key> --wait --auto-approve --agent my-agent --system linux --workspace ws-abc --directory /home/user/src` |
| `hoody agent prompt send-sync` |  | action | Execute prompt (synchronous) | `agent.prompt.agentPromptSync` | `hoody agent prompt send-sync --session-id abc-123 --model-provider-id abc-123 --model-model-id abc-123 --endpoint https://example.com --api-key <api_key> --wait --auto-approve --agent my-agent --system linux --workspace ws-abc --directory /home/user/src` |
| `hoody agent providers auth-methods` |  | read | Get provider auth methods | `agent.providers.getAuthMethods` | `hoody agent providers auth-methods --workspace-id abc-123` |
| `hoody agent providers list` |  | read | List providers | `agent.providers.list` | `hoody agent providers list --workspace-id abc-123` |
| `hoody agent providers list-configs` |  | read | List config providers | `agent.providers.listConfigs` | `hoody agent providers list-configs --workspace-id abc-123` |
| `hoody agent providers oauth authorize` |  | action | OAuth authorize | `agent.providers.authorizeOAuth` | `hoody agent providers oauth authorize --provider-id abc-123 --workspace-id abc-123 --method 10` |
| `hoody agent providers oauth callback` |  | action | OAuth callback | `agent.providers.callbackOAuth` | `hoody agent providers oauth callback --provider-id abc-123 --workspace-id abc-123 --method 10 --code <code>` |
| `hoody agent questions consult` |  | action | Consult AI about a question | `agent.questions.consult` | `hoody agent questions consult --request-id abc-123 --workspace-id abc-123 --provider-id abc-123 --model-id abc-123 --note note-abc --question-index 10 --system linux` |
| `hoody agent questions list` |  | read | List pending questions | `agent.questions.list` | `hoody agent questions list --workspace-id abc-123` |
| `hoody agent questions reject` |  | action | Reject question request | `agent.questions.reject` | `hoody agent questions reject --request-id abc-123 --workspace-id abc-123` |
| `hoody agent questions reply` |  | action | Reply to question request | `agent.questions.reply` | `hoody agent questions reply --request-id abc-123 --workspace-id abc-123 --answers <answers>` |
| `hoody agent sessions abort` |  | action | Abort workspace session | `agent.sessions.abort` | `hoody agent sessions abort --workspace-id abc-123 --session-id abc-123` |
| `hoody agent sessions children` |  | read | Get child sessions | `agent.sessions.getChildren` | `hoody agent sessions children --workspace-id abc-123 --session-id abc-123` |
| `hoody agent sessions cli-agent start` |  | action | Start an external CLI agent (gemini/codex/claude) job against the session's working directory. Returns a queued jobID; subscribe to `agent sessions cli-agent stream` for progress. | `agent.workspaceSession.sessionsCliAgentStart` | `hoody agent sessions cli-agent start --workspace-id abc-123 --session-id abc-123 --agent my-agent --prompt <prompt> --model claude-opus-4-6 --git --timeout 10` |
| `hoody agent sessions cli-agent stream` |  | read | Stream CLI agent job progress (SSE). Emits a snapshot first, then live events; exits 0 when the job completes. | `agent.workspaceSession.sessionsCliAgentStream` | `hoody agent sessions cli-agent stream --workspace-id abc-123 --session-id abc-123 --job-id abc-123` |
| `hoody agent sessions create` |  | write | Create workspace session | `agent.sessions.create` | `hoody agent sessions create --workspace-id abc-123 --parent-id abc-123 --title "My Title" --metadata <key=value>` |
| `hoody agent sessions delete` |  | destructive | Delete workspace session | `agent.sessions.delete` | `hoody agent sessions delete --workspace-id abc-123 --session-id abc-123` |
| `hoody agent sessions diff` |  | read | Get workspace session diff | `agent.sessions.getDiff` | `hoody agent sessions diff --workspace-id abc-123 --session-id abc-123 --message-id 1` |
| `hoody agent sessions export` |  | action | Export session (workspace) | `agent.sessions.export` | `hoody agent sessions export --workspace-id abc-123 --session-id abc-123` |
| `hoody agent sessions fork` |  | action | Fork workspace session | `agent.sessions.fork` | `hoody agent sessions fork --workspace-id abc-123 --session-id abc-123 --message-id 1` |
| `hoody agent sessions get` |  | read | Get workspace session | `agent.sessions.get` | `hoody agent sessions get --workspace-id abc-123 --session-id abc-123` |
| `hoody agent sessions init` |  | action | Initialize workspace session config | `agent.sessions.init` | `hoody agent sessions init --workspace-id abc-123 --session-id abc-123 --model-id abc-123 --provider-id abc-123 --message-id 1` |
| `hoody agent sessions list` |  | read | List workspace sessions | `agent.sessions.list` | `hoody agent sessions list --workspace-id abc-123 --page 1 --limit 50 --roots --search "my search"` |
| `hoody agent sessions message get` |  | read | Get workspace session message | `agent.sessions.getMessage` | `hoody agent sessions message get --workspace-id abc-123 --session-id abc-123 --message-id 1` |
| `hoody agent sessions message list` |  | read | List workspace session messages | `agent.sessions.listMessages` | `hoody agent sessions message list --workspace-id abc-123 --session-id abc-123 --limit 10 --role user --after <after>` |
| `hoody agent sessions message part delete` |  | destructive | Delete a part from a session message | `agent.sessions.deletePart` | `hoody agent sessions message part delete --workspace-id abc-123 --session-id abc-123 --message-id 1 --part-id abc-123` |
| `hoody agent sessions message part update` |  | write | Update a part of a session message | `agent.sessions.updatePart` | `hoody agent sessions message part update --workspace-id abc-123 --session-id abc-123 --message-id 1 --part-id abc-123 --body '{}'` |
| `hoody agent sessions message update` |  | write | Update message | `agent.sessions.updateMessage` | `hoody agent sessions message update --workspace-id abc-123 --session-id abc-123 --message-id 1 --model-provider-id abc-123 --model-model-id abc-123` |
| `hoody agent sessions prompt` |  | action | Send message | `agent.sessions.prompt` | `hoody agent sessions prompt --workspace-id abc-123 --session-id abc-123 --message-id 1 --model-provider-id abc-123 --model-model-id abc-123 --agent my-agent --tools <key=value> --system linux --variant default --parts '[]'` |
| `hoody agent sessions prompt-async` |  | action | Send async message | `agent.sessions.promptAsync` | `hoody agent sessions prompt-async --workspace-id abc-123 --session-id abc-123 --message-id 1 --model-provider-id abc-123 --model-model-id abc-123 --agent my-agent --tools <key=value> --system linux --variant default --parts '[]'` |
| `hoody agent sessions revert` |  | action | Revert workspace session message | `agent.sessions.revert` | `hoody agent sessions revert --workspace-id abc-123 --session-id abc-123 --message-id 1 --part-id abc-123` |
| `hoody agent sessions rsi review` |  | action | Start an RSI multi-model review (returns jobID) | `agent.rsi.rsiReviewStart` | `hoody agent sessions rsi review --workspace-id abc-123 --session-id abc-123 --focus <focus> --reviewers <reviewers>` |
| `hoody agent sessions rsi stream` |  | read | Stream RSI review job progress (SSE). Exits 0 when the job completes. | `agent.rsi.rsiStream` | `hoody agent sessions rsi stream --workspace-id abc-123 --session-id abc-123 --job-id abc-123` |
| `hoody agent sessions run-command` |  | action | Send command | `agent.sessions.command` | `hoody agent sessions run-command --workspace-id abc-123 --session-id abc-123 --message-id 1 --agent my-agent --model claude-opus-4-6 --arguments <arguments> --command "ls -la" --variant default --parts '[]'` |
| `hoody agent sessions self-tuning amplify` |  | action | Start a best-of-N self-tuning amplify run (n must be odd, max 11) | `agent.selfTuning.selfTuningAmplifyStart` | `hoody agent sessions self-tuning amplify --workspace-id abc-123 --session-id abc-123 --task <task> --verifier-name <verifier_name> --n 10 --model-provider-id abc-123 --model-model-id abc-123` |
| `hoody agent sessions self-tuning stream` |  | read | Stream self-tuning job progress (SSE). Exits 0 when the job completes. | `agent.selfTuning.selfTuningStream` | `hoody agent sessions self-tuning stream --workspace-id abc-123 --session-id abc-123 --job-id abc-123` |
| `hoody agent sessions self-tuning tune` |  | action | Start a self-tuning tune run (returns jobID) | `agent.selfTuning.selfTuningTuneStart` | `hoody agent sessions self-tuning tune --workspace-id abc-123 --session-id abc-123 --task <task> --verifier-name <verifier_name> --max-iterations 10 --model-provider-id abc-123 --model-model-id abc-123` |
| `hoody agent sessions shell` |  | action | Run shell command | `agent.sessions.shell` | `hoody agent sessions shell --workspace-id abc-123 --session-id abc-123 --agent my-agent --model-provider-id abc-123 --model-model-id abc-123 --command "ls -la"` |
| `hoody agent sessions status` |  | read | Get all workspace session statuses | `agent.sessions.getStatuses` | `hoody agent sessions status --workspace-id abc-123` |
| `hoody agent sessions summarize` |  | action | Summarize session | `agent.sessions.summarize` | `hoody agent sessions summarize --workspace-id abc-123 --session-id abc-123 --provider-id abc-123 --model-id abc-123 --auto <auto> --system-prompt <system_prompt>` |
| `hoody agent sessions summary` |  | read | Get workspace session summary | `agent.sessions.getSummary` | `hoody agent sessions summary --workspace-id abc-123 --session-id abc-123` |
| `hoody agent sessions todo` |  | read | Get workspace session todos | `agent.sessions.getTodo` | `hoody agent sessions todo --workspace-id abc-123 --session-id abc-123` |
| `hoody agent sessions unrevert` |  | action | Unrevert workspace session | `agent.sessions.unrevert` | `hoody agent sessions unrevert --workspace-id abc-123 --session-id abc-123` |
| `hoody agent sessions update` |  | write | Update workspace session | `agent.sessions.update` | `hoody agent sessions update --workspace-id abc-123 --session-id abc-123 --title "My Title" --time-archived <time.archived> --permission read --compaction-override <compaction_override>` |
| `hoody agent sessions update-tags` |  | write | Update session tags | `agent.sessions.updateTags` | `hoody agent sessions update-tags --workspace-id abc-123 --session-id abc-123 --tags "tag1,tag2"` |
| `hoody agent skills delete` |  | destructive | Delete skill | `agent.skills.delete` | `hoody agent skills delete --workspace-id abc-123 --name my-resource` |
| `hoody agent skills discover` |  | read | Discover agent skills | `agent.skills.discover` | `hoody agent skills discover` |
| `hoody agent skills get` |  | read | Get skill | `agent.skills.get` | `hoody agent skills get --workspace-id abc-123 --name my-resource` |
| `hoody agent skills marketplace` |  | read | Browse marketplace | `agent.skills.listMarketplace` | `hoody agent skills marketplace --workspace-id abc-123` |
| `hoody agent skills toggle-builtin` |  | write | Toggle built-in skill | `agent.skills.toggleBuiltin` | `hoody agent skills toggle-builtin --workspace-id abc-123 --name my-resource --enabled` |
| `hoody agent skills update` |  | write | Partially update skill | `agent.skills.update` | `hoody agent skills update --workspace-id abc-123 --name my-resource --description "My description" --content "Hello" --enabled` |
| `hoody agent skills upsert` |  | write | Create or update skill | `agent.skills.upsert` | `hoody agent skills upsert --workspace-id abc-123 --name my-resource --description "My description" --content "Hello" --scope project --enabled` |
| `hoody agent tools list` |  | read | List all tools | `agent.tools.list` | `hoody agent tools list --workspace-id abc-123` |
| `hoody agent web-search status` |  | read | Get web search status | `agent.webSearch.getStatus` | `hoody agent web-search status --workspace-id abc-123` |

### `hoody workspaces` (7) — Hoody Workspaces — projects you operate on (CRUD + container binding)

| Command | Aliases | Category | Summary | SDK Link | Example |
|---------|---------|----------|---------|----------|---------|
| `hoody workspaces bind` |  | action | Bind container to workspace | `agent.workspace.bind` | `hoody workspaces bind --workspace-id abc-123 --container-id abc-123 --project-id abc-123 --server-node node-abc` |
| `hoody workspaces create` | new | write | Create workspace entry | `agent.workspace.workspacesCreate` | `hoody workspaces create --worktree <worktree> --name my-resource --color "#ff0000" --visible --container-container-id abc-123 --container-project-id abc-123 --container-server-name <container.server_name> --container-server-node <container.server_node>` |
| `hoody workspaces delete` | rm | destructive | Delete workspace entry | `agent.workspace.workspacesDelete` | `hoody workspaces delete --workspace-id abc-123` |
| `hoody workspaces get` |  | read | Get workspace | `agent.workspace.workspacesGet` | `hoody workspaces get --workspace-id abc-123` |
| `hoody workspaces list` | ls | read | List workspaces | `agent.workspace.workspacesList` | `hoody workspaces list --page 1 --limit 50` |
| `hoody workspaces unbind` |  | destructive | Unbind container from workspace | `agent.workspace.unbind` | `hoody workspaces unbind --workspace-id abc-123` |
| `hoody workspaces update` |  | write | Update workspace | `agent.workspace.workspacesUpdate` | `hoody workspaces update --workspace-id abc-123 --name my-resource --icon-url <icon.url> --icon-override <icon.override> --icon-color <icon.color> --commands-start <commands.start>` |