@oh-my-pi/pi-tui 16.3.5 → 16.3.7

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [16.3.7] - 2026-07-05
+
+### Fixed
+
+- Fixed an issue where `@` file-reference tokens in slash-command arguments incorrectly triggered prompt-composer autocompletion when the command did not define argument completions.
+- Fixed a memory leak caused by unbounded map growth in the image budget cache.
+
+## [16.3.6] - 2026-07-04
+
+### Added
+
+- Added `Markdown.getLastRenderSettledRows()`: the rendered frozen-token-prefix row count of the most recent streaming render, exposed (hard-monotone per text lineage) for native-scrollback commit gating. Frozen-prefix code blocks now syntax-highlight during streaming renders so settled rows stay byte-stable across finalize.
+
+### Changed
+
+- Rewrote the native-scrollback commit law around a visual-record model: whatever scrolls above the viewport enters history exactly once, in order — nothing painted ever vanishes. `NativeScrollbackLiveRegion` is now a single method (`getNativeScrollbackLiveRegionStart`) reporting an exactness boundary: rows below it commit as exact audited bytes; rows above it commit as frozen visual snapshots that are audit-exempt while their source stays live and strict-verified exactly once when the boundary passes them (a divergence recommits the final content below the frozen fragment — duplication, never loss). `getNativeScrollbackCommitSafeEnd`/`getNativeScrollbackSnapshotSafeEnd` and the heuristic promotion machinery they fed are removed.
+- Simplified committed-prefix auditing to one hard-verified mark deriving three zones (verified/newly-final/frozen); a frame that shrinks below the committed row count re-bases at the first divergence against the recorded prefix so a collapsing live suffix never re-shows or re-commits already-recorded rows.
+
+### Fixed
+
+- Fixed live tool/eval preview boxes spraying duplicated stale copies into native scrollback mid-run: a still-live block's scrolled rows are now frozen visual snapshots that never re-anchor while it runs; at most one repair happens at finalize.
+- Fixed streamed content vanishing above the viewport mid-turn: scrolled-off rows always reach native scrollback (as exact bytes for declared-final content, as visual snapshots otherwise) instead of being deferred invisibly.
+
 ## [16.3.5] - 2026-07-04
 
 ### Fixed

package/dist/types/autocomplete.d.ts

@@ -19,6 +19,8 @@ export interface SlashCommand {
     aliases?: string[];
     description?: string;
     argumentHint?: string;
+    /** Whether the command consumes argument text after the command name. False means the full input stays normal prompt text once args are present. */
+    allowArgs?: boolean;
     /** Dynamic display-only description for slash-command autocomplete. Must be synchronous and side-effect free. */
     getAutocompleteDescription?: () => string | undefined;
     getArgumentCompletions?(argumentPrefix: string): Awaitable<AutocompleteItem[] | null>;

package/dist/types/components/box.d.ts

@@ -1,4 +1,4 @@
-import type { Component } from "../tui";
+import type { Component } from "../tui.js";
 /** Box-drawing glyphs plus an optional colorizer for an outline drawn around a {@link Box}. */
 export interface BoxBorder {
     chars: {

package/dist/types/components/cancellable-loader.d.ts

@@ -1,4 +1,4 @@
-import { Loader } from "./loader";
+import { Loader } from "./loader.js";
 /**
  * Loader that can be cancelled with Escape.
  * Extends Loader with an AbortSignal for cancelling async operations.

package/dist/types/components/editor.d.ts

@@ -1,7 +1,7 @@
-import { type AutocompleteProvider } from "../autocomplete";
-import type { SymbolTheme } from "../symbols";
-import { type Component, type Focusable } from "../tui";
-import { type SelectListTheme } from "./select-list";
+import { type AutocompleteProvider } from "../autocomplete.js";
+import type { SymbolTheme } from "../symbols.js";
+import { type Component, type Focusable } from "../tui.js";
+import { type SelectListTheme } from "./select-list.js";
 export interface EditorTheme {
     borderColor: (str: string) => string;
     selectList: SelectListTheme;

package/dist/types/components/image.d.ts

@@ -1,5 +1,5 @@
-import { type ImageDimensions } from "../terminal-capabilities";
-import type { Component } from "../tui";
+import { type ImageDimensions } from "../terminal-capabilities.js";
+import type { Component } from "../tui.js";
 export interface ImageTheme {
     fallbackColor: (str: string) => string;
 }

package/dist/types/components/input.d.ts

@@ -1,4 +1,4 @@
-import { type Component, type Focusable } from "../tui";
+import { type Component, type Focusable } from "../tui.js";
 /**
  * Input component - single-line text input with horizontal scrolling
  */

package/dist/types/components/loader.d.ts

@@ -1,5 +1,5 @@
-import type { TUI } from "../tui";
-import { Text } from "./text";
+import type { TUI } from "../tui.js";
+import { Text } from "./text.js";
 type ColorFn = (str: string) => string;
 export type LoaderMessageColorFn = ColorFn & {
     readonly animated?: true;

package/dist/types/components/markdown.d.ts

@@ -1,5 +1,5 @@
-import type { SymbolTheme } from "../symbols";
-import type { Component } from "../tui";
+import type { SymbolTheme } from "../symbols.js";
+import type { Component } from "../tui.js";
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export declare function clearRenderCache(): void;
 /**
@@ -55,6 +55,16 @@ export declare class Markdown implements Component {
     invalidate(): void;
     get transientRenderCache(): boolean;
     set transientRenderCache(value: boolean);
+    /**
+     * Rows at the top of the most recent render() (top padding + rendered
+     * frozen-token prefix) whose bytes are settled: byte-stable at this
+     * width/theme for as long as the text keeps growing append-only. Hosts
+     * feed this to transcript commit gating (see the coding agent's
+     * `FinalizableBlock.getTranscriptBlockSettledRows`). 0 outside streaming
+     * (`transientRenderCache`) mode, after a text rewind (re-earned on the new
+     * lineage), and on cache-served non-streaming renders.
+     */
+    getLastRenderSettledRows(): number;
     render(width: number): readonly string[];
 }
 /**

package/dist/types/components/scroll-view.d.ts

@@ -1,5 +1,5 @@
-import type { Component } from "../tui";
-import { Ellipsis } from "../utils";
+import type { Component } from "../tui.js";
+import { Ellipsis } from "../utils.js";
 type ScrollbarMode = "auto" | "always" | "never";
 export interface ScrollViewTheme {
     track?: (text: string) => string;

package/dist/types/components/select-list.d.ts

@@ -1,6 +1,6 @@
-import { type MouseRoutable, type SgrMouseEvent } from "../mouse";
-import type { SymbolTheme } from "../symbols";
-import type { Component } from "../tui";
+import { type MouseRoutable, type SgrMouseEvent } from "../mouse.js";
+import type { SymbolTheme } from "../symbols.js";
+import type { Component } from "../tui.js";
 export interface SelectItem {
     value: string;
     label: string;

package/dist/types/components/settings-list.d.ts

@@ -1,5 +1,5 @@
-import type { SgrMouseEvent } from "../mouse";
-import type { Component } from "../tui";
+import type { SgrMouseEvent } from "../mouse.js";
+import type { Component } from "../tui.js";
 export interface SettingItem {
     /** Unique identifier for this setting */
     id: string;

package/dist/types/components/spacer.d.ts

@@ -1,4 +1,4 @@
-import type { Component } from "../tui";
+import type { Component } from "../tui.js";
 /**
  * Spacer component that renders empty lines
  */

package/dist/types/components/tab-bar.d.ts

@@ -1,4 +1,4 @@
-import type { Component } from "../tui";
+import type { Component } from "../tui.js";
 /** Tab definition */
 export interface Tab {
     /** Unique identifier for the tab */

package/dist/types/components/text.d.ts

@@ -1,4 +1,4 @@
-import type { Component } from "../tui";
+import type { Component } from "../tui.js";
 /**
  * Text component - displays multi-line text with word wrapping
  */

package/dist/types/components/truncated-text.d.ts

@@ -1,4 +1,4 @@
-import type { Component } from "../tui";
+import type { Component } from "../tui.js";
 /**
  * Text component that truncates to fit viewport width
  */

package/dist/types/desktop-notify.d.ts

@@ -1,4 +1,4 @@
-import type { TerminalId, TerminalNotification } from "./terminal-capabilities";
+import type { TerminalId, TerminalNotification } from "./terminal-capabilities.js";
 /** Resolved notifier binary used to fan a notification out to D-Bus. */
 export type DesktopNotifierKind = "notify-send" | "gdbus";
 export interface DesktopNotifier {

package/dist/types/editor-component.d.ts

@@ -1,5 +1,5 @@
-import type { AutocompleteProvider } from "./autocomplete";
-import type { Component } from "./tui";
+import type { AutocompleteProvider } from "./autocomplete.js";
+import type { Component } from "./tui.js";
 /**
  * Interface for custom editor components.
  *

package/dist/types/index.d.ts

@@ -1,32 +1,32 @@
-export * from "./autocomplete";
-export * from "./components/box";
-export * from "./components/cancellable-loader";
-export * from "./components/editor";
-export * from "./components/image";
-export * from "./components/input";
-export * from "./components/loader";
-export * from "./components/markdown";
-export * from "./components/scroll-view";
-export * from "./components/select-list";
-export * from "./components/settings-list";
-export * from "./components/spacer";
-export * from "./components/tab-bar";
-export * from "./components/text";
-export * from "./components/truncated-text";
-export * from "./deccara";
-export * from "./desktop-notify";
-export type * from "./editor-component";
-export * from "./fuzzy";
-export * from "./keybindings";
-export * from "./keys";
-export * from "./kitty-graphics";
-export * from "./latex-block";
-export * from "./latex-to-unicode";
-export * from "./mouse";
-export * from "./stdin-buffer";
-export type * from "./symbols";
-export * from "./terminal";
-export * from "./terminal-capabilities";
-export * from "./ttyid";
-export * from "./tui";
-export * from "./utils";
+export * from "./autocomplete.js";
+export * from "./components/box.js";
+export * from "./components/cancellable-loader.js";
+export * from "./components/editor.js";
+export * from "./components/image.js";
+export * from "./components/input.js";
+export * from "./components/loader.js";
+export * from "./components/markdown.js";
+export * from "./components/scroll-view.js";
+export * from "./components/select-list.js";
+export * from "./components/settings-list.js";
+export * from "./components/spacer.js";
+export * from "./components/tab-bar.js";
+export * from "./components/text.js";
+export * from "./components/truncated-text.js";
+export * from "./deccara.js";
+export * from "./desktop-notify.js";
+export type * from "./editor-component.js";
+export * from "./fuzzy.js";
+export * from "./keybindings.js";
+export * from "./keys.js";
+export * from "./kitty-graphics.js";
+export * from "./latex-block.js";
+export * from "./latex-to-unicode.js";
+export * from "./mouse.js";
+export * from "./stdin-buffer.js";
+export type * from "./symbols.js";
+export * from "./terminal.js";
+export * from "./terminal-capabilities.js";
+export * from "./ttyid.js";
+export * from "./tui.js";
+export * from "./utils.js";

package/dist/types/keybindings.d.ts

@@ -1,4 +1,4 @@
-import { type KeyId } from "./keys";
+import { type KeyId } from "./keys.js";
 /**
  * Global keybinding registry.
  * Downstream packages can add keybindings via declaration merging.

package/dist/types/terminal-capabilities.d.ts

@@ -42,6 +42,12 @@ export declare class TerminalInfo {
 export declare function isInsideTmux(env?: NodeJS.ProcessEnv): boolean;
 /** Detect terminal multiplexers where scrollback clearing and height-change redraws are hostile. */
 export declare function isInsideTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether the agent process is running inside a Zellij session. Read fresh on
+ * each call (like {@link isInsideTmux}) so a session attached/detached mid-run
+ * is observed and tests can toggle `Bun.env.ZELLIJ` per case.
+ */
+export declare function isInsideZellij(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Wrap a control-sequence payload in tmux's DCS passthrough envelope. Each
  * ESC byte inside `payload` is doubled per tmux's escape rules. tmux strips

package/dist/types/terminal.d.ts

@@ -1,4 +1,4 @@
-import { type HangulCompatibilityJamoWidth } from "./utils";
+import { type HangulCompatibilityJamoWidth } from "./utils.js";
 export declare function resolveHangulCompatibilityJamoWidthFromTerminalIdentity(env?: NodeJS.ProcessEnv): HangulCompatibilityJamoWidth;
 /**
  * Split `data` into chunks whose encoded UTF-8 byte length is no greater than

package/dist/types/tui.d.ts

@@ -1,6 +1,6 @@
-import { ImageBudget } from "./components/image";
-import { type Terminal } from "./terminal";
-import { visibleWidth } from "./utils";
+import { ImageBudget } from "./components/image.js";
+import { type Terminal } from "./terminal.js";
+import { visibleWidth } from "./utils.js";
 type InputListenerResult = {
     consume?: boolean;
     data?: string;
@@ -76,45 +76,23 @@ export interface OverlayFocusOwner {
     ownsOverlayFocusTarget(component: Component): boolean;
 }
 /**
- * Component seam for append-only native-scrollback commits. A component that
- * renders a finalized prefix followed by a live/mutating suffix reports the
- * local line index where that suffix begins after each render. The engine
- * commits rows to native scrollback only up to that boundary; everything
- * below repaints in place inside the visible window and never enters history
- * until it finalizes.
+ * Component seam for append-only native-scrollback commits. A component whose
+ * rendered rows can still change reports, after each render, the local line
+ * index where that mutable suffix begins. Rows above the boundary are declared
+ * FINAL — byte-stable at the current width for the component's lifetime — and
+ * commit to native scrollback as exact, audited content. Rows at/after the
+ * boundary repaint in place inside the visible window; when they scroll above
+ * the window top they still commit — the tape records what was on screen —
+ * but as frozen visual snapshots that are permanently audit-exempt: later
+ * re-layout of their source never re-anchors or recommits them. A root that
+ * reports no seam commits everything that scrolls as final (shell semantics).
  *
- * `getNativeScrollbackCommitSafeEnd` optionally reports a *deeper* boundary
- * inside the live suffix: the line index up to which the live region is
- * append-only (earlier rows never re-layout — a streaming assistant message).
- * Rows in `[liveRegionStart, commitSafeEnd)` may commit even though they are
- * technically live, because they will never change. Without it, a single live
- * block that alone overflows the window would hold its scrolled-off head out
- * of history until it finalizes. Volatile live blocks (tool previews that
- * collapse) omit it. Defaults to `liveRegionStart` when absent; a root that
- * reports no seam at all commits everything that scrolls (shell semantics).
- * `getNativeScrollbackSnapshotSafeEnd` optionally reports a still deeper
- * boundary: the line index up to which the live region is *durable* — its rows
- * may still change bytes later (a streaming markdown table re-aligning its
- * columns every row), but their CURRENT snapshot is permanent content, so
- * dropping them when they scroll above the window is forbidden. Unlike
- * `commitSafeEnd` (byte-stable: offered rows are asserted never to re-layout and
- * stay under the committed-prefix audit), rows committed under the snapshot end
- * are audit-EXEMPT once they pass the window top — the engine appends their
- * scroll-off snapshot and never recommits them, so later layout drift becomes a
- * frozen stale row in history (duplication never loss) instead of either a
- * dropped row or an audit re-anchor spray. Provisional live blocks (collapsing
- * tool/edit previews whose head is a throwaway tail window) omit it. Defaults to
- * `commitSafeEnd ?? liveRegionStart` when absent.
- *
- * When several root children report a seam in the same frame, the topmost
- * one (and its commit-safe / snapshot-safe extension) defines the boundary:
- * commits are prefix-only, so everything below the first seam is already
- * excluded.
+ * When several root children report a seam in the same frame, the topmost one
+ * defines the boundary: exactness is prefix-only, so everything below the
+ * first seam is already excluded.
  */
 export interface NativeScrollbackLiveRegion {
     getNativeScrollbackLiveRegionStart(): number | undefined;
-    getNativeScrollbackCommitSafeEnd?(): number | undefined;
-    getNativeScrollbackSnapshotSafeEnd?(): number | undefined;
 }
 export interface NativeScrollbackCommittedRows {
     setNativeScrollbackCommittedRows(rows: number): void;
@@ -294,40 +272,34 @@ export declare function coalesceAdjacentSgr(line: string): string;
  * re-anchor the commit index when it does not. Returns the resync row index,
  * or -1 when no resync is needed.
  *
- * Audits the committed prefix [0, auditTo) EXCEPT the exempt window
- * [exemptFrom, exemptTo): rows in the window are durable snapshots (a streaming
- * table re-aligning its columns) that may drift legitimately, so their drift
- * never triggers a re-anchor. Rows below the window — including forced-overflow
- * rows committed only because they scrolled above the viewport under a
- * commit-unstable barrier — ARE audited.
- *
- * Two detectors run over the audited rows:
+ * Zones (verifiedTo ≤ finalTo ≤ prefix.length):
+ *   [0, verifiedTo)         VERIFIED exact rows — sampled with tolerance.
+ *   [verifiedTo, finalTo)   NEWLY-FINAL rows — frozen visual snapshots whose
+ *       source just became declared-final (the block finalized / a barrier
+ *       cleared). Hard-scanned in FULL with no tolerance: any content change
+ *       (a pending header settling, a preview replaced by its result, a tail
+ *       shifting up after a barrier removal) re-anchors so the final content
+ *       recommits below the frozen snapshot — duplication, never loss —
+ *       instead of being committed nowhere and painted nowhere.
+ *   [finalTo, prefix.length) FROZEN visual snapshots of still-live rows —
+ *       exempt: their drift is expected (a collapsing preview, a ticking
+ *       progress tree) and must never spray re-anchors mid-run.
  *
- * 1. Hard scan of the now-permanent forced suffix [exemptTo, permanentEnd):
- *    forced-overflow rows that THIS frame asserts are durable/permanent (index <
- *    permanentEnd — the barrier above them finalized or cleared, so durableBoundary
- *    rose past them). A content change there is real finalized content, so ANY
- *    mismatch re-anchors. Scanned in FULL, not sampled, so a single edit far above
- *    the commit boundary with an unchanged tail still re-anchors (duplication,
- *    never loss) instead of being committed nowhere and painted nowhere.
- * 2. Tail sample (only when the hard scan is clean): exploits the asymmetry
- *    between the two mutation classes — an in-place edit/restyle of a committed
- *    row disturbs only the touched rows (alignment below intact; the stale copy
- *    in history is the long-accepted artifact), while an insertion/deletion
- *    shifts EVERY row below it. So up to 8 non-blank rows within the last 24
- *    audited rows are compared SGR-stripped (theme changes stay quiet),
- *    tolerating a SINGLE non-hard mismatch (a legitimate one-row edit): aligned ⇒
- *    no resync; misaligned ⇒ resync at the first non-equivalent audited row. The
- *    tolerance keeps both an offscreen still-live barrier (a ticking spinner) and
- *    a no-seam in-place row edit from spraying duplicate snapshots every frame;
- *    the hard scan above is what forbids it from swallowing a finalized row.
+ * The verified zone's sampled check exploits the asymmetry between the two
+ * mutation classes: an in-place edit/restyle disturbs only the touched rows
+ * (alignment below stays intact; the stale copy in history is the accepted
+ * artifact), while an insertion/deletion shifts EVERY row below it. Up to 8
+ * non-blank rows within the last 24 verified rows are compared SGR-stripped
+ * (theme changes stay quiet), tolerating a SINGLE mismatch. The tolerance is
+ * load-bearing for roots that report NO seam: an animated row already in
+ * history would otherwise re-anchor on every glyph tick.
  *
  * Highly repetitive tails (identical filler rows) can mask a shift in the tail
  * sample, in which case the skipped rows are content-identical to the committed
  * ones — observationally harmless. Exported for the render-stress harness, whose
  * shadow commit ledger must mirror the engine's law exactly.
  */
-export declare function findCommittedPrefixResync(frame: readonly string[], prefix: readonly string[], auditTo?: number, exemptFrom?: number, exemptTo?: number, permanentEnd?: number): number;
+export declare function findCommittedPrefixResync(frame: readonly string[], prefix: readonly string[], verifiedTo?: number, finalTo?: number): number;
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "16.3.5",
+	"version": "16.3.7",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "16.3.5",
-		"@oh-my-pi/pi-utils": "16.3.5",
+		"@oh-my-pi/pi-natives": "16.3.7",
+		"@oh-my-pi/pi-utils": "16.3.7",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.5"
 	},

package/src/autocomplete.ts

@@ -182,6 +182,8 @@ export interface SlashCommand {
 	aliases?: string[];
 	description?: string;
 	argumentHint?: string;
+	/** Whether the command consumes argument text after the command name. False means the full input stays normal prompt text once args are present. */
+	allowArgs?: boolean;
 	/** Dynamic display-only description for slash-command autocomplete. Must be synchronous and side-effect free. */
 	getAutocompleteDescription?: () => string | undefined;
 	// Function to get argument completions for this command
@@ -387,44 +389,18 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 		const currentLine = lines[cursorLine] || "";
 		const textBeforeCursor = currentLine.slice(0, cursorCol);
 
-		// Check for @ file reference (fuzzy search) - must be after a delimiter or at start
-		const atPrefix = this.#extractAtPrefix(textBeforeCursor);
-		if (atPrefix) {
-			const { rawPrefix, isQuotedPrefix } = parsePathPrefix(atPrefix);
-			// Recursive fuzzy walks rooted outside the project (e.g. `@../`,
-			// `@~/`, `@/abs`) can be huge — a parent dir full of sibling
-			// projects blows past several seconds of latency. Outside cwd,
-			// fall back to plain prefix listing of the immediate directory
-			// (matches Claude Code's behavior). Inside cwd we keep the
-			// fuzzy-then-prefix flow.
-			if (rawPrefix.length > 0 && this.#isOutsideCwd(rawPrefix)) {
-				const items = await this.#getFileSuggestions(atPrefix);
-				if (items.length === 0) return null;
-				return { items, prefix: atPrefix };
-			}
-			const suggestions =
-				rawPrefix.length > 0
-					? await this.#getFuzzyFileSuggestions(rawPrefix, { isQuotedPrefix })
-					: await this.#getFileSuggestions("@");
-			if (suggestions.length === 0 && rawPrefix.length > 0) {
-				const fallback = await this.#getFileSuggestions(atPrefix);
-				if (fallback.length === 0) return null;
-				return { items: fallback, prefix: atPrefix };
-			}
-			if (suggestions.length === 0) return null;
-
-			return {
-				items: suggestions,
-				prefix: atPrefix,
-			};
-		}
-
 		const leadingSlashStart = findLeadingSlashCommandStart(textBeforeCursor);
 		const trailingSlashStart = findTrailingSlashCommandStart(textBeforeCursor);
 		const hasPromptTextBeforeTrailingSlash =
 			trailingSlashStart !== null &&
 			hasPromptTextBeforeSlash(lines, cursorLine, textBeforeCursor, trailingSlashStart);
-		const slashStart = hasPromptTextBeforeTrailingSlash ? trailingSlashStart : leadingSlashStart;
+		const hasPromptTextBeforeLeadingSlash =
+			leadingSlashStart !== null && hasPromptTextBeforeSlash(lines, cursorLine, textBeforeCursor, leadingSlashStart);
+		const slashStart = hasPromptTextBeforeTrailingSlash
+			? trailingSlashStart
+			: hasPromptTextBeforeLeadingSlash
+				? null
+				: leadingSlashStart;
 		if (slashStart !== null) {
 			const commandText = textBeforeCursor.slice(slashStart);
 			const spaceIndex = commandText.indexOf(" ");
@@ -453,26 +429,62 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 				// A mid-prompt slash token with no matching skill may still be an
 				// absolute path (`see /tmp`); fall through to file-path completion.
 			} else if (!isMidPromptSkillLookup) {
-				// Space found - complete command arguments
+				// Submitted slash commands own their argument text only when the
+				// matched command accepts args. No-arg slash-looking prompts such
+				// as `/settings @file` still fall through to prompt-composer
+				// completions because submit treats them as normal prompt text.
 				const commandName = commandText.slice(1, spaceIndex); // Command without "/"
 				const argumentText = commandText.slice(spaceIndex + 1); // Text after space
 
 				const command = this.#commands.find(cmd => commandMatchesNameOrAlias(cmd, commandName));
-				if (!command || !("getArgumentCompletions" in command) || !command.getArgumentCompletions) {
-					return null; // No argument completion for this command
-				}
+				if (command && (!("allowArgs" in command) || command.allowArgs !== false)) {
+					if (!("getArgumentCompletions" in command) || !command.getArgumentCompletions) {
+						return null; // No argument completion for this command
+					}
+
+					const argumentSuggestions = await command.getArgumentCompletions(argumentText);
+					if (!Array.isArray(argumentSuggestions) || argumentSuggestions.length === 0) {
+						return null;
+					}
 
-				const argumentSuggestions = await command.getArgumentCompletions(argumentText);
-				if (!Array.isArray(argumentSuggestions) || argumentSuggestions.length === 0) {
-					return null;
+					return {
+						items: argumentSuggestions,
+						prefix: argumentText,
+					};
 				}
+			}
+		}
 
-				return {
-					items: argumentSuggestions,
-					prefix: argumentText,
-				};
+		// Check for @ file reference (fuzzy search) - must be after a delimiter or at start
+		const atPrefix = this.#extractAtPrefix(textBeforeCursor);
+		if (atPrefix) {
+			const { rawPrefix, isQuotedPrefix } = parsePathPrefix(atPrefix);
+			// Recursive fuzzy walks rooted outside the project (e.g. `@../`,
+			// `@~/`, `@/abs`) can be huge — a parent dir full of sibling
+			// projects blows past several seconds of latency. Outside cwd,
+			// fall back to plain prefix listing of the immediate directory
+			// (matches Claude Code's behavior). Inside cwd we keep the
+			// fuzzy-then-prefix flow.
+			if (rawPrefix.length > 0 && this.#isOutsideCwd(rawPrefix)) {
+				const items = await this.#getFileSuggestions(atPrefix);
+				if (items.length === 0) return null;
+				return { items, prefix: atPrefix };
 			}
-			if (!isMidPromptSkillLookup) return null;
+			const suggestions =
+				rawPrefix.length > 0
+					? await this.#getFuzzyFileSuggestions(rawPrefix, { isQuotedPrefix })
+					: await this.#getFileSuggestions("@");
+			if (suggestions.length === 0 && rawPrefix.length > 0) {
+				const fallback = await this.#getFileSuggestions(atPrefix);
+				if (fallback.length === 0) return null;
+				return { items: fallback, prefix: atPrefix };
+			}
+			if (suggestions.length === 0) return null;
+
+			return {
+				items: suggestions,
+				prefix: atPrefix,
+			};
 		}
 
 		// Check for file paths - triggered by Tab or if we detect a path pattern