Tools

agentlane.harness.tools provides first-party harness tool definitions for common workspace actions. File tools also support application storage. Each helper returns a HarnessToolDefinition, which wraps an executable agentlane.models.Tool or runner-owned ToolSpec plus optional prompt metadata for HarnessToolsShim.

Index

Core docs:

1. Design: construction model, imports, HarnessToolsShim, base tool sets, and shared output limits.
2. Permissions: permissive defaults, path policy, bundled permission policies, approval callbacks and brokers, and bash boundaries.
3. File I/O interfaces: injected storage for native file tools and skill loading.
4. Sandboxes: run environment tools in a sandbox managed by your app.
5. MCP: use tools from Model Context Protocol servers.

Tool reference:

1. agent: delegate focused work to a fresh helper agent.
2. read: read UTF-8 text files with deterministic truncation.
3. find: walk directories with gitignore-aware pattern matching.
4. grep: search file contents with ripgrep-backed results.
5. patch: apply minimal SEARCH/REPLACE edits.
6. write: create or overwrite UTF-8 files.
7. write_plan: update the visible task plan.
8. bash: run bounded non-interactive shell commands.

Quick Start

For common local-agent apps, use WorkspaceToolsShim so the standard tools share one workspace root and the model sees workspace-relative path guidance.

from pathlib import Path

from agentlane.harness.tools import WorkspaceToolsShim

WORKSPACE = Path.cwd()

shims = (WorkspaceToolsShim(WORKSPACE),)

For a trusted local prototype that needs direct control over the tool set, use the standard tools directly. A specific cwd controls relative path resolution; it is not a sandbox.

from pathlib import Path

from agentlane.harness.tools import HarnessToolsShim, base_harness_tools

WORKSPACE = Path.cwd()

shims = (
    HarnessToolsShim(
        base_harness_tools(cwd=WORKSPACE),
    ),
)

For a workspace-bounded coding assistant, pass an explicit permission policy:

from agentlane.harness.tools import (
    WorkspaceToolsShim,
    WorkspaceToolPermissionPolicy,
)

shims = (
    WorkspaceToolsShim(
        WORKSPACE,
        permissions=WorkspaceToolPermissionPolicy(WORKSPACE),
    ),
)

For approval workflows, broader path scopes, operation grants, and bash behavior, see Tool permissions.

For application storage, use HarnessToolsShim with injected storage tools as shown in File I/O interfaces. WorkspaceToolsShim configures local tools and does not accept storage adapters.

Use MountedReader when one read tool must access both local and remote files. The skill loader can share that reader so activation returns paths that the read tool can use. Use MountedFileSystem to add writes to capable mounts and share paths across read, write, find, and patch.

Standard Set

base_harness_tools() returns read, find, grep, patch, write, write_plan, bash, and agent. The public base-tools set currently does not include ls.

Pass reader= for read, find, and patch. Pass writer= for write and patch, or supply a reader that also implements WritableFileSystem. Find requires read, listing, and metadata capabilities. Injected file tools use storage_cwd, which defaults to the storage root (/ for mounts, . for plain injected backends). Set storage_cwd="/tenant/sessions/session-123" to resolve bare file names within that mounted directory. Each tool captures its cwd; activation of a skill does not change it. Grep uses cwd in the harness process filesystem. Bash uses cwd in its executor filesystem, which can be different with a custom executor. Logical mounts do not become process mounts. See File I/O interfaces for construction and path rules.

For a SPACE sandbox, pass space_harness_tools(sandbox, cwd=guest_cwd) to HarnessToolsShim in place of the base bundle. The extension reuses the core tools and routes all six environment tools to the guest. write_plan and agent stay on the host. Setting only bash_executor= changes only Bash; it does not move the file tools. See SPACE: How it works.

Pass include= or exclude= when an application needs the standard set with only selected tools. Selectors use the model-visible tool names above, and returned tools keep the standard order:

search_tools = base_harness_tools(
    cwd=WORKSPACE,
    include=("read", "find", "grep"),
)

no_shell_tools = base_harness_tools(
    cwd=WORKSPACE,
    exclude=("bash",),
)

Unknown selector names raise ValueError. Passing the same name in both include and exclude also raises ValueError.

BASE_TOOL_NAMES is exported for applications that compose the base tools with their own tools and need the owned name set without re-deriving it from base_harness_tools():

from agentlane.harness.tools import BASE_TOOL_NAMES

assert "bash" in BASE_TOOL_NAMES

Sharing One Selector With Application Tools

When an application adds its own tools alongside the base set and wants a single include/exclude selector to span both, pass the application tool names through extra_names. Those names are accepted by selector validation but never built by base_harness_tools (it only owns BASE_TOOL_NAMES), so the selectors no longer raise on names this function does not own:

# `web_search` is an application tool; the shared selector references it without
# `base_harness_tools` rejecting the unknown name or trying to build it.
base = base_harness_tools(
    cwd=WORKSPACE,
    include=("read", "grep", "web_search"),
    extra_names=("web_search",),
)
# -> read, grep   (web_search is the application's responsibility to build)

Names outside both BASE_TOOL_NAMES and extra_names still raise ValueError, so genuine typos are still caught.

You can also construct tools individually when an agent needs a custom tool set:

from agentlane.harness.tools import (
    agent_tool,
    bash_tool,
    find_tool,
    grep_tool,
    patch_tool,
    plan_tool,
    read_tool,
    write_tool,
)

workspace_tools = (
    read_tool(cwd=WORKSPACE),
    find_tool(cwd=WORKSPACE),
    grep_tool(cwd=WORKSPACE),
    patch_tool(cwd=WORKSPACE),
    write_tool(cwd=WORKSPACE),
    plan_tool(),
    bash_tool(cwd=WORKSPACE),
    agent_tool(),
)