README: tighten wording on secondary execution warning

Author: afq984

README.md

@@ -2,6 +2,41 @@
 
 Tools to let coding agents access the shell with opinionated defaults.
 
+## Security model
+
+Most agent actions should run under [`//sandbox`](sandbox/BUILD.bazel).
+Command filtering complements sandboxing by narrowly delegating selected CLI
+capabilities, including commands that intentionally use the user's ambient
+credentials. It is not a substitute for sandboxing.
+
+Command filtering is useful for narrowing which command lines an agent may run:
+which binaries are allowed, which subcommands and flags are allowed, and which
+logical paths may be passed as arguments. That is a least-authority delegation
+mechanism, not a full security boundary.
+
+If an allowed command can use the user's ambient credentials, network access,
+or other external authority, then allowing that command is effectively
+granting that capability to the agent. Path restrictions such as `<path:r>`
+and `<path:w>` only constrain named file arguments; they do not constrain
+unrelated side effects a command may have.
+
+For example, a user might grant an agent permission to fetch GitHub Actions
+logs via a narrow `gh` rule. That is different from allowing arbitrary `gh`
+usage: the rule is a deliberate delegation of one credential-backed
+capability, not blanket authority over the GitHub CLI.
+
+Some allowed tools may execute hooks, helpers, pagers, editors, or other
+user-controlled programs as part of their normal behavior.
+Rules should be written with those secondary execution paths in mind.
+
+Practical guidance:
+
+- Prefer running agent actions in `//sandbox`.
+- Use command filters to grant narrow, reviewable capabilities, especially for
+  tools that intentionally act with the user's ambient credentials.
+- Write rules per operation, not per binary.
+- Treat each allow-rule as a permission grant that should be reviewed.
+
 ## License
 
 Apache-2.0

command_filter/LANGUAGE.md

@@ -4,6 +4,12 @@ A small language for defining allowed command invocations. Each rule file
 describes the permitted argument shapes for a command, with path arguments
 carrying read/write permission annotations.
 
+This language describes which command lines are permitted. It does not by
+itself provide process isolation. In this repository, most agent actions
+should run under `//sandbox`; command filtering is used to narrowly delegate
+specific CLI capabilities, including commands that intentionally use ambient
+user credentials.
+
 ## Statements
 
 Every line is one of two statement types, identified by a keyword prefix: