refactor: take the tool vocabulary from tinytools

.github/workflows/ci.yml

@@ -21,6 +21,11 @@ jobs:
           # This job executes repo code (cargo build/test); don't persist the
           # token in git config.
           persist-credentials: false
+          # `vendor/tinytools` is a path dependency of this crate, so cargo
+          # cannot even resolve the manifest without it. Without this the build
+          # fails at `Updating crates.io index` with "failed to read
+          # vendor/tinytools/crates/tinytools/Cargo.toml".
+          submodules: recursive
 
       - uses: dtolnay/rust-toolchain@stable
         with:

.github/workflows/release.yml

@@ -31,6 +31,8 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
+          # Required to resolve the `vendor/tinytools` path dependency.
+          submodules: recursive
 
       - uses: dtolnay/rust-toolchain@stable
         with:

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "wiki"]
 	path = wiki
 	url = https://github.com/tinyhumansai/tinyagents.wiki.git
+[submodule "vendor/tinytools"]
+	path = vendor/tinytools
+	url = https://github.com/tinyhumansai/tinytools.git

Cargo.toml

@@ -11,6 +11,24 @@ categories = ["asynchronous", "api-bindings"]
 
 [dependencies]
 async-trait = "0.1"
+# The tool vocabulary. This crate re-exports the host-facing naming/context
+# helpers (`humanize_tool_name`, `context_detail_from_args`, `WorkspaceDescriptor`,
+# `SandboxMode`, …) rather than declaring its own copies, so a host and this
+# harness read a tool's workspace root and display name identically.
+#
+# `harness::tool::Tool<State>` itself stays a distinct, harness-owned trait —
+# it is generic over application `State` and its signature carries this
+# crate's own model-facing dialect types (`ToolCall` / `ToolResult` /
+# `ToolPolicy` / `ToolTimeout`), which are a deliberately separate concern from
+# `tinytools::Tool`'s host-facing shape. The interop point is
+# `ToolExecutionContext` implementing `tinytools::ToolRunContext` (below in
+# `harness::tool::types`), which lets a tool read its workspace descriptor
+# without this crate naming `ToolExecutionContext` inside `tinytools` (the
+# edge points one way: `tinytools` must never depend on this crate).
+#
+# Path-only for now, which is what stops this crate being published. Publishing
+# `tinytools` is the prerequisite; see that repository's AGENTS.md.
+tinytools = { path = "vendor/tinytools/crates/tinytools" }
 # Cheap, reference-counted byte buffers. Used only on the *internal* SSE
 # byte-stream seam (`harness::providers::openai::sse::SseState`) so each
 # network chunk from `reqwest::Response::bytes_stream` is forwarded without a

docs/modules/harness/workspace.md

@@ -112,17 +112,22 @@ assert_eq!(kinds, vec!["workspace.prepared", "workspace.cleanup"]);
 
 ## Fail-closed path enforcement
 
-Before a tool touches a path, call `WorkspaceDescriptor::enforce(path, &events)`.
+Before a tool touches a path, call `enforce_workspace_path(&ws, path, &events)`.
 It is a fail-closed gate: an allowed path returns `Ok(())` silently; a path
 outside every allowed root emits `AgentEvent::WorkspaceViolation { path }` and
 returns `TinyAgentsError::Validation`, so the caller blocks the operation.
 
+`WorkspaceDescriptor` is now `tinytools`' type — its lexical `allows()` check
+moved there with it — so the event-emitting half of the old `enforce()` method
+is a free function here instead of an inherent method on a foreign type.
+
 ```rust
+use tinyagents::harness::workspace::{WorkspaceDescriptor, enforce_workspace_path};
+
 let ws = WorkspaceDescriptor::new("/work/agent-a");
-ws.enforce(std::path::Path::new("/work/agent-a/out.txt"), &events)?; // allowed, no event
+enforce_workspace_path(&ws, std::path::Path::new("/work/agent-a/out.txt"), &events)?; // allowed, no event
 
-let err = ws
-    .enforce(std::path::Path::new("/etc/passwd"), &events)
+let err = enforce_workspace_path(&ws, std::path::Path::new("/etc/passwd"), &events)
     .expect_err("path outside root must be blocked");
 assert!(err.to_string().contains("outside the allowed workspace"));
 // A `workspace.violation` event was emitted for audit.

src/harness/tool/mod.rs

@@ -25,11 +25,19 @@ use serde_json::Value;
 use crate::error::{Result, TinyAgentsError};
 
 pub use error_policy::{ToolErrorPolicy, is_control_flow_error};
+// Rendering a tool call for a human is not harness-specific, and two copies of
+// the prefix list is how one of them silently stops stripping a prefix the
+// other does. The definitions live in `tinytools` so a host that never links
+// this crate still renders a tool name the same way.
 pub use injected::{project_injected_arguments, strip_injected_arguments};
 pub use prompt::*;
 pub use schema::*;
 pub use schema_prepare::*;
 pub use timeout::*;
+pub use tinytools::{
+    ContextDetailOptions, context_detail_from_args, context_detail_from_args_with,
+    humanize_tool_name,
+};
 pub use types::*;
 
 impl ToolSchema {
@@ -272,149 +280,6 @@ impl ToolPolicy {
     }
 }
 
-/// Derives a title-cased human-readable label from a raw tool name.
-///
-/// Common machine prefixes are stripped, and `snake_case` / `kebab-case` names
-/// become spaced labels. Degenerate names fall back to the original input so
-/// callers never receive an empty label unless the input itself was empty.
-pub fn humanize_tool_name(name: &str) -> String {
-    let trimmed = name
-        .strip_prefix("composio_")
-        .or_else(|| name.strip_prefix("mcp_"))
-        .unwrap_or(name);
-
-    let mut out = String::with_capacity(trimmed.len());
-    let mut capitalize = true;
-    for ch in trimmed.chars() {
-        if ch == '_' || ch == '-' {
-            if !out.is_empty() && !out.ends_with(' ') {
-                out.push(' ');
-            }
-            capitalize = true;
-        } else if capitalize {
-            out.extend(ch.to_uppercase());
-            capitalize = false;
-        } else {
-            out.push(ch);
-        }
-    }
-
-    let label = out.trim();
-    if label.is_empty() {
-        name.to_string()
-    } else {
-        label.to_string()
-    }
-}
-
-/// How a context detail is trimmed for display.
-///
-/// Exists because the cap and the ellipsis are **presentation**, and a host
-/// that renders tool activity in its own timeline has already picked both. The
-/// key-scanning rule underneath is what is actually shared; forcing a host to
-/// re-implement the whole function to change one character is how two copies of
-/// it end up in a codebase.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct ContextDetailOptions {
-    /// Maximum rendered length, in characters, including the ellipsis.
-    pub max_chars: usize,
-    /// Appended when the value is trimmed.
-    pub ellipsis: &'static str,
-}
-
-impl Default for ContextDetailOptions {
-    fn default() -> Self {
-        Self {
-            max_chars: 80,
-            ellipsis: "...",
-        }
-    }
-}
-
-/// Extracts a compact human-facing detail from common tool argument keys.
-///
-/// The first recognized scalar value wins, using keys that usually identify the
-/// resource being acted on (`path`, `query`, `to`, `url`, and similar). Returns
-/// `None` for non-object args, empty values, and complex values.
-///
-/// Uses [`ContextDetailOptions::default`]; see
-/// [`context_detail_from_args_with`] to choose the cap and ellipsis.
-pub fn context_detail_from_args(args: &Value) -> Option<String> {
-    context_detail_from_args_with(args, ContextDetailOptions::default())
-}
-
-/// [`context_detail_from_args`] with explicit trimming.
-pub fn context_detail_from_args_with(
-    args: &Value,
-    options: ContextDetailOptions,
-) -> Option<String> {
-    const CONTEXT_KEYS: &[&str] = &[
-        "to",
-        "recipient",
-        "recipient_email",
-        "to_email",
-        "email",
-        "query",
-        "q",
-        "search",
-        "search_query",
-        "url",
-        "file_path",
-        "path",
-        "command",
-        "cmd",
-        "subject",
-        "title",
-        "channel",
-        "channel_id",
-        "repo",
-        "repository",
-        "name",
-        "id",
-    ];
-
-    let obj = args.as_object()?;
-    for key in CONTEXT_KEYS {
-        let Some(value) = obj.get(*key) else {
-            continue;
-        };
-        if let Some(rendered) = render_context_value(value, options) {
-            return Some(rendered);
-        }
-    }
-    None
-}
-
-fn render_context_value(value: &Value, options: ContextDetailOptions) -> Option<String> {
-    let raw = match value {
-        Value::String(s) => s.trim().to_string(),
-        Value::Number(n) => n.to_string(),
-        Value::Bool(b) => b.to_string(),
-        Value::Array(items) => items
-            .iter()
-            .filter_map(Value::as_str)
-            .collect::<Vec<_>>()
-            .join(", "),
-        _ => String::new(),
-    };
-    let raw = raw.split_whitespace().collect::<Vec<_>>().join(" ");
-    if raw.is_empty() {
-        return None;
-    }
-    if raw.chars().count() > options.max_chars {
-        // Clamp the ellipsis itself to max_chars first: an ellipsis longer than
-        // the cap (a misconfigured caller) would otherwise survive
-        // `saturating_sub`'s zero and still get appended in full, pushing the
-        // rendered value past `max_chars`.
-        let ellipsis: String = options.ellipsis.chars().take(options.max_chars).collect();
-        let keep = options.max_chars.saturating_sub(ellipsis.chars().count());
-        let truncated: String = raw.chars().take(keep).collect();
-        Some(format!("{truncated}{ellipsis}"))
-    } else {
-        Some(raw)
-    }
-}
-
 impl<State: Send + Sync> ToolRegistry<State> {
     /// Creates an empty registry.
     pub fn new() -> Self {

src/harness/tool/types.rs

@@ -229,20 +229,38 @@ impl ToolExecutionContext {
     }
 }
 
-/// How strictly a tool must be sandboxed when it executes.
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum SandboxMode {
-    /// Inherit whatever the run's execution environment provides (the default).
-    #[default]
-    Inherit,
-    /// The tool is safe to run without any sandbox.
-    Disabled,
-    /// The tool must run inside an isolated execution environment; policy
-    /// enforcement fails closed if no sandbox is available.
-    Required,
+/// Lets a tool read this context without depending on the harness.
+///
+/// A tool is written against `tinytools`, which cannot name this type: this
+/// crate depends on `tinytools`, so an edge back would be a cycle. The
+/// vocabulary therefore declares a narrow trait and this crate implements it,
+/// which is what lets a host hand a live [`ToolExecutionContext`] to a tool
+/// that has never heard of the harness.
+///
+/// Only the facts a tool actually reads are exposed. The run id, event sink,
+/// cancellation token and streaming flag stay harness-internal — a tool that
+/// wanted them would be reaching into the run rather than doing its job.
+///
+/// `workspace` needs no conversion: [`WorkspaceDescriptor`] is `tinytools`'
+/// type, re-exported by this crate, so the field is already the right one.
+impl tinytools::ToolRunContext for ToolExecutionContext {
+    fn workspace(&self) -> Option<&tinytools::WorkspaceDescriptor> {
+        self.workspace.as_ref()
+    }
+
+    fn thread_id(&self) -> Option<&str> {
+        self.thread_id.as_ref().map(ThreadId::as_str)
+    }
+
+    fn max_turn_output_tokens(&self) -> Option<u32> {
+        self.max_turn_output_tokens
+    }
 }
 
+// `SandboxMode` rides on `WorkspaceDescriptor`, which is `tinytools`' type, so
+// the mode has to be the same type on both sides of that field.
+pub use tinytools::SandboxMode;
+
 /// How a tool is allowed to reach the caller's workspace / filesystem root.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]

src/harness/workspace/mod.rs

@@ -14,6 +14,7 @@ mod policy;
 mod types;
 
 pub use git::*;
+pub use policy::enforce_workspace_path;
 pub use types::*;
 
 use std::path::PathBuf;