ws-aitoolkit 0.1.1__tar.gz → 0.1.2__tar.gz

{ws_aitoolkit-0.1.1 → ws_aitoolkit-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ws-aitoolkit
-Version: 0.1.1
+Version: 0.1.2
 Summary: Your memory, skills and rules, in any AI.
 Author: Michael Fry
 License-Expression: Apache-2.0
@@ -61,6 +61,15 @@ questions, or `ws setup` to go step by step. `ws doctor --json` gives the same r
 
 To follow a whole first session, see the [first-run tutorial](docs/tutorials/first-run.md).
 
+## Skills
+
+`ws install` puts six skills in your runner's skills folder: `align`, `checkpoint`, `taste-gate`, `dataviz`, `resume`
+and `ship`. `ws skills` lists them per runner. A skill you already have under one of those names stays as it is.
+
+To use ws's version of a name you already have, run `ws skills adopt NAME`. Yours moves to
+`$WS_HOME/backups/skills/<runner>/` and ws installs its own. `ws skills restore NAME` takes ws's copy out and moves yours
+back.
+
 ## Verify
 
 Check which build you have:

{ws_aitoolkit-0.1.1 → ws_aitoolkit-0.1.2}/README.md

@@ -44,6 +44,15 @@ questions, or `ws setup` to go step by step. `ws doctor --json` gives the same r
 
 To follow a whole first session, see the [first-run tutorial](docs/tutorials/first-run.md).
 
+## Skills
+
+`ws install` puts six skills in your runner's skills folder: `align`, `checkpoint`, `taste-gate`, `dataviz`, `resume`
+and `ship`. `ws skills` lists them per runner. A skill you already have under one of those names stays as it is.
+
+To use ws's version of a name you already have, run `ws skills adopt NAME`. Yours moves to
+`$WS_HOME/backups/skills/<runner>/` and ws installs its own. `ws skills restore NAME` takes ws's copy out and moves yours
+back.
+
 ## Verify
 
 Check which build you have:

{ws_aitoolkit-0.1.1 → ws_aitoolkit-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ws-aitoolkit"
-version = "0.1.1"
+version = "0.1.2"
 description = "Your memory, skills and rules, in any AI."
 readme = "README.md"
 license = "Apache-2.0"

{ws_aitoolkit-0.1.1 → ws_aitoolkit-0.1.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ws-aitoolkit"
-version = "0.1.1"
+version = "0.1.2"
 description = "Your memory, skills and rules, in any AI."
 readme = "README.md"
 license = "Apache-2.0"

{ws_aitoolkit-0.1.1 → ws_aitoolkit-0.1.2}/src/ws/_build.py

@@ -1,6 +1,6 @@
 """Written by the release workflow before uv build; absent in a checkout."""
 
-git_sha = "6bf31217fc9ae246b5a0dba2f91eb98e5f0e696a"
+git_sha = "92389d65eb2553fe9d570d9fd6f37cb386b08c01"
 dirty = False
-build_date = "2026-10-31T21:45:24Z"
+build_date = "2026-11-01T07:40:02Z"
 source = "release"

ws_aitoolkit-0.1.2/src/ws/adapters/__init__.py

@@ -0,0 +1,99 @@
+"""Runner adapters: one module per runner. To add a runner, add a module here; nothing else changes.
+
+A module must define:
+
+    NAME: str                                   the --runner name, e.g. "claude-code"
+    def generate(policy, ws_cmd, out, policy_file, *, protect=()) -> dict
+                                                file name (relative to the out dir) -> text; pure, no I/O.
+                                                `ws_cmd` is the argv list that runs ws, e.g. ["ws"]; `out` is the
+                                                folder the files go in and `policy_file` the policy they came from:
+                                                both are ws's own files, so the runner must not let a session edit
+                                                them (see check_argv for the hook's side of that). `protect` names
+                                                more paths a session may not write (deny rules, the hook's
+                                                --protect arguments, the sandbox's denyWrite).
+    def parse(payload) -> Call | list[Call] | None
+                                                a hook payload from that runner, as neutral Call(s); None if the call
+                                                is not one the policy governs; ValueError or TypeError if it cannot be
+                                                read (`ws gate check` then denies: fail closed).
+    def launch_hint(out) -> str                 one line: how to start the runner with the generated config.
+
+and, optionally:
+
+    UNSUPPORTED_GUARDS: tuple[str, ...]         guard names (ws.guards) this runner's generated config does not run.
+    EVENT_NAMES: dict[str, str]                 the runner's hook event name -> a ws.guards event ("pre", "post",
+                                                "start", "prompt", "stop", "subagent-stop"), for `ws gate event`.
+
+Modules are found by scanning this package, so the registry is the directory.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import MappingProxyType, ModuleType
+
+
+@dataclass(frozen=True)
+class Call:
+    """A tool call in runner-neutral terms. kind: "command" (shell), "read" (one file read), "search" (a folder
+    searched or listed, recursively), "write" (a file written or edited), "tool" (a neutral tool name from
+    ws.policy.KNOWN_TOOLS), "agent" (a subagent started), "skill" (a skill loaded) or "message" (a message sent to
+    another agent). value: the command text, the path, the tool name, the agent type, the skill name or the
+    recipient. data: what else the tool gave, read-only: a write has `old`, `new`, `content` or `edits` as the tool
+    supplies them; an agent has `prompt`, `description` and `subagent_type`; a skill has `name`; a message has `text`.
+    The policy judges command, read, search, write and tool calls; the other kinds reach guards only."""
+
+    kind: str
+    value: str
+    data: Mapping = field(default_factory=lambda: MappingProxyType({}), hash=False)
+
+    @classmethod
+    def of(cls, kind: str, value: str, **data) -> Call:
+        """A Call with its `data` set (read-only)."""
+        return cls(kind, value, MappingProxyType(data))
+
+
+def all_adapters() -> dict[str, ModuleType]:
+    found = {}
+    for info in pkgutil.iter_modules(__path__):
+        mod = importlib.import_module(f"{__name__}.{info.name}")
+        if hasattr(mod, "NAME") and hasattr(mod, "generate"):
+            found[mod.NAME] = mod
+    return dict(sorted(found.items()))
+
+
+def get(name: str) -> ModuleType:
+    adapters = all_adapters()
+    if name not in adapters:
+        raise KeyError(f"unknown runner {name!r} (known: {', '.join(adapters)})")
+    return adapters[name]
+
+
+def protected_paths(out: Path, policy_file: Path, extra: tuple[str, ...] = ()) -> list[str]:
+    """Everything a session must not write: the generated folder, the policy, ws's other control files next to
+    it (profile, secrets, jobs, release, runs, logs), and any `extra` path the caller names (a user settings file).
+    Each adapter denies edits to all of them natively."""
+    from ws.policy import control_paths
+
+    paths = [str(out), str(policy_file), *control_paths(policy_file.parent), *extra]
+    return list(dict.fromkeys(paths))
+
+
+def check_argv(
+    ws_cmd: list[str], runner: str, policy_file: Path, out: Path, protect: tuple[str, ...] = ()
+) -> list[str]:
+    """The command a generated hook or shim runs. The policy and the protected folder are absolute paths, so the hook
+    reads the same policy wherever the runner starts and cannot be pointed at another one by the session's cwd. Each
+    `protect` path is one more `--protect`."""
+    argv = [*ws_cmd, "gate", "check", "--runner", runner, "--policy", str(policy_file), "--protect", str(out)]
+    for p in protect:
+        argv += ["--protect", str(p)]
+    return argv
+
+
+def event_argv(ws_cmd: list[str], runner: str, policy_file: Path) -> list[str]:
+    """The command a generated hook runs for the events that are not a tool call's check: `ws gate event`."""
+    return [*ws_cmd, "gate", "event", "--runner", runner, "--policy", str(policy_file)]

{ws_aitoolkit-0.1.1 → ws_aitoolkit-0.1.2}/src/ws/adapters/claude_code.py

@@ -41,7 +41,29 @@ sandbox off or open it up, because an interactive session cannot be started with
 The sandbox covers shell commands; Claude's own Read, Edit and Write tools are covered by the permission rules above and
 the hook, not by it. `env` carries WS_GATED_SESSION so `ws approve` knows it is being run from a gated session.
 
-Pass the file with `claude --settings OUT/settings.json`. Nothing here touches ~/.claude.
+Guards (ws.guards) add hooks, only for the events and tools the guards that are on need: PreToolUse matches more tools
+(Agent, Task, Skill, SendMessage) when a guard reads them; PostToolUse, SubagentStop and the prompt event run
+`ws gate event`; SessionStart and Stop run it beside what they already run.
+
+Which hooks can block: PreToolUse (`ws gate check`) denies a call, and its command ends `|| exit 2` so a missing or
+crashing ws blocks too. PostToolUse (`ws gate event`) exits 2 on purpose when a check finds a problem, and Claude Code
+shows that stderr to the model; it carries no `|| exit`. Every other generated hook command (SessionStart,
+UserPromptSubmit, Stop, SubagentStop) ends `|| true`, because an exit 2 there would block the person's prompt or keep the
+session going: those hooks add context and findings, and the session carries on whatever they return.
+
+Notification and Stop also run `ws notify alert --runner claude-code || true`, the phone alert.
+
+`env` also carries WS_SANDBOXED=1, which tells the hook this session has the sandbox block above. `preflight` runs for
+every session except one whose settings set WS_SANDBOXED=0, the marker of a settings file written without the sandbox
+block; settings written before the marker existed carry the block and no marker, so `preflight` runs for them.
+
+Pass the file with `claude --settings OUT/settings.json`. Nothing in this module writes ~/.claude: `ws install` merges
+the hooks, deny rules and env of this file into the user's own `settings.json` when the profile says
+`gate = "every-session"` (ws.userconfig). That copy is built with `user_scope=True`, which swaps the project-lock Edit
+rules above for `USER_LOCKS`. In every session, not only inside the wall, a rule such as `Edit(**/.claude/**)` would
+also block a session working in a `.claude/worktrees/` checkout, so the shared file locks only the files Claude Code
+or the version-control tool runs as code. It also leaves out WS_GATED_SESSION, so `ws approve` still works from the
+person's own Claude shell (the hook denies it to the model whatever the env says).
 """
 
 from __future__ import annotations
@@ -53,9 +75,9 @@ import re
 import shlex
 from pathlib import Path
 
-from ws import jobs
-from ws.adapters import Call, check_argv, protected_paths
-from ws.approvals import ENV_MARKER, ApprovalError
+from ws import guards, jobs
+from ws.adapters import Call, check_argv, event_argv, protected_paths
+from ws.approvals import ENV_MARKER, SANDBOX_MARKER, ApprovalError
 from ws.approvals import _read_regular as read_regular
 from ws.policy import Policy, native_patterns, sandbox_read_paths, sandbox_write_paths
 
@@ -64,6 +86,37 @@ FILE = "settings.json"
 MATCHER = "Bash|Read|Grep|Glob|WebFetch|WebSearch|Edit|Write|MultiEdit|NotebookEdit"
 _TOOLS = {"web_fetch": "WebFetch", "web_search": "WebSearch"}
 _NEUTRAL = {v: k for k, v in _TOOLS.items()}
+# The project files that run as code, at any depth. These are the Edit locks in the user's own settings.json (every
+# session); the wide set from ws.sandbox.claude_denied() stays in the file `ws gate launch` uses, inside the wall.
+USER_LOCKS = (
+    "Edit(**/.claude/settings.json)",
+    "Edit(**/.claude/settings.local.json)",
+    "Edit(**/.mcp.json)",
+    "Edit(**/.git/hooks/**)",
+    "Edit(**/.git/config)",
+)
+# Claude Code's hook event names, as ws.guards names them.
+EVENT_NAMES = {
+    "PreToolUse": "pre",
+    "PostToolUse": "post",
+    "SessionStart": "start",
+    "UserPromptSubmit": "prompt",
+    "Stop": "stop",
+    "SubagentStop": "subagent-stop",
+}
+# The tools a Call kind comes from, in the order a matcher lists them.
+_KIND_TOOLS = {
+    "command": ("Bash",),
+    "read": ("Read",),
+    "search": ("Grep", "Glob"),
+    "tool": ("WebFetch", "WebSearch"),
+    "write": ("Edit", "Write", "MultiEdit", "NotebookEdit"),
+    "agent": ("Agent", "Task"),
+    "skill": ("Skill",),
+    "message": ("SendMessage",),
+}
+_EXTRA_PRE_KINDS = ("agent", "skill", "message")  # the PreToolUse matcher covers the other kinds already
+HOOK_TIMEOUT = 20  # seconds: the syntax checkers get 10
 
 # Where this runner keeps what ws installs globally, and where a repo may shadow it (read by ws.globals).
 # kinds: sub-folder -> how a name is taken: "dir" the folder name, "name" the file name, "stem" the name without extension.
@@ -87,15 +140,51 @@ def session_hooks(ws_cmd: list[str]) -> dict:
     return {"SessionStart": hook("start"), "UserPromptSubmit": hook("nudge")}
 
 
+def alert_hook(ws_cmd: list[str]) -> dict:
+    """The phone alert: `ws notify alert` reads the hook payload and always exits 0; `|| true` keeps it advice."""
+    cmd = f"{shlex.join(ws_cmd)} notify alert --runner {NAME} || true"
+    return {"type": "command", "command": cmd, "timeout": 5}
+
+
+def _matcher(kinds: set[str], base: tuple[str, ...] = ()) -> str:
+    tools = [*base]
+    for kind, names in _KIND_TOOLS.items():
+        if kind in kinds:
+            tools += [t for t in names if t not in tools]
+    return "|".join(tools)
+
+
+def _event_hook(ws_cmd: list[str], policy_file: Path, *, may_block: bool = False) -> dict:
+    """A `ws gate event` hook. It ends `|| true` unless it may block (PostToolUse, whose exit 2 reaches the model)."""
+    cmd = shlex.join(event_argv(ws_cmd, NAME, policy_file)) + ("" if may_block else " || true")
+    return {"type": "command", "command": cmd, "timeout": HOOK_TIMEOUT}
+
+
+def guard_hooks(policy: Policy, ws_cmd: list[str], policy_file: Path) -> dict:
+    """The hooks beyond the PreToolUse check and the session hooks: `ws gate event` for each event a guard that is on
+    runs at (PostToolUse, Stop, SubagentStop). Returns {event name: [matcher groups]} to merge with the session hooks."""
+    on = policy.guards.on
+    hooks: dict[str, list[dict]] = {}
+    post = guards.kinds_for(on, "post")
+    if post:
+        hooks["PostToolUse"] = [
+            {"matcher": _matcher(post), "hooks": [_event_hook(ws_cmd, policy_file, may_block=True)]}
+        ]
+    for name, ev in (("Stop", "stop"), ("SubagentStop", "subagent-stop")):
+        if guards.wanted(on, ev):
+            hooks[name] = [{"hooks": [_event_hook(ws_cmd, policy_file)]}]
+    return hooks
+
+
 def _path(path: str) -> str:
     """Claude's path syntax: `~/x` is home, `//x` is an absolute path, anything else is cwd-relative gitignore."""
     return f"/{path}" if path.startswith("/") else path
 
 
-def sandbox_block(policy: Policy, out: Path, policy_file: Path) -> dict:
+def sandbox_block(policy: Policy, out: Path, policy_file: Path, protect: tuple[str, ...] = ()) -> dict:
     """The `sandbox` settings: see the module docstring for what each key is for."""
     home = str(Path(policy_file).parent)
-    fs: dict = {"denyWrite": list(dict.fromkeys([home, *protected_paths(out, policy_file)]))}
+    fs: dict = {"denyWrite": list(dict.fromkeys([home, *protected_paths(out, policy_file, protect)]))}
     if policy.gate.deny_read:
         fs["denyRead"] = sandbox_read_paths(policy)
     if policy.gate.allow_write:  # Claude Code already allows its project folder and tmp; these are the person's extras
@@ -118,7 +207,11 @@ def preflight(payload: dict) -> str | None:
     folder is CLAUDE_PROJECT_DIR (set for hooks; Claude reads project settings from there, wherever the session has since
     changed to), else the payload's cwd. A file that does not parse is ignored, as Claude Code ignores it. A settings
     file that is not a plain file (a link, a FIFO), is too big or cannot be read is a deny: it is read without following a
-    link and without blocking, because a hook that hangs fails open (only exit 2 blocks)."""
+    link and without blocking, because a hook that hangs fails open (only exit 2 blocks). It is skipped only when the
+    settings `env` says WS_SANDBOXED=0 (the marker of settings written without the sandbox block); settings written
+    before the marker existed have the block and no marker, so it runs for them."""
+    if os.environ.get(SANDBOX_MARKER) == "0":
+        return None
     project = os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd")
     if not isinstance(project, str) or not project.startswith("/"):
         return None
@@ -176,27 +269,47 @@ def for_project(settings: str, project: str) -> str:
     return json.dumps(conf, indent=2) + "\n"
 
 
-def generate(policy: Policy, ws_cmd: list[str], out: Path, policy_file: Path) -> dict[str, str]:
+def generate(
+    policy: Policy,
+    ws_cmd: list[str],
+    out: Path,
+    policy_file: Path,
+    *,
+    protect: tuple[str, ...] = (),
+    user_scope: bool = False,
+) -> dict[str, str]:
+    protect = tuple(protect)
     deny = [f"Bash({p})" for p in native_patterns(policy)]
     deny += [f"Read({_path(p)})" for p in policy.gate.deny_read]
-    for p in protected_paths(out, policy_file):  # a file or a folder: cover both; Edit rules cover Write too
+    for p in protected_paths(out, policy_file, protect):  # a file or a folder: cover both; Edit rules cover Write too
         deny += [f"Edit({_path(p)})", f"Edit({_path(p)}/**)"]
-    from ws import sandbox
-
-    for rel in sandbox.claude_denied():  # the project's own config and git hooks: see ws.sandbox PROJECT_LOCKED
-        deny += [
-            f"Edit(**/{rel})",
-            f"Edit(**/{rel}/**)",
-        ]  # at any depth: a runner started in a sub-folder reads that one
+    if user_scope:
+        deny += USER_LOCKS
+    else:
+        from ws import sandbox
+
+        for rel in sandbox.claude_denied():  # the project's own config and git hooks: see ws.sandbox PROJECT_LOCKED
+            deny += [
+                f"Edit(**/{rel})",
+                f"Edit(**/{rel}/**)",
+            ]  # at any depth: a runner started in a sub-folder reads that one
     deny += [_TOOLS[t] for t in policy.gate.deny_tools]
-    hook = shlex.join(check_argv(ws_cmd, NAME, policy_file, out)) + " || exit 2"
+    hook = shlex.join(check_argv(ws_cmd, NAME, policy_file, out, protect)) + " || exit 2"
+    matcher = _matcher(guards.kinds_for(policy.guards.on, "pre") & set(_EXTRA_PRE_KINDS), tuple(MATCHER.split("|")))
     settings = {
         "permissions": {"deny": list(dict.fromkeys(deny))},
-        "sandbox": sandbox_block(policy, out, policy_file),
-        "env": {ENV_MARKER: "1"},
-        "hooks": {"PreToolUse": [{"matcher": MATCHER, "hooks": [{"type": "command", "command": hook}]}]},
+        "sandbox": sandbox_block(policy, out, policy_file, protect),
+        "env": {ENV_MARKER: "1", SANDBOX_MARKER: "1"},
+        "hooks": {"PreToolUse": [{"matcher": matcher, "hooks": [{"type": "command", "command": hook}]}]},
     }
     settings["hooks"].update(session_hooks(ws_cmd))
+    for name, ev in (("SessionStart", "start"), ("UserPromptSubmit", "prompt")):
+        if guards.wanted(policy.guards.on, ev):
+            settings["hooks"][name][0]["hooks"].append(_event_hook(ws_cmd, policy_file))
+    for name, groups in guard_hooks(policy, ws_cmd, policy_file).items():
+        settings["hooks"][name] = groups
+    settings["hooks"]["Notification"] = [{"hooks": [alert_hook(ws_cmd)]}]
+    settings["hooks"].setdefault("Stop", [{"hooks": []}])[0]["hooks"].append(alert_hook(ws_cmd))
     return {FILE: json.dumps(settings, indent=2) + "\n"}
 
 
@@ -211,9 +324,18 @@ def parse(payload: dict) -> Call | list[Call] | None:
     if name == "Read":
         return Call("read", _text(inp, "file_path"))
     if name in ("Edit", "Write", "MultiEdit"):
-        return Call("write", _text(inp, "file_path"))
+        return Call.of("write", _text(inp, "file_path"), tool=name, **_write_data(name, inp))
     if name == "NotebookEdit":
-        return Call("write", _text(inp, "notebook_path"))
+        return Call.of("write", _text(inp, "notebook_path"), tool=name, **_write_data(name, inp))
+    if name in ("Agent", "Task"):
+        found = {k: inp[k] for k in ("prompt", "description", "subagent_type") if isinstance(inp.get(k), str)}
+        return Call.of("agent", found.get("subagent_type", ""), tool=name, **found)
+    if name == "Skill":
+        skill = inp.get("skill") if isinstance(inp.get("skill"), str) else _optional(inp, "name") or ""
+        return Call.of("skill", skill, tool=name, name=skill, args=_optional(inp, "args") or "")
+    if name == "SendMessage":
+        text = next((inp[k] for k in ("message", "text", "content") if isinstance(inp.get(k), str)), "")
+        return Call.of("message", _optional(inp, "to") or "", tool=name, text=text)
     if name in ("Grep", "Glob"):
         calls = [Call("search", _optional(inp, "path") or ".")]
         pattern = inp.get("pattern")
@@ -225,6 +347,26 @@ def parse(payload: dict) -> Call | list[Call] | None:
     return None
 
 
+def _write_data(tool: str, inp: dict) -> dict:
+    """What a write tool gives besides the path: `old` and `new` (Edit), `content` (Write), `edits` (MultiEdit, as a
+    tuple of {old, new}), `new` (NotebookEdit). Only text the tool really sent."""
+    found: dict = {}
+    for key, name in (("old_string", "old"), ("new_string", "new"), ("content", "content"), ("new_source", "new")):
+        if isinstance(inp.get(key), str):
+            found[name] = inp[key]
+    edits = inp.get("edits")
+    if tool == "MultiEdit" and isinstance(edits, list):
+        found["edits"] = tuple(
+            {
+                k: e[key] if isinstance(e.get(key), str) else None
+                for k, key in (("old", "old_string"), ("new", "new_string"))
+            }
+            for e in edits
+            if isinstance(e, dict)
+        )  # a recorded call (record-calls) holds a size and fingerprint where the text was: None here
+    return found
+
+
 def _text(d: dict, key: str) -> str:
     v = d.get(key)
     if not isinstance(v, str):

{ws_aitoolkit-0.1.1 → ws_aitoolkit-0.1.2}/src/ws/adapters/opencode.py

@@ -22,10 +22,11 @@ from __future__ import annotations
 
 import json
 import math
+import re
 import shlex
 from pathlib import Path
 
-from ws import jobs
+from ws import guards, jobs
 from ws.adapters import Call, check_argv, protected_paths
 from ws.adapters.opencode_plugin import SOURCE
 from ws.policy import Policy, native_patterns
@@ -37,6 +38,8 @@ _TOOLS = {"web_fetch": "webfetch", "web_search": "websearch"}
 # For ws.sandbox: the env var that names the generated folder. The whole folder is read-only in the wall (OpenCode loads
 # plugin/, tool/, agent/, command/ and opencode.jsonc from it, so a planted file there would outlive the session).
 CONFIG_DIR_ENV = "OPENCODE_CONFIG_DIR"
+# The guards (ws.guards) the generated shim does not run yet: all of them. `ws doctor` names them when a policy has one on.
+UNSUPPORTED_GUARDS = guards.names()
 
 
 # OpenCode writes this file into its config folder at start and will not run if it cannot (1.19.4). Written here at
@@ -111,7 +114,10 @@ def _protect_forms(path: str, is_out: bool) -> list[str]:
     return [path, f"{path}/**", f"**/{tail}", f"**/{tail}/**"]
 
 
-def generate(policy: Policy, ws_cmd: list[str], out: Path, policy_file: Path) -> dict[str, str]:
+def generate(
+    policy: Policy, ws_cmd: list[str], out: Path, policy_file: Path, *, protect: tuple[str, ...] = ()
+) -> dict[str, str]:
+    protect = tuple(protect)
     # Last matching rule wins, so the catch-all comes first.
     bash: dict[str, str] = {"*": "allow"}
     bash.update(dict.fromkeys(native_patterns(policy), "deny"))
@@ -120,19 +126,32 @@ def generate(policy: Policy, ws_cmd: list[str], out: Path, policy_file: Path) ->
         rules = {"*": "allow", **dict.fromkeys((f for r in policy.gate.deny_read for f in _read_forms(r)), "deny")}
         permission.update(read=rules, grep=dict(rules), glob=dict(rules), list=dict(rules))
     edit = {"*": "allow"}  # covers write and patch too; a path may be a file or a folder: cover both
-    for p in protected_paths(out, policy_file):
+    for p in protected_paths(out, policy_file, protect):
         edit.update(dict.fromkeys(_protect_forms(p, p == str(out)), "deny"))
     permission["edit"] = edit
     for t in policy.gate.deny_tools:
         permission[_TOOLS[t]] = "deny"
     config = {"$schema": "https://opencode.ai/config.json", "permission": permission}
-    plugin = SOURCE.replace("/*__CHECK__*/ []", json.dumps(check_argv(ws_cmd, NAME, policy_file, out)))
+    plugin = SOURCE.replace("/*__CHECK__*/ []", json.dumps(check_argv(ws_cmd, NAME, policy_file, out, protect)))
     plugin = plugin.replace("/*__WS__*/ []", json.dumps(ws_cmd))
     return {CONFIG: json.dumps(config, indent=2) + "\n", PLUGIN: plugin, IGNORE: IGNORE_TEXT}
 
 
-def parse(payload: dict) -> Call | None:
-    """What the shim sends: {"tool": "bash", "args": {"command": ...}}."""
+_PATCH_PATH = re.compile(r"^\*\*\* (?:Add File|Update File|Delete File|Move to):[ \t]*(\S.*?)[ \t\r]*$", re.MULTILINE)
+
+
+def patch_paths(patch: str) -> list[str]:
+    """The files a patch (OpenCode's `*** Begin Patch` text) adds, updates, deletes or moves to, in order. A patch
+    that names none cannot be judged, so it raises: the call is denied."""
+    paths = list(dict.fromkeys(_PATCH_PATH.findall(patch)))
+    if not paths:
+        raise TypeError("args.patchText names no file (expected `*** Update File: path` lines)")
+    return paths
+
+
+def parse(payload: dict) -> Call | list[Call] | None:
+    """What the shim sends: {"tool": "bash", "args": {"command": ...}}. A patch tool is a write of each file in the
+    patch."""
     tool, args = payload.get("tool"), payload.get("args")
     if not isinstance(tool, str) or not isinstance(args, dict):
         raise TypeError("payload has no tool and args")
@@ -142,6 +161,15 @@ def parse(payload: dict) -> Call | None:
         return Call("read", _text(args, "filePath"))
     if tool in ("edit", "write", "multiedit"):
         return Call("write", _text(args, "filePath"))
+    if tool in ("patch", "apply_patch"):
+        kept = payload.get(
+            "paths"
+        )  # only a line record-calls kept has these (the shim sends none): text -> fingerprint
+        if isinstance(args.get("patchText"), dict) and isinstance(kept, list) and kept:
+            if not all(isinstance(p, str) and p for p in kept):
+                raise TypeError("paths must be non-empty text")
+            return [Call.of("write", p, tool=tool) for p in kept]
+        return [Call.of("write", p, tool=tool) for p in patch_paths(_text(args, "patchText"))]
     if tool in ("grep", "glob", "list"):
         path = args.get("path")
         if path is not None and not isinstance(path, str):

{ws_aitoolkit-0.1.1 → ws_aitoolkit-0.1.2}/src/ws/adapters/opencode_plugin.py

@@ -15,7 +15,9 @@ import { resolve } from "node:path"
 
 const CHECK = /*__CHECK__*/ []
 const WS = /*__WS__*/ []
-const GOVERNED = new Set(["bash", "read", "grep", "glob", "list", "edit", "write", "multiedit", "webfetch", "websearch"])
+const GOVERNED = new Set([
+  "bash", "read", "grep", "glob", "list", "edit", "write", "multiedit", "patch", "apply_patch", "webfetch", "websearch",
+])
 
 // Session notes (advice, never a gate): record the release on session.created; on session.idle ask `ws session nudge`
 // and show its one line as a toast (OpenCode has no way for a plugin to add text to the model's context). Any error is

{ws_aitoolkit-0.1.1 → ws_aitoolkit-0.1.2}/src/ws/approvals.py

@@ -69,6 +69,7 @@ from ws.profile import ws_home
 
 TTL = 600  # seconds a pending or a granted approval lives
 ENV_MARKER = "WS_GATED_SESSION"  # set in a gated session's env; `ws approve` refuses when it is there
+SANDBOX_MARKER = "WS_SANDBOXED"  # set in the env of a session that has ws's sandbox block (the hook checks for it)
 _SHORT = 12  # hex digits of the id shown to a person
 _ID = re.compile(r"^[0-9a-f]{8,64}$")
 _FULL = re.compile(r"^[0-9a-f]{64}$")
@@ -249,10 +250,13 @@ def peek(root: Path, ident: str, now: float) -> str | None:
     return _verdict(text, ident, now)
 
 
-def require(root: Path, bound: Bound, now: float | None = None, consume: bool = True) -> str | Claim | None:
+def require(
+    root: Path, bound: Bound, now: float | None = None, consume: bool = True, why_asked: str = ""
+) -> str | Claim | None:
     """None if this exact call holds a granted approval (which is used up). Else the reason it is refused, with the
     id to approve: a pending record is written (or kept, if one is still fresh). With consume=False (inside the
-    wall, where the grant cannot be consumed) a valid grant gives a Claim for the caller to send to the launcher."""
+    wall, where the grant cannot be consumed) a valid grant gives a Claim for the caller to send to the launcher.
+    `why_asked` goes in front of the reason: what stopped the call (a guard's finding)."""
     now = time.time() if now is None else now
     root = Path(root)
     ident = bound.digest()
@@ -269,6 +273,7 @@ def require(root: Path, bound: Bound, now: float | None = None, consume: bool =
         _prune(root, now)
     note = "" if why == _NONE else f" ({why})"
     return (
+        f"{why_asked + ': ' if why_asked else ''}"
         f"needs a person's approval{note}: in a terminal of your own run `ws approve {ident[:_SHORT]}`, "
         f"then retry the identical call (good for one use, within {TTL // 60} minutes)"
     )

{ws_aitoolkit-0.1.1 → ws_aitoolkit-0.1.2}/src/ws/broker.py

@@ -348,7 +348,8 @@ class Broker:
         allow_plain_http: bool = False,
     ):
         env = os.environ if env is None else env
-        sock = Path(socket_file).expanduser() if socket_file else ws_home(env) / "run" / "broker.sock"
+        # --socket wins; else what clients use: $WS_BROKER_SOCKET, [roles.secrets] socket, $WS_HOME/run/broker.sock
+        sock = Path(socket_file).expanduser() if socket_file else wsecrets.socket_path(env)
         return cls(
             sock,
             wsecrets.registry_path(env),
@@ -978,7 +979,11 @@ def register(sub) -> None:
     b = sub.add_parser("broker", help="the secrets broker: agents ask it to use a key and never see the value")
     bsub = b.add_subparsers(dest="broker_command", required=True)
     p = bsub.add_parser("serve", help="run the broker (a Unix socket and a loopback lease proxy)")
-    p.add_argument("--socket", metavar="PATH", help="default $WS_HOME/run/broker.sock")
+    p.add_argument(
+        "--socket",
+        metavar="PATH",
+        help="default $WS_BROKER_SOCKET, else [roles.secrets] socket in the profile, else $WS_HOME/run/broker.sock",
+    )
     p.add_argument("--group", metavar="GROUP", help="also serve members of this group (socket folder becomes 0750)")
     p.add_argument("--port", type=int, default=0, help="lease proxy port on 127.0.0.1 (default: any free one)")
     p.add_argument(

{ws_aitoolkit-0.1.1 → ws_aitoolkit-0.1.2}/src/ws/cli.py

@@ -15,6 +15,7 @@ from ws import (
     config_cmd,
     devices,
     doctor,
+    extcmd,
     gate,
     install,
     mcp_server,
@@ -217,10 +218,19 @@ def cmd_help(args: argparse.Namespace) -> int:
         if word not in kids:
             raise WsError("usage", f"no help topic {word!r}", output.did_you_mean(word, kids) or "run `ws help`", 2)
         parser = kids[word]
+    root = parser is args.ws_root
+    extra = extcmd.help_lines(_subcommands(parser)) if root else []
     if args.json:
-        output.result(_help_json(parser))
+        data = _help_json(parser)
+        if root:
+            builtins = _subcommands(parser)
+            data["external"] = extcmd.list_externals(builtins)
+            data["fallback"] = extcmd._fallback_for_help()
+        output.result(data)
     else:
         print(parser.format_help(), end="")
+        if extra:
+            print("\n" + "\n".join(extra))
     return 0
 
 
@@ -267,6 +277,7 @@ def build_parser() -> argparse.ArgumentParser:
     approvals.register(sub)
     setup_ui.register(sub)
     config_cmd.register(sub)
+    extcmd.register(sub)
     status.register(sub)
     ws_eval.register(sub)
     version.register(sub)
@@ -279,9 +290,14 @@ def main(argv: list[str] | None = None) -> int:
     try:
         g, rest = output.split_global(raw)
         want_json = g.json
-        if g.cwd is not None:
+        parser = build_parser()
+        flags = [o for a in parser._actions for o in a.option_strings]
+        spec = extcmd.plan(raw, g, rest, _subcommands(parser), flags)
+        if g.cwd is not None and (spec is None or spec.keep_cwd):
             output.enter_cwd(g.cwd)
-        args = build_parser().parse_args(rest)
+        if spec is not None:
+            return extcmd.launch(spec)
+        args = parser.parse_args(rest)
         kind = args.ws_command
         return output.dispatch(args, kind, g.json)
     except WsError as e: