diff --git a/changelog.d/docs-hooks-default-followup.md b/changelog.d/docs-hooks-default-followup.md new file mode 100644 index 000000000..1f5db076d --- /dev/null +++ b/changelog.d/docs-hooks-default-followup.md @@ -0,0 +1 @@ +- **Correction to the on-by-default helper hooks entry: the hook still routes only to /review, /qa and /verify, so skills you've installed yourself aren't suggested yet. With gstack's skills it routes 14 of 60 real bug reports (was 17), and long prompts are no longer skipped.** The OpenClaw and Hermes start hook stays off on upgrade whenever it was off, and the one-line "turn it on" hint prints only for an off saved before this release; an off set with `GSTACK_HARNESS_START_HOOK` or `harness_start_hook` stays off without a hint. docs/skill-routing-and-contracts.md (an unreadable config turns all three hooks off; the host table lists the destructive-command check) and docs/hosts.md (only an explicit start-hook request exits 4) now match the code. diff --git a/docs/hosts.md b/docs/hosts.md index 8c45df5e4..0e6d562f0 100644 --- a/docs/hosts.md +++ b/docs/hosts.md @@ -87,7 +87,7 @@ It is on by default (gstack-evals#369: a line on the prompt naming a skill got O **Run the harness's own setup first.** gstack turns the hook on only in a harness that already has its config (`openclaw.json` from `openclaw onboard`, `config.yaml` from `hermes setup`). Without one, the harness CLI would create a config holding nothing but gstack's plugin setting, with no model, provider or terminal settings, so gstack runs no harness command: the plugin's files are written, the hook reports `written` with the setup to run, and `register` and `./setup --host` exit 4. Once the harness is set up, the next `./setup` or `gstack-harness refresh` turns the hook on, changing only the `gstack-start` plugin entry. -**Check it.** The receipt and `gstack-harness status` show `start hook: active` (configured for new sessions; a running OpenClaw gateway or Hermes gateway picks it up when it reloads or restarts), `written` (files in place but not active, with the reason and the command that fixes it), `disabled` (you turned it off in the harness), `unknown` (the harness CLI is not on `PATH`, as inside OpenClaw's or Hermes's own terminal tool, and the config file cannot settle it; gstack reads `plugins.enabled` and `plugins.disabled` from Hermes's `config.yaml` and the plugin entry from `openclaw.json` instead), `unchecked` (a run that left a hook already on alone, or `status --no-check`; `gstack-harness status` checks it) or `off`. When the run that turns the hook on (or `--start-hook`) leaves it inactive, `gstack-harness register` and `./setup --host` exit 4 after registering the skills (`HARNESS_HOOK_INACTIVE`). Later refreshes and upgrades try once more each time, without failing, until the hook is active or you disable the plugin in the harness. +**Check it.** The receipt and `gstack-harness status` show `start hook: active` (configured for new sessions; a running OpenClaw gateway or Hermes gateway picks it up when it reloads or restarts), `written` (files in place but not active, with the reason and the command that fixes it), `disabled` (you turned it off in the harness), `unknown` (the harness CLI is not on `PATH`, as inside OpenClaw's or Hermes's own terminal tool, and the config file cannot settle it; gstack reads `plugins.enabled` and `plugins.disabled` from Hermes's `config.yaml` and the plugin entry from `openclaw.json` instead), `unchecked` (a run that left a hook already on alone, or `status --no-check`; `gstack-harness status` checks it) or `off`. When `--start-hook`, `GSTACK_HARNESS_START_HOOK` or `harness_start_hook` turns the hook on and the run leaves it inactive, `gstack-harness register` and `./setup --host` exit 4 after registering the skills (`HARNESS_HOOK_INACTIVE`); when only the default turned it on, the run does not fail. Later refreshes and upgrades try once more each time, without failing, until the hook is active or you disable the plugin in the harness. **Turn it off.** `gstack-harness register openclaw --no-start-hook` (or `hermes`), which that registration keeps, or `gstack-config set harness_start_hook off` followed by `./setup`, which every registration keeps. Either turns the plugin off through the harness's CLI and removes its folder. You can also switch it off in the harness (`openclaw config set plugins.entries.gstack-start.enabled false`, `hermes plugins disable gstack-start`); gstack then leaves it off and never turns it back on unless you pass `--start-hook` again. `gstack-harness unregister` and `gstack-uninstall` remove it with the rest (Hermes only disables it when its folder holds an edited file or a kept `.edited-*` copy, so your edit survives), and print the harness command to run when the harness CLI is not on `PATH`. In a profile with no harness config yet (no `openclaw.json` or `config.yaml`), the hook was never turned on, so turning it off or unregistering runs no harness command and leaves the config alone. diff --git a/docs/skill-routing-and-contracts.md b/docs/skill-routing-and-contracts.md index affe6c810..c05b10033 100644 --- a/docs/skill-routing-and-contracts.md +++ b/docs/skill-routing-and-contracts.md @@ -15,7 +15,7 @@ Each switch resolves in this order, and the first one set wins: 3. Config: `gstack-config set skill_routing on|off`, `gstack-config set skill_contracts on|off` and `gstack-config set destructive_guard on|off`. 4. The default: `SWITCH_DEFAULT` in `lib/skill-route.ts`, the only place it is written. Setup, the hooks, `gstack-config get|list|defaults` and `gstack-skill-route --default ` all read it. -`on` also accepts yes, true and 1; `off` accepts no, false and 0. Setup warns about any other value, uses the default for that run, and does not save it; the hooks also use the default for such a value. A config file that exists but cannot be read turns both hooks off in setup and in the hooks, whatever the default, because it may hold an `off` you set. +`on` also accepts yes, true and 1; `off` accepts no, false and 0. Setup warns about any other value, uses the default for that run, and does not save it; the hooks also use the default for such a value. A config file that exists but cannot be read turns all three hooks off in setup and in the hooks, whatever the default, because it may hold an `off` you set. Setup registers a hook only when its switch is on, prints one line the first time it registers it, and removes the registration when the switch is off (or with `--no-team`). The hooks also read the switch every time they run, so this takes effect on the next prompt without re-running setup: @@ -29,10 +29,10 @@ The off switch is for people. The text the Stop hook shows the model never menti ## Host support -| Host | Routing hook | Contract Stop hook | Notes | -|---|---|---|---| -| Claude Code | yes | yes | Registered in `~/.claude/settings.json` by `./setup` | -| Codex, OpenCode, Cursor and other hosts | no | no | No hook support. `gstack-skill-contract check` still works on a Claude Code transcript | +| Host | Routing hook | Contract Stop hook | Destructive-command check | Notes | +|---|---|---|---|---| +| Claude Code | yes | yes | yes | Registered in `~/.claude/settings.json` by `./setup` | +| Codex, OpenCode, Cursor and other hosts | no | no | no | No hook support. `gstack-skill-contract check` still works on a Claude Code transcript | ## Routing