Background

PR #1742 introduced tools.alsoAllow to solve the problem where users setting tools.allow = ["lobster"] accidentally disable all other tools. While this works, having two separate fields (allow and alsoAllow) adds config complexity and potential confusion.

Current State

// Restrictive - only these tools enabled
{ "tools": { "allow": ["exec", "fs"] } }

// Additive - all default tools + these extras  
{ "tools": { "alsoAllow": ["lobster"] } }

// Invalid - mutual exclusion enforced
{ "tools": { "allow": ["exec"], "alsoAllow": ["lobster"] } }

Goal

Simplify the allowlist UX while preserving both restrictive and additive use cases.

Proposed Solutions

Option 1: Unify with allowMode

Single allow field with explicit mode selector:

// Additive (default for better UX)
{ "tools": { "allow": ["lobster"] } }

// Restrictive (explicit opt-in)
{ "tools": { "allow": ["exec", "fs"], "allowMode": "restrictive" } }

Pros: One field, clear intent and secure by default.
Cons: Might introduce a breaking change and undesired output if we flip the default behavior.

Option 2: Rename for clarity

Replace both fields with semantically clear names:

// Restrictive
{ "tools": { "onlyAllow": ["exec", "fs"] } }

// Additive
{ "tools": { "alsoAllow": ["lobster"] } }

Pros: No ambiguity, both use cases explicit
Cons: Deprecates allow (migration needed)

Option 3: Smart detection (least disruptive)

Keep current fields but auto-detect intent:

• If allow contains only plugin tools → treat as additive
• If allow contains core tools → treat as restrictive

Pros: No config changes needed
Cons: Implicit magic, harder to reason about

Migration Considerations

• tools.allow is widely used - any change needs deprecation period
• Consider clawdbot doctor migration to rewrite configs
• Document behavior change clearly in release notes

Acceptance Criteria

• Single clear way to express "default tools + extras"
• Single clear way to express "only these tools"
• Migration path for existing tools.allow users
• Updated docs and examples
• Config validation catches conflicting settings

Related

• PR feat(config): tools.alsoAllow additive allowlist #1742: feat(config): tools.alsoAllow additive allowlist