Tools

The tools the model can call, as the model sees them: the name, the level and effect that decide how it is permitted (Permissions), the description heph gives the model, and the parameters. This page is generated from the catalog in the binary by make book; do not edit it by hand.

The principal is the parameter a permission pattern matches and a prompt shows: the path, the command, the URL, the pattern or glob, or the first edit's path.

view

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

Read a file, with line numbers. A file up to 400 lines is returned whole; a longer one comes back as its outline (items and the lines they span) so you can read the part you need: offset (1-based) and limit for a range, or symbol for one item by name (parse, Config::load, a heading). offset alone reads from there to the end. Prefer this to shell(cat).

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Path relative to the worktree"
    },
    "offset": {
      "type": "integer",
      "minimum": 1,
      "description": "First line to return (1-based)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "description": "Number of lines to return"
    },
    "symbol": {
      "type": "string",
      "description": "An item from the outline to return whole: a function, type, impl, or section by name; `Type::method` for a method"
    }
  },
  "required": [
    "path"
  ]
}

ls

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

List a directory. depth for a tree (default 1), long for size, mode, and modification time. Ignored paths (build output, node_modules) are listed but not descended into.

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Directory, relative to the worktree; default the root"
    },
    "depth": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8
    },
    "long": {
      "type": "boolean"
    }
  }
}

glob

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

Find files by glob pattern (**/*.rs, src/**/mod.rs), honoring the project's ignore rules. Returns paths relative to the worktree, most recently modified first.

{
  "type": "object",
  "properties": {
    "pattern": {
      "type": "string"
    },
    "path": {
      "type": "string",
      "description": "Directory to search under; default the root"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "default": 200
    }
  },
  "required": [
    "pattern"
  ]
}

grep

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

Search file contents with ripgrep. pattern is a regex unless literal is true. include restricts to a glob (*.rs), context adds lines around each match, files_only lists matching files, count counts matches per file. Returns the first limit matches (default 100), or files in the listing modes, and the total; narrow with path or include rather than raising it. Prefer this to shell(grep).

{
  "type": "object",
  "properties": {
    "pattern": {
      "type": "string"
    },
    "path": {
      "type": "string",
      "description": "File or directory to search; default the root"
    },
    "include": {
      "type": "string",
      "description": "Glob of files to search, e.g. *.rs"
    },
    "literal": {
      "type": "boolean"
    },
    "context": {
      "type": "integer",
      "minimum": 0,
      "maximum": 20
    },
    "files_only": {
      "type": "boolean"
    },
    "count": {
      "type": "boolean"
    },
    "case_insensitive": {
      "type": "boolean"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "required": [
    "pattern"
  ]
}

stat

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

Size, line count, kind, mode, and modification time of paths. For a directory: the number of files and lines by extension. Prefer this to shell(wc) or shell(du).

{
  "type": "object",
  "properties": {
    "paths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1
    }
  },
  "required": [
    "paths"
  ]
}

outline

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

The items a file defines and the lines each spans: functions, types, impls, classes, sections, tasks. Read this first for a file of any size, then view the ranges you need, or view with symbol for one item. Found from the text, so approximate; lsp_symbols is exact where a language server is configured. Rust, Python, JavaScript and TypeScript, Go, Ruby, shell, C-like languages, Markdown, Norg, TOML, YAML, and Makefiles.

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Path relative to the worktree"
    }
  },
  "required": [
    "path"
  ]
}

edit

Level 1 (Notify). It writes into the worktree.

Replace exact text in files. Each edit names a path, the exact old text (including whitespace and indentation) and the new text. old must occur exactly once unless replace_all is set. Edits are checked first and applied all or none, so a multi-file change never lands half-way. Before a write, state in one or two sentences what you are changing and why; that sentence is what the user reviews the hunk against.

{
  "type": "object",
  "properties": {
    "edits": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "old": {
            "type": "string"
          },
          "new": {
            "type": "string"
          },
          "replace_all": {
            "type": "boolean"
          }
        },
        "required": [
          "path",
          "old",
          "new"
        ]
      }
    }
  },
  "required": [
    "edits"
  ]
}

create

Level 1 (Notify). It writes into the worktree.

Create a new file with the given content, making directories as needed. Refuses a path that already exists; use edit to change an existing file.

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string"
    },
    "content": {
      "type": "string"
    },
    "executable": {
      "type": "boolean",
      "description": "Set the executable bit"
    }
  },
  "required": [
    "path",
    "content"
  ]
}

search_replace

Level 1 (Notify). It writes into the worktree.

Find and replace across every file matching a glob. pattern is a regex (with $1 capture references in replacement) unless literal is true. Reports the files and counts changed. For a rename that must follow references semantically, prefer lsp_rename when it is available.

{
  "type": "object",
  "properties": {
    "pattern": {
      "type": "string"
    },
    "replacement": {
      "type": "string"
    },
    "glob": {
      "type": "string",
      "description": "Files to change, e.g. src/**/*.rs"
    },
    "literal": {
      "type": "boolean"
    }
  },
  "required": [
    "pattern",
    "replacement",
    "glob"
  ]
}

markdown_format

Level 1 (Notify). It writes into the worktree.

Format named .md or .markdown files with yucky at 80 columns, in process. paths is a nonempty list of worktree-relative files; no globs, directories, or symlinks. check (default false) reports files needing formatting without writing, returning an error if any differ. All files are checked and formatted in memory before any write. Reports formatted/unchanged files and warnings, not their contents. Does not generate HTML. Before a write, state what you are changing and why; the changes enter normal review.

{
  "type": "object",
  "properties": {
    "paths": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string"
      }
    },
    "check": {
      "type": "boolean",
      "default": false
    }
  },
  "required": [
    "paths"
  ],
  "additionalProperties": false
}

config_view

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

Read heph's authoritative project or user config, including path overrides. This reads the original file, not a shadow copy. A missing file is empty. Use config_edit for changes, never generic file edits.

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "enum": [
        "project",
        "user"
      ],
      "default": "project"
    }
  }
}

config_edit

Level 3 (Escalate). It runs a command in the worktree.

Replace heph's authoritative project or user config immediately, outside source review. Read config_view first. Supply the complete current file as old and the complete proposed file as new, preserving comments and unrelated settings. A fresh user approval is required every time, even with --yes or remembered patterns. A concurrent change or invalid config refuses the write. Permission and network policy refresh on the next tool call in each session; other settings require restarting heph (skills can use /skills --reload). Before calling, explain the change and why.

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "enum": [
        "project",
        "user"
      ],
      "default": "project"
    },
    "old": {
      "type": "string",
      "description": "Complete current contents, empty for a missing file"
    },
    "new": {
      "type": "string",
      "description": "Complete proposed contents"
    }
  },
  "required": [
    "old",
    "new"
  ]
}

log

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

The project's commit history: hash, date, author, subject. Filter with paths, author, since (a date or 2 weeks ago), grep (subject and body), revision (a branch, tag, or range), and limit (default 30). Prefer this to shell(git log).

{
  "type": "object",
  "properties": {
    "paths": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "author": {
      "type": "string"
    },
    "since": {
      "type": "string"
    },
    "grep": {
      "type": "string"
    },
    "revision": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  }
}

show

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

One commit: message, author, date, and the files it changed. patch includes the diff; paths restricts it. Prefer this to shell(git show).

{
  "type": "object",
  "properties": {
    "revision": {
      "type": "string",
      "description": "A hash, branch, tag, or HEAD~n"
    },
    "patch": {
      "type": "boolean"
    },
    "paths": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "revision"
  ]
}

diff

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

A diff. With no arguments: exactly what you have changed this turn, which is what the user will review. from and to (revisions) and paths for anything else, e.g. from: HEAD~3. stat for a summary only.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string"
    },
    "to": {
      "type": "string"
    },
    "paths": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "stat": {
      "type": "boolean"
    }
  }
}

status

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

What differs from the project's last commit, in two groups: what this conversation carried into the turn (earlier turns' accepted work, not yet published with /commit), and your changes this turn. Prefer this to shell(git status).

{
  "type": "object",
  "properties": {}
}

branches

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

The project's branches, remote-tracking branches, and tags with their tip commits, and which commit this worktree is built on.

{
  "type": "object",
  "properties": {}
}

blame

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

Who wrote each line of a file and why: for lines written this turn, the tool call and the rationale you gave; for everything else, the project's commit. lines as start-end narrows it.

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string"
    },
    "lines": {
      "type": "string",
      "description": "A range like 40-60"
    }
  },
  "required": [
    "path"
  ]
}

search_history

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

Full-text search over this project's past conversations: what was asked, decided, and done in earlier turns. Returns turn ids with snippets; use read_turn on one for the whole exchange.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "query"
  ]
}

read_turn

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

One past turn in full: the prompt, what was said, each tool call with its parameters and result, how it ended, and what it cost.

{
  "type": "object",
  "properties": {
    "turn_id": {
      "type": "string"
    }
  },
  "required": [
    "turn_id"
  ]
}

read_output

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

Recover a session-owned command log without rerunning the command. Select stdout or stderr, a 1-based byte offset, and a byte limit (capped at 16 KiB). Text rendering replaces invalid or split UTF-8; use encoding=hex for exact bytes. Only logs in this conversation's ancestry are accessible.

{
  "type": "object",
  "properties": {
    "log_id": {
      "type": "string"
    },
    "stream": {
      "type": "string",
      "enum": [
        "stdout",
        "stderr"
      ]
    },
    "offset": {
      "type": "integer",
      "minimum": 1
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 16384
    },
    "encoding": {
      "type": "string",
      "enum": [
        "text",
        "hex"
      ]
    }
  },
  "required": [
    "log_id"
  ],
  "additionalProperties": false
}

which

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

Whether a command is installed, and where. Reports absent rather than failing; never runs the command.

{
  "type": "object",
  "properties": {
    "commands": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1
    }
  },
  "required": [
    "commands"
  ]
}

man

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

Read a manual page as plain text. section narrows it (e.g. 2 for system calls).

{
  "type": "object",
  "properties": {
    "page": {
      "type": "string"
    },
    "section": {
      "type": "string"
    }
  },
  "required": [
    "page"
  ]
}

shell

Level 2 (Approve). It runs a command in the worktree.

Run a command in the worktree with sh -c, for genuine shell features: pipes, redirection, shell globbing, command chaining. To run a single program, prefer exec (with its env map for environment variables), which spawns it directly and can be approved once for many calls; a shell approval is one exact command, because a wildcard could cover an injected ; rm -rf /. Not for looking at things: view, ls, glob, grep, stat, log, show, diff, status, blame, which, and man are silent and cover every read; a shell command asks the user for approval. git commit here moves a private pointer only; publishing to the user's repository happens through /commit after review and final gates. Returns combined stdout and stderr with the exit code, the middle cut past 16 KB.

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string"
    },
    "timeout_seconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3600
    }
  },
  "required": [
    "command"
  ]
}

exec

Level 2 (Approve). It runs a command in the worktree.

Run one program directly, with its arguments passed to it verbatim -- no shell, so no ;, |, >, $VAR, or glob is interpreted. This is the way to run a build, a test, a formatter, a linter, or any single command: prefer it to shell, because one approval (exec(cargo) args(*)) can cover a whole family of calls safely, where a shell approval is one exact command. program is the executable, found on PATH; args is a list of arguments, each a separate string (not one string with spaces). env optionally maps environment variable names to string values for this child only; use it instead of running env or a shell environment prefix. Values are literal, not expanded. Heph's command environment and git-redirection protections take precedence. Reach for shell only for a pipe, a redirect, shell globbing, or chaining. Returns combined stdout and stderr with the exit code, the middle cut past 16 KB. With opt-in command-output compaction, eligible successful status commands may return a fixed terse result and a read_output log ID. Set keep_output=true when inspecting diagnostics or requested data.

{
  "type": "object",
  "properties": {
    "program": {
      "type": "string"
    },
    "args": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "env": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Child-only environment overrides; values are literal strings."
    },
    "timeout_seconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3600
    },
    "keep_output": {
      "type": "boolean",
      "description": "Keep normal output for diagnostic/data inspection, even when successful-command compaction is enabled."
    }
  },
  "required": [
    "program"
  ]
}

background

Level 2 (Approve). It runs a command in the worktree.

Start a command that should keep running while you work: a dev server, a watcher, a long build. It runs in the worktree and you get a job number; read its output with job_status and stop it with job_kill. Every job ends when the session does. For a command that finishes on its own in a minute or two, use shell and wait.

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "description": "The command, run with sh -c in the worktree"
    }
  },
  "required": [
    "command"
  ]
}

job_status

Level 0 (Transparent). It reads the worktree, the shadow history, or the conversation.

A background job's state and the last lines of its output (lines, default 50). With no id, every job this session, one line each.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 0,
      "description": "The job number from `background`"
    },
    "lines": {
      "type": "integer",
      "minimum": 1,
      "maximum": 2000,
      "description": "How many lines of output, from the end"
    }
  }
}

job_kill

Level 2 (Approve). It runs a command in the worktree.

Stop a background job and everything it started. Its output stays readable with job_status.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 0,
      "description": "The job number from `background`"
    }
  },
  "required": [
    "id"
  ]
}

web_fetch

Level 2 (Approve). It reads over the network; Level 1 to a host on the allowlist (Network).

Fetch a URL with an HTTP GET and return its content as text (HTML is reduced to readable text). Documentation, changelogs, issues. Well-known documentation hosts fetch silently; any other host asks the user once. A redirect to another host is reported, not followed: fetch the new URL if you want it. Nothing is ever posted.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "url"
  ]
}

todos

Level 0 (Transparent). It keeps the model's notes for the session; it touches nothing else.

Your task list for the work at hand, shown to the user. Each call replaces the whole list. Use it for work with several steps: write the steps before starting, mark one in_progress while you are on it, mark it completed as soon as it is done, and add steps you discover on the way. Skip it for a single step. Keep items short and in the imperative; twenty is the most a list holds.

{
  "type": "object",
  "properties": {
    "todos": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "description": "The step, in the imperative"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "in_progress",
              "completed"
            ]
          }
        },
        "required": [
          "content",
          "status"
        ]
      },
      "description": "The whole list, in order"
    }
  },
  "required": [
    "todos"
  ]
}

ask_user

Level 0 (Transparent). It asks you a question.

Ask the user one question and wait for the answer. Use it when a decision materially changes the work and neither the codebase nor the conversation settles it; never ask in prose, which ends the turn. Read before asking. options may hold two to five short choices, rendered as a picker; five is what a person holds in view. More than five means the list has not been narrowed: read more, or ask a narrower question first and a second with the survivors. The user can always type an answer instead of picking.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "One question, as the user will read it"
    },
    "options": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 2,
      "maxItems": 5,
      "description": "Two to five short choices"
    },
    "context": {
      "type": "string",
      "description": "One sentence on what the answer changes"
    }
  },
  "required": [
    "question"
  ]
}

submit_for_review

Level 0 (Transparent). It asks you a question.

End the working segment and hand one complete publication unit to heph's gates and review. Call this by itself after finishing the unit's implementation, tests, and documentation. This does not authorize publication or create a Git commit. Heph offers publication through the normal approval UI and starts the next remaining unit only after verified successful publication. Declines and failures pause the sequence; review and gate repairs stay in the current unit. Use an empty remaining_work list for the final unit. Set include_unpublished only after the developer explicitly agrees to combine earlier unpublished work into this unit. No further tool calls in this response will run after a successful submission.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Short title of this publication unit"
    },
    "summary": {
      "type": "string",
      "description": "What is ready for review"
    },
    "commit_message": {
      "type": "string",
      "description": "Proposed commit message; the developer may edit it"
    },
    "remaining_work": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 20,
      "description": "Remaining publication units in order; empty for the final unit"
    },
    "include_unpublished": {
      "type": "boolean",
      "description": "True only after explicit developer consent to include earlier unpublished work"
    }
  },
  "required": [
    "title",
    "summary",
    "commit_message",
    "remaining_work"
  ],
  "additionalProperties": false
}