[FEATURE] Allow plugin settings.json to ship more default settings (at minimum permissions, env, statusLine)

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

A plugin can ship a settings.json at its root, but it currently honors only two keys — agent and subagentStatusLine. Per the plugin docs:

Plugins can include a settings.json file at the plugin root to apply default configuration when the plugin is enabled. Currently, only the agent and subagentStatusLine keys are supported. [...] Unknown keys are silently ignored.

This means a plugin author cannot ship the settings their own bundled components need to work. The components install, but the configuration that makes them usable does not:

• MCP servers (.mcp.json) and bin/ executables routinely require permissions.allow entries. A plugin can install the server but cannot pre-approve its tools, so every user hits permission prompts on first use — and subagent / Agent-tool flows can stall silently on the MCP permission gate (see #61315).
• env — plugins that wrap a CLI or service often need default environment variables; there's no way to provide them.
• statusLine — a plugin can now ship a status-line script via bin/, but still can't wire it up as a default.

The failure mode is especially confusing because unknown keys are silently dropped — an author who adds permissions or env to their plugin's settings.json gets no error and no effect.

The net result: distributing a working, batteries-included plugin to a team or community is not actually possible today. Each user must hand-edit their own settings.json to add allowlist/env entries that the plugin already knows it needs, which defeats the purpose of packaging and distributing the plugin in the first place

Proposed Solution

Expand the set of keys honored in a plugin's root settings.json to include at least permissions, env, and statusLine, applied as defaults when the plugin is enabled.

Ideal behavior:

• Defaults, not overrides. Plugin-shipped settings sit at the lowest precedence — below user, project, and local settings — so anything the user (or their org) configures always wins. Managed settings remain authoritative and can override or forbid plugin-shipped values entirely.
• Scoped permissions. As a conservative first step, support permissions.allow only (not deny / ask), scoped to the plugin's own MCP tools and bin/ executables. This directly resolves the recurring permission-allowlist asks (#64750, #62616).
• No silent drops. Surface unsupported or unknown keys with a load-time warning instead of silently ignoring them, so authors get feedback while iterating.
• Visible at install/enable. Because a plugin granting itself permissions is sensitive, surface plugin-shipped permissions to the user at install/enable time, and let managed settings disable this behavior org-wide.

Example of what a plugin author would ship:

// my-plugin/settings.json
{
  "permissions": {
    "allow": [
      "mcp__my-plugin__*",
      "Bash(my-plugin-cli:*)"
    ]
  },
  "env": {
    "MY_PLUGIN_REGION": "us-east-1"
  },
  "statusLine": {
    "type": "command",
    "command": "${CLAUDE_PLUGIN_ROOT}/bin/statusline"
  }
}

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

For organizations that maintain internal plugins distributed through a private marketplace. It bundles:

• several MCP servers (defined in .mcp.json) for internal tooling, and
• a couple of bin/ executables used by the plugin's skills.

Today, the rollout looks like this:

1. A teammate installs the plugin from the marketplace and enables it.
2. They invoke a skill that calls one of the plugin's MCP tools.
3. Claude Code prompts them to approve the tool. They approve it.
4. They invoke another skill — a different MCP tool — and get prompted again.
5. A skill dispatches an Agent-tool subagent that needs an MCP tool. The subagent stalls silently on the permission gate (no prompt surfaced to the parent UI), and the flow appears to hang (#61315).
6. To make it work smoothly, each teammate has to manually edit their own settings.json to add the permissions.allow entries — entries the plugin already knows it needs. We end up documenting these in a README and asking everyone to copy-paste them.

With this feature, the rollout would be:

1. We add a settings.json to the plugin that pre-allows the plugin's own MCP tools and bin/ executables (and sets a default env var or two).
2. A teammate installs and enables the plugin. At enable time they see which permissions the plugin requests.
3. Every bundled skill, MCP tool, and subagent flow works out of the box — no per-tool prompts, no manual settings.json editing, no copy-paste README step.
4. Anyone who wants to tighten or change a setting just adds their own value, which overrides the plugin default.

Additional Context

There are additional fields in the settings.json that would be valuable as well.

For example adding things to the autoMode section, if we have Claude Skills that do write actions we want to allow from the plugin it'd be nice to add additional things for automode to consider for that.