@hagicode/cli 0.1.0-dev.38.1.49d2c87 → 0.1.0-dev.41.1.8543fd3

package/README.md

@@ -86,11 +86,12 @@ Every operation command resolves the backend base URL on each invocation, in thi
 
 ```json
 {
-  "baseUrl": "https://hagicode.example.com"
+  "baseUrl": "https://hagicode.example.com",
+  "steer": false
 }
 ```
 
-If none of the three is set, the command exits with code `2` and sends no backend request.
+If none of the three is set, the command exits with code `2` and sends no backend request. The `steer` key is the default for `hagi chat send`, `hagi proposal send`, and `hagi hagitask send` (see [Steer](#steer-send-option)); it must be `true` or `false`.
 
 Operation commands send requests without a credential by default. Pass `--token` (or set `HAGI_API_TOKEN`) only when your backend requires one.
 
@@ -110,17 +111,19 @@ $ echo $?
 hagi
 |-- project   list | repositories | create | update | delete
 |   `-- monospecs show | init | set | validate | reload | clone | remove-checkout
-|-- proposal  list | create | optimize-description | generate | annotate | execute | archive | status | complete | send
+|-- proposal  list | create | optimize-description | generate | annotate | execute | archive | status | complete | send | get | messages
 |-- vault     list | create | update | delete
 |   `-- files list | preview
 |-- chat      list | create | archive | delete | send
-|-- hagitask  list | schema | create | send
+|-- hagitask  list | schema | create | send | get | messages
 |-- plan      list | get | create | update | enable | disable | delete | run
 `-- skills    local list | enable | disable | uninstall
               gallery search | detail | install
               trusted list | upsert | delete | reset
 ```
 
+The `send` commands of `chat`, `proposal`, and `hagitask` also take `--steer` and `--no-steer`, and `HAGI_SEND_STEER` sets the default. See [Steer](#steer-send-option).
+
 ## Example Setup
 
 The examples in the family sections run in order against a local backend. They assume:
@@ -243,6 +246,14 @@ hagi proposal status --session-id "$PROPOSAL_ID" --status Reviewing
 hagi proposal send --session-id "$PROPOSAL_ID" --content "Please continue"
 ```
 
+Steer the message into the running turn, from the environment, or with a normal send that overrides the environment:
+
+```bash
+hagi proposal send --session-id "$PROPOSAL_ID" --content "Please continue" --steer
+HAGI_SEND_STEER=1 hagi proposal send --session-id "$PROPOSAL_ID" --content "Please continue"
+hagi proposal send --session-id "$PROPOSAL_ID" --content "Please continue" --no-steer
+```
+
 The next steps are AI lifecycle actions and need a backend with an AI executor. `optimize-description` writes the optimized title, description, and proposal name to the session in one backend step, and `generate` needs that name. Without the AI executor, or before the name exists, the backend answers with a 400 that names the missing state:
 
 ```bash
@@ -260,6 +271,17 @@ hagi proposal complete --session-id "$PROPOSAL_ID"
 hagi proposal archive --session-id "$PROPOSAL_ID"
 ```
 
+### Follow a Run
+
+`proposal get` reads one session. With `--wait` it polls until the status settles, so the next lifecycle command runs at the right time. `proposal messages` reads the session's messages, newest first.
+
+```bash
+hagi proposal get --session-id "$PROPOSAL_ID" --wait --json
+hagi proposal messages --session-id "$PROPOSAL_ID" --last 1 --json
+```
+
+The options are the same as `hagitask get`. WaitingForReply counts as settled, because a person must answer. Which stage each command starts is in [references/openspec-workflow.md](skills/hagi/references/openspec-workflow.md).
+
 ### Explicit Lifecycle Sequence
 
 The CLI keeps proposal lifecycle actions explicit and non-interactive. Each command maps to one backend action:
@@ -341,6 +363,9 @@ Send a message, archive, and delete:
 
 ```bash
 hagi chat send --session-id "$CHAT_ID" --content "Summarize the current diff"
+hagi chat send --session-id "$CHAT_ID" --content "Summarize the current diff" --steer
+HAGI_SEND_STEER=1 hagi chat send --session-id "$CHAT_ID" --content "Summarize the current diff"
+hagi chat send --session-id "$CHAT_ID" --content "Summarize the current diff" --no-steer
 hagi chat archive --session-id "$CHAT_ID"
 hagi chat delete --session-id "$CHAT_ID"
 ```
@@ -357,8 +382,8 @@ hagi hagitask list --json
 `hagitask schema` shows one task's target scope, commands, parameters, requirements and scenes. Each required parameter is marked `yes`. The `--json` output adds the input JSON Schema and an example request body:
 
 ```bash
-hagi hagitask schema --task-id compose-commit
-hagi hagitask schema --task-id compose-commit --json
+hagi hagitask schema --task-id <task-id>
+hagi hagitask schema --task-id <task-id> --json
 ```
 
 Write the input file. Its keys are the parameter keys the schema lists under `inputs`, plus the `targets` and `targetScopes` keys when the schema's scope lists targets. For example, `input.json` for a task with one required input:
@@ -375,17 +400,28 @@ Create the session from that task and input. The new id is read from `session.se
 
 ```bash
 HAGITASK_ID=$(hagi hagitask create \
-  --title "Auto compose commit" \
+  --title "Auto task" \
   --project-id "$PROJECT_ID" \
-  --task-id compose-commit \
+  --task-id <task-id> \
   --input input.json \
+  --json | json_field '.session.sessionId')
+```
+
+Super Commit is a prompt, not a preset task. It has no schema and takes no `--input`. Start it with its prompt id, and pass the Git options it accepts:
+
+```bash
+SUPER_COMMIT_ID=$(hagi hagitask create \
+  --title "Commit the CLI changes" \
+  --project-id "$PROJECT_ID" \
+  --prompt-id auto-compose-commit.en-US \
   --repository-path repos/cli \
-  --need-push \
   --target-branch-mode new-custom \
   --target-branch-name feature/cli-completion \
   --json | json_field '.session.sessionId')
 ```
 
+Start a Super Commit only when the user asked for it. Add `--need-push` only when the user asked for a push. See [references/super-commit.md](skills/hagi/references/super-commit.md) for the options, the branch modes, the result and the explicit-request rule.
+
 Use `--prompt-id` instead of `--task-id` for a prompt template with no structured input. `--input` needs `--task-id`. Input is read from a file, or from stdin with `--input -`. The CLI only checks that the input is a JSON object. The backend checks the keys and values. It rejects a key that the schema does not list, and a missing required value. Its error is printed unchanged, and no session is reported as created. `--hero-selection-mode` takes `first` (the default) or `random`.
 
 The backend must have a hero available for the task's script. Without one, `hagitask create` fails with a 400 whose error is `no-executable-hero`.
@@ -396,6 +432,23 @@ Send a follow-up message to the HagiTask session:
 hagi hagitask send --session-id "$HAGITASK_ID" --content "Retry with a smaller diff"
 ```
 
+Steer the message into the running task, from the environment, or with a normal send that overrides the environment:
+
+```bash
+hagi hagitask send --session-id "$HAGITASK_ID" --content "Retry with a smaller diff" --steer
+HAGI_SEND_STEER=1 hagi hagitask send --session-id "$HAGITASK_ID" --content "Retry with a smaller diff"
+hagi hagitask send --session-id "$HAGITASK_ID" --content "Retry with a smaller diff" --no-steer
+```
+
+Read one HagiTask session, or wait until its status settles, and read its messages:
+
+```bash
+hagi hagitask get --session-id "$SUPER_COMMIT_ID" --wait --timeout 900 --json
+hagi hagitask messages --session-id "$SUPER_COMMIT_ID" --last 1 --json
+```
+
+`hagitask get` reads one session. With `--wait` it polls every `--interval` seconds (default 5) until the status is no longer Optimizing, Openspecing, Executing or Archiving. `--timeout` (default 900) and `--grace` (default 10, `0` disables) are seconds, and `--timeout`, `--interval` and `--grace` need `--wait`. `--interval` must be less than `--timeout`. A timeout exits `31` and prints the last status. `hagitask messages --last <n>` reads the n newest messages; `--json` prints the list unchanged.
+
 **Migration from AutoTask:** `hagi hagitask create` and `hagi hagitask send` replace `hagi autotask create` and `hagi autotask send`. There is no `autotask` alias, so an `autotask` command now fails as an unknown command. Read the task schema with `hagitask schema` to find the input keys that replace the old flags.
 
 ## Plan Commands
@@ -595,6 +648,45 @@ hagi skills trusted delete --provider-id example-provider
 hagi skills trusted reset
 ```
 
+## Steer (send option)
+
+`hagi chat send`, `hagi proposal send`, and `hagi hagitask send` deliver a message in one of two ways:
+
+- **Normal send** (default): the message waits behind the running turn, as before.
+- **Steer**: the message is inserted into the running turn through the backend's `SteerSession` RPC. The CLI makes one call.
+
+Steer is off unless you ask for it. The first source that is set decides, in this order:
+
+1. `--steer` (on) or `--no-steer` (off) on the command.
+2. `HAGI_SEND_STEER`: `1`, `true`, `yes`, `on` turn Steer on; `0`, `false`, `no`, `off` turn it off. Case and surrounding spaces are ignored. Any other value exits with code `2` and sends no request.
+3. `"steer": true` or `"steer": false` in the config file. Any other type exits with code `2` and names the file.
+4. The default, `false`.
+
+A lower source is not read once a higher one is set, so `--no-steer` works even when `HAGI_SEND_STEER` holds a value the CLI does not recognize.
+
+### Outcomes
+
+- `steered`: a running task took the message. It does not guarantee the text was used: the backend can return a steered message to the queue when the run ends.
+- `queued`: no running task took the message, so it was sent as the next message. This is a success and exits with code `0`. The backend also answers `queued` for an idle session, where the message starts a run at once.
+
+Human output adds `steer`, `effective`, `outcome`, and `messageId` rows, and a line saying no running task took the message for `queued`. `--json` keeps `sessionId`, `message`, and `requested`, and adds a `steer` object: `{ requested, source, effective, outcome?, messageId?, reason? }`. `source` is `flag`, `env`, `config`, or `default`. `reason` appears only when Steer was requested but not used. On the Steer path `message` is `Steered` or `Queued`.
+
+### Conflicts and fallback
+
+Steer carries text only, so it cannot be combined with `--mode` or `--executor-type`:
+
+- `--steer` with either option exits with code `2` and sends nothing.
+- When Steer comes only from `HAGI_SEND_STEER` or the config file, the command sends a normal message with the options and records the reason in `steer.reason`.
+- When Steer comes only from `HAGI_SEND_STEER` or the config file and the backend does not implement `SteerSession`, the command sends a normal message and records the reason `the backend does not support Steer`. An explicit `--steer` reports the backend error instead.
+
+A queued Steer is always sent in `Edit` mode. A session that must keep another mode should send with `--no-steer --mode <mode>`.
+
+Steer works with the executors the backend supports. For any other executor, the backend answers `queued`.
+
+### Unattended messaging
+
+For session-to-session messages sent by an orchestrator without a person watching, set `HAGI_SEND_STEER=1` in its environment. Add `--no-steer` to a single call that must go through the normal queue.
+
 ## Environment Variables
 
 The CLI resolves runtime settings centrally before every command. Explicit flags always override environment variables.
@@ -604,6 +696,7 @@ The CLI resolves runtime settings centrally before every command. Explicit flags
 | `HAGI_API_BASE_URL` | Backend base URL, used when `--base-url` is not given. Overrides the config file. Required when neither is set. |
 | `HAGI_API_TOKEN` | Bearer token attached as `Authorization: Bearer <token>`. |
 | `HAGI_API_LANG` | Shared `Accept-Language` header value. |
+| `HAGI_SEND_STEER` | Turns Steer on (`1`, `true`, `yes`, `on`) or off (`0`, `false`, `no`, `off`) for the send commands, ignoring case and surrounding spaces. Any other value exits with code `2`. Overridden by `--steer` / `--no-steer`. Order: flag, then this variable, then the `steer` config key, then `false`. |
 
 ## Backend Transport
 
@@ -624,6 +717,7 @@ Stable non-zero exits used by the CLI. The HTTP numbers are the equivalents of t
 | `24` | HTTP 404 |
 | `29` | HTTP 409 |
 | `30` | Operation failed: the backend returned a refusal, for example `skills local enable` or `disable` on a name that is not a built-in skill, an invalid MonoSpecs configuration from `project monospecs validate`, or a failed clone from `project monospecs clone` or `set --clone` |
+| `31` | Wait timed out: `--wait` on `proposal get` or `hagitask get` reached `--timeout` before the session settled. The last status is printed. Not a success, and not a backend error |
 | `40` | Other HTTP 4xx |
 | `50` | HTTP 5xx |
 | `60` | Transport or connection failure |