Add canonical tool policy vocabulary

Cargo.toml

@@ -14,7 +14,7 @@ exclude = ["worktrees"]
 # true`, so the version the release workflow bumps is written in exactly one
 # place and every crate moves together.
 [workspace.package]
-version = "0.1.0"
+version = "0.2.0"
 edition = "2024"
 rust-version = "1.88"
 license = "GPL-3.0-only"

README.md

@@ -34,7 +34,7 @@ re-export the macro. Add it as a direct dependency alongside `tinytools`:
 
 ```toml
 [dependencies]
-tinytools = "0.1"
+tinytools = "0.2"
 async-trait = "0.1"
 ```
 
@@ -60,6 +60,7 @@ compiles neither the harness nor the host.
 | `spec` | `ToolSpec` — the declaration a model is shown |
 | `permission` | `PermissionLevel` — the privilege ladder, ordered `None` → `Dangerous` |
 | `classification` | `ToolScope`, `ToolCategory` — where a tool may run, and which belt it is on |
+| `policy` | `ToolPolicy`, `ToolRuntime`, `ToolAccess`, `ToolSideEffects`, `WorkspaceAccess`, `ToolDisplay` — declarative execution requirements and presentation metadata |
 | `call` | `ToolCallOptions`, `ToolTimeout` — per-invocation inputs that are not arguments |
 | `context` | `ToolRunContext` — the narrow seam onto a live run |
 | `workspace` | `WorkspaceDescriptor`, `SandboxMode` — the root a tool may touch, and how strictly it is sandboxed |
@@ -110,6 +111,32 @@ Two consequences worth knowing:
   point. Overriding only `external_effect` on a tool whose classification
   depends on its arguments leaves the per-call case unhandled.
 
+`Tool::policy()` carries the complete declarative form for hosts that need a
+single auditable projection: side effects, runtime requirements, access
+requirements, and display metadata. It defaults to unclassified; a host may
+therefore reject undeclared tools without TinyTools making an admission decision.
+The policy is descriptive only. It never enforces approval, credentials,
+sandboxing, cancellation, deadlines, retries, workspace containment, or result
+limits.
+
+`ToolTimeout` has three stable JSON forms:
+`{ "mode": "inherit" }`, `{ "mode": "unbounded" }`, and
+`{ "mode": "millis", "timeout_ms": <u64> }`. Policy field names and omission
+rules are likewise wire contracts for persisted policy and registry
+introspection; literal-wire tests pin every timeout variant and a fully
+populated policy declaration.
+
+## Injected arguments and call identity
+
+`ToolCall` / `ToolCallId` carry a model request's identity outside
+`ToolResult`, where a harness can correlate it with its own events and elapsed
+time. `Tool::injected_arguments()` declares schema keys owned by either the
+host or the call id. A harness uses `project_injected_arguments` for the
+model-facing schema, then runtime-only `InjectedToolArguments` and
+`prepare_tool_arguments` to strip model-supplied protected values, inject the
+authoritative values, and validate the returned object. Host values are never
+serialized or exposed to the model.
+
 ## Development
 
 ```bash

crates/tinytools-agent/Cargo.toml

@@ -14,7 +14,7 @@ readme = "README.md"
 regex = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
-tinytools = { path = "../tinytools", version = "0.1.0" }
+tinytools = { path = "../tinytools", version = "0.2.0" }
 tracing = { workspace = true, optional = true }
 
 [features]

crates/tinytools/Cargo.toml

@@ -7,7 +7,7 @@ license.workspace = true
 repository.workspace = true
 description = "The agent tool vocabulary: the `Tool` trait, its result and spec types, and the permission, scope and timeout classifications a host enforces around a call."
 documentation = "https://docs.rs/tinytools"
-readme = "../../README.md"
+readme = "README.md"
 keywords = ["llm", "agents", "tools", "tool-calling"]
 categories = ["asynchronous", "api-bindings"]
 

crates/tinytools/README.md

@@ -0,0 +1,102 @@
+# TinyTools
+
+`tinytools` is the dependency-light vocabulary shared by a tool implementation
+and the host or harness that runs it. Its primary entry points are `Tool`,
+`ToolSpec`, `ToolResult`, `ToolRunContext`, and `ToolPolicy`.
+
+```rust
+use tinytools::{Tool, ToolPolicy, ToolResult};
+
+struct Echo;
+
+#[async_trait::async_trait]
+impl Tool for Echo {
+    fn name(&self) -> &str { "echo" }
+    fn description(&self) -> &str { "Returns its input unchanged." }
+    fn parameters_schema(&self) -> serde_json::Value {
+        serde_json::json!({
+            "type": "object",
+            "properties": { "text": { "type": "string" } },
+            "required": ["text"],
+        })
+    }
+    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
+        let text = args.get("text").and_then(|value| value.as_str()).unwrap_or_default();
+        Ok(ToolResult::success(text))
+    }
+    fn policy(&self) -> ToolPolicy {
+        ToolPolicy::read_only()
+    }
+}
+```
+
+## Public contract
+
+`Tool` describes a callable capability. Its result is a `ToolResult` block list
+with a reported-error flag and optional markdown rendering. `ToolSpec` is the
+model-visible declaration. `ToolRunContext` exposes only tool-relevant run
+facts: workspace, thread id, and output cap.
+
+`ToolPolicy` is the complete host-readable declaration around a call:
+
+- `ToolSideEffects` records filesystem, network, dependency, destructive,
+  external-service, payment, and read-only effects.
+- `ToolRuntime` records deadline, retry, idempotency, cancellation, sandbox,
+  result-size, and streaming requirements.
+- `ToolAccess` records workspace reach, trusted roots, credential names,
+  approval, and background-safety requirements.
+- `ToolDisplay` supplies optional timeline/audit label and detail text.
+
+`Tool::policy()` defaults to an unclassified declaration. A host that admits
+tools fail-closed can refuse that default. The policy is descriptive only:
+TinyTools does not enforce approvals, credentials, workspace containment,
+sandboxing, cancellation, deadlines, retries, or result limits.
+
+## Injected arguments and call identity
+
+`ToolCall` and its `ToolCallId` carry the identity of one parsed model request.
+That identity is invocation metadata, not a `ToolResult` field, so a harness can
+correlate events and results without mutating tool-owned output.
+
+A tool declares host-owned schema keys with `Tool::injected_arguments()`, using
+`ToolInjectedArgument::host` or `ToolInjectedArgument::tool_call_id`. The host
+uses `project_injected_arguments` for the model-facing schema, keeps
+authoritative values in runtime-only `InjectedToolArguments`, and calls
+`prepare_tool_arguments` before schema validation. The helper strips the
+model-supplied protected keys, inserts authoritative values, and returns the
+object to validate. It never serializes host values, and it ignores values for
+undeclared keys. This ordering prevents a model from forging a protected
+argument while keeping model arguments model-owned.
+
+`ToolTimeout` is serializable and has exactly three wire forms:
+
+| Rust value | JSON |
+| --- | --- |
+| `ToolTimeout::Inherit` | `{ "mode": "inherit" }` |
+| `ToolTimeout::Unbounded` | `{ "mode": "unbounded" }` |
+| `ToolTimeout::Millis(250)` | `{ "mode": "millis", "timeout_ms": 250 }` |
+
+All policy vocabulary uses the documented serde field names. These forms are
+part of the public persistence and introspection contract; change them only
+with an intentional compatibility migration and updated literal-wire tests.
+`ToolCall` and `ToolInjectedArgument` are likewise serialized vocabulary;
+`InjectedToolArguments` intentionally is not, because it may hold credentials.
+
+## Boundaries
+
+TinyTools has no registry, dispatch loop, provider transport, runtime, or agent
+harness dependency. `tinytools-agent` owns model-facing tool-call parsing,
+dialects, catalogues, rendering, and transcript replay. Hosts own execution and
+all policy decisions.
+
+## Development
+
+```sh
+cargo fmt --all -- --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo build --all-targets --all-features
+cargo test --all-features
+```
+
+`Tool` implementations require a direct `async-trait` dependency because the
+crate uses the macro internally but does not re-export it.