---
title: "Tools and permissions"
description: "Give agents the tools to execute work within repository and approval boundaries."
canonical_url: "https://hoplite.sh/docs/agent/tools"
markdown_url: "https://hoplite.sh/docs/agent/tools.md"
---

# Tools and permissions
URL: /docs/agent/tools
LLM index: /llms.txt
Description: Give agents the tools to execute work within repository and approval boundaries.
Related: /docs/threads/review, /docs/workspace/security, /docs/agent/mcp

# Tools and permissions

Hoplite agents use tools to inspect repositories, change code, run commands, and work with connected services. Each run's tool catalog follows its repository binding, integrations, and agent role. A parent agent, a child sharing its workspace, and a child with a separate workspace can have different capabilities.

An explicit child-agent model override must use the parent agent's provider. Omit the override to use the configured delegate; delegation cannot switch to an unrelated provider.

## Permissions and approvals

Cloud agents automatically approve tool calls, so a run does not pause waiting for a tool-approval response. This includes connected-service writes and public media display. Auto-approval does not grant access: repository scope, command policy, protected paths, integration write settings, and workspace policy still constrain the operation. Local CLI and desktop runs on your own machine retain their approval flow; see [Review and approvals](/docs/threads/review#approvals).

| Operation | Boundary |
| --- | --- |
| Repository reads and edits | Repository scope and protected-path policy |
| Shell commands | Command policy and command provenance |
| Sandbox restart or resource changes | Runtime support and role restrictions; disruptive operations can interrupt processes |
| Preview checklist changes | Agents cannot mark their own work as user-reviewed |
| Script overrides | The agent can inspect and repair project script overrides directly |
| Connected-service writes | The integration's configured write capability and resource scope |

## Source control

Native `source_control_*` tools let agents inspect repositories, manage pull requests, and read checks and reviews within the active repository binding. Writes follow the operation’s approval policy. Agents can also use `git` and `gh` through the shell for repository work. Hoplite provisions a short-lived GitHub App installation token scoped to the active repository in private repository-local CLI configuration. The token is not returned as tool output or exported to every sandbox command.

Authenticated commands remain subject to repository scope and command policy. The sandbox contains that credential configuration, so it is part of the security boundary. See [Security](/docs/workspace/security#repository-credentials).

Thread-native source-control tools can list releases, but do not create or update them.

A PR created through the CLI must also be linked to the thread. Linking makes its checks and reviews visible in Hoplite and enables the review loop when PR autofix is configured. See [Pull requests](/docs/github).

## Execution capabilities

| Capability | Model-facing tool | Scope |
| --- | --- | --- |
| Commands, tests, file searches, browser automation | `shell` | Thread workspace |
| Read output, send input, or stop a running command | `shell_poll`, `shell_write_stdin`, `shell_kill` | The session handle returned by `shell`; availability depends on the engine |
| File patches | `apply_patch` | Repository and protected-path policy |
| Workspace setup and managed previews | `workspace_control`, `sandbox_control` | Thread workspace; disruptive operations are restricted for shared-workspace children |
| Delegated work | `subagent_control` | Children of the active run |
| Plans and preview checklists | `task_list` | Separate work and preview lists |
| Repository credentials | `credential_control` | Status, rotation, and revocation for the active repository |
| Project script overrides | `project_control` | Effective settings and override updates |
| Hosted skills | `load_skill` | Personal and built-in skills; repository skills are read from disk |

`credential_control` provisions a GitHub App installation token scoped to the active repository with contents, pull request, and workflow writes plus read access to Actions, checks, issues, and commit statuses, narrowed to what the installation has approved. `workflows: write` is included because GitHub refuses any push that adds or changes a file under `.github/workflows/` without it. A permission the installation has not approved appears under `unavailablePermissions` in `status`, and a push that needs it fails with a note naming the permission and the owner-side approval step instead of the raw Git error.

Use the activity timeline to inspect the operation an agent actually called and the result it received. Tool availability can differ from this table when an integration or runtime capability is unavailable.

## Cross-thread access

Repository agents can search and read history within their signed project scope, restricted to threads created by the invoking run's user. Retrieved messages are treated as historical context. Agents cannot widen that search to another project or the whole organization.

Continuing another thread is narrower: the target must belong to the same project and have been created by the invoking user. The agent cannot send to its own thread. Peer replies are bounded to 32 causation hops (16 request/reply rounds), with repeated-content detection and per-run write limits. Verified scheduled runs can coordinate on behalf of their creator; verified PR review-loop runs can read and message related threads but cannot create new tasks.

## Delegated work

MCP integrations remain parent-only. A child cannot gain MCP access by changing models. Handoffs naming a registered MCP wrapper, or a configured server in an MCP/Executor request, are rejected before a child starts. The parent should do that work itself or delegate analysis of already-retrieved, non-sensitive material. Managed Preview controls unavailable to a child also remain the parent's responsibility; the parent must verify the integrated UI before claiming completion.

A separate-workspace child must commit its changes before handoff: Hoplite transfers commits reachable from its current HEAD, not uncommitted files. Each new fork uses a fresh parent snapshot. If exporting child commits fails, Hoplite retains the fork for recovery rather than deleting the unpublished work; a retained fork is not proof that the parent received it.

## Viewing workspace images

The `view_image` tool accepts paths relative to the thread workspace and absolute paths inside that workspace, as well as screenshots under `/tmp/verify`. Absolute paths do not grant access to files outside those locations; symlink targets must remain within the allowed location too.

## External tools and artifacts

Remote [MCP servers](/docs/agent/mcp) add tools within the permissions of their configured credentials. Sentry operations stay within the selected project binding. [Sazabi](/docs/integrations/sazabi) exposes `sazabi_control` only when the workspace is connected, scoped to the connected Sazabi organization. Linking a Linear issue to a thread stores the association; it does not itself read or modify the issue.

Screenshots and videos displayed in a thread are stored durably. Public sharing requires workspace policy permission and creates an unguessable link that expires after seven days; cloud media tools do not pause for a separate approval prompt. Otherwise access remains restricted to workspace members.

## Sitemap

Sitemap discovery is not enabled for this deployment.