Files
pipelines/internal/stage/tools.go
T
alan c41bf4f5b0 State each model stage's permitted tools in its prompt
A planner had no machine-readable view of the tool set later stages would
have, so it could emit acceptance checks that required tools (shell) the
implementer was not permitted, causing a blocked run.

modelPrompt now emits exactly one authoritative line naming the stage's
permitted tools, derived from the definition via the new effectiveTools
helper. effectiveTools reuses ToolNames: a present tools block, including
an explicit empty one, is returned as parsed; an absent block yields the
legacy mutating read/glob/grep/edit/shell bundle so it is never
misrepresented as empty or read-only. The bundle is declared once as
legacyTools and reused by tools.go, agent.go, pi.go and permissions.go.

The redundant client-side strings.Replace of the tools line is removed
from AgentClient.Generate and PiClient.Generate; the agent-only guidance
sentence is preserved by appending it in agent.go, and Pi appends a short
mapping line derived from piTools. Edit-scope and permitted-shell text,
routing, review, budgets and retries are unchanged.

Adds internal/stage/model_prompt_test.go covering explicit, absent and
explicit-empty blocks plus derivation edge cases, and a guard that the
agent prompt still carries the tools, edit-scope and shell-command text.
2026-10-16 23:34:39 +01:00

147 lines
4.7 KiB
Go

package stage
import (
"fmt"
"path/filepath"
"regexp"
"strings"
)
// ToolNames validates model-stage permissions, not general graph semantics.
// A present empty block explicitly denies all tools.
func ToolNames(def Definition) ([]string, bool, error) {
text, present := def.Blocks["tools"]
if !present {
return nil, false, nil
}
tools := []string{}
seen := map[string]bool{}
for _, line := range strings.Split(text, "\n") {
name := strings.TrimSpace(line)
if name == "" {
continue
}
switch name {
case "websearch", "webfetch", "read", "glob", "grep", "edit", "shell":
default:
return nil, true, fmt.Errorf("unsupported tool %q", name)
}
if seen[name] {
return nil, true, fmt.Errorf("duplicate tool %s", name)
}
seen[name] = true
tools = append(tools, name)
}
return tools, true, nil
}
// legacyTools is the single declaration of the implicit tool set for a stage
// with no tools block: the mutating read/glob/grep/edit/shell bundle. It is
// never nil or empty, so an absent block is never represented as a read-only or
// text-only stage.
var legacyTools = []string{"read", "glob", "grep", "edit", "shell"}
// effectiveTools is the single materialisation point for the tools a model
// stage is permitted. A present tools block (including an explicit empty block)
// is returned exactly as parsed by ToolNames; an absent block yields the legacy
// mutating bundle so it is never silently narrowed to an empty or read-only set.
func effectiveTools(def Definition) ([]string, error) {
tools, explicit, err := ToolNames(def)
if err != nil {
return nil, err
}
if !explicit {
return legacyTools, nil
}
return tools, nil
}
// safeToReplay is the single definition of which post-admission work may be
// automatically retried. Only an explicit tools block that selects neither
// "edit" nor "shell" is side-effect free. An absent block is the legacy
// read/glob/grep/edit/shell bundle and is treated as mutating, matching the
// runner's useAgent/permissionRules semantics.
func safeToReplay(def Definition) bool {
tools, explicit, err := ToolNames(def)
if err != nil || !explicit {
return false
}
for _, tool := range tools {
if tool == "edit" || tool == "shell" {
return false
}
}
return true
}
func (c *AgentClient) permissionRules() []map[string]string {
rules := []map[string]string{{"action": "*", "resource": "*", "effect": "deny"}}
tools := c.Tools
// A missing block gets normal local agent tools. Explicit stage blocks still
// select which tools are available, including an empty block for text-only work.
if tools == nil {
tools = legacyTools
}
allow := func(action, resource string) {
rules = append(rules, map[string]string{"action": action, "resource": resource, "effect": "allow"})
}
for _, tool := range tools {
switch tool {
case "websearch", "webfetch", "read", "glob", "grep":
allow(tool, "*")
case "edit":
if len(c.WritePaths) == 0 && c.Policy.Edit == nil {
allow("edit", "*")
rules = append(rules, map[string]string{"action": "edit", "resource": "/*", "effect": "deny"})
if c.Directory != "" {
allow("edit", filepath.ToSlash(filepath.Join(c.Directory, "*")))
}
} else {
paths := c.WritePaths
if len(paths) == 0 {
paths = c.Policy.Edit
}
// Relative patterns may also match absolute paths. Deny those first,
// then grant only absolute equivalents inside the run directory.
for _, path := range paths {
if c.Policy.Edit == nil || matchesEditPolicy(c.Policy.Edit, path) {
allow("edit", filepath.ToSlash(path))
}
}
rules = append(rules, map[string]string{"action": "edit", "resource": "/*", "effect": "deny"})
for _, path := range paths {
if c.Directory != "" && (c.Policy.Edit == nil || matchesEditPolicy(c.Policy.Edit, path)) {
allow("edit", filepath.ToSlash(filepath.Join(c.Directory, path)))
}
}
}
for _, pattern := range []string{"../*", "*/../*"} {
rules = append(rules, map[string]string{"action": "edit", "resource": pattern, "effect": "deny"})
}
case "shell":
if c.Policy.Shell == nil {
allow("shell", "*")
} else {
for _, command := range c.Policy.Shell {
allow("shell", command)
}
}
}
}
for _, pattern := range []string{"*.env", "*.env.*", "pipelines.db*"} {
rules = append(rules, map[string]string{"action": "read", "resource": pattern, "effect": "deny"})
}
return rules
}
func matchesEditPolicy(patterns []string, path string) bool {
for _, pattern := range patterns {
// OpenCode resource wildcards match across directory separators.
re := strings.ReplaceAll(strings.ReplaceAll(regexp.QuoteMeta(pattern), `\*`, ".*"), `\?`, ".")
if ok, _ := regexp.MatchString("^"+re+"$", filepath.ToSlash(path)); ok {
return true
}
}
return false
}