Tools, scrollback, and the permission prompt

Why this matters

The TUI is not a chat log you skim. It is the place Grok shows you what it is about to do to your machine. File edits arrive as diffs. Shell commands arrive as permission cards. If you click through those the way you dismiss a cookie banner, you will ship a change you never read.

This module is the standing habit for the rest of Pathway C: read the diff before you accept. Always-approve (--yolo, Ctrl+O, /always-approve) exists. You will not use it here. You need to see the prompt enough times that you know what it is asking.

Teach

What Grok can call

Built-in tools, from the product docs:

MCP servers can add more tools. Ignore that until C7. Today you only need to recognize a read, an edit, and a shell in the scrollback.

Reads and a fixed list of read-only shell commands (ls, git status, git diff, rg, and the rest of the documented list) run without asking, unless a deny or ask rule says otherwise. Edits and anything that can write wait for you. That is the default ask mode. It is the correct mode for this pathway.

Scrollback is the work surface

Scrollback shows, in order you will actually see them:

• Your prompt (sticky header)
• Agent text, with markdown
• Thinking blocks (foldable)
• Tool calls — including inline diffs for edits
• Task lists

Tab focuses the scrollback. Arrow keys move. Left/Right collapse or expand the selected entry. Enter opens the fullscreen viewer. That viewer is how you read a long diff without guessing from the one-line summary.

If you turn on Vim mode (/vim-mode, or vim_mode = true under [ui] in ~/.grok/config.toml), j/k move, h/l fold, y copies the block, Y copies metadata (the exact command that ran). Default simple mode does not steal letter keys — a letter focuses the prompt and types. Leave simple mode on until you want otherwise.

@ in the prompt attaches files. The picker respects .gitignore and hides dotfiles unless you prefix !:

@src/main.rs
@src/main.rs:10-50
@src/
@!.env

Attach the file you care about. Do not dump the whole tree into context because you are in a hurry.

The permission prompt

When Grok wants to edit or run a non-read-only command, a blocking card takes the keyboard.

• Arrow keys / j k move the options
• 1–9 pick a row
• Enter confirms the focused row
• Tab / Shift+Tab walk the rows and stay inside the card
• Esc parks focus in the scrollback so you can read context; it does not approve or dismiss. Tab returns to the card
• Ctrl+C cancels the request
• Ctrl+O on the card turns on always-approve — do not press it today
• Left/Right widen or narrow what an “always” grant would remember
• On the reject row, typing starts a message back to the agent

Typical choices: allow once, reject once (optionally with a reason), allow all edits this session (in memory only), or enable always-approve for everything. Per-command “Always allow cargo test” rows stay hidden until you set remember_tool_approvals = true under [ui]. You do not need that yet.

Allow once after you have read the command or the diff. Reject once if the command is broader than the ask (rm, git push, a format-the-whole-repo, an edit to a file you did not mention). Type why you rejected it. Grok can recover from a no. It cannot un-run a git push.

Dangerous commands (rm, chmod, chown, pkill, kill, git push, and the rest of the documented list) prompt even when a remembered prefix would have covered them. An explicit allow rule or always-approve will still let them through. You have neither.

Modes, without turning them on

Shift+Tab cycles Normal → Plan → Always-approve → Normal. Ctrl+O and /always-approve toggle always-approve. /auto is a classifier mode that lets some work through and blocks or escalates the rest. --yolo on the command line is always-approve for that process.

Always-approve still honors deny rules, hooks, and some shell ask rules. It is not a license to skip reading diffs. It is a skip of the click. For automation and later modules, maybe. For C2–C6, stay in ask mode.

Deny always wins over allow, including over always-approve. You can put a narrow deny in .grok/config.toml later. Do not spend this lesson writing a policy file. Learn the card first.

Reading an edit

An edit is a search_replace (or write) in the scrollback. Expand it. You should see a unified diff: minus lines, plus lines, the path. Read the path first. If it is not the file you asked for, reject. Then read the hunks. If Grok “while I was here” also renamed a function, restyled the file, or touched tests you did not request, reject and tell it to do only the asked change.

After you accept, the file is on disk. The permission card is not a commit. git status and git diff are still yours. C4 makes that the whole lesson. Start the habit now.

Worked example

Scratch repo from C1. A README.md that says practice desk for Pathway C.

Launch grok in that directory. Send:

Add a one-line "Status: scratch" sentence to README.md. Do not touch any other file. Do not commit. Do not run formatters.

Watch the scrollback.

1. Grok will read_file or list_dir without asking. Let those run.
2. When search_replace appears, do not hammer Enter on the card. Esc if you need to park, Tab back, select the edit block, Enter to open the viewer.
3. Confirm the path is README.md. Confirm the hunk is one sentence, not a rewrite of the file.
4. Allow once.
5. Send: Show me git diff for README.md. Do not stage or commit.
6. Approve the git diff if it is asked (plain git diff is on the read-only list and often will not ask). Read the same change a second time from git.
7. If the first edit was a rewrite, reject it, say “one sentence only,” and wait for a smaller diff.

That is the whole loop: prompt, tool, read, allow or reject, verify on disk.

If you do not write software. The file does not have to be a README for an app. Attach the price list or the letter from the C0b scratch repository with @. Ask for one sentence — a “last updated” line, a status, a date. Read the diff the same way. Reject a rewrite of the whole letter. Accept one line. git diff still works on a text file.

Your turn

Do c2-l01-e1 in Grok Build. You will attach a file with @, force a permission prompt, read an edit in the viewer, reject one over-broad proposal (or a command you did not ask for), then accept a narrow one. Stay off always-approve.

Common failure

You approved the command from the summary line. The card shows a short form. Ctrl+F expands arguments. Open the tool block in the viewer. git is not one command — git status and git push are not the same family.

You pressed Ctrl+O or Shift+Tab onto Always-approve to “get on with it.” Cycle back to Normal. If you launched with --yolo, /quit and start without the flag.

The edit is folded to +N/-M. That is a display setting (collapsed_edit_blocks). Expand the block. A diffstat is not a review.

You let Grok run git commit or git add . because it offered. Reject. You did not ask. Staging secrets and junk is how practice repos become a mess and how real repos leak.

You argued with the model in the prompt instead of rejecting the tool. The reject row is there so the file never changes. Use it.

What’s next

C3 is plan mode: a read-only planning phase with its own file and its own approval bar. You will still be in ask mode underneath. The skill you just practiced — read, then allow — is the same skill with a larger document.

@README.md
Summarize this file in two sentences. Do not edit.

---

Rewrite README.md as a full project homepage with badges, a long feature list, and a contributing guide. Also run any formatter you like.

---

Add a single sentence to README.md: "Status: scratch." Do not touch any other file. Do not commit.