[FEATURE] Allow specifying tool permissions in agents and plugins

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When sharing a custom agent or plugin in a marketplace, I want to be able to establish sensible permissions both to ensure the safety and proper level of automation.

As far as I know, it's only possible to set permissions like this either in my user settings or in the settings in the directory I'm working in, but it's not possible to create settings that are scoped to the plugin. This seems like it would be an important way to allow plugin authors to tune the balance of automation and safety for their functionality.

Proposed Solution

Allow a settings.json file to be included in either of the following directories:

• A plugin's directory
• A custom agent's directory

Settings provided by the file are scoped to the entity (plugin or agent) associated with that directory.

Settings can include "permissions".

For security, permissions that have been explicitly limited in an outer scope cannot be loosened ("deny" -> { "ask", "allow" } or "ask" -> "allow") in an inner scope.

It might be worth allowing subagent permissions to be set in the document's front-matter for convenience (instead of in a separate settings.json file), but I don't know if the syntax would be too unwieldy.

Alternative Solutions

My current workaround is to document in the plugin's README optional instructions for configuring the settings in ./.claude/settings.json.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

I've been developing a git utility plugin that assists in rewriting a PR branch's commit history for code review. The custom agents and skills in the plugin have enough guardrails that it's safe to allow Read/Write/Edit and most git commands by default. But the plugin should never do things like talk to a git remote.

So it would be appropriate to set the permissions to e.g.:

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Write(*)",
      "Edit(*)",
      "Bash(git status:*)",
      "Bash(git log:*)",
      "Bash(git diff:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(git checkout:*)",
      "Bash(git rev-parse:*)",
      "Bash(git merge-base:*)",
      "Bash(npm *)",
      "Bash(yarn *)",
      "Grep(*)",
      "Glob(*)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(git rebase:*)",
      "Bash(git reset:*)",
      "Bash(rm:*)"
    ]
  }
}

Additional Context

I have an example plugin with several subagents at https://github.com/dherman/claude-plugins/tree/main/plugins/historian -- it would benefit from being able to specify these permissions.