@matheuskrumenauer/tanya 0.5.0-beta.0 → 0.6.0-beta.0

package/README.md

@@ -114,6 +114,43 @@ The workspace state directory remains `.tania/` for historical compatibility.
 Existing run logs, context files, artifact materialization, and memory files are
 not moved or renamed.
 
+## Permissions
+
+Tanya has an opt-in pre-execution permission layer for native tools and
+project-local slash commands. The default mode in v0.x is `bypass` so existing
+automation keeps full access until a workspace opts in.
+
+Modes:
+
+- `bypass` skips gating and logs decisions for audit.
+- `default` applies configured rules; unmatched calls are allowed.
+- `ask` applies configured rules; unmatched calls prompt the host.
+- `plan` denies all tool execution so the model must respond with text only.
+
+Rules live in `~/.tanya/permissions.json` for user scope and
+`.tania/permissions.json` for project scope. Project rules merge over user
+rules. A minimal deny rule:
+
+```json
+{
+  "version": 1,
+  "mode": "default",
+  "alwaysDeny": ["run_shell:.*rm -rf.*"]
+}
+```
+
+Generate a starter config from recent runs:
+
+```bash
+tanya permissions migrate --cwd . > .tania/permissions.suggested.json
+```
+
+Spend rules can gate projected token or USD budgets before a tool runs. For
+example, `/cost --enforce --max-usd 0.50` writes a session-scoped rule.
+
+See [docs/permissions.md](./docs/permissions.md) for the full schema,
+precedence, audit log, and worked examples.
+
 ## Commands
 
 ```bash
@@ -158,8 +195,8 @@ Project-local commands live in `.tania/commands/*.{js,ts,sh}` and appear in
 run directly; JavaScript and TypeScript commands export a default
 `CommandDefinition`.
 
-Project-local commands are arbitrary code execution. TODO(M3): gate them
-through the permission engine before treating them as safe extension points.
+Project-local commands are arbitrary code execution and are gated by the same
+permission engine as native tools.
 
 `--verify` adds required verification commands to the run context. Tanya must run and report each exact command before finishing the coding task.