Actions

An action is an entry a user reaches by right-clicking a file, a selection of files, or a folder. It’s a fixed, discoverable way to start something — as opposed to a tool, which the model chooses on its own mid-conversation.

Two kinds

• prompt (default) — renders a template and opens it as an agent turn in chat. The model reads the rendered prompt and responds like any other turn, optionally calling tools.
• tool — calls one of your contributes.tools[] entries directly. No agent turn, no model involved.

"actions": [
  { "id": "summarize-document", "title": "Summarize", "description": "Summarize the selected document",
    "scope": "single-file", "fileTypes": ["document"], "prompt": "./prompts/summarize.md", "toolScope": "read-only" },
  { "id": "convert-to-pdf", "title": "Convert to PDF", "description": "Convert the selected file to PDF",
    "scope": ["single-file", "multi-file"], "kind": "tool", "toolId": "convert_document" }
]

summarize-document opens a chat turn built from prompts/summarize.md; convert-to-pdf calls convert_document directly with no chat turn at all.

toolScope

A prompt action can restrict what tools the resulting turn has access to:

• "read-only" — the turn gets only tools that read the folder and its knowledge base. Nothing that writes, runs a command, reaches the network, or belongs to a plugin.
• "none" — no tools at all for that turn.

If your prompt says something like “read the file at … and summarize it,” give it toolScope: "read-only", not "none" — with no tools available the model has nothing to read with and narrates instead of actually reading the file.

toolScope is forbidden on kind: "tool" actions — they don’t run an agent turn, so there’s no tool list to restrict.

Multi-file tools

For a kind: "tool" action whose scope includes "multi-file", multiFileMode decides how the selection reaches your tool:

• "independent" (default) — one tool call per selected file.
• "batch" — exactly one call, with every selected path passed together as an array under the tool schema’s array-of-paths property. Use this when the tool’s point is to combine the files, not process each one alone.

Dialog inputs

An action can open a small dialog before it runs, collecting params[]:

• { id, label, type: "select" | "text" | "per-file-text", options?, placeholder?, default?, required? }
• generate — an in-form button that invokes a sibling kind: "tool" action and fills a per-file-text param from its result. Useful when one action can pre-compute a suggested value for another.
• hidden: true — keeps an action out of the context menu entirely while it stays invocable as another action’s generate.actionId. This is how a helper action stays out of the way of users while still doing work behind a generate button.

See the manifest reference for the full actions[] field table.

Next

• Hooks and events — react to what an action’s turn produces
• Permissions — what toolScope: "read-only" actually grants