hermes: add `disable-tools` so operators can extend the driver's disabled tool set

[mostlydev]

Problem

The hermes driver maintains a set of disabled native tools and exposes
allow-tools so an operator can subtract from it. There is no way to
add to it, so an operator cannot disable a native Hermes tool from
claw-pod.yml.

Setting CLAWDAPUS_DISABLED_TOOLS in the pod's environment: does not work
either: the driver computes its own value and writes it per-service into
compose.generated.yml, overriding whatever the pod supplied.

$ grep CLAWDAPUS_DISABLED_TOOLS compose.generated.yml
      CLAWDAPUS_DISABLED_TOOLS: text_to_speech     # driver-written, per service
      ...
  CLAWDAPUS_DISABLED_TOOLS: skill_manage           # operator anchor, ignored

The runtime side is fine — toolsets.py filters on whatever it receives:

_CLAW_DISABLED_TOOLS = {t.strip() for t in
    os.getenv("CLAWDAPUS_DISABLED_TOOLS", "").split(",") if t.strip()}

def _claw_filter_tools(tools):
    if not _CLAW_DISABLED_TOOLS:
        return tools
    return [t for t in tools if t not in _CLAW_DISABLED_TOOLS]

It simply never receives the operator's entries.

Current behaviour

internal/driver/hermes/config.go:436:

func resolveDisabledHermesTools(rc *driver.ResolvedClaw) []string {
    if !hasDiscordHandle(rc) && !hasSlackHandle(rc) {
        return nil
    }
    disabled := []string{hermesTextToSpeechTool}
    if rc == nil || rc.Hermes == nil || len(rc.Hermes.AllowTools) == 0 {
        return disabled
    }
    // ... drops anything present in AllowTools from `disabled`
}

Consumed at config.go:172 and driver.go:203.

Proposal

Add a disable-tools counterpart alongside the existing allow-tools, in the
same x-claw.hermes block:

services:
  my-agent:
    x-claw:
      hermes:
        disable-tools: [skill_manage]

One consistent config surface, no env-var semantics change, no runtime change.

Implementation sketch

1. internal/pod/parser.go:117 — extend rawHermesConfig:

   type rawHermesConfig struct {
       AllowTools   []string `yaml:"allow-tools"`
       DisableTools []string `yaml:"disable-tools"`
       AllowSilent  bool     `yaml:"allow-silent"`
   }

2. internal/pod/parser.go:995 (parseHermesConfig) — trim/validate
   DisableTools the same way AllowTools is handled (reject empty entries
   with an indexed error), and include it in the early-return emptiness check
   so a block containing only disable-tools still produces a config.

3. internal/driver/types.go:95 — add DisableTools []string to
   HermesConfig.

4. internal/driver/hermes/config.go:436 — append rc.Hermes.DisableTools
   to disabled before the AllowTools subtraction, deduping.

5. Precedence — suggest allow-tools wins on conflict (subtraction applied
   last), matching its current "operator re-enables" meaning; a tool named in
   both is enabled. Worth an explicit line in the docs either way.

6. Guard on the handle check — note that resolveDisabledHermesTools
   returns nil early when there is no Discord/Slack handle, so today
   disable-tools would silently no-op for handle-less hermes services. Either
   move the deny list above that check or document the limitation.

Tests

• disable-tools alone produces a config (previously nil when allow-tools
  was empty and allow-silent false).
• Deny entry reaches CLAWDAPUS_DISABLED_TOOLS in the generated compose.
• Deny + allow on the same tool resolves per the documented precedence.
• Empty/whitespace entry is rejected with an indexed error.
• Existing allow-tools behaviour unchanged.

Docs

x-claw reference for hermes: — document disable-tools next to
allow-tools, the precedence rule, and the handle-check caveat.

Motivation

Unattended, scheduled agents. skill_manage lets an agent write into its own
skills directory, and those files are re-read as standing instructions on every
later turn (see #342), so an agent's own conclusion from one turn silently
becomes durable policy with no human in the loop. That is reasonable for an
interactive assistant and risky for a cron-driven one — hence wanting it
configurable per pod rather than removed.

Current workaround is patching toolsets.py from the agent's Clawfile, which
requires an agent image rebuild (neither claw up nor a pull-and-regen
picks it up) and re-breaks whenever that module is reorganized.

Environment

claw version 0.26.0, hermes driver, hermes-base:v2026.6.19-claw.3.

[mostlydev]

Follow-up after reading the driver — the env-var merge I suggested is the wrong
shape. There is already a pod-level surface for this, it just only works in one
direction.

internal/pod/parser.go:118 defines:

AllowTools  []string `yaml:"allow-tools"`

and resolveDisabledHermesTools (internal/driver/hermes/config.go:436) uses it
to subtract from the driver's disabled set:

disabled := []string{hermesTextToSpeechTool}
if rc == nil || rc.Hermes == nil || len(rc.Hermes.AllowTools) == 0 {
    return disabled
}
// ... drop anything present in AllowTools from `disabled`

So an operator can re-enable a tool the driver chose to disable, but there is
no way to add one. CLAWDAPUS_DISABLED_TOOLS is then written per-service
into the generated compose from this result, which is why anything set in the
pod env is overwritten.

The natural fix is a deny counterpart alongside the existing allow list —
e.g. disable-tools in the same x-claw.hermes block — appended to disabled
before the AllowTools subtraction (or after, if allow should win; either is
defensible as long as the precedence is documented). That keeps one consistent
config surface, needs no env-var semantics change, and makes the runtime side
work unmodified, since toolsets.py already filters on whatever it receives.

This is the smallest change that would let an operator disable skill_manage
for unattended agents (the case in #342) without a Clawfile patch or an image
rebuild.

[mostlydev]

Adding measured cost evidence, because this turns out to be a spend issue and not only a governance one.

We decomposed the request payloads of a fleet of scheduled agents over two days.

Prompt cost is linear in mediated rounds — the full context, including the entire tool schema, is re-sent every round:

rounds	prompt tokens
1	39,802
2	79,810
4	183,181
8	444,233

Composition of the most expensive turn (444,233 prompt tokens, 8 rounds):

component	bytes	share
tool schema	58,300	45.1%
injected feeds	40,819	31.6%
tool results	21,000	16.3%
contract	8,230	6.4%
user wake	679	0.5%

Inside that schema, managed service tools are the minority:

• 32 managed tools (declared via x-claw.tools): 20,756 B — 36%
• 15 native runner tools: 37,450 B — 64%

Largest single entries: delegate_task 7,706 B, terminal 5,675, session_search 5,073, memory 2,859, execute_code 2,417, image_generate 2,238, patch 1,928, search_files 1,786.

Observed usage over two days, all agents: delegate_task 0, image_generate 0, vision_analyze 0, patch 0, process 0, cronjob 0, clarify 0. That is 14,071 B of schema, re-billed every round, for tools nothing invoked once.

Role-scoped against measured usage, disabling the unused natives is worth roughly 13.5% of total prompt spend on our fleet. (Our first estimate was 20.2%; that assumed a uniform disable list. 13.5% is the measured, role-aware number — some agents genuinely use terminal, read_file and session_search, so a blanket list would break real jobs.)

This is why allow-tools being subtract-only is costly rather than merely inconvenient: allow-tools scopes managed tools, which are 36% of the schema, while the 64% that is native and largely unused has no operator-facing knob at all.

Two notes for whoever implements this:

1. Please make it per-service, not pod-global. Our coordinator needs terminal for a scheduled shell task, an infra agent needs read_file/search_files, and a router genuinely uses the file surface — while the trading agents use none of them. A single fleet-wide list would force us to keep the expensive tools everywhere.
2. skill_view/skills_list/memory should be easy to retain; they are heavily used and are how agents read operator-provided references.

We are currently using the image-adapter workaround noted above and extending the existing disabled set rather than adding a second filtering path.