flashlite 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,584 @@
-# Temporary Holding Version
+# flashlite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A personal agentic coding CLI — Claude Code / pi style — for any OpenAI- or
+Anthropic-compatible chat endpoint. Streaming chat REPL plus an agent loop
+with **filesystem tools** for creating and organizing projects, reading/editing code,
+searching, copying assets, and removal, plus **terminal commands** for builds, tests,
+and other requested work. Opt-in **guarded auto** runs arbitrary terminal commands
+without prompts, but still asks before network access, installs, sudo, paths outside
+the project, and destructive Git operations — and refuses obviously catastrophic
+deletion/disk commands. A separate **unguarded auto** mode permits whole-drive file
+access and every command; only recognizable catastrophic actions ask.
+
+TypeScript on Node ≥ 24, run straight from source via Node's native type stripping:
+**zero build step, zero runtime dependencies** (only `typescript` + `@types/node` as
+devDependencies for typechecking). macOS only.
+
+## Setup
+
+```bash
+npm install        # devDependencies only (typescript + @types/node)
+npm run typecheck  # tsc --noEmit
+npm test           # node --test — the full suite is offline
+
+# put the CLI (command `flash`) on your PATH (no root needed):
+mkdir -p ~/.local/bin
+ln -s "$PWD/scripts/flashlite-wrapper.sh" ~/.local/bin/flash   # or copy it; chmod +x
+```
+
+On first interactive launch, `flash` asks for your endpoint URL and then your API key
+with masked input, saving both to `~/.config/flashlite/config.json` (chmod 600). Each
+local user provides their own endpoint and key; nothing is bundled with the npm package
+or baked into the binary. Keys are never printed, logged, or committed — not even
+masked. Non-interactive runs require an existing config file (or `--base-url`).
+Configuration is validated before
+use: `auto_approve` must be a JSON boolean (the string `"false"` cannot enable it),
+`max_output_tokens` must be an integer from 256–65536,
+and `tool_result_budget_bytes` from 0–4,000,000 (0 disables tool-result elision).
+Invalid fields produce value-free warnings and fall back to defaults; permission
+fields fail closed. Base URLs must use HTTP(S) and cannot contain login credentials,
+query strings or fragments.
+
+```bash
+flash --check          # connectivity + model catalog diagnostic
+flash                  # the REPL
+flash -p "explain this code: …"  # text-only one-shot; no tools or workspace access
+flash --agent -p "inspect this repo"  # headless tools, read-only by default
+flash --agent --auto -p "fix the failing tests and verify"  # trusted project; guarded commands
+flash --agent --auto-approve -p "update the README"  # file changes only
+flash --absolute       # unguarded auto: whole drive + every command; no gate
+flash --auto           # guarded auto; network/installs/sudo/outside/destructive still ask
+flash --auto-approve   # file-only auto; every terminal command still asks
+flash --model <id> --debug
+```
+
+## Real-work workflows
+
+The agent is instructed to inspect relevant files, make focused changes, run authorized
+validation, diagnose failures, retry, and report what was actually verified. Tool
+schemas explain scope, approval and supported follow-up options instead of treating
+bounded output as a dead end. Applicable `CLAUDE.md` files are loaded from the nearest
+repository root down to the launch directory, attributed to their source/scope. Outside
+a repository, only the launch directory is considered. Sources are regular, non-symlink
+files, bounded to 16 KiB each / 32 KiB total; nested guidance must be inspected when
+working in a deeper subtree. Project instructions cannot override host permissions or
+credential protection.
+
+For automation, **`--agent -p` explicitly enables tools**. It defaults to read-only,
+ignoring saved `auto_approve` permissions. Add `--auto-approve` for file changes or
+`--auto` for file changes plus guarded commands. Actions without approval
+are denied as tool results, never an unattended approval prompt; denied/failed tools
+or unfinished turns produce a nonzero exit code. Headless runs save private transcripts
+and retain completed-action evidence. They use bounded tool rounds but currently do
+not fetch model context windows or auto-compact; keep automated tasks scoped. Unguarded
+auto is interactive-only. Ordinary `-p` remains text-only, not a repo-inspection mode.
+
+## The REPL
+
+- **Terminal UI:** chat scrolls above a bottom-anchored panel, with the selected model
+  on its top divider, the orange `❯` input between dividers, and a labeled status row
+  below. Your input echoes with its orange `❯` chevron; streamed assistant replies
+  start with a subtle `●` marker. Tool calls are grouped by name only within a single
+  model-proposed batch, not across later calls. The layout uses a flat light yellow accent (#ffe066)
+  for branding, models, menus, and availability, with orange (#ff9f40) for keywords. The status row names every token (`mode`/`effort`); the effort value
+  warms from light yellow to red as the level rises, and the drive-wide mode badge reads
+  `unguarded auto`. A resting status word is omitted from the footer; success states stay
+  green and warnings amber/red, and **Shift+Tab** cycles the permission mode. Command menus
+  and views open immediately **below the input**, outside
+  the scrolling conversation. While a command is open, the normal status row is
+  hidden so only its controls remain. Reasoning text is hidden; answers and
+  in-flow tool activity cards stay in chat. The compact header shows only the
+  working directory. Pipes and very small terminals keep a simple layout; `--no-color`
+  disables styling and animation. Set `FLASHLITE_THEME=light` for white/light terminals: the
+  warm palette darkens and switches to explicit true-color (no bright `9x`, no `2` faint) so
+  every text role keeps ≥4.5:1 contrast; `dark` is the default and unchanged. Restart `flash`
+  after source changes — existing sessions do not hot-reload.
+- **Context meter:** the bottom bar shows conversation context usage as a color-coded
+  percent with token counts (e.g. `ctx 42% 42k/100k`) — accent up to 70%, yellow 70–85%, red above 85%;
+  missing or disabled context shows nothing. The context amount is always kept visible,
+  even on narrow terminals — the status truncates around it.
+- **Dynamic slash commands:** type `/` to open a live filtered palette below the input.
+  ↑/↓ selects, Tab completes, Enter runs, and Esc dismisses. `/model` opens the model
+  picker; `/model <id>` still sets
+  directly and persists the default. `/compact` summarizes older complete
+  turns while retaining the latest user turn; the append-only session log stores a checkpoint
+  so resumed conversations use the compacted context. `/settings` offers token saver
+  (off/low/high/custom) and boost (on/off) instead of raw token-budget controls. Off
+  uses saved budgets; low/high reduce output, context and replay budgets and compact
+  earlier. Custom opens the advanced output/context/replay/compaction controls.
+  Boost keeps the same model, reasoning effort and token budgets. For substantial
+  requests it starts independent read-only code/UI investigation or research helpers
+  while the main agent works. Finished findings arrive at safe model-round boundaries
+  so the main agent can avoid duplicate investigation; remaining helpers are awaited
+  before concluding. Focused validation stays with the main agent.
+  Small tasks skip delegation. Boost tints the model name, `ϟ` glyph and composer rules
+  orange. While the model works, a highlight sweeps the full model bar and the lower
+  composer rule; at rest the bar holds its static orange. Set
+  `FLASHLITE_REDUCED_MOTION=1` (or `NO_COLOR`) to disable motion, and animations never
+  run in piped output.
+  Flashlite already uses fast context checks, bounded replay and parallel tool calls in
+  every mode; Boost cannot force faster provider inference. Presets do not overwrite
+  advanced config values. **Shift+Alt+Tab** toggles Boost in the interactive editor. Settings also include the local API key,
+  default model, reasoning effort, permission default, endpoint and **Memory** entry.
+  Pick Memory to append a global prompt for the next turn. Context checks use exact
+  counting near the limit where supported and estimates otherwise. Key entry is masked and never echoed; credentials come only from the local config. `/mode` picks `ask`, `files`, guarded `auto`,
+  or unguarded `auto`; `/mode auto` and `/mode unguarded` switch directly, and **Shift+Tab**
+  cycles the mode from the prompt. Modes are session-only. `/clear` resets the visible conversation and starts
+  a fresh transcript; `/exit` quits. Command notices and controls stay below the
+  input; agent answers and tool cards stay in chat. Pipes and tiny terminals use plain
+  command output.
+- **Anchored scrolling and selection:** Page Up/Down scroll conversation history while
+  the input stays fixed, even during a streaming answer. New output does not pull you
+  away from the history you are reading. Page Down returns live; submitting a new
+  turn also returns live. Open command panels/pickers receive these keys instead.
+  Display history retains the latest 10,000 logical lines; full transcripts stay on disk.
+  Mouse reporting stays disabled so normal click-and-drag text selection and copy work
+  without a modifier key. The mouse wheel uses your terminal's native scrolling.
+- **Effort:** `/effort` opens a picker for `auto`, `low`, `medium`, `high`, `xhigh`, `max`;
+  `/effort high` sets directly. The choice is shown in the bar and saved as
+  `reasoning_effort`. `flash --effort high` overrides it for this run, including `-p`.
+  `auto` omits an explicit API setting. Chat Completions uses `reasoning_effort`; Messages
+  uses thinking budgets (2,048 / 4,096 / 8,192 / 16,384 / 32,000 tokens), raising total
+  `max_tokens` when necessary to leave at least 4,096 tokens for the answer. Supported
+  levels depend on the model/router; a rejection is reported, not silently downgraded.
+  DeepSeek is the exception: its picker offers only the levels the model accepts
+  (`auto`, `low`, `high`, `max`; `auto`, `high`, `max` for `pro`) and the wire value is
+  coerced (`medium`/`xhigh` → `high`) so an unsupported level is never sent.
+  Signed thinking blocks are retained for tool continuations, never shown in chat.
+- **Live agent cards:** the thinking indicator updates in place in the chat area, above
+  the composer, not in the bottom status strip. It is transient (not transcript/history
+  content), disappears when the answer starts, and stays hidden while viewing older
+  chat. Hidden model reasoning remains hidden. Tool activity updates a card **in the
+  conversation**, rather than pinning it to the composer; file writes/edits show pending
+  code as arguments stream, then update that same card to success/denied/error. An edit
+  over a readable file renders as a line-numbered unified diff — context rows, `+`/`−`
+  rows and a `+N −M` chip — with the code token-colored by the file's language; when the
+  target can't be read (a new file, a partial stream) it falls back to a plain `− old`/
+  `+ new` block. The finished card keeps the `+N −M` count. Completed
+  cards remain in chat history, and later replies follow them. Previews do not execute
+  changes: writes follow the selected permission mode. Completed cards name what a tool acted on
+  beside its timing — e.g. `✓ read_file 2x · src/a.ts · src/b.ts · 1.2s` and
+  `✗ run_command · npm test · 2m 05s` — and denied runs say what was denied; live queued cards show
+  the subject too (e.g. `● read_file src/a.ts`).
+- **Image attachments:** **Ctrl+V** reads an image from the macOS clipboard and queues
+  it for your next prompt; your typed draft stays intact. Copy an image, or capture a
+  screenshot directly to the clipboard with **Ctrl+Cmd+Shift+4**, then Ctrl+V in `flash`.
+  **Cmd+V** still handles ordinary terminal text paste. An empty/text-only clipboard
+  produces a notice, not a message to the agent. Clipboard access occurs only on this
+  explicit shortcut, never in the background or via agent tools.
+  Pending filenames appear in the footer. Type your question and Enter, or Enter alone
+  to send an image-only turn. **Ctrl+X** removes pending attachments; `/clear` removes
+  both queued attachments and images already in conversation history. Images stay in
+  history across tool rounds and follow-up questions. Failed requests retain the original
+  user message and images in history once; send a continuation to retry without reattaching. Use an **image-capable model**: router/model support varies,
+  and unsupported images are reported rather than silently dropped.
+  - Up to 4 images per prompt, 10 MiB each, 20 MiB total. Clipboard PNG is preserved;
+    screenshot TIFF is converted to PNG using AppKit. No resizing or HEIC conversion.
+    TIFF input is bounded to 40 MiB / 40 million pixels before PNG conversion.
+  - `flash --image ./shot.png -p "Explain this screenshot"` works in one-shot mode;
+    repeat `--image` for multiple files. Without `-p`, images are queued in the REPL.
+    Local files support PNG, JPEG, WebP, GIF, quoted paths, `~/`, and absolute paths.
+  - No image slash commands. Type `/` for the palette or `/help` for shortcuts and recovery.
+    Clipboard images are local snapshots; nothing is uploaded until you submit a prompt.
+    Remote image URLs and Finder file-copy clipboard references are not supported.
+  - Clipboard access uses macOS's built-in `/usr/bin/osascript` with fixed AppKit/JXA
+    code via `execFile` (no shell, packages, native compilation, or temporary image files).
+    Reads time out after 10 seconds and Ctrl+C cancels; failed/cancelled reads keep the
+    queue intact. Shortcuts are disabled during turns, permission prompts, model pickers
+    and command panels.
+  - UI and Markdown transcripts show filenames/metadata only. Private JSONL transcripts
+    (mode 0600) retain the encoded image bytes, so they can be much larger and include
+    private image content. No clipboard payload is printed to the terminal.
+  - Context warnings use exact Messages token counting when available, otherwise a rough
+    2,048-token allowance per image; actual image tokens vary by model and resolution.
+- **Live typing and steering:** the composer stays editable while the AI streams or
+  runs tools. **Enter** queues your text as steering; muted grey message rows above
+  the composer show what's pending, with the count in the existing footer. The latest
+  three messages are visible (earlier ones are summarized); long rows use an ellipsis.
+  Smaller terminals reduce this preview to preserve chat and the anchored composer.
+  Messages are delivered in order at the next safe model boundary,
+  after all results from an in-flight tool batch. A queued message received during
+  a final answer starts another response in the same turn. It does not interrupt a
+  running request or undo tools already executing — **Ctrl+C** stops the turn.
+  Pending previews update in place and disappear when sent. Applied messages use the
+  ordinary user-message styling, with no “steer:” prefix, and are included in the same
+  active workflow/transcript. Delivering them does not stop or restart the agent or a
+  running terminal command. A provider request already in flight cannot accept new
+  input retroactively; the next continuation receives the messages after tool results.
+  Pending text is display-only.
+  Unsubmitted drafts survive turn completion and temporarily yield to permission
+  questions, then return afterward. Permission answers are not steering. Ctrl+C
+  during approval cancels rather than approving the write. Unapplied steering on
+  cancellation, error or the tool-round cap returns to the editor for an explicit
+  retry; multiple restored messages are joined in order. Slash commands work during
+  a turn: `/model`, `/effort`, and `/mode` open their usual controls while
+  the AI continues. Model/effort changes apply to the **next turn**; current requests
+  and tool continuations retain their original settings, and usage/transcripts remain
+  attributed to the active turn's model.
+  Cancelling a command does not cancel the agent. Permission questions take priority
+  over open command controls. `/clear` cancels and awaits the active turn before
+  resetting history/queued steering; `/exit` stops both. Clipboard shortcuts remain
+  idle-only.
+- **Agent loop:** no fixed tool-round cap — the turn runs until the model stops requesting
+  tools (bounded by the context budget, output limits and auto-compaction).
+- **Tool-result budget:** to keep replay tokens bounded, older tool results are elided from
+  the request the model sees once their combined size exceeds `tool_result_budget_bytes`
+  (default 8,192; advanced value in config.json, 0 disables). The newest result is always
+  sent whole; older ones are replaced with a short `[earlier tool result elided …]` stub that
+  records the original size. This trims only the replayed request — canonical history, the
+  transcript and tool-call/result pairing stay intact, and the elision is idempotent across
+  rounds.
+- **Multi-turn context:** each turn appends the user message and the assistant answer to
+  the conversation, so follow-ups continue the same context. The router only concatenates
+  a prior turn's chain of thought when the request carries `tools`; this CLI follows that
+  rule — OpenAI `reasoning_content` is retained on the assistant message but replayed only
+  while tools are present (so tool continuations keep continuity), and tool-less requests
+  omit it. Model reasoning is never shown in chat or written to the Markdown log; it stays
+  in the private JSONL transcript. "Steering" is separate: it queues a message delivered at
+  the next safe boundary *within* an active turn.
+  File and terminal approvals appear in a bordered panel above the composer with a
+  separate choice row, not as text in the normal input bar. File changes accept
+  `y` = once, `a` = all file changes (this session), `n` or Enter = deny.
+  `--auto-approve` or `"auto_approve": true` skips **file-write** prompts only.
+  `/mode auto` or `--auto` runs arbitrary terminal commands, still asking before the five
+  guarded-auto risk categories.
+  In `ask` and `files` modes, all terminal commands show the full
+  command/cwd/timeout and require their own explicit `y`/`yes`; blank, `a`/`all`, EOF
+  and cancellation do not authorize them. Unguarded auto skips file and command prompts
+  entirely, except recognizable catastrophic commands.
+  `/mode ask` revokes automatic grants;
+  queued auto/unguarded commands and unguarded file mutations cannot start after
+  revocation. Running commands need cancellation to stop; file operations also recheck
+  cancellation/authorization at bounded checkpoints.
+  Tool batches have four workers; approvals are asked just-in-time (one prompt at a time,
+  in call order) so an early tool can run while later calls still await approval, and
+  results keep their call order. After the last
+  permitted batch, one tools-disabled request lets the model evaluate its results.
+  Truncated/incomplete proposals never execute; unmatched/duplicate batch IDs stop with
+  an explicit interruption rather than corrupting the next request. Round exhaustion,
+  context exhaustion, invalid calls and model truncation have distinct recoverable
+  notices—not invented success. Completed tool evidence survives failures.
+  Interactive context checks reserve actual output/thinking capacity. Auto-compaction
+  can summarize older exchanges within a long active task, retaining current instructions
+  and the latest two complete exchanges (including required signed thinking). Attempts
+  are bounded and recounted; if retained context still cannot fit, the turn stops instead
+  of knowingly sending an overfull request. Fallback token counts remain estimates.
+- **Keys:** Enter submits, arrows walk history, Ctrl+C interrupts (aborts a streaming
+  turn), Ctrl+D exits. **Ctrl+O** expands/collapses the latest completed tool batch's
+  output in place; the expanded view shares the chat viewport across calls, with
+  omitted lines indicated (full results remain in the private transcript).
+  Full output also remains in the private session transcript. `/agents` shows running
+  agents and role settings; select a role to launch or configure its model/effort.
+  Defaults inherit the current main model and effort at launch; changes affect future
+  launches, not running jobs. `/agents <role> <task>` starts one directly, while
+  `/agents list`, `/agents show <id>` and `/agents stop <id>` inspect or stop jobs.
+  Roles include ui-ux, code, minor, oracle, reviewer, coder and researcher. All agents
+  are read-only: they can inspect project files but never edit them or run shell
+  commands. Boost-spawned helpers remain read-only too. Researchers can read public
+  HTTPS text/HTML/JSON pages without a network prompt; local/private endpoints and
+  redirects are blocked. Running and finished agents remain listed above the input.
+  **Ctrl+R** opens a bash-style reverse history search: typing narrows,
+  Ctrl+R or ↑ walk older matches, ↓ newer, Enter accepts the match back into your draft (Enter
+  again submits), and Esc restores your exact pre-search draft. Multi-line bracketed pastes
+  submit as one turn. The model picker
+  navigates with ↑/↓ (or `j`/`k`), confirms with Enter, cancels with Esc or Ctrl+C.
+- **Markdown:** answers render as markdown — `**bold**`, `` `code` ``, fenced code
+  blocks (light yellow), `#` headings, list markers, and `[links](url)` (URL dropped). Italic is
+  intentionally unsupported (`*`/`_` collide with identifiers). Fenced code with a recognized
+  language (`ts`, `js`, `jsx`, `json`, `bash`, `sh`, `zsh`, `python`, `go`, `rust`, `yaml`, `toml`)
+  is token-colored live and in one-shot — keywords orange, strings green, numbers yellow, comments
+  dim — while prose stays default. Unknown or absent languages keep the flat light-yellow accent,
+  and fence openers show their language tag in orange. Transcripts keep the raw
+  markdown; styling is display-only. Partial prose, bold/code spans, and code-block
+  content appear as chunks arrive, without waiting for a newline or Ctrl+C. Only
+  ambiguous Markdown prefixes/links use bounded lookahead. Streamed replies discard
+  oversized leading/trailing blank gaps and use one blank line between prose paragraphs;
+  code-block whitespace is preserved.
+- **Sessions:** every turn appends to `~/.config/flashlite/sessions/` — a
+  markdown log plus a JSONL transcript. Resume the newest saved conversation with
+  `flash --resume latest`, a specific one with `flash --resume <session-id>`, or use
+  `/sessions` from the REPL to select one. New sessions record their canonical workspace;
+  resuming from a different folder is blocked rather than silently retargeting paths.
+  Legacy sessions require explicit workspace acknowledgement (CLI:
+  `--acknowledge-legacy-workspace`). Permissions are never restored from a transcript.
+  Validated context and recoverable checkpoints retain completed actions even after a
+  later provider failure. Transcript errors do not undo execution; a later successful
+  JSONL write checkpoints unsaved context. If logging keeps failing, evidence is retained
+  only in the running process, not guaranteed on disk. Future turns append to the same
+  private transcript; `/clear` starts fresh.
+- Model IDs auto-route to the right wire dialect: `anthropic/*` speaks the Messages
+  API; everything else speaks Chat Completions. Bare `claude-*` and
+  `gpt-*`/`grok-*`/`deepseek-*` also work; other bare IDs ask for the full
+  provider-prefixed ID from `/model`.
+
+## Custom commands, memory, hooks, todos, and undo
+
+Five extension points build on the same tool/approval engine:
+
+- **Custom slash commands.** Drop markdown files in `~/.config/flashlite/commands/`
+  (global) or `<project>/.flashlite/commands/` (project; shadows global by name). The filename
+  is the command (`review.md` → `/review`); the body is a prompt template. `$1`..`$9`
+  substitute positional arguments and `$ARGS` substitutes them all. Optional frontmatter
+  sets `description` (shown in the `/` palette) and `argument-hint`. No shell interpolation
+  runs — the body is prompt text, not a script.
+- **Path completion.** Tab completes `@file` mentions and bare paths relative to the working
+  directory (directories get a trailing `/`); an unambiguous match resolves fully, an
+  ambiguous one extends to the longest common prefix.
+- **Memory.** `~/.config/flashlite/memory.md` (global) and `<project>/.flashlite/memory.md`
+  (project) are loaded into the system prompt (bounded, treated as data). The `/settings`
+  **Memory** entry appends a global memory prompt; project memory can be edited directly.
+- **Todos.** The agent can call `todo_write` to publish a task list
+  (`pending`/`in_progress`/`completed`/`cancelled`); it renders live in a dock strip with
+  `☐`/`◐`/`✓`/`✗` and clears on `/clear`.
+- **Undo.** Before a mutating file tool runs, its target's original bytes are captured; a
+  turn's captures form a checkpoint. `/undo` reverts the most recent turn's file changes
+  (created files are removed, changed files restored). Shell side effects are never
+  captured — this only reverses the file tools.
+- **Hooks + notifications.** Executable scripts named `PreToolUse`, `PostToolUse`,
+  `Notification`, or `Stop` in `~/.config/flashlite/hooks/` or `<project>/.flashlite/hooks/`
+  receive one JSON object on stdin. `PreToolUse` may veto a call with
+  `{"decision":"block","reason":"…"}`; hook errors fail open. A ~15s+ turn also fires a
+  macOS notification.
+
+## Tool policy
+
+Tools are available in the interactive agent REPL. Launch `flash` from the folder you
+want it to work in. In `ask`, `files`, and guarded `auto`, **filesystem-tool paths**
+are relative to that folder and confined there: absolute paths, `~`, parent-directory
+escapes, and symlink escapes are refused. In unguarded `auto`, tools can use
+absolute paths, `~/`, parent paths and external symlink parents across the drive,
+wherever your current macOS account has permission. Terminal commands are separately
+authorized (explicitly, by guarded auto, or by unguarded auto) and are
+**not sandboxed**. Their starting directory is validated, but their effects can extend
+to other files on your PC and the network. Ordinary `-p` is chat-only; explicit
+`--agent -p` uses the same tools with the noninteractive approval policy above.
+
+| Tool | What it does | Approval |
+| --- | --- | --- |
+| `read_file` | Read text, with UTF-8-safe byte pages up to 256 KiB and continuation metadata | No |
+| `read_files` | Read 1–20 text files with per-file errors and a shared 256 KiB content budget | No |
+| `file_info` | Inspect type, size, permissions and modification time; no file content | No |
+| `list_dir` | Sorted directory pages using `offset` and `limit` (up to 500 per page) | No |
+| `find_files` | Find paths by literal substring, optionally files/directories only | No |
+| `grep` | Stream literal text search in a file or directory with bounded snippets and honest partial-result metadata | No |
+| `write_file` | Create/overwrite text, including missing parents, up to 1 MiB | Yes |
+| `edit_file` | Replace a nonempty, unique exact match; resulting file up to 1 MiB | Yes |
+| `make_dir` | Create folders and missing parents | Yes |
+| `copy_path` | Copy a file (including binary assets) or directory tree | Yes |
+| `move_path` | Move/rename a file or directory | Yes |
+| `remove_path` | Permanently delete a file/directory (no recovery store; use git or a copy) | Yes |
+| `run_command` | Noninteractive terminal command with bounded output/time | Explicit yes; guarded auto for arbitrary commands except five risk categories; unguarded auto for everything |
+
+File mutations marked Yes ask in `ask` mode and run automatically in `files`/`auto`/`unguarded`.
+Neither file approve-all nor `--auto-approve` grants terminal authorization.
+
+`copy_path` and `move_path` **never overwrite an existing destination**.
+Copy/move/remove preflight trees with a 5,000-entry / 100 MiB limit. Tree
+operations reject symlinks and special files rather than silently omitting entries.
+Outside unguarded auto they also reject `.git` internals;
+mutations reject symlink paths (even links staying inside the project), the working
+directory itself, and `.git` internals. Unguarded auto lifts those project/protected-name
+path guards, but write/edit still refuse final symlinks and non-regular files, and
+tree operations still refuse symlink entries. Text tools reject NUL-containing binary
+files. Write/edit may overwrite according to the selected permission mode; read before
+changing an existing file. Aborted/revoked copies roll back their newly-created destination
+contents; an individual OS copy syscall cannot be interrupted, and newly-created parent
+folders may remain. File paging/search is not snapshot-isolated from concurrent rewrites.
+
+`find_files` caps at 500 results / 5,000 inspected entries; `grep` caps at 200 results /
+5,000 inspected entries (including directories). Both skip symlinks. Outside unguarded
+auto they also skip `.git`, dependencies, common build directories and
+`.DS_Store`; unguarded searches include those names, without dropping traversal/output
+caps. Find patterns are literal, not globs or regular expressions.
+
+Large text files can be inspected without increasing context arbitrarily:
+`read_file(path, offset_bytes?, max_bytes?)` returns ordinary text for a complete small
+file, or a JSON page with byte positions, total bytes and `next_offset_bytes` for a
+large/ranged read. Page content is UTF-8-safe; continue using the returned offset.
+`list_dir(path?, offset?, limit?)` sorts entries and reports the next offset when more
+remain. Pages are not filesystem snapshots: restart after directory changes. A listing
+that reaches its 100,000-entry scan bound is explicitly partial, without a misleading
+continuation offset for an unscanned remainder.
+
+`grep` can search a single regular file as well as a directory. Its default scan
+budget is 16 MiB (configurable with `max_scan_bytes` up to 100 MiB), and results use
+bounded snippets with byte positions. `max_output_bytes` controls the aggregate result
+budget up to 64 KiB, including partial-result notices; `max_results` is capped at 200.
+For a single file, pass the reported `next_start_byte` as `start_byte`; inspect matching ranges
+with `read_file`. Directory traversal caps/skipped files are explicitly reported:
+partial search is not an exhaustive “no matches.” Narrow the directory scope when
+traversal is capped. Search may read up to 16.5 KiB of preceding context and 16 KiB of
+unsearched suffix context for snippets/credential redaction; matches and continuation
+stay within the forward scan budget. Read-page limits bound source bytes, not JSON
+escaping/redaction overhead. Binary/special files remain unsupported by text tools.
+
+Mutations from concurrent tool batches are serialized per project in this process.
+Confinement is a path guard, not an OS sandbox against another process changing the
+filesystem concurrently; avoid moving project folders or changing symlinks mid-operation.
+
+**Removal is permanent.** `remove_path` deletes with `fs.rm`; there is no recovery
+store, `list_removed`/`restore_file`, or automatic purge — git (or a copy made first) is
+the only recovery. A shell `rm` is likewise a real deletion, and redirects/`tee` can
+clobber a file. These file-tool protections are not an OS sandbox: an approved terminal
+command can delete files the tools guard.
+
+### Terminal commands
+
+`run_command(command, cwd?, timeout_ms?)` uses macOS `/bin/zsh -f -c`, with ignored
+stdin and piped stdout/stderr, not an interactive terminal. `cwd` must be an existing
+project directory (default project root), except unguarded auto also permits existing
+directories elsewhere on the drive. The default timeout is 60 seconds, maximum
+5 minutes; commands are limited to 16 KiB and captured output to a combined 1 MiB.
+Overflow terminates the command and reports truncation, not unlimited collection.
+Results include status, exit code/signal, stdout/stderr and truncation; failure is
+reported faithfully. The live card shows lifecycle only, not raw command output.
+
+In ask/file-only mode, every command gets a separate approval. Guarded auto runs
+arbitrary commands without a prompt except for five risk categories (below); unguarded
+auto runs every command except recognizable catastrophic deletion/disk destruction.
+When a command needs approval, its full text,
+canonical cwd and effective timeout appear in chat before the anchored yes/no question;
+control/invisible characters and backslashes are escaped visibly rather than executed
+by the terminal. Known router-key-bearing commands are rejected before display.
+Commands use a minimal environment allowlist (standard path/home/user/temp/locale
+variables, `TERM=dumb`), not ambient credential variables. Known router credentials
+are redacted from captured output before model/history/transcript use. This is not
+comprehensive secret isolation: commands can still read local configuration or make
+network requests. Review what you approve. `/bin/zsh -f` disables ordinary user rc
+loading; it does not isolate system startup behavior.
+
+### Guarded auto
+
+Enable with `flash --auto`, `/mode auto`, or the `/mode` picker. It is opt-in for this
+session, never saved as a default. `files` mode and legacy `auto_approve` remain file-only;
+`--auto`, `--auto-approve`, and `--absolute` are mutually exclusive.
+
+Guarded auto is **trust-by-default**: arbitrary commands and pipelines run without a
+prompt, including unknown executables, interpreters, builds, tests and file mutations.
+Exactly five categories still ask, and none can be hidden behind a wrapper, pipeline,
+env assignment or literal `sh -c` body:
+
+- **Network access** — `curl`, `wget`, `nc`, `ssh`, `scp`, `rsync`, `git fetch|pull|push|clone|remote`, and similar.
+- **Installs / package managers** — `npm install|ci|add|…`, `pnpm`/`yarn add`, `brew`, `pip`, `apt`, `cargo install`, `go get`, `npx`, and similar.
+- **Privilege escalation** — `sudo`, `doas`, `su`, `pkexec`.
+- **Paths outside the project** — absolute paths, `~`, parent (`..`) traversal, and symlink escapes.
+- **Destructive Git** — `git reset --hard`, `git clean -f…`, `git push --force`, `git branch -D`.
+
+Obviously catastrophic deletion or disk commands (recursive deletion of a filesystem
+root, home or volume; `diskutil` erase; `mkfs`; `dd`/redirection to a raw disk) are
+**refused outright**, not offered. Syntax the classifier cannot reduce to inspectable
+words — command substitution, backticks, globs, here-docs, `eval`/`source`, subshells
+and background jobs — fails closed and asks. Paths must resolve inside the project,
+plus the CLI's own `~/.config/flashlite` tree for reads. `cp`/`mv` never overwrite.
+
+**Guarded auto trusts arbitrary commands and project code.** A classifier is not proof
+of safety, this is not an OS sandbox, and buildings/tests can execute arbitrary code with
+side effects. There is an external filesystem race between inspection and execution;
+command text cannot provide isolation. Do not enable auto in an untrusted repository.
+Turning auto off revokes queued grants, including after turning it on again, but does
+not interrupt work already running.
+
+### Unguarded auto
+
+Enable with `flash --absolute`, `/mode unguarded`, or the `/mode` picker. It takes effect
+immediately with a one-line notice — there is no typed acknowledgement or disclaimer
+gate. A `/mode` switch applies to the session; the `/config` default-mode picker can save
+it as the launch default (written to config as `unguarded`, never `absolute`). An
+interactive terminal is required, and `--absolute` is rejected with `-p`, `--check`, or
+piped input/output.
+
+**Unguarded auto has no approval prompts and no guarded-auto ask list.** Ordinary `rm`,
+builds, installs, Git changes, elevated, unknown and opaque commands all run. File tools
+can read/change paths across the drive, including absolute paths and `~/`, and commands
+may start outside the project. The mode badge reads `unguarded auto`. Use only when you
+trust the task and the files/code the agent will encounter.
+
+The only exceptional action-confirmation gate recognizes **very large irreversible
+operations**: recursive deletion of a filesystem root, whole home/user tree, named
+system root or whole mounted volume (including whole-tree glob variants); destructive
+`diskutil` erase/partition/APFS-delete operations; formatting a raw disk with
+`mkfs`/`newfs`; `dd` writing a raw disk; or shell output redirected to a raw disk.
+Recognized literal `sudo`/`env` wrappers, compound commands and `sh`/`zsh`/`bash -c`
+bodies are checked too. These show the exact command/canonical cwd/timeout and require
+an explicit **yes for that command only**, without disabling unguarded auto. Denial,
+cancellation or revocation prevents that command from starting.
+
+This is a **best-effort recognizer, not a safety guarantee**: it does not inspect
+script files, aliases, arbitrary expansions, remote code or general interpreter
+programs, and it does not make opaque commands safe. Unrecognized actions still run
+without a prompt in unguarded auto; do not rely on this gate to protect your machine.
+
+This is current-account access, **not automatic root/sudo or a bypass of macOS privacy
+permissions**. No interactive password entry is provided. Tool byte/tree limits,
+regular-file and symlink-tree rules, no-overwrite copy/move and permanent-deletion
+guards, bounded command output/time and cancellation remain. Commands can still
+perform permanent deletion. Known router credentials are rejected in commands and
+redacted from command output and unguarded file-tool results/errors before history;
+this is not comprehensive secret isolation or a network sandbox.
+
+Unguarded auto is session-only, never saved or enabled by `auto_approve`. `/mode ask`
+disables it; queued unguarded commands/mutations recheck their mode generation before
+executing. Turning it back on cannot revive old grants. Running commands are not
+interrupted by a mode change; use Ctrl+C to stop the active turn. File tools recheck
+live authorization at bounded checkpoints and before commits; revoked copies roll back
+new destination data.
+
+### Command cancellation
+
+Ctrl+C, `/clear`, `/exit`, timeout and output overflow terminate the process group,
+with TERM→KILL escalation. Normal shell completion also cleans up ordinary background
+descendants. There is no persistent-background-job or interactive-input API; programs
+requiring a TTY or password entry may fail. Descendants that detach into another
+process group/session can escape cleanup; no sandbox guarantee is made. Commands
+serialize with project mutations in this process and recheck cancellation before
+queued execution starts. Tool results remain paired with calls after cancellation,
+so continuing the conversation does not send broken tool history.
+
+For example: “Create a small website in `site/`, copy my assets into it, and run its
+tests.” In ask mode, the agent creates the structure with approval and asks before
+running tests. In guarded auto, the project work runs without per-call prompts, but a
+network install or `sudo` still asks. Package installs and downloads are performed
+through authorized commands, not silently through filesystem tools.
+
+## Development
+
+```
+src/index.ts       entry, flags, bootstrap      test/            node:test suites
+src/client.ts      RouterClient (HTTP, retry)   scripts/         SSE harness (live)
+src/adapters/      openai.ts, anthropic.ts
+src/tools.ts       file tools + confinement     src/loop.ts      agent round driver
+src/repl.ts        REPL shell                   src/lineinput.ts raw-mode editor
+src/sessions.ts    transcripts
+src/markdown.ts    terminal markdown renderer
+```
+
+Live wire-shape verification:
+
+```bash
+node scripts/sse-harness.ts --model <id> --dialect openai|anthropic|auto [--tools] [--save test/fixtures/x.sse]
+```
+
+## Manual E2E checklist
+
+- [ ] `flash --check` green; `npm test` green; `npm run typecheck` clean
+- [ ] `/model` → arrow-key picker → streamed chat answers (markdown-rendered)
+- [ ] multi-tool task (create → edit → grep) exercising y / a / n approvals
+- [ ] Page Up/Down scroll chat with input anchored, including mid-stream; mouse drag selects text
+- [ ] Ctrl+V queues a clipboard screenshot without submitting; Ctrl+X clears pending images
+- [ ] text Cmd+V still works; `/` palette has no image commands; `/help` opens shortcuts
+- [ ] `/clear` starts a fresh transcript; session files exist
+- [ ] type during streaming; Enter queues steering and leaves tool/result ordering valid
+- [ ] an unfinished draft survives a permission question and turn completion
+- [ ] Ctrl+C mid-stream prints `*[stopped]*` and restores any unapplied steering
+- [ ] `flash -p "hi"` one-shot; `echo "…" | flash` piped mode works
+- [ ] bad key exits with the 401 hint; `FLASHLITE_BASE_URL` pointing at a dead port
+      reports a network error, not a crash
+- [ ] `flash --debug` shows frame sizes and retry metadata without message content or credentials
+
+## Notes
+
+- **Zero runtime deps** — `src/` and `scripts/` use Node built-ins only.
+- **Never print an API key** — not even masked. Real keys live only in the local config.
+- Diagnostic logging never includes message content. Private transcripts live under
+  `~/.config/…/sessions/`; normal UI/one-shot output shows the requested answer.
+  `--debug` reports metadata only, never raw SSE payloads.