@matheuskrumenauer/tanya 0.5.0-beta.0 → 0.7.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.
 
@@ -208,12 +245,24 @@ Tanya handles context pressure as a cascade instead of truncating abruptly:
 1. Microcompact folds empty/no-op tool-call pairs in place.
 2. Snip removes low-signal history such as duplicate file reads and empty read-only tool results.
 3. Auto-compact reacts to provider `413` / context-window errors by summarizing older turns into a `[compaction summary: ...]` system message and retrying once normally, then once more aggressively.
-4. Archive writes compacted messages to `.tanya/runs/<runId>/archive.jsonl` before they leave live history, so verifier scans and future memory tools can still inspect them.
+4. Archive writes compacted messages to `.tania/runs/<runId>/archive.jsonl` before they leave live history, so verifier scans and future memory tools can still inspect them.
 
 Runs are capped at three total auto-compactions. If the provider still rejects the context, Tanya raises `CompactionExhaustedError` and asks the user to narrow the task, clear the session, or split the work.
 
 See [docs/long-sessions.md](./docs/long-sessions.md) for details.
 
+## Token economy
+
+Tanya trims model-visible tokens while keeping state reversible and auditable.
+
+- Lite prompts can be enabled with `TANYA_LITE_PROMPT=1` for cheap-provider exploration turns. The legacy `TANIA_LITE_PROMPT` alias is still accepted.
+- System prompts are automatically capped to the active provider context window. Tune the default 25% cap with `TANYA_PROMPT_BUDGET_RATIO`.
+- Large shell/tool outputs are shortened for the model with a visible `<truncated ...>` marker. Use `expand_result` with the marker's `tool_call_id` to fetch the full output or a byte range.
+- Repeated unchanged `read_file` calls return a reference marker instead of resending the same content. Pass `force: true` when the agent genuinely needs the full file again.
+- `/budget` reports token usage, cost estimates, expensive turns, and one deterministic optimization suggestion. `/budget --enforce --max-usd <amount>` persists a session spend rule through the permission engine.
+
+See [docs/token-economy.md](./docs/token-economy.md) for the full model, cache locations, and tool-definition knobs.
+
 Context files are generic JSON envelopes for caller-supplied task metadata, artifacts, instructions, and verification commands.
 
 ## Current Tools