@hydra-acp/cli 0.1.4 → 0.1.6

package/README.md

@@ -178,7 +178,7 @@ hydra-acp daemon start
 #    spawned-by-editor cases where stdio is already piped. The first
 #    session/new asks the daemon which agent to spawn (defaults to
 #    config.defaultAgent). If you'd rather the editor pin a specific agent,
-#    spawn `hydra-acp launch <agent-id>` (see "Launcher mode" below).
+#    spawn `hydra-acp launch <agent>` (see "Launcher mode" below).
 
 # 4. From a terminal, drive a session interactively (TUI).
 hydra-acp                                   # bare invocation in a TTY launches the TUI
@@ -198,13 +198,13 @@ hydra-acp --session-id hydra_session_abc123
 hydra-acp                                   # auto-dispatch: TUI in a TTY, shim when stdio is piped
 hydra-acp shim                              # explicit shim mode (forces shim regardless of TTY)
 hydra-acp tui                               # explicit terminal-UI mode
-hydra-acp launch <agent-id>                 # launcher mode: shim that forces the
-                                            # daemon to spawn <agent-id> on session/new
+hydra-acp launch <agent>                    # launcher mode: shim that forces the
+                                            # daemon to spawn <agent> on session/new
 hydra-acp --session-id <id>                 # attach to existing session
                                             # (TUI in a TTY, shim otherwise)
 
 hydra-acp init                              # generate config + auth token
-hydra-acp daemon start [--port N] [--host H]
+hydra-acp daemon start [--foreground]       # detached by default; --foreground to attach
 hydra-acp daemon stop
 hydra-acp daemon status
 
@@ -234,7 +234,7 @@ A bare invocation (`hydra-acp` with no subcommand) auto-dispatches based on whet
 
 ### Launcher mode
 
-`hydra-acp launch <agent-id>` is a convenience for "shim me, and use *this* registry agent." It's the easiest way to wrap an existing ACP-speaking editor configuration whose agent-spawn surface is just a command and arguments:
+`hydra-acp launch <agent>` is a convenience for "shim me, and use *this* registry agent." It's the easiest way to wrap an existing ACP-speaking editor configuration whose agent-spawn surface is just a command and arguments:
 
 ```text
 # Configure your editor's ACP-launch command to:
@@ -243,9 +243,9 @@ hydra-acp launch claude-code
 
 When the editor sends `session/new`, the shim rewrites the params to `{ ..., agentId: "claude-code" }` before forwarding to the daemon. The daemon resolves `claude-code` against the cached ACP Registry, downloads/installs the agent on first use under `~/.hydra-acp/agents/`, and spawns the subprocess. The editor sees a normal ACP agent. From then on, `hydra-acp sessions` lists the live session and any other client can `session/attach` to it.
 
-`<agent-id>` is the registry ID — e.g. `claude-code`, `gemini-cli`, `codex`. Run `hydra-acp agents` to browse what's available, or fetch the registry CDN URL directly.
+`<agent>` is the registry ID — e.g. `claude-code`, `gemini-cli`, `codex`. Run `hydra-acp agents` to browse what's available, or fetch the registry CDN URL directly.
 
-If both `launch <agent-id>` and `--session-id` are given, `--session-id` wins (attach mode); the agent ID is ignored because the agent process is already running.
+If both `launch <agent>` and `--session-id` are given, `--session-id` wins (attach mode); the agent is ignored because the agent process is already running.
 
 ### Naming sessions from the editor
 
@@ -267,7 +267,7 @@ Slash commands of the form `/hydra <verb> [args]` are intercepted by hydra befor
 |---|---|
 | `/hydra title` | Asks the agent for a one-line summary, applies it as the new title via `session_info_update`. The sub-prompt and reply are suppressed from clients. |
 | `/hydra title <text>` | Sets the title to `<text>` directly. No agent call. |
-| `/hydra switch <agent>` | Swaps the agent process backing this session. Spawns the new agent (must be in the registry — see `hydra-acp agents list`), kills the old one, and feeds the conversation transcript so far back in as the first prompt to the new agent. `session_info_update` carries the new `agentId`; a synthetic `agent_message_chunk` banner marks the switch in the transcript. The on-disk session record is updated so resurrection brings the session back on the new agent. |
+| `/hydra agent <agent>` | Swaps the agent process backing this session. Spawns the new agent (must be in the registry — see `hydra-acp agents list`), kills the old one, and feeds the conversation transcript so far back in as the first prompt to the new agent. `session_info_update` carries the new `agentId`; a synthetic `agent_message_chunk` banner marks the switch in the transcript. The on-disk session record is updated so resurrection brings the session back on the new agent. |
 
 These work from anywhere a session prompt can be typed — the TUI's input box, agent-shell, the slack thread composer, the browser chat composer. Hydra detects them server-side; clients send them as ordinary `session/prompt` requests.
 
@@ -284,11 +284,11 @@ hydra-acp sessions import backup.hydra --replace  # overwrites in place
 
 Each session carries a stable **`lineageId`** that survives every export/import hop, so the same bundle imported twice is detected as a duplicate — the second import errors with the existing local id. `--replace` overrides that and overwrites the existing local copy, killing any live session first and preserving the local `sessionId` so bookmarks (Slack threads, editor session links) keep resolving.
 
-The first attach to an imported session is slow: hydra spawns a fresh agent, runs `session/new`, and feeds the imported history back in as a synthesized takeover transcript (same machinery as `/hydra switch`). Subsequent attaches use the normal `session/load` path. This is a text-level handover — the originating agent's internal state (tool-call chains, compacted earlier turns) isn't preserved, so the resumed conversation may be cognitively shallower than the original.
+The first attach to an imported session is slow: hydra spawns a fresh agent, runs `session/new`, and feeds the imported history back in as a synthesized takeover transcript (same machinery as `/hydra agent`). Subsequent attaches use the normal `session/load` path. This is a text-level handover — the originating agent's internal state (tool-call chains, compacted earlier turns) isn't preserved, so the resumed conversation may be cognitively shallower than the original.
 
-### Forwarding agent args (`hydra-acp launch <agent-id> ...`)
+### Forwarding agent args (`hydra-acp launch <agent> ...`)
 
-Anything you put after `<agent-id>` in launcher mode is forwarded to the underlying agent's command. Hydra appends the extra args to the registry-provided spawn plan. Example:
+Anything you put after `<agent>` in launcher mode is forwarded to the underlying agent's command. Hydra appends the extra args to the registry-provided spawn plan. Example:
 
 ```text
 hydra-acp launch codex-acp -c sandbox_mode=danger-full-access
@@ -303,14 +303,17 @@ Every config-knob flag has an `HYDRA_ACP_FOO_BAR` env-var equivalent. Flag wins
 | Flag | Env var |
 |---|---|
 | `--name` | `HYDRA_ACP_NAME` |
-| `--agent-id` | `HYDRA_ACP_AGENT_ID` |
+| `--agent` | `HYDRA_ACP_AGENT` |
+| `--model` | `HYDRA_ACP_MODEL` |
 | `--session-id` | `HYDRA_ACP_SESSION_ID` |
 
+`--model` is a one-shot override for the per-agent `defaultModels` entry in `~/.hydra-acp/config.json`. It only applies at fresh session creation — resurrect and `/hydra agent` switch ignore it (resurrected sessions stay on whatever model they were last using).
+
 Action commands (`init`, `daemon`, `sessions`, `--help`, `--version`, `--rotate-token`) are not config knobs and are flag-only.
 
 ### Registry id resolution
 
-When you ask hydra to spawn an agent (via `launch <id>`, `--agent-id`, or `HYDRA_ACP_AGENT_ID`), the daemon first tries an exact match against the ACP Registry's `id` field. If nothing matches, it falls back to matching against the **npx package basename** (the segment after the last `/` and before the version `@`). That means common binary names work transparently:
+When you ask hydra to spawn an agent (via `launch <agent>`, `--agent`, or `HYDRA_ACP_AGENT`), the daemon first tries an exact match against the ACP Registry's `id` field. If nothing matches, it falls back to matching against the **npx package basename** (the segment after the last `/` and before the version `@`). That means common binary names work transparently:
 
 | You spawn… | Registry `id` | Resolves via |
 |---|---|---|