(magpie) branch main updated: docs(vetted-ops): say that --config selects the policy file (#1284)

[po...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git


The following commit(s) were added to refs/heads/main by this push:
     new f432ef8f docs(vetted-ops): say that --config selects the policy file (#1284)
f432ef8f is described below

commit f432ef8f98edb1e562cf0198c80b2a6ea619fcf7
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Fri Sep 18 19:50:06 2026 +0200

    docs(vetted-ops): say that --config selects the policy file (#1284)
    
    The README claimed "The policy is never supplied on the command line: a
    caller cannot widen its own policy", but `cli.py` defines `--config`, so a
    caller does choose which policy TOML applies.
    
    The claim also contradicted the same document further down, where "Wiring
    it into settings" advises keeping the policy outside the sandbox-writable
    root and pointing `--config` at it — a mitigation that only exists because
    the flag does.
    
    State the accurate property instead: the policy *contents* are never
    CLI-supplied (no flag adds a repo, a caller, or an operation), so a
    caller's reach is bounded by the policy files on disk and by who may write
    them. That puts the weight on the `deny` rules and the file's location,
    which is where it actually rests, and cross-references the section that
    already relies on the flag. Also show the path-bound `allow` form for repos
    holding more than one policy.
    
    No behaviour change; `--config` is unchanged and the test suite uses it.
    
    Fixes #1283
    
    Generated-by: Claude Opus 5
---
 tools/vetted-ops/README.md | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/tools/vetted-ops/README.md b/tools/vetted-ops/README.md
index 0e279dfb..02382a73 100644
--- a/tools/vetted-ops/README.md
+++ b/tools/vetted-ops/README.md
@@ -215,8 +215,22 @@ Grant the narrowest set that lets a skill finish its job: `pr-management-stats`
 is a read-only dashboard, so it gets no write operation at all, and a
 prompt-injection payload in a PR title cannot talk it into one.
 
-The policy is never supplied on the command line: a caller cannot widen its own
-policy.
+The policy *contents* are never supplied on the command line: no flag adds a
+repo, a caller, or an operation. What `--config` selects is *which policy file*
+applies, so a caller's reach is bounded by the policy files that already exist
+on disk and by who may write them — not by the absence of a flag. The `deny`
+rules and the file's location are what close that surface; see
+[Wiring it into settings](#wiring-it-into-settings), which points `--config` at
+a policy outside the sandbox-writable root on purpose.
+
+When a repo holds more than one policy, bind the flag in the permission rule so
+the grant names the policy it was reasoned about:
+
+```jsonc
+"allow": [
+  "Bash(… vetted-op-read --config .apache-magpie-overrides/tools/vetted-ops/config.toml *)"
+]
+```
 
 `upstream` is required; **`tracker` is optional**. A project whose skills only
 touch public work has no tracker to name, and requiring one would fail every