Project Plugin Trust & Management
Manage project plugins: the trust banner, staged activation, Run here and Show here controls, settings scopes, secret storage, binding, and reload behavior.
Project plugins arrive through a clone, pull, or repository edit. Daintree discovers their manifests before running them, and keeps the folder disabled until you decide to trust it. This page explains that decision, the controls for individual plugins, and where a project tool stores its data.
The first trust decision
When the registered project root contains at least one valid project plugin and no trust decision is recorded, Daintree shows a nonmodal trust banner. It names the plugins and explains that their code runs with your account. It does not interrupt the active terminal with a modal dialog.
| Choice | Effect |
|---|---|
| Keep disabled | Remember the refusal for this project. No plugin code runs. You can enable the folder later in project settings. |
| Enable for this session | Allow the folder while this project remains live in the current app session. Closing, sleeping, or auto-parking the project discards this temporary grant; reopening can ask again. The choice is not persisted. |
| Always enable | Persist the project-level trust decision in Daintree's own store. |
| Decide later | Dismiss the banner without making a decision. Plugins remain off; the sidebar indicator and project settings keep the controls available. |
The decision covers the folder and everyone who can change its contents, including agents working in the repository. Project plugins run ordinary Node code in utility workers; capability declarations do not create a runtime sandbox. There are no filesystem permission checkboxes in this banner that claim otherwise.
What happens after a pull or branch change
Known plugins in a trusted project reload after changes to plugin.json or dist/ without asking you to approve each new version. That includes edits from pulls, branch switches, and agents. Review those changes through your normal source review process.
A previously unseen manifest id is staged. Daintree parses and lists it, announces it once, and waits for Activate plugin. Ignoring the notice leaves it staged. With persisted trust, staging survives a restart. A known id that disappears and later returns is treated as returning, so a branch round trip does not turn it into a new plugin.
All worktrees belonging to the registered project use its trust decision. They are not separate discovery roots. A separately registered clone has its own project identity and decision; a moved folder that Daintree recognizes as the existing project can retain that identity. Do not use a Git-tracked file as evidence that a new user already trusted the code.
Manage the folder and individual plugins
Open Project settings → Plugins. The selector includes This project, the repository's plugins, and installed plugins. The overview controls folder trust and offers Re-scan plugins folder. Selecting a project plugin shows its source path, declared capabilities, status, settings, Reload from disk, and Reveal folder.
| Control | What stops | What is remembered |
|---|---|---|
| Run here, turned off for one project plugin | That plugin unloads and stays muted for this project. | Folder trust and existing capability grants remain. Other project plugins keep running. |
| Turn off project plugins | Every plugin from the project folder unloads, including its contributions and asset authorities. | The disabled decision persists and the project's capability grants are purged. |
| Close, sleep, or auto-park the project | Its loaded plugin instances unload. | Remembered trust remains for a later open. Session-only trust is discarded. Closing does not purge stored capability grants. |
| Remove a plugin from the repository | The watcher unloads the missing plugin. | Its known identity and retained panel state allow a returning branch to recover. |
Turning Run here back on restores a known plugin only when folder trust allows it. A muted staged plugin cannot activate while muted. These preferences belong to the local Daintree installation; they do not rewrite the plugin's manifest or remove its repository directory.
The global Plugin Manager also lists repository plugins under This project, with source details, staged activation, load errors, and logs. An Id clash indicator means an installed plugin uses the same manifest name; both can coexist because runtime identities differ.
Hiding an installed plugin is different
An installed plugin's Show here switch controls its visibility in the current project. It hides that plugin's panels, commands, toolbar buttons, keybindings, and context menus from the project's views. The plugin remains installed and running. Its app-wide agents, recipes, forge providers, and file decorations continue to operate.
Where it shows up sets the default to Every project or Only projects I turn it on in; individual projects can override that choice. This is useful for keeping a specialized tool visible only in the repositories where you use it. To stop an installed plugin globally, disable it in global plugin settings or the Plugin Manager.
Capabilities and project binding
The manifest's capability list discloses intent and drives host-side action policy. Supported host APIs also check declarations, filesystem containment, and first-use consent where applicable. These checks remain in force after folder trust is granted. Capability grants are keyed per runtime plugin instance, so approving one project's copy does not approve another's.
Project-bound host calls resolve their owning project rather than following focus. Dispatch and UI prompts reject with PROJECT_VIEW_UNAVAILABLE if that project has no available renderer; read-only action catalog calls return empty or unavailable results. Filesystem tokens, worktree reads, project settings, and worktree storage resolve against the same binding. This prevents a supported host call from silently falling through to another project's active view.
Settings, storage, and secrets
Choose a persistence scope based on who should share the value. A setting's declared scope is authoritative: omitting the scope when reading resolves its declaration, and an explicit conflicting scope is rejected.
| Surface | Use it for | Where it lives |
|---|---|---|
settings, scope project | Shared repository configuration such as service names and team defaults. | <projectRoot>/.daintree/plugin-settings/<manifestId>.json |
settings, scope local | This machine's setting for this project, such as an interpreter path or environment-specific credential. | Under ~/.daintree/plugin-settings/local/<projectId>/, outside the repository. |
settings, scope user | Preferences for the plugin instance across its worktrees. | Under ~/.daintree/plugin-settings/. Project plugins use their instance identity, keeping other project copies separate. |
storage, scope user | Private plugin working state; the default storage scope. | ~/.daintree/plugin-storage/<instanceKey>.json |
storage, scope project or worktree | Working state deliberately associated with the project or its current worktree. | .daintree/plugin-storage/<manifestId>.json under that root. |
Panel persistState | Small view state such as selection, expansion, and sort order. | The panel's saved extensionState bag; read back through initialArgs on mount. |
The in-repository filenames use manifest ids, so a teammate's machine-specific project identity does not become part of a tracked filename. Worktree storage follows the bound project's current worktree; if no such worktree exists, reads return undefined and writes reject instead of falling back to another project.
storage and panel state are plaintext JSON. Credentials belong in a type: "secret" setting, preferably local or user scope. Secret settings use OS-backed encryption when available, with an explicitly indicated plaintext fallback on hosts without a usable backend. Project scope remains a repository file; do not commit credentials there.
Reloads and missing panels
Settings and storage survive reloads. Worker module variables and React state do not. Persist state that matters and initialize the view from saved data when it mounts.
If a plugin kind disappears because trust is off or a branch lacks the plugin, existing panels are retained as Plugin unavailable placeholders. Reintroducing the plugin can restore them. Saved project-plugin kinds still carry the runtime project qualification at this revision, so restoring a layout across a separately registered re-clone is not guaranteed.
Implementation and tests
- Trust banner and Project settings controls: actual labels and UI behavior.
- ProjectPluginController and its tests: decisions, staged ids, mute preferences, and revocation.
- PluginSettingsManager, PluginStorageManager, and panel-kind persistence helpers: storage and identity boundaries.