---
title: "Tools and permissions"
description: "The agent's full tool catalog, and which actions require approval"
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: The agent's full tool catalog, and which actions require approval
Related: /docs/sandboxes, /docs/github, /docs/agent/mcp

# Tools and permissions

The agent works through a catalog of first-party tools. Every call streams into the [thread](/docs/threads)'s activity timeline with a short description of what it's doing; sensitive calls pause for [approval](#which-tools-require-approval) first.

The identifiers below are the names the model calls. Hoplite's own surfaces — the activity timeline and Linear agent sessions — show a human-readable name instead, so `source_control_rebase_pull_request` reads as "Rebase pull request." Tools from [MCP servers](/docs/agent/mcp) have no hand-written name, so their identifier is humanized on the fly.

## Files and search

| Tool | What it does |
| --- | --- |
| `repo_info` | Repository layout and metadata |
| `read_file` | Read a file from the sandbox |
| `write_file` | Create or overwrite a file |
| `edit_file` | Targeted string replacement in a file |
| `apply_patch` | Multi-file patch application (the primary editor on GPT models) |
| `list_files` / `find_files` | Browse and locate files |
| `search` | Content search across the repo |
| `read_logs` / `tail_logs` | Read and follow log output |
| `load_skill` | Load a project [skill](/docs/agent/skills) on demand |
| `web_search` | Search current public-web documentation and research through Hoplite's Exa integration; each result includes its source URL |

`web_search` is a platform capability rather than an MCP server: when staff enables it, it is available to all agent runs using a worker-owned Exa credential. The credential is never copied to project settings, repository files, or sandboxes. Search results are untrusted external content, so the agent treats them as reference material — not instructions.

When the tool is available, agents search current documentation before relying on a third-party SDK, library, service, tool, or person named in a request. They prefer the current version unless the repository pins another one, cite sources that inform recommendations, and verify important claims against authoritative documentation.

## Shell and processes

| Tool | What it does |
| --- | --- |
| `shell` | Run a command in the sandbox |
| `process_list` / `kill_process` | Inspect and stop running processes |
| `sandbox_ports` | See which ports are listening |

The raw sandbox shell never receives a GitHub App credential, so `git` and `gh` commands cannot inherit repository authority. First-party GitHub and pull-request tools broker fresh, repository-scoped installation tokens inside Hoplite's trusted worker for the exact fetch or publication operation; those tokens never reach the remote URL, Git configuration, workspace filesystem, or agent-authored shell. Publication paths also reject repositories with tracked submodules before pushing.

## Sandbox lifecycle

| Tool | What it does |
| --- | --- |
| `sandbox_setup` | Run the project's [setup script](/docs/sandboxes/scripts) |
| `preview_start` | Start the run script and return a live [preview URL](/docs/sandboxes/previews); also reports additional HTTP listeners from that managed run, which the agent can promote into `ports.additional` |
| `sandbox_open_preview` | Mint a preview URL for a port that's already listening |
| `sandbox_status` | Health, resources, and disk usage |
| `sandbox_restart` | Restart the sandbox |
| `sandbox_resize_up` / `sandbox_resize_down` | Adjust the reserved CPU, memory, and disk floor within [policy limits](/docs/sandboxes/resources) — rarely needed, since compute bursts on demand |

## Browser

Each thread has a persistent browser inside the sandbox — the agent uses it to verify its own work against your running app. Screenshots and recordings are written under the git-ignored `.hoplite/artifacts/` directory and excluded from workspace diffs, so proof files never become application changes.

`browser_cli` runs the installed `agent-browser` CLI with native arguments after `agent-browser` and optional finite stdin, exposing its complete non-interactive browser automation suite in the thread's persistent browser session and namespace. Hoplite preserves command semantics while canonicalizing screenshot and recording destinations under `.hoplite/artifacts/`, including nested batch commands and batch stdin. `browser_open`, `browser_snapshot`, `browser_click`, `browser_fill`, `browser_screenshot`, `browser_console`, `browser_errors`, and `browser_record` (video capture) remain convenience shortcuts for common operations.

Visual verification is proportional. For a UI-only change that touches at most three implementation files or changes at most 150 implementation lines, and does not affect routing, auth, persistence, API/data contracts, or a multi-step interaction, one successful DOM assertion or one screenshot is enough. Before/after images are captured only when a comparison is requested. Video is reserved for a multi-step interaction the user explicitly asks to see; one recording per run is normal, and the agent does not re-record for framing or probe and extract frames from its own clip.

`browser_record` targets 10fps by default. Its `start` action accepts an optional integer `fps` from 10 through 60 for motion that needs smoother capture; the managed recorder samples compositor-pushed frames at that cadence while variable-rate encoding preserves their real arrival times instead of fabricating catch-up frames. `stop` reports compositor arrival, submitted-frame, fresh-frame, duplicate-frame, backpressure, processing/encoding latency, skipped cadence slots, and longest-hold metrics, so a nominal container frame rate is never the only cadence signal. Providers with strict tool schemas may require `fps`, `path`, or both on every action: pass `fps: 10` for the compatible default, and reuse the start values on `stop`, where Hoplite ignores them. A non-default `browser_record` FPS requires the managed Hoplite `agent-browser` build. The same sandbox-native option is available through `browser_cli`, for example `record start .hoplite/artifacts/demo.webm --fps 24`; screenshot and recording destinations are confined to `.hoplite/artifacts/`, while any explicit `--fps` value, including 10, is passed through unchanged and requires the managed build. An older sandbox fails clearly before recording rather than treating `--fps` as a URL.

## Vision and media

| Tool | What it does |
| --- | --- |
| `view_image` | Load a workspace image into the agent's own context as vision input |
| `display_image` | Show an image to **you** in the chat (stored durably; optionally published at an unguessable URL that expires after 7 days) |
| `display_video` | Show a video in the chat (public mode renders an animated GIF preview that works in GitHub comments) |

## Source control

GitHub is the currently configured source-control provider, but agents call a provider-neutral `source_control_*` surface. `source_control_get_issue` and `source_control_list_issues` read the repository issue queue, while `source_control_create_issue` creates a repository-bound issue. `source_control_list_ci_runs`, `source_control_get_ci_run`, and `source_control_list_ci_jobs` provide bounded CI investigation; pass a failed `jobId` to `source_control_get_ci_job_log` for its bounded log tail. The GitHub App credential stays in Hoplite's trusted worker and is never exposed to the sandbox or forwarded to GitHub's signed log-download URL.

Pull-request operations include `source_control_create_pull_request`,
`source_control_update_pull_request`,
`source_control_get_pull_request`, `source_control_get_pull_request_review_state`,
`source_control_list_pull_request_files`,
`source_control_get_pull_request_file_diff`,
`source_control_list_pull_request_checks`, `source_control_comment_on_pull_request`,
`source_control_update_pull_request_comment`,
`source_control_delete_pull_request_comment`,
`source_control_list_pull_requests`, `source_control_merge_pull_request`,
`source_control_mark_pull_request_ready_for_review`,
`source_control_rebase_pull_request`, `source_control_request_pull_request_reviewers`,
`source_control_reply_to_pull_request_review_comment`, and
`source_control_resolve_review_thread`. `thread_link_pull_request` and
`thread_list_pull_requests` tie pull requests to the thread. See
[GitHub & pull requests](/docs/github).

`source_control_update_pull_request` rewrites an open linked pull request's
title and description in place, so the agent can keep the holistic PR summary
and verification evidence current while leaving per-turn narration in comments.
Its optional `base` parameter retargets the pull request onto a new parent
branch when restacking.

Large changes ship as native pull request stacks: the agent publishes segments
on branches derived from the thread branch (`<thread-branch>--<slug>`, with
another `--<slug>` per depth; `/` is not used because Git cannot create a ref
beneath a branch that already exists)
and passes `base` to `source_control_create_pull_request` so each stacked pull
request targets its parent segment's branch. Every stacked pull request gets
its own autofix review loop, and merges proceed bottom-up.

`source_control_list_repository_branches` discovers branch names through the
repository-bound source-control broker without exposing provider credentials.
`source_control_fetch_git_refs` imports explicitly requested branch or commit
objects through that broker, while `source_control_publish_git_commit` publishes
one exact local commit only to the thread branch, a stack branch derived from
it, or a live linked pull-request head under an exact remote-head lease and cannot overwrite the configured base
branch.

After every pull request linked to a thread for the current repository has been merged or closed,
`source_control_start_branch` starts an independent follow-up from the
configured base. The agent passes a short lowercase slug and uses the exact
authorized branch returned by the tool; Hoplite persists that branch identity
and can safely rename an already-created local fallback without discarding its
work. This avoids guessing a branch namespace or creating another thread just
to publish follow-up work.

Workflow dispatch is exposed only when the current GitHub App installation has
effective Actions write permission and deployment policy binds an immutable
repository identity, an allowlisted workflow, and one exact safe ref. Every
dispatch is brokered against that policy, so an agent-controlled pull-request branch
cannot substitute modified workflow YAML that reads repository secrets.
Top-level comment updates and deletions are limited to pull requests linked to
the current thread and comments created by the configured Hoplite GitHub App;
deletion cannot be undone. Providers without a
verified ownership signal do not expose these comment-mutation tools.

All first-party `source_control_*` tools run without a separate user approval
prompt. Their authority comes from repository binding, exact target and lease
checks, current provider permissions, and at-most-once mutation contracts, so
the agent can complete repository work without avoidable human handoffs.

## Thread context and continuation

Repository agents can use `list_threads`, `search_threads`, `get_thread`,
`read_thread_messages`, and `read_thread_message` to recover relevant history
from the project they are currently working in. These reads are fixed to that
signed project scope: an agent cannot request organization scope, another
project, or a cross-project thread ID. Thread titles, excerpts, and messages are
treated as untrusted historical context rather than instructions.

`send_message_to_thread` continues work in another thread created by the
invoking user in the same project and starts a run there. The agent uses it
instead of creating duplicate work; it cannot target its current thread, cross
projects, or recursively bounce work between threads.

`thread_rename` keeps the current thread's generated title aligned with its
actual purpose when later context makes the old title materially inaccurate.
It avoids rephrasing already accurate titles and never replaces your explicit
[`/rename`](/docs/agent/slash-commands) choice merely for style.

## Preview checklists

`preview_checklist_set` creates the ordered review steps shown in a thread's Preview panel. `preview_checklist_update` revises a step, including resetting its review state after a later change. See [Previews](/docs/sandboxes/previews).

## Linear

`thread_link_linear_issue` attaches a Linear issue to the current thread. The agent uses it proactively when a prompt includes an issue reference, and inbound Linear agent sessions attach the originating issue automatically. The linked issue appears as the compact Linear pill used alongside pull requests in thread views. This tool only stores Hoplite thread metadata; it does not read from or write to Linear. See [Linear](/docs/integrations/linear).

## Self-configuration and feedback

| Tool | What it does |
| --- | --- |
| `project_settings_get` | Show how project scripts and settings resolve (repo file vs. Hoplite overrides) |
| `project_settings_update` | Change script overrides directly; automatic-QA policy changes require approval |
| `report_platform_issue` | File a structured platform-issue report to the Hoplite team |

## Sentry

When a project has a Sentry binding, `sentry_info` returns its redacted
connection status, valid `sentryProjectId` values, credential availability, and
effective read/write capabilities without exposing a token. Agents call it
before project-scoped Sentry tools when more than one Sentry project is bound.
Issue, event, release, alert, team, and member reads are bounded to the selected
binding; comment and resolution tools appear only when the installation and
workspace policy both grant those capabilities.

## MCP tools

Projects can attach [MCP servers](/docs/agent/mcp); their tools join the agent's catalog alongside the first-party set.

## Which tools require approval

These pause for your sign-off before executing:

- `write_file`, `edit_file`, and `apply_patch` when they target sensitive files or paths — credentials and environment files, CI workflows, infrastructure configuration, unresolved targets, and paths outside the repository workspace
- `shell`
- `kill_process`, `sandbox_restart`, `sandbox_resize_down`
- `preview_checklist_set`, `preview_checklist_update`
- `project_settings_update` when changing automatic-QA policy

Routine repository-local edits run without interruption. A mixed batch still pauses for any sensitive edit it contains. Everything else — including all first-party source-control tools — runs without interruption so the agent keeps its momentum.

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).