bingshuo/grok-build-upstream-mirror
Watch
1
0
Fork
You've already forked grok-build-upstream-mirror
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Synced from monorepo

Browse source 
Synced from monorepo

Changes:
- Refresh tool search when the managed MCP catalog is re-fetched
- Prevent duplicate leader process spawn and startup hang from stale leaders
- Document marketplaces, plugins, and organization controls
- Stamp session ID on image generation direct-to-API requests
- Fix auto mode blocked documentation
- Auto mode considers recent user intent
- Expose deploy archive, taken-down, limit, and in-progress reasons on the chat API
- Fail-closed auth refresh contract for shell clients
- Emit a chat-supplied per-session turn index in turn hooks
- Show bash mode chrome in minimal mode
- Add metrics for true-noop and stationarity stops
- Include voice interim text on prompt submit
- Silently end turn on true-noop thrash
- Quiet copy toast when clipboard delivery is confirmed
- Fix session fork truncating at the wrong prompt in rewound sessions
- Make the idle "still running" watcher cue clickable to open the tasks pane
- Default web search model to grok-4.5
- Let plugin subagents inherit parent MCP servers
- Gate no-op end-turn reminder on system reminders
- Add gateway bridge lifecycle telemetry
- Allow editing finalized text while voice is open
- Relocate token carrier to turn-commit events and plumb per-turn origin context
- Raise workflow scratch quotas and make failed runs resumable
- Workflows overlay: auto-progress phases, live agent status, and drop budget meter

Source-Revision: 9b8d35b46d959c042ea9aa31cbbebbd1f0c5c527
This commit is contained in:
grokkybara[bot] 2026-07-24 16:59:42 +00:00
commit 6e38642082
103 changed files with 4964 additions and 1261 deletions
Download patch file Download diff file Expand all files Collapse all files

2
crates/codegen/xai-grok-pager/docs/user-guide/04-slash-commands.md
View file

@ -66,7 +66,7 @@ Copy the most recent response to the clipboard. Pass a number to copy the Nth-la
/copy 2 ~/exports/last-reply.md
```
Every copy is also written to a backup file — `~/.grok/last-copy.txt` by default, or `GROK_COPY_FILE` if set — and the toast tells you exactly where the text landed, so you can retrieve it even when the clipboard couldn't be reached or the copy went out as an OSC 52 escape this terminal couldn't confirm.
Every copy is also written to a backup file — `~/.grok/last-copy.txt` by default, or `GROK_COPY_FILE` if set. Confirmed copies toast briefly (e.g. `Copied!`). Unverified OSC 52 deliveries and clipboard-unreachable fallbacks name the backup path so you can recover the text.
### `/export`

4
crates/codegen/xai-grok-pager/docs/user-guide/05-configuration.md
View file

@ -27,8 +27,8 @@ Location: `~/.grok/config.toml`. If the file is missing, Grok uses its built-in
auto_update = true # check for updates on launch
[models]
default = "grok-build" # model used for new sessions
web_search = "grok-4.20-multi-agent" # model used by the web_search tool
default = "grok-4.5" # model used for new sessions
web_search = "grok-4.5" # model used by the web_search tool
# Defaults applied to every model; a per-model [model.<id>] value always wins.
# See "Custom Models" for the per-model overrides and full details.

14
crates/codegen/xai-grok-pager/docs/user-guide/07-mcp-servers.md
View file

@ -18,6 +18,8 @@ See the [MCP specification](https://modelcontextprotocol.io) for protocol detail
MCP servers are configured in `~/.grok/config.toml` under `[mcp_servers.<name>]` sections.
To distribute MCP servers to a team, or to restrict which servers users may run, see [Distribute across an organization](09-plugins.md#distribute-across-an-organization) in the Plugins guide.
### stdio Transport (Local Process)
Grok spawns a local process and communicates over stdin/stdout:
@ -310,6 +312,18 @@ See the [MCP Server Registry](https://github.com/modelcontextprotocol/servers) f
---
## Subagents and MCP
Subagents inherit the parent session’s connected MCP servers by default, including plugin-sourced agents. Use agent frontmatter `mcpInheritance` to restrict that set (`all`, `none`, `named`, or `except`). Details are in [Subagents — MCP inheritance](16-subagents.md#mcp-inheritance).
If a child lists `search_tool` / `use_tool` but returns an empty catalog, check that:
1. The parent session actually connected the server (see Extensions / `grok inspect`)
2. The agent’s `mcpInheritance` is not `none` or a filter that excludes the server
3. Plugin agents cannot declare their own `mcpServers` in frontmatter — they only see parent-connected servers
---
## Troubleshooting
### Server Not Starting

2
crates/codegen/xai-grok-pager/docs/user-guide/08-skills.md
View file

@ -140,6 +140,8 @@ Grok asks where to save the skill:
- **Project** (`<repo_root>/.grok/skills/<name>/`) -- available only in this repository and shareable with teammates through version control. Grok recommends this scope inside a git repository.
- **User** (`~/.grok/skills/<name>/`) -- available across all your projects.
To distribute a skill to a whole team or organization, package it in a plugin and publish it through a marketplace. See [Create your own marketplace](09-plugins.md#create-your-own-marketplace) and [Distribute across an organization](09-plugins.md#distribute-across-an-organization).
The new skill appears in the slash menu within a few seconds, because Grok reloads skills when files change on disk.
---

539
crates/codegen/xai-grok-pager/docs/user-guide/09-plugins.md
View file

@ -1,229 +1,33 @@
# Plugins
A plugin bundles skills, slash commands, agents, hooks, MCP server configurations, and LSP server configurations into one installable unit.
A plugin bundles skills, slash commands, agents, hooks, and MCP servers into one installable unit. You get plugins from a marketplace, install the ones you want, and Grok loads what they add. To build and share your own, see [Create your own marketplace](#create-your-own-marketplace).
---
## What a plugin contains
## How marketplaces work
A plugin is a directory that holds any combination of these components:
A marketplace is a catalog of plugins that someone has published and shared. Using one takes two steps, like adding an app store: adding the marketplace lets you browse its plugins, and you then choose which to install.
- **Skills** -- a `skills/` directory of SKILL.md files
- **Slash commands** -- a `commands/` directory of command files
- **Agents** -- an `agents/` directory of agent definitions
- **Hooks** -- a `hooks/hooks.json` file of lifecycle hooks. Plugin hooks also receive `GROK_PLUGIN_ROOT` and `GROK_PLUGIN_DATA` (see the [Hooks guide](10-hooks.md) for every environment variable passed to hooks).
- **MCP servers** -- a `.mcp.json` file of server configurations
- **LSP servers** -- a `.lsp.json` file of language server configurations
1. **Add the marketplace** so Grok can show what it offers. Nothing installs yet.
2. **Install the plugins you want**, one at a time.
If a plugin includes a `plugin.json` manifest, the manifest can override paths or add metadata; otherwise components load from the convention directories. The manifest is optional: without one, Grok discovers the components above from their standard directories.
For example, a `team-tools` plugin might include a deploy skill, a code-review agent, pre-commit hooks, and a Linear MCP server. Install them together in one step.
## Environment variables in plugin hooks
Plugin hooks receive two environment variables beyond the standard ones set for every hook:
| Variable | Description |
|----------------------|-------------|
| `GROK_PLUGIN_ROOT` | Absolute path to the plugin's installed directory. |
| `GROK_PLUGIN_DATA` | Absolute path to the plugin's writable data directory, for plugin state, caches, and logs. |
Grok sets these values and overrides any value you declare for the same key in the hook JSON's `env` map. (Grok also sets the `CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` aliases for compatibility.) See the [Hooks guide](10-hooks.md) for every environment variable passed to hooks.
Plugins stay off until you install and enable them, and a plugin's hooks and MCP servers stay inactive until you [trust](#trust-and-security) it.
---
## Plugin locations
## Add a marketplace
Grok discovers plugins from these locations, in priority order:
| Location | Scope | Trust |
|----------|-------|-------|
| `_meta.pluginDirs` (`session/new` / `session/load`) | Session -- loaded for that session only | Trusted automatically |
| `--plugin-dir` (CLI flag, `grok agent`) | Process -- loaded for that agent process only | Trusted automatically |
| `.grok/plugins/` | Project -- shared with the team through version control | Requires trust |
| `~/.grok/plugins/` | User -- personal plugins for every project | Trusted automatically |
| `[plugins].paths` (config) | Custom directories you add in `config.toml` | Depends on location |
Grok also reads the `.claude/plugins/` equivalents for compatibility. When two plugins share a name, the higher-priority location wins.
The Agent SDKs load per-session plugins through `GrokOptions.plugins`, which arrives as `_meta.pluginDirs` on `session/new` and `session/load`; because the caller controls the directory, these plugins are always trusted -- their hooks and MCP servers activate without a prompt, and they never persist beyond the session. The `--plugin-dir` flag is the process-wide equivalent for direct CLI use (repeatable: `grok agent --no-leader --plugin-dir A --plugin-dir B stdio`); it applies to dedicated agent processes only and is ignored in leader mode (the shared leader discovers its own plugins).
---
## Manage plugins in the TUI
### Open the modal
| Action | Opens |
|--------|-------|
| `Ctrl+L` (from any pane; **non–VS Code family**) | Plugins tab |
| `/plugins` (any terminal; **required on VS Code family**) | Plugins tab |
The modal has five tabs: **Hooks**, **Plugins**, **Marketplace**, **Skills**, and **MCP Servers**. Switch tabs with `Tab` (forward) or `Shift+Tab` (backward). The `/hooks`, `/marketplace`, `/skills`, and `/mcps` commands each open the modal on the matching tab.
### Plugins tab
Press `Enter` to expand a plugin row and show its details:
- **Name** and **version**
- **Scope** -- `cli`, `project`, `user`, `custom path`, or the marketplace source name
- **Skills** -- names or count
- **Agents** -- names or count
- **Hooks** -- count
- **MCP servers** -- count (or `blocked` when the plugin is not trusted)
- **Description** and **path**
Use these keys in the Plugins tab:
| Key | Action |
|-----|--------|
| `r` | Reload all plugins |
| `a` | Add a plugin from `owner/repo`, a URL, or a local path |
| `Space` | Enable or disable the selected plugin |
| `x` | Uninstall the selected plugin (asks for confirmation) |
| `f` | Filter by status (all, enabled, or disabled) |
| `Enter` | Expand or collapse plugin details |
| `/` | Search plugins by name |
Uninstall asks for confirmation: press lowercase `y` to confirm, or any other key (including `Esc`) to cancel.
### Marketplace tab
Browse and install plugins from your configured marketplace sources.
Use these keys in the Marketplace tab:
| Key | Action |
|-----|--------|
| `i` | Install the selected plugin |
| `d` | Uninstall the selected plugin (asks for confirmation) |
| `a` | Add a marketplace source |
| `x` | Remove the selected source and all its plugins (asks for confirmation) |
| `r` | Refresh marketplace sources |
| `u` | Update the selected marketplace plugin |
| `Enter` | Expand or collapse a source or plugin |
| `/` | Search plugins by name |
Component summaries on list rows and per-category component details in the
expanded view appear only for marketplaces that publish a `plugin-index.json`
catalog.
---
## CLI commands
Manage plugins without starting an interactive session.
### Plugin commands
A marketplace source is a GitHub repository, a git URL on any host, or a local folder. Add one from the command line:
```bash
grok plugin list [--json] [--available] # List installed plugins (--available requires --json)
grok plugin install <source> --trust # Git URL, GitHub shorthand (user/repo), or local path
grok plugin uninstall <name> [--confirm] [--keep-data] # Aliases: rm, remove
grok plugin update [<name>] # Omit the name to update all plugins
grok plugin enable <name>
grok plugin disable <name>
grok plugin details <name> # Show the plugin's component inventory
grok plugin validate [<path>] # Validate plugin.json (default: current directory)
grok plugin tag [<path>] [--push] [--force] [--dry-run] # Tag a release from the manifest version
grok plugin marketplace add my-org/team-plugins # GitHub shorthand (owner/repo)
grok plugin marketplace add https://gitlab.com/acme/plugins.git # any git host, include https:// and .git
grok plugin marketplace add ./my-marketplace # a local folder
```
Run `grok plugin install <source>` without `--trust` and Grok prints the source and warns that installing will activate the plugin's hooks, MCP servers, and skills, then stops without installing. Add `--trust` to install it.
List, refresh, and remove sources with `grok plugin marketplace list`, `grok plugin marketplace update [<name>]`, and `grok plugin marketplace remove <url>`.
The `<source>` argument accepts:
- `user/repo` -- GitHub shorthand
- `user/repo@v1.0` -- pinned to a ref
- `user/repo@<commit-sha>` -- pinned to an exact commit (verified after fetch)
- `user/repo#subdir` -- subdirectory within the repo
- `https://github.com/user/repo.git` -- full URL
- `git@github.com:user/repo.git` -- SSH
- `./local-dir` or `/absolute/path` -- local directory
### Requiring commit pins (`require_sha`)
Remote plugins are not cryptographically signed: an install that tracks a
branch or tag runs whatever that ref points at tomorrow. Operators can require
every remote install and update to pin a full commit sha (40- or 64-hex,
verified against the fetched checkout):
```toml
# config.toml
[marketplace]
require_sha = true
```
or `GROK_MARKETPLACE_REQUIRE_SHA=1`. Both are tighten-only: either one enables
the policy and neither can switch it back off. With the policy on, unpinned
remote installs, marketplace installs without a published `sha`, and updates of
branch-tracking installs are refused.
Scope: the policy covers everything fetched from a remote git URL at install or
update time. Plugins vendored inside a marketplace source itself are copied
from that source's synced checkout and are not covered — pin your marketplace
source's content by publishing `sha` entries in `plugin-index.json`.
### Marketplace commands
```bash
grok plugin marketplace list [--json]
grok plugin marketplace add <url> # Git URL, GitHub shorthand (user/repo), or local path
grok plugin marketplace remove <url> # Git URL or local path of a configured source
grok plugin marketplace update [<name>] # Omit the name to refresh all sources
```
### Example: set up a team marketplace
```bash
grok plugin marketplace add my-org/team-plugins
grok plugin marketplace list
grok plugin install my-org/team-plugins --trust
grok plugin list
grok plugin update
```
---
## Slash commands
In an interactive session, these commands open the modal on a specific tab. They take no arguments — manage plugins from the modal or with the `grok plugin` CLI.
| Command | Opens |
|---------|-------|
| `/plugins` | Plugins tab |
| `/hooks` | Hooks tab |
| `/marketplace` | Marketplace tab |
| `/skills` | Skills tab |
| `/mcps` | MCP Servers tab |
---
## Configuration
Configure plugin directories and per-plugin state in `~/.grok/config.toml`:
```toml
[plugins]
paths = ["~/my-plugins/custom-tools"] # Additional plugin directories
disabled = ["user/a1b2c3d4/noisy-plugin"] # Plugin IDs or names to skip
enabled = ["project/9f8e7d6c/team-tools"] # Plugin IDs or names to force on
```
List a plugin in `disabled` to discover it but skip loading its components. List a plugin in `enabled` to activate it — plugins are disabled by default unless a CLI override or an explicit config path enables them, so add them here to turn them on. Each entry is either a plain plugin name (as shown by `grok plugin list`) or a full plugin ID in the form `<scope>/<hash>/<name>`.
### Hide the plugins UI
To hide the hooks and plugins UI — the `/hooks` and `/plugins` commands and the scrollback annotations — set this in `~/.grok/pager.toml`:
```toml
disable_plugins = true
```
---
## Marketplace sources
Add git or local marketplace sources to discover and install plugins.
You can also declare sources in config so they are always present.
### In config.toml
@ -257,43 +61,326 @@ Place this file at `~/.grok/settings.json` or `~/.claude/settings.json`.
---
## Trust model
## Install and use a plugin
Enabling a plugin loads its skills, slash commands, and agents. Trust is separate and controls whether a plugin's code runs: even for an enabled plugin, its hooks, MCP servers, and LSP servers stay inactive until you trust it. This prevents an untrusted repository from running code on your machine.
Once a marketplace is added, install a plugin by name. You can also install straight from a repository or a local path:
Grok trusts plugins from `~/.grok/plugins/` automatically. Project plugins in `.grok/plugins/` require explicit trust. To trust a plugin, install it with `--trust`:
```bash
grok plugin install deploy-tools --trust
```
The source you install accepts several forms:
- `owner/repo` (GitHub shorthand), `owner/repo@v1.0` (a ref), `owner/repo@<commit-sha>` (an exact commit, verified after fetch), or `owner/repo#subdir`
- a full git URL (`https://github.com/user/repo.git`) or SSH (`git@github.com:user/repo.git`)
- a local path (`./local-dir` or `/absolute/path`)
Run `grok plugin install <source>` without `--trust` and Grok shows the source, warns that installing activates the plugin's hooks, MCP servers, and skills, then stops. Add `--trust` to go ahead. Only install plugins from sources you trust (see [Trust and security](#trust-and-security)).
A plugin's skills appear in the slash menu. When a skill name is ambiguous, Grok shows the qualified form prefixed by the plugin name, for example `/deploy-tools:release`. To pick up a newly installed plugin, press `r` in the Plugins tab or start a new session.
---
## Manage plugins
### From the command line
```bash
grok plugin list [--json] [--available] # installed plugins (--available requires --json)
grok plugin uninstall <name> [--confirm] [--keep-data] # aliases: rm, remove
grok plugin update [<name>] # omit the name to update every plugin
grok plugin enable <name>
grok plugin disable <name>
grok plugin details <name> # show the plugin's component inventory
```
### In the terminal UI
Open the plugins modal with `Ctrl+L` (outside the VS Code family) or `/plugins` (any terminal, and required on the VS Code family). It has five tabs, **Hooks**, **Plugins**, **Marketplace**, **Skills**, and **MCP Servers**; switch with `Tab` / `Shift+Tab`. The `/hooks`, `/marketplace`, `/skills`, and `/mcps` commands open the modal on the matching tab.
In the **Plugins** tab, press `Enter` to expand a plugin and see its name, version, scope (`cli`, `project`, `user`, `custom path`, or the marketplace source name), skills, agents, hooks, MCP servers (shown as `blocked` when the plugin is not trusted), description, and path. Then:
| Key | Action |
|-----|--------|
| `r` | Reload all plugins |
| `a` | Add a plugin from `owner/repo`, a URL, or a local path |
| `Space` | Enable or disable the selected plugin |
| `x` | Uninstall the selected plugin |
| `f` | Filter by status (all, enabled, or disabled) |
| `/` | Search by name |
In the **Marketplace** tab, browse and install from your sources:
| Key | Action |
|-----|--------|
| `i` | Install the selected plugin |
| `d` | Uninstall the selected plugin |
| `a` | Add a marketplace source |
| `x` | Remove the selected source and its plugins |
| `r` | Refresh sources |
| `u` | Update the selected plugin |
Component summaries in the Marketplace tab appear only for marketplaces that publish a [`plugin-index.json`](#add-a-catalog-optional) catalog. Destructive actions ask for confirmation: press lowercase `y` to confirm, any other key (including `Esc`) to cancel.
### Turn plugins on or off in config
Set these in `~/.grok/config.toml`:
```toml
[plugins]
paths = ["~/my-plugins/custom-tools"] # extra plugin directories
disabled = ["user/a1b2c3d4/noisy-plugin"] # names or IDs to skip
enabled = ["project/9f8e7d6c/team-tools"] # names or IDs to force on
```
Plugins are off by default, so list one in `enabled` to turn it on, or in `disabled` to discover it but skip loading it. Each entry is a plain plugin name (from `grok plugin list`) or a full ID (`<scope>/<hash>/<name>`).
To hide the plugins and hooks interface entirely, set `disable_plugins = true` in `~/.grok/pager.toml`.
---
## Trust and security
Plugins run with your privileges, so treat them like any software you install: only add marketplaces and install plugins from sources you trust.
Enabling a plugin loads its skills, commands, and agents. Trust is separate and controls whether a plugin's code runs: even when enabled, its hooks, MCP servers, and LSP servers stay inactive until you trust it. Grok trusts plugins in `~/.grok/plugins/` automatically; project plugins in `.grok/plugins/` require trust. Install with `--trust` to grant it:
```bash
grok plugin install <source> --trust
```
Trusted plugin `.mcp.json` servers attach to the session like other MCP config, and child agents inherit them. Plugin agents (`plugin-name:agent-name`) use the parent session's MCP servers by default, the same as user agents under `~/.grok/agents/`; restrict that with the `mcpInheritance` frontmatter (see [Subagents](16-subagents.md#mcp-inheritance)). For safety, plugin agent frontmatter cannot declare `mcpServers` or hooks, or set `permissionMode: bypassPermissions`.
---
## Inspect plugins
## Create your own marketplace
Run `grok inspect` to see every discovered plugin and what it provides:
A marketplace is a git repository (or a local folder) that lists a set of plugins. Adding one works like adding an app store: it lets people browse your plugins, and they choose which to install. Publishing your own is how a team or an organization shares its skills, commands, agents, hooks, and MCP servers from one place.
```bash
grok inspect # Show plugins with their skills, agents, hooks, and MCP servers
grok inspect --json # Emit machine-readable JSON
You need three things: a git repository, one folder per plugin, and a single index file that lists them.
### Set up the repository
1. **Create a git repository.** A private repository is fine; access uses each person's own git credentials.
2. **Add each plugin as a folder.** A plugin folder holds any of `skills/`, `commands/`, `agents/`, `hooks/hooks.json`, `.mcp.json`, and an optional `plugin.json` manifest (see [What a plugin contains](#what-a-plugin-contains)).
3. **List the plugins in `.grok-plugin/marketplace.json`.** This is the index Grok reads.
4. **Push the repository.**
A typical layout:
```
my-org-plugins/
.grok-plugin/
marketplace.json # the index Grok reads (required)
plugin-index.json # optional catalog for richer browsing
plugins/
gdrive/
plugin.json # optional manifest
skills/gdrive/SKILL.md
.mcp.json # MCP servers this plugin adds
```
Plugin-provided components appear in their sections (Skills, Agents, MCP Servers, and so on) with a `plugin: <name>` label, so you can see where each component originates.
Grok reads the index from `.grok-plugin/marketplace.json`. It also accepts `.grok-plugin/plugin.json` and the `.claude-plugin/` equivalents.
### Write the index
`marketplace.json` names the marketplace and lists each plugin:
```json
{
"name": "My Org Plugins",
"description": "Internal skills and tools",
"owner": { "name": "Platform Team", "email": "platform@example.com" },
"plugins": [
{
"name": "gdrive",
"description": "Search and edit Google Drive, Docs, Sheets, and Slides",
"category": "productivity",
"source": { "type": "local", "path": "./plugins/gdrive" }
}
]
}
```
Each plugin's `source` points at its files, in one of two ways:
- **In this repository**: `{ "type": "local", "path": "./plugins/gdrive" }`. The plain string `"./plugins/gdrive"` also works.
- **In a separate repository**: `{ "source": "url", "url": "https://github.com/my-org/gdrive.git", "sha": "<full commit sha>" }`. Pin a `sha` so installs are reproducible (required when you [require pinned versions](#require-pinned-versions)).
Optional per-plugin fields: `version`, `author`, `homepage`, `tags`, and `keywords`.
### Add a catalog (optional)
A `plugin-index.json` catalog lets the marketplace browser show each plugin's skills, commands, hooks, and agents before anyone installs it. It is for display only, installs work without it, and teams usually generate it in CI:
```json
{
"version": 1,
"plugins": {
"gdrive": {
"components": {
"skills": [{ "name": "gdrive", "description": "Google Drive access" }]
}
}
}
}
```
### Check and share it
Validate a plugin before publishing with `grok plugin validate [<path>]`, and tag a release from the manifest version with `grok plugin tag [<path>] [--push]`. Then point people at the repository. They add it once and install the plugins they want:
```bash
grok plugin marketplace add my-org/my-org-plugins # GitHub shorthand, a git URL, or a local path
grok plugin install gdrive --trust
```
To install it for everyone automatically instead of person by person, see [Distribute across an organization](#distribute-across-an-organization).
---
## General keyboard shortcuts
## Distribute across an organization
These keys work across every tab in the modal:
Admins control plugins, marketplaces, and MCP servers through two managed layers the deployment sends to each user:
- **`managed_config.toml`** holds the same settings as a user's `config.toml` and merges into it. Use it to hand everyone a marketplace and turn plugins on.
- **`managed-settings.json`** is a protected policy file for allowlists and defaults. Its values take precedence over user, project, and local config and cannot be overridden.
### Roll a marketplace out to everyone
Add the source, and turn on the plugins you want, in `managed_config.toml`:
```toml
[[marketplace.sources]]
name = "My Org Plugins"
git = "https://github.com/my-org/my-org-plugins.git"
# Plugins stay off until enabled. List plugin names (from `grok plugin list`)
# or full IDs (`<scope>/<hash>/<name>`).
[plugins]
enabled = ["gdrive"]
```
For a hands-off install with no per-person step, also place the plugin's files where Grok discovers and trusts them automatically: `~/.grok/plugins/`, or a directory your device-management tool manages that you point to with `[plugins].paths`. Then enable them with `[plugins].enabled`.
A managed workspace can also sync skills to users directly, without a plugin. Synced skills appear with the `server` scope and are administered by the workspace; a user's own skill of the same name shadows the synced one. See [Skills](08-skills.md).
### Restrict which marketplaces can be added
List the only sources people may add in `managed-settings.json`. Any other marketplace is refused:
```json
{
"strictKnownMarketplaces": [
{ "source": "git", "url": "git@github.enterprise.example:ACME/my-org-plugins.git" }
]
}
```
### Restrict which MCP servers can run
Also in `managed-settings.json`. Each entry allows an HTTP address (with `*` wildcards) or a local command; anything unlisted is denied:
```json
{
"allowedMcpServers": [
{ "serverUrl": "https://*.example.com/*" },
{ "command": "npx" }
]
}
```
The deployment can also send MCP servers to users directly. The allowlist bounds what any configuration, managed or personal, is allowed to run.
### Require pinned versions
Refuse any remote plugin install or update that is not pinned to a full commit sha:
```toml
[marketplace]
require_sha = true
```
You can also set `GROK_MARKETPLACE_REQUIRE_SHA=1`. Both only tighten the policy; neither turns it back off. Publish `sha` values in your marketplace's `plugin-index.json` so installs from it satisfy the rule. Plugins vendored directly inside a marketplace repository are copied from that repository's checkout, so pin them the same way, with `sha` values in `plugin-index.json`.
### Turn off the plugins UI
To hide the plugins and hooks interface, set this in `pager.toml`:
```toml
disable_plugins = true
```
### What this does not cover
Marketplaces distribute Grok content: skills, commands, agents, hooks, and MCP server configurations. They do not install a program onto a machine. A skill or MCP server that runs a helper binary (for example a custom sign-in tool) still needs that binary delivered separately, bundled with your deployment or pushed through your device-management tool.
---
## Troubleshooting
**A plugin you installed isn't showing up.** Plugins are off until enabled. Check `grok plugin list`, then add the plugin's name or ID to `[plugins].enabled`, or press `Space` on it in the Plugins tab. Reload with `r` in the Plugins tab or start a new session.
**A plugin's hooks or MCP servers don't run.** They stay inactive until the plugin is trusted. Reinstall with `--trust`, or place the plugin under `~/.grok/plugins/` (auto-trusted). See [Trust and security](#trust-and-security).
**A skill or MCP server from a marketplace is missing.** Refresh the source with `grok plugin marketplace update`, confirm the plugin is installed and enabled, and, if your organization restricts sources, check that the marketplace is still allowed (see [Distribute across an organization](#distribute-across-an-organization)). Some MCP servers require a sign-in and will not appear until you authenticate.
**An install is refused as unpinned.** Your deployment requires pinned commits. Install an exact commit (`owner/repo@<sha>`), or use a marketplace whose `plugin-index.json` publishes `sha` values. See [Require pinned versions](#require-pinned-versions).
**See exactly what loaded.** Run `grok inspect` (add `--json` for machine-readable output) to list every discovered plugin and the skills, agents, hooks, and MCP servers it provides, each labeled with its `plugin: <name>` source.
---
## Reference
### What a plugin contains
A plugin is a directory with any combination of:
- **Skills**: a `skills/` directory of SKILL.md files
- **Slash commands**: a `commands/` directory
- **Agents**: an `agents/` directory
- **Hooks**: a `hooks/hooks.json` file
- **MCP servers**: a `.mcp.json` file
- **LSP servers**: a `.lsp.json` file
An optional `plugin.json` manifest can override paths or add metadata; without one, Grok discovers components from these standard directories. For example, a `team-tools` plugin might bundle a deploy skill, a code-review agent, pre-commit hooks, and a Linear MCP server, installed together in one step.
A skill or command may ship a **helper script** next to its SKILL.md (for example a Python file it calls). Put the script in the plugin and have the skill run it by relative path; it is copied to the machine with the plugin. The script's runtime and any packages it imports must already be present, plugins deliver files, not runtimes or native binaries (see [What this does not cover](#what-this-does-not-cover)).
### Where Grok looks for plugins
Grok discovers plugins from these locations, in priority order. The `.claude/plugins/` equivalents also work, and when two plugins share a name the higher-priority one wins:
| Location | Scope | Trust |
|----------|-------|-------|
| `_meta.pluginDirs` (`session/new` / `session/load`) | Session, that session only | Trusted automatically |
| `--plugin-dir` (the `grok agent … stdio` flag) | Process, that agent process only | Trusted automatically |
| `.grok/plugins/` | Project, shared through version control | Requires trust |
| `~/.grok/plugins/` | User, every project | Trusted automatically |
| `[plugins].paths` (config) | Custom directories you add | Depends on location |
The `_meta.pluginDirs` field on the `session/new` and `session/load` requests loads plugins for a single session; because the caller supplies the directory, those plugins are trusted automatically and do not persist after the session. `--plugin-dir` is the process-wide equivalent for a dedicated `grok agent … stdio` process, repeatable (`grok agent --no-leader --plugin-dir A --plugin-dir B stdio`), and ignored in leader mode, where the shared leader discovers its own plugins.
### Environment variables in plugin hooks
Plugin hooks receive two variables beyond the standard hook environment:
| Variable | Description |
|----------|-------------|
| `GROK_PLUGIN_ROOT` | Absolute path to the plugin's installed directory. |
| `GROK_PLUGIN_DATA` | Absolute path to the plugin's writable data directory, for state, caches, and logs. |
Grok sets these and overrides any same-named value in the hook's `env` map (the `CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` aliases are set too). See the [Hooks guide](10-hooks.md) for every variable passed to hooks.
### Keyboard shortcuts
These keys work across every tab in the plugins modal:
| Key | Action |
|-----|--------|
| `Tab` | Next tab |
| `Shift+Tab` | Previous tab |
| `j` / down-arrow | Move selection down |
| `k` / up-arrow | Move selection up |
| `Tab` / `Shift+Tab` | Next / previous tab |
| `j` / `k` or arrow keys | Move the selection |
| `Enter` | Expand or collapse the selected item |
| `/` | Search the current tab by name |
| `Esc` | Clear the search, or close the modal |
Destructive remove and uninstall actions in the modal ask for confirmation. Press lowercase `y` to confirm, or any other key (including `Esc`) to cancel.

8
crates/codegen/xai-grok-pager/docs/user-guide/11-custom-models.md
View file

@ -6,7 +6,7 @@ Grok connects to custom model endpoints for alternative providers, self-hosted m
## Default Models
By default, Grok uses models hosted by SpaceXAI, and new sessions start with `grok-build`. Default models require no configuration. Authenticate with `grok login` or an API key, then start a session.
By default, Grok uses models hosted by SpaceXAI, and new sessions start with `grok-4.5`. Default models require no configuration. Authenticate with `grok login` or an API key, then start a session.
List all available models:
@ -48,7 +48,7 @@ Set a persistent default in `~/.grok/config.toml`:
```toml
[models]
default = "grok-build"
default = "grok-4.5"
```
---
@ -315,13 +315,13 @@ The `web_search` tool uses a separate model. Configure it with:
```toml
[models]
web_search = "grok-4.20-multi-agent"
web_search = "grok-4.5"
```
Or via environment variable:
```bash
export GROK_WEB_SEARCH_MODEL="grok-4.20-multi-agent"
export GROK_WEB_SEARCH_MODEL="grok-4.5"
```
If you point web search at a custom model, you also need a `[model.*]` entry so Grok can reach it. Server-side ("backend") web search runs only when the model sets `supports_backend_search = true` (and the build enables backend search); it does not depend on `api_backend`:

16
crates/codegen/xai-grok-pager/docs/user-guide/14-headless-mode.md
View file

@ -34,7 +34,7 @@ Grok processes the prompt, runs any necessary tools, and prints the result to st
| `--disallowed-tools <TOOLS>` | Denylist of built-in tools to remove (comma-separated). Supports `Agent` entries. Headless only. |
| `--max-turns <N>` | Maximum number of agentic turns before stopping. Headless only. |
| `--reasoning-effort` / `--effort <LEVEL>` | Reasoning effort for reasoning models. Canonical levels: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (each a distinct tier; a model only accepts the levels its menu advertises). Also accepts per-model menu option ids (e.g. `deep` → mapped wire value), same as `/effort`. Works in TUI and headless. |
| `--permission-mode <MODE>` | Permission mode. `bypassPermissions` enables always-approve via this flag (see [22-permissions-and-safety.md](22-permissions-and-safety.md)); for deny-by-default use `defaultMode` in `.claude/settings.json`. |
| `--permission-mode <MODE>` | Permission mode. `bypassPermissions` enables always-approve (see [Permissions and safety](22-permissions-and-safety.md#permission-modes)); for deny-by-default use `defaultMode` in `.claude/settings.json`. |
| `--allow <RULE>` | Permission allow rule with glob patterns (repeatable). Works in TUI and headless. |
| `--deny <RULE>` | Permission deny rule with glob patterns (repeatable). Works in TUI and headless. |
| `--prompt-json <JSON>` | Prompt as JSON content blocks |
@ -431,20 +431,16 @@ echo "No issues found"
---
## Fully Automated Runs with --yolo
## Always-approve for automation
The `--yolo` flag enables always-approve mode (the same mode as `--permission-mode bypassPermissions` and `--always-approve`), auto-approving tool executions (file writes, command execution, etc.) without prompting for confirmation. Explicit `deny` rules and `PreToolUse` hooks still apply, and administrators can disable the mode via `requirements.toml` (see [22-permissions-and-safety.md](22-permissions-and-safety.md)). This is required for unattended automation:
`--always-approve` (alias `--yolo`, same as `--permission-mode bypassPermissions`) runs tool calls without interactive permission prompts. Deny rules, hooks, and admin locks still apply (see [Permissions and safety](22-permissions-and-safety.md#permission-modes)).
```bash
# Format all files without asking
grok -p "Format all files" --yolo
# Run tests and fix failures
grok -p "Run the tests and fix any failures" --cwd ~/projects/my-app --yolo
grok -p "Format all files" --always-approve
grok -p "Run the tests and fix any failures" --cwd ~/projects/my-app --always-approve
```
**Use `--yolo` with care.** It grants the agent full autonomy to modify files and run commands. Only use it in trusted environments or with well-scoped prompts.
For agent servers and SDKs, see [Agent mode](15-agent-mode.md#automation-and-sdks).
---
## Environment Variables for Headless

113
crates/codegen/xai-grok-pager/docs/user-guide/15-agent-mode.md
View file

@ -1,70 +1,94 @@
# Agent Mode (ACP) and IDE Integration
# Agent mode (ACP) and IDE integration
Agent mode runs Grok as an ACP (Agent Client Protocol) server for integration with IDEs, editors, and custom tooling. Unlike single-prompt mode (`grok -p`, which prints one response and exits), agent mode keeps a persistent process running and communicates through structured JSON-RPC messages.
Agent mode runs Grok as a long-lived server that clients talk to over [ACP](https://agentclientprotocol.com) (JSON-RPC). Use it from IDEs, SDKs, eval harnesses, and custom apps. For a one-shot prompt that prints and exits, use `grok -p` instead ([headless mode](14-headless-mode.md)).
---
## Automation and SDKs
For scripts, CI, evals, and agent servers, start with always-approve so tools run without interactive permission prompts. Deny rules and hooks still apply.
```bash
# stdio (local process / many SDKs)
grok agent --always-approve stdio
# WebSocket server
grok agent --always-approve serve --bind 127.0.0.1:2419 --secret <token>
```
You can also set always-approve per session on `session/new`:
```json
{
"cwd": "/path/to/project",
"mcpServers": [],
"_meta": { "yoloMode": true }
}
```
Interactive TUI users typically leave the default ask mode (or use auto). See [Permissions and safety](22-permissions-and-safety.md).
---
## What is ACP?
The [Agent Client Protocol (ACP)](https://agentclientprotocol.com) is a standard for AI agent communication. It defines how clients (IDEs, editors, custom apps) interact with AI agents through a structured JSON-RPC protocol. ACP provides:
The [Agent Client Protocol (ACP)](https://agentclientprotocol.com) defines how clients talk to coding agents over JSON-RPC. With Grok it covers:
- **Session management** -- create, load, and resume conversations
- **Prompt submission** -- send user messages and receive streamed responses
- **Tool visibility** -- see what tools the agent is using in real time
- **Thought streams** -- observe the agent's reasoning process
- **Permission handling** -- approve or deny tool executions interactively
- Sessions (create, load, resume)
- Prompts and streamed replies
- Tool call updates
- Reasoning / thought streams
- Permission prompts when the session is not always-approve
---
## stdio transport
stdio is the primary integration mode. The agent exchanges JSON-RPC messages over stdin and stdout:
stdio is the common local integration path. The agent speaks JSON-RPC on stdin and stdout:
```bash
grok agent stdio
grok agent --always-approve stdio
```
Clients that use this mode include:
- IDE extensions (for example, Zed, Neovim, and Emacs)
- Custom automation tools
- ACP client libraries
Typical clients: IDE extensions (Zed, Neovim, Emacs), custom tools, and ACP SDKs.
### Options
These options belong to the `grok agent` command and apply to every mode. Pass them before the mode name, for example `grok agent --model grok-build stdio`. The `stdio` subcommand itself takes no options.
Agent options apply to every transport (`stdio`, `serve`, `headless`, `leader`). They go after `agent` and before the mode name. Mode-specific flags go after the mode (for example `serve --bind`).
| Flag | Description |
| -------------------------- | ---------------------------------------------------------------- |
| `-m, --model <MODEL>` | Set the model ID (for example, `grok-build`). |
| `--always-approve` | Auto-approve every tool execution. (Alias: `--yolo`.) |
| `--reauth` | Run authentication before starting the agent. |
| `--agent-profile <PATH>` | Load an agent profile from a file. |
```bash
grok agent --always-approve --model grok-build stdio
grok agent --always-approve serve --bind 127.0.0.1:2419 --secret <token>
```
| Flag | Description |
| ---- | ----------- |
| `-m, --model <MODEL>` | Model ID (for example `grok-build`). |
| `--always-approve` | Run without interactive tool-permission prompts. Alias: `--yolo`. |
| `--reauth` | Authenticate before the agent starts. |
| `--agent-profile <PATH>` | Load an agent profile from a file. |
| `--leader` / `--no-leader` | Connect to a shared leader process, or force a local agent. |
---
## Server mode
Run the agent as a WebSocket server for remote clients:
```bash
grok agent serve --bind 127.0.0.1:2419 --secret <token>
grok agent --always-approve serve --bind 127.0.0.1:2419 --secret <token>
```
Clients connect over WebSocket and authenticate with the secret token. If you omit `--secret`, the agent generates a token and prints it at startup; you can also supply one through the `GROK_AGENT_SECRET` environment variable. The agent persists across reconnections, so a client can disconnect and later resume in-flight work.
Clients connect over WebSocket and authenticate with the secret token. If you omit `--secret`, the agent prints a generated token at startup, or set `GROK_AGENT_SECRET`. The process keeps state across client reconnects. Permissions match other entry points; see [Permissions and safety](22-permissions-and-safety.md).
---
## WebSocket relay
To reach the agent over the internet instead of the local network, run a WebSocket relay server and have the agent connect to it:
To reach the agent over the internet, connect the agent to a relay and point browsers at the same relay:
```bash
grok agent headless --grok-ws-url wss://your-relay.example.com/ws
grok agent --always-approve headless --grok-ws-url wss://your-relay.example.com/ws
```
The agent connects out to your relay, and your web clients connect to the same relay. This is useful for building web UIs where browsers cannot spawn local processes.
---
## ACP protocol basics
@ -75,7 +99,7 @@ Communication follows the JSON-RPC 2.0 format. A typical session lifecycle:
2. **Create session** -- client sends `session/new` with working directory
3. **Send prompts** -- client sends `session/prompt` with user messages
4. **Receive updates** -- agent sends `session/update` notifications with streamed content
5. **Handle permissions** -- agent may request tool execution approval
5. **Handle permissions** -- agent may request tool execution approval (or allow or deny based on permission mode)
### Architecture
@ -149,13 +173,23 @@ The agent sends push notifications to clients for real-time updates:
## Session `_meta` options
The `session/new` request accepts these optional `_meta` fields:
Optional fields on `session/new`:
| Field | Description |
| ---------------------- | ---------------------------------------------- |
| `rules` | Extra rules appended to the system prompt. |
| `systemPromptOverride` | A replacement system prompt. |
| `agentProfile` | An agent profile, as a name or a JSON object. |
| Field | Description |
| ----- | ----------- |
| `rules` | Extra rules appended to the system prompt. |
| `systemPromptOverride` | Replacement system prompt. |
| `agentProfile` | Agent profile name or JSON object. |
| `yoloMode` | When `true`, always-approve for this session. |
| `autoMode` | When `true`, auto permission mode for this session. Superseded when always-approve is already on. |
```json
{
"cwd": "/path/to/project",
"mcpServers": [],
"_meta": { "yoloMode": true }
}
```
---
@ -199,10 +233,9 @@ class GrokACPChat {
constructor(private cwd = ".") {}
async init() {
this.proc = spawn("grok", ["agent", "stdio"]);
this.proc = spawn("grok", ["agent", "--always-approve", "stdio"]);
this.rl = readline.createInterface({ input: this.proc.stdout! });
// Initialize
await this.request("initialize", {
protocolVersion: 1,
clientCapabilities: {
@ -211,10 +244,10 @@ class GrokACPChat {
},
});
// Create session
const { sessionId } = await this.request("session/new", {
cwd: this.cwd,
mcpServers: [],
_meta: { yoloMode: true },
});
this.sessionId = sessionId;
return this;

34
crates/codegen/xai-grok-pager/docs/user-guide/16-subagents.md
View file

@ -183,6 +183,40 @@ The `resume_from` parameter lets a new subagent continue where a completed subag
The new subagent inherits the source's transcript, tool state, and model; its system prompt and tools are re-rendered from the current agent definition. The source must be completed (not running), belong to the current session, and use the same agent type.
### MCP inheritance
Subagents inherit the parent session’s **already-connected** MCP servers by default. That includes local stdio/HTTP servers and plugin-sourced agents (for example `my-plugin:reviewer`). The child discovers and calls those tools with `search_tool` / `use_tool` the same way the parent does.
Control inheritance with agent frontmatter `mcpInheritance`:
| Value | Effect |
| ----- | ------ |
| `all` (default if omitted) | Inherit every parent-connected MCP server |
| `none` | Inherit no parent MCP servers |
| `named: [server, …]` | Inherit only the listed server names |
| `except: [server, …]` | Inherit all parent servers except the listed names |
Example:
```yaml
---
name: research-only
description: Read MCP tools but not internal connectors
tools: search_tool, use_tool, Read
mcpInheritance:
except:
- internal-tools
---
```
**Plugin agents** inherit parent MCP the same way. For security they still cannot:
- Declare their own `mcpServers` in agent frontmatter (ignored with a warning)
- Declare hooks in agent frontmatter
- Set `permissionMode: bypassPermissions`
Plugin-bundled MCP servers (plugin `.mcp.json`) still attach to the **parent/session** after the plugin is trusted — they are not a child-only frontmatter declaration. See [Plugins](09-plugins.md) and [MCP Servers](07-mcp-servers.md).
---
## Isolation: Worktree Mode

13
crates/codegen/xai-grok-pager/docs/user-guide/21-terminal-support.md
View file

@ -124,15 +124,16 @@ terminal-native `Shift+Insert`, or hold `Shift` while middle-clicking when the
terminal uses that gesture to bypass mouse reporting.
When Grok cannot identify the outer terminal over SSH, it predicts that OSC 52
will be sent but marks the route as not verified. The copy message shows the
actual result and backup file. Run `/doctor` for other copy options.
will be sent but marks the route as not verified. The copy toast then names the
backup file so you can retrieve the text. Run `/doctor` for other copy options.
#### Apple Terminal over SSH
Apple Terminal does not support OSC 52, so a remote copy cannot directly reach
the local clipboard. Grok also saves each copy to the backup file named in the
copy message (`~/.grok/last-copy.txt` by default; override with
`GROK_COPY_FILE`). You can also use `/copy <file>` or `/minimal`.
Apple Terminal does not support OSC 52, so a remote copy cannot reach the local
clipboard. Each copy is still saved to a backup file (`~/.grok/last-copy.txt` by
default; override with `GROK_COPY_FILE`); the toast names that path when delivery
is unverified or the clipboard is unreachable. You can also use `/copy <file>` or
`/minimal`.
For direct clipboard forwarding, run the SSH command from the local computer
through `grok wrap`, for example `grok wrap ssh user@host`. The same command can

173
crates/codegen/xai-grok-pager/docs/user-guide/22-permissions-and-safety.md
View file

@ -1,12 +1,122 @@
# Permissions and Safety Controls
# Permissions and safety
Grok can read files, search code, edit files, and run shell commands. The permission system controls what the agent is allowed to do. You can combine several independent layers: permission rules, permission modes, hooks, and the OS-level sandbox.
Control what Grok can access and do: permission modes, allow/ask/deny rules, hooks, and the optional OS-level sandbox.
This guide explains how a tool call is authorized, how to configure permission rules from the CLI, native configuration, or Claude settings, and how to use `PreToolUse` hooks for allow lists that apply in every mode.
- **Modes** set how often Grok asks for approval (always-approve, auto, ask, and related).
- **Rules** set which tools are allowed, asked about, or blocked within that baseline.
---
## How a Tool Call Is Authorized
## Permission modes
When Grok edits a file, runs a command, or calls an external tool, it may pause for approval. Permission modes control how often that happens.
Modes set a baseline. Allow, ask, and deny [rules](#configuring-permissions) still apply on top of any mode.
### Starting points
| Situation | Mode |
| --------- | ---- |
| Interactive TUI | Default (ask), or auto for fewer prompts with background checks |
| Scripts, SDKs, CI, agent servers | Always-approve; add [deny rules](#configuring-permissions) or hooks for hard limits |
```bash
grok -p "Run the tests" --always-approve
grok agent --always-approve stdio
grok agent --always-approve serve --bind 127.0.0.1:2419 --secret <token>
```
ACP clients can set `"_meta": { "yoloMode": true }` on `session/new`. See [Agent mode](15-agent-mode.md#automation-and-sdks).
### Available modes
| Mode | What runs without asking | Best for |
| ---- | ------------------------ | -------- |
| `default` (**ask**) | Read-only tools and built-in read-only shell commands | Interactive day-to-day use |
| `acceptEdits` | File edits without a prompt | Local coding while you review diffs later |
| `plan` | Accepted for compatibility; use [plan mode](19-plan-mode.md) for gated planning | Claude-compatible settings |
| `auto` | Work the safety check allows; other calls are blocked or escalated | Interactive sessions that want fewer prompts |
| `dontAsk` | Only pre-approved tools and built-in read-only handling | Strict CI allowlists |
| `bypassPermissions` (**always-approve**) | Tool calls in general (`deny` rules, hooks, and some shell `ask` rules still apply) | Trusted automation and agent servers |
**Always-approve** is the product name; config and Claude-compatible settings may use `bypassPermissions` for the same mode. Always-approve and auto are mutually exclusive (always-approve takes precedence when both are requested).
### How to set the mode
**Interactive TUI:** `Shift+Tab` / `Ctrl+O`, `/always-approve` or `/auto`, or `/settings` ([shortcuts](03-keyboard-shortcuts.md), [commands](04-slash-commands.md)).
**CLI:**
```bash
grok --always-approve -p "Run the test suite"
grok --permission-mode auto
grok agent --always-approve serve --bind 127.0.0.1:2419 --secret <token>
```
**Config:**
```toml
[ui]
permission_mode = "always-approve" # or "auto", "ask", …
```
Claude-compatible `defaultMode` in `.claude/settings.json` is also supported (see [Claude-compatible settings](#3-claude-code-compatibility-claudesettingsjson)). CLI overrides config for that process.
### Always-approve
Skips ordinary permission prompts so tools run without waiting for a click. `deny` rules, hooks, and some shell `ask` rules still apply. Admins can lock the mode off (below).
| Mechanism | Example |
| --------- | ------- |
| CLI | `--always-approve` (alias `--yolo`), or `--permission-mode bypassPermissions` |
| Config | `[ui] permission_mode = "always-approve"` |
| Interactive | `/always-approve`, `Ctrl+O` |
| ACP | `_meta.yoloMode: true` on `session/new` |
#### Always-approve with hard limits
Keep always-approve for automation, and add deny rules for paths or commands you never want run:
```toml
# project .grok/config.toml
[ui]
permission_mode = "always-approve"
[permission]
deny = [
"Bash(rm -rf *)",
"MCPTool(sales__delete_*)",
]
```
```bash
grok -p "Deploy the service" --always-approve --deny 'Bash(rm -rf *)'
```
Deny always wins over allow and over always-approve’s normal pass-through. See [Configuring permissions](#configuring-permissions).
### Auto mode
Reduces interactive prompts by checking many tool calls before they run. Routine local work often proceeds; other calls may be blocked or escalated. In non-interactive sessions, a blocked call fails and is reported to the model (for example `Auto mode blocked this action …`). Behavior is the same for `grok -p`, `agent stdio`, and `agent serve`.
For automation that must run tools without interactive approval, use always-approve (and deny rules if you need hard blocks) rather than auto alone.
### Disable always-approve (administrators)
Organizations can prevent always-approve from being enabled via CLI, TUI, or `/always-approve`. Set this in `requirements.toml` (user-level under `~/.grok/`, or system-wide under `/etc/grok/` for enforcement users cannot remove):
```toml
[ui]
disable_bypass_permissions_mode = true
```
Do not use `permission_mode` for this lock; that key is a switchable default. The legacy `[ui] yolo = false` key in `requirements.toml` also disables always-approve for compatibility.
Grok can still load Claude-style permission **rules** from managed settings; always-approve is locked with `requirements.toml` as shown above.
---
## How a tool call is authorized
When the model requests a tool, the following checks happen in order:
@ -23,7 +133,7 @@ When the model requests a tool, the following checks happen in order:
5. **Prompt policy** (set by the [permission mode](#permission-modes)): prompt you, auto-approve, or auto-deny the call.
Always-approve mode (`bypassPermissions`) short-circuits this pipeline after step 2: `deny` rules, hooks, and `ask` rules that match a shell command's segments still apply, but remembered grants (including remembered "never allow" entries) are not consulted, and `ask` rules on non-shell tools do not prompt.
[Always-approve](#always-approve) short-circuits this pipeline after step 2: `deny` rules, hooks, and `ask` rules that match a shell command's segments still apply, but remembered grants (including remembered "never allow" entries) are not consulted, and `ask` rules on non-shell tools do not prompt.
---
@ -58,47 +168,12 @@ After splitting chained commands (on `&&`, `||`, `;`, and pipes), the following
**Kubernetes (read-only):**
- `kubectl get`, `kubectl logs`, `kubectl describe`
> **Note:** `tee` is not on this list because it can write its input to arbitrary files. `cargo check` is not on this list because it compiles and runs `build.rs`, proc-macros, and any `build.rustc-wrapper` from the repo (in Ask mode it therefore prompts; Auto mode may still heuristic-allow `cargo` as a project code runner). `sort --compress-program=…` (including unique long-option abbreviations), `git -c` / `--config-env` overrides, and a git command whose local/worktree config installs an executable hook (`core.fsmonitor`, a `diff.*.command`/`textconv`/`external` driver, or a shell `alias.<safe-subcommand> = !…`) raise a request-level floor and prompt rather than auto-approve, unless the user granted that exact full script or YOLO is on.
> **Note:** `tee` is not on this list because it can write its input to arbitrary files. `cargo check` is not on this list because it compiles and runs `build.rs`, proc-macros, and any `build.rustc-wrapper` from the repo (in Ask mode it therefore prompts; Auto mode may still heuristic-allow `cargo` as a project code runner). `sort --compress-program=…` (including unique long-option abbreviations), `git -c` / `--config-env` overrides, and a git command whose local/worktree config installs an executable hook (`core.fsmonitor`, a `diff.*.command`/`textconv`/`external` driver, or a shell `alias.<safe-subcommand> = !…`) raise a request-level floor and prompt rather than auto-approve, unless the user granted that exact full script or always-approve is enabled.
These checks apply per segment. In a command like `ls && rm -rf /`, the `ls` segment is recognized as read-only, but the `rm` segment is not on the list. In `default` mode the `rm` segment prompts; under `dontAsk` it is denied.
---
## Permission Modes
The prompt policy is named by one of these modes:
| Mode | Behavior | Typical Use |
|---------------------|--------------------------------------------------------------------------|---------------------------------|
| `default` | Prompt for anything not pre-approved | Daily interactive use |
| `dontAsk` | Deny anything without an explicit allow rule or built-in auto-approval | Headless, CI, high-security |
| `bypassPermissions` | Auto-approve tool calls (`deny` rules, hooks, and shell `ask` rules still apply) | Trusted environments |
| `acceptEdits` | Auto-approve file edits (`search_replace`, `write`, etc.) | "Accept edits" workflows |
| `plan` | Accepted for compatibility; plan sessions are a separate feature (see [19-plan-mode.md](19-plan-mode.md)) | Structured planning sessions |
### Setting the Mode
The mode is set by `defaultMode` in `.claude/settings.json` (see [Claude Code Compatibility](#3-claude-code-compatibility-claudesettingsjson)). `dontAsk`, `acceptEdits`, and `bypassPermissions` change the prompt policy from there; `default` and `plan` keep standard prompting.
The `--permission-mode` CLI flag applies `bypassPermissions` (always-approve) and `default`; an explicit flag value always wins over a mode set in configuration. Passing `dontAsk`, `acceptEdits`, or `plan` to the flag is accepted but does not enable that policy; set those through `defaultMode` instead.
In headless runs (`-p`), a tool call that would prompt is cancelled and reported to the model instead of waiting for input. For deny-by-default in automation, set `defaultMode: "dontAsk"`.
### Disabling Always-Approve Mode
Administrators can turn always-approve (`bypassPermissions` / `--always-approve`) off so it cannot be enabled from the CLI, the TUI toggle, or the `/always-approve` command. Set the dedicated key in `requirements.toml`:
```toml
[ui]
disable_bypass_permissions_mode = true # default: false. true = locked off.
```
Do not use `permission_mode` for this; it is a user-switchable default, not a lock. The legacy `[ui] yolo = false` key in `requirements.toml` also disables the mode, for backward compatibility; in `config.toml` the same key remains a togglable preference.
The user-level `~/.grok/requirements.toml` is under the user's control, so a developer can remove the lock by editing that file. For enforcement that users cannot override, deploy the setting in the root-owned system file `/etc/grok/requirements.toml`.
> **Note:** Grok honors the permission rules in Claude Code's `managed-settings.json`, but not its `disableBypassPermissionsMode` lock. To disable always-approve in Grok, use `requirements.toml` as shown above.
---
## Configuring Permissions
@ -220,7 +295,7 @@ Example:
}
```
Supported `defaultMode` values are `default`, `acceptEdits`, `bypassPermissions`, `dontAsk`, and `plan`. Grok reads `defaultMode` from its canonical location under `permissions`; a top-level `defaultMode` is also accepted when the nested key is absent.
Supported `defaultMode` values include `default`, `auto`, `acceptEdits`, `bypassPermissions`, `dontAsk`, and `plan`. Grok reads `defaultMode` from its canonical location under `permissions`; a top-level `defaultMode` is also accepted when the nested key is absent.
`permissions.allow`, `permissions.deny`, and `permissions.ask` entries are translated into native rules and then matched with the semantics in the [Rule Matching Reference](#rule-matching-reference). Translation notes:
@ -451,7 +526,7 @@ Recommended combination for untrusted code:
## Managing Permissions in the TUI
- Permission decisions appear in the transcript.
- The `/always-approve` command toggles always-approve mode; other modes are set through `defaultMode` (see [Setting the Mode](#setting-the-mode)).
- The `/always-approve` command toggles always-approve mode; other modes are set through `defaultMode` (see [How to set the mode](#how-to-set-the-mode)).
- With `[ui] remember_tool_approvals = true`, permission prompts include per-command "Always allow" options that persist for the current project only. See [Interactive Approvals](#interactive-approvals-and-where-they-persist).
- To manage hooks and plugins, run `/hooks` or `/plugins` (on most terminals, **Ctrl+L** also opens the Extensions modal; on VS Code, Cursor, Windsurf, and Zed, `Ctrl+L` is mid-turn interject instead). See [10-hooks.md](10-hooks.md).
@ -467,9 +542,11 @@ Recommended combination for untrusted code:
---
## See Also
## See also
- [Hooks](10-hooks.md) — PreToolUse and other lifecycle scripts
- [Headless mode](14-headless-mode.md) — One-shot CLI and automation flags
- [Agent mode](15-agent-mode.md) — ACP, stdio, and agent servers
- [Sandbox](18-sandbox.md) — OS-level isolation profiles
- [Configuration](05-configuration.md) — Native `config.toml` structure
- [10-hooks.md](10-hooks.md) — Hook authoring guide
- [14-headless-mode.md](14-headless-mode.md) — Headless flags, including permission-related ones
- [18-sandbox.md](18-sandbox.md) — OS-level isolation profiles
- [05-configuration.md](05-configuration.md) — Native `config.toml` structure

4
crates/codegen/xai-grok-pager/docs/user-guide/README.md
View file

@ -27,7 +27,7 @@ Customize and extend Grok Build.
| 6 | [Theming and Appearance](06-theming.md) | Themes, the `/theme` command, `pager.toml`, and color-support detection |
| 7 | [MCP Servers](07-mcp-servers.md) | External tool integrations through the Model Context Protocol |
| 8 | [Skills](08-skills.md) | Reusable prompt packages in the SKILL.md format |
| 9 | [Plugins](09-plugins.md) | Bundle and share skills, commands, agents, hooks, and MCP servers; install from marketplace sources |
| 9 | [Plugins](09-plugins.md) | Bundle and share skills, commands, agents, hooks, and MCP servers; install from, author, and govern marketplaces (organization controls) |
| 10 | [Hooks](10-hooks.md) | Lifecycle scripts and HTTP callbacks for pre- and post-tool-use events |
| 11 | [Custom Models](11-custom-models.md) | Bring-your-own-key, Ollama, and OpenAI-compatible endpoints |
| 12 | [Project Rules (AGENTS.md)](12-project-rules.md) | Per-directory AGENTS.md instructions and their precedence |
@ -49,6 +49,6 @@ Automate, script, and integrate Grok Build with other systems.
| 19 | [Plan Mode](19-plan-mode.md) | Structured planning, plan-file edits, and approval before coding |
| 20 | [Background Tasks and Monitoring](20-background-tasks.md) | `background: true`, `/loop`, `monitor`, and `Ctrl+B` to demote |
| 21 | [Terminal Support and Troubleshooting](21-terminal-support.md) | tmux, SSH, truecolor, clipboard, and OSC 52 |
| 22 | [Permissions and Safety Controls](22-permissions-and-safety.md) | `dontAsk` mode, auto-approved tools, the safe-bash list, and restrictive PreToolUse hooks (such as git/gh-only) |
| 22 | [Permissions and Safety](22-permissions-and-safety.md) | Modes (always-approve, auto, ask), rules, matching, hooks, and examples |
| 23 | [Agent Dashboard](23-dashboard.md) | Central overview of local sessions and forks |
| 24 | [Monitoring Usage (External OpenTelemetry)](24-monitoring-usage.md) | Customer OTEL export |