toolgrant

package
v0.7.8-dev.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package toolgrant compares the runner tools a QuickAgent's instruction names with what its manifest grants. The runner builds a run's tool surface from the capability contract: a tool whose capability is not declared is absent, not present and refusing. An instruction that works a website through browser_click, runs a program through run_command, reaches a host through fetch or registers a task through task_add, in a release that declares no browser, no command, no egress or no clock, describes a run that cannot happen: the agent meets a tool list without the tools its instruction depends on.

Check reads the instruction for tool names and reports each one whose grant the manifest lacks, with the line to add. The publication scan records what it reports as a finding that holds the version for a person, the draft check returns it before Submit, and a client can ask the same question of a local draft.

What the reading counts as naming a tool: a tool name with an underscore (run_command, browser_click, host_run) anywhere as a word of its own; a one-word tool name (fetch) only where it is written alone in backticks or followed by "tool" (fetch( is JavaScript's, which a browser script calls); a harness's prefixed form (mcp__gateway__fetch); browser_* and host_* for the whole family; and <server>__<tool>, a declared MCP server's tool by its server's name. A mention in a sentence that turns the tool away ("not browser_pdf_save", "never call fetch", "if you have run_command") is not a need, and neither is a list continuing one, nor a paragraph that speaks of a QuickAgent in the third person ("a QuickAgent", "the QuickAgent's own fetch"), which describes another package's tools (an instruction that drafts or reviews QuickAgents). Words such as "browser" or "fetch the page" in prose are not tool names.

Index

Constants

View Source
const (
	MaxNameBytes = 80
	MaxMissing   = 50
)

Bounds on what Check answers, which callers return and record: a name longer than MaxNameBytes is not a tool name, and at most MaxMissing tools are reported.

Variables

This section is empty.

Functions

func NotContract

func NotContract() []string

NotContract returns the runner's tools no contract line grants, sorted.

func Table

func Table() map[string]Grant

Table returns every runner tool the contract grants, with its grant.

func ToolsOf

func ToolsOf(g Grant) []string

ToolsOf returns the tools a grant gives, sorted. (A browser that may type secrets is given every one of its tools but browser_evaluate.)

Types

type Grant

type Grant string

Grant is the line of the capability contract a tool needs.

const (
	// GrantBrowser is capabilities.browser: the browser server's tools.
	GrantBrowser Grant = "browser"
	// GrantExec is capabilities.exec with at least one command:
	// run_command.
	GrantExec Grant = "exec"
	// GrantEgress is capabilities.network.egress naming at least one host:
	// fetch.
	GrantEgress Grant = "egress"
	// GrantTargetHosts is capabilities.targetHosts: the host link's tools.
	GrantTargetHosts Grant = "targetHosts"
	// GrantFSRead is capabilities.filesystem.read other than none:
	// fs_read and fs_list.
	GrantFSRead Grant = "filesystem.read"
	// GrantFSWrite is capabilities.filesystem.write other than none:
	// fs_write.
	GrantFSWrite Grant = "filesystem.write"
	// GrantMCPServer is capabilities.mcpServers: a declared server's
	// tools.
	GrantMCPServer Grant = "mcpServers"
	// GrantDesktop is capabilities.desktop.servers: an application
	// server's tools on the person's computer.
	GrantDesktop Grant = "desktop"
	// GrantComputerUse is capabilities.desktop.computerUse: the computer
	// use tools.
	GrantComputerUse Grant = "computerUse"
	// GrantClock is capabilities.persistent.clock: a persistent agent's
	// task tools.
	GrantClock Grant = "persistent.clock"
	// GrantMemory is capabilities.persistent.memory: recall.
	GrantMemory Grant = "persistent.memory"
	// GrantSelfConfigure is capabilities.persistent.selfConfigure:
	// self_configure.
	GrantSelfConfigure Grant = "persistent.selfConfigure"
	// GrantMeetings is capabilities.persistent.meetings: the meeting
	// tools.
	GrantMeetings Grant = "persistent.meetings"
	// GrantHelper is capabilities.persistent.helper: the helper tools that
	// search the registry, show, install, run and schedule QuickAgents,
	// open settings and read the docs.
	GrantHelper Grant = "persistent.helper"
	// GrantWeb is capabilities.persistent.web: web_search and web_read.
	GrantWeb Grant = "persistent.web"
	// GrantReview is capabilities.persistent.review: ai_review.
	GrantReview Grant = "persistent.review"
	// GrantSubagents is a persistent release's dependencies.agents naming
	// at least one subagent: subagent_list, subagent_run and
	// subagent_result.
	GrantSubagents Grant = "subagents"
)

The grants a runner tool can need.

func Grants

func Grants() []Grant

Grants returns every grant, in a fixed order.

func (Grant) Path

func (g Grant) Path() string

Path is the manifest path a release adds to hold the grant.

type Missing

type Missing struct {
	// Tool is the tool as the instruction names it, without a harness's
	// mcp__<server>__ prefix for a runner tool; browser_* or host_* for
	// a whole family; <server>__<tool> for a declared server's tool.
	Tool string
	// Grant is what the tool needs; Path is the manifest line to change:
	// Grant.Path(), or capabilities.browser.secrets for browser_evaluate,
	// which a browser that may type secrets is not given.
	Grant Grant
	Path  string
	// Line is the first line, from 1, that names the tool as a need.
	Line int
	// Reason says why in a sentence that quotes no instruction text.
	Reason string
}

Missing is one tool the instruction calls for that the run will not have.

func Check

func Check(c manifest.Capabilities, instruction string) []Missing

Check returns each tool the instruction calls for that the capabilities do not grant, in the order the instruction first names them, at most MaxMissing, reading it as a release that is not persistent. A tool named only where the instruction turns it away is not reported.

func CheckRelease added in v0.6.1002

func CheckRelease(m *manifest.Manifest, instruction string) []Missing

CheckRelease is Check for the release m, read with a persistent agent's tools when its modes include persistent.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL