rumo-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{rumo_cli-0.2.1 → rumo_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rumo-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: Your dev work, past, now and later: Markdown files, a terminal Timeline, and AI agents that keep it current
 Project-URL: Homepage, https://github.com/pedrobuzzi/rumo
 Project-URL: Issues, https://github.com/pedrobuzzi/rumo/issues
@@ -33,7 +33,7 @@ Timeline, and let your AI agent sessions keep it up to date while you work.
 
 Items can belong to a **group** (a project or initiative), shown as a label with its name on its
 color; color in rumo only ever means the group. One item is one line, plus its next step. rumo shows
-one horizon at a time (Now, or Past with `p`, or Later with `l`) in three views: the **Timeline**,
+one horizon at a time (`h` steps Now, Later, Past), named in a banner atop the list, in three views: the **Timeline**,
 **Projects** (one block per group) and **Repos** (one block per repository of the item's latest
 agent session). The interface is in English; the content (titles, notes, steps) is in your own
 language.
@@ -71,7 +71,9 @@ system language.
   ```
 
 **Update**: `uv tool upgrade rumo-cli` (or `pipx upgrade rumo-cli`, `brew upgrade rumo`), and
-`/plugin marketplace update rumo` in Claude Code.
+`/plugin marketplace update rumo` in Claude Code, then `/reload-plugins` in sessions already open.
+To get new plugin versions on their own, turn on auto-update for the `rumo` marketplace in `/plugin`
+(Marketplaces tab); the `rumo` command updates with your package manager.
 
 **Uninstall**: `/plugin uninstall rumo@rumo`, then `uv tool uninstall rumo-cli` (or
 `pipx uninstall rumo-cli`, `brew uninstall rumo`). Your items in `~/rumo/` are never touched.
@@ -85,7 +87,7 @@ system language.
 | ↑ ↓ | move through the list |
 | Tab | switch between the list, steps and sessions |
 | `v` | next view: Timeline, Projects, Repos (`1` `2` `3` go straight to one; rumo remembers it) |
-| `p` / `l` | show Past / Later; press again to go back to Now |
+| `h` | next horizon: Now, then Later, then Past, then Now again |
 | `s` | change status (1-5 picks directly) |
 | `g` | set the group or create one; inside, `r` renames, `c` recolors and `d` deletes the highlighted group (its items stay) |
 | `t` | toggle tags |
@@ -120,8 +122,15 @@ applies it only if you agree.
 
 Steps are the heart of an item: while a session is linked, the agent checks off what got done, adds
 what came up and keeps the next action as the first open step, after every response in which work
-happened. Left off is one line and Context at most three. `/clear` starts a new, unlinked session;
-`claude --resume <id>` picks the old one up again.
+happened. If a turn did work and no linked item changed, the plugin reminds the agent before the turn
+ends. Open steps are never deleted unless you ask, so half-done work stays in Now. One session can
+follow several topics: when you start something no linked item covers, the agent asks once whether to
+track it as a new item, add it as a step, or leave it out. Left off is one line and Context at most
+three. `/clear` starts a new, unlinked session; `claude --resume <id>` picks the old one up again.
+
+In a session without an item, once it edits files, the agent asks whether to track it. The first time
+it also asks whether to keep asking in future sessions (`ask_to_track` in the config). If you say no,
+it reminds you that the option exists every 15 days or 15 sessions.
 
 ## Item format
 
@@ -165,14 +174,15 @@ folder = "~/rumo"
 language = "pt-BR"     # language of the content the agent writes; defaults to your system language
 tags = ["bug", "feature", "refactor", "research", "spike", "review",
         "infra", "deploy", "meeting", "docs", "support", "tech-debt"]
+ask_to_track = true    # offer rumo in agent sessions without an item; unset until you first answer
 
 [groups.auth]
 name = "Auth migration"
 color = "blue"         # blue, green, yellow, orange, red, magenta, purple, cyan
 ```
 
-Groups appear in the order of this file in every view. The last view is remembered in
-`state.json`, next to `config.toml`.
+Groups appear in the order of this file in every view. The last view, and when the agent last
+asked about tracking, are remembered in `state.json`, next to `config.toml`.
 
 `RUMO_DIR` and `RUMO_CONFIG` override the folder and the config path.
 

{rumo_cli-0.2.1 → rumo_cli-0.3.0}/README.md

@@ -12,7 +12,7 @@ Timeline, and let your AI agent sessions keep it up to date while you work.
 
 Items can belong to a **group** (a project or initiative), shown as a label with its name on its
 color; color in rumo only ever means the group. One item is one line, plus its next step. rumo shows
-one horizon at a time (Now, or Past with `p`, or Later with `l`) in three views: the **Timeline**,
+one horizon at a time (`h` steps Now, Later, Past), named in a banner atop the list, in three views: the **Timeline**,
 **Projects** (one block per group) and **Repos** (one block per repository of the item's latest
 agent session). The interface is in English; the content (titles, notes, steps) is in your own
 language.
@@ -50,7 +50,9 @@ system language.
   ```
 
 **Update**: `uv tool upgrade rumo-cli` (or `pipx upgrade rumo-cli`, `brew upgrade rumo`), and
-`/plugin marketplace update rumo` in Claude Code.
+`/plugin marketplace update rumo` in Claude Code, then `/reload-plugins` in sessions already open.
+To get new plugin versions on their own, turn on auto-update for the `rumo` marketplace in `/plugin`
+(Marketplaces tab); the `rumo` command updates with your package manager.
 
 **Uninstall**: `/plugin uninstall rumo@rumo`, then `uv tool uninstall rumo-cli` (or
 `pipx uninstall rumo-cli`, `brew uninstall rumo`). Your items in `~/rumo/` are never touched.
@@ -64,7 +66,7 @@ system language.
 | ↑ ↓ | move through the list |
 | Tab | switch between the list, steps and sessions |
 | `v` | next view: Timeline, Projects, Repos (`1` `2` `3` go straight to one; rumo remembers it) |
-| `p` / `l` | show Past / Later; press again to go back to Now |
+| `h` | next horizon: Now, then Later, then Past, then Now again |
 | `s` | change status (1-5 picks directly) |
 | `g` | set the group or create one; inside, `r` renames, `c` recolors and `d` deletes the highlighted group (its items stay) |
 | `t` | toggle tags |
@@ -99,8 +101,15 @@ applies it only if you agree.
 
 Steps are the heart of an item: while a session is linked, the agent checks off what got done, adds
 what came up and keeps the next action as the first open step, after every response in which work
-happened. Left off is one line and Context at most three. `/clear` starts a new, unlinked session;
-`claude --resume <id>` picks the old one up again.
+happened. If a turn did work and no linked item changed, the plugin reminds the agent before the turn
+ends. Open steps are never deleted unless you ask, so half-done work stays in Now. One session can
+follow several topics: when you start something no linked item covers, the agent asks once whether to
+track it as a new item, add it as a step, or leave it out. Left off is one line and Context at most
+three. `/clear` starts a new, unlinked session; `claude --resume <id>` picks the old one up again.
+
+In a session without an item, once it edits files, the agent asks whether to track it. The first time
+it also asks whether to keep asking in future sessions (`ask_to_track` in the config). If you say no,
+it reminds you that the option exists every 15 days or 15 sessions.
 
 ## Item format
 
@@ -144,14 +153,15 @@ folder = "~/rumo"
 language = "pt-BR"     # language of the content the agent writes; defaults to your system language
 tags = ["bug", "feature", "refactor", "research", "spike", "review",
         "infra", "deploy", "meeting", "docs", "support", "tech-debt"]
+ask_to_track = true    # offer rumo in agent sessions without an item; unset until you first answer
 
 [groups.auth]
 name = "Auth migration"
 color = "blue"         # blue, green, yellow, orange, red, magenta, purple, cyan
 ```
 
-Groups appear in the order of this file in every view. The last view is remembered in
-`state.json`, next to `config.toml`.
+Groups appear in the order of this file in every view. The last view, and when the agent last
+asked about tracking, are remembered in `state.json`, next to `config.toml`.
 
 `RUMO_DIR` and `RUMO_CONFIG` override the folder and the config path.
 

{rumo_cli-0.2.1 → rumo_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rumo-cli"
-version = "0.2.1"
+version = "0.3.0"
 description = "Your dev work, past, now and later: Markdown files, a terminal Timeline, and AI agents that keep it current"
 readme = "README.md"
 requires-python = ">=3.11"

{rumo_cli-0.2.1 → rumo_cli-0.3.0}/src/rumo/app.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import json
 import os
 import re
 import shlex
@@ -30,6 +29,12 @@ from rumo.items import Item, WriteConflict
 SHAPES = {"doing": "●", "waiting": "◐", "idea": "○", "paused": "◌", "done": "✓"}
 VIEWS = {"timeline": "Timeline", "projects": "Projects", "repos": "Repos"}
 HORIZONS: tuple[str, ...] = ("past", "now", "later")
+CYCLE = ("now", "later", "past")  # what `h` steps through, starting where rumo opens
+HORIZON_SAYS = {
+    "now": "doing and waiting",
+    "later": "ideas and paused work",
+    "past": f"done in the last {items.PAST_WINDOW_DAYS} days",
+}
 UNGROUPED = "-"  # the "No group" or "No repo" block, which always comes last
 MAX_LABEL = 16  # the project label fits the longest group name up to this many characters
 NEW_GROUP = "+new"
@@ -39,7 +44,7 @@ KEYS = Text.assemble(
     *(
         part
         for key, label in [
-            ("v", "view"), ("p", "past"), ("l", "later"), ("s", "status"), ("g", "group"), ("t", "tags"),
+            ("v", "view"), ("h", "now/later/past"), ("s", "status"), ("g", "group"), ("t", "tags"),
             ("n", "new idea"), ("e", "edit"), ("space", "step"), ("c", "copy resume"), ("/", "filter"), ("q", "quit"),
         ]
         for part in ((key, "bold"), (f" {label}  ", "dim"))
@@ -65,7 +70,7 @@ def short_date(stamp: str) -> str:
 
 EMPTY = {
     "past": f"Nothing finished in the last {items.PAST_WINDOW_DAYS} days.",
-    "now": "Nothing in progress. Press l to see what is next.",
+    "now": "Nothing in progress. Press h to see what is next.",
     "later": "Nothing for later. Press n to capture an idea.",
 }
 
@@ -318,8 +323,7 @@ class RumoApp(App):
         Binding("1", "view('timeline')", show=False),
         Binding("2", "view('projects')", show=False),
         Binding("3", "view('repos')", show=False),
-        Binding("p", "horizon('past')", "past"),
-        Binding("l", "horizon('later')", "later"),
+        Binding("h", "next_horizon", "horizon"),
         Binding("s", "status", "status"),
         Binding("g", "group", "group"),
         Binding("t", "tags", "tags"),
@@ -425,8 +429,10 @@ class RumoApp(App):
         build = {"timeline": self.timeline_rows, "projects": self.project_rows, "repos": self.repo_rows}[self.view]
         if not self.items:
             options = [self.message("No items yet. Press n to capture an idea, or run /rumo new in an agent session.")]
+        elif filtering:
+            options = build(tl, shown) or [self.message("No matches.")]
         else:
-            options = build(tl, shown) or [self.message("No matches." if filtering else EMPTY[self.horizon])]
+            options = [self.banner(tl), *(build(tl, shown) or [self.message(EMPTY[self.horizon])])]
 
         timeline.clear_options()
         timeline.add_options(options)
@@ -455,7 +461,7 @@ class RumoApp(App):
             if len(shown) > 1:
                 if not its and not older:
                     continue
-                rows.append(Option(Text(horizon.capitalize(), "bold"), id=f"header:{horizon}", disabled=True))
+                rows.append(Option(Text(f" {horizon.upper()} ", "bold reverse"), id=f"header:{horizon}", disabled=True))
             if older:
                 rows.append(self.older_option(older))
             rows += [self.item_option(i) for i in its]
@@ -569,11 +575,28 @@ class RumoApp(App):
     def horizon_tabs(self, tl: items.Timeline) -> Text:
         counts = {horizon: len(its) for horizon, its in self.horizons(tl).items()}
         text = Text(" ")
-        for horizon, key in (("past", "p "), ("now", ""), ("later", "l ")):
-            text.append(f"{key}{horizon.capitalize()} {counts[horizon]}", "bold" if horizon == self.horizon else "dim")
-            text.append(" " if horizon == "later" else "  ")
+        for horizon in HORIZONS:
+            name = horizon.upper() if horizon == self.horizon else horizon.capitalize()
+            text.append(f"{name} {counts[horizon]}", "bold" if horizon == self.horizon else "dim")
+            text.append(" " if horizon == HORIZONS[-1] else "  ")
         return text
 
+    def banner(self, tl: items.Timeline) -> Option:
+        """The list's first row: which horizon this is, what it holds, and where `h` goes next."""
+        count = len(self.horizons(tl)[self.horizon])
+        following = CYCLE[(CYCLE.index(self.horizon) + 1) % len(CYCLE)]
+        grid = Table.grid(padding=(0, 1), expand=True)
+        grid.add_column(no_wrap=True)
+        grid.add_column(ratio=1, no_wrap=True, overflow="ellipsis")
+        grid.add_column(no_wrap=True, justify="right")
+        grid.add_row(
+            Text(f" {self.horizon.upper()} ", "bold reverse"),
+            Text(f"{plural(count, 'item')} · {HORIZON_SAYS[self.horizon]}", "dim"),
+            Text.assemble(("h", "bold"), (f" ▸ {following.capitalize()}", "dim")),
+        )
+        grid.add_row("", "", "")
+        return Option(grid, id=f"horizon:{self.horizon}", disabled=True)
+
     def legend(self) -> Text:
         text = Text()
         if self.cfg.error:
@@ -659,31 +682,20 @@ class RumoApp(App):
         self.build_timeline()
         self.show_detail()
 
-    def action_horizon(self, horizon: str) -> None:
-        """`p` shows Past and `p` again goes back to Now; `l` does the same for Later."""
-        self.horizon = "now" if self.horizon == horizon else horizon
+    def action_next_horizon(self) -> None:
+        """`h` steps Now -> Later -> Past -> Now."""
+        self.horizon = CYCLE[(CYCLE.index(self.horizon) + 1) % len(CYCLE)]
         self.build_timeline()
         self.show_detail()
 
-    # The view survives restarts, in a file of its own: config.toml only ever changes when the
-    # user edits a group.
-    def state_path(self) -> Path:
-        return self.config_path.parent / "state.json"
-
+    # The view survives restarts, in state.json: config.toml only ever changes when the user
+    # edits a group.
     def load_state(self) -> None:
-        try:
-            data = json.loads(self.state_path().read_text(encoding="utf-8"))
-        except (OSError, ValueError):
-            return
-        if isinstance(data, dict) and data.get("view") in VIEWS:
-            self.view = data["view"]
+        if (view := config.load_state(self.config_path).get("view")) in VIEWS:
+            self.view = view
 
     def save_state(self) -> None:
-        state = {"view": self.view}
-        try:
-            self.state_path().write_text(json.dumps(state) + "\n", encoding="utf-8")
-        except OSError:
-            pass  # remembering is a convenience; never fail an action over it
+        config.update_state(self.config_path, view=self.view)
 
     def action_toggle_step(self) -> None:
         item = self.current_item()

{rumo_cli-0.2.1 → rumo_cli-0.3.0}/src/rumo/cli.py

@@ -1,7 +1,7 @@
 """The `rumo` command: opens the Timeline.
 
 Other subcommands exist for the agent and the hook, and are kept out of
-the help on purpose: `hook`, `index`, `path`, `group-add`, `--version`.
+the help on purpose: `hook`, `index`, `path`, `group-add`, `ask-to-track`, `--version`.
 """
 
 from __future__ import annotations
@@ -37,6 +37,8 @@ def main(argv: list[str] | None = None) -> None:
         _index()
     elif command == "group-add":
         _group_add(args[1:])
+    elif command == "ask-to-track":
+        _ask_to_track(args[1:])
     elif command in ("-V", "--version"):
         from importlib.metadata import version
 
@@ -73,5 +75,17 @@ def _group_add(rest: list[str]) -> None:
     print(config.add_group(config.load().path, rest[0].strip(), rest[1]))
 
 
+def _ask_to_track(rest: list[str]) -> None:
+    """`rumo ask-to-track true|false`: whether the hook offers rumo in agent sessions without an item."""
+    from rumo import config
+
+    if len(rest) != 1 or rest[0] not in ("true", "false"):
+        print("usage: rumo ask-to-track <true|false>", file=sys.stderr)
+        raise SystemExit(2)
+    path = config.load().path
+    config.set_ask_to_track(path, rest[0] == "true")
+    print(f"ask_to_track = {rest[0]} in {path}")
+
+
 if __name__ == "__main__":
     main()

{rumo_cli-0.2.1 → rumo_cli-0.3.0}/src/rumo/config.py

@@ -3,6 +3,7 @@
     folder = "~/rumo"
     language = "pt-BR"            # language of the content the agent writes
     tags = ["bug", "feature"]     # fixed list the agent picks from
+    ask_to_track = true           # in agent sessions without an item, offer to track them (unset: ask once)
 
     [groups.auth]
     name = "Migração auth"        # content: any language
@@ -57,6 +58,7 @@ class Config:
     language: str = "en"
     tags: list[str] = field(default_factory=lambda: list(DEFAULT_TAGS))
     groups: dict[str, Group] = field(default_factory=dict)
+    ask_to_track: bool | None = None  # None: the user was never asked
     error: str | None = None
 
 
@@ -90,6 +92,8 @@ def load(path: Path | None = None) -> Config:
         cfg.language = language.strip()
     if isinstance(tags := data.get("tags"), list):
         cfg.tags = [str(t) for t in tags]
+    if isinstance(ask := data.get("ask_to_track"), bool):
+        cfg.ask_to_track = ask
     groups = data.get("groups")
     for key, value in (groups.items() if isinstance(groups, dict) else []):
         if isinstance(value, dict):
@@ -129,6 +133,29 @@ def add_group(path: Path, name: str, color: str) -> str:
     return key
 
 
+def set_ask_to_track(path: Path, value: bool) -> None:
+    """Write `ask_to_track` as a top-level key: replace it in place, or add it before the first table.
+
+    Without a config file, write only this key: the hook that records the answer may not see the
+    system language, so the defaults are left to the first `rumo` run or to `load`.
+    """
+    new_line = f"ask_to_track = {'true' if value else 'false'}\n"
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(new_line, encoding="utf-8")
+        return
+    lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
+    if lines and not lines[-1].endswith("\n"):
+        lines[-1] += "\n"
+    first_table = next((i for i, line in enumerate(lines) if _TABLE_RE.match(line)), len(lines))
+    found = next((i for i in range(first_table) if re.match(r"^\s*ask_to_track\s*=", lines[i])), None)
+    if found is not None:
+        lines[found] = new_line
+    else:
+        lines.insert(_content_end(lines, -1, first_table), new_line)
+    path.write_text("".join(lines), encoding="utf-8")
+
+
 class GroupNotEditable(Exception):
     """The group has no `[groups.<key>]` table in the plain form these text edits understand."""
 
@@ -197,5 +224,28 @@ def default_text(folder: Path, language: str) -> str:
     )
 
 
+def state_path(config_path: Path) -> Path:
+    """Small state rumo writes for itself (the TUI's view, the hook's counters), apart from the user's config."""
+    return config_path.parent / "state.json"
+
+
+def load_state(config_path: Path) -> dict:
+    try:
+        data = json.loads(state_path(config_path).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def update_state(config_path: Path, **changes: object) -> None:
+    """Merge `changes` into state.json. Never fails: remembering is a convenience."""
+    try:
+        path = state_path(config_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(load_state(config_path) | changes) + "\n", encoding="utf-8")
+    except OSError:
+        pass
+
+
 def toml_str(value: str) -> str:
     return json.dumps(value, ensure_ascii=False)  # a JSON string is a valid TOML basic string

rumo_cli-0.3.0/src/rumo/hook.py

@@ -0,0 +1,294 @@
+"""Claude Code hooks: keep the items a session works on up to date, and offer rumo for untracked work.
+
+The plugin sends two events to `rumo hook`:
+
+- UserPromptSubmit: remind a linked session of its items and the update rules. The link is the
+  session id written in an item's Sessions section (by `/rumo new` or `/rumo link`). A line
+  ending in `| closed` (from park/unlink) no longer links, and after `/clear` the id changes, so
+  the reminder stops on its own.
+- Stop: at the end of a turn that did work, check that it reached the items. A linked session
+  whose items did not change gets one more nudge. A session without items that edited files is
+  asked once whether to track it (see `untracked`).
+
+The messages carry the rules, so they reach the agent exactly when they matter and nothing has to be
+added to the user's global instructions. Runs on every prompt and every stop: stdlib only, UTF-8
+regardless of the console, silent on anything unexpected.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from pathlib import Path
+
+from rumo import config, items
+
+RULES = (
+    "Steps are what matters. Before you finish this response, if any work happened, edit the item it "
+    "belongs to with the Edit tool: in Steps, check what is done, add a step for anything new or left for "
+    "later (`- [ ] [agent] ...`, or `- [ ] [manual] ...` for what the user or someone else does), reword "
+    "steps that changed, and keep the very next action as the first open step. Never delete an open step "
+    "unless the user explicitly asks; switching topics never closes, parks or deletes anything. If the user "
+    "starts work that belongs to none of these items, ask once, in one line at the end of your response: "
+    "track it as a new item ({create}; this session links to it too), add it as a step to one of these, "
+    "or not track it. One short line per step, starting with a verb. Then set `updated`; rewrite Left off "
+    "(one line: where it stands or what blocks it) only if that changed, and keep Context to at most 3 "
+    "lines. Conversation-only replies need no update. Write content in the configured language (`rumo "
+    "index`); keep keys, sections, statuses and tags in English. Never set `done` without every step "
+    "checked and the user's confirmation. To stop updating from this session, append `| closed` to its "
+    "line in Sessions."
+)
+SHOWN_STEPS = 3
+
+WORK_TOOLS = {"Edit", "Write", "NotebookEdit", "Bash"}  # a linked turn with these should reach its items
+EDIT_TOOLS = {"Edit", "Write", "NotebookEdit"}  # an untracked session is worth asking about once it edits
+ASK_AGAIN_DAYS = 15  # after the user said not to be asked, remind them the option exists
+ASK_AGAIN_SESSIONS = 15
+REMEMBERED_SESSIONS = 200  # sessions already asked or counted, so each one is asked at most once
+
+# Shell commands that only look around: a turn that ran nothing else did no work to record.
+LOOK_COMMANDS = {
+    "ls", "cat", "head", "tail", "less", "wc", "pwd", "echo", "printf", "grep", "rg", "find", "fd", "tree",
+    "which", "type", "file", "stat", "du", "df", "date", "env", "printenv", "diff", "cd",
+}
+LOOK_SUBCOMMANDS = {
+    "git": {"status", "diff", "log", "show", "branch", "rev-parse", "remote", "blame", "ls-files"},
+    "rumo": {"index", "path", "--version"},
+}
+
+
+def open_steps(item: items.Item) -> str:
+    """The next open steps, so the agent sees what to check off without opening the file."""
+    pending = [s for s in item.steps if not s.done]
+    if not pending:
+        return "Open steps: none."
+    shown = [(f"[{s.kind}] " if s.kind else "") + (s.text if len(s.text) <= 80 else s.text[:79] + "…") for s in pending[:SHOWN_STEPS]]
+    more = len(pending) - SHOWN_STEPS
+    return "Open steps: " + "; ".join(shown + ([f"(+{more} more)"] if more > 0 else [])) + "."
+
+
+def how_to_create() -> str:
+    """The agent cannot run the /rumo skill itself, but it can follow it when the plugin says where it is."""
+    root = os.environ.get("CLAUDE_PLUGIN_ROOT")
+    skill = Path(root) / "skills" / "rumo" / "SKILL.md" if root else None
+    if skill and skill.is_file():
+        return f"create it the way `/rumo new` does, following the `new` section of {skill}"
+    return "ask them to type `/rumo new`"
+
+
+def linked_items(cfg: config.Config, session_id: str) -> list[items.Item]:
+    return [
+        item for item in items.list_items(cfg.folder)
+        if any(s.id == session_id and not s.closed for s in item.sessions)
+    ]
+
+
+def reminder(cfg: config.Config, session_id: str) -> str:
+    linked = [f"{item.path} (status: {item.status}). {open_steps(item)}" for item in linked_items(cfg, session_id)]
+    if not linked:
+        return ""
+    return "This session is linked to rumo item(s): " + " ".join(linked) + " " + RULES.format(create=how_to_create()) + "\n"
+
+
+@dataclass
+class Turn:
+    """What the agent did since the user's last prompt."""
+
+    started: datetime | None = None  # None: the prompt was not found
+    tools: list[tuple[str, dict]] = field(default_factory=list)
+
+
+def last_turn(transcript: Path) -> Turn:
+    """Read the transcript backwards up to the last prompt, collecting the tools used after it."""
+    tools: list[tuple[str, dict]] = []
+    for line in reverse_lines(transcript):
+        try:
+            entry = json.loads(line)
+        except ValueError:
+            continue
+        message = entry.get("message") if isinstance(entry, dict) else None
+        content = message.get("content") if isinstance(message, dict) else None
+        if entry.get("type") == "assistant" and isinstance(content, list):
+            for block in reversed(content):
+                if isinstance(block, dict) and block.get("type") == "tool_use":
+                    tool_input = block.get("input")
+                    tools.append((str(block.get("name", "")), tool_input if isinstance(tool_input, dict) else {}))
+        elif entry.get("type") == "user" and not entry.get("isMeta") and is_prompt(content):
+            return Turn(parse_time(entry.get("timestamp")), tools[::-1])
+    return Turn(None, tools[::-1])
+
+
+def is_prompt(content: object) -> bool:
+    """A user entry the person typed (or a notification that starts a turn), not a tool result."""
+    if isinstance(content, str):
+        return True
+    return isinstance(content, list) and bool(content) and not any(
+        isinstance(b, dict) and b.get("type") == "tool_result" for b in content
+    )
+
+
+def parse_time(value: object) -> datetime | None:
+    try:
+        return datetime.fromisoformat(str(value))
+    except ValueError:
+        return None
+
+
+def reverse_lines(path: Path, block: int = 1 << 16) -> Iterator[str]:
+    """The file's lines from last to first, without reading a long transcript whole."""
+    with path.open("rb") as f:
+        position = f.seek(0, os.SEEK_END)
+        rest = b""
+        while position > 0:
+            size = min(block, position)
+            position -= size
+            f.seek(position)
+            lines = (f.read(size) + rest).split(b"\n")
+            rest = lines.pop(0)
+            for line in reversed(lines):
+                if line.strip():
+                    yield line.decode("utf-8", "replace")
+        if rest.strip():
+            yield rest.decode("utf-8", "replace")
+
+
+def changed_since(path: Path, since: datetime | None) -> bool:
+    if since is None:
+        return True  # cannot tell: never nag on a guess
+    try:
+        return path.stat().st_mtime >= since.timestamp()
+    except OSError:
+        return False
+
+
+def stop(cfg: config.Config, session_id: str, payload: dict) -> str:
+    if payload.get("stop_hook_active"):
+        return ""  # this stop already comes from a nudge: never insist twice in a row
+    transcript = payload.get("transcript_path")
+    if not transcript:
+        return ""
+    turn = last_turn(Path(transcript))
+    linked = linked_items(cfg, session_id)
+    if not linked:
+        return untracked(cfg, session_id, turn)
+    if not any(name in WORK_TOOLS and not only_looks(name, tool_input) for name, tool_input in turn.tools):
+        return ""
+    if any(changed_since(item.path, turn.started) for item in linked):
+        return ""
+    if asks_the_user(payload.get("last_assistant_message")):
+        return ""  # the agent waits for an answer (maybe whether to track this); the next reminder follows up
+    return (
+        f"rumo: this turn did work, but no linked item changed ({', '.join(str(i.path) for i in linked)}). "
+        "Update the Steps of the item this work belongs to: check what is done, add what is new or left for "
+        "later, never delete open steps. If the work belongs to none of them, ask the user in one line: track "
+        "it as a new item, add it as a step to one of these, or not track it. If they already chose not to "
+        "track it, or nothing worth recording happened, change nothing. Either way, never repeat or summarize "
+        "your previous answer, and end without any further text."
+    )
+
+
+def only_looks(name: str, tool_input: dict) -> bool:
+    """A Bash call whose every command only reads (ls, git status, ...) and writes no file."""
+    if name != "Bash":
+        return False
+    command = re.sub(r"\d?>\s*/dev/null|\d>&\d", "", str(tool_input.get("command", "")))
+    if ">" in command or re.search(r"\s-(delete|exec|execdir)\b", command):
+        return False
+    for part in re.split(r"&&|\|\||[;|\n]", command):
+        words = [w for w in part.split() if not re.match(r"^\w+=", w)]  # skip FOO=1 prefixes
+        if not words:
+            continue
+        program, rest = words[0], words[1:]
+        if program in LOOK_SUBCOMMANDS:
+            if not rest or rest[0] not in LOOK_SUBCOMMANDS[program]:
+                return False
+        elif program not in LOOK_COMMANDS:
+            return False
+    return True
+
+
+def asks_the_user(answer: object) -> bool:
+    """Whether the agent's final message asks something (any script's question mark)."""
+    return isinstance(answer, str) and any(mark in answer for mark in ("?", "？", "؟"))
+
+
+def untracked(cfg: config.Config, session_id: str, turn: Turn) -> str:
+    """Ask a session without items, once, whether to track it; `ask_to_track` says how often to ask."""
+    folder = cfg.folder.resolve()
+    edited = [
+        Path(str(target)) for name, tool_input in turn.tools if name in EDIT_TOOLS
+        if (target := tool_input.get("file_path") or tool_input.get("notebook_path"))
+    ]
+    if not any(not path.resolve().is_relative_to(folder) for path in edited):
+        return ""  # nothing edited, or only items (an idea noted with /rumo idea)
+
+    state = config.load_state(cfg.path).get("ask_to_track")
+    state = state if isinstance(state, dict) else {}
+    seen = [s for s in state.get("seen", []) if isinstance(s, str)]
+    if session_id in seen:
+        return ""
+    state["seen"] = (seen + [session_id])[-REMEMBERED_SESSIONS:]
+
+    today = date.today()
+    head = "rumo: this session changed files, but no rumo item tracks it. "
+    track = f"should this work be tracked as a rumo item (if yes, {how_to_create()})"
+    message = ""
+    if cfg.ask_to_track is None:
+        message = (
+            head + f"Ask the user once, in one short line in their language: {track}, and should you ask like "
+            "this in future sessions without an item? Record that second answer with `rumo ask-to-track true` "
+            "or `rumo ask-to-track false`. Do not ask again in this session."
+        )
+        state.update(last_asked=today.isoformat(), sessions=0)
+    elif cfg.ask_to_track:
+        message = (
+            head + f"Ask the user once, in one short line in their language: {track}? If they say to stop "
+            "asking, run `rumo ask-to-track false`. Do not ask again in this session."
+        )
+    else:
+        try:
+            last = date.fromisoformat(str(state.get("last_asked")))
+        except ValueError:
+            last = today
+        sessions = state.get("sessions")
+        sessions = (sessions if isinstance(sessions, int) else 0) + 1
+        if sessions >= ASK_AGAIN_SESSIONS or (today - last).days >= ASK_AGAIN_DAYS:
+            message = (
+                head + "The user chose not to be asked; it has been a while, so remind them once that the "
+                f"option exists, in one short line in their language: {track}, and do they want to be asked "
+                "again in sessions without an item? If they do, run `rumo ask-to-track true`; otherwise change "
+                "nothing. Do not ask again in this session."
+            )
+            last, sessions = today, 0
+        state.update(last_asked=last.isoformat(), sessions=sessions)
+    config.update_state(cfg.path, ask_to_track=state)
+    return message
+
+
+def main() -> None:
+    try:
+        payload = json.loads(sys.stdin.buffer.read().decode("utf-8"))
+        session_id = payload.get("session_id", "")
+        event = payload.get("hook_event_name") or "UserPromptSubmit"
+    except (ValueError, OSError, AttributeError):
+        return
+    if not session_id:
+        return
+
+    cfg = config.load()
+    if event == "Stop":
+        try:
+            message = stop(cfg, session_id, payload)
+        except Exception:  # a hook must never break the session; stay silent instead
+            return
+        output = json.dumps({"hookSpecificOutput": {"hookEventName": "Stop", "additionalContext": message}}) if message else ""
+    else:
+        output = reminder(cfg, session_id)
+    if output:
+        sys.stdout.buffer.write(output.encode("utf-8"))
+        sys.stdout.flush()

rumo_cli-0.2.1/src/rumo/hook.py

@@ -1,60 +0,0 @@
-"""Claude Code `UserPromptSubmit` hook: remind a linked session to keep its item up to date.
-
-The link is the session id written in an item's Sessions section (by `/rumo new` or
-`/rumo link`). A line ending in `| closed` (from park/unlink) no longer links, and after
-`/clear` the id changes, so the reminder stops on its own.
-
-The reminder carries the update rules, so they reach the agent exactly when they matter and
-nothing has to be added to the user's global instructions.
-Runs on every prompt: stdlib only, UTF-8 regardless of the console, silent on anything unexpected.
-"""
-
-from __future__ import annotations
-
-import json
-import sys
-
-from rumo import config, items
-
-RULES = (
-    "Steps are what matters. Before you finish this response, if any work happened, edit the item "
-    "with the Edit tool: in Steps, check what is done, add a step for anything new or left for later "
-    "(`- [ ] [agent] ...`, or `- [ ] [manual] ...` for what the user or someone else does), reword steps "
-    "that changed, and keep the very next action as the first open step. One short line per step, "
-    "starting with a verb. Then set `updated`; rewrite Left off (one line: where it stands or what "
-    "blocks it) only if that changed, and keep Context to at most 3 lines. Conversation-only replies "
-    "need no update. Write content in the configured language (`rumo index`); keep keys, sections, "
-    "statuses and tags in English. Never set `done` without every step checked and the user's "
-    "confirmation. To stop updating from this session, append `| closed` to its line in Sessions."
-)
-SHOWN_STEPS = 3
-
-
-def open_steps(item: items.Item) -> str:
-    """The next open steps, so the agent sees what to check off without opening the file."""
-    pending = [s for s in item.steps if not s.done]
-    if not pending:
-        return "Open steps: none."
-    shown = [(f"[{s.kind}] " if s.kind else "") + (s.text if len(s.text) <= 80 else s.text[:79] + "…") for s in pending[:SHOWN_STEPS]]
-    more = len(pending) - SHOWN_STEPS
-    return "Open steps: " + "; ".join(shown + ([f"(+{more} more)"] if more > 0 else [])) + "."
-
-
-def main() -> None:
-    try:
-        payload = json.loads(sys.stdin.buffer.read().decode("utf-8"))
-        session_id = payload.get("session_id", "")
-    except (ValueError, OSError, AttributeError):
-        return
-    if not session_id:
-        return
-
-    linked = []
-    for item in items.list_items(config.load().folder):
-        if any(s.id == session_id and not s.closed for s in item.sessions):
-            linked.append(f"{item.path} (status: {item.status}). {open_steps(item)}")
-
-    if linked:
-        message = "This session is linked to rumo item(s): " + " ".join(linked) + " " + RULES + "\n"
-        sys.stdout.buffer.write(message.encode("utf-8"))
-        sys.stdout.flush()