feat(agent): allow variable tool permission modes

[j15z]

Summary

Let an agent tool's Permission Mode be a fixed selector value or a variable such as <start.toolMode>. The expression is resolved before tool filtering, and anything other than auto, force, or none is rejected before provider or tool work starts.

• Stores the fixed usageControl and the usageControlExpression separately, with a selector/variable toggle in the expanded tool controls.
• API and Copilot edits select the mode from the field they send. A tool that carries both values keeps its current mode, and each tool keeps its mode when an edit reorders the tools list.
• Preserves the expression through workflow search, import/export, and sanitization, and adds it to the v2 OpenAPI spec and generated CLI types.
• Moves Permission Mode from the tool header into the expanded tool. Clicking a tool header now expands it (custom and MCP tools included), a pencil button opens the custom tool editor, and a tool set to None is greyed out.

Companion: simstudioai/mothership#488

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• Other: ___________

Testing

• Unit and engine tests cover fixed and variable resolution, invalid values, secret tracking, mode selection and unchanged round trips through API edits, modes following reordered tools, import/export, search, and sanitization.
• type-check, lint, check:api-validation, check:openapi, check:cli-api, and check:cli-docs pass, and CI passes.
• Manual Chrome and CLI testing covered selector and variable modes end to end.

Reviewers: applyAgentToolUsageControlModesAfterEdits in lib/workflows/editing/engine.ts runs after the tool canonical-mode reindex, so a mode chosen through an API edit lands on its tool's final position.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Screenshots/Videos

Before:

After:

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 14, 2026 6:24pm UTC

[j15z]

@greptile

[j15z]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@j15z I have started the AI code review. It will take a few minutes to complete.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no actionable new defects or outstanding previous findings remain.

Summary

• Resolves and validates the active permission mode before tool discovery, transformation, or provider work.
• Adds editor controls and canonical-mode handling for fixed and variable representations.
• Preserves expressions through API contracts, editing, sanitization, import/export, and workflow search.
• Updates generated OpenAPI and CLI artifacts and adds focused regression coverage.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Stored Agent tool] --> B{Canonical permission mode}
  B -->|Selector| C[Use fixed usageControl]
  B -->|Variable| D[Resolve usageControlExpression]
  D --> E{Auto, Force, or None?}
  E -->|No| F[Reject before tool or provider work]
  E -->|Yes| G[Apply resolved mode]
  C --> G
  G --> H{Mode is None?}
  H -->|Yes| I[Exclude tool]
  H -->|No| J[Transform and send tool to provider]

Loading

_{Reviews (12) · Last reviewed commit: "docs(agent): document the tool Permissio..."}

[github-actions]

✅ Cross-repo companion check

All declared companion PRs are merged into staging.

• ✅ simstudioai/mothership#488 — merged into staging — feat(workflow): document variable agent tool permissions

[j15z]

@greptile

[j15z]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@j15z I have started the AI code review. It will take a few minutes to complete.

[j15z]

@greptile

[j15z]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@j15z I have started the AI code review. It will take a few minutes to complete.

[j15z]

@greptile

[j15z]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@j15z I have started the AI code review. It will take a few minutes to complete.

[j15z]

@greptile

[j15z]

@greptile