scootcli 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scootcli
-Version: 0.3.0
+Version: 0.5.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:
 
 ```
@@ -196,6 +206,8 @@ scoot --no-panel --no-dock           # plain prompt, no status bar (also what yo
 /model     list or switch model     /approve   set mode (always|auto-read|auto-edits|yolo)
 /yolo      auto-approve all         /worktree  isolate work in a git worktree
 /auth      provider keys            /logo      show or toggle the mascot
+/scope     where file tools may go   /hooks     configured hooks and results
+/route     how auto picks a model
 /sessions  list saved sessions      /resume    resume a saved session ([id])
 /forget    delete session(s)        /panel     toggle the bottom status bar
 /verbosity feed detail (full|compact|quiet)
@@ -213,7 +225,11 @@ Without a TTY, scoot falls back to a plain prompt with no bar and no dock.
 ### Tools and approvals
 
 The agent has eight tools: `read_file`, `list_dir`, `search`, `write_file`, `edit_file`, `run_shell`, `open_editor` (hands a file to IntelliJ IDEA's `idea -e` or to VS Code, `SCOOT_EDITOR` picks), and `update_plan` (a progress checklist for multi-step work).
-Every tool is sandboxed to the workspace root.
+Paths are resolved against the workspace root, and `~` works.
+
+The workspace is where the agent works, not a wall.
+When a tool needs a file outside it, in `~/.config`, another repo, `/etc`, scoot asks once: allow this path `[a]`, allow that directory for the session `[d]`, allow anywhere for the session `[A]`, skip `[s]`, or quit `[q]`.
+`--scope anywhere`, `SCOOT_SCOPE=anywhere`, or `/scope anywhere` skip the question; `/scope` shows what has been granted.
 
 When a call needs approval you can approve once `[a]`, trust that tool for the session `[t]`, approve everything this session `[A]`, edit the arguments `[e]`, skip `[s]`, or quit `[q]`.
 `/approve <mode>` sets how much runs without asking: `always` prompts for everything, `auto-read` auto-approves reads, `auto-edits` also auto-approves file edits, `yolo` runs everything.
@@ -227,6 +243,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 +273,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 +281,9 @@ 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.
+**Upgrading.** `pipx upgrade scootcli`, or `pip install --upgrade scootcli`, or rerun the curl line, which always fetches the latest release; `scoot --version` shows what you have.
+
+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.5.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:
 
 ```
@@ -171,6 +181,8 @@ scoot --no-panel --no-dock           # plain prompt, no status bar (also what yo
 /model     list or switch model     /approve   set mode (always|auto-read|auto-edits|yolo)
 /yolo      auto-approve all         /worktree  isolate work in a git worktree
 /auth      provider keys            /logo      show or toggle the mascot
+/scope     where file tools may go   /hooks     configured hooks and results
+/route     how auto picks a model
 /sessions  list saved sessions      /resume    resume a saved session ([id])
 /forget    delete session(s)        /panel     toggle the bottom status bar
 /verbosity feed detail (full|compact|quiet)
@@ -188,7 +200,11 @@ Without a TTY, scoot falls back to a plain prompt with no bar and no dock.
 ### Tools and approvals
 
 The agent has eight tools: `read_file`, `list_dir`, `search`, `write_file`, `edit_file`, `run_shell`, `open_editor` (hands a file to IntelliJ IDEA's `idea -e` or to VS Code, `SCOOT_EDITOR` picks), and `update_plan` (a progress checklist for multi-step work).
-Every tool is sandboxed to the workspace root.
+Paths are resolved against the workspace root, and `~` works.
+
+The workspace is where the agent works, not a wall.
+When a tool needs a file outside it, in `~/.config`, another repo, `/etc`, scoot asks once: allow this path `[a]`, allow that directory for the session `[d]`, allow anywhere for the session `[A]`, skip `[s]`, or quit `[q]`.
+`--scope anywhere`, `SCOOT_SCOPE=anywhere`, or `/scope anywhere` skip the question; `/scope` shows what has been granted.
 
 When a call needs approval you can approve once `[a]`, trust that tool for the session `[t]`, approve everything this session `[A]`, edit the arguments `[e]`, skip `[s]`, or quit `[q]`.
 `/approve <mode>` sets how much runs without asking: `always` prompts for everything, `auto-read` auto-approves reads, `auto-edits` also auto-approves file edits, `yolo` runs everything.
@@ -202,6 +218,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 +248,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 +256,9 @@ 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.
+**Upgrading.** `pipx upgrade scootcli`, or `pip install --upgrade scootcli`, or rerun the curl line, which always fetches the latest release; `scoot --version` shows what you have.
+
+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.5.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.5.0"
 

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

@@ -70,6 +70,12 @@ class HeadlessUI:
         self.events.append(("approve", tool.name, args))
         return Approval(self.decision, args)
 
+    scope_decision = "dir"  # what this headless UI answers to a scope question (tests override)
+
+    def approve_scope(self, tool, path, ctx) -> str:
+        self.events.append(("scope", tool.name, str(path)))
+        return self.scope_decision
+
     def auto_approved(self, tool, args) -> None:
         self.events.append(("auto", tool.name, args))
 
@@ -97,6 +103,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 +151,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 +194,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 +288,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,
@@ -292,7 +351,16 @@ class Agent:
     # ── tool execution ───────────────────────────────────────────────────────────
     def _run_tools(self, session, tool_calls, ui, cancel_event, cfg=None) -> Optional[str]:
         cfg = cfg or getattr(session, "config", None) or self.config
-        ctx = ToolContext(root=cfg.root, config=cfg, cancel_event=cancel_event)
+        scope = getattr(session, "scope", None)
+        if scope is None:
+            from .tools.base import Scope
+
+            scope = Scope(cfg.root, everything=(getattr(cfg, "scope", "workspace") == "anywhere"))
+            try:
+                session.scope = scope
+            except Exception:
+                pass
+        ctx = ToolContext(root=cfg.root, config=cfg, cancel_event=cancel_event, scope=scope)
         mode = getattr(session, "approval_mode", "always")
         # Session trust-list: tools the user chose to auto-approve for the rest of the session.
         trusted = getattr(session, "trusted_tools", None)
@@ -315,11 +383,36 @@ class Agent:
                 self._append_tool(session, tc_id, f"error: unknown tool '{name}'")
                 continue
 
+            # Paths outside the workspace: ask the user once (this path, its directory, or anywhere).
+            outside = self._outside_paths(tool, args, ctx)
+            if outside:
+                verdict = self._ask_scope(session, tool, outside, ctx, ui)
+                if verdict == "abort":
+                    self._append_tool(session, tc_id, "user aborted the operation")
+                    return "abort"
+                if verdict == "deny":
+                    self._append_tool(session, tc_id, f"user declined access outside the workspace: {outside[0]}")
+                    ui.tool_result(name, ToolResult(ok=False, summary="outside the workspace: declined"))
+                    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,10 +440,51 @@ 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
 
+    @staticmethod
+    def _outside_paths(tool, args, ctx) -> "list":
+        from .tools.base import resolve_path
+
+        scope = ctx.scope
+        found = []
+        for raw in tool.paths(args):
+            try:
+                p = resolve_path(ctx.root, raw)
+            except Exception:
+                continue
+            if scope is None or not scope.allows(p):
+                found.append(p)
+        return found
+
+    def _ask_scope(self, session, tool, paths, ctx, ui) -> str:
+        """Ask for the first outside path; grant per the answer. Returns once|dir|all|deny|abort."""
+        scope = ctx.scope
+        if getattr(session, "config", None) is not None and getattr(session.config, "scope", "") == "anywhere":
+            scope.grant_all()
+            return "all"
+        asker = getattr(ui, "approve_scope", None)
+        if asker is None:
+            return "deny"
+        from .hooks import notify
+
+        notify(session, "scope", f"{tool.name} wants {paths[0]} outside the workspace")
+        verdict = asker(tool, paths[0], ctx)
+        if verdict == "once":
+            for p in paths:
+                scope.grant(p)
+        elif verdict == "dir":
+            for p in paths:
+                scope.grant_dir(p)
+            ui.assistant(f"allowing {scope.granted[-1]} for the rest of this session.")
+        elif verdict == "all":
+            scope.grant_all()
+            ui.assistant("allowing access anywhere on this machine for the rest of this session.")
+        return verdict
+
     @staticmethod
     def _handle_result(session, name: str, result: ToolResult, ui) -> None:
         """Surface a tool result: render a plan update specially, else the generic result line."""

{scootcli-0.3.0 → scootcli-0.5.0}/src/scootcli/approvals.py

@@ -126,6 +126,40 @@ def _edit_args(args: dict) -> dict:
     return args
 
 
+SCOPE_CHOICES = ("once", "dir", "all", "deny", "abort")
+
+
+def request_scope(tool: Tool, path, ctx: ToolContext) -> str:
+    """Ask once about a path outside the workspace. Returns one of ``SCOPE_CHOICES``."""
+    from pathlib import Path as _P
+
+    p = _P(str(path))
+    where = p if p.is_dir() else p.parent
+    print(color(f"  ⌂ {tool.name} wants {p}", "yellow") + color("  (outside the workspace)", "gray"))
+    while True:
+        print(
+            "  "
+            + color("allow this path", "green") + " [a]  "
+            + color(f"allow {where} this session", "green") + " [d]  "
+            + color("allow anywhere this session", "green") + " [A]  "
+            + color("skip", "yellow") + " [s]  "
+            + color("quit", "red") + " [q] › ",
+            end="", flush=True,
+        )
+        key = read_key()
+        print(key)
+        if key in ("a", "y", "\r", "\n", ""):
+            return "once"
+        if key == "d":
+            return "dir"
+        if key == "A":
+            return "all"
+        if key == "s":
+            return "deny"
+        if key == "q":
+            return "abort"
+
+
 def request_approval(tool: Tool, args: dict, ctx: ToolContext) -> Approval:
     """Show the pending tool call and read the user's decision (with optional arg editing)."""
     while True:

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

@@ -59,6 +59,10 @@ 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("--scope", choices=["workspace", "anywhere"],
+                        help="Where file tools may go: workspace (default; the first access outside it asks once) or anywhere.")
+    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",
@@ -90,6 +94,7 @@ def _config_from_args(args: argparse.Namespace) -> Config:
         proxy=args.proxy,
         root=args.root,
         approval="yolo" if (args.yolo or args.yes) else args.approval,
+        scope="anywhere" if args.yes else args.scope,
         verbose=True if args.verbose else None,
         stream=False if args.no_stream else None,
         panel=False if args.no_panel else None,
@@ -154,6 +159,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 +182,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 +231,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 +282,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.5.0}/src/scootcli/commands/__init__.py

@@ -52,6 +52,8 @@ 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
+    from . import scope as _scope  # noqa: F401
 
     _loaded = True
 

{scootcli-0.3.0 → scootcli-0.5.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.5.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.5.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]"))