stillwright 0.2.1__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -450,7 +450,7 @@ checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
450
450
 
451
451
  [[package]]
452
452
  name = "stillwright"
453
- version = "0.2.1"
453
+ version = "0.2.2"
454
454
  dependencies = [
455
455
  "chrono",
456
456
  "clap",
@@ -1,6 +1,6 @@
1
1
  [package]
2
2
  name = "stillwright"
3
- version = "0.2.1"
3
+ version = "0.2.2"
4
4
  edition = "2021"
5
5
  rust-version = "1.89"
6
6
  description = "State keeper (sw) for the Stillwright agent skills: goals, runs, inbox, dated notes, hash-pinned tools"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: stillwright
3
- Version: 0.2.1
3
+ Version: 0.2.2
4
4
  Classifier: Environment :: Console
5
5
  Classifier: Programming Language :: Rust
6
6
  Classifier: Topic :: Software Development
@@ -78,6 +78,14 @@ refuses the stale receipt. The rewind keeps the state it replaced, so nothing is
78
78
  and the agent's final message is at most five lines.
79
79
  - **Goals, not prompts.** It keeps a goal queue, plans each goal into checkable steps, routes
80
80
  steps to the cheapest model that a command can verify, and measures the dollars.
81
+ - **Hooks the plugin brings along.** In Claude Code the plugin ships three hooks: the gate
82
+ before every shell command (`sw gate`: ask or block before a destructive one), the brief
83
+ after every context compaction (`sw run brief`), and a Stop hook (`sw run stop`) that refuses
84
+ to end a turn, once, while the open run has a `$`-checked step with no certified receipt. The
85
+ model gets the step and the exact commands back instead of the user getting "done". A step
86
+ logged as failed, a card waiting on you, or the host already continuing because of the hook
87
+ lets the turn end; a plan edited after work started costs one nudge and is dated in the log;
88
+ a machine without `sw` is never blocked.
81
89
 
82
90
  ## Measured
83
91
 
@@ -113,7 +121,9 @@ Or the agent's own way:
113
121
  | Hermes Agent | `git clone --depth 1 https://github.com/HamzaIlyas/stillwright /tmp/stillwright && mkdir -p ~/.hermes/skills/stillwright && cp -R /tmp/stillwright/skills/. ~/.hermes/skills/stillwright/` |
114
122
 
115
123
  For a whole team: run `sw init` in the repository and commit the two files it writes
116
- (`.claude/settings.json`, `.github/copilot/settings.json`).
124
+ (`.claude/settings.json`, `.github/copilot/settings.json`). It writes the same three hooks
125
+ the plugin ships, for hosts and setups that do not load plugin hooks; with the plugin
126
+ installed, a hook written by `sw init` runs a second time, which is harmless.
117
127
 
118
128
  The skills need the `sw` binary (a single file, no runtime). Any of these installs it:
119
129
 
@@ -61,6 +61,14 @@ refuses the stale receipt. The rewind keeps the state it replaced, so nothing is
61
61
  and the agent's final message is at most five lines.
62
62
  - **Goals, not prompts.** It keeps a goal queue, plans each goal into checkable steps, routes
63
63
  steps to the cheapest model that a command can verify, and measures the dollars.
64
+ - **Hooks the plugin brings along.** In Claude Code the plugin ships three hooks: the gate
65
+ before every shell command (`sw gate`: ask or block before a destructive one), the brief
66
+ after every context compaction (`sw run brief`), and a Stop hook (`sw run stop`) that refuses
67
+ to end a turn, once, while the open run has a `$`-checked step with no certified receipt. The
68
+ model gets the step and the exact commands back instead of the user getting "done". A step
69
+ logged as failed, a card waiting on you, or the host already continuing because of the hook
70
+ lets the turn end; a plan edited after work started costs one nudge and is dated in the log;
71
+ a machine without `sw` is never blocked.
64
72
 
65
73
  ## Measured
66
74
 
@@ -96,7 +104,9 @@ Or the agent's own way:
96
104
  | Hermes Agent | `git clone --depth 1 https://github.com/HamzaIlyas/stillwright /tmp/stillwright && mkdir -p ~/.hermes/skills/stillwright && cp -R /tmp/stillwright/skills/. ~/.hermes/skills/stillwright/` |
97
105
 
98
106
  For a whole team: run `sw init` in the repository and commit the two files it writes
99
- (`.claude/settings.json`, `.github/copilot/settings.json`).
107
+ (`.claude/settings.json`, `.github/copilot/settings.json`). It writes the same three hooks
108
+ the plugin ships, for hosts and setups that do not load plugin hooks; with the plugin
109
+ installed, a hook written by `sw init` runs a second time, which is harmless.
100
110
 
101
111
  The skills need the `sw` binary (a single file, no runtime). Any of these installs it:
102
112
 
@@ -295,6 +295,17 @@ enum RunCmd {
295
295
  run: String,
296
296
  step: String,
297
297
  },
298
+ /// Claude Code's Stop hook: the turn may not end, once, while the open run here has a
299
+ /// `$`-checked step without a certified receipt (no receipt, a failing one, or one not yet
300
+ /// passed by `sw run done`). `--hook` reads the Stop event on stdin and answers with
301
+ /// `{"decision":"block","reason":…}`; without it, prints the verdict. Allows the stop when
302
+ /// the host is already continuing because of this hook, when an ask or review card for the
303
+ /// run is open (waiting on the user is a reason to stop), when a step was logged as failed,
304
+ /// when no run is open here, and when the event is not JSON (fail open).
305
+ Stop {
306
+ #[arg(long)]
307
+ hook: bool,
308
+ },
298
309
  }
299
310
 
300
311
  #[derive(Subcommand)]
@@ -1809,6 +1820,174 @@ fn run_cwd(run: &Path) -> Option<String> {
1809
1820
  .into_iter()
1810
1821
  .find(|e| event_is(e, "event", "start"))
1811
1822
  .and_then(|e| e.get("cwd").map(value_str))
1823
+ .filter(|cwd| !cwd.is_empty())
1824
+ }
1825
+
1826
+ /// The step's title: the words between `N.` and the first `|`.
1827
+ fn plan_step_title(plan: &str, step: &str) -> String {
1828
+ plan.lines()
1829
+ .find_map(|line| {
1830
+ let digits: String = line.chars().take_while(|c| c.is_ascii_digit()).collect();
1831
+ let rest = &line[digits.len()..];
1832
+ (digits == step && rest.starts_with('.'))
1833
+ .then(|| rest[1..].split('|').next().unwrap_or("").trim().to_string())
1834
+ })
1835
+ .unwrap_or_default()
1836
+ }
1837
+
1838
+ /// Open runs started in `here` or in a folder above it. A run started in a subfolder is not
1839
+ /// this session's, and a session opened above the run folder is not the run's either, so a
1840
+ /// Stop hook in `~` is never held by a project underneath.
1841
+ fn open_runs_over(store: &Store, here: &Path) -> Result<Vec<PathBuf>> {
1842
+ let here = fs::canonicalize(here).unwrap_or_else(|_| here.to_path_buf());
1843
+ Ok(store
1844
+ .runs()?
1845
+ .into_iter()
1846
+ .filter(|dir| {
1847
+ run_cwd(dir).is_some_and(|c| here.starts_with(PathBuf::from(c)))
1848
+ && Progress::of(dir).next.is_some()
1849
+ })
1850
+ .collect())
1851
+ }
1852
+
1853
+ /// Whether plan.md differs from the last hash on record; when it does, the new hash is
1854
+ /// appended, so the edit is dated in the log and the next look finds it recorded.
1855
+ fn plan_drift(run: &Path) -> Result<Option<(String, String)>> {
1856
+ let Some(now) = plan_hash(run) else {
1857
+ return Ok(None);
1858
+ };
1859
+ let last = log_events(run)?
1860
+ .into_iter()
1861
+ .rev()
1862
+ .find(|e| event_is(e, "event", "plan"))
1863
+ .and_then(|e| e.get("sha256").map(value_str));
1864
+ match last {
1865
+ Some(then) if then != now => {
1866
+ let mut event = serde_json::Map::new();
1867
+ event.insert("event".into(), "plan".into());
1868
+ event.insert("sha256".into(), now.clone().into());
1869
+ event.insert("changed".into(), true.into());
1870
+ append_json(run, event)?;
1871
+ Ok(Some((then, now)))
1872
+ }
1873
+ _ => Ok(None),
1874
+ }
1875
+ }
1876
+
1877
+ /// Why this run may not let the turn end yet, or `None` when it may.
1878
+ fn stop_reason(store: &Store, dir: &Path) -> Result<Option<String>> {
1879
+ let name = file_name(dir);
1880
+ let cards: Vec<Card> = store.load("inbox.json")?;
1881
+ let waiting = cards
1882
+ .iter()
1883
+ .any(|c| c.status == "open" && c.run == name && matches!(c.kind, Kind::Ask | Kind::Review));
1884
+ if waiting {
1885
+ return Ok(None);
1886
+ }
1887
+ note_plan(dir)?;
1888
+ if let Some((then, now)) = plan_drift(dir)? {
1889
+ return Ok(Some(format!(
1890
+ "stillwright: run {name}: plan.md changed after work started (was {}, now {}), so this \
1891
+ turn cannot end on the old plan. The edit is now on record; if it is intended, say \
1892
+ why in the log (`sw run log {name} note=\"plan: <what changed and why>\"`), then stop again.",
1893
+ short(&then),
1894
+ short(&now)
1895
+ )));
1896
+ }
1897
+ let plan = fs::read_to_string(dir.join("plan.md")).unwrap_or_default();
1898
+ let results = step_results(dir, &plan);
1899
+ let events = log_events(dir)?;
1900
+ for step in runnable_steps(&plan, &results) {
1901
+ let Some(check) = plan_step_check(&plan, &step) else {
1902
+ continue;
1903
+ };
1904
+ if command_check(&check).is_none() {
1905
+ continue;
1906
+ }
1907
+ if outward_of(&plan, &step).is_some() && consent(store, dir).is_err() {
1908
+ // Held until the user says yes: waiting is the right thing to do.
1909
+ continue;
1910
+ }
1911
+ // The last word on the step: a receipt from `sw run check`, or a hand-logged result.
1912
+ let last = events.iter().rev().find(|e| {
1913
+ event_is(e, "step", &step)
1914
+ && (event_is(e, "event", "receipt") || e.contains_key("result"))
1915
+ });
1916
+ let state = match last {
1917
+ None => "has no receipt",
1918
+ Some(e) if event_is(e, "event", "receipt") => {
1919
+ if e.get("ok") == Some(&serde_json::Value::Bool(true)) {
1920
+ "has a receipt that `sw run done` has not certified"
1921
+ } else {
1922
+ "has a failing receipt"
1923
+ }
1924
+ }
1925
+ // Logged as not done: an honest stop, nothing to force.
1926
+ Some(e) if e.get("result").map(value_str).as_deref() == Some("fail") => continue,
1927
+ Some(_) => "has a pass logged by hand, which does not count for a `$` check",
1928
+ };
1929
+ let title = plan_step_title(&plan, &step);
1930
+ return Ok(Some(format!(
1931
+ "stillwright: run {name} step {step} ({title}) {state}, so this turn cannot end as done. \
1932
+ Run `sw run check {name} {step}` and then `sw run done {name} {step}`. \
1933
+ If the step is not done, say so: `sw run log {name} step={step} result=fail note=<why>`. \
1934
+ If you are waiting on the user, add a card (`sw inbox add ask \"<question>\" --run {name}`), then stop again."
1935
+ )));
1936
+ }
1937
+ Ok(None)
1938
+ }
1939
+
1940
+ /// Why this turn may not end yet, or `None` when it may. Every open run started here or above
1941
+ /// is asked, so a second run cannot shadow the first.
1942
+ fn stop_verdict(store: &Store, here: &Path, host_continuing: bool) -> Result<Option<String>> {
1943
+ if host_continuing {
1944
+ // The host is already continuing because of this hook: one nudge is the rule, so a
1945
+ // step that stays unproven can never trap the session.
1946
+ return Ok(None);
1947
+ }
1948
+ for dir in open_runs_over(store, here)? {
1949
+ if let Some(reason) = stop_reason(store, &dir)? {
1950
+ return Ok(Some(reason));
1951
+ }
1952
+ }
1953
+ Ok(None)
1954
+ }
1955
+
1956
+ fn run_stop(store: &Store, hook: bool) -> Result<()> {
1957
+ let mut here = std::env::current_dir().map_err(|e| e.to_string())?;
1958
+ let mut host_continuing = false;
1959
+ if hook {
1960
+ use std::io::Read as _;
1961
+ let mut input = String::new();
1962
+ std::io::stdin()
1963
+ .read_to_string(&mut input)
1964
+ .map_err(|e| e.to_string())?;
1965
+ let input = input.trim_start_matches('\u{feff}');
1966
+ let event: serde_json::Value = serde_json::from_str(input).unwrap_or_default();
1967
+ if event.get("hook_event_name").and_then(|v| v.as_str()) != Some("Stop") {
1968
+ // Fail open: a Stop hook that errors would hold every turn, and a broken event is
1969
+ // the host's bug; say so where the log can see it.
1970
+ eprintln!("warning: sw run stop --hook: no Stop event on stdin; allowed");
1971
+ return Ok(());
1972
+ }
1973
+ host_continuing = event
1974
+ .get("stop_hook_active")
1975
+ .and_then(|v| v.as_bool())
1976
+ .unwrap_or(false);
1977
+ if let Some(cwd) = event.get("cwd").and_then(|v| v.as_str()) {
1978
+ here = PathBuf::from(cwd);
1979
+ }
1980
+ }
1981
+ match (hook, stop_verdict(store, &here, host_continuing)?) {
1982
+ (true, Some(reason)) => println!(
1983
+ "{}",
1984
+ serde_json::json!({ "decision": "block", "reason": reason })
1985
+ ),
1986
+ (true, None) => {}
1987
+ (false, Some(reason)) => println!("block: {reason}"),
1988
+ (false, None) => println!("allow"),
1989
+ }
1990
+ Ok(())
1812
1991
  }
1813
1992
 
1814
1993
  fn run_brief(store: &Store) -> Result<()> {
@@ -2207,6 +2386,9 @@ fn enable_in_settings(path: &Path) -> Result<bool> {
2207
2386
  for (event, matcher, command) in [
2208
2387
  ("PreToolUse", "Bash", "sw gate --hook"),
2209
2388
  ("SessionStart", "startup|resume|compact", "sw run brief"),
2389
+ // The Stop verdict travels as JSON on stdout, so the exit code carries nothing; `exit 0`
2390
+ // keeps an older sw without `run stop` (exit 2 on an unknown subcommand) from holding a turn.
2391
+ ("Stop", "", "sw run stop --hook; exit 0"),
2210
2392
  ] {
2211
2393
  let list = hooks.entry(event).or_insert_with(|| serde_json::json!([]));
2212
2394
  let Some(list) = list.as_array_mut() else {
@@ -2222,10 +2404,14 @@ fn enable_in_settings(path: &Path) -> Result<bool> {
2222
2404
  })
2223
2405
  });
2224
2406
  if !present {
2225
- list.push(serde_json::json!({
2226
- "matcher": matcher,
2227
- "hooks": [{ "type": "command", "command": command, "timeout": 20 }]
2228
- }));
2407
+ let hook =
2408
+ serde_json::json!([{ "type": "command", "command": command, "timeout": 20 }]);
2409
+ // Stop takes no matcher: it fires on every stop.
2410
+ list.push(if matcher.is_empty() {
2411
+ serde_json::json!({ "hooks": hook })
2412
+ } else {
2413
+ serde_json::json!({ "matcher": matcher, "hooks": hook })
2414
+ });
2229
2415
  }
2230
2416
  }
2231
2417
  }
@@ -2940,6 +3126,7 @@ fn run_cmd(store: &Store, cmd: RunCmd) -> Result<()> {
2940
3126
  RunCmd::Snapshot { run, step } => run_snapshot(&store.resolve_run(&run)?, &step)?,
2941
3127
  RunCmd::Rewind { run, step } => run_rewind(&store.resolve_run(&run)?, &step)?,
2942
3128
  RunCmd::Brief => run_brief(store)?,
3129
+ RunCmd::Stop { hook } => run_stop(store, hook)?,
2943
3130
  RunCmd::Stats => run_stats(store)?,
2944
3131
  RunCmd::Next { run } => {
2945
3132
  let dir = store.resolve_run(&run)?;
File without changes
File without changes
File without changes
File without changes