@hagicode/cli 0.3.0 → 0.4.0

package/README.md

@@ -110,11 +110,11 @@ $ 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
@@ -260,6 +260,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:
@@ -357,8 +368,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 +386,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 +418,15 @@ Send a follow-up message to the HagiTask session:
 hagi hagitask send --session-id "$HAGITASK_ID" --content "Retry with a smaller diff"
 ```
 
+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
@@ -553,6 +584,26 @@ hagi skills gallery search --query react --json
 hagi skills gallery detail --id vercel-react-best-practices --source vercel-labs/agent-skills
 ```
 
+`gallery detail` also shows third-party audit ratings for the skill, supplied by skills.sh (providers such as `ath`, `socket` and `snyk`). In `--json` output every detail field is unchanged and an `audit` object is added. It lists one entry per provider that supplied data; `risk`, `alerts`, `score` and `analyzedAt` appear only when the backend has them:
+
+```json
+{
+  "id": "vercel-react-best-practices",
+  "source": "vercel-labs/agent-skills",
+  "...": "all other detail fields",
+  "audit": {
+    "providers": [
+      { "provider": "ath", "risk": "low", "alerts": 0, "score": 92, "analyzedAt": "2026-10-30T08:00:00Z" },
+      { "provider": "socket", "risk": "medium", "alerts": 2 }
+    ]
+  }
+}
+```
+
+In human output the detail table is followed by one line per provider, for example `skills.sh audit (socket): risk=medium, alerts=2, score=--, analyzedAt=--`, where `--` marks a value the backend did not supply.
+
+The audit is best-effort. If the audit call fails, times out or has no data, the detail still prints and the command exits `0`; in `--json` output `audit.providers` is then `[]`, never missing. The backend bounds the audit wait, and the CLI adds no timeout of its own. A failure of the detail call itself fails the command as before, and the audit never hides it. The audit does not change the install command preview or whether the skill is installable.
+
 Start a managed install of a gallery skill. This writes the skill into your local skill directories, so run it only when you intend to install it:
 
 ```bash
@@ -604,6 +655,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 |