scootcli 0.3.0__tar.gz → 0.4.0__tar.gz

{scootcli-0.3.0/src/scootcli.egg-info → scootcli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scootcli
-Version: 0.3.0
+Version: 0.4.0
 Summary: A tiny coding agent that goes where you point it
 Author: Sergey Nes
 License-Expression: MIT
@@ -61,12 +61,19 @@ The naive version did real work in my repos for long enough that the next step w
 ## Quick start
 
 ```bash
-pipx install scootcli            # or: pip install scootcli
+pipx install scootcli && pipx ensurepath   # then open a new terminal so `scoot` is on PATH
 scoot auth set openai            # paste your OpenAI API key once (hidden input, validated, stored 0600)
 cd ~/code/your-project
 scoot                            # open the REPL
 ```
 
+No pipx yet? On Debian, Ubuntu, and Pop!_OS it is `sudo apt install pipx`; on macOS `brew install pipx`.
+Or skip pipx entirely with the one-line installer, which needs only `curl` and Python 3.9+:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash
+```
+
 Or run entirely local with [Ollama](https://ollama.com), no key at all:
 
 ```bash
@@ -74,6 +81,9 @@ ollama pull llama3.2
 scoot --model ollama/llama3.2
 ```
 
+**First run.** With no key saved and no Ollama running, scoot still opens: the banner says "no provider set up yet", a short block lists the three ways to set one up, and the bar shows `not set up` until a provider can answer.
+Run `scoot auth set openai` (or `anthropic`) inside the REPL and the bar switches to the real provider and model at once.
+
 The first prompt:
 
 ```
@@ -227,6 +237,29 @@ Responses stream live and stay interruptible.
 Drag an image into the prompt and a vision-capable model describes it into the turn as text, so even a text-only coding model can act on it; `SCOOT_VISION_MODEL` pins the describer, `--no-images` turns the feature off.
 Every turn auto-saves under `~/.local/state/scoot/sessions/` (owner-only, secrets redacted, last 20 kept); `scoot --continue` or `/resume` picks up where you left off.
 
+### Automation: hooks and headless mode
+
+**Hooks** run your own scripts at lifecycle events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `Notification`, `SessionEnd`.
+A hook gets a JSON payload on stdin and answers with an exit code or JSON on stdout; the shapes follow the convention Claude Code established, so a script written for one works with the other.
+Put them in `~/.config/scoot/hooks.json` or `.scoot/hooks.json` in the project:
+
+```json
+{
+  "PreToolUse": [
+    {"matcher": "run_shell|write_file|edit_file", "hooks": [{"type": "command", "command": "~/bin/guard.py", "timeout": 30}]}
+  ],
+  "Stop": [{"hooks": [{"type": "command", "command": "~/bin/notify.sh"}]}]
+}
+```
+
+A `PreToolUse` hook can answer `{"permissionDecision": "deny", "reason": "..."}` to skip a tool (the model is told why), `allow` to skip the approval prompt, or `ask` to force one even in `yolo`; exit code 2 denies with stderr as the reason.
+A `Stop` hook that answers `{"decision": "block", "reason": "run the tests first"}` sends the agent back to work with that instruction, at most three times per turn.
+`/hooks` shows what is configured and what ran; `SCOOT_HOOKS=0` turns hooks off.
+
+**Headless mode** is for editors, automation, and remote-control tools: `scoot --headless` reads JSON lines on stdin (`prompt`, `approve`, `note`, `interrupt`, `command`, `shutdown`) and writes JSON lines on stdout (streamed text, tool calls, approval requests, results, plan updates, usage, errors, a heartbeat), with nothing else ever printed there.
+Same sessions, tools, approvals, routing, and hooks as the REPL.
+The message tables and a full transcript are in [`docs/headless-protocol.md`](./docs/headless-protocol.md); an unanswered approval is denied after `SCOOT_APPROVAL_TIMEOUT` seconds (default 120).
+
 ### The status bar
 
 The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `> >` thinking, `- -` stopped), the provider, the workspace and session id, the model, the approval mode, context size against the auto-compact threshold, cumulative tokens, message count, and the last error if any.
@@ -234,7 +267,7 @@ The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `>
 ## Install options
 
 ```bash
-pipx install scootcli                          # recommended: isolated, `scoot` on PATH
+pipx install scootcli && pipx ensurepath       # recommended: isolated; ensurepath puts ~/.local/bin on PATH for new shells
 curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash   # no pipx: puts the zipapp at ~/.local/bin/scoot
 pip install scootcli                           # anywhere
 curl -LO https://github.com/sergenes/scootcli/releases/latest/download/scoot.pyz && python3 scoot.pyz  # single file, no install
@@ -242,6 +275,7 @@ git clone https://github.com/sergenes/scootcli && cd scootcli && pip install -e
 ```
 
 The install script needs only `curl` and Python 3.9+. `SCOOT_VERSION=v0.2.0` pins a release and `SCOOT_INSTALL_DIR` changes the target; read it before you run it, it is sixty lines.
+Both pipx and the script install into `~/.local/bin`. On a fresh Linux account that directory is added to PATH at login only if it already exists, so after the very first install either open a new login shell or run `pipx ensurepath`; the installer prints the exact line for your shell.
 
 Requirements: Python 3.9 or newer on macOS or Linux.
 Nothing else: no compiler, no packages, no `curl`.

{scootcli-0.3.0 → scootcli-0.4.0}/README.md

@@ -36,12 +36,19 @@ The naive version did real work in my repos for long enough that the next step w
 ## Quick start
 
 ```bash
-pipx install scootcli            # or: pip install scootcli
+pipx install scootcli && pipx ensurepath   # then open a new terminal so `scoot` is on PATH
 scoot auth set openai            # paste your OpenAI API key once (hidden input, validated, stored 0600)
 cd ~/code/your-project
 scoot                            # open the REPL
 ```
 
+No pipx yet? On Debian, Ubuntu, and Pop!_OS it is `sudo apt install pipx`; on macOS `brew install pipx`.
+Or skip pipx entirely with the one-line installer, which needs only `curl` and Python 3.9+:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash
+```
+
 Or run entirely local with [Ollama](https://ollama.com), no key at all:
 
 ```bash
@@ -49,6 +56,9 @@ ollama pull llama3.2
 scoot --model ollama/llama3.2
 ```
 
+**First run.** With no key saved and no Ollama running, scoot still opens: the banner says "no provider set up yet", a short block lists the three ways to set one up, and the bar shows `not set up` until a provider can answer.
+Run `scoot auth set openai` (or `anthropic`) inside the REPL and the bar switches to the real provider and model at once.
+
 The first prompt:
 
 ```
@@ -202,6 +212,29 @@ Responses stream live and stay interruptible.
 Drag an image into the prompt and a vision-capable model describes it into the turn as text, so even a text-only coding model can act on it; `SCOOT_VISION_MODEL` pins the describer, `--no-images` turns the feature off.
 Every turn auto-saves under `~/.local/state/scoot/sessions/` (owner-only, secrets redacted, last 20 kept); `scoot --continue` or `/resume` picks up where you left off.
 
+### Automation: hooks and headless mode
+
+**Hooks** run your own scripts at lifecycle events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `Notification`, `SessionEnd`.
+A hook gets a JSON payload on stdin and answers with an exit code or JSON on stdout; the shapes follow the convention Claude Code established, so a script written for one works with the other.
+Put them in `~/.config/scoot/hooks.json` or `.scoot/hooks.json` in the project:
+
+```json
+{
+  "PreToolUse": [
+    {"matcher": "run_shell|write_file|edit_file", "hooks": [{"type": "command", "command": "~/bin/guard.py", "timeout": 30}]}
+  ],
+  "Stop": [{"hooks": [{"type": "command", "command": "~/bin/notify.sh"}]}]
+}
+```
+
+A `PreToolUse` hook can answer `{"permissionDecision": "deny", "reason": "..."}` to skip a tool (the model is told why), `allow` to skip the approval prompt, or `ask` to force one even in `yolo`; exit code 2 denies with stderr as the reason.
+A `Stop` hook that answers `{"decision": "block", "reason": "run the tests first"}` sends the agent back to work with that instruction, at most three times per turn.
+`/hooks` shows what is configured and what ran; `SCOOT_HOOKS=0` turns hooks off.
+
+**Headless mode** is for editors, automation, and remote-control tools: `scoot --headless` reads JSON lines on stdin (`prompt`, `approve`, `note`, `interrupt`, `command`, `shutdown`) and writes JSON lines on stdout (streamed text, tool calls, approval requests, results, plan updates, usage, errors, a heartbeat), with nothing else ever printed there.
+Same sessions, tools, approvals, routing, and hooks as the REPL.
+The message tables and a full transcript are in [`docs/headless-protocol.md`](./docs/headless-protocol.md); an unanswered approval is denied after `SCOOT_APPROVAL_TIMEOUT` seconds (default 120).
+
 ### The status bar
 
 The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `> >` thinking, `- -` stopped), the provider, the workspace and session id, the model, the approval mode, context size against the auto-compact threshold, cumulative tokens, message count, and the last error if any.
@@ -209,7 +242,7 @@ The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `>
 ## Install options
 
 ```bash
-pipx install scootcli                          # recommended: isolated, `scoot` on PATH
+pipx install scootcli && pipx ensurepath       # recommended: isolated; ensurepath puts ~/.local/bin on PATH for new shells
 curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash   # no pipx: puts the zipapp at ~/.local/bin/scoot
 pip install scootcli                           # anywhere
 curl -LO https://github.com/sergenes/scootcli/releases/latest/download/scoot.pyz && python3 scoot.pyz  # single file, no install
@@ -217,6 +250,7 @@ git clone https://github.com/sergenes/scootcli && cd scootcli && pip install -e
 ```
 
 The install script needs only `curl` and Python 3.9+. `SCOOT_VERSION=v0.2.0` pins a release and `SCOOT_INSTALL_DIR` changes the target; read it before you run it, it is sixty lines.
+Both pipx and the script install into `~/.local/bin`. On a fresh Linux account that directory is added to PATH at login only if it already exists, so after the very first install either open a new login shell or run `pipx ensurepath`; the installer prints the exact line for your shell.
 
 Requirements: Python 3.9 or newer on macOS or Linux.
 Nothing else: no compiler, no packages, no `curl`.

{scootcli-0.3.0 → scootcli-0.4.0}/src/scootcli/__init__.py

@@ -1,4 +1,4 @@
 """scoot: a tiny coding agent that goes where you point it."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 

{scootcli-0.3.0 → scootcli-0.4.0}/src/scootcli/agent.py

@@ -97,6 +97,7 @@ class Agent:
         self._refresh_workspace(session, cfg)
         steps = 0
         compacted = False
+        stop_blocks = 0
         while True:
             if cancel_event.is_set():
                 return AgentOutcome("interrupted", steps=steps)
@@ -144,10 +145,16 @@ class Agent:
                     return AgentOutcome(status, steps=steps)
                 continue
 
-            # No tool calls -> the model is done.
-            return AgentOutcome(
-                "done", content=_strip_done(result.content), steps=steps, streamed=streamed
-            )
+            # No tool calls -> the model is done, unless a Stop hook asks for more (bounded).
+            content = _strip_done(result.content)
+            if stop_blocks < 3:
+                reason = self._stop_hook(session, content, steps)
+                if reason:
+                    stop_blocks += 1
+                    session.messages.append({"role": "user", "content": reason})
+                    ui.assistant(f"continuing: {reason}")
+                    continue
+            return AgentOutcome("done", content=content, steps=steps, streamed=streamed)
 
     # ── model call (streaming or buffered) ───────────────────────────────────────
     def _model_call(self, session, cfg, ui, cancel_event, steps):
@@ -181,6 +188,45 @@ class Agent:
             )
         return result, False
 
+    # ── hooks ────────────────────────────────────────────────────────────────────
+    @staticmethod
+    def _hooks(session):
+        from .hooks import for_session
+
+        return for_session(session)
+
+    def _stop_hook(self, session, content: str, steps: int) -> str:
+        hooks = self._hooks(session)
+        if hooks is None or not hooks.has("Stop"):
+            return ""
+        payload = hooks.payload(session, "Stop", last_assistant_message=content, steps=steps,
+                                usage=getattr(session, "last_usage", {}) or {})
+        decision = hooks.run("Stop", payload)
+        return (decision.reason or "the Stop hook asked to continue") if decision.blocks else ""
+
+    def _pre_tool_hook(self, session, tool, args, cancel_event) -> "tuple[str, str]":
+        hooks = self._hooks(session)
+        if hooks is None or not hooks.has("PreToolUse"):
+            return "", ""
+        from .hooks import tool_kind
+
+        payload = hooks.payload(session, "PreToolUse", tool_name=tool.name, tool_input=args,
+                                tool_kind=tool_kind(tool))
+        decision = hooks.run("PreToolUse", payload, cancel_event)
+        return decision.action, decision.reason
+
+    def _post_tool_hook(self, session, tool, args, result: ToolResult) -> None:
+        hooks = self._hooks(session)
+        if hooks is None or not hooks.has("PostToolUse"):
+            return
+        from .hooks import tool_kind
+
+        response = {"ok": result.ok, "summary": result.summary or "", "error": result.error or "",
+                    "content": (result.content or "")[:4000]}
+        hooks.run("PostToolUse", hooks.payload(session, "PostToolUse", tool_name=tool.name,
+                                               tool_input=args, tool_kind=tool_kind(tool),
+                                               tool_response=response))
+
     @staticmethod
     def _last_user_text(session) -> str:
         for m in reversed(getattr(session, "messages", []) or []):
@@ -236,6 +282,13 @@ class Agent:
 
     def _messages(self, session, cfg=None) -> List[dict]:
         cfg = cfg or getattr(session, "config", None) or self.config
+        notes = getattr(session, "pending_notes", None)
+        if notes:
+            joined = "\n".join(n for n in notes if n)
+            notes.clear()
+            if joined:
+                session.messages.append({"role": "user",
+                                         "content": "Note from the user while you work:\n" + joined})
         system = build_agent_system_prompt(
             root=cfg.root,
             model=session.active_model,
@@ -315,11 +368,25 @@ class Agent:
                 self._append_tool(session, tc_id, f"error: unknown tool '{name}'")
                 continue
 
+            # A PreToolUse hook may deny (skip the tool), allow (skip the prompt), or ask (force it).
+            hook_action, hook_reason = self._pre_tool_hook(session, tool, args, cancel_event)
+            if hook_action == "deny":
+                self._append_tool(session, tc_id, f"user declined via hook: {hook_reason or 'no reason given'}")
+                ui.tool_result(name, ToolResult(ok=False, summary=f"denied by hook: {hook_reason}"[:80]))
+                continue
             # Approval policy: auto-approve when the mode/trust allows it, else prompt.
-            if needs_prompt(mode, tool, args, trusted) is None:
+            must_prompt = needs_prompt(mode, tool, args, trusted)
+            if hook_action == "allow":
+                must_prompt = None
+            elif hook_action == "ask":
+                must_prompt = hook_reason or "hook asked for confirmation"
+            if must_prompt is None:
                 if not getattr(tool, "auto_approve", False):
                     ui.auto_approved(tool, args)  # meta tools render their own output
             else:
+                from .hooks import notify
+
+                notify(session, "approval", f"{name} needs approval: {must_prompt}")
                 approval = ui.approve(tool, args, ctx)
                 if approval.decision == Decision.ABORT:
                     self._append_tool(session, tc_id, "user aborted the operation")
@@ -347,6 +414,7 @@ class Agent:
                 result = ToolResult.fail(f"tool crashed: {exc}")
 
             self._handle_result(session, name, result, ui)
+            self._post_tool_hook(session, tool, args, result)
             payload = result.content if result.ok else f"ERROR: {result.error}"
             self._append_tool(session, tc_id, payload or "(no output)")
         return None

{scootcli-0.3.0 → scootcli-0.4.0}/src/scootcli/cli.py

@@ -59,6 +59,8 @@ def _build_parser() -> argparse.ArgumentParser:
                         help="Don't inject the repo map (git + file tree) into the agent prompt.")
     parser.add_argument("--no-labels", action="store_true",
                         help="Hide the role labels/gutters (❯ you / ⏺ scoot) in the REPL transcript.")
+    parser.add_argument("--headless", action="store_true",
+                        help="Line-delimited JSON on stdin/stdout instead of the REPL (see docs/headless-protocol.md).")
     parser.add_argument("--no-logo", action="store_true",
                         help="Hide the mascot (launch banner art + status-bar face). Persist with /logo off.")
     parser.add_argument("--no-emoji", action="store_true",
@@ -154,6 +156,17 @@ def _run_once(config: Config, pool: ProviderPool, prompt: str, as_json: bool, re
     session = ReplSession(config, pool)
     if resume is not None:
         session.apply_record(resume)
+    from .hooks import Hooks, session_event, submit_prompt
+
+    session.hooks = Hooks(config.root)
+    session_event(session, "SessionStart", source="resume" if resume is not None else "startup")
+    submitted = submit_prompt(session, prompt)
+    if submitted is None:
+        reason = getattr(session, "hook_block_reason", "") or "a UserPromptSubmit hook blocked it"
+        eprint(color(f"⏹ prompt not sent: {reason}", "yellow"))
+        session_event(session, "SessionEnd", reason="blocked")
+        return 1
+    prompt = submitted
     # Fold any dropped image paths into the prompt (best-effort; no-op when none/disabled).
     try:
         from .vision import fold_images_into_text
@@ -166,6 +179,7 @@ def _run_once(config: Config, pool: ProviderPool, prompt: str, as_json: bool, re
     agent_config = config.override(stream=False) if as_json else config
     outcome = Agent(agent_config, pool).run_turn(session, ReplUI(), threading.Event())
     session.autosave()  # persist so `scoot -c` can continue this conversation
+    session_event(session, "SessionEnd", reason=outcome.status)
 
     if as_json:
         print(_json.dumps({
@@ -214,14 +228,8 @@ def _interactive(pool: ProviderPool, resume=None) -> int:
 
         resume = sessions.latest_for_root(str(config.root))
 
-    try:
-        from .providers.registry import readiness
-
-        ready, message = readiness(config)
-        if not ready:  # first-run onboarding: guide, but still open the REPL so /auth is usable
-            eprint(color(message, "yellow"))
-    except ScootError as exc:
-        eprint(color(f"⚠ {redact(str(exc))}", "yellow"))
+    # First-run onboarding happens inside the REPL (banner + a setup block), because anything printed
+    # here would be wiped by the screen clear the REPL does on start.
     return Repl(config, pool, resume=resume).run()
 
 
@@ -271,6 +279,13 @@ def main(argv: Optional[List[str]] = None) -> int:
 
         prompt = _resolve_prompt(args)
         resume = _resolve_resume(config, args)
+        if args.headless:
+            if prompt is not None:
+                eprint(color("--headless takes prompts on stdin, not as an argument.", "yellow"))
+                return 2
+            from .headless import run_headless
+
+            return run_headless(config.override(panel=False, dock=False, logo=False), pool, resume=resume)
         if prompt is not None:
             return _run_once(config, pool, prompt, args.json, resume=resume)
         return _interactive(pool, resume=resume)

{scootcli-0.3.0 → scootcli-0.4.0}/src/scootcli/commands/__init__.py

@@ -52,6 +52,7 @@ def load_builtins() -> None:
     from . import copy as _copy  # noqa: F401
     from . import logo as _logo  # noqa: F401
     from . import route as _route  # noqa: F401
+    from . import hooks as _hooks  # noqa: F401
 
     _loaded = True
 

{scootcli-0.3.0 → scootcli-0.4.0}/src/scootcli/commands/auth.py

@@ -69,6 +69,7 @@ def _set(session, name: str) -> None:
     if pool is not None and hasattr(pool, "_providers"):
         pool._providers.pop(name, None)  # rebuild with the new key on next use
     print(color(f"✔ {name} key saved to {path} (owner-only).", "green"))
+    _after_change(session)
 
 
 def _clear(session, name: str) -> None:
@@ -80,6 +81,7 @@ def _clear(session, name: str) -> None:
         print(color(f"forgot the saved {name} key.", "green"))
     else:
         print(color(f"no saved {name} key.", "gray"))
+    _after_change(session)
     pool = getattr(session, "provider", None)
     if pool is not None and hasattr(pool, "_providers"):
         pool._providers.pop(name, None)
@@ -90,6 +92,20 @@ def _clear(session, name: str) -> None:
         print(color(f"  {missing_key_hint(spec)}", "gray"))
 
 
+def _after_change(session) -> None:
+    """A key came or went: the default provider may have changed, so re-resolve and re-check."""
+    try:
+        if session.model.lower() in ("default", "auto"):
+            session.active_model = session.resolved_model()
+        session._available = None  # the model list depends on which providers are configured
+        if session.refresh_readiness():
+            print(color(f"ready: {session.active_model}", "gray"))
+        else:
+            print(color(session.setup_message, "yellow"))
+    except Exception:
+        pass
+
+
 def _run(session, args: str):
     words = (args or "").split()
     if not words:

scootcli-0.4.0/src/scootcli/commands/hooks.py

@@ -0,0 +1,37 @@
+"""/hooks — list the configured hooks and what they did last."""
+
+from __future__ import annotations
+
+from ..hooks import EVENTS, enabled, global_path, project_path
+from ..rendering import color
+from . import register
+from .base import SlashCommand
+
+
+def _run(session, args: str):
+    hooks = getattr(session, "hooks", None)
+    if (args or "").strip() == "reload" and hooks is not None:
+        hooks.reload()
+        print(color("hooks reloaded.", "gray"))
+    print(color("hooks:", "bold"))
+    if not enabled():
+        print(color("  disabled by SCOOT_HOOKS=0", "yellow"))
+    root = getattr(getattr(session, "config", None), "root", ".")
+    print(color(f"  files: {project_path(root)} (project), {global_path()} (global)", "gray"))
+    if hooks is None or not hooks.config:
+        print(color("  none configured", "gray"))
+    else:
+        for event in EVENTS:
+            for entry in hooks.config.get(event, []):
+                matcher = f"  [{entry['matcher']}]" if entry.get("matcher") else ""
+                for hook in entry.get("hooks", []):
+                    print(f"  {color(event, 'cyan')}{matcher}  {hook.get('command', '')}")
+        if hooks.history:
+            print(color("  recent:", "gray"))
+            for r in hooks.history[-8:]:
+                detail = f"  {r.detail[:60]}" if r.detail else ""
+                print(f"    {r.event:<16} {r.outcome:<8} {r.seconds:>5.2f}s  {r.command[:40]}{detail}")
+    print(color("  usage: /hooks [reload]", "gray"))
+
+
+register(SlashCommand("hooks", "list configured hooks and recent results", _run, usage="[reload]"))

{scootcli-0.3.0 → scootcli-0.4.0}/src/scootcli/commands/model.py

@@ -40,6 +40,8 @@ def _run(session, args: str):
         set_model(arg)
         what = "picked per task from the live list" if arg == "auto" else f"the provider's preferred model, now {session.active_model}"
         print(color(f"model preference set to {arg} ({what}); saved for next launch.", "gray"))
+        if hasattr(session, "refresh_readiness") and not session.refresh_readiness():
+            print(color(session.setup_message, "yellow"))
         return
 
     if arg not in available:
@@ -55,6 +57,8 @@ def _run(session, args: str):
     session.active_model = arg
     set_model(arg)
     print(color(f"model set to {arg}; saved for next launch.", "gray"))
+    if hasattr(session, "refresh_readiness") and not session.refresh_readiness():
+        print(color(session.setup_message, "yellow"))
 
 
 register(SlashCommand("model", "list or switch model (default|auto|provider/model)", _run, usage="[provider/model|default|auto]"))

{scootcli-0.3.0 → scootcli-0.4.0}/src/scootcli/commands/reset.py

@@ -9,6 +9,9 @@ from .base import SlashCommand
 
 def _run(session, args: str):
     session.reset()
+    from ..hooks import session_event
+
+    session_event(session, "SessionStart", source="reset")
     redraw = getattr(session, "redraw_home", None)
     if callable(redraw):
         redraw("fresh session — conversation + context cleared.")