Plugin permission reference

A PluginPermission is one exact string in manifest.json.permissions. Permissions gate supported Plugin API operations and approved host commands for the installed plugin identity. They do not sandbox community plugin JavaScript or guarantee that the operating system will permit an approved operation.

Complete permission catalog

Risk labels are review cues, not security ratings. A low-risk label does not make an operation harmless in every workflow, and a high-risk label does not mean the operation is prohibited.

filesystem.read

Accepted manifest value:

{
	"permissions": ["filesystem.read"]
}

This permission gates supported Plugin API operations that inspect arbitrary user files and folders. It does not grant a write, rename, Trash, clipboard, or network operation.

Provider-scoped reads explicitly supplied to MetadataProvider extraction are available through MetadataAPI without adding a broad manifest permission. Their scope and lifetime are part of that provider contract.

filesystem.write

Accepted manifest value:

{
	"permissions": ["filesystem.write"]
}

This permission implies the supported filesystem.read operations. Do not declare both:

{
	"permissions": [
		"filesystem.read",
		"filesystem.write"
	]
}

The redundant pair is invalid. filesystem.write covers supported mutation, not arbitrary shell execution or permanent-delete commands. The typed Trash operations move items to the operating system’s Trash.

clipboard.read

Accepted manifest value:

{
	"permissions": ["clipboard.read"]
}

This permission gates reading current text through api.clipboard.readText(). It does not grant clipboard writes.

Clipboard content may contain credentials or private user data. Read it only from a clear user workflow and do not include it in diagnostics by default.

clipboard.write

Accepted manifest value:

{
	"permissions": ["clipboard.write"]
}

This permission gates replacing current clipboard text through api.clipboard.writeText(text). It does not grant clipboard reads.

network.fetch

Accepted manifest value:

{
	"permissions": ["network.fetch"]
}

This permission gates api.fetch(input, init). It does not imply file or clipboard access.

network.fetch applies to the supported Plugin API wrapper. Community plugins run as trusted renderer JavaScript, so it is not a network sandbox for ambient browser APIs or bundled dependencies.

workspace-folders.read

{
	"permissions": ["workspace-folders.read"]
}

This permission gates protected reads through api.workspaceFolders. Basic pane capability state does not reveal protected schemas, values, or known Workspace Folder paths.

workspace-folders.write

{
	"permissions": ["workspace-folders.write"]
}

This permission implies workspace-folders.read. Declaring both is invalid. It is distinct from filesystem.write: changing Workspace Folder properties is not the same trust decision as changing file bytes.

Invalid permission names

The permission list is a closed enum. Every string outside the seven catalog values is invalid, including:

shell.execute
filesystem.delete
filesystem
network
network.request
clipboard
process.execute
*

There is no catch-all permission and no supported shell or process-execution permission. Letter case matters; Filesystem.Read is invalid.

Values must appear at most once. Non-string values and null are invalid.

Permission review

Phials compares the complete requested set with the last set approved for the installed plugin ID. Ordering does not affect comparison.

Review is required when:

• a plugin is installed for the first time, including with an empty set;
• an update adds a permission;
• an update removes a permission; or
• an update replaces one permission with another.

Until the current set is approved, the community plugin cannot activate. An earlier approval does not approve later permission changes. The enabled preference remains recorded while review or community plugin safe mode blocks activation.

Approval does not bypass:

• community plugin safe mode;
• minimum Phials or Plugin API compatibility;
• module loading and plugin activation;
• the approved api.invoke command allowlist; or
• operating-system errors and access controls.

The exact typed-operation mapping is in Permission-gated Plugin API operations.