Custom prompts: passing arguments ($1..$9, $ARGUMENTS) + @ file picker + frontmatter hints (#3565)

Key features
- Custom prompts accept arguments: $1..$9, $ARGUMENTS, and $$ (literal)
- @ file picker in composer: type @ to fuzzy‑search and insert quoted
paths
- Frontmatter hints: optional description + argument-hint shown in
palette (body stripped before send)

Why
- Make saved prompts reusable with runtime parameters.
- Improve discoverability with concise, helpful hints in the slash
popup.
- Preserve privacy and approvals; no auto‑execution added.

Details
- Protocol: extend CustomPrompt with description, argument_hint
(optional).
- Core: parse minimal YAML‑style frontmatter at file top; strip it from
the submitted body.
- TUI: expand arguments; insert @ paths; render
description/argument-hint or fallback excerpt.
- Docs: prompts.md updated with frontmatter and argument examples.

Tests
- Frontmatter parsing (description/argument-hint extracted; body
stripped).
- Popup rows show description + argument-hint; excerpt fallback; builtin
name collision.
- Argument expansion for $1..$9, $ARGUMENTS, $$; quoted args and @ path
insertion.

Safety / Approvals
- No changes to approvals or sandboxing; prompts do not auto‑run tools.

Related
- Closes #2890
- Related #3265
- Complements #3403

docs/prompts.md

@@ -6,6 +6,12 @@ Save frequently used prompts as Markdown files and reuse them quickly from the s
 - File type: Only Markdown files with the `.md` extension are recognized.
 - Name: The filename without the `.md` extension becomes the slash entry. For a file named `my-prompt.md`, type `/my-prompt`.
 - Content: The file contents are sent as your message when you select the item in the slash popup and press Enter.
+- Arguments: Local prompts support placeholders in their content:
+  - `$1..$9` expand to the first nine positional arguments typed after the slash name
+  - `$ARGUMENTS` expands to all arguments joined by a single space
+  - `$$` is preserved literally
+  - Quoted args: Wrap a single argument in double quotes to include spaces, e.g. `/review "docs/My File.md"`.
+  - File picker: While typing a slash command, type `@` to open the file picker and fuzzy‑search files under the current working directory. Selecting a file inserts its path at the cursor; if it contains spaces it is auto‑quoted.
 - How to use:
   - Start a new session (Codex loads custom prompts on session start).
   - In the composer, type `/` to open the slash popup and begin typing your prompt name.
@@ -13,3 +19,61 @@ Save frequently used prompts as Markdown files and reuse them quickly from the s
 - Notes:
   - Files with names that collide with built‑in commands (e.g. `/init`) are ignored and won’t appear.
   - New or changed files are discovered on session start. If you add a new prompt while Codex is running, start a new session to pick it up.
+
+### Slash popup rendering
+
+When you type `/`, the popup lists built‑in commands and your custom prompts. For custom prompts, the popup shows only:
+
+- A five‑word excerpt from the first non‑empty line of the prompt file, rendered dim + italic.
+
+Details:
+
+- The excerpt strips simple Markdown markers (backticks, `*`, `_`, leading `#`) and any `$1..$9`/`$ARGUMENTS` placeholders before counting words. If the line is longer than five words, it ends with an ellipsis `…`.
+- If frontmatter provides an `argument-hint`, it appears inline after the excerpt; otherwise only the excerpt is shown. Placeholders still expand when you submit the prompt.
+
+Examples (illustrative):
+
+- Prompt file `perf-investigation.md` starts with: `Profile the slow path in module $1` → popup shows: `/perf-investigation  Profile the slow path in module`
+- Prompt file `release-runbook.md` starts with: `Assemble release checklist for this service` → popup shows: `/release-runbook  Assemble release checklist`
+
+Styling follows the Codex TUI conventions (command cyan + bold; excerpt dim + italic).
+
+### Frontmatter (optional)
+
+Prompt files may start with a YAML‑style block to describe how the command should appear in the palette. The frontmatter is stripped before the prompt body is sent to the model.
+
+```
+---
+description: "Run a post-incident retro"
+argument-hint: "[incident-id] [severity]"
+---
+Draft a post-incident retrospective for incident $1 (severity $2).
+List the timeline, impacted subsystems, contributing factors, and next steps.
+```
+
+With this file saved as `incident-retro.md`, the popup row shows:
+- Name: `/incident-retro`
+- Description: `Run a post-incident retro`
+- Argument hint: `[incident-id] [severity]`
+
+### Argument examples
+
+All arguments with `$ARGUMENTS`:
+
+```
+# search-codebase.md
+Search the repository for $ARGUMENTS and summarize the files that need attention.
+```
+
+Usage: `/search-codebase async runtime contention` → `$ARGUMENTS` becomes `"async runtime contention"`.
+
+Individual arguments with `$1`, `$2`, …:
+
+```
+# hotfix-plan.md
+Prepare a hotfix plan for bug $1 targeting branch $2.
+Assign engineering owners: $3.
+Include smoke tests and rollback steps.
+```
+
+Usage: `/hotfix-plan BUG-1234 main "alice,bob"` → `$1` is `"BUG-1234"`, `$2` is `"main"`, `$3` is `"alice,bob"`.