Claude Code: Persistent Plugin State and Agent Frontmatter for Plugin-Shipped Agents

Plugin Development Before v2.1.78

Claude Code's plugin system lets developers package tools, hooks, and agents into distributable units that others can install with /plugin install. Before this release, plugins faced two significant limitations that constrained what could be built and distributed practically.

First, plugins had no dedicated persistent storage. Any data a plugin needed to retain — API credentials, user preferences, accumulated context, cache — had to be stored in locations managed by the plugin author, with no guarantee of where those locations were relative to the plugin's install path. Plugin updates could overwrite or orphan that stored data. There was no standard.

Second, agents bundled inside plugins could only be configured via the fields Claude Code always supported in agent frontmatter. The effort, maxTurns, and disallowedTools fields — which let authors specify how hard an agent should think, how many turns it may take, and which tools it cannot use — were not available in plugin-shipped agents. Authors who wanted to distribute focused, constrained agents had to ask end users to manually configure these behaviors.

Persistent Plugin Data: ${CLAUDE_PLUGIN_DATA}

Version 2.1.78 introduces ${CLAUDE_PLUGIN_DATA}, a new variable available to plugin scripts that expands to a stable, plugin-specific directory for persistent storage. The directory is:

• Scoped per plugin — each installed plugin gets its own subdirectory, preventing data collisions between plugins
• Stable across updates — reinstalling or updating a plugin does not delete the directory or its contents
• Managed by Claude Code — the directory is created automatically on first use; plugin authors do not need to handle directory creation

A plugin can use this path to store anything that should survive the plugin's own lifecycle: a SQLite database of accumulated knowledge, cached API responses, user-specific configuration, or OAuth tokens. The variable is available in hook scripts, subagent scripts, and any other executable the plugin ships.

Safe Uninstall Prompt

To match the new persistence capability, /plugin uninstall now prompts before deleting plugin data. When a plugin has stored data in ${CLAUDE_PLUGIN_DATA}, uninstalling will ask whether to preserve or delete that directory. This prevents the common accident of uninstalling a plugin and losing state that took time to accumulate — credentials, tuned preferences, or a months-old cache.

Agent Frontmatter in Plugins: effort, maxTurns, disallowedTools

The second improvement gives plugin-shipped agents three new frontmatter fields:

effort

The effort field controls the model's extended thinking budget for the agent. Plugin authors can now specify whether their agent should use minimal, standard, or high effort — matching the thinking budget to the task's complexity without requiring users to understand or configure this themselves. A plugin shipping a fast, focused code-review agent can set effort: low; a plugin shipping a deep architectural analysis agent can set effort: high.

maxTurns

maxTurns caps how many conversation turns the agent may take before stopping. This is a hard limit on agent scope — it prevents a bundled agent from running indefinitely or expanding beyond its intended purpose. A plugin for a well-scoped task (e.g., "summarize this PR") can enforce a low turn limit, making the agent's behavior predictable and its cost bounded.

disallowedTools

disallowedTools is a list of tools the agent is not permitted to use, even if they are available in the user's environment. A plugin that ships a read-only audit agent can disallow all write tools. A plugin focused on documentation can disallow shell execution. This allows plugin authors to make explicit, verifiable claims about what their agent can and cannot do — a meaningful step toward trustworthy, distributable agent packages.

What These Changes Make Possible

Together, ${CLAUDE_PLUGIN_DATA} and the new frontmatter fields solve two of the most significant practical barriers to building production-grade Claude Code plugins.

A plugin can now:

• Bundle a pre-configured agent that users install and run without any manual setup — the agent's behavior, scope, and tool access are all defined by the plugin author in frontmatter
• Accumulate state over time without risk of losing it to updates or reinstalls
• Present a safety boundary — the combination of disallowedTools and maxTurns means plugin authors can credibly describe what an agent will and will not do, making plugins easier to audit and approve in team environments

The ${CLAUDE_PLUGIN_DATA} variable and the frontmatter additions are additive and work naturally together. A plugin can ship an agent that stores its accumulated context in the persistent data directory, with frontmatter-defined constraints that keep the agent focused on its intended scope regardless of what the user's broader Claude Code configuration looks like.

Implications for the Plugin Ecosystem

These additions move Claude Code's plugin system meaningfully closer to a model where plugins are self-contained, distributable products — not just collections of scripts that require user configuration to work. For teams that use Claude Code in shared environments, or for developers building tools for others, this is the release that makes plugins worth investing in seriously.