Documentation
¶
Overview ¶
Package agents bridges clawtool to the host AI coding agents that embed it (Claude Code, Codex, OpenCode, …). Per ADR-011 the role of this package is the **hard-replacement** of native tools — i.e. flipping the host agent's settings so clawtool's `mcp__clawtool__*` becomes the only Bash/Read/Edit/Write/Grep/Glob/WebFetch/WebSearch the model can see.
Each host gets one Adapter implementation. The Adapter only needs to know how to read its settings, claim a known set of tools (atomic write + idempotent), release them, and report status. The CLI subcommand (internal/cli/agents.go) is a thin dispatcher over this interface.
Claude Code adapter — mutates ~/.claude/settings.json's `permissions.deny` array to take native Bash/Read/Edit/Write/Grep/ Glob/WebFetch/WebSearch out of the model's tool surface, leaving only mcp__clawtool__*.
Wire-format note: earlier versions of this adapter wrote to a top-level `disabledTools` field. Claude Code 2.x ignores that key — the canonical mechanism is `permissions.deny`. On read we still recognize the legacy field and migrate it forward; on write we only emit `permissions.deny`.
Package agents — genericAdapter is a parameterised adapter that mirrors claude-code's settings.json + permissions.deny shape but lets the registration site point at any other config dir + field name. Used to ship support for new agents without writing a full adapter file each time.
Today this is best-effort: hermes-agent and openclaw both presumably load a similar JSON config but their exact deny- field name may shift. The adapter is structured so a future PR can swap the field via a one-line change.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ClaimedToolsForClawtool = []string{
"Bash",
"Edit",
"Glob",
"Grep",
"Read",
"WebFetch",
"WebSearch",
"Write",
}
ClaimedToolsForClawtool is the canonical set of native tool names every adapter disables when claiming. Per ADR-011 this is exactly the 1:1 mapping with clawtool's core tools that have native equivalents.
Stored here (not per-adapter) because the mapping is identical across hosts — Claude Code calls them `Bash`, `Read`, etc.; other hosts use the same names since they all converged on Claude Code's vocabulary. If Codex / OpenCode use different native names, override per adapter.
var ErrUnknownAgent = errors.New("unknown agent")
ErrUnknownAgent is returned by Find when the requested agent isn't in the Registry. CLI catches this to print the list of known agents.
var Registry = []Adapter{}
Registry is the set of available adapters. Adapters self-register in their package's init() function so adding a host is one new file.
Functions ¶
func Register ¶
func Register(a Adapter)
Register adds an adapter to the registry. Sorted by Name for stable CLI output across runs.
func SetClaudeCodeSettingsPath ¶
func SetClaudeCodeSettingsPath(p string)
SetClaudeCodeSettingsPath redirects the adapter to a custom settings path. Tests use it; production should never call it.
func SetGenericAdapterPath ¶ added in v0.9.0
func SetGenericAdapterPath(name, path string)
SetGenericAdapterPath retargets one of the generic adapters at a custom path. Test-only; production code never calls this.
Types ¶
type Adapter ¶
type Adapter interface {
Name() string
// Detected returns true when the host's settings file exists or
// the host is otherwise configured on this machine. False means
// the agent isn't installed; CLI commands should report
// "not detected" instead of failing.
Detected() bool
// Claim disables the native tools clawtool replaces. Idempotent.
Claim(opts Options) (Plan, error)
// Release re-enables every tool clawtool's previous Claim
// disabled (tracked via the per-adapter marker file). Idempotent.
Release(opts Options) (Plan, error)
// Status reports what's currently claimed.
Status() (Status, error)
}
Adapter describes one host AI coding agent. Implementations live in per-host files (claudecode.go for Claude Code, codex.go later, …).
Implementations MUST:
- Be idempotent for Claim and Release (run twice = same result).
- Use atomic writes (no partial state observable on crash).
- Touch ONLY the fields/files they own. User customizations stay.
- Track ownership via a marker file so Release only undoes what this clawtool installation added.
type Options ¶
type Options struct {
DryRun bool
}
Options carries per-call flags the CLI propagates.
type Plan ¶
type Plan struct {
Adapter string // "claude-code"
Action string // "claim" | "release" | "noop"
SettingsPath string // file the adapter would mutate
MarkerPath string // file the adapter would write to track ownership
ToolsAdded []string // tools claim is about to disable
ToolsRemoved []string // tools release is about to re-enable
WasNoop bool // already in the requested state
DryRun bool
}
Plan is what an adapter would do (or did, in non-dry-run). The CLI renders this for human consumption.
type Status ¶
type Status struct {
Adapter string
Detected bool
SettingsPath string
Claimed bool // true when our marker file exists and lists tools
DisabledByUs []string // tools we disabled (read from marker)
Notes string // anything an adapter wants to surface (e.g. "settings file missing")
}
Status is a snapshot of the adapter's current claim state.
Source Files