mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-22 08:01:32 +01:00
Helper hooks are on by default, the destructive-command check runs as a hook, and prompt routing fires on long bug reports (GST-3110) (#4503)
Claude Code now gets gstack's prompt-routing, skill-contract and destructive-command hooks on by default, and new OpenClaw and Hermes registrations get the start hook. On 60 real bug reports, routing now matches a bug-fix skill on 40 (was 22), but gstack's own skills route 14 (was 17). Why: on Opus 5.5, unattended, a hook line naming a skill got it loaded in 58 of 60 sessions, and a skill relying on its description in 0 of 60 (gstack-evals#369). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> Review-Finding: p1v/outside-voice#1 reader=outside-voice Review-Finding: p1v/adversarial-native#4 reader=adversarial-native Review-Finding: p2/red-team#1 reader=red-team
This commit is contained in:
1 parent
43026970b7
commit
3f1b82b22a
28 files changed
+543
-95
No files matched your search
@@ -204,7 +204,7 @@ The same `/qa` and `/qa-only` commands test CLIs, APIs, jobs, workers and webhoo
|
||||
|-------|-------------|
|
||||
| `/codex` | **Second Opinion** — independent code review from OpenAI Codex CLI. Review, challenge, and consult modes. Available on every harness except Codex. |
|
||||
| `/claude-code` | **Second Opinion** — independent code review from Claude Code. Review, challenge, and consult modes, with session continuity for consultation. Available on every harness except Claude Code. |
|
||||
| `/careful` | **Safety Guardrails** — warns before destructive commands (rm -rf, DROP TABLE, force-push). Say "be careful" to activate. Override any MEDIUM warning; root/home recursive deletes and default-branch force-pushes are hard-denied. |
|
||||
| `/careful` | **Safety Guardrails** — warns before destructive commands (rm -rf, DROP TABLE, force-push). The check runs in every Claude Code session by default; `gstack-config set destructive_guard off` turns it off. Override any MEDIUM warning; root/home recursive deletes and default-branch force-pushes are hard-denied. |
|
||||
| `/freeze` | **Edit Lock** — restrict file edits to one directory. Prevents accidental changes outside scope while debugging. |
|
||||
| `/guard` | **Full Safety** — `/careful` + `/freeze` in one command. Maximum safety for prod work. |
|
||||
| `/unfreeze` | **Unlock** — remove the `/freeze` boundary. |
|
||||
|
||||
+5
-4
@@ -214,7 +214,7 @@ CONFIG_HEADER='# gstack configuration — edit freely, changes take effect on ne
|
||||
# # (a one-line note on every turn to run the start
|
||||
# # command of a skill; edits openclaw.json or config.yaml via the
|
||||
# # harness CLI). off: takes it out. Absent = each
|
||||
# # registration keeps its saved choice (default off).
|
||||
# # registration keeps its saved choice, else on (the default).
|
||||
# # GSTACK_HARNESS_START_HOOK=1|0 overrides it. Docs: docs/hosts.md
|
||||
#
|
||||
# ─── Advanced ────────────────────────────────────────────────────────
|
||||
@@ -353,6 +353,7 @@ lookup_default() {
|
||||
timeline_stop_hook) echo "yes" ;; # yes | no — controls ./setup timeline Stop hook registration (#2677)
|
||||
skill_routing) bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" "$(dirname "$0")/gstack-skill-route" --default skill_routing ;; # on | off — the skill-routing UserPromptSubmit hook; default: SWITCH_DEFAULT in lib/skill-route.ts (docs/skill-routing-and-contracts.md)
|
||||
skill_contracts) bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" "$(dirname "$0")/gstack-skill-route" --default skill_contracts ;; # on | off — the skill-contract Stop hook; default: SWITCH_DEFAULT in lib/skill-route.ts (docs/skill-routing-and-contracts.md)
|
||||
destructive_guard) bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" "$(dirname "$0")/gstack-skill-route" --default destructive_guard ;; # on | off — the destructive-command check (PreToolUse on Bash and PowerShell, /careful's check in every session); default: SWITCH_DEFAULT in lib/skill-route.ts (docs/skill-routing-and-contracts.md)
|
||||
ceo_review_gate) bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" "$(dirname "$0")/gstack-skill-route" --default ceo_review_gate ;; # on | off — the /plan-ceo-review enforcement hooks; default: SWITCH_DEFAULT in lib/skill-route.ts (docs/skill-gates.md)
|
||||
autoplan_gate) bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" "$(dirname "$0")/gstack-skill-route" --default autoplan_gate ;; # on | off — the /autoplan stop gate; default: SWITCH_DEFAULT in lib/skill-route.ts (docs/skill-gates.md)
|
||||
|
||||
@@ -404,7 +405,7 @@ lookup_default() {
|
||||
agent_model) echo "" ;; # empty = host (agents keep their own model); gstack-models resolve --role agent
|
||||
codex_effort) echo "" ;; # empty = each gate's own effort; /codex --effort, then GSTACK_CODEX_EFFORT, win (gstack-codex-probe run-with-timeout --effort)
|
||||
review_effort_tiers) echo "on" ;; # on | off — gstack-review-plan effort tiers (docs/model-policy.md#reasoning-effort)
|
||||
harness_start_hook) echo "" ;; # on | off — empty = each harness registration keeps its saved choice (docs/hosts.md#start-hook)
|
||||
harness_start_hook) echo "" ;; # on | off — empty = each harness registration keeps its saved choice, else on (docs/hosts.md#start-hook)
|
||||
ship_greptile_early) echo "true" ;; # true | false — /ship's early Greptile PR
|
||||
pr_wait_gating_bots) echo "greptile,macroscope" ;; # review bots gstack-pr-wait --until ready waits for
|
||||
pr_wait_advisory_bots) echo "coderabbit" ;; # review bots gstack-pr-wait reports but never waits for
|
||||
@@ -1160,7 +1161,7 @@ $_gstack_legacy_root"
|
||||
ship_measure_max_rounds ship_measure_sweep_cases ship_measure_sweep_budget_usd ship_rerun_backend test_backend \
|
||||
plan_review_tier implementation_tier model_frontier_claude model_frontier_openai \
|
||||
model_smart_claude model_smart_openai codex_effort review_effort_tiers agent_model harness_start_hook \
|
||||
skill_routing skill_contracts ceo_review_gate autoplan_gate plan_record; do
|
||||
skill_routing skill_contracts destructive_guard ceo_review_gate autoplan_gate plan_record; do
|
||||
gstack_config_select "$KEY"
|
||||
VALUE="$_gstack_cfg_value"
|
||||
SOURCE="default"
|
||||
@@ -1186,7 +1187,7 @@ $_gstack_legacy_root"
|
||||
ship_measure_max_rounds ship_measure_sweep_cases ship_measure_sweep_budget_usd ship_rerun_backend test_backend \
|
||||
plan_review_tier implementation_tier model_frontier_claude model_frontier_openai \
|
||||
model_smart_claude model_smart_openai codex_effort review_effort_tiers agent_model harness_start_hook \
|
||||
skill_routing skill_contracts ceo_review_gate autoplan_gate plan_record; do
|
||||
skill_routing skill_contracts destructive_guard ceo_review_gate autoplan_gate plan_record; do
|
||||
printf ' %-24s %s\n' "$KEY:" "$(lookup_default "$KEY")"
|
||||
done
|
||||
;;
|
||||
|
||||
@@ -132,6 +132,7 @@ var KNOWN_HOOKS = {
|
||||
"gstack-verify-gate": { source: "verify-gate", event: "Stop", matcher: "", relpath: "bin/gstack-verify-gate" },
|
||||
"skill-route-hook": { source: "gstack-skill-route", event: "UserPromptSubmit", matcher: "", relpath: "hosts/claude/hooks/skill-route-hook" },
|
||||
"skill-contract-stop-hook": { source: "gstack-skill-contract", event: "Stop", matcher: "", relpath: "hosts/claude/hooks/skill-contract-stop-hook" },
|
||||
"destructive-guard-hook": { source: "gstack-destructive-guard", event: "PreToolUse", matcher: "Bash|PowerShell", relpath: "hosts/claude/hooks/destructive-guard-hook" },
|
||||
"investigate-gate-pre": { source: "gstack-investigate-gate", event: "PreToolUse", matcher: "Edit|Write|MultiEdit|NotebookEdit|Bash", relpath: "hosts/claude/hooks/investigate-gate-pre" },
|
||||
"investigate-gate-post": { source: "gstack-investigate-gate", event: "PostToolUse", matcher: "Bash", relpath: "hosts/claude/hooks/investigate-gate-post" },
|
||||
"investigate-gate-post-failure": { source: "gstack-investigate-gate", event: "PostToolUseFailure", matcher: "Bash", relpath: "hosts/claude/hooks/investigate-gate-post-failure" },
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
*
|
||||
* Usage:
|
||||
* gstack-skill-route --explain "<prompt>" [--json] [--threshold <n>]
|
||||
* gstack-skill-route --default <skill_routing|skill_contracts|ceo_review_gate|autoplan_gate>
|
||||
* gstack-skill-route --default <skill_routing|skill_contracts|destructive_guard|ceo_review_gate|autoplan_gate>
|
||||
*
|
||||
* Prints the switch state, the threshold, every candidate skill with its
|
||||
* score and best trigger, the route the hook would take and the exact line it
|
||||
@@ -16,13 +16,13 @@ import {
|
||||
ROUTE_THRESHOLD, SWITCH_DEFAULT, hintLine, installedSkillsDir, readSkillSwitch, routePrompt, scanInstalledSkills,
|
||||
} from '../lib/skill-route';
|
||||
|
||||
const USAGE = 'Usage: gstack-skill-route --explain "<prompt>" [--json] [--threshold <n>]\n gstack-skill-route --default <skill_routing|skill_contracts|ceo_review_gate|autoplan_gate>';
|
||||
const USAGE = 'Usage: gstack-skill-route --explain "<prompt>" [--json] [--threshold <n>]\n gstack-skill-route --default <skill_routing|skill_contracts|destructive_guard|ceo_review_gate|autoplan_gate>';
|
||||
const args = process.argv.slice(2);
|
||||
if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(`${USAGE}\n`); process.exit(0); }
|
||||
if (args[0] === '--default') {
|
||||
const name = args[1] ?? '';
|
||||
if (!Object.hasOwn(SWITCH_DEFAULT, name)) {
|
||||
process.stderr.write(`SKILL_ROUTE_USAGE: --default needs skill_routing, skill_contracts, ceo_review_gate or autoplan_gate\n${USAGE}\n`);
|
||||
process.stderr.write(`SKILL_ROUTE_USAGE: --default needs skill_routing, skill_contracts, destructive_guard, ceo_review_gate or autoplan_gate\n${USAGE}\n`);
|
||||
process.exit(2);
|
||||
}
|
||||
process.stdout.write(`${SWITCH_DEFAULT[name as keyof typeof SWITCH_DEFAULT]}\n`);
|
||||
|
||||
+11
-3
@@ -89,8 +89,8 @@ Two catastrophic shapes are **denied**, not asked: `rm -r`/`-R` of exactly
|
||||
`/`, `~`, or `$HOME`, and force-push to the repo's **default branch**. SIMPLE
|
||||
commands only (no `;`, `&&`, `||`, `|`, newline) — compound shapes fall
|
||||
through to the MEDIUM ask; `--force-with-lease` is never HIGH. A best-effort
|
||||
advisory hard-stop, not a policy boundary: the escape hatch is ending the
|
||||
opt-in, session-scoped /careful session.
|
||||
advisory hard-stop, not a policy boundary: the escape hatch is running the
|
||||
command yourself, outside the agent.
|
||||
|
||||
## Project patterns (additive only)
|
||||
|
||||
@@ -100,4 +100,12 @@ Add warn rules — one POSIX ERE per line, `#` comments OK — in
|
||||
after the built-in families, so config can only ADD rules, never suppress a
|
||||
baseline warning. Invalid regex lines are skipped.
|
||||
|
||||
To deactivate, end the conversation or start a new one. Hooks are session-scoped.
|
||||
## Always on
|
||||
|
||||
Since gstack's helper hooks went on by default, `./setup` also registers this
|
||||
check as a Claude Code hook for every session (`destructive_guard`), so it runs
|
||||
even when /careful is never loaded. Loading /careful adds nothing to that
|
||||
check; /guard still adds the edit boundary. Turn the every-session check off
|
||||
with `gstack-config set destructive_guard off` (or `./setup
|
||||
--no-destructive-guard`). With it off, /careful's own hooks last until the
|
||||
conversation ends.
|
||||
+11
-3
@@ -93,8 +93,8 @@ Two catastrophic shapes are **denied**, not asked: `rm -r`/`-R` of exactly
|
||||
`/`, `~`, or `$HOME`, and force-push to the repo's **default branch**. SIMPLE
|
||||
commands only (no `;`, `&&`, `||`, `|`, newline) — compound shapes fall
|
||||
through to the MEDIUM ask; `--force-with-lease` is never HIGH. A best-effort
|
||||
advisory hard-stop, not a policy boundary: the escape hatch is ending the
|
||||
opt-in, session-scoped /careful session.
|
||||
advisory hard-stop, not a policy boundary: the escape hatch is running the
|
||||
command yourself, outside the agent.
|
||||
|
||||
## Project patterns (additive only)
|
||||
|
||||
@@ -104,4 +104,12 @@ Add warn rules — one POSIX ERE per line, `#` comments OK — in
|
||||
after the built-in families, so config can only ADD rules, never suppress a
|
||||
baseline warning. Invalid regex lines are skipped.
|
||||
|
||||
To deactivate, end the conversation or start a new one. Hooks are session-scoped.
|
||||
## Always on
|
||||
|
||||
Since gstack's helper hooks went on by default, `./setup` also registers this
|
||||
check as a Claude Code hook for every session (`destructive_guard`), so it runs
|
||||
even when /careful is never loaded. Loading /careful adds nothing to that
|
||||
check; /guard still adds the edit boundary. Turn the every-session check off
|
||||
with `gstack-config set destructive_guard off` (or `./setup
|
||||
--no-destructive-guard`). With it off, /careful's own hooks last until the
|
||||
conversation ends.
|
||||
@@ -132,7 +132,7 @@ if [ "$_IS_SIMPLE" -eq 1 ]; then
|
||||
set +f
|
||||
if [ "$_ROOT_TARGETS" -eq 1 ] && [ "$_SAFE_TARGETS" -eq 0 ]; then
|
||||
_careful_log_fire "high_rm_root"
|
||||
gstack_hook_decision deny "[careful][HIGH] Recursive delete of / or the home directory is blocked while /careful is active. If you truly mean it, end the /careful session first."
|
||||
gstack_hook_decision deny "[careful][HIGH] Recursive delete of / or the home directory is blocked by gstack's destructive-command check. If the user truly means it, they run it themselves."
|
||||
exit 0
|
||||
fi
|
||||
fi
|
||||
@@ -185,7 +185,7 @@ if [ "$_IS_SIMPLE" -eq 1 ]; then
|
||||
fi
|
||||
if [ "$_TARGETS_DEFAULT" -eq 1 ]; then
|
||||
_careful_log_fire "high_force_push_default"
|
||||
gstack_hook_decision deny "[careful][HIGH] Force-push to the default branch ($_DEFAULT_BRANCH) is blocked while /careful is active. Use --force-with-lease on a feature branch, or end the /careful session if you truly mean it."
|
||||
gstack_hook_decision deny "[careful][HIGH] Force-push to the default branch ($_DEFAULT_BRANCH) is blocked by gstack's destructive-command check. Use --force-with-lease on a feature branch; if the user truly means it, they run it themselves."
|
||||
exit 0
|
||||
fi
|
||||
fi
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
bump: minor
|
||||
---
|
||||
- **gstack's helper hooks are now on by default in Claude Code, OpenClaw and Hermes, and the prompt-routing hook fires on real bug reports.** `./setup` now registers the prompt-routing hook (one line naming the gstack skill a prompt fits), the skill-contract hook (holds /review once if it stops before its specialist reviewers ran), and a new destructive-command hook that runs /careful's check before every Bash and PowerShell command, so `rm -rf`, `DROP TABLE`, force-push and the like ask before they run even when nobody loaded /careful (in `claude -p` and other sessions nobody is watching, it prints a warning instead of asking, so nothing waits on an answer). New OpenClaw and Hermes registrations get the start hook (a one-line note on each turn telling the agent to run a skill's start command). Why: on Opus 5.5, unattended, a hook line naming a skill got it loaded in 58 of 60 sessions, where a skill relying on its description loaded in 0 of 60. The routing hook used to skip any prompt over 8,000 characters and miss bug reports that never say "bug"; it now scores a long prompt's first 4,000 and last 1,000 characters, reads words like error, exception, traceback, crash and fails as a bug, and keeps paths such as `site-packages` whole. On 60 real bug reports it now fires on 40 instead of 22, and on none of 60 plain prompts that are not bug reports, reviews, QA or checks.
|
||||
|
||||
**Upgrading:** the first `./setup` or `/gstack-upgrade` after this release turns these hooks on once and prints what it turned on. An off you chose earlier (a `./setup --no-...` flag, `gstack-config set <name> off` or an environment variable) is kept. An OpenClaw or Hermes start hook that is off stays off on upgrade, and the setup output prints one line saying how to turn it on: `gstack-harness register openclaw --start-hook` (or `hermes`).
|
||||
|
||||
**Turning them off:** `gstack-config set skill_routing off`, `gstack-config set skill_contracts off` or `gstack-config set destructive_guard off` (each takes effect on the next prompt or command), or `./setup --no-skill-routing`, `--no-skill-contracts`, `--no-destructive-guard`. For OpenClaw or Hermes: `gstack-harness register openclaw --no-start-hook` (or `hermes`), or `gstack-config set harness_start_hook off` and `./setup`. Details: docs/skill-routing-and-contracts.md and docs/hosts.md#start-hook.
|
||||
+2
-2
@@ -194,8 +194,8 @@ registered as a short entry that tells the agent to read the skill's full
|
||||
reads in pages (`.gstack-skills/` under `--skills all`).
|
||||
Install, verify and remove: [hosts.md](hosts.md#agent-harnesses).
|
||||
Agents in OpenClaw read gstack's skills but rarely run their start command, so
|
||||
there is an opt-in [start hook](hosts.md#start-hook): `gstack-harness register
|
||||
openclaw --start-hook` adds a `gstack-start` plugin that puts a one-line note on
|
||||
there is a [start hook](hosts.md#start-hook), on by default for a new registration (`gstack-harness register
|
||||
openclaw --no-start-hook` turns it off; an upgrade keeps an existing off): it adds a `gstack-start` plugin that puts a one-line note on
|
||||
every user turn, and grants it the conversation access OpenClaw requires for
|
||||
`before_prompt_build` through `openclaw config set`.
|
||||
|
||||
|
||||
+5
-5
@@ -24,7 +24,7 @@ neither does `./setup --local`.
|
||||
|
||||
**What it writes.** Copies in the harness's own skills folder, never edits to
|
||||
`openclaw.json`, Hermes's `config.yaml` or any context file you did not name.
|
||||
The one exception is the [start hook](#start-hook), which you turn on yourself:
|
||||
The one exception is the [start hook](#start-hook), which is on by default for a new registration:
|
||||
it adds a plugin and enables it through the harness's own commands.
|
||||
A context block is opt-in: `gstack-harness register openclaw|hermes|generic
|
||||
--context <file>` writes the marked block into that file only, after printing
|
||||
@@ -70,11 +70,11 @@ characters, the part of a description Hermes's skills index shows.
|
||||
| any other harness | the router in an Agent Skills folder you name, and/or a 600-byte routing block between `<!-- gstack:begin harness-routing -->` markers in a context file you name | `gstack-harness register generic --skills-dir <dir>` and/or `--context <file>`; `gstack-harness manifest generic` prints every skill as JSON | the harness's own skill list | `gstack-harness unregister generic` |
|
||||
|
||||
<a id="start-hook"></a>
|
||||
### Start hook (OpenClaw and Hermes, opt-in)
|
||||
### Start hook (OpenClaw and Hermes, on by default for new registrations)
|
||||
|
||||
Every gstack skill starts with a command in its Preamble (`gstack-skill-start`) that sets up the session: whether it runs unattended, questions, consent, upgrade checks. In OpenClaw and Hermes, agents read gstack's skills but almost never run that command (1 start in 29 chances, HARN-18). The start hook is a small `gstack-start` plugin that puts one note of about 210 characters on every user turn, telling the agent to run that command first, exactly as written, with no pipe.
|
||||
|
||||
It is off unless you turn it on, because turning it on changes the harness's own settings:
|
||||
It is on by default (gstack-evals#369: a line on the prompt naming a skill got Opus 5.5 to load it in 58 of 60 sessions, where a skill relying on its description loaded in 0 of 60). Turning it on changes the harness's own settings:
|
||||
|
||||
| | OpenClaw | Hermes |
|
||||
|---|---|---|
|
||||
@@ -83,13 +83,13 @@ It is off unless you turn it on, because turning it on changes the harness's own
|
||||
| Settings it changes, through the harness's own CLI | `openclaw config set plugins.entries.gstack-start.hooks.allowConversationAccess true` and `...enabled true` in `openclaw.json`. OpenClaw runs `before_prompt_build` from a plugin it did not bundle only with that grant, which also lets the plugin's hooks see conversation content (the plugin reads only its own note.txt) | `hermes plugins enable gstack-start` adds it to `plugins.enabled` in `config.yaml` |
|
||||
| Check | `openclaw plugins inspect gstack-start --runtime --json` lists `before_prompt_build` under `typedHooks` | `hermes plugins list` shows `gstack-start` enabled |
|
||||
|
||||
**Turn it on.** `gstack-harness register openclaw --start-hook` (or `hermes`), or `gstack-config set harness_start_hook on` followed by `./setup`, or `GSTACK_HARNESS_START_HOOK=1 ./setup --host openclaw`. The first of these that is set decides: the `--start-hook`/`--no-start-hook` flag, then `GSTACK_HARNESS_START_HOOK` (`1`/`on` or `0`/`off`), then `harness_start_hook`, then the choice saved in the registration's ledger. Whatever decides, the choice is saved, so refresh and upgrades keep it. The hook goes only into the harness profile's own plugin folder; a registration with a custom `--skills-dir`, or OpenClaw run with `OPENCLAW_CONFIG_PATH` pointing at another config, gets no hook (`HARNESS_HOOK_UNSUPPORTED` with `--start-hook`; with `GSTACK_HARNESS_START_HOOK` or `harness_start_hook`, `register` and `./setup --host` say why and exit 4). `OPENCLAW_CONFIG_PATH` naming the profile's own `openclaw.json`, by any path that resolves to it, is fine. A hook you already turned on stays on when a later run happens to have `OPENCLAW_CONFIG_PATH` set.
|
||||
**On by default, and how to choose.** A new registration with no choice gets the hook. The first of these that is set decides: the `--start-hook`/`--no-start-hook` flag, then `GSTACK_HARNESS_START_HOOK` (`1`/`on` or `0`/`off`), then `harness_start_hook` in gstack-config, then the choice saved in the registration's ledger, then the default. Every off a registration saved is kept, including one saved before the default changed: an upgrade never turns an existing start hook on. The first `./setup` or `/gstack-upgrade` after the change prints, once, `off, as before: gstack now turns it on only for new registrations; turn it on: gstack-harness register <harness> --start-hook`. The only off the default overrides is one gstack recorded because it had to refuse the hook (a custom `--skills-dir` or a foreign `OPENCLAW_CONFIG_PATH`), so the hook comes on once that cause is gone. When the default turns the hook on and the harness cannot activate it yet, the skills are registered and the run does not fail; later refreshes try again. The hook goes only into the harness profile's own plugin folder; a registration with a custom `--skills-dir`, or OpenClaw run with `OPENCLAW_CONFIG_PATH` pointing at another config, gets no hook (`HARNESS_HOOK_UNSUPPORTED` with `--start-hook`; with `GSTACK_HARNESS_START_HOOK` or `harness_start_hook`, `register` and `./setup --host` say why and exit 4). `OPENCLAW_CONFIG_PATH` naming the profile's own `openclaw.json`, by any path that resolves to it, is fine. A hook you already turned on stays on when a later run happens to have `OPENCLAW_CONFIG_PATH` set.
|
||||
|
||||
**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.
|
||||
|
||||
**Turn it off.** `gstack-harness register openclaw --no-start-hook` (or `hermes`), or `gstack-config set harness_start_hook off` followed by `./setup`. 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.
|
||||
**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.
|
||||
|
||||
**What it costs.** The note is about 50 tokens and lands on every user turn, and each copy stays in the session's history, so a long session pays more (mostly cache reads). HARN-18's panel measures the added cost per trial. OpenClaw also logs that it cannot verify where the plugin came from, because gstack writes it instead of installing it from npm or ClawHub.
|
||||
|
||||
|
||||
+6
-4
@@ -39,10 +39,12 @@ explicit "no" removes a live registration. `GSTACK_TIMELINE_STOP_HOOK=no` and
|
||||
--source gstack-timeline-stop` removes it by hand, and `gstack-uninstall`
|
||||
removes it too.
|
||||
|
||||
Two more hooks are off by default and registered only when you turn them on:
|
||||
skill routing (`./setup --skill-routing`, a `UserPromptSubmit` hook that names
|
||||
the gstack skill a prompt fits) and skill contracts (`./setup --skill-contracts`,
|
||||
a `Stop` hook that blocks once when a skill ends without its required outputs);
|
||||
Three more hooks are on by default: skill routing (a `UserPromptSubmit` hook
|
||||
that names the gstack skill a prompt fits), skill contracts (a `Stop` hook that
|
||||
blocks once when a skill ends without its required outputs) and the
|
||||
destructive-command check (a `PreToolUse` hook that runs /careful's check before
|
||||
every Bash and PowerShell command). Turn one off with `./setup --no-skill-routing`,
|
||||
`--no-skill-contracts` or `--no-destructive-guard`, or `gstack-config set <name> off`;
|
||||
see [skill-routing-and-contracts.md](skill-routing-and-contracts.md). The
|
||||
opt-in skill gates (`./setup --ceo-review-gate`, `./setup --autoplan-gate`)
|
||||
register their own hooks the same way; see [skill-gates.md](skill-gates.md).
|
||||
|
||||
@@ -1,17 +1,18 @@
|
||||
# Skill routing and skill contracts
|
||||
|
||||
Two Claude Code hooks that help a model actually run gstack's skills (GST-1088). Each has one default, `SWITCH_DEFAULT` in `lib/skill-route.ts`; `gstack-config defaults` prints it. With both off nothing changes. The opt-in gates that hold one skill rule mid-run (the /plan-ceo-review and /autoplan gates) are in [skill-gates.md](skill-gates.md).
|
||||
Three Claude Code hooks that help a model actually run gstack's skills (GST-1088, GST-3110). All three are on by default. On Opus 5.5, unattended, a hook line naming a skill got it loaded in 58 of 60 bug-fix sessions, where the same skill relying on its description loaded in 0 of 60 (gstack-evals#369, and B1 before it on the same 60 tasks). With the contract hook, all 66 /review sessions ran its specialist reviewers, 42 of them after the hook's one block; in an earlier run without it, 0 of 66 did (gstack-evals board posts GEVA-271 and GEVA-105). Each has one default, `SWITCH_DEFAULT` in `lib/skill-route.ts`; `gstack-config defaults` prints it. With all three off nothing changes. The opt-in gates that hold one skill rule mid-run (the /plan-ceo-review and /autoplan gates) are in [skill-gates.md](skill-gates.md).
|
||||
|
||||
- **Skill routing** (`skill_routing`, a UserPromptSubmit hook). When a prompt matches an installed skill's `triggers:`, the hook adds one line of context naming that skill, for example "this request fits /verify. Run /verify with the Skill tool before you start".
|
||||
- **Skill contracts** (`skill_contracts`, a Stop hook). A skill can declare the outputs that must exist before it is done. When the model tries to stop without them, the hook blocks once and names what is missing.
|
||||
- **Destructive-command check** (`destructive_guard`, a PreToolUse hook on Bash and PowerShell). /careful's check, run in every session without the model loading /careful: see [below](#destructive-command-check).
|
||||
|
||||
## Turn them on or off
|
||||
|
||||
Each switch resolves in this order, and the first one set wins:
|
||||
|
||||
1. The `./setup` flag: `--skill-routing` / `--no-skill-routing` and `--skill-contracts` / `--no-skill-contracts` (also `--skill-routing=on|off`). A flag is saved to config, so it survives upgrades.
|
||||
2. The environment: `GSTACK_SKILL_ROUTING` and `GSTACK_SKILL_CONTRACTS` (`on` or `off`). Not saved.
|
||||
3. Config: `gstack-config set skill_routing on|off` and `gstack-config set skill_contracts on|off`.
|
||||
1. The `./setup` flag: `--skill-routing` / `--no-skill-routing`, `--skill-contracts` / `--no-skill-contracts` and `--destructive-guard` / `--no-destructive-guard` (also `--skill-routing=on|off`). A flag is saved to config, so it survives upgrades.
|
||||
2. The environment: `GSTACK_SKILL_ROUTING`, `GSTACK_SKILL_CONTRACTS` and `GSTACK_DESTRUCTIVE_GUARD` (`on` or `off`). Not saved.
|
||||
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 <switch>` 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.
|
||||
@@ -20,6 +21,9 @@ Setup registers a hook only when its switch is on, prints one line the first tim
|
||||
|
||||
gstack-config set skill_contracts off
|
||||
gstack-config set skill_routing off
|
||||
gstack-config set destructive_guard off
|
||||
|
||||
**Upgrading from an install where they were off.** The default used to be off, and nothing was saved unless you chose. So the first `./setup` (or `/gstack-upgrade`) after this change registers each hook you never turned off, prints one line per hook with its off switch, and once prints a short notice listing what it turned on. An off you set earlier, by flag, `gstack-config` or the environment, is read before the default and kept.
|
||||
|
||||
The off switch is for people. The text the Stop hook shows the model never mentions it.
|
||||
|
||||
@@ -37,7 +41,10 @@ The hook scores the prompt against the `triggers:` list in each installed `SKILL
|
||||
- A trigger scores 1 when its whole phrase appears in the prompt. Otherwise it scores the share of its content words (common words dropped, light stemming, so "failing" matches "fails") that the prompt contains. A trigger with one content word counts only on its whole phrase, unless that word has five or more letters and is not a question word.
|
||||
- Only /review, /qa and /verify route (/investigate did too until it was cut, GST-1717). In the d7 check (PR #3912), scoring every installed skill's triggers sent 17 of 32 non-fit Terminal-Bench prompts to some skill at 0.66; routing only the four routed skills of that time sent 4. The other skills wait for their own trigger review.
|
||||
- The skill with the best score routes when it reaches the threshold, 0.66: both words of a two-word trigger, or two of three.
|
||||
- Prompts that start with `/` (you already picked a skill) and prompts over 8,000 characters (pasted logs) are never routed.
|
||||
- Words a bug report uses for the defect (error, exception, traceback, crash, fails, failure, broken, regression, incorrect, wrong, defect, and exception names such as `ValueError`) score as "bug", so "parse_one raises ValueError, please fix" matches a "fix this bug" trigger. Paths and identifiers stay whole (`site-packages`, `src/review.ts`, `max_retries`), so a traceback's paths never match a trigger's words.
|
||||
- When a trigger ties with another of the same skill on score and words, a whole-phrase match wins.
|
||||
- A prompt longer than 5,000 characters is scored on its first 4,000 and last 1,000 characters, where the request usually sits; a log pasted between them is not scored, so its words cannot match everything. Until GST-3110 such prompts (over 8,000 characters) were never routed.
|
||||
- Prompts that start with `/` (you already picked a skill) are never routed.
|
||||
- The injected line names its source and its off switch, and asks the model to tell you in one sentence that gstack routed the request.
|
||||
|
||||
### Dry run
|
||||
@@ -45,7 +52,7 @@ The hook scores the prompt against the `triggers:` list in each installed `SKILL
|
||||
`gstack-skill-route --explain` shows what the hook would do, with the switch on or off. It never injects anything.
|
||||
|
||||
$ gstack-skill-route --explain "run the checks and verify my change"
|
||||
switch: skill_routing off (default)
|
||||
switch: skill_routing on (default)
|
||||
threshold: 0.66
|
||||
skills: 63 scanned in /home/you/.claude/skills
|
||||
candidates:
|
||||
@@ -60,6 +67,13 @@ Add `--json` for a machine-readable answer, or `--threshold <n>` to see another
|
||||
|
||||
Every decision is one line in `$GSTACK_STATE_ROOT/hooks/skill-route.log`: the session, the event (`routed`, `no-route` with its reason, or an error) and, for errors, `failures=<n>` for that session. The log never holds prompt text. On any error the hook prints nothing and exits 0; it never blocks a prompt.
|
||||
|
||||
<a id="destructive-command-check"></a>
|
||||
## Destructive-command check
|
||||
|
||||
`./setup` registers `hosts/claude/hooks/destructive-guard-hook` as a PreToolUse hook on `Bash|PowerShell`. It runs `careful/bin/check-careful.sh`, the same check /careful and /guard load, so it fires even when the model never loads /careful. Its decisions are the check's own: `ask` before the destructive families (`rm -rf`, `DROP TABLE`, `TRUNCATE`, force-push, `git reset --hard`, `kubectl delete` and the rest in /careful's table), which you can always approve, and `deny` for the two catastrophic simple shapes (a recursive delete of `/` or your home directory, and a force-push to the default branch). An ask's reason, which you read, adds `(gstack's destructive-command check, on in every session; off: gstack-config set destructive_guard off)`; a deny's reason, which the model reads, never names the off switch. In a session nobody is watching (`claude -p`, which Claude Code marks `CLAUDE_CODE_ENTRYPOINT=sdk-cli`, or a session `gstack-session-kind` reports as headless), an ask would wait for an answer that never comes, so the hook prints the same reason as a warning and lets the command run, which is what happens when the check is off; a deny stays a deny. It costs about a tenth of a second per Bash call.
|
||||
|
||||
The hook reads `destructive_guard` every time it runs, so `gstack-config set destructive_guard off` takes effect on the next command. With it off, /careful and /guard still load their own session hooks.
|
||||
|
||||
## Contracts
|
||||
|
||||
### Schema (version 1)
|
||||
|
||||
+2
-2
@@ -1484,7 +1484,7 @@ gstack can invoke a skill for you when your request matches one. By default (`pr
|
||||
|
||||
## Safety & Guardrails
|
||||
|
||||
Four skills that add safety rails to any Claude Code session. They work via Claude Code's PreToolUse hooks — transparent, session-scoped, no configuration required.
|
||||
Four skills that add safety rails to any Claude Code session. They work via Claude Code's PreToolUse hooks — transparent, no configuration required. /careful's destructive-command check also runs in every session by default (`destructive_guard`; off: `gstack-config set destructive_guard off`); the others are session-scoped.
|
||||
|
||||
### `/careful`
|
||||
|
||||
@@ -1502,7 +1502,7 @@ On Windows the same hook checks Claude Code's PowerShell tool and any `pwsh`/`po
|
||||
|
||||
Common build artifact cleanups (`rm -rf node_modules`, `dist`, `.next`, `__pycache__`, `build`, `coverage`) are whitelisted — no false alarms on routine operations.
|
||||
|
||||
You can override any MEDIUM warning. Two catastrophic shapes are hard-denied instead of asked: recursive deletes of the filesystem root or your home directory (including the `/*`, `~/`, and `$HOME/` forms), and force-pushes to the repo's default branch (`--force-with-lease` never triggers the deny; the escape hatch is ending the session-scoped `/careful` session). You can also add your own warn rules — one POSIX ERE per line — in `~/.gstack/careful-patterns.txt` (global) or `~/.gstack/projects/<slug>/careful-patterns.txt` (per-project); custom patterns only ever add warnings, never suppress the built-ins. The guardrails are accident prevention, not access control.
|
||||
You can override any MEDIUM warning. Two catastrophic shapes are hard-denied instead of asked: recursive deletes of the filesystem root or your home directory (including the `/*`, `~/`, and `$HOME/` forms), and force-pushes to the repo's default branch (`--force-with-lease` never triggers the deny; to run one anyway, turn the every-session check off with `gstack-config set destructive_guard off` and don't load `/careful` or `/guard`). You can also add your own warn rules — one POSIX ERE per line — in `~/.gstack/careful-patterns.txt` (global) or `~/.gstack/projects/<slug>/careful-patterns.txt` (per-project); custom patterns only ever add warnings, never suppress the built-ins. The guardrails are accident prevention, not access control.
|
||||
|
||||
### `/freeze`
|
||||
|
||||
|
||||
+4
-4
@@ -8,7 +8,7 @@ If gstack is installed on your machine:
|
||||
~/.claude/skills/gstack/bin/gstack-uninstall
|
||||
```
|
||||
|
||||
This handles skills, symlinks, harness registrations (the files `gstack-harness` wrote into OpenClaw, Hermes, a Dot or another harness, from their ledgers, plus the opt-in [start hook](hosts.md#start-hook), which it turns off through the harness's own CLI), global state (`~/.gstack/`), project-local state, browse daemons, and temp files. Use `--keep-state` to preserve config and analytics; it also keeps the repo's `.gstack/` and `.gstack-worktrees/`. Use `--force` to skip confirmation.
|
||||
This handles skills, symlinks, harness registrations (the files `gstack-harness` wrote into OpenClaw, Hermes, a Dot or another harness, from their ledgers, plus the [start hook](hosts.md#start-hook), which it turns off through the harness's own CLI), global state (`~/.gstack/`), project-local state, browse daemons, and temp files. Use `--keep-state` to preserve config and analytics; it also keeps the repo's `.gstack/` and `.gstack-worktrees/`. Use `--force` to skip confirmation.
|
||||
|
||||
A plain uninstall keeps the git-tracked files under `.gstack/` (such as ship policy) and removes only the ones git ignores. It stops with exit 2, before removing anything, when a checkout under `.gstack-worktrees/` has uncommitted changes, has commits no branch or tag holds, or is not a worktree this repo registered. Pass `--force-worktrees` to delete those checkouts anyway. Every checkout is checked, including a worktree created inside another checkout under `.gstack-worktrees/`. A git submodule inside a clean checkout is deleted with it only when every commit it holds is on a remote-tracking branch; otherwise it stops the uninstall. A locked worktree (`git worktree lock`) always stops the uninstall, even with `--force-worktrees`; unlock it with `git worktree unlock <path>` if you want it gone. If `git worktree list` fails, the uninstall stops too, even with `--force-worktrees`, and so it does on git older than 2.36, which cannot list worktrees with `-z`. The check runs again after you confirm, before anything is removed, so a checkout you edit while the confirmation prompt waits is kept: uninstall exits 2 and removes nothing. Run from inside the gstack install itself, a `.gstack/` that holds its own git repository also stops the uninstall, because deleting the install would take it along. A `.gstack/` that is its own git repository is kept, with a message saying so, because its commits may exist nowhere else. When `.gstack-worktrees` is a symlink, uninstall removes only the link and never follows it, so the folder it points at and the worktrees there are kept.
|
||||
|
||||
@@ -126,12 +126,12 @@ Manual removal leaves gstack's hook entries behind in `~/.claude/settings.json`
|
||||
`_gstack_source` tag was stripped). Edit that file and delete every hook whose
|
||||
command path points into `.claude/skills/gstack/`: the SessionStart auto-update
|
||||
hook, the AskUserQuestion PreToolUse/PostToolUse hooks, the Stop hooks
|
||||
(session timeline, plus verify-gate and skill contracts if you opted in), and
|
||||
the skill-routing UserPromptSubmit hook if you turned it on, and the
|
||||
(session timeline, skill contracts, which is on by default, and verify-gate if you opted in), and
|
||||
the skill-routing UserPromptSubmit hook and the destructive-command PreToolUse hook (both on by default), and the
|
||||
/plan-ceo-review and /autoplan skill-gate hooks if you turned those on. Left in place, they error
|
||||
on every matching event once the install directory is gone.
|
||||
|
||||
If you turned on the OpenClaw or Hermes [start hook](hosts.md#start-hook),
|
||||
If the OpenClaw or Hermes [start hook](hosts.md#start-hook) is on (the default for a new registration),
|
||||
manual removal also leaves its `gstack-start` plugin turned on. Turn it off
|
||||
with `openclaw config unset plugins.entries.gstack-start` or `hermes plugins
|
||||
disable gstack-start`, then delete
|
||||
|
||||
Executable
+10
@@ -0,0 +1,10 @@
|
||||
#!/usr/bin/env bash
|
||||
# Bash shim — Claude Code hooks run `command` strings via /bin/sh, so this
|
||||
# wrapper makes the TypeScript hook executable via bun. Settings.json
|
||||
# references this file directly (registered by ./setup unless destructive_guard is off).
|
||||
#
|
||||
# FAIL-OPEN: every failure path — bun missing, script crash — still exits 0.
|
||||
GSTACK_BUN_CONFIG=/dev/null; case "${OSTYPE:-}" in msys*|cygwin*) if command -v cygpath >/dev/null 2>&1; then GSTACK_BUN_CONFIG=NUL; fi ;; esac
|
||||
HERE="$(cd "$(dirname "$0")" && pwd)" || exit 0
|
||||
bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" "$HERE/destructive-guard-hook.ts" || true
|
||||
exit 0
|
||||
Executable
+53
@@ -0,0 +1,53 @@
|
||||
#!/usr/bin/env -S bun --no-env-file --config=/dev/null
|
||||
/**
|
||||
* destructive-guard-hook — PreToolUse hook (Bash, PowerShell) that runs /careful's destructive-command check in every
|
||||
* Claude Code session, so the check fires without the model loading /careful. On unless destructive_guard is off (env
|
||||
* GSTACK_DESTRUCTIVE_GUARD, then config destructive_guard, then SWITCH_DEFAULT).
|
||||
*
|
||||
* switch on? -> careful/bin/check-careful.sh with the hook payload on stdin -> its decision, unchanged
|
||||
*
|
||||
* CONTRACT
|
||||
* - The decision is check-careful.sh's: "ask" for the destructive families, "deny" for the two catastrophic shapes,
|
||||
* nothing for the rest. An "ask" reason, which the person reads, also names this hook and its off switch; a
|
||||
* "deny" reason, which the model reads, does not.
|
||||
* - With nobody to answer an ask (claude -p, which Claude Code marks CLAUDE_CODE_ENTRYPOINT=sdk-cli, or a session
|
||||
* gstack-session-kind calls headless, unattended or spawned), an "ask" becomes a warning (systemMessage) and no
|
||||
* decision, so the command runs as it would with no guard loaded. A "deny" stays a deny.
|
||||
* - Always exits 0. With the switch off it prints nothing.
|
||||
* Docs: docs/skill-routing-and-contracts.md#destructive-command-check.
|
||||
*/
|
||||
import * as path from 'path';
|
||||
import { resolveWindowsBashCached, runScriptSync } from '../../../lib/script-invocation';
|
||||
import { readSkillSwitch } from '../../../lib/skill-route';
|
||||
import { resolveStateRoot } from '../../../lib/state-root';
|
||||
import { sessionKind } from './spawn-bin';
|
||||
|
||||
export const ASK_NOTE = "(gstack's destructive-command check, on in every session; off: gstack-config set destructive_guard off)";
|
||||
const CHECK = path.join(import.meta.dir, '..', '..', '..', 'careful', 'bin', 'check-careful.sh');
|
||||
|
||||
function main(): void {
|
||||
if (!readSkillSwitch('destructive_guard').on) return;
|
||||
const r = runScriptSync(CHECK, [], { stdio: ['inherit', 'pipe', 'inherit'], encoding: 'utf8', timeout: 8000 }, {
|
||||
resolve: () => resolveWindowsBashCached(path.join(resolveStateRoot(), 'cache', 'windows-bash.json')),
|
||||
});
|
||||
const out = (r.stdout ?? '').trim();
|
||||
if (!out) return;
|
||||
let decision: { hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string } };
|
||||
try { decision = JSON.parse(out); } catch { process.stdout.write(out + '\n'); return; }
|
||||
const o = decision.hookSpecificOutput;
|
||||
if (o?.permissionDecision === 'ask') {
|
||||
const reason = `${o.permissionDecisionReason ?? ''} ${ASK_NOTE}`.trim();
|
||||
const kind = process.env.CLAUDE_CODE_ENTRYPOINT === 'sdk-cli' ? 'headless' : sessionKind(2000);
|
||||
if (kind && kind !== 'interactive') {
|
||||
process.stdout.write(JSON.stringify({ systemMessage: `${reason} Allowed without asking: this ${kind} session has nobody to answer.` }) + '\n');
|
||||
return;
|
||||
}
|
||||
o.permissionDecisionReason = reason;
|
||||
}
|
||||
process.stdout.write(JSON.stringify(decision) + '\n');
|
||||
}
|
||||
|
||||
if (import.meta.main) {
|
||||
main();
|
||||
process.exit(0);
|
||||
}
|
||||
@@ -1,11 +1,11 @@
|
||||
#!/usr/bin/env -S bun --no-env-file --config=/dev/null
|
||||
/**
|
||||
* skill-route-hook — UserPromptSubmit hook that names the gstack skill a prompt
|
||||
* fits (GST-1088, lane A). Off unless skill_routing is on (env
|
||||
* fits (GST-1088, lane A). On unless skill_routing is off (env
|
||||
* GSTACK_SKILL_ROUTING, then config skill_routing, then SWITCH_DEFAULT).
|
||||
*
|
||||
* stdin (<= 256 KiB, 500 ms) -> switch on? -> JSON object with a prompt?
|
||||
* -> not a /command, not over 8000 chars -> score against installed triggers
|
||||
* -> not a /command -> score its head and tail windows against installed triggers
|
||||
* -> at or above ROUTE_THRESHOLD: one additionalContext line -> exit 0
|
||||
*
|
||||
* CONTRACT
|
||||
|
||||
+15
-9
@@ -528,7 +528,7 @@ function shellRegistry(opts: RegisterOptions, fn: string, args: string[]): boole
|
||||
return sourcedBash(opts.checkout, 'gstack-install-registry.sh', fn, args, opts.stateRoot, opts.env).status === 0;
|
||||
}
|
||||
|
||||
interface HookPlan { on: boolean; prevOn: boolean; explicit: boolean; retry: boolean; profile: string; root: string; files: Map<string, Buffer>; note?: string; fix?: string; requested?: boolean }
|
||||
interface HookPlan { on: boolean; prevOn: boolean; explicit: boolean; byDefault: boolean; by?: string; retry: boolean; profile: string; root: string; files: Map<string, Buffer>; note?: string; fix?: string; requested?: boolean }
|
||||
|
||||
/** The start hook for this run: whether it is on, where it goes, and its files (null for targets without a hook). */
|
||||
function hookPlan(opts: RegisterOptions, dest: string, prev: Ledger | null): HookPlan | null {
|
||||
@@ -537,29 +537,32 @@ function hookPlan(opts: RegisterOptions, dest: string, prev: Ledger | null): Hoo
|
||||
if (opts.startHook) throw new HarnessError('HARNESS_HOOK_UNSUPPORTED', t.displayName + ' has no start hook');
|
||||
return null;
|
||||
}
|
||||
const choice = hookChoice(opts.startHook, opts.env, opts.stateRoot, prev?.meta.start_hook);
|
||||
const choice = hookChoice(opts.startHook, opts.env, opts.stateRoot, prev ? prev.meta.start_hook ?? 'off' : undefined, prev?.meta.start_hook_by);
|
||||
if ('invalid' in choice) throw new HarnessError('HARNESS_HOOK_CHOICE_INVALID', choice.invalid + ' is not on or off');
|
||||
const prevOn = prev?.meta.start_hook === 'on' && !!prev.meta.hook_root && !!prev.meta.hook_profile;
|
||||
const profile = prevOn ? prev!.meta.hook_profile : hookProfile(t.name, opts.env, opts.home);
|
||||
const root = hookRoot(t.name, profile);
|
||||
const plan = { on: choice.on, prevOn, explicit: choice.source === 'flag', retry: prevOn && prev!.meta.hook_active === 'no', profile, root, files: new Map<string, Buffer>() };
|
||||
const keptOld = choice.source === 'ledger' && !choice.on && !prev?.meta.start_hook_by;
|
||||
const by = choice.on || choice.source === 'default' ? undefined : choice.source === 'ledger' ? prev?.meta.start_hook_by ?? 'before-default' : choice.source;
|
||||
const note = keptOld ? 'off, as before: gstack now turns it on only for new registrations; turn it on: gstack-harness register ' + t.name + ' --start-hook' : undefined;
|
||||
const plan = { on: choice.on, prevOn, explicit: choice.source === 'flag', byDefault: choice.source === 'default', by, note, retry: prevOn && prev!.meta.hook_active === 'no', profile, root, files: new Map<string, Buffer>() };
|
||||
const saved = prev?.meta.hook_root && prev.meta.hook_profile ? { profile: prev.meta.hook_profile, root: prev.meta.hook_root } : null;
|
||||
const name = t.name;
|
||||
const off = (p: HookPlan) => { if (saved) assertHookRoot(name, saved.profile, saved.root, saved.root, (code, msg) => { throw new HarnessError(code, msg); }); return p; };
|
||||
if (!choice.on) return off(plan);
|
||||
const requested = !opts.inherit;
|
||||
const requested = !opts.inherit && choice.source !== 'default';
|
||||
const foreign = t.name === 'openclaw' ? foreignOpenclawConfig(opts.env, profile) : '';
|
||||
const [why, fix] = dest !== profileSkills(t.name, profile) ? ['this registration uses another skills folder (' + dest + ')', 'register without --skills-dir to get the hook, or pass --no-start-hook to keep this registration without it']
|
||||
: foreign ? ['OPENCLAW_CONFIG_PATH points OpenClaw at ' + foreign + ', outside that profile', 'unset OPENCLAW_CONFIG_PATH or set it to ' + hookConfig('openclaw', profile) + ', then register again'] : ['', ''];
|
||||
if (why && (plan.explicit || !prevOn)) {
|
||||
if (plan.explicit) throw new HarnessError('HARNESS_HOOK_UNSUPPORTED', 'the start hook goes into the ' + t.displayName + ' profile ' + profile + ', and ' + why);
|
||||
return off({ ...plan, on: false, requested, fix, note: 'off: ' + why + ' (' + choice.source + ' asked for the hook)' });
|
||||
return off({ ...plan, on: false, by: 'refused', requested, fix, note: 'off: ' + why + ' (' + choice.source + ' asked for the hook)' });
|
||||
}
|
||||
try {
|
||||
assertHookRoot(t.name, profile, root, prevOn ? prev!.meta.hook_root : undefined, (code, msg) => { throw new HarnessError(code, msg); });
|
||||
} catch (e) {
|
||||
if (plan.explicit || prevOn || !(e instanceof HarnessError)) throw e;
|
||||
return off({ ...plan, on: false, requested, fix: HARNESS_CODES[e.code].fix, note: 'off: ' + e.message + ' (' + choice.source + ' asked for the hook)' });
|
||||
return off({ ...plan, on: false, by: 'refused', requested, fix: HARNESS_CODES[e.code].fix, note: 'off: ' + e.message + ' (' + choice.source + ' asked for the hook)' });
|
||||
}
|
||||
return { ...plan, files: hookFiles(t.name, root) };
|
||||
}
|
||||
@@ -577,7 +580,10 @@ function finishHook(opts: RegisterOptions, hook: HookPlan | null, released: stri
|
||||
}
|
||||
const failed = activateHook(t, hook.profile, opts.env, opts.home);
|
||||
const r = inspectHook(t, hook.profile, opts.env, opts.home);
|
||||
return { ...r, ...(failed && r.state !== 'active' && !r.detail?.startsWith(failed) ? { detail: failed + (r.detail ? '; ' + r.detail : '') } : {}), profile: hook.profile, root: hook.root, required, retried: !required };
|
||||
const fatal = required && !hook.byDefault;
|
||||
const detail = [hook.byDefault && !hook.prevOn ? 'on by default; turn it off: gstack-harness register ' + t + ' --no-start-hook, or gstack-config set harness_start_hook off' : '',
|
||||
failed && r.state !== 'active' && !r.detail?.startsWith(failed) ? failed : '', r.detail ?? ''].filter(Boolean).join('; ');
|
||||
return { ...r, ...(detail ? { detail } : {}), profile: hook.profile, root: hook.root, required: fatal, retried: !fatal };
|
||||
}
|
||||
|
||||
export function register(opts: RegisterOptions): RegisterResult {
|
||||
@@ -641,7 +647,7 @@ export function register(opts: RegisterOptions): RegisterResult {
|
||||
&& (prev.meta.context ?? '') === context && prev.blocks.length === blocks.length
|
||||
&& blocks.every(b => prev.blocks.some(p => p.path === b.path && p.sha === b.sha && p.pad === b.pad))
|
||||
&& want.every(w => prevFiles.get(w.path) === w.sha && onDiskSha(w.path) === w.sha)
|
||||
&& (!hook || (prev.meta.start_hook ?? 'off') === (hook.on ? 'on' : 'off'));
|
||||
&& (!hook || ((prev.meta.start_hook ?? 'off') === (hook.on ? 'on' : 'off') && (prev.meta.start_hook_by ?? '') === (hook.by ?? '')));
|
||||
const stamp = new Date().toISOString().replace(/[:.]/g, '-');
|
||||
const kept: string[] = [];
|
||||
let written = 0;
|
||||
@@ -651,7 +657,7 @@ export function register(opts: RegisterOptions): RegisterResult {
|
||||
for (const p of files.keys()) for (let d = path.dirname(p); !fs.existsSync(d) && path.dirname(d) !== d; d = path.dirname(d)) dirs.add(d);
|
||||
const record = (recorded: typeof want, final: boolean) => writeLedger(lfile, {
|
||||
meta: { id, target: t.name, dest, mode, checkout: opts.checkout, version: opts.version, names: visible.join(','), ...(router ? { router } : {}), ...(context ? { context } : {}),
|
||||
...(hook ? { start_hook: hook.on ? 'on' : 'off' } : {}), ...(hook?.on ? { hook_profile: hook.profile, hook_root: hook.root, ...(!hook.prevOn || hook.explicit ? { hook_active: 'no' } : prev?.meta.hook_active ? { hook_active: prev.meta.hook_active } : {}) } : !final && prev?.meta.hook_root ? { hook_profile: prev.meta.hook_profile, hook_root: prev.meta.hook_root } : {}) },
|
||||
...(hook ? { start_hook: hook.on ? 'on' : 'off', ...(hook.by ? { start_hook_by: hook.by } : {}) } : {}), ...(hook?.on ? { hook_profile: hook.profile, hook_root: hook.root, ...(!hook.prevOn || hook.explicit ? { hook_active: 'no' } : prev?.meta.hook_active ? { hook_active: prev.meta.hook_active } : {}) } : !final && prev?.meta.hook_root ? { hook_profile: prev.meta.hook_profile, hook_root: prev.meta.hook_root } : {}) },
|
||||
files: recorded, dirs: [...dirs].sort((a, b) => b.length - a.length), blocks,
|
||||
});
|
||||
record([...want, ...(prev?.files ?? []).filter(f => !files.has(f.path))], false);
|
||||
|
||||
@@ -3,7 +3,10 @@
|
||||
* (before_prompt_build) and Hermes (pre_llm_call), telling the agent to run a gstack skill's start command as
|
||||
* written. Skill listings were followed on 1 of 29 chances (HARN-18); a per-turn note 97-100% (HARN-15).
|
||||
*
|
||||
* Off unless the user asks: `--start-hook`, GSTACK_HARNESS_START_HOOK or `gstack-config set harness_start_hook on`.
|
||||
* On by default for a new registration (START_HOOK_DEFAULT); off with `--no-start-hook`, GSTACK_HARNESS_START_HOOK=0 or
|
||||
* `gstack-config set harness_start_hook off`. A registration keeps every off it recorded, including one from before the
|
||||
* default changed, because the plugin grants OpenClaw conversation access and an old off can't be told from the old
|
||||
* default. The one exception is an on gstack had to refuse (ledger start_hook_by=refused), which the default retries.
|
||||
* Turning it on writes a fixed plugin into the harness profile (never under a custom --skills-dir) and changes the
|
||||
* harness's settings only through its own commands: OpenClaw needs plugins.entries.gstack-start.hooks.
|
||||
* allowConversationAccess before a non-bundled plugin's before_prompt_build runs (2026.10.6 hook-policy-decisions:6);
|
||||
@@ -144,8 +147,13 @@ export function hookFiles(t: HookTarget, root: string): Map<string, Buffer> {
|
||||
return out;
|
||||
}
|
||||
|
||||
/** The user's choice and where it came from: --start-hook/--no-start-hook, then the env var, then gstack-config, then the ledger. */
|
||||
export function hookChoice(flag: boolean | undefined, env: Env, stateRoot: string, recorded: string | undefined): { on: boolean; source: 'flag' | 'env' | 'config' | 'ledger' } | { invalid: string } {
|
||||
export const START_HOOK_DEFAULT: 'on' | 'off' = 'on';
|
||||
|
||||
/**
|
||||
* The user's choice and where it came from: --start-hook/--no-start-hook, then the env var, then gstack-config, then
|
||||
* the ledger's on or off (unless the off is an on gstack refused, recordedBy 'refused'), then START_HOOK_DEFAULT.
|
||||
*/
|
||||
export function hookChoice(flag: boolean | undefined, env: Env, stateRoot: string, recorded: string | undefined, recordedBy?: string): { on: boolean; source: 'flag' | 'env' | 'config' | 'ledger' | 'default' } | { invalid: string } {
|
||||
if (flag !== undefined) return { on: flag, source: 'flag' };
|
||||
const parse = (v: string | null | undefined) => v == null || v === '' ? null : /^(1|on|true|yes)$/i.test(v) ? true : /^(0|off|false|no)$/i.test(v) ? false : undefined;
|
||||
const fromEnv = parse(env.GSTACK_HARNESS_START_HOOK);
|
||||
@@ -155,7 +163,8 @@ export function hookChoice(flag: boolean | undefined, env: Env, stateRoot: strin
|
||||
const fromConfig = parse(stored);
|
||||
if (fromConfig === undefined) return { invalid: 'gstack-config harness_start_hook=' + JSON.stringify(stored) };
|
||||
if (fromConfig !== null) return { on: fromConfig, source: 'config' };
|
||||
return { on: recorded === 'on', source: 'ledger' };
|
||||
if (recorded === 'on' || (recorded === 'off' && recordedBy !== 'refused')) return { on: recorded === 'on', source: 'ledger' };
|
||||
return { on: START_HOOK_DEFAULT === 'on', source: 'default' };
|
||||
}
|
||||
|
||||
/** Runs the harness's own CLI for one profile: argv only, stdin closed, a timeout, and no environment beyond PATH, HOME and the profile. */
|
||||
|
||||
+45
-19
@@ -6,8 +6,8 @@
|
||||
* in the installed skills' SKILL.md frontmatter. No model call, no network:
|
||||
* the same prompt and the same installed skills always give the same route.
|
||||
*
|
||||
* Also home to what both skill hooks share: the on/off switches
|
||||
* (skill_routing, skill_contracts), the installed-skills directory, the
|
||||
* Also home to what the skill hooks share: the on/off switches
|
||||
* (skill_routing, skill_contracts, destructive_guard and the gates), the installed-skills directory, the
|
||||
* bounded stdin reader and the trace log under $GSTACK_STATE_ROOT/hooks/.
|
||||
* Docs: docs/skill-routing-and-contracts.md.
|
||||
*/
|
||||
@@ -20,26 +20,33 @@ import { readConfigKey, resolveStateRoot } from './state-root';
|
||||
|
||||
/** A route needs at least this share of a trigger's content words (2 of 3, 3 of 4; both of 2). */
|
||||
export const ROUTE_THRESHOLD = 0.66;
|
||||
/** Longer prompts (pasted logs, files) are never routed: their words match everything. */
|
||||
export const PROMPT_MAX_CHARS = 8000;
|
||||
/**
|
||||
* A prompt longer than the two windows is scored on its first PROMPT_HEAD_CHARS and last PROMPT_TAIL_CHARS
|
||||
* characters, where the request usually sits; a log or file pasted between them is not scored, so its words
|
||||
* cannot match everything.
|
||||
*/
|
||||
export const PROMPT_HEAD_CHARS = 4000;
|
||||
export const PROMPT_TAIL_CHARS = 1000;
|
||||
const FRONTMATTER_MAX_BYTES = 16 * 1024;
|
||||
const MAX_SKILLS = 256;
|
||||
const MAX_TRIGGER_CHARS = 200;
|
||||
const TRACE_MAX_BYTES = 1024 * 1024;
|
||||
const FAILURE_SESSIONS_KEPT = 64;
|
||||
|
||||
export type SwitchName = 'skill_routing' | 'skill_contracts' | 'ceo_review_gate' | 'autoplan_gate';
|
||||
export type SwitchName = 'skill_routing' | 'skill_contracts' | 'destructive_guard' | 'ceo_review_gate' | 'autoplan_gate';
|
||||
export const SWITCH_ENV: Record<SwitchName, string> = {
|
||||
skill_routing: 'GSTACK_SKILL_ROUTING',
|
||||
skill_contracts: 'GSTACK_SKILL_CONTRACTS',
|
||||
destructive_guard: 'GSTACK_DESTRUCTIVE_GUARD',
|
||||
ceo_review_gate: 'GSTACK_CEO_REVIEW_GATE',
|
||||
autoplan_gate: 'GSTACK_AUTOPLAN_GATE',
|
||||
};
|
||||
|
||||
/** Each switch's one default. setup, gstack-config and gstack-skill-route read it through `gstack-skill-route --default <switch>`; the hooks read it here. */
|
||||
export const SWITCH_DEFAULT: Record<SwitchName, 'on' | 'off'> = {
|
||||
skill_routing: 'off',
|
||||
skill_contracts: 'off',
|
||||
skill_routing: 'on',
|
||||
skill_contracts: 'on',
|
||||
destructive_guard: 'on',
|
||||
ceo_review_gate: 'off',
|
||||
autoplan_gate: 'off',
|
||||
};
|
||||
@@ -158,14 +165,29 @@ export function stem(word: string): string {
|
||||
return w;
|
||||
}
|
||||
|
||||
const words = (text: string) => text.toLowerCase().match(/[a-z0-9]+(?:'[a-z]+)?/g) ?? [];
|
||||
/** Words, with paths and identifiers (site-packages, src/review.ts, max_retries) kept whole so their parts never match a trigger. */
|
||||
const words = (text: string) => text.toLowerCase().match(/[a-z0-9]+(?:[-_./\\][a-z0-9]+)*(?:'[a-z]+)?/g) ?? [];
|
||||
|
||||
/**
|
||||
* Words a bug report uses for the defect itself, scored as "bug": a report says "raises TypeError" or "fails"
|
||||
* far more often than "bug". Exception names (ValueError, RuntimeException) count too.
|
||||
*/
|
||||
const DEFECT_WORDS = new Set(['bug', 'error', 'exception', 'traceback', 'crash', 'fail', 'failure', 'broken', 'regression',
|
||||
'incorrect', 'incorrectly', 'wrong', 'defect']);
|
||||
const concept = (stemmed: string) => DEFECT_WORDS.has(stemmed) || /^[a-z]{3,}(?:error|exception)$/.test(stemmed) ? 'bug' : stemmed;
|
||||
|
||||
export function tokens(text: string): string[] {
|
||||
return words(text).map(stem);
|
||||
return words(text).map(w => concept(stem(w)));
|
||||
}
|
||||
|
||||
export function contentTokens(text: string): string[] {
|
||||
return [...new Set(words(text).filter(w => !STOPWORDS.has(w)).map(stem))];
|
||||
return [...new Set(words(text).filter(w => !STOPWORDS.has(w)).map(w => concept(stem(w))))];
|
||||
}
|
||||
|
||||
/** The text a prompt is scored on: all of it, or its head and tail windows when it is longer than both. */
|
||||
export function promptWindow(prompt: string): string {
|
||||
if (prompt.length <= PROMPT_HEAD_CHARS + PROMPT_TAIL_CHARS) return prompt;
|
||||
return `${prompt.slice(0, PROMPT_HEAD_CHARS)}\n${prompt.slice(-PROMPT_TAIL_CHARS)}`;
|
||||
}
|
||||
|
||||
export interface RouteCandidate { skill: string; score: number; matched: number; trigger: string; file: string }
|
||||
@@ -174,17 +196,20 @@ export interface RouteCandidate { skill: string; score: number; matched: number;
|
||||
const SPECIFIC_WORD = /^(?!(?:what|which|where|whose)$)[a-z0-9]{5,}$/;
|
||||
|
||||
/**
|
||||
* Every skill whose best trigger shares a content word with the prompt, best first (score, matched words,
|
||||
* name). A trigger's score is 1 when its whole phrase appears in the prompt, else the share of its content
|
||||
* words (stopwords dropped, lightly stemmed) that the prompt contains. A trigger with one content word scores
|
||||
* only on its whole phrase unless that word is specific (SPECIFIC_WORD).
|
||||
* Every skill whose best trigger shares a content word with the prompt's window (promptWindow), best first
|
||||
* (score, matched words, name). A trigger's score is 1 when its whole phrase appears in the prompt, else the
|
||||
* share of its content words (stopwords dropped, lightly stemmed, defect words read as "bug") that the prompt
|
||||
* contains. A trigger with one content word scores only on its whole phrase unless that word is specific
|
||||
* (SPECIFIC_WORD).
|
||||
*/
|
||||
export function scorePrompt(prompt: string, skills: InstalledSkill[]): RouteCandidate[] {
|
||||
const promptSeq = ` ${tokens(prompt).join(' ')} `;
|
||||
const promptSet = new Set(contentTokens(prompt));
|
||||
const scored = promptWindow(prompt);
|
||||
const promptSeq = ` ${tokens(scored).join(' ')} `;
|
||||
const promptSet = new Set(contentTokens(scored));
|
||||
const out: RouteCandidate[] = [];
|
||||
for (const skill of skills) {
|
||||
let best: RouteCandidate | null = null;
|
||||
let bestPhrase = false;
|
||||
for (const trigger of skill.triggers) {
|
||||
const content = contentTokens(trigger);
|
||||
if (!content.length) continue;
|
||||
@@ -192,8 +217,10 @@ export function scorePrompt(prompt: string, skills: InstalledSkill[]): RouteCand
|
||||
const phrase = promptSeq.includes(` ${tokens(trigger).join(' ')} `);
|
||||
const weakSingle = content.length === 1 && !SPECIFIC_WORD.test(content[0]);
|
||||
const score = phrase ? 1 : weakSingle ? 0 : Math.round((matched / content.length) * 100) / 100;
|
||||
if (score > 0 && (!best || score > best.score || (score === best.score && matched > best.matched))) {
|
||||
const tie = !!best && score === best.score && (matched > best.matched || (matched === best.matched && phrase && !bestPhrase));
|
||||
if (score > 0 && (!best || score > best.score || tie)) {
|
||||
best = { skill: skill.name, score, matched, trigger, file: skill.file };
|
||||
bestPhrase = phrase;
|
||||
}
|
||||
}
|
||||
if (best) out.push(best);
|
||||
@@ -210,13 +237,12 @@ const isRouted = (name: string) => ROUTED_SKILLS.includes(name.toLowerCase().rep
|
||||
|
||||
export type RouteDecision =
|
||||
| { route: RouteCandidate; candidates: RouteCandidate[] }
|
||||
| { route: null; reason: 'slash-command' | 'prompt-too-long' | 'empty' | 'below-threshold'; candidates: RouteCandidate[] };
|
||||
| { route: null; reason: 'slash-command' | 'empty' | 'below-threshold'; candidates: RouteCandidate[] };
|
||||
|
||||
export function routePrompt(prompt: string, skills: InstalledSkill[], threshold = ROUTE_THRESHOLD): RouteDecision {
|
||||
const trimmed = prompt.trim();
|
||||
if (!trimmed) return { route: null, reason: 'empty', candidates: [] };
|
||||
if (trimmed.startsWith('/')) return { route: null, reason: 'slash-command', candidates: [] };
|
||||
if (prompt.length > PROMPT_MAX_CHARS) return { route: null, reason: 'prompt-too-long', candidates: [] };
|
||||
const candidates = scorePrompt(prompt, skills.filter(s => isRouted(s.name)));
|
||||
const top = candidates[0];
|
||||
return top && top.score >= threshold ? { route: top, candidates } : { route: null, reason: 'below-threshold', candidates };
|
||||
|
||||
@@ -60,6 +60,12 @@ Claude Code hooks (docs/skill-routing-and-contracts.md):
|
||||
--skill-contracts / --no-skill-contracts
|
||||
Block once when a contract skill ends without its
|
||||
required outputs (Stop). Saved as skill_contracts.
|
||||
--destructive-guard / --no-destructive-guard
|
||||
Run /careful's destructive-command check before every
|
||||
Bash and PowerShell call (PreToolUse). Saved as
|
||||
destructive_guard.
|
||||
These three are on by default; the flag, env var or
|
||||
gstack-config set <name> off turns one off.
|
||||
--ceo-review-gate / --no-ceo-review-gate
|
||||
After /plan-ceo-review loads, block its final stop (and a
|
||||
review subagent's) until the output file ranks the top
|
||||
@@ -201,6 +207,7 @@ PLAN_TUNE_HOOKS_MODE="" # "" = resolve from env/config/prompt; "yes"/"no" = ex
|
||||
TIMELINE_STOP_HOOK_MODE="" # "" = resolve from env/config; "yes"/"no" = explicit (#2677)
|
||||
SKILL_ROUTING_MODE="" # "" = resolve from env/config; "on"/"off" = explicit (GST-1088)
|
||||
SKILL_CONTRACTS_MODE="" # "" = resolve from env/config; "on"/"off" = explicit (GST-1088)
|
||||
DESTRUCTIVE_GUARD_MODE="" # "" = resolve from env/config; "on"/"off" = explicit (GST-3110)
|
||||
CEO_REVIEW_GATE_MODE="" # "" = resolve from env/config; "on"/"off" = explicit (GST-1461)
|
||||
AUTOPLAN_GATE_MODE="" # "" = resolve from env/config; "on"/"off" = explicit (GST-1666)
|
||||
MODEL_OVERRIDE=""
|
||||
@@ -216,7 +223,7 @@ _setup_unknown_option() {
|
||||
local bad="$1" next="${2:-}" best="" best_d=99 flag d value=""
|
||||
for flag in --host --model --claude-model --loadout --global --local --prefix --no-prefix --team --no-team \
|
||||
--plan-tune-hooks --no-plan-tune-hooks --timeline-stop-hook --no-timeline-stop-hook \
|
||||
--skill-routing --no-skill-routing --skill-contracts --no-skill-contracts \
|
||||
--skill-routing --no-skill-routing --skill-contracts --no-skill-contracts --destructive-guard --no-destructive-guard \
|
||||
--ceo-review-gate --no-ceo-review-gate --autoplan-gate --no-autoplan-gate \
|
||||
--refresh-registered --status --no-browser --no-harness-auto --quiet --help; do
|
||||
d="$(awk -v a="${bad%%=*}" -v b="$flag" 'BEGIN {
|
||||
@@ -266,6 +273,9 @@ while [ $# -gt 0 ]; do
|
||||
--skill-contracts) SKILL_CONTRACTS_MODE="on"; shift ;;
|
||||
--no-skill-contracts) SKILL_CONTRACTS_MODE="off"; shift ;;
|
||||
--skill-contracts=*) SKILL_CONTRACTS_MODE="${1#--skill-contracts=}"; shift ;;
|
||||
--destructive-guard) DESTRUCTIVE_GUARD_MODE="on"; shift ;;
|
||||
--no-destructive-guard) DESTRUCTIVE_GUARD_MODE="off"; shift ;;
|
||||
--destructive-guard=*) DESTRUCTIVE_GUARD_MODE="${1#--destructive-guard=}"; shift ;;
|
||||
--ceo-review-gate) CEO_REVIEW_GATE_MODE="on"; shift ;;
|
||||
--no-ceo-review-gate) CEO_REVIEW_GATE_MODE="off"; shift ;;
|
||||
--ceo-review-gate=*) CEO_REVIEW_GATE_MODE="${1#--ceo-review-gate=}"; shift ;;
|
||||
@@ -5006,13 +5016,15 @@ _skill_hook_gate() {
|
||||
case "$out" in
|
||||
*unchanged*) : ;;
|
||||
*re-pointed*) log " re-pointed $event hook to $cmd (previous registration held a stale path)" ;;
|
||||
*) log " registered $event hook: $what (on via $src; turn off: gstack-config set $key off, or ./setup --no-${key//_/-}; backup: settings.json.bak.<ts>)" ;;
|
||||
*) log " registered $event hook: $what (on via $src; turn off: gstack-config set $key off, or ./setup --no-${key//_/-}; backup: settings.json.bak.<ts>)"
|
||||
if [ "$src" = "default" ]; then _HOOKS_ON_BY_DEFAULT="$_HOOKS_ON_BY_DEFAULT $key"; fi ;;
|
||||
esac
|
||||
else
|
||||
log " warning: settings hook update failed: $(printf '%s\n' "$out" | head -1) — run $SETTINGS_HOOK manually"
|
||||
fi
|
||||
done
|
||||
}
|
||||
_HOOKS_ON_BY_DEFAULT=""
|
||||
SKILL_ROUTE_BIN="$SOURCE_GSTACK_DIR/bin/gstack-skill-route"
|
||||
SKILL_ROUTE_HOOK="$(_hook_command_path hosts/claude/hooks/skill-route-hook || true)"
|
||||
SKILL_CONTRACT_HOOK="$(_hook_command_path hosts/claude/hooks/skill-contract-stop-hook || true)"
|
||||
@@ -5022,6 +5034,26 @@ _skill_hook_gate skill_routing "$SKILL_ROUTING_MODE" GSTACK_SKILL_ROUTING UserPr
|
||||
_skill_hook_gate skill_contracts "$SKILL_CONTRACTS_MODE" GSTACK_SKILL_CONTRACTS Stop \
|
||||
"$SKILL_CONTRACT_HOOK" gstack-skill-contract 10 \
|
||||
"a contract skill that ends without its required outputs is blocked once"
|
||||
# /careful's destructive-command check in every session (GST-3110): the same
|
||||
# check-careful.sh, its ask and deny unchanged, without the model loading /careful.
|
||||
DESTRUCTIVE_GUARD_HOOK="$(_hook_command_path hosts/claude/hooks/destructive-guard-hook || true)"
|
||||
_skill_hook_gate destructive_guard "$DESTRUCTIVE_GUARD_MODE" GSTACK_DESTRUCTIVE_GUARD PreToolUse \
|
||||
"$DESTRUCTIVE_GUARD_HOOK" gstack-destructive-guard 10 \
|
||||
"destructive commands (rm -rf, DROP TABLE, force-push) ask before they run" 'Bash|PowerShell'
|
||||
# One notice, the first time a default turns these hooks on (an install that
|
||||
# predates the default, or a new one). An off you set earlier is kept: the
|
||||
# gate reads it before the default.
|
||||
_HOOKS_NOTICE_MARKER="$GSTACK_STATE_ROOT/.hooks-on-by-default-notice"
|
||||
if [ -n "$_HOOKS_ON_BY_DEFAULT" ] && [ "$QUIET" -eq 0 ] && [ ! -e "$_HOOKS_NOTICE_MARKER" ]; then
|
||||
log ""
|
||||
log "gstack's helper hooks are now on by default. This run turned on:$_HOOKS_ON_BY_DEFAULT"
|
||||
log " skill_routing: a one-line hint naming the gstack skill a prompt fits"
|
||||
log " skill_contracts: a skill with required steps (/review's specialist reviewers) is held once if it stops without them"
|
||||
log " destructive_guard: rm -rf, DROP TABLE, force-push and the like ask before they run"
|
||||
log " Turn one off: gstack-config set <name> off (takes effect on the next prompt), or ./setup --no-skill-routing,"
|
||||
log " --no-skill-contracts, --no-destructive-guard. Docs: docs/skill-routing-and-contracts.md"
|
||||
mkdir -p "$GSTACK_STATE_ROOT" 2>/dev/null && : > "$_HOOKS_NOTICE_MARKER" 2>/dev/null || true
|
||||
fi
|
||||
# Both skill gates register HOOK_TIMEOUT_S from lib/skill-gates.ts, the longest
|
||||
# gate deadline plus a margin (GST-1615): Claude Code kills a hook at its
|
||||
# timeout and lets the stop through unchecked. Empty if bun cannot run, which
|
||||
|
||||
@@ -0,0 +1,80 @@
|
||||
/**
|
||||
* hosts/claude/hooks/destructive-guard-hook (GST-3110): /careful's destructive-command check as an every-session
|
||||
* PreToolUse hook. Its decisions are check-careful.sh's own; an ask names the hook and its off switch, a deny does
|
||||
* not; the destructive_guard switch (env, then config, then SWITCH_DEFAULT) turns it off.
|
||||
*/
|
||||
import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import * as fs from 'node:fs';
|
||||
import * as os from 'node:os';
|
||||
import * as path from 'node:path';
|
||||
import { SWITCH_DEFAULT } from '../lib/skill-route';
|
||||
import { ASK_NOTE } from '../hosts/claude/hooks/destructive-guard-hook.ts';
|
||||
|
||||
const ROOT = path.resolve(import.meta.dir, '..');
|
||||
const SHIM = path.join(ROOT, 'hosts', 'claude', 'hooks', 'destructive-guard-hook');
|
||||
const CHECK = path.join(ROOT, 'careful', 'bin', 'check-careful.sh');
|
||||
|
||||
let state = '';
|
||||
beforeEach(() => { state = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-dguard-')); });
|
||||
afterEach(() => fs.rmSync(state, { recursive: true, force: true }));
|
||||
|
||||
const payload = (command: string, tool = 'Bash') => JSON.stringify({ session_id: 's', hook_event_name: 'PreToolUse', tool_name: tool, tool_input: { command } });
|
||||
const run = (file: string, input: string, env: Record<string, string> = {}) => {
|
||||
const r = spawnSync('bash', [file], { input, env: { PATH: process.env.PATH ?? '', HOME: state, GSTACK_STATE_ROOT: state, ...env }, encoding: 'utf8', timeout: 30_000 });
|
||||
return { code: r.status, stdout: (r.stdout ?? '').trim(), stderr: r.stderr ?? '' };
|
||||
};
|
||||
const decision = (stdout: string) => JSON.parse(stdout).hookSpecificOutput ?? {};
|
||||
|
||||
describe('destructive-guard hook', () => {
|
||||
test('on by default: an ask keeps check-careful.sh\'s reason and adds the hook and its off switch', () => {
|
||||
expect(SWITCH_DEFAULT.destructive_guard).toBe('on');
|
||||
const hooked = run(SHIM, payload('rm -rf /var/data'));
|
||||
const direct = run(CHECK, payload('rm -rf /var/data'));
|
||||
expect(hooked.code).toBe(0);
|
||||
expect(decision(hooked.stdout).permissionDecision).toBe('ask');
|
||||
expect(decision(hooked.stdout).permissionDecisionReason).toBe(`${decision(direct.stdout).permissionDecisionReason} ${ASK_NOTE}`);
|
||||
expect(ASK_NOTE).toContain('gstack-config set destructive_guard off');
|
||||
});
|
||||
|
||||
test('a deny is check-careful.sh\'s deny, unchanged, and never names the off switch to the model', () => {
|
||||
const hooked = run(SHIM, payload('rm -rf /'));
|
||||
expect(hooked.stdout).toBe(run(CHECK, payload('rm -rf /')).stdout);
|
||||
expect(decision(hooked.stdout).permissionDecision).toBe('deny');
|
||||
expect(hooked.stdout).not.toContain('destructive_guard');
|
||||
});
|
||||
|
||||
test('safe commands and the PowerShell tool pass through as check-careful.sh decides', () => {
|
||||
expect(run(SHIM, payload('git status')).stdout).toBe(run(CHECK, payload('git status')).stdout);
|
||||
expect(decision(run(SHIM, payload('Remove-Item -Recurse -Force C:\\proj', 'PowerShell')).stdout).permissionDecision).toBe('ask');
|
||||
});
|
||||
|
||||
test('an interactive session (the claude CLI) gets the ask', () => {
|
||||
const r = run(SHIM, payload('rm -rf /var/data'), { CLAUDE_CODE_ENTRYPOINT: 'cli' });
|
||||
expect(decision(r.stdout).permissionDecision).toBe('ask');
|
||||
});
|
||||
|
||||
test('an interactive Agent SDK host (Conductor, CLAUDE_CODE_ENTRYPOINT=sdk-ts) still gets the ask', () => {
|
||||
const r = run(SHIM, payload('rm -rf /var/data'), { CLAUDE_CODE_ENTRYPOINT: 'sdk-ts', CONDUCTOR_WORKSPACE_PATH: '/tmp/conductor-ws' });
|
||||
expect(decision(r.stdout).permissionDecision).toBe('ask');
|
||||
});
|
||||
|
||||
test('claude -p and headless sessions get a warning and no decision, so nothing waits on an answer; a deny stays a deny', () => {
|
||||
const reason = decision(run(CHECK, payload('rm -rf /var/data')).stdout).permissionDecisionReason;
|
||||
for (const env of [{ CLAUDE_CODE_ENTRYPOINT: 'sdk-cli' }, { GSTACK_HEADLESS: '1' }] as Record<string, string>[]) {
|
||||
const r = run(SHIM, payload('rm -rf /var/data'), env);
|
||||
expect(r.code).toBe(0);
|
||||
const out = JSON.parse(r.stdout);
|
||||
expect(out.hookSpecificOutput).toBeUndefined();
|
||||
expect(out.systemMessage).toBe(`${reason} ${ASK_NOTE} Allowed without asking: this headless session has nobody to answer.`);
|
||||
expect(decision(run(SHIM, payload('rm -rf /'), env).stdout).permissionDecision).toBe('deny');
|
||||
}
|
||||
});
|
||||
|
||||
test('off in env or config prints nothing; env on wins over config off', () => {
|
||||
expect(run(SHIM, payload('rm -rf /var/data'), { GSTACK_DESTRUCTIVE_GUARD: 'off' })).toEqual({ code: 0, stdout: '', stderr: '' });
|
||||
fs.writeFileSync(path.join(state, 'config.yaml'), 'destructive_guard: off\n');
|
||||
expect(run(SHIM, payload('rm -rf /var/data'))).toEqual({ code: 0, stdout: '', stderr: '' });
|
||||
expect(decision(run(SHIM, payload('rm -rf /var/data'), { GSTACK_DESTRUCTIVE_GUARD: 'on' }).stdout).permissionDecision).toBe('ask');
|
||||
});
|
||||
});
|
||||
+63
@@ -0,0 +1,63 @@
|
||||
# Plain prompts that fit none of the routed skills (/review, /qa, /verify) and are not bug reports.
|
||||
# test/skill-route.test.ts routes every line and expects no route; the last six use defect words
|
||||
# (error, exception, failed) in requests that are features, not bugs.
|
||||
Add a dark mode toggle to the settings page and remember the choice in localStorage.
|
||||
Write a CLI flag --json that prints the report as JSON instead of a table.
|
||||
Add pagination to the /users API endpoint, 50 rows per page.
|
||||
Create a new React component that shows a user's avatar with their initials as a fallback.
|
||||
Add support for reading the config from a TOML file as well as YAML.
|
||||
Implement a retry with exponential backoff for the S3 upload client.
|
||||
Add a "copy to clipboard" button next to each code block in the docs site.
|
||||
Build a small script that exports last month's orders to CSV.
|
||||
Add an optional timeout parameter to fetch_page, defaulting to 30 seconds.
|
||||
Let users sign in with GitHub OAuth in addition to email and password.
|
||||
Add a progress bar to the import command for large files.
|
||||
Support Python 3.13 in the package metadata and CI matrix.
|
||||
Add a webhook that posts to Slack when a deploy finishes.
|
||||
Implement a simple LRU cache for the geocoding lookups.
|
||||
Add keyboard shortcuts j and k to move between items in the inbox list.
|
||||
Explain how the scheduler decides which job runs next.
|
||||
What's the difference between a process and a thread in this runtime?
|
||||
How does the auth middleware decide whether a request is an admin request?
|
||||
Walk me through what happens when a user uploads a file, from the browser to the database.
|
||||
Why do we use a message queue between the API and the workers?
|
||||
What does the --strict flag in our tsconfig actually change?
|
||||
Summarize what changed in the last ten commits on main.
|
||||
Which modules import the payments client directly?
|
||||
How would I add a new language to the translation files?
|
||||
Is there a way to run only the integration tests locally?
|
||||
Write a README section that explains how to install the project on macOS.
|
||||
Rewrite the onboarding email so it sounds friendlier and shorter.
|
||||
Add docstrings to every public function in utils/dates.py.
|
||||
Draft release notes for version 2.4 from the merged pull requests.
|
||||
Write an architecture overview of the billing service for new engineers.
|
||||
Update the CONTRIBUTING guide to mention the new branch naming rule.
|
||||
Translate the error messages in the CLI help text into Spanish.
|
||||
Write a short blog post announcing the new search feature.
|
||||
Refactor the OrderService class into smaller functions without changing behavior.
|
||||
Rename the variable usr to user everywhere in the accounts module.
|
||||
Move the date helpers into their own module and update the imports.
|
||||
Convert the callbacks in the legacy upload code to async/await.
|
||||
Replace the hand-written argument parsing with argparse.
|
||||
Split the 2,000-line views.py into one file per resource.
|
||||
Extract the duplicated SQL into a shared query builder.
|
||||
Replace moment.js with date-fns across the frontend.
|
||||
Bump the Node version to 22 in the Dockerfile and the CI config.
|
||||
Set up a GitHub Actions workflow that builds the Docker image on every tag.
|
||||
Add a Makefile target that seeds the local database with sample data.
|
||||
Configure the logger to write JSON lines in production and pretty text in development.
|
||||
Pin all the Python dependencies and add a lock file.
|
||||
Add a health-check endpoint for the load balancer.
|
||||
Set up pre-commit with black and isort.
|
||||
Increase the database connection pool to 20 and make it configurable.
|
||||
Plot weekly active users for the last six months from the events table.
|
||||
Write a SQL query that finds customers who ordered more than three times in March.
|
||||
Compute the median response time per endpoint from these access logs.
|
||||
Build a notebook that compares the two pricing experiments.
|
||||
Load the survey CSV and give me counts by country.
|
||||
Add error handling to the upload endpoint so a bad file returns a clear message.
|
||||
Improve the error messages the CLI prints when a required flag is missing.
|
||||
Add a custom exception class for configuration problems and use it in the loader.
|
||||
Record failed login attempts in the audit table.
|
||||
Show a friendly page when the payment provider returns an error code.
|
||||
Add a section to the docs explaining what each exit code means.
|
||||
@@ -8,8 +8,8 @@ import { spawnSync } from 'node:child_process';
|
||||
import * as fs from 'node:fs';
|
||||
import * as os from 'node:os';
|
||||
import * as path from 'node:path';
|
||||
import { TARGETS, readLedger, register, status, unregister, type RegisterOptions } from '../lib/harness-register';
|
||||
import { HOOK_ID, START_NOTE, START_NOTE_MAX, hookChoice, hookFiles, inspectHook } from '../lib/harness-start-hook';
|
||||
import { TARGETS, readLedger, register, status, unregister, writeLedger, type RegisterOptions } from '../lib/harness-register';
|
||||
import { HOOK_ID, START_HOOK_DEFAULT, START_NOTE, START_NOTE_MAX, hookChoice, hookFiles, inspectHook } from '../lib/harness-start-hook';
|
||||
import { cleanupFixtures, cleanupSeed, makeFixture, makeSource, registryRows, runSetup } from './helpers/install-fixture';
|
||||
|
||||
const ROOT = path.resolve(import.meta.dir, '..');
|
||||
@@ -133,11 +133,16 @@ describe('start hook: the note and the plugin files', () => {
|
||||
});
|
||||
|
||||
describe('start hook: who decides', () => {
|
||||
test('flag, then GSTACK_HARNESS_START_HOOK, then gstack-config harness_start_hook, then the ledger', () => {
|
||||
test('flag, then GSTACK_HARNESS_START_HOOK, then gstack-config harness_start_hook, then the ledger, then the default (on)', () => {
|
||||
const d = tmp();
|
||||
const state = path.join(d, 'state');
|
||||
fs.mkdirSync(state);
|
||||
expect(hookChoice(undefined, {}, state, undefined)).toEqual({ on: false, source: 'ledger' });
|
||||
expect(START_HOOK_DEFAULT).toBe('on');
|
||||
expect(hookChoice(undefined, {}, state, undefined)).toEqual({ on: true, source: 'default' });
|
||||
expect(hookChoice(undefined, {}, state, 'off')).toEqual({ on: false, source: 'ledger' });
|
||||
expect(hookChoice(undefined, {}, state, 'off', 'refused')).toEqual({ on: true, source: 'default' });
|
||||
expect(hookChoice(undefined, {}, state, 'off', 'flag')).toEqual({ on: false, source: 'ledger' });
|
||||
expect(hookChoice(undefined, {}, state, 'off', 'env')).toEqual({ on: false, source: 'ledger' });
|
||||
expect(hookChoice(undefined, {}, state, 'on')).toEqual({ on: true, source: 'ledger' });
|
||||
fs.writeFileSync(path.join(state, 'config.yaml'), 'harness_start_hook: off\n');
|
||||
expect(hookChoice(undefined, {}, state, 'on')).toEqual({ on: false, source: 'config' });
|
||||
@@ -212,13 +217,60 @@ describe('start hook: who decides', () => {
|
||||
});
|
||||
|
||||
describe('start hook: OpenClaw lifecycle (fake CLI)', () => {
|
||||
test('default registration adds no plugin and runs no harness command', () => {
|
||||
test('default registration turns the hook on, says so with the off switch, and a failed activation is not an error', () => {
|
||||
const r = rig('openclaw');
|
||||
const res = register(r.o());
|
||||
expect(res.hook).toEqual({ state: 'off' });
|
||||
expect(fs.existsSync(path.join(r.profile, 'extensions'))).toBe(false);
|
||||
expect(res.hook).toMatchObject({ state: 'active', required: false, retried: true, profile: r.profile, root: r.root });
|
||||
expect(res.hook?.detail).toContain('on by default; turn it off: gstack-harness register openclaw --no-start-hook, or gstack-config set harness_start_hook off');
|
||||
expect(fs.readdirSync(r.root).sort()).toEqual(['index.js', 'note.txt', 'openclaw.plugin.json', 'package.json']);
|
||||
expect(readLedger(res.ledger)!.meta).toMatchObject({ start_hook: 'on', hook_active: 'yes' });
|
||||
expect(readLedger(res.ledger)!.meta.start_hook_by).toBeUndefined();
|
||||
expect(register(r.o()).hook?.state).toBe('unchecked');
|
||||
|
||||
const blocked = rig('openclaw', { noCli: true, fresh: true });
|
||||
const quiet = register(blocked.o());
|
||||
expect(quiet.hook).toMatchObject({ required: false });
|
||||
expect(quiet.hook?.state).not.toBe('active');
|
||||
}, 120_000);
|
||||
|
||||
test('an off given by flag or env is kept by later runs; an off recorded before the default changed, or a record from before the start hook existed, stays off and says once how to turn it on', () => {
|
||||
const r = rig('openclaw');
|
||||
const off = register(r.o({ startHook: false }));
|
||||
expect(off.hook?.state).toBe('off');
|
||||
expect(readLedger(off.ledger)!.meta).toMatchObject({ start_hook: 'off', start_hook_by: 'flag' });
|
||||
const refreshed = register(r.o({ inherit: true }));
|
||||
expect(refreshed.hook?.state).toBe('off');
|
||||
expect(r.calls()).toEqual([]);
|
||||
expect(fs.existsSync(r.root)).toBe(false);
|
||||
|
||||
const viaEnv = rig('openclaw');
|
||||
const envOff = register({ ...viaEnv.o(), env: { ...viaEnv.env, GSTACK_HARNESS_START_HOOK: '0' } });
|
||||
expect(readLedger(envOff.ledger)!.meta).toMatchObject({ start_hook: 'off', start_hook_by: 'env' });
|
||||
expect(register(viaEnv.o({ inherit: true })).hook?.state).toBe('off');
|
||||
expect(viaEnv.calls()).toEqual([]);
|
||||
|
||||
const old = readLedger(off.ledger)!;
|
||||
delete old.meta.start_hook_by;
|
||||
writeLedger(off.ledger, old);
|
||||
const upgraded = register(r.o({ inherit: true }));
|
||||
expect(upgraded.status).toBe('updated');
|
||||
expect(upgraded.hook).toEqual({ state: 'off', detail: 'off, as before: gstack now turns it on only for new registrations; turn it on: gstack-harness register openclaw --start-hook' });
|
||||
expect(readLedger(upgraded.ledger)!.meta).toMatchObject({ start_hook: 'off', start_hook_by: 'before-default' });
|
||||
expect(fs.existsSync(r.root)).toBe(false);
|
||||
const again = register(r.o({ inherit: true }));
|
||||
expect(again.status).toBe('unchanged');
|
||||
expect(again.hook).toEqual({ state: 'off' });
|
||||
expect(r.calls()).toEqual([]);
|
||||
|
||||
const older = readLedger(off.ledger)!;
|
||||
delete older.meta.start_hook;
|
||||
delete older.meta.start_hook_by;
|
||||
writeLedger(off.ledger, older);
|
||||
const fromBeforeHooks = register(r.o({ inherit: true }));
|
||||
expect(fromBeforeHooks.hook).toEqual({ state: 'off', detail: 'off, as before: gstack now turns it on only for new registrations; turn it on: gstack-harness register openclaw --start-hook' });
|
||||
expect(readLedger(fromBeforeHooks.ledger)!.meta).toMatchObject({ start_hook: 'off', start_hook_by: 'before-default' });
|
||||
expect(fs.existsSync(r.root)).toBe(false);
|
||||
expect(r.calls()).toEqual([]);
|
||||
expect(readLedger(res.ledger)!.files.every(f => f.path.startsWith(path.join(r.profile, 'skills') + path.sep))).toBe(true);
|
||||
}, 120_000);
|
||||
|
||||
test('on, refreshed, disabled by the user, then off: activation runs once, a user disable sticks, opt-out cleans up', () => {
|
||||
@@ -532,6 +584,8 @@ describe('start hook: HARN-18 smoke defects (GST-778)', () => {
|
||||
expect(custom.hook).toMatchObject({ state: 'off', required: true });
|
||||
expect(custom.hook?.fix).toContain('--no-start-hook');
|
||||
expect(register({ ...r.o({ skillsDir: path.join(r.d, 'custom', 'skills'), startHook: false }), env: { ...r.env, GSTACK_HARNESS_START_HOOK: '1' } }).hook).toEqual({ state: 'off' });
|
||||
expect(readLedger(res.ledger)!.meta.start_hook_by).toBe('refused');
|
||||
expect(register(r.o({ inherit: true })).hook?.state).toBe('active');
|
||||
}, 120_000);
|
||||
|
||||
test('a fresh harness with no config: turning the hook on creates no config, runs no harness command, and fails with the setup to run first', () => {
|
||||
|
||||
@@ -252,6 +252,7 @@ export const FREE_FIXTURES: Readonly<Record<string, readonly string[]>> = {
|
||||
'test/fixtures/skill-contract/**': ['test/skill-contract-stop-hook.test.ts', 'test/skill-contract.test.ts'],
|
||||
'test/fixtures/skill-evals/**': ['test/skill-eval-checks.test.ts', 'test/skill-eval-tasks.test.ts'],
|
||||
'test/fixtures/skill-md-size-allowlist.json': ['test/skill-md-size-guard.test.ts'],
|
||||
'test/fixtures/skill-route-plain-prompts.txt': ['test/skill-route.test.ts'],
|
||||
'test/fixtures/spawn-sync-raw-importers.json': ['test/spawn-sync.test.ts'],
|
||||
'test/fixtures/state-matrix-6792/**': ['test/state-matrix.test.ts'],
|
||||
'test/fixtures/pregate-timing/**': ['test/pregate-timing.test.ts'],
|
||||
|
||||
@@ -340,6 +340,7 @@ describe('setup: registers the hooks that parse, refuses the rest, exits non-zer
|
||||
GSTACK_PLAN_TUNE_HOOKS: 'yes',
|
||||
GSTACK_SKILL_ROUTING: 'off',
|
||||
GSTACK_SKILL_CONTRACTS: 'off',
|
||||
GSTACK_DESTRUCTIVE_GUARD: 'off',
|
||||
TMPDIR: fx.base,
|
||||
};
|
||||
// A file, not `bash -c`: the script is longer than Windows' 32,767-character command line.
|
||||
|
||||
@@ -34,6 +34,7 @@ const settings = () => (fs.existsSync(settingsFile()) ? JSON.parse(fs.readFileSy
|
||||
const GATES = {
|
||||
skill_routing: 'GSTACK_SKILL_ROUTING UserPromptSubmit "$2/hosts/claude/hooks/skill-route-hook" gstack-skill-route 5 "routing hint"',
|
||||
skill_contracts: 'GSTACK_SKILL_CONTRACTS Stop "$2/hosts/claude/hooks/skill-contract-stop-hook" gstack-skill-contract 10 "contract check"',
|
||||
destructive_guard: 'GSTACK_DESTRUCTIVE_GUARD PreToolUse "$2/hosts/claude/hooks/destructive-guard-hook" gstack-destructive-guard 10 "destructive check" \'Bash|PowerShell\'',
|
||||
ceo_review_gate: 'GSTACK_CEO_REVIEW_GATE Stop "$2/hosts/claude/hooks/ceo-review-gate-stop" gstack-ceo-review-gate "$SKILL_GATE_HOOK_TIMEOUT" "ceo review gate" ""'
|
||||
+ ' SubagentStop "$2/hosts/claude/hooks/ceo-review-gate-subagent-stop" ""',
|
||||
autoplan_gate: 'GSTACK_AUTOPLAN_GATE Stop "$2/hosts/claude/hooks/autoplan-stop-gate-stop" gstack-autoplan-gate "$SKILL_GATE_HOOK_TIMEOUT" "autoplan gate" ""'
|
||||
@@ -65,17 +66,22 @@ const registered = (event = 'UserPromptSubmit') => (settings().hooks?.[event] ??
|
||||
|
||||
describe('setup: skill hook gates', () => {
|
||||
test('flags parse for both switches, and both appear in --help', () => {
|
||||
for (const f of ['--skill-routing)', '--no-skill-routing)', '--skill-routing=*)', '--skill-contracts)', '--no-skill-contracts)', '--skill-contracts=*)']) {
|
||||
for (const f of ['--skill-routing)', '--no-skill-routing)', '--skill-routing=*)', '--skill-contracts)', '--no-skill-contracts)', '--skill-contracts=*)',
|
||||
'--destructive-guard)', '--no-destructive-guard)', '--destructive-guard=*)']) {
|
||||
expect(setupSrc).toContain(` ${f}`);
|
||||
}
|
||||
expect(setupSrc).toContain('--skill-routing --no-skill-routing --skill-contracts --no-skill-contracts');
|
||||
expect(setupSrc).toContain('--skill-routing / --no-skill-routing');
|
||||
expect(setupSrc).toContain('--skill-contracts / --no-skill-contracts');
|
||||
expect(setupSrc).toContain('--destructive-guard / --no-destructive-guard');
|
||||
expect(setupSrc).toContain('--destructive-guard --no-destructive-guard');
|
||||
});
|
||||
|
||||
test('both hooks resolve through _hook_command_path literals (the parse gate and hook-check see them), with KNOWN_HOOKS rows', () => {
|
||||
expect(setupSrc).toContain('_hook_command_path hosts/claude/hooks/skill-route-hook ||');
|
||||
expect(setupSrc).toContain('_hook_command_path hosts/claude/hooks/skill-contract-stop-hook ||');
|
||||
expect(setupSrc).toContain('_hook_command_path hosts/claude/hooks/destructive-guard-hook ||');
|
||||
expect(settingsHookSrc).toContain('"destructive-guard-hook": { source: "gstack-destructive-guard", event: "PreToolUse", matcher: "Bash|PowerShell", relpath: "hosts/claude/hooks/destructive-guard-hook" }');
|
||||
expect(settingsHookSrc).toContain('"skill-route-hook": { source: "gstack-skill-route", event: "UserPromptSubmit", matcher: "", relpath: "hosts/claude/hooks/skill-route-hook" }');
|
||||
expect(settingsHookSrc).toContain('"skill-contract-stop-hook": { source: "gstack-skill-contract", event: "Stop", matcher: "", relpath: "hosts/claude/hooks/skill-contract-stop-hook" }');
|
||||
expect(setupSrc).toMatch(/_skill_hook_gate skill_contracts "\$SKILL_CONTRACTS_MODE" GSTACK_SKILL_CONTRACTS Stop \\\n "\$SKILL_CONTRACT_HOOK" gstack-skill-contract 10/);
|
||||
@@ -136,6 +142,37 @@ describe('setup: skill hook gates', () => {
|
||||
gate('', {}, 1);
|
||||
expect(registered()).toEqual([]);
|
||||
});
|
||||
|
||||
test('destructive_guard: on by default as one PreToolUse entry for Bash and PowerShell; an off set earlier is kept', () => {
|
||||
const g = gate('', {}, 0, ROOT, 'destructive_guard');
|
||||
expect(g.out).toContain(`registered PreToolUse hook: destructive check (on via default; turn off: gstack-config set destructive_guard off, or ./setup --no-destructive-guard`);
|
||||
const entries = settings().hooks?.PreToolUse ?? [];
|
||||
expect(entries).toHaveLength(1);
|
||||
expect(entries[0]).toMatchObject({ matcher: 'Bash|PowerShell', _gstack_source: 'gstack-destructive-guard' });
|
||||
expect(entries[0].hooks[0].command).toEndWith('hosts/claude/hooks/destructive-guard-hook');
|
||||
expect(config()).not.toContain('destructive_guard');
|
||||
fs.rmSync(settingsFile());
|
||||
fs.writeFileSync(path.join(state, 'config.yaml'), 'destructive_guard: off\nskill_routing: off\n');
|
||||
expect(gate('', {}, 0, ROOT, 'destructive_guard')).toEqual({ code: 0, out: '' });
|
||||
expect(gate('')).toEqual({ code: 0, out: '' });
|
||||
expect(settings().hooks?.PreToolUse ?? []).toEqual([]);
|
||||
expect(registered()).toEqual([]);
|
||||
});
|
||||
|
||||
test('the on-by-default notice prints once, names every switch it turned on and how to turn each off', () => {
|
||||
const start = setupSrc.indexOf('_HOOKS_NOTICE_MARKER=');
|
||||
const block = setupSrc.slice(start, setupSrc.indexOf('\nfi\n', start) + 4);
|
||||
const run = (on: string) => spawnSync('bash', ['-c', ['log() { printf "%s\\n" "$*"; }', 'QUIET=0', `_HOOKS_ON_BY_DEFAULT="${on}"`, block].join('\n')], {
|
||||
env: { PATH: process.env.PATH ?? '', HOME: home, GSTACK_STATE_ROOT: state }, encoding: 'utf8', timeout: 10_000,
|
||||
});
|
||||
expect(run('').stdout).toBe('');
|
||||
const first = run(' skill_routing destructive_guard');
|
||||
expect(first.status).toBe(0);
|
||||
expect(first.stdout).toContain("gstack's helper hooks are now on by default. This run turned on: skill_routing destructive_guard");
|
||||
expect(first.stdout).toContain('Turn one off: gstack-config set <name> off');
|
||||
expect(first.stdout).toContain('--no-skill-contracts, --no-destructive-guard');
|
||||
expect(run(' skill_contracts').stdout).toBe('');
|
||||
});
|
||||
});
|
||||
|
||||
describe('SWITCH_DEFAULT is the one default (a flip PR changes one line)', () => {
|
||||
@@ -197,14 +234,19 @@ describe('SWITCH_DEFAULT is the one default (a flip PR changes one line)', () =>
|
||||
expect(config()).toBe('');
|
||||
}
|
||||
|
||||
test('pin: skill_routing defaults to off today (a flip PR changes lib/skill-route.ts line 41 and this pin)', () => {
|
||||
expect(original.split('\n')[40]).toBe(" skill_routing: 'off',");
|
||||
expect(SWITCH_DEFAULT.skill_routing).toBe('off');
|
||||
test('pin: skill_routing defaults to on today (a flip PR changes lib/skill-route.ts line 47 and this pin)', () => {
|
||||
expect(original.split('\n')[46]).toBe(" skill_routing: 'on',");
|
||||
expect(SWITCH_DEFAULT.skill_routing).toBe('on');
|
||||
});
|
||||
|
||||
test('pin: skill_contracts defaults to off today (a flip PR changes lib/skill-route.ts line 42 and this pin)', () => {
|
||||
expect(original.split('\n')[41]).toBe(" skill_contracts: 'off',");
|
||||
expect(SWITCH_DEFAULT.skill_contracts).toBe('off');
|
||||
test('pin: skill_contracts defaults to on today (a flip PR changes lib/skill-route.ts line 48 and this pin)', () => {
|
||||
expect(original.split('\n')[47]).toBe(" skill_contracts: 'on',");
|
||||
expect(SWITCH_DEFAULT.skill_contracts).toBe('on');
|
||||
});
|
||||
|
||||
test('pin: destructive_guard defaults to on today (a flip PR changes lib/skill-route.ts line 49 and this pin)', () => {
|
||||
expect(original.split('\n')[48]).toBe(" destructive_guard: 'on',");
|
||||
expect(SWITCH_DEFAULT.destructive_guard).toBe('on');
|
||||
});
|
||||
|
||||
test('every reader agrees with SWITCH_DEFAULT: gstack-config, setup, the routing hook and the Stop hook', () => {
|
||||
|
||||
@@ -10,7 +10,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import * as fs from 'node:fs';
|
||||
import * as path from 'node:path';
|
||||
import { PROMPT_MAX_CHARS, ROUTED_SKILLS, ROUTE_THRESHOLD, SWITCH_DEFAULT, firstStep, hintLine, readSkillSwitch, routePrompt, scanInstalledSkills, scorePrompt, stem } from '../lib/skill-route';
|
||||
import { PROMPT_HEAD_CHARS, PROMPT_TAIL_CHARS, ROUTED_SKILLS, ROUTE_THRESHOLD, SWITCH_DEFAULT, firstStep, hintLine, readSkillSwitch, routePrompt, scanInstalledSkills, scorePrompt, stem } from '../lib/skill-route';
|
||||
import { ROOT, ROUTE_HOOK, SKILLS, hookEnv, runHook, skillsDir, tmpDir } from './helpers/skill-contract-fixture';
|
||||
|
||||
let state = '', skills = '';
|
||||
@@ -46,12 +46,41 @@ describe('scorer', () => {
|
||||
expect(['fixes', 'failing', 'debugging', 'passes'].map(stem)).toEqual(['fix', 'fail', 'debug', 'pass']);
|
||||
});
|
||||
|
||||
test('threshold, weak single words, slash commands and long prompts', () => {
|
||||
test('threshold, weak single words and slash commands', () => {
|
||||
expect(ROUTE_THRESHOLD).toBe(0.66);
|
||||
expect(routePrompt('what is the weather', fixtureSkills).route).toBeNull();
|
||||
expect(routePrompt('please review my diff', fixtureSkills)).toMatchObject({ route: null, reason: 'below-threshold' });
|
||||
expect(routePrompt('/verify fix this bug', fixtureSkills)).toMatchObject({ route: null, reason: 'slash-command' });
|
||||
expect(routePrompt(`fix this bug ${'x'.repeat(PROMPT_MAX_CHARS)}`, fixtureSkills)).toMatchObject({ route: null, reason: 'prompt-too-long' });
|
||||
});
|
||||
|
||||
test('a long prompt is scored on its head and tail windows, never skipped, and a paste between them is not scored', () => {
|
||||
const log = (n: number) => 'log line '.repeat(n);
|
||||
expect(routePrompt(`fix this bug ${log(2000)}`, fixtureSkills).route?.skill).toBe('verify');
|
||||
expect(routePrompt(`${log(2000)} fix this bug`, fixtureSkills).route?.skill).toBe('verify');
|
||||
const middle = `${'x '.repeat(PROMPT_HEAD_CHARS)}fix this bug ${'y '.repeat(PROMPT_TAIL_CHARS)}`;
|
||||
expect(routePrompt(middle, fixtureSkills)).toMatchObject({ route: null, reason: 'below-threshold' });
|
||||
});
|
||||
|
||||
test('a bug report routes on the words it uses for the defect; paths and identifiers never split into words', () => {
|
||||
const bugfix = { name: 'verify', file: '', frontmatter: '', triggers: ['fix this bug'] };
|
||||
for (const report of [
|
||||
'Please fix: parse_one raises ValueError on window functions',
|
||||
'Fix the crash when the config file is empty',
|
||||
'the export is wrong after the upgrade, fix it',
|
||||
'fix the failing upload: it fails with a traceback',
|
||||
]) expect(routePrompt(report, [bugfix]).route?.trigger).toBe('fix this bug');
|
||||
const qa = { name: 'qa', file: '', frontmatter: '', triggers: ['test the site'] };
|
||||
expect(routePrompt('test failed in /usr/lib/python3/site-packages/foo.py', [qa]).route).toBeNull();
|
||||
expect(routePrompt('please test the site', [qa]).route?.skill).toBe('qa');
|
||||
});
|
||||
|
||||
test('plain prompts that are not bug reports, reviews, QA or checks route nowhere', () => {
|
||||
const bugfix = { name: 'verify', file: '', frontmatter: '', triggers: ['fix this bug', 'reproduce the bug in a test'] };
|
||||
const routed = scanInstalledSkills(ROOT).skills.filter(s => ROUTED_SKILLS.includes(s.name));
|
||||
expect(routed.map(s => s.name).sort()).toEqual(['qa', 'review', 'verify']);
|
||||
const plain = fs.readFileSync(path.join(ROOT, 'test', 'fixtures', 'skill-route-plain-prompts.txt'), 'utf8').split('\n').filter(l => l && !l.startsWith('#'));
|
||||
expect(plain.length).toBe(60);
|
||||
expect(plain.filter(p => routePrompt(p, [bugfix, ...fixtureSkills, ...routed]).route)).toEqual([]);
|
||||
});
|
||||
|
||||
test('only the three discovery targets route; another installed skill with a matching trigger does not', () => {
|
||||
@@ -129,11 +158,11 @@ describe('skill-route hook', () => {
|
||||
test('error cases exit 0 with nothing on stdout or stderr, and count a failure', () => {
|
||||
expect(route('{not json')).toEqual(silent);
|
||||
expect(route('[1,2]')).toEqual(silent);
|
||||
expect(route(prompt('x'.repeat(PROMPT_MAX_CHARS + 1) + ' fix this bug'))).toEqual(silent);
|
||||
expect(route(prompt(`${'x '.repeat(6000)}fix this bug ${'y '.repeat(1000)}`))).toEqual(silent);
|
||||
expect(route(prompt('fix this bug ' + 'y'.repeat(300 * 1024)))).toEqual(silent);
|
||||
expect(route(JSON.stringify({ session_id: 'sess-r' }))).toEqual(silent);
|
||||
const log = traceLog();
|
||||
for (const event of ['event=bad-json', 'reason=prompt-too-long', 'event=stdin-over-cap', 'event=no-prompt']) expect(log).toContain(event);
|
||||
for (const event of ['event=bad-json', 'event=stdin-over-cap', 'event=no-prompt']) expect(log).toContain(event);
|
||||
expect(log).toContain('session=unknown event=stdin-over-cap cap=262144 failures=3');
|
||||
expect(log).toContain('session=sess-r event=no-prompt failures=2');
|
||||
});
|
||||
|
||||
Reference in new issue
Block a user