feat(grid-agent): enforce central action policy (#120)

docs/grid-agent-architecture.md

@@ -26,6 +26,8 @@ handles, the control sender, and observable receiver.
 | Conversation / tool calls | request owner | 256 messages / 64 calls, with lower configured limits | rejected before request |
 | LLM request slots | shared `LlmClient` semaphore | 256 hard / configured concurrent requests | async acquire or cancellation |
 | Reasoning/tool session | `ToolLoop` caller | 32 turns / 256 calls hard, with lower configured limits | total timeout, cancellation, or supersession |
+| Policy tools / approvals / schedules | `PolicyGateway` mutex | 64 tools / 4,096 approval records / 1,024 scheduler grants hard | deny before opaque authorization |
+| Principal/global resource budget | `PolicyGateway` time window | validated calls, zero L$, upload, inventory, movement, and build ceilings | atomic charge or stable denial |
 | Authorized avatars | immutable `AgentConfig` set | 1,024 hard ceiling, lower configured limit | malformed, nil, duplicate, and wildcard input rejected |
 | Configuration / secret file | loader | 64 KiB / 16 KiB | regular non-symlink file only |
 
@@ -65,7 +67,8 @@ shutdown.
   The `live-grid` feature supplies `LibremetaverseClientOwner`; live
   implementations must own it and reuse its client and managers.
 - World changes cross only `WorldMutator::apply`, which always receives the
-  proposed call and an explicit `PolicyDecision`. This issue supplies no live
+  non-forgeable `AuthorizedAction` produced by `PolicyGateway`. Raw calls and
+  caller-created decisions are not accepted. This issue supplies no live
   mutation implementation.
 - LLM traffic crosses one exact configured URL through `LlmClient`. Redirects
   are refused, response bodies are bounded while streaming, bearer secrets are
@@ -89,7 +92,9 @@ typed config/events/policy boundaries    live-grid feature boundary
 
 avatar session -> bounded ToolLoop -> exact-endpoint LlmClient
                        |
-                       +-> validated ToolExecutor boundary
+                       +-> PolicyToolExecutor -> PolicyGateway
+                                                   |
+                                                   +-> AuthorizedToolBackend
 ```
 
 The package has no build script or direct native dependency. The focused
@@ -97,3 +102,5 @@ The package has no build script or direct native dependency. The focused
 source, build scripts, and unreviewed direct dependency names in this package.
 The precise LLM compatibility and cancellation contract is documented in
 [`grid-agent-llm.md`](grid-agent-llm.md).
+The origin/capability matrix and opaque mutation boundary are documented in
+[`grid-agent-policy.md`](grid-agent-policy.md).

docs/grid-agent-policy.md

@@ -0,0 +1,80 @@
+# Grid-agent authorization and safety policy
+
+Every production tool action crosses `PolicyGateway` and then
+`PolicyToolExecutor`. The gateway is deny-by-default: a tool must be registered
+with its typed argument schema, capability, read/write risk, allowed origins,
+maximum resource cost, deterministic cost estimator, idempotency,
+approval rule, and scheduler eligibility. A tool description is model context,
+not authority, and is never consulted by policy.
+
+## Identity and origin matrix
+
+Grid authority comes only from the sender UUID carried by the grid event.
+Names, message bodies, UUID text embedded in messages, and tool arguments cannot
+select an origin. Local-operator principals can only be constructed by the
+crate's authenticated control-plane boundary. Scheduler contexts require an
+opaque grant previously issued from an authorized IM or operator action.
+
+| Origin | Informational read | Public LSL delivery capability | Allow-listed mutation | Scheduled action |
+| --- | --- | --- | --- | --- |
+| Public chat, including an authorized avatar | yes | yes | no | no |
+| Unprivileged IM | yes | no | no | no |
+| Authorized IM | when registered | when registered | when registered | may create an exact grant |
+| Authenticated local operator | when registered | when registered | when registered | may create an exact grant |
+| Internal scheduler | exact grant only | no | exact grant only | bounded runs and expiry |
+
+The public LSL capability is a narrow inventory-mutation marker for the later
+script-delivery workflow; it does not permit executing generated code or any
+other public command. Tool names are exact ASCII identifiers, so case changes,
+newlines, smuggled names, and Unicode confusables do not resolve to registered
+tools.
+
+## Approvals and budgets
+
+Arguments are parsed again at the gateway and must equal the arguments bound to
+the proposed call. Canonical JSON is SHA-256 hashed. An approval binds that
+hash, exact tool, requesting principal, expiry, and one execution. Changed
+arguments, another principal, an ungranted/expired approval, or a replay is a
+stable denial. Authorization is represented by non-cloneable
+`AuthorizedAction`, whose fields have no public constructor; action backends
+cannot accept a raw call plus a caller-created decision.
+
+Each authorized attempt atomically charges a configured time-window budget for
+both the originating principal and the whole agent. The resource vector covers
+tool-call rate, L$, upload bytes, inventory operations, movement millimetres,
+and build prims. Hard ceilings validate configured budgets and per-tool maximum
+costs. This milestone fixes every L$ budget at zero and refuses registration or
+execution for currency spend, estate/parcel changes, permanent deletion,
+arbitrary inventory acceptance, and generated-code execution.
+
+Scheduler grants preserve the originating principal and bind one tool and
+argument hash. Run count and lifetime are bounded; every run is charged again.
+The opaque `PolicySnapshot` preserves budgets, approvals (including consumed
+replay state), and scheduler grants when a trusted persistence integration
+reconstructs the gateway. No durable policy store is enabled by the current
+offline service; a future store must protect snapshot integrity rather than
+accept caller-authored approval data.
+
+## Prompt and audit boundaries
+
+Chat, IM, inventory metadata, object text, parcel data, web/LLM output, and
+generated scripts use `UntrustedData`. It emits a bounded labelled JSON data
+record and never contributes system instructions or tool availability. This is
+defence in depth: authorization is still enforced after inference at the exact
+gateway.
+
+Every decision emits a bounded structured `PolicyAuditRecord` before an action
+is authorized. It contains origin class and UUID where applicable, principal,
+session/correlation IDs, exact tool, disposition, stable reason code, applied
+budget, an argument hash, and outcome. The executor emits the completed,
+rejected, failed, or ambiguous final outcome. Raw/secret arguments and hidden
+reasoning are never stored. Audit backpressure fails closed before issuing a
+new authorization.
+
+Focused verification:
+
+```sh
+cargo test --locked -p metacrate-grid-agent --lib policy_tests
+cargo test --locked -p metacrate-grid-agent --test policy_gateway
+cargo clippy --locked -p metacrate-grid-agent --all-targets -- -D warnings
+```