@dieulc/workflow 0.5.1 → 0.5.2

package/README.md

@@ -69,7 +69,9 @@ A profile is a **named combination of role model settings** — one `{provider,
 
 **Why**: mix models from different providers in one workflow (frontier planner + cheap explorer), keep one profile per provider to control budget per provider, run concurrent sessions on different providers to work around per-provider concurrency limits, and exploit cheaper starter plans across several providers.
 
-Profile config lives in `~/.pi/agent/profiles.json` v1 (user) with optional per-project override at `<cwd>/.pi/profiles.json` (per-profile replace, project wins). Names are case-insensitively unique, ≤ 40 chars, no whitespace (keep them CLI-addressable), and `none`/`auto` are reserved. A missing file is the normal empty state; a corrupt or wrong-version file is never rewritten (warning + in-memory empty config).
+Profile config lives in `~/.pi/agent/profiles.json` v1 (user) with optional per-project override at `<cwd>/.pi/profiles.json` (per-profile replace, project wins). Names are case-insensitively unique, ≤ 40 chars, no whitespace (keep them CLI-addressable), and `none`/`auto`/`off` are reserved (`off` is a `/profile use` deactivate keyword, so a profile can never be named it). A missing file is the normal empty state; a corrupt or wrong-version file is never rewritten (warning + in-memory empty config).
+
+**Argument completion** follows pi's full-argument contract (the same one pi's `/mcp` uses): accepting a suggestion replaces the entire typed argument text, so completing `/profile use Syn-␣` inserts `/profile use Syn-Deepseek-…` with the subcommand intact — it never collapses to `/profile <name>`. The dropdown closes (and the first Enter submits) once the typed token is already an exact, unique match. This applies positionally to `/profile` (`use|edit|show|delete|rename <old>|default <name> [global|project]`), `/commit-policy` (`never|ask|allow [global|project]`) and `/role` (`set <role> <provider/model> [thinking]`, `use <role|auto>`, `remove <name>`).
 
 ## Review Mode
 

package/commit-policy.ts

@@ -23,6 +23,8 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import type { ArgumentCompletion } from "./utils.ts";
+import { joinArgumentValue, suppressExactArgumentMatch } from "./utils.ts";
 
 /** Pi's project config directory. Mirrors WORKFLOW_CONFIG_DIR without importing review.ts (which pulls provider modules). */
 export const COMMIT_CONFIG_DIR = ".pi";
@@ -526,3 +528,104 @@ export function writeCommitPolicyConfig(
     };
   }
 }
+
+// ── Argument completions (/commit-policy) ────────────────────────────
+
+/** One /commit-policy subcommand with its usage hint. */
+const COMMIT_POLICY_SUBS: readonly {
+  name: string;
+  label: string;
+  description: string;
+}[] = [
+  {
+    name: "never",
+    label: "never",
+    description: "agent cannot git add/commit/push — you commit (or /commit)",
+  },
+  {
+    name: "ask",
+    label: "ask",
+    description: "agent may commit; each git commit/push asks first",
+  },
+  {
+    name: "allow",
+    label: "allow",
+    description: "agent may commit freely (per-step during plan execution)",
+  },
+];
+
+const COMMIT_POLICY_SCOPES: readonly {
+  token: string;
+  description: string;
+}[] = [
+  { token: "global", description: "write to ~/.pi/agent/settings.json" },
+  { token: "project", description: "write to <cwd>/.pi/settings.json" },
+];
+
+/** commit-policy subcommands take an optional scope → trailing-space values. */
+const COMMIT_POLICY_MODE_TOKENS: ReadonlySet<string> = new Set([
+  "never",
+  "ask",
+  "allow",
+]);
+
+/**
+ * Argument completions for `/commit-policy` (pure; unit-tested in
+ * commit-policy.test.ts).
+ *
+ * Follows the pi-tui full-argument contract (see `joinArgumentValue` and the
+ * /mcp extension): the first token completes a mode, the second token
+ * completes the write scope, and every returned `value` is the complete
+ * replacement for the typed argument text (`"ask project"`, never
+ * `"project"`). Returns null when nothing useful can be offered, including
+ * when the typed token is already an exact unique match (exact-match
+ * suppression — the dropdown closes so the first Enter submits).
+ */
+export function commitPolicyArgumentCompletions(
+  argumentPrefix: string,
+): ArgumentCompletion[] | null {
+  const raw = String(argumentPrefix ?? "");
+  const join = (token: string) => joinArgumentValue(raw, token);
+
+  // ── Subcommand position: no whitespace typed yet ────────────────────
+  if (!raw.trim() || !/\s/.test(raw)) {
+    const lower = raw.trim().toLowerCase();
+    const matching = COMMIT_POLICY_SUBS.filter((s) =>
+      s.name.startsWith(lower),
+    );
+    if (matching.length === 0) return null;
+    return matching.map((s) => ({
+      value: `${s.name} `,
+      label: s.label,
+      description: s.description,
+    }));
+  }
+
+  // ── Argument position: mode already committed → complete the scope ──
+  const tokens = raw.trim().split(/\s+/).filter(Boolean);
+  const mode = (tokens[0] ?? "").toLowerCase();
+  if (!COMMIT_POLICY_MODE_TOKENS.has(mode)) return null;
+  const endsWithWs = /\s$/.test(raw);
+  const partial = endsWithWs ? "" : (tokens[tokens.length - 1] ?? "");
+  const items: ArgumentCompletion[] = COMMIT_POLICY_SCOPES.flatMap((s) =>
+    s.token.startsWith(partial.toLowerCase())
+      ? [
+          {
+            value: join(s.token),
+            label: s.token,
+            description: s.description,
+          },
+        ]
+      : [],
+  );
+  if (items.length === 0) return null;
+  if (
+    suppressExactArgumentMatch(
+      items.map((i) => i.label),
+      partial,
+    )
+  ) {
+    return null;
+  }
+  return items;
+}

package/index.ts

@@ -94,6 +94,7 @@ import {
   COMMIT_FLOW_TTL_MS,
   armCommitAuthorization,
   commitConfigPaths,
+  commitPolicyArgumentCompletions,
   decideCommitGate,
   describeCommitPolicyMode,
   isAuthorizationActive,
@@ -122,6 +123,7 @@ import {
   defaultRoleConfig,
   loadRoleConfigDetailed,
   rolesFingerprint,
+  roleArgumentCompletions,
   saveRoleConfig,
   getRole,
   formatRolesForDisplay,
@@ -145,6 +147,7 @@ import {
   getProfile,
   formatProfilesForDisplay,
   describeProfile,
+  profileArgumentCompletions,
   validateProfileName,
   applyProfileOverlay,
   missingProfileRoles,
@@ -1587,39 +1590,11 @@ export default function workflowExtension(pi: ExtensionAPI) {
       );
       updateStatus(ctx as any);
     },
-    getArgumentCompletions: (prefix: string) => {
-      const flags = [
-        {
-          value: "never",
-          label: "never",
-          description:
-            "agent cannot git add/commit/push — you commit (or /commit)",
-        },
-        {
-          value: "ask",
-          label: "ask",
-          description: "agent may commit; each git commit/push asks first",
-        },
-        {
-          value: "allow",
-          label: "allow",
-          description:
-            "agent may commit freely (per-step during plan execution)",
-        },
-        {
-          value: "global",
-          label: "global",
-          description: "write to ~/.pi/agent/settings.json",
-        },
-        {
-          value: "project",
-          label: "project",
-          description: "write to <cwd>/.pi/settings.json",
-        },
-      ];
-      const filtered = flags.filter((f) => f.value.startsWith(prefix));
-      return filtered.length ? filtered : null;
-    },
+    // pi-tui full-argument contract (see commitPolicyArgumentCompletions):
+    // modes first, then the write scope, with values that replace the whole
+    // typed argument text ("ask project", never bare "project").
+    getArgumentCompletions: (prefix: string) =>
+      commitPolicyArgumentCompletions(prefix),
   });
 
   pi.registerCommand("review-prompt", {
@@ -3042,6 +3017,21 @@ export default function workflowExtension(pi: ExtensionAPI) {
 
   pi.registerCommand("role", {
     description: "Configure one model + thinking per role — opens picker UI",
+    // pi-tui full-argument contract (see roleArgumentCompletions): positional
+    // set/use/remove completions whose values replace the whole typed
+    // argument text ("set planner <provider/model>"), never bare tokens.
+    getArgumentCompletions: (prefix: string) => {
+      // No ctx here — use the live session cwd so project-scope roles.json is
+      // honored, matching the handler's ensureRoleConfig(cwd) key.
+      ensureRoleConfig((currentSessionCtx as any)?.cwd);
+      const models = collectRoleCatalog(currentSessionCtx as any).all.map(
+        (e) => formatModelRef({ provider: e.provider, id: e.id } as RoleModel),
+      );
+      return roleArgumentCompletions(prefix, {
+        roleNames: roleConfig.roles.map((r) => r.name),
+        models,
+      });
+    },
     handler: async (args, ctx) => {
       const cwd = (ctx as any)?.cwd as string | undefined;
       ensureRoleConfig(cwd);
@@ -4553,90 +4543,31 @@ export default function workflowExtension(pi: ExtensionAPI) {
         return;
       }
 
-      // Bare profile name → show detail (mirrors /role <name>).
+      // Bare profile name → show detail (mirrors /role <name>). The hint
+      // matters: this branch is where the old completion bug dropped users
+      // who meant `/profile use <name>`.
       const named = getProfile(profilesConfig, sub);
       if (named) {
-        ctx.ui.notify(describeProfile(named), "info");
+        ctx.ui.notify(
+          `${describeProfile(named)}\n\nActivate it with /profile use ${named.name}.`,
+          "info",
+        );
         return;
       }
       ctx.ui.notify(PROFILE_USAGE, "info");
     },
+    // pi-tui contract: argument completions replace the ENTIRE typed argument
+    // text with item.value (see profileArgumentCompletions / utils.joinArgument
+    // Value). The old inline completer returned bare profile names, so
+    // accepting a suggestion rewrote "/profile use X" → "/profile X" and the
+    // command silently showed details instead of activating.
     getArgumentCompletions: (prefix: string) => {
-      ensureProfilesConfig();
-      const subs = [
-        { value: "list", label: "list", description: "show all profiles" },
-        {
-          value: "use",
-          label: "use <name|none>",
-          description: "activate/deactivate for this session",
-        },
-        {
-          value: "create",
-          label: "create <name>",
-          description: "create a profile (seeded from current models)",
-        },
-        {
-          value: "edit",
-          label: "edit <name>",
-          description: "open the tabbed model editor",
-        },
-        {
-          value: "rename",
-          label: "rename <old> <new>",
-          description: "rename a profile",
-        },
-        {
-          value: "delete",
-          label: "delete <name>",
-          description: "delete a profile",
-        },
-        {
-          value: "default",
-          label: "default [name|none] [global|project]",
-          description: "default profile for new sessions",
-        },
-        {
-          value: "show",
-          label: "show <name>",
-          description: "show one profile's models",
-        },
-      ];
-      const lower = String(prefix || "").toLowerCase();
-      if (lower.includes(" ")) {
-        // Completing an argument after a subcommand → profile names where relevant.
-        const cmd = lower.trim().split(/\s+/)[0];
-        const wantsNames =
-          cmd === "use" ||
-          cmd === "edit" ||
-          cmd === "delete" ||
-          cmd === "show" ||
-          cmd === "default";
-        if (!wantsNames) return null;
-        const last = lower.trim().split(/\s+/).pop() ?? "";
-        const names = profilesConfig.profiles
-          .filter((p) => p.name.toLowerCase().startsWith(last))
-          .map((p) => ({
-            value: p.name,
-            label: p.name,
-            description: p.description || undefined,
-          }));
-        return cmd === "use" || cmd === "default"
-          ? [
-              ...names,
-              { value: "none", label: "none", description: "no profile" },
-            ]
-          : names;
-      }
-      const matching = subs.filter((s) => s.value.startsWith(lower));
-      if (matching.length > 0) return matching;
-      const names = profilesConfig.profiles
-        .filter((p) => p.name.toLowerCase().startsWith(lower))
-        .map((p) => ({
-          value: p.name,
-          label: p.name,
-          description: p.description || undefined,
-        }));
-      return names.length ? names : null;
+      // The completion callback gets no ctx — use the live session cwd so
+      // project-scope profiles (<cwd>/.pi/profiles.json) are included and the
+      // profiles cache key matches the handler's (a cwd-less reload could
+      // otherwise deactivate an active project-scope profile).
+      ensureProfilesConfig((currentSessionCtx as any)?.cwd);
+      return profileArgumentCompletions(prefix, profilesConfig.profiles);
     },
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dieulc/workflow",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "type": "module",
   "private": false,
   "keywords": ["pi-package", "workflow", "plan-mode", "review-mode", "questionnaire", "rewind"],

package/profiles.ts

@@ -40,6 +40,8 @@ import {
   roleIcon,
 } from "./roles.ts";
 import { COMMIT_CONFIG_DIR, WORKFLOW_SETTINGS_KEY } from "./commit-policy.ts";
+import type { ArgumentCompletion } from "./utils.ts";
+import { joinArgumentValue, suppressExactArgumentMatch } from "./utils.ts";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -66,7 +68,7 @@ export const PROFILE_CONFIG_VERSION = 1;
 export const MAX_PROFILE_NAME_LENGTH = 40;
 
 /** Reserved words — they collide with `/profile use <name|none>` and `/role use` style keywords. */
-export const RESERVED_PROFILE_NAMES: readonly string[] = ["none", "auto"];
+export const RESERVED_PROFILE_NAMES: readonly string[] = ["none", "auto", "off"];
 
 /** Fallback thinking level when a sanitized model omits an invalid one. */
 const DEFAULT_THINKING: ThinkingLevel = "medium";
@@ -615,3 +617,208 @@ export function writeDefaultProfileSetting(
     };
   }
 }
+
+// ── Argument completions (/profile) ──────────────────────────────────
+
+/** Subcommands that take a profile-name argument (position 2). */
+const PROFILE_NAME_SUBS: ReadonlySet<string> = new Set([
+  "use",
+  "edit",
+  "show",
+  "delete",
+  "default",
+  "rename",
+]);
+
+/** Aliases the /profile handler accepts, mapped to their canonical subcommand. */
+const PROFILE_CMD_ALIASES: Readonly<Record<string, string>> = {
+  activate: "use",
+  config: "edit",
+  remove: "delete",
+  rm: "delete",
+  mv: "rename",
+  new: "create",
+  add: "create",
+};
+
+/** Write-scope descriptions for `/profile default <name> <scope>` completions. */
+const SCOPE_DESCRIPTIONS: Readonly<Record<string, string>> = {
+  global: "write to ~/.pi/agent/settings.json",
+  project: "write to <cwd>/.pi/settings.json",
+};
+
+interface ProfileSubMeta {
+  name: string;
+  /** Takes an argument → completion `value` carries a trailing space. */
+  takesArg: boolean;
+  label: string;
+  description: string;
+}
+
+const PROFILE_SUBS: readonly ProfileSubMeta[] = [
+  {
+    name: "list",
+    takesArg: false,
+    label: "list",
+    description: "show all profiles",
+  },
+  {
+    name: "use",
+    takesArg: true,
+    label: "use <name|none>",
+    description: "activate/deactivate for this session",
+  },
+  {
+    name: "create",
+    takesArg: true,
+    label: "create <name>",
+    description: "create a profile (seeded from current models)",
+  },
+  {
+    name: "edit",
+    takesArg: true,
+    label: "edit <name>",
+    description: "open the tabbed model editor",
+  },
+  {
+    name: "rename",
+    takesArg: true,
+    label: "rename <old> <new>",
+    description: "rename a profile",
+  },
+  {
+    name: "delete",
+    takesArg: true,
+    label: "delete <name>",
+    description: "delete a profile",
+  },
+  {
+    name: "default",
+    takesArg: true,
+    label: "default [name|none] [global|project]",
+    description: "default profile for new sessions",
+  },
+  {
+    name: "show",
+    takesArg: true,
+    label: "show <name>",
+    description: "show one profile's models",
+  },
+];
+
+/** Profile names matching a lowercased partial token, case-insensitively. */
+function profileNameMatches(
+  profiles: readonly Profile[],
+  partial: string,
+): Profile[] {
+  if (!partial) return [...profiles];
+  return profiles.filter((p) =>
+    p.name.toLowerCase().startsWith(partial.toLowerCase()),
+  );
+}
+
+function profileCompletions(
+  profiles: readonly Profile[],
+  join: (token: string) => string,
+): ArgumentCompletion[] {
+  return profiles.map((p) => ({
+    value: join(p.name),
+    label: p.name,
+    ...(p.description ? { description: p.description } : {}),
+  }));
+}
+
+/**
+ * Argument completions for `/profile` (pure; unit-tested in profiles.test.ts).
+ *
+ * `argumentPrefix` is the ENTIRE typed argument text after "/profile " (what
+ * pi's CombinedAutocompleteProvider passes). Per the pi-tui contract, every
+ * returned item's `value` is the complete replacement for that argument text
+ * (`joinArgumentValue`), never a bare token — accepting `"use Syn-De" →
+ * "Syn-…"` would otherwise drop the `use` subcommand (see the /mcp
+ * extension for the reference implementation).
+ *
+ * Returns null when there is nothing useful to offer (unknown subcommand,
+ * `rename <old> <new>` second arg, `create`, …) or when the typed token is
+ * already an exact, unique match (exact-match suppression → the dropdown
+ * closes and the first Enter submits the command).
+ */
+export function profileArgumentCompletions(
+  argumentPrefix: string,
+  profiles: readonly Profile[],
+): ArgumentCompletion[] | null {
+  const raw = String(argumentPrefix ?? "");
+  const join = (token: string) => joinArgumentValue(raw, token);
+
+  // ── Subcommand position: no whitespace typed yet ────────────────────
+  if (!raw.trim() || !/\s/.test(raw)) {
+    const lower = raw.trim().toLowerCase();
+    const matching = PROFILE_SUBS.filter((s) =>
+      s.name.startsWith(lower),
+    );
+    if (matching.length > 0) {
+      return matching.map((s) => ({
+        value: s.takesArg ? `${s.name} ` : s.name,
+        label: s.label,
+        description: s.description,
+      }));
+    }
+    // Bare profile name → `/profile <name>` shows detail (mirrors /role).
+    const names = profileNameMatches(profiles, lower);
+    if (names.length === 0) return null;
+    return profileCompletions(names, join);
+  }
+
+  // ── Argument position ────────────────────────────────────────────────
+  const tokens = raw.trim().split(/\s+/).filter(Boolean);
+  const head = tokens[0] ?? "";
+  const canonical = PROFILE_CMD_ALIASES[head.toLowerCase()] ?? head.toLowerCase();
+  const endsWithWs = /\s$/.test(raw);
+  const committedCount = endsWithWs ? tokens.length : tokens.length - 1;
+  const partial = endsWithWs ? "" : (tokens[tokens.length - 1] ?? "");
+
+  let items: ArgumentCompletion[] | null = null;
+
+  if (canonical === "default") {
+    if (committedCount <= 1) {
+      // Second token: profile name | none.
+      const names = profileNameMatches(profiles, partial);
+      const none: ArgumentCompletion[] =
+        "none".startsWith(partial.toLowerCase())
+          ? [{ value: join("none"), label: "none", description: "no profile" }]
+          : [];
+      items = [...profileCompletions(names, join), ...none];
+    } else {
+      // Third token: scope.
+      items = ["global", "project"].flatMap((s) =>
+        s.startsWith(partial.toLowerCase())
+          ? [
+              {
+                value: join(s),
+                label: s,
+                description: SCOPE_DESCRIPTIONS[s],
+              },
+            ]
+          : [],
+      );
+    }
+  } else if (canonical === "rename") {
+    // First arg: existing name; second arg (new name) is free text.
+    if (committedCount <= 1) {
+      items = profileCompletions(profileNameMatches(profiles, partial), join);
+    }
+  } else if (PROFILE_NAME_SUBS.has(canonical)) {
+    const names = profileNameMatches(profiles, partial);
+    const none: ArgumentCompletion[] =
+      canonical === "use" && "none".startsWith(partial.toLowerCase())
+        ? [{ value: join("none"), label: "none", description: "no profile" }]
+        : [];
+    items = [...profileCompletions(names, join), ...none];
+  }
+  // create|new|add (new name is free text), list, unknown → items stays null.
+
+  if (!items || items.length === 0) return null;
+  const candidateTokens = items.map((i) => i.label);
+  if (suppressExactArgumentMatch(candidateTokens, partial)) return null;
+  return items;
+}

package/roles.ts

@@ -13,6 +13,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ArgumentCompletion } from "./utils.ts";
+import {
+  joinArgumentValue,
+  suppressExactArgumentMatch,
+} from "./utils.ts";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -430,3 +435,140 @@ export function formatRolesForDisplay(config: RoleConfig): string {
   );
   return lines.join("\n");
 }
+
+// ── Argument completions (/role) ─────────────────────────────────────
+
+interface RoleSubMeta {
+  name: string;
+  /** Takes an argument → completion `value` carries a trailing space. */
+  takesArg: boolean;
+  label: string;
+  description: string;
+}
+
+const ROLE_SUBS: readonly RoleSubMeta[] = [
+  { name: "list", takesArg: false, label: "list", description: "show all roles" },
+  {
+    name: "show",
+    takesArg: false,
+    label: "show",
+    description: "show all roles (alias of list)",
+  },
+  {
+    name: "config",
+    takesArg: true,
+    label: "config",
+    description: "open the role config screen (picker)",
+  },
+  {
+    name: "set",
+    takesArg: true,
+    label: "set <role> <provider/model> [thinking]",
+    description: "configure one role's model",
+  },
+  {
+    name: "add",
+    takesArg: true,
+    label: "add <name> [provider/model] [thinking]",
+    description: "add a custom role",
+  },
+  {
+    name: "remove",
+    takesArg: true,
+    label: "remove <name>",
+    description: "remove a custom role",
+  },
+  {
+    name: "reset",
+    takesArg: false,
+    label: "reset",
+    description: "reset roles to defaults",
+  },
+  {
+    name: "use",
+    takesArg: true,
+    label: "use <role|auto>",
+    description: "activate one role for the whole workflow",
+  },
+];
+
+/**
+ * Argument completions for `/role` (pure; unit-tested in roles.test.ts).
+ *
+ * Follows the pi-tui full-argument contract (see `joinArgumentValue` and the
+ * /mcp extension): every returned `value` is the complete replacement for the
+ * typed argument text — `set planner opencode-go/muse-…`, never a bare token.
+ * Positional rules mirror the /role handler:
+ *   - `set` arg1 = existing role names, arg2 = model refs (`provider/id`,
+ *     null when `opts.models` is empty), arg3 = thinking levels;
+ *   - `use` = role names + `auto`;
+ *   - `remove` = role names;
+ *   - `add` arg1 is a NEW name → no completions.
+ * Returns null when nothing useful can be offered, including when the typed
+ * token is already an exact unique match (exact-match suppression — the
+ * dropdown closes so the first Enter submits).
+ */
+export function roleArgumentCompletions(
+  argumentPrefix: string,
+  opts: { roleNames: readonly string[]; models?: readonly string[] },
+): ArgumentCompletion[] | null {
+  const raw = String(argumentPrefix ?? "");
+  const join = (token: string) => joinArgumentValue(raw, token);
+
+  // ── Subcommand position: no whitespace typed yet ────────────────────
+  if (!raw.trim() || !/\s/.test(raw)) {
+    const lower = raw.trim().toLowerCase();
+    const matching = ROLE_SUBS.filter((s) => s.name.startsWith(lower));
+    if (matching.length === 0) return null;
+    return matching.map((s) => ({
+      value: s.takesArg ? `${s.name} ` : s.name,
+      label: s.label,
+      description: s.description,
+    }));
+  }
+
+  // ── Argument position ────────────────────────────────────────────────
+  const tokens = raw.trim().split(/\s+/).filter(Boolean);
+  const cmd = (tokens[0] ?? "").toLowerCase();
+  const endsWithWs = /\s$/.test(raw);
+  const committedCount = endsWithWs ? tokens.length : tokens.length - 1;
+  const partial = endsWithWs ? "" : (tokens[tokens.length - 1] ?? "");
+  const matchToken = (t: string) => t.toLowerCase().startsWith(partial.toLowerCase());
+
+  const roleNameItems = (): ArgumentCompletion[] =>
+    opts.roleNames.flatMap((n) =>
+      matchToken(n) ? [{ value: join(n), label: n }] : [],
+    );
+
+  let items: ArgumentCompletion[] | null = null;
+
+  if (cmd === "set") {
+    if (committedCount <= 1) {
+      items = roleNameItems();
+    } else if (committedCount === 2) {
+      items = (opts.models ?? []).flatMap((m) =>
+        matchToken(m) ? [{ value: join(m), label: m }] : [],
+      );
+    } else {
+      items = VALID_THINKING_LEVELS.flatMap((t) =>
+        matchToken(t) ? [{ value: join(t), label: t }] : [],
+      );
+    }
+  } else if (cmd === "use") {
+    items = [
+      ...roleNameItems(),
+      ...("auto".startsWith(partial.toLowerCase())
+        ? [{ value: join("auto"), label: "auto" }]
+        : []),
+    ];
+  } else if (cmd === "remove") {
+    items = roleNameItems();
+  }
+  // add (new name is free text), config, list/show, reset, unknown → null.
+
+  if (!items || items.length === 0) return null;
+  if (suppressExactArgumentMatch(items.map((i) => i.label), partial)) {
+    return null;
+  }
+  return items;
+}

package/utils.ts

@@ -1583,3 +1583,63 @@ export function renderReviewContextBlock(
   }
   return out;
 }
+
+// ── Slash-command argument completions (pi-tui contract) ─────────────
+//
+// `CombinedAutocompleteProvider.getSuggestions` (pi-tui dist/autocomplete.js)
+// passes `getArgumentCompletions(argumentText)` the ENTIRE typed argument
+// text after the command name and, on accept, `applyCompletion` replaces
+// that whole argument text with `item.value` (the slash-argument branch:
+// `newLine = beforePrefix + item.value`). So an argument-position item's
+// `value` must be the complete replacement — e.g. `"use <name>"`, never the
+// bare token. Pi's own /mcp extension follows this contract
+// (`value: `${action} ${name}``). `joinArgumentValue` is the single helper
+// that enforces it: it keeps every committed token and appends (or replaces
+// the last partial token with) `token`.
+
+/** One slash-command argument completion item (pi-tui `AutocompleteItem` shape). */
+export interface ArgumentCompletion {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+/**
+ * Build the full-argument replacement `value` for a completion token.
+ *
+ * `prefix` is the typed argument text so far. Tokens separated by whitespace
+ * are "committed"; if `prefix` ends with whitespace the user is starting a
+ * fresh token, so `token` is appended — otherwise it replaces the trailing
+ * partial token. Pure; never throws.
+ *
+ *   joinArgumentValue("use Syn-De", "Syn-Deepseek-v4.1-Flash-Planner")
+ *     → "use Syn-Deepseek-v4.1-Flash-Planner"
+ *   joinArgumentValue("use ", "none") → "use none"
+ *   joinArgumentValue("", "list")     → "list"
+ */
+export function joinArgumentValue(prefix: string, token: string): string {
+  const raw = String(prefix ?? "");
+  const endsWithWs = /\s$/.test(raw);
+  const parts = raw.trim().split(/\s+/).filter(Boolean);
+  const committed = endsWithWs ? parts : parts.slice(0, -1);
+  return [...committed, token].join(" ");
+}
+
+/**
+ * Exact-match suppression for slash-command argument completions: when the
+ * token being typed (`partial`, "" while the prefix ends with whitespace)
+ * already equals the ONLY remaining candidate, return true so the completer
+ * yields null — pi's editor then closes the dropdown and the FIRST Enter
+ * submits instead of being consumed by the completion-accept handler
+ * (editor.js `tui.select.confirm`). Pure.
+ */
+export function suppressExactArgumentMatch(
+  candidates: readonly string[],
+  partial: string,
+): boolean {
+  if (!partial) return false;
+  return (
+    candidates.length === 1 &&
+    candidates[0].toLowerCase() === partial.toLowerCase()
+  );
+}