Skip to content

docs(plugins): clarify permission requirements for non-built-in plugins#299

Open
dsaenztagarro wants to merge 1 commit intozellij-org:mainfrom
dsaenztagarro:plugin-permissions-docs
Open

docs(plugins): clarify permission requirements for non-built-in plugins#299
dsaenztagarro wants to merge 1 commit intozellij-org:mainfrom
dsaenztagarro:plugin-permissions-docs

Conversation

@dsaenztagarro
Copy link
Copy Markdown

Summary

When forking a built-in plugin (e.g. session-manager) and loading it via file:, the plugin crashes because built-in plugins never call request_permission() — they bypass permission checks entirely via is_builtin(). This is not documented anywhere, making it a common pitfall.

This PR adds guidance across three documentation pages:

  • plugin-api-permissions.md — New "How permissions work" section explaining the difference between built-in (zellij:) and non-built-in (file:, http(s):) plugins, with a code example and a callout for plugin forking
  • plugin-aliases.md — Warning when swapping default aliases to file: plugins
  • plugin-lifecycle.md — Note in the load() section that non-built-in plugins must request permissions

Motivation

I forked session-manager to add custom keybindings, loaded it via file: in the plugin aliases, and it crashed with a panic at zellij-tile/src/shim.rs (bytes_from_stdin().unwrap() on <NO PAYLOAD>). The root cause: CurrentSessionLastSavedTime requires ReadApplicationState, which was silently denied because the plugin never called request_permission(). The host writes no response on denial, so the plugin panics reading from empty stdin.

This took significant debugging to trace through the permission check logic in zellij_exports.rs. A note in the docs would save others the same effort.

Add guidance across three documentation pages explaining that plugins
loaded via file: or http(s): must call request_permission() in their
load() function, unlike built-in zellij: plugins which bypass permission
checks entirely. Without this call, privileged API commands are silently
denied, causing plugin panics.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant