git:20261107.4268891 to git:20261109.d9346bf

11 added, 0 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

# Policy Agent Guidance
For `crates/policy/**`. Follow the repository-root `AGENTS.md` first.
- This crate is interface-frozen: the `pub use` façade, and the authored vocabulary of action
names, readable attributes, and what `when temporal { … }` observes. An operator's policy file is
their source code.
- Fix the Box integration, the schema, and the event mapping behind the façade without approval.
- `dogwood-language` and `dogwood-local-engine` are published crates, pinned at `=1.0.0`.
- Close a gap listed here; never widen one. Never delete or `#[ignore]` a test that pins one.
## Read This First: Durable Dogwood History
- The engine is Dogwood: the published `dogwood-language` and `dogwood-local-engine` crates.
Cedar's authorizer is deleted. Issue #59 lists what 1.0.0 lacks and where the box covers it.
- The code and its tests own the commit, recovery, policy-change, and time contract.
[History is durable per box](../../docs/design/decisions.md#history-is-durable-per-box-and-has-no-rewind)
records why. Do not restate that contract here.
## Sources Of Truth
- Behaviour and the durability contract: `src/**` and `tests/**`.
- Decisions: [`docs/design/decisions.md`](../../docs/design/decisions.md). Its entries on
[the engine](../../docs/design/decisions.md#the-engine-is-dogwood),
[durable state](../../docs/design/decisions.md#history-is-durable-per-box-and-has-no-rewind),
[temporal enforcement](../../docs/design/decisions.md#temporal-rules-are-enforced-against-recorded-history), and
[the public surface](../../docs/design/decisions.md#the-policy-crate-exposes-one-facade) record why.
- Rewrite a decision entry when its answer changes, as the root guidance requires.
## Public Contract Discipline
- The lifecycle is `PolicyEngine::open` → `decide` → `record` → `effective`.
`PolicyEngine::validate` and `PolicyEngine::check` sit off it and return no authority.
- The root `pub use` set is the whole API: `EgressPolicyInterceptor`, `RenameDestination`,
`ScriptPermit`, `ScriptPolicyInterceptor`, `ScriptRefusal`, `ShellPolicyInterceptor`,
`CatalogRefusal`, `CatalogStage`, `CompleteCatalog`, `DiscoveryFailure`, `ListPage`,
`MAXIMUM_LIST_BYTES`, `MAXIMUM_LIST_PAGES`, `McpServerKind`, `ServerDiscovery`, `ToolCatalogs`,
`Finding`, `Location`, `PolicyCheck`, `RuleRef`, `Decision`, `DenyReason`, `PolicyAttribution`,
`RuleId`, `event_schema_source`, `PolicyDiagnostic`, `PolicyError`, `PolicyStagingError`,
`McpSchemaError`, `compose_action_schema`, `generate_mcp_schema`,
`validate_mcp_schema_composition`, `DecisionObserver`, `Delivery`, `FsResult`, `Outcome`,
`ApprovedPath`, `PathRefusal`, `PathResolver`, `ENGINE_ID`, `EffectivePolicy`, `Policy`,
`PolicyEngine`, `SELF_DEFENDED_FILES`, `SchemaStage`, `FsAccess`, `FsOperation`, `Principal`,
`Request`, `RequestId`, `GovernedBox`, `Operator`, `PolicyWarning`, `ToolGrammar`, `ToolGrammars`,
`ToolGrammarError`, `GrammarBindings`, `BindingRefusal`. That is 58 names with `--all-features`
and 52 by default; recompute it when you touch the façade.
- `check` and `validate` share one composition (`check_and_expand`), and the staged check repeats
the steps of `open_staged_with_engine` with no engine. A finding keeps a span only when the span
is an offset into the authored text: a Dogwood parse error and a Cedar validation error over
the complete set. Box's own checks and every staged validation name rules and carry no span,
because Dogwood exposes no span for a parsed rule. Keep `tests/policy_check.rs`
`a_check_refuses_exactly_what_open_refuses` and
`a_staged_check_refuses_exactly_what_open_staged_refuses`.
- Keep modules private. Keep every `dogwood_language` and `cedar_policy` type out of the façade.
- Keep `cedar-policy = "=4.11.0"` exact: the schema and the request gate are Cedar types, and
Dogwood's own constraint is a caret range.
- `decide` and `record` take the `GovernedBox` as integration metadata. Assign that name from the
endpoint you own; never read it from a request.
- `decide` is not a pure query: it observes the request into history first, so a denied request
can advance history. The code and its tests own the exact verdict contract.
- Retain the confirmed `RequestId` from `decide` for each corresponding `record` call.
Refuse an ordinary effect if its allow verdict has no token.
- One resource entity, `Box::Resource`, always uses the id `"unused"`. It carries no policy
information, so a rule discriminates on the action and `context.input`.
- One principal, `Box::Agent`, always uses the id `"self"`. `Principal::with_id` retains integration
metadata and does not change the policy identity.
- One `PolicyEngine` per run and one history file per box provide structural box isolation.
Authored policy cannot discriminate on a box name.
- `PathResolver` is the only public minter of an `ApprovedPath`.
- `validate`'s caller is `read_authored_policy`, through `ConfigureRequest::load`, for `run` and
`init`. Unvalidated, a bad policy exits 0 and fails at the next `run`. Keep
`box/tests/box_lifecycle.rs::create_refuses_a_policy_the_engine_cannot_load` and
`validation_accepts_and_refuses_exactly_what_open_does`.
- Do not reintroduce `PolicyConfig`, `ContainmentScope`, `containment_config`, `PolicyMode`, or
`Remediation` without an entry in [`decisions.md`](../../docs/design/decisions.md). Add a public
extension point only after
[an external consumer is named](../../docs/design/decisions.md#the-policy-crate-exposes-one-facade).
## Internal Ownership
- `policy.rs` the lifecycle. `dogwood.rs` the private engine, event mapping, scope lock, and clock.
`schema.rs` the `.cedarschema`, the name constants, and the request gate. `request.rs`,
`outcome.rs`, `decision.rs`, `error.rs`, `check.rs` their public types. `path.rs` the path types.
`adapters/` one module per enforcement point, each behind its own feature.
- Put a new boundary in `adapters/`, not in a new root file. Keep a method with its type.
## Fail-Closed Invariants
- `open` returns an authority only after the engine's `Validator` strict-validates; `lower()` alone
accepts a typo'd action. An unrecognized action is `PolicyError::UnknownAction`.
- Abort loading when `uses_providers()` is true.
- Keep the schema request gate in `decide`, although no caller reaches it today.
- Keep production timestamps on the durable engine's trusted system wall clock.
`FixedClock` and `open_with_test_clock` are test-only.
- Keep `decide` infallible, and preserve its verdict contract.
- Preserve the startup refusal: `open` never returns an authority on empty or partial history.
- Deny a poisoned scope lock as `DenyReason::InternalFault`. Never call `into_inner()`.
- Grant only on `Decision::Allow`, and only with empty `diagnostics().errors()`.
- Never discard a `record` error.
- Treat `EffectivePolicy::policy_id` as diagnostic, not as an attested digest.
- An adapter may narrow a verdict and must never manufacture `Allow`.
- Absent policy is deny-by-default.
- Leave containment, credentials, and network enforcement to their owners.
## Known Limits — State These, Do Not Silently Work Around Them
- Declare context under `input`. A flat `context` makes `context has path` statically false, so a
rule loads and never fires.
- The request gate has no externally-constructible non-conformance case; see
`tests/readme_examples.rs::a_conforming_request_reaches_a_catch_all_permit`.
- A temporal predicate cannot name an action group, and offers no `or` and no wildcard, so write
one clause per granular action. The spellings are `shell:exec`, `http:request`, and `mcp:call`.
Do not reintroduce a group action.
- Key a precondition on `::response`, because a `::request` predicate matches a denied attempt.
Pinned by `tests/temporal_shell_e2e.rs::a_denied_attempt_satisfies_a_request_keyed_precondition`.
- History is pruned to the deepest window, and the workload fills that window. State an
availability bound.
- Pin a destination on `host` and `port`, and refuse an address with a `forbid` on the string `ip4`
or `ip6`. Each needs its own `has` guard, so a rule that covers both families has one clause for
each.
- `context.input.path` also carries a URL path, so a rule that reads `context.input` names actions
of one family, and the load refuses any other
(`spelling::refuse_input_across_families`). Pinned by
`tests/path_spelling.rs::a_filesystem_path_rule_stays_off_an_http_request_with_the_same_path`.
The check runs before strict validation and in `validate_staged`, so a rule that reads the input
across a tool action and another family is refused, not parked; a rule scoped to one tool action
loads. Pinned by
`tests/runtime_mcp_policy_staging.rs::a_rule_that_reads_the_input_across_a_tool_action_is_refused_before_its_schema_stages`.
- An MCP union argument reads as its generated `typeChoice` record. `ToolInputs::conform` places a
bare value in every member it matches, before the request gate and the event, so a rule on a
duplicate member still fires. It refuses a value that matches none, including a value already in
the record shape. A record whose fields
are all named `typeChoice<N>` is read as a union, so an object property with that name is too.
A `null` matches no member. A `datetime`, `ipaddr`, `decimal`, or `duration` member takes a
string that Cedar's constructor accepts. The Dogwood event still carries that value as a string,
so a rule that compares it fails evaluation and denies, as it does for a non-union argument.
Pinned by
`mcp_schema::tests::a_union_argument_accepts_each_member_and_refuses_a_non_member` and
`tests/runtime_mcp_policy_staging.rs::a_union_argument_is_decided_by_the_policy` and
`a_datetime_union_member_is_placed_and_its_rule_cannot_be_bypassed`.
+ - A per-tool rule keeps its history across a restart only when its head names per-tool actions
+ alone. `commit_discovering` keeps it installed under the server fragments that
+ `mcp_schema::mcp_schemas_in` recovers from the stored action schema. The tools it decides stay
+ held until their schemas stage. A rule with a Box head that reads per-tool history, and a rule
+ whose server never lists in that run, start fresh. Pinned by
+ `tests/runtime_mcp_policy_staging.rs::a_rule_that_names_a_tool_keeps_its_history_across_a_restart`,
+ `::a_rule_that_names_two_servers_keeps_its_history_while_they_list_one_at_a_time`,
+ `::a_rule_that_decides_a_box_action_from_tool_history_is_not_kept_from_the_previous_run`, and
+ `::a_server_that_never_lists_its_tools_unloads_the_kept_rule`. A namespace that this build's
+ base schema declares is never read as a server, which
+ `mcp_schema::tests::a_previous_build_of_the_box_actions_is_not_read_as_a_server` pins.
- `body_bytes` is the offer on a `::request` and the delivery on a `::response`.
- Sum an outbound budget over `http:request::response`, as `tests/policies/egress_byte_budget.dw`
does. One exchange records one such event, at reply time, with the delivered request bytes and
the reply's `output.status`. Pinned by
`tests/temporal_egress_budget.rs::a_reply_adds_nothing_to_an_outbound_budget`.
- An outcome-only fact reaches history through the event kind (`response` vs `error`); every filesystem response also carries `output.result`.
- Do not extend a durability, audit, atomicity, or performance claim past what the tests
pin.
## Documentation Boundaries
- `README.md` serves a Rust consumer. Extend `tests/readme_examples.rs` with each example, and
apply the `docs-writer` skill there. Keep workflow, structure, and review rules here.
## Change Checklist
1. Read the relevant entries in
[`decisions.md`](../../docs/design/decisions.md).
2. Reconcile the public names across the code, the tests, and `README.md`.
3. Run `build`, `test`, `clippy --all-targets`, and `fmt --check` for `-p strands-box-policy`, each
with and without `--all-features`, plus `RUSTDOCFLAGS="-D warnings" cargo doc`. Vendored
clippy warnings from `strands-shell` are expected; policy-owned warnings must be zero.
4. Give a temporal change a long-run test, because a short one passes on a sawtooth.
5. Run `feature-critic` before you commit. Keep `Cargo.lock`, `egress-gateway`, and `credentials`
unchanged.
## Measured fail-opens and footguns
- LIVE GAP: the Script boundary resolves lexically, so a read through a symlink and a rename onto
an aliased destination each evade a rule. Containment is the only control. Pinned by
`tests/policy_script_fs_e2e.rs::script_symlink_aliasing_is_not_defended`. To close it, resolve a
rename's source and its destination's final component no-follow and the destination's parents follow, and resolve through Monty's mount table,
never with `std::fs::canonicalize`.
- LIVE GAP: `approve_host`'s refusal variant shows whether a host path exists: a path through a
live symlink at any component is `NotCanonical` and one through a dangling symlink `Unresolvable`,
and a plain path outside every root is `Unresolvable` when its parent is missing and `Unreachable`
when it is not. This is the existence-oracle class on host binds. Give one reason for every
refusal of a path the caller may not reach.
- LIVE GAP: `like` is case-sensitive and macOS is not, so `policy.DW` stays exposed. Do not widen
the pattern to `*.dw`, which over-denies an ordinary `.dw` file.
- `SELF_DEFENDED_FILES` is `["box.toml", "policy.dw"]`, and it is public so tests and
`box/src/define/layout.rs` derive from it. Add no `*.cedar` rule and no speculative entry. A
defended filename costs an escalation chain, as `mcp.toml` did.
- Raise three legs for a `FilesystemPair`: the source as the pair operation, the source as
`fs:read_content`, and the destination. Do not reduce it to two. A rename whose destination
exists raises a fourth, `fs:delete` on the destination, because the rename removes what it held.
- Shell outbound HTTP raises no attempt, so policy does not cover it and only the deny-only
`network_enabled` switch and SSRF floor do. Do not decide egress in the Shell adapter. The MCP
`shell` tool reaches `run_pipeline`, so it does raise `shell:exec`.
- A degraded tool recovers only when a complete bundle commits: a late list whose schema is the last
thing the bundle needs, or a reload. `stage_mcp_schema` and `reload` clear the whole
`degraded_tools` set then, so one commit lifts every hold, on every server. While anything else is
missing — a second schema, or a staged schema that does not match its rule — a late list is
`Rejected` and its fragment goes out with the proposal that held it, so two missing schemas
recover neither server. Closing that would mean retaining an accepted fragment across a rejected
bundle — the partial install that only `Discovering` allows — so do not widen the clear to reach
it. Clear nothing on `Rejected`, because a cleared tool whose action is undeclared rides the
coarse `mcp:call` grant past its `forbid`. Pinned by `runtime_mcp_policy_staging.rs`
`::a_complete_bundle_after_completion_clears_the_degraded_mark`,
`::a_late_list_that_supplies_the_last_schema_recovers_both_servers`,
`::two_missing_schemas_do_not_recover_from_a_relist`,
`::a_late_list_is_refused_while_a_staged_schema_does_not_match_its_rule`, and
`::a_late_list_refused_for_a_namespace_collision_keeps_the_degraded_mark`, and by
`policy.rs::a_degraded_tool_stays_denied_until_a_reload_drops_its_rule`. The `Rejected` exit for a
refused durable commit needs an exhausted store, and no test pins the mark there.
- Record an outcome this vocabulary cannot name as `Indeterminate`; never drop it.
- Refuse `os.getenv` and `os.environ` while the schema cannot name them, because the box projects
credential phantoms into the environment. Pinned by
`an_environment_read_is_refused_while_the_schema_cannot_name_it`.
- Refuse `Mkdir` with `parents == true`, because `ScriptPermit` cannot bound the ancestors.
- Keep `classify` exhaustive. If upstream marks `OsFunctionCall` `non_exhaustive`, add `_ => None`,
denied.
- Keep `Admitted::Clock` bounded to `date.today()` and `datetime.now()`, decided by nobody and
recorded nowhere.
- Map `Stat`, `Exists`, `IsFile`, `IsDir`, and `IsSymlink` to `fs:read_metadata`. The
vocabulary does not separate follow from no-follow.
- Do not align the Script adapter with upstream `monty-dogwood`, which leaves an unmapped call
ungated and authorizes the caller's spelling. Deny an unmapped call, and normalize before you
decide.
- Fill both the logged event and Cedar request context for input data read by both policy types.
Use `EventBuilder::logged_field` alone for reserved history fields such as `requestId`.
- Keep both saturations deny-ward: `Clock::now()` to 0, and `clamp(bytes)` to `i64::MAX`.
- A dropped `ScriptPermit` submits `FsResult::Indeterminate` from `Drop`. Keep `#[must_use]`, claim
`reported` before you submit, and discard a `Drop` recording failure. `EffectPermit` and
`KernelPermit` mirror it.
- The engine differential is deleted with Cedar (528 verdicts, 0 divergences). It caught the
missing request gate (32 verdicts), so the gate lives in `decide`.
- Parse the schema at `open`, never lazily: a lazy parse costs the first call ~1.5 ms and turns a
load error into a first-request deny. `cached_uid` saves ~7 µs per verdict and still yields
`PolicyError::Schema`.