Add declarative tool rules (allow/deny/hide/approval)

AGENTS.md

@@ -31,6 +31,7 @@ crates/
         ├── context/        # `ToolRunContext`
         ├── progress/       # `ToolProgress`, `ProgressSink`
         ├── naming/         # rendering a call for a human
+        ├── rules/          # `ToolRules`: declarative allow/deny/hide/approval rules
         └── shared/         # `SharedTool`: an `Arc<dyn Tool>` as an owned belt entry
                             # each: mod.rs / types.rs / mod_tests.rs
 docs/

README.md

@@ -68,6 +68,7 @@ compiles neither the harness nor the host.
 | `naming` | `humanize_tool_name`, `context_detail_from_args` — rendering a call for a human |
 | `shared` | `SharedTool`, `share_belt`, `owned_belt` — one built `Arc<dyn Tool>` handed out as many owned `Box<dyn Tool>` belts, forwarding every trait method |
 | `rank` | `ToolRanker`, `RankCandidate`, `RankHit`, `Bm25Ranker` — ranking a catalogue of tools against an intent, with the lexical ranker built in |
+| `rules` | `ToolRules`, `ToolRuleSet`, `ToolRule`, `ToolSubject`, `RuleDecision` — declarative allow / deny / hide / approval rules over tools, evaluated by a harness on the catalogue, search and call surfaces |
 
 The workspace also contains `tinytools-agent`, a separate crate for
 model-facing tool-call parsing, dialects, catalogue/result rendering, and

crates/tinytools/src/lib.rs

@@ -116,6 +116,7 @@ pub mod policy;
 pub mod progress;
 pub mod rank;
 pub mod result;
+pub mod rules;
 pub mod shared;
 pub mod spec;
 pub mod tool;
@@ -148,6 +149,11 @@ pub use rank::{
     Bm25Index, Bm25Ranker, RankCandidate, RankContext, RankError, RankHit, ToolRanker, tokenize,
 };
 pub use result::{FileData, ImageData, ToolContent, ToolControl, ToolErrorKind, ToolResult};
+pub use rules::{
+    ApprovalDirective, ArgMatcher, DefaultEffect, IndirectCall, Patterns, RuleContext,
+    RuleDecision, RuleEffect, RuleRef, SideEffect, Surface, ToolMatcher, ToolRule, ToolRuleSet,
+    ToolRules, ToolSubject, glob_matches,
+};
 pub use shared::{SharedTool, owned_belt, share_belt};
 pub use spec::ToolSpec;
 pub use tool::{Tool, ToolExposure};

crates/tinytools/src/rules/README.md

@@ -0,0 +1,50 @@
+# `rules`: declarative tool rules
+
+Allow, deny, hide and approval rules over tools, written by a host and
+evaluated by a harness on every surface a tool reaches the model on.
+Specification: [`docs/specs/tool-rules.md`](../../../../docs/specs/tool-rules.md).
+
+## Design
+
+A host restricts tools from many places, such as an agent's allowlist, a
+channel's permission ceiling, an MCP server filter or a connector's curated
+actions. This module gives all of them one vocabulary. It holds **no policy**:
+the rules are data the host writes, and evaluation is mechanical. That is the
+same line `deferral` draws.
+
+| File | Holds |
+|---|---|
+| `glob.rs` | `glob_matches`: `*` and `?`, ASCII case-insensitive, with no dependency |
+| `types.rs` | `ToolRule`, `ToolMatcher`, `ArgMatcher`, `ToolRules`, `ToolRuleSet`, `RuleContext`, `RuleDecision`, `RuleRef`, `ApprovalDirective` |
+| `subject.rs` | `ToolSubject`: what is evaluated, built from a live tool or by hand |
+| `eval.rs` | Evaluation of a rule, a layer, a set, and a concrete call |
+
+## Public surface
+
+- **`ToolRule`** has an effect (`allow`, `deny`, `hide`, `require_approval`,
+  `auto_approve`), the surfaces it applies on (`catalog`, `search`, `call`), a
+  `match`, an optional `except` carve-out, `when` context conditions, and an
+  `id` and `reason` for refusals.
+- **`ToolRules`** is one layer with a default. Inside a layer, effects combine
+  without regard to order:
+  - `deny` wins.
+  - With a `deny` default, a tool needs a matching `allow`.
+  - `hide` only clears visibility on the listing surfaces.
+  - `require_approval` beats `auto_approve`.
+- **`ToolRuleSet`** stacks layers, and every layer must admit a tool. Adding a
+  layer can only narrow, so two allowlists intersect.
+- **`ToolRuleSet::evaluate_call`** evaluates a call with the tool's
+  argument-aware permission. When the tool reports an `indirect_target`, an
+  `IndirectCall { target, arguments }`, it evaluates that target too. It uses
+  the target's own arguments when the dispatcher wraps them in an envelope, so
+  an argument-scoped rule cannot be sidestepped through the dispatcher.
+
+## Operational constraints
+
+- A matcher field naming an attribute the subject does not know does not
+  match. That fails open for `deny` and closed for `allow`, so evaluate
+  against the live tool wherever you have one.
+- Off the call surface an `arg` condition cannot be decided. An `allow` reads
+  it optimistically and every other effect does not apply.
+- A wrapper tool must forward `tags` and `indirect_target`, as `SharedTool`
+  does. Otherwise tag rules miss and a dispatcher's target escapes its rules.