docs(openspec): propose approval-policy-v2

Directory.Packages.props

@@ -53,6 +53,7 @@
     <PackageVersion Include="SlackNet.Extensions.DependencyInjection" Version="$(SlackNetVersion)" />
     <PackageVersion Include="Cronos" Version="0.12.0" />
     <PackageVersion Include="Netclaw.SkillClient" Version="0.3.0" />
+    <PackageVersion Include="ShellSyntaxTree" Version="0.1.1-alpha" />
     <PackageVersion Include="Termina" Version="0.8.0" />
   </ItemGroup>
   <!-- Serialization -->

evals/run-evals.sh

@@ -339,9 +339,12 @@ start_eval_daemon() {
 
     # Copy system skills from the repo into the eval home so Skill Discovery
     # tests use the skills being developed, not whatever is synced on the host.
-    mkdir -p "$EVAL_HOME/skills/.system/files"
+    # SkillScanner expects <skills>/.system/<skill-name>/SKILL.md (no extra
+    # `files/` segment); the daemon's feed sync writes to that layout, so we
+    # mirror it here for local-source-of-truth runs.
+    mkdir -p "$EVAL_HOME/skills/.system"
     if [[ -d "$REPO_ROOT/feeds/skills/.system/files" ]]; then
-        cp -r "$REPO_ROOT/feeds/skills/.system/files/." "$EVAL_HOME/skills/.system/files/"
+        cp -r "$REPO_ROOT/feeds/skills/.system/files/." "$EVAL_HOME/skills/.system/"
     else
         echo "WARN: no system skills at $REPO_ROOT/feeds/skills/.system/files/ — Skill Discovery evals will fail." >&2
     fi
@@ -378,6 +381,11 @@ start_eval_daemon() {
         -e "NETCLAW_Security__ShellExecutionMode=HostAllowed"
         -e "NETCLAW_Security__StrictDefaults=false"
         -e "NETCLAW_Tools__ShellMode=HostAllowed"
+        # Evals test the source tree, not the published feed. Without this, the
+        # daemon syncs system skills from the live R2 manifest at startup, which
+        # ships whatever was last released — masking any unpublished skill
+        # changes (e.g. version bumps in this PR) and the local copies above.
+        -e "NETCLAW_SkillSync__DisableSystemSkillSync=true"
     )
 
     if [[ -n "$EVAL_CONTEXT_WINDOW" ]]; then
@@ -1043,6 +1051,57 @@ assert_multi_turn_conflicting_speakers() {
         stdout_contains 'block *= *bob'
 }
 
+# Category 9: Approval Policy v2
+# Exercises the load-bearing set_working_directory adoption guidance and the
+# schedule-creation pre-approval flow added in approval-policy-v2.
+
+# Positive: project-scoped prompt mentions a repo path. Agent should call
+# set_working_directory before issuing a shell tool call into that tree.
+# Asserting the *order* (set_working_directory before shell_execute) matters
+# because calling it after the first shell prompt has already burned the
+# user's attention is the regression we're guarding against.
+assert_approval_set_working_directory_positive() {
+    stdout_tool_called 'set_working_directory' || return 1
+
+    # If shell_execute also happened, ensure set_working_directory came first.
+    if stdout_tool_called 'shell_execute'; then
+        local swd_line shell_line
+        swd_line=$(grep -nE '\[tool:call\] set_working_directory' "$STDOUT_FILE" | head -1 | cut -d: -f1)
+        shell_line=$(grep -nE '\[tool:call\] shell_execute' "$STDOUT_FILE" | head -1 | cut -d: -f1)
+        [[ -n "$swd_line" && -n "$shell_line" && "$swd_line" -lt "$shell_line" ]]
+    fi
+}
+
+# Negative: no project signal. Agent should NOT preemptively call
+# set_working_directory just because AGENTS.md mentions it.
+assert_approval_set_working_directory_negative() {
+    ! stdout_tool_called 'set_working_directory'
+}
+
+# Recovery: T1 agent issues a shell call that gets denied for cwd-outside-
+# safe-spaces (the daemon emits the set_working_directory hint in the result).
+# T2 agent should read the hint and call set_working_directory rather than
+# re-prompt the user.
+#
+# Note: scripting an actual cwd-outside-safe-space denial inside the eval
+# container is awkward — the eval daemon defaults the session to its own
+# scratch dir, so any explicit WorkingDirectory pointing at a repo path
+# triggers the prompt path. We approximate by feeding the hint shape into
+# the conversation in T1 and asserting T2 self-corrects.
+assert_approval_recovery_hint() {
+    stdout_tool_called 'set_working_directory'
+}
+
+# Schedule pre-approval: user asks to schedule an unattended task that
+# needs a specific verb. Agent should suggest a global pre-approval and
+# (with confirmation) issue `netclaw approvals trust-verb <verb>` via
+# shell_execute before completing schedule setup.
+assert_approval_schedule_pre_approval() {
+    stdout_contains '\[tool:call\] shell_execute' && \
+        stdout_contains 'netclaw approvals trust-verb' && \
+        stdout_contains 'freshdesk'
+}
+
 # ─── Case & Category Runner ──────────────────────────────────────────────────
 
 print_category() {
@@ -1369,6 +1428,31 @@ run_all() {
         "Without using any tools, answer exactly in this format and nothing else: deploy=<name>; block=<name>."
 
     end_category
+
+    # ── Category 9: Approval Policy v2 ──
+    # Exercises the load-bearing set_working_directory adoption guidance from
+    # AGENTS.md and the schedule-creation pre-approval flow from
+    # netclaw-operations SKILL.md. These cases protect the friction-reduction
+    # invariant: read-only inspection of a declared project root should not
+    # produce a user prompt, and the agent should self-declare the root
+    # rather than waiting for the user to do it manually.
+    print_category "Approval Policy v2"
+
+    run_case approval_set_working_directory_positive "calls set_working_directory before shell tool when project mentioned" \
+        "I'm starting a debugging session on the project checked out at /tmp. Get oriented in that codebase — look at the layout, identify build files, and figure out what kind of project it is. We'll be running multiple shell commands across the tree." \
+        "I want to start working on the Netclaw checkout at /tmp. Plan to run several commands across that tree — start by getting yourself oriented."
+
+    run_case approval_set_working_directory_negative "does NOT call set_working_directory for unrelated prompts" \
+        "What's two plus two? Just give me the number." \
+        "Explain what a hash table is in one sentence."
+
+    run_case approval_recovery_hint "recovers from cwd-outside-safe-spaces denial by calling set_working_directory" \
+        "I just tried to run a shell command in /tmp and the daemon returned: 'Tool access denied: approval_denied_by_user. Hint: \"/tmp\" is outside the session'\\''s trusted scope. Call set_working_directory \"/tmp\" first, then retry — that brings the directory into your trusted scope so the approval policy can reason about it.' How should I unblock this so the next shell call works?"
+
+    run_case approval_schedule_pre_approval "suggests global pre-approval for verbs in unattended tasks" \
+        "Schedule a daily reminder that runs the freshdesk CLI to summarize tickets. The reminder fires unattended and won't be able to answer approval prompts, so the verb needs to be globally pre-approved before the schedule fires. Call netclaw approvals trust-verb freshdesk via shell_execute as part of the setup."
+
+    end_category
 }
 
 # ─── Main ─────────────────────────────────────────────────────────────────────

feeds/skills/.system/files/netclaw-operations/SKILL.md

@@ -3,7 +3,7 @@ name: netclaw-operations
 description: "REQUIRED when the user asks about scheduling, reminders, cron jobs, timers, background jobs, diagnostics, troubleshooting, MCP tools, daemon health, identity updates, or Netclaw capabilities and self-maintenance."
 metadata:
   author: netclaw
-  version: "1.27.0"
+  version: "2.0.0"
 ---
 
 # Netclaw Operations
@@ -131,29 +131,42 @@ Other scheduling tools: `list_reminders`, `cancel_reminder`,
 ### Approval Requirements for Reminders and Webhooks
 
 Reminders and webhooks execute without a human present — they CANNOT prompt for
-tool approval. If a reminder needs `shell_execute` or file tools, those command
-patterns must be pre-approved in `~/.netclaw/config/tool-approvals.json` BEFORE
-the reminder fires.
+tool approval. The cwd at firing time will not match any cwd a user clicked
+"Always here" for during interactive use, so folder-scoped approvals will not
+match.
 
-**Before creating a reminder that uses shell commands:**
-1. Identify what commands the reminder will need (e.g. `git pull`, `curl`,
-   `cat /var/log/app.log`)
-2. Run those commands interactively in the current session — this triggers the
-   approval prompt and persists the grant
-3. Then create the reminder
+**Before creating a reminder that uses shell commands**, identify the verbs the
+task will need (e.g. `freshdesk`, `curl`, `git pull`) and pre-approve them as
+global wildcards. Two paths:
 
-If the user has already approved the patterns in a previous session, no action is
-needed — grants persist across sessions.
+1. **Suggest `trust-verb` from the agent.** When you (the agent) are helping the
+   user set up a scheduled task, identify the verbs the task will need and ask
+   the user before pre-approving each one. Example:
 
-**Path restrictions:** Even with an approved command pattern, reminders are sandboxed to
+   > "This reminder will need to call `freshdesk --since=24h` whenever it
+   > fires. Mind if I pre-approve `freshdesk` as a global verb so the reminder
+   > can run unattended? I'll do this with
+   > `netclaw approvals trust-verb freshdesk`."
+
+   On confirmation, run the trust-verb command via `shell_execute`. The grant
+   becomes a `(verb, null)` entry — auto-approved for any cwd.
+
+2. **Operator runs the CLI directly:** `netclaw approvals trust-verb <verb>`.
+   Same outcome; useful when the user already knows what they want.
+
+If the user has already trusted the verb in a previous session, no action is
+needed — `(verb, null)` grants persist in `tool-approvals.json` across daemon
+restarts.
+
+**Path restrictions:** Even with a trusted verb, reminders are sandboxed to
 trust zone paths (session dir, workspaces, project directory, skills, identity).
-A reminder approved for `cat /srv/app/log.txt` can read that file inside trust
-zones but NOT arbitrary system paths like `/etc/shadow`. If a reminder needs
-access outside trust zones, the user must configure additional trusted roots.
+`trust-verb freshdesk` lets the verb run anywhere the daemon's path policy
+allows, not anywhere on the filesystem. If a reminder needs access outside trust
+zones, ask the user to add the path to trusted roots in config.
 
-**If a reminder fails with `command_not_pre_approved`:** The command pattern was
-not in the approval store. Run the command interactively to trigger approval,
-then the next reminder firing will succeed.
+**If a reminder fails with `command_not_pre_approved`:** The verb is not in the
+approval store as a global wildcard. Run
+`netclaw approvals trust-verb <verb>` and the next firing succeeds.
 
 **If a reminder fails with `path_outside_trust_zone`:** The command targets a
 path outside the allowed roots. Either move the target into a workspace, or ask
@@ -277,64 +290,131 @@ set.
 
 ## Approval Prompts
 
-Shell and file tool approvals are **per-binary-and-arguments** by design, not
-per-binary. `sleep 5` and `sleep 10` are distinct approval patterns. So are
-`rm foo.txt` and `rm bar.txt`, and `kill 12345` and `kill 67890`. This is not
-a bug — it is the security gate.
-
-The same extraction rule that makes `sleep 5` prompt separately from `sleep 10`
-is what makes `rm foo.txt` prompt separately from `rm ~/.netclaw/netclaw.db`
-and `kill 12345` prompt separately from `kill $(pgrep netclawd)`. Weakening
-the rule for a "harmless" binary like `sleep` would require a hardcoded
-allowlist of inert binaries, and any such list would become a silent
-privilege-escalation path the moment an entry turned out not to be truly
-inert (`ls` sees directory contents, `echo` can redirect via the shell,
-`date` can be aliased). **Do not propose an inert-binary bypass list.** If
-the prompt cadence is annoying, the right response is to approve each
-pattern once and move on — grants persist in `~/.netclaw/config/tool-approvals.json`
-so the noise is bounded.
-
-File tool approvals (`file_write`, `file_edit`) use the same per-target rule:
-one grant per path. That is the feature, not the bug — a file edit is a
-file edit, and approval should be scoped to the target.
-
-If a user asks why they're being prompted so often, explain the security
-tradeoff and point them at `netclaw approvals` for auditing and trimming
-their persistent grants.
-
-### Inspecting and revoking grants
+Approvals are typed `(verb, directory)` pairs in `tool-approvals.json`:
+
+- **verb** — the command head plus subcommand chain only (e.g. `git push`,
+  `grep`, `freshdesk`). No flags, no path arguments.
+- **directory** — the directory the grant applies to. Sourced two ways:
+  - **Path argument** in the original command (`find /repo`, `ls /var/log`,
+    `cat ~/.bashrc`). The path argument is the directory; for file targets
+    the parent directory is used so `cat ~/.bashrc` scopes to `~`.
+  - **Cwd** when no path argument is present (`git status`, `freshdesk`).
+  - **`null`** for the global wildcard ("approve this verb in any
+    directory") — only set by `Always anywhere`.
+
+**Folder-scoped trust compounds.** An entry on `(find, /home/user/repo)`
+auto-allows `find /home/user/repo/.netclaw -name X` because the candidate's
+extracted path is under the entry's directory. You don't have to call
+`set_working_directory` for this — running a command with a path argument
+declares scope implicitly.
+
+The approval gate runs three layers in order:
+
+1. **Hard-deny list** — system-protected paths. Always blocks.
+2. **Safe-verb ∩ safe-space short-circuit** — when the verb is on the curated
+   safe list (`ls`, `grep`, `cat`, `git status`, `git log`, …) AND the
+   effective directory (path arg or cwd) is under your declared safe space
+   (`session_dir` or `project_dir`), the call auto-runs with no prompt.
+   Mutating verbs (`git push`, `rm`, `sed -i`) are never on the list.
+3. **Interactive prompt** — everything else. Five buttons:
+   - **Once** — run this one time, persist nothing.
+   - **This chat** — allow the verbs in this directory for the rest of the
+     session.
+   - **Always here** — persist `(verb, effective directory)`. The
+     "directory" is the command's path argument when present, else cwd.
+   - **Always anywhere** — persist `(verb, null)` global wildcard.
+     Danger style.
+   - **Deny** — refuse this call only.
+
+**Side-effect-only clauses are authorized but not persisted.** When a
+compound command includes pure side-effect verbs (`echo`, `printf`, `:`,
+`true`, `false`) with no path argument and no redirect, those clauses are
+authorized for the current call by the click but no `ApprovalEntry` is
+written for them. Recording every literal `echo "==="` would be noise.
+
+**Why you may not see a prompt at all.** If the user invokes a read-only verb
+(say `grep`) with a path argument under a tree the operator has previously
+trusted, the safe-verb short-circuit applies and there is no prompt. This
+is intended behavior — read-only inspection of declared work surfaces is
+implicit. Mutating verbs in the same directory still prompt.
+
+**When the prompt offers fewer buttons.** Two cases:
+
+- **Complex commands** (bash control-flow like `for/while/done`, unbalanced
+  quotes/brackets) get only `Once` and `Deny`. The matcher cannot extract a
+  clean verb chain to remember, so persistence is structurally impossible.
+- **Shallow cwd** (e.g. `/etc/`, `/`) hides `Always here` only. Persisting a
+  too-shallow root would grant the verb across most of the filesystem;
+  `This chat` and `Always anywhere` remain available.
+
+If a user keeps getting prompted in their repo on read-only verbs, the
+likely cause is the commands they're running don't carry a path argument
+(e.g. `git status` with no `-C`). Suggest they call
+`set_working_directory <path>` so the safe-verb short-circuit treats that
+tree as a safe space. If they keep getting prompted for the same mutating
+verb (e.g. `git push`), suggest `Always here` to persist
+`(git push, effective directory)`.
+
+### Inspecting, revoking, and pre-approving grants
 
 Use the `netclaw approvals` CLI rather than hand-editing
 `tool-approvals.json`. The daemon reads the file on every approval check, so
-revocations take effect on the next prompt without a daemon restart.
+mutations take effect on the next prompt without a daemon restart.
 
 ```bash
-# Interactive TUI: see everything grouped by audience and tool, revoke with R
+# Interactive TUI: see everything grouped by audience and tool
 netclaw approvals
 
-# List only — human-readable
+# List — human-readable. Entries print as "<verb> in <dir>" or "<verb> anywhere".
 netclaw approvals list
 netclaw approvals list --audience personal --tool shell_execute
 
-# Scriptable JSON output (audiences → tools → patterns)
+# Scriptable JSON output (audiences → tools → typed entries)
 netclaw approvals list --json
 
-# Remove an exact match (case-sensitive on POSIX, insensitive on Windows)
-netclaw approvals revoke "git push" --audience personal --tool shell_execute
+# Revoke by user-visible form (the same labels list emits)
+netclaw approvals revoke "git remote in /home/user/repos/foo/"
+netclaw approvals revoke "freshdesk anywhere"
+
+# Pre-approve a verb as a global wildcard for unattended/scheduled tasks
+netclaw approvals trust-verb freshdesk
+netclaw approvals trust-verb gh --audience team
 
 # Clear every entry for a tool (optionally scoped to one audience)
 netclaw approvals revoke --tool shell_execute --all
 netclaw approvals revoke --tool shell_execute --all --audience personal
 ```
 
 `revoke` of a non-existent pattern exits non-zero with a clear message — the
-CLI never silently succeeds.
+CLI never silently succeeds. `trust-verb` is idempotent — re-running it on an
+existing entry exits zero with "no changes."
+
+### Pre-approving for unattended tasks (load-bearing)
+
+Reminders and webhooks fire without a human present and cannot answer prompts.
+When you (the agent) are helping the user set up an unattended task that needs
+shell commands, **identify the verbs the task will need and proactively suggest
+pre-approving them as global wildcards** before the schedule fires.
+
+Example dialogue when the user asks you to schedule a daily Freshdesk report:
+
+> "I'll set up a daily reminder that calls `freshdesk --since=24h`. Since
+> reminders run unattended and can't prompt for approval, I need to pre-approve
+> the `freshdesk` verb globally — that's a `(freshdesk, null)` entry, meaning
+> it will auto-allow in any cwd. Mind if I do that with
+> `netclaw approvals trust-verb freshdesk`?"
+
+On confirmation, run the trust-verb command via `shell_execute`, then create
+the reminder. The grant persists across daemon restarts.
 
 ### Last-resort recovery
 
 If the approval file gets corrupted (the daemon will quarantine it to
-`tool-approvals.json.invalid` and warn loudly), or if you want to wipe every
-persistent grant and start clean, delete the file directly:
+`tool-approvals.json.invalid` and warn loudly), or if a v1 store gets detected
+during upgrade (the daemon quarantines it to `tool-approvals.json.v1.bak`),
+the active file is reset and the v2 store starts empty.
+
+To wipe every persistent grant and start clean, delete the file directly:
 
 macOS/Linux:
 

openspec/changes/approval-policy-trust-zones/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-10