@giovannijecha/jecode 0.1.8 → 0.1.9

package/README.md

@@ -3,11 +3,7 @@
 </p>
 
 <p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/wordmark-light.svg">
-    <source media="(prefers-color-scheme: light)" srcset="docs/assets/brand/wordmark-dark.svg">
-    <img src="docs/assets/brand/wordmark-dark.svg" width="280" alt="Jecode">
-  </picture>
+  <img src="docs/assets/brand/wordmark-steel.svg" width="280" alt="Jecode">
 </p>
 
 <p align="center"><strong>Your code. Your loop.</strong></p>
@@ -175,11 +171,10 @@ Type **/** to open searchable command completion inside the composer.
 | /providers | Switch the provider for the next turn |
 | /models | Search the live model catalogue |
 | /credentials | Add, replace, inspect, or forget saved credentials |
-| /permissions | Review or revoke remembered session approvals |
-| /usage | Show normalized token usage |
-| /new | Start a clean in-memory conversation |
+| /permissions | Manage session tool access and remembered approvals |
+| /new | Start a clean conversation and reset session tool permissions |
 | /export | Save a timestamped Markdown transcript in the launch directory |
-| /help | Show commands and controls |
+| /help | Open a temporary keyboard reference in the composer dock |
 | /exit | Restore the terminal and exit |
 
 Useful controls:
@@ -196,7 +191,9 @@ Useful controls:
 The one-line footer keeps model, effort, and workspace on the left. Live work
 stays visible on the reasoning and tool rail; the right edge carries the
 interrupt hint, readiness guidance, and temporary feedback without polluting
-the transcript.
+the transcript. Slash commands never append content to the conversation or its
+Markdown export; **/help** closes with **Esc**, and token accounting remains
+internal to the active session.
 
 ## Configuration
 
@@ -241,8 +238,8 @@ untrusted data.
 
 - Tool paths are confined to the selected workspace. Writes reject symlink and
   junction components, then revalidate the boundary during atomic replacement.
-- Dangerous tools require approval unless the process was started with
-  **--auto-approve**.
+- Dangerous tools ask by default unless explicitly allowed for the session in
+  **/permissions** or the process started with **--auto-approve**.
 - Credential fields are masked and excluded from transcripts. Approved shell
   commands receive no credential-like environment variables, and recognized
   credential values are redacted before tool output reaches the model, screen,

package/dist/commands.js

@@ -4,33 +4,27 @@
 // without asking the provider what it has — but none of them ever sends a
 // message. Provider and credential interaction lives in provider-commands.ts;
 // this file keeps command discovery, dispatch, and local session operations.
-import { heading } from "./tui/picker.js";
-import { modelsCommand, providersCommand, setupCommand } from "./provider-commands.js";
+import { modelsCommand, providersCommand } from "./provider-commands.js";
 import { credentialsCommand } from "./credential-commands.js";
+import { permissionsCommand } from "./permission-command.js";
 import { effortCommand, settingsCommand } from "./settings-command.js";
-import { emptyUsage, formatTokens } from "./usage.js";
+import { emptyUsage } from "./usage.js";
 /**
  * The commands, declared once.
  *
- * `/help` and the completion menu both read this list, so a command cannot
- * exist in the switch below and be missing from the two places that tell the
- * user it exists.
- *
  * Deliberately short. `/settings` owns persistent defaults; the narrower
- * provider, model, effort, credential, and setup commands remain useful direct
- * paths into the same interactions.
+ * provider, model, effort, and credential commands remain useful direct paths
+ * into the same interactions.
  */
 export const COMMANDS = [
-    { name: "help", blurb: "this list" },
+    { name: "help", blurb: "show keyboard controls" },
     { name: "exit", blurb: "exit and restore the terminal" },
-    { name: "new", blurb: "start a clean in-memory session" },
-    { name: "usage", blurb: "show token usage for this session" },
+    { name: "new", blurb: "start clean and reset tool permissions" },
     { name: "export", blurb: "save this transcript as Markdown" },
-    { name: "permissions", blurb: "review or revoke remembered approvals" },
+    { name: "permissions", blurb: "manage session tool access" },
     { name: "settings", blurb: "change and save jecode defaults" },
     { name: "effort", blurb: "set the reasoning effort" },
     { name: "credentials", blurb: "inspect, replace, or forget API keys" },
-    { name: "setup", blurb: "make the current provider ready" },
     { name: "models", blurb: "pick a model, from what the provider offers" },
     { name: "providers", blurb: "pick a provider" },
 ];
@@ -38,7 +32,16 @@ export async function handleCommand(line, session, host) {
     const [name] = line.slice(1).trim().split(/\s+/);
     switch (name) {
         case "help":
-            host.emit(help());
+            if (host.showHelp === undefined) {
+                host.emit({
+                    kind: "notice",
+                    text: "interactive help needs the TUI · run jecode --help for startup options",
+                    tone: "info",
+                });
+            }
+            else {
+                await host.showHelp();
+            }
             return "handled";
         case "exit":
             return "exit";
@@ -46,10 +49,7 @@ export async function handleCommand(line, session, host) {
             session.history.length = 0;
             session.usage = emptyUsage();
             host.reset?.();
-            host.emit({ kind: "notice", text: "new session · history, usage, and approvals cleared", tone: "info" });
-            return "handled";
-        case "usage":
-            host.emit(usage(session));
+            host.emit({ kind: "notice", text: "new session", tone: "info" });
             return "handled";
         case "export":
             if (host.exportTranscript === undefined) {
@@ -57,11 +57,11 @@ export async function handleCommand(line, session, host) {
             }
             else {
                 const saved = await host.exportTranscript();
-                host.emit({ kind: "notice", text: `transcript saved to ${saved}`, tone: "info" });
+                host.emit({ kind: "notice", text: `saved · ${saved}`, tone: "info" });
             }
             return "handled";
         case "permissions":
-            await permissions(session, host);
+            await permissionsCommand(session, host);
             return "handled";
         case "settings":
             await settingsCommand(session, host);
@@ -72,9 +72,6 @@ export async function handleCommand(line, session, host) {
         case "credentials":
             await credentialsCommand(session, host);
             return "handled";
-        case "setup":
-            await setupCommand(session, host);
-            return "handled";
         case "models":
             await modelsCommand(session, host);
             return "handled";
@@ -82,89 +79,17 @@ export async function handleCommand(line, session, host) {
             await providersCommand(session, host);
             return "handled";
         default:
-            host.emit({ kind: "notice", text: `unknown command /${name ?? ""} — try /help`, tone: "warn" });
+            host.emit({
+                kind: "notice",
+                text: `unknown command /${name ?? ""} · type / to browse commands`,
+                tone: "warn",
+            });
             return "handled";
     }
 }
-function usage(session) {
-    const value = session.usage;
-    const rows = [
-        `  requests${String(value.requests).padStart(18)}`,
-        `  latest context${formatTokens(value.lastInputTokens).padStart(12)}`,
-        `  input${formatTokens(value.inputTokens).padStart(21)}`,
-        `  output${formatTokens(value.outputTokens).padStart(20)}`,
-    ];
-    if (value.cachedInputTokens > 0)
-        rows.push(`  cached input${formatTokens(value.cachedInputTokens).padStart(14)}`);
-    if (value.cacheWriteInputTokens > 0) {
-        rows.push(`  cache writes${formatTokens(value.cacheWriteInputTokens).padStart(14)}`);
-    }
-    if (value.reasoningTokens > 0)
-        rows.push(`  reasoning${formatTokens(value.reasoningTokens).padStart(17)}`);
-    return { kind: "list", items: rows.map((text) => ({ text, dim: false })) };
-}
-async function permissions(session, host) {
-    const choose = chooser(host);
-    if (choose === undefined)
-        return;
-    if (session.config.autoApprove) {
-        host.emit({
-            kind: "notice",
-            text: "--auto-approve is active · every dangerous call is allowed for this process",
-            tone: "warn",
-        });
-    }
-    const entries = host.permissions?.() ?? [];
-    if (entries.length === 0) {
-        host.emit({ kind: "notice", text: "no remembered session permissions", tone: "info" });
-        return;
-    }
-    const index = await choose({
-        title: heading("revoke permission", "applies only to this session", session.palette),
-        options: [
-            ...entries.map((entry) => ({ label: entry.label, hint: "revoke" })),
-            { label: "all remembered permissions", hint: "revoke all" },
-        ],
-        index: 0,
-    });
-    if (index === undefined)
-        return;
-    if (index === entries.length) {
-        host.revokePermission?.();
-        host.emit({ kind: "notice", text: "all remembered permissions revoked", tone: "info" });
-        return;
-    }
-    const entry = entries[index];
-    if (entry === undefined)
-        return;
-    host.revokePermission?.(entry.key);
-    host.emit({ kind: "notice", text: `revoked · ${entry.label}`, tone: "info" });
-}
 function chooser(host) {
     if (host.choose === undefined) {
         host.emit({ kind: "notice", text: "that command needs the screen", tone: "warn" });
     }
     return host.choose;
 }
-function help() {
-    const width = Math.max(...COMMANDS.map((c) => label(c).length));
-    return {
-        kind: "list",
-        items: [
-            ...COMMANDS.map((command) => ({
-                text: `  ${label(command).padEnd(width + 4)}${command.blurb}`,
-                dim: false,
-            })),
-            { text: "", dim: true },
-            { text: "  esc interrupts a running turn · ctrl+c exits", dim: true },
-            { text: "  wheel or pgup / pgdn scrolls · ctrl+l redraws", dim: true },
-            { text: "  ctrl+o expands the latest reasoning or tool details", dim: true },
-            { text: "  type in the model picker to filter · home/end jumps", dim: true },
-            { text: "  ↑↓ selects an open menu · tab completes · esc closes it", dim: true },
-            { text: "  enter selects or sends · alt+enter starts a new line", dim: true },
-        ],
-    };
-}
-function label(command) {
-    return `/${command.name}`;
-}

package/dist/credential-commands.js

@@ -1,4 +1,4 @@
-// Credential command flows shared by setup and provider selection.
+// Credential command flows shared by settings and provider selection.
 import { heading } from "./tui/picker.js";
 import { EMPTY } from "./tui/editor.js";
 import { PROVIDERS } from "./providers/index.js";
@@ -31,21 +31,20 @@ export async function askForKey(name, host, pal) {
     });
     if (index === 0) {
         hold(name, value);
-        host.emit({ kind: "notice", text: "credential available for this session", tone: "info" });
+        host.emit({ kind: "notice", text: "API key ready · this session", tone: "info" });
         return true;
     }
     if (index === 1) {
         try {
             await keep(name, value);
-            host.emit({ kind: "notice", text: `credential saved · ${storeLabel()}`, tone: "info" });
+            host.emit({ kind: "notice", text: "API key saved", tone: "info" });
             return true;
         }
         catch (error) {
-            host.emit({ kind: "notice", text: `could not save credential · ${error.message}`, tone: "error" });
+            host.emit({ kind: "notice", text: `could not save API key · ${error.message}`, tone: "error" });
             return false;
         }
     }
-    host.emit({ kind: "notice", text: "credential discarded", tone: "warn" });
     return false;
 }
 export async function credentialsCommand(session, host) {
@@ -70,7 +69,7 @@ export async function credentialsCommand(session, host) {
     if (source === "environment") {
         host.emit({
             kind: "notice",
-            text: `${name} comes from the environment · update it outside jecode and restart`,
+            text: `${name} comes from the environment · restart after changing it`,
             tone: "info",
         });
         if (hasSaved(name))
@@ -80,14 +79,13 @@ export async function credentialsCommand(session, host) {
     const actions = [
         { label: source === undefined ? "add credential" : "replace credential", key: "r" },
         ...(hasSaved(name) ? [{ label: "forget saved copy", hint: storeLabel(), key: "f" }] : []),
-        { label: "close", key: "c" },
     ];
     const action = await choose({
         title: heading(name, source ?? "missing", session.palette),
         options: actions,
         index: 0,
     });
-    if (action === undefined || action === actions.length - 1)
+    if (action === undefined)
         return;
     if (actions[action]?.key === "f") {
         await forget(name, host);
@@ -114,12 +112,12 @@ async function forget(name, host) {
         const removed = await forgetSaved(name);
         host.emit({
             kind: "notice",
-            text: removed ? "saved credential removed" : "no saved credential to remove",
+            text: removed ? "API key removed" : "no saved API key",
             tone: removed ? "info" : "warn",
         });
     }
     catch (error) {
-        host.emit({ kind: "notice", text: `could not forget: ${error.message}`, tone: "error" });
+        host.emit({ kind: "notice", text: `could not remove API key · ${error.message}`, tone: "error" });
     }
 }
 function chooser(host) {

package/dist/permission-command.js

@@ -0,0 +1,107 @@
+// The session-local permission control plane exposed through /permissions.
+import { heading } from "./tui/picker.js";
+export async function permissionsCommand(session, host) {
+    const choose = host.choose;
+    const control = host.permissions;
+    if (choose === undefined || control === undefined) {
+        host.emit({ kind: "notice", text: "permissions need the interactive screen", tone: "warn" });
+        return;
+    }
+    let selected = 0;
+    while (true) {
+        const tools = control.listTools();
+        const index = await choose(permissionsPicker(tools, session.palette, selected));
+        if (index === undefined)
+            return;
+        const tool = tools[index];
+        if (tool === undefined)
+            return;
+        selected = index;
+        await configureTool(tool, control, choose, session.palette);
+    }
+}
+export function permissionsPicker(tools, pal, index = 0) {
+    const launchOverride = tools.some((tool) => tool.locked);
+    return {
+        title: heading("permissions", launchOverride ? "session only · auto approve at launch" : "session only", pal),
+        description: "Changes apply now · /new resets them",
+        options: tools.map((tool) => ({ label: tool.name, hint: toolHint(tool) })),
+        index: Math.min(Math.max(0, index), Math.max(0, tools.length - 1)),
+    };
+}
+async function configureTool(tool, control, choose, pal) {
+    if (tool.locked) {
+        await choose({
+            title: heading(tool.name, "launch override", pal),
+            description: "Restart without --auto-approve to change this tool",
+            options: [{ label: "allow", hint: "locked for this process" }],
+            index: 0,
+        });
+        return;
+    }
+    const modes = tool.dangerous ? ["ask", "allow", "deny"] : ["allow", "deny"];
+    const grants = control.listGrants(tool.name);
+    const index = await choose({
+        title: heading(tool.name, tool.dangerous ? "dangerous tool" : "read-only tool", pal),
+        description: tool.dangerous
+            ? "Session only · ask is the safe default"
+            : "Session only · deny hides this tool from the model",
+        options: [
+            ...modes.map((mode) => ({ label: mode, hint: modeHint(mode, tool.dangerous) })),
+            ...(grants.length === 0
+                ? []
+                : [{ label: "remembered approvals", hint: String(grants.length) }]),
+        ],
+        index: Math.max(0, modes.indexOf(tool.mode)),
+    });
+    if (index === undefined)
+        return;
+    const mode = modes[index];
+    if (mode !== undefined) {
+        control.set(tool.name, mode);
+        return;
+    }
+    await reviewGrants(tool.name, control, choose, pal);
+}
+async function reviewGrants(tool, control, choose, pal) {
+    let selected = 0;
+    while (true) {
+        const grants = control.listGrants(tool);
+        if (grants.length === 0)
+            return;
+        const options = [
+            ...grants.map((grant) => ({ label: grant.label, hint: "revoke" })),
+            ...(grants.length > 1 ? [{ label: "all remembered approvals", hint: "revoke all" }] : []),
+        ];
+        const index = await choose({
+            title: heading("remembered", tool, pal),
+            description: "Allowed without asking · this session",
+            options,
+            index: Math.min(selected, options.length - 1),
+        });
+        if (index === undefined)
+            return;
+        if (index === grants.length) {
+            control.revokeTool(tool);
+            return;
+        }
+        const grant = grants[index];
+        if (grant === undefined)
+            return;
+        control.revoke(grant.key);
+        selected = index;
+    }
+}
+function toolHint(tool) {
+    const kind = tool.dangerous ? "" : " · read only";
+    const remembered = tool.remembered === 0 ? "" : ` · ${tool.remembered} remembered`;
+    const locked = tool.locked ? " · launch override" : "";
+    return `${tool.mode}${kind}${remembered}${locked}`;
+}
+function modeHint(mode, dangerous) {
+    if (mode === "deny")
+        return "hide from the model";
+    if (mode === "ask")
+        return "prompt when needed";
+    return dangerous ? "every call this session" : "offer to the model";
+}

package/dist/permissions.js

@@ -0,0 +1,113 @@
+// Session-local tool policies and remembered approval scopes.
+/** One permission control plane for one interactive process. */
+export function sessionPermissions(tools, autoApprove) {
+    const catalogue = [...tools];
+    const byName = new Map(catalogue.map((tool) => [tool.name, tool]));
+    const modes = new Map();
+    const grants = new Map();
+    const configured = (tool) => modes.get(tool.name) ?? defaultMode(tool);
+    const effective = (tool) => autoApprove && tool.dangerous ? "allow" : configured(tool);
+    const revokeTool = (name) => {
+        for (const [key, grant] of grants) {
+            if (grant.tools.includes(name))
+                grants.delete(key);
+        }
+    };
+    return {
+        listTools() {
+            return catalogue.map((tool) => ({
+                name: tool.name,
+                dangerous: tool.dangerous,
+                mode: effective(tool),
+                remembered: [...grants.values()].filter((grant) => grant.tools.includes(tool.name)).length,
+                locked: autoApprove && tool.dangerous,
+            }));
+        },
+        set(name, mode) {
+            const tool = byName.get(name);
+            if (tool === undefined || (autoApprove && tool.dangerous))
+                return false;
+            if (!tool.dangerous && mode === "ask")
+                return false;
+            if (configured(tool) === mode)
+                return true;
+            if (mode === defaultMode(tool))
+                modes.delete(name);
+            else
+                modes.set(name, mode);
+            revokeTool(name);
+            return true;
+        },
+        listGrants(name) {
+            return [...grants.values()].filter((grant) => name === undefined || grant.tools.includes(name));
+        },
+        revoke(key) {
+            grants.delete(key);
+        },
+        revokeTool,
+        reset() {
+            modes.clear();
+            grants.clear();
+        },
+        availableTools() {
+            return catalogue.filter((tool) => effective(tool) !== "deny");
+        },
+        approved(call) {
+            const tool = byName.get(call.name);
+            if (tool === undefined)
+                return false;
+            const mode = effective(tool);
+            if (mode === "allow")
+                return true;
+            if (mode === "deny")
+                return false;
+            return grants.has(scopeFor(call).key);
+        },
+        remember(call) {
+            const tool = byName.get(call.name);
+            if (tool === undefined || effective(tool) !== "ask")
+                return;
+            const scope = scopeFor(call);
+            grants.set(scope.key, { key: scope.key, tools: grantTools(call), label: scope.summary });
+        },
+    };
+}
+/** The narrow permission represented by "for the session" in an approval. */
+export function scopeFor(call) {
+    const path = typeof call.input.path === "string" ? call.input.path : undefined;
+    if ((call.name === "write_file" || call.name === "edit_file") && path !== undefined) {
+        return { key: `file\0${path}`, label: `changes to ${path}`, summary: `file changes · ${path}` };
+    }
+    const command = typeof call.input.command === "string" ? call.input.command : undefined;
+    if (call.name === "run_command" && command !== undefined) {
+        return { key: `command\0${command}`, label: "this exact command", summary: `command · ${command}` };
+    }
+    return {
+        key: `${call.name}\0${stable(call.input)}`,
+        label: "this exact call",
+        summary: `${call.name} · ${target(call.input)}`,
+    };
+}
+function defaultMode(tool) {
+    return tool.dangerous ? "ask" : "allow";
+}
+function grantTools(call) {
+    return call.name === "write_file" || call.name === "edit_file"
+        ? ["edit_file", "write_file"]
+        : [call.name];
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stable(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function target(input) {
+    const value = input.path ?? input.command;
+    return typeof value === "string" ? value : stable(input);
+}

package/dist/provider-commands.js

@@ -1,4 +1,4 @@
-// Provider, model, and setup command flows.
+// Provider and model command flows.
 import { heading } from "./tui/picker.js";
 import { PROVIDERS } from "./providers/index.js";
 import { readSettings } from "./settings.js";
@@ -10,7 +10,7 @@ import { providerFailure } from "./provider-errors.js";
  * Every provider is offered, including the ones that cannot run: the reason
  * one is unusable — the variable it wants, by name — is worth more on screen
  * than the row would be worth hidden. A blocked choice opens the same masked
- * credential flow used by setup and settings, and cancellation leaves the old choice.
+ * credential flow used by settings, and cancellation leaves the old choice.
  */
 export async function providersCommand(session, host, behavior = {}) {
     const choose = chooser(host);
@@ -93,7 +93,7 @@ export async function providersCommand(session, host, behavior = {}) {
     if (behavior.announce !== false) {
         host.emit({
             kind: "notice",
-            text: session.model === "" ? `${chosen.id} — pick a model with /models` : `${chosen.id} · ${session.model}`,
+            text: session.model === "" ? `provider · ${chosen.id} · pick a model` : `provider · ${chosen.id}`,
             tone: "info",
         });
     }
@@ -171,38 +171,10 @@ export async function modelsCommand(session, host, behavior = {}) {
         }
     }
     if (behavior.announce !== false) {
-        host.emit({ kind: "notice", text: `${provider.id} · ${chosen}`, tone: "info" });
+        host.emit({ kind: "notice", text: `model · ${chosen}`, tone: "info" });
     }
     return true;
 }
-/** Make the provider selected by flags/environment usable without leaving the TUI. */
-export async function setupCommand(session, host) {
-    const blocked = session.provider.blocked();
-    if (blocked !== undefined) {
-        if (!isCredentialBlocker(session.provider, blocked)) {
-            host.emit({ kind: "notice", text: blocked, tone: "error" });
-            return;
-        }
-        const accepted = await askForKey(session.provider.keyVar, host, session.palette);
-        if (!accepted || session.provider.blocked() !== undefined) {
-            host.emit({
-                kind: "notice",
-                text: `${providerName(session.provider.id)} still needs an API key · /setup`,
-                tone: "warn",
-            });
-            return;
-        }
-    }
-    if (session.model === "") {
-        await modelsCommand(session, host);
-        return;
-    }
-    host.emit({
-        kind: "notice",
-        text: `${session.provider.id} · ${session.model} · ${session.provider.location?.() ?? "cloud"} · ready`,
-        tone: "info",
-    });
-}
 /** The way to put a menu up, or nothing — and the reason, already said. */
 function chooser(host) {
     if (host.choose === undefined) {

package/dist/settings-command.js

@@ -25,7 +25,7 @@ export async function settingsCommand(session, host) {
         if (index === undefined)
             return;
         const action = items[index]?.action;
-        if (action === undefined || action === "close")
+        if (action === undefined)
             return;
         selected = index;
         switch (action) {
@@ -82,7 +82,6 @@ function settingsItems(values) {
             option: { label: "reduced motion", hint: values.reducedMotion ? "on" : "off" },
         },
         { action: "credentials", option: { label: "credentials", hint: "manage API keys" } },
-        { action: "close", option: { label: "close" } },
     ];
 }
 function settingsValues(session) {
@@ -187,7 +186,7 @@ async function persist(host, patch) {
         return true;
     }
     catch (error) {
-        host.emit({ kind: "notice", text: `could not save settings: ${error.message}`, tone: "error" });
+        host.emit({ kind: "notice", text: `could not save settings · ${error.message}`, tone: "error" });
         return false;
     }
 }

package/dist/tools/shell.js

@@ -8,7 +8,7 @@ const MAX_OUTPUT_CHARS = 30_000;
 export const runCommand = {
     name: "run_command",
     description: "Run a shell command starting in the workspace root and return its combined stdout " +
-        "and stderr. The shell is not a filesystem sandbox, so every call requires approval. Output is " +
+        "and stderr. The shell is not a filesystem sandbox, so calls ask for approval by default. Output is " +
         "truncated past 30000 characters.",
     dangerous: true,
     input: {

package/dist/transcript.js

@@ -25,9 +25,6 @@ export function transcriptMarkdown(blocks) {
             case "notice":
                 out.push(`> ${block.tone.toUpperCase()}: ${safeMultiline(block.text).replaceAll("\n", "\n> ")}`, "");
                 break;
-            case "list":
-                out.push(...block.items.map((item) => safeInline(item.text)), "");
-                break;
         }
     }
     while (out[out.length - 1] === "")

package/dist/tui/app-workflows.js

@@ -4,20 +4,24 @@ import { runTurn } from "../controller.js";
 import { updateSettings } from "../settings.js";
 import { saveTranscript } from "../transcript-export.js";
 import { recordUsage } from "../usage.js";
-import { answerAt, scopeFor } from "./approve.js";
+import { answerAt } from "./approve.js";
 import { controllerOptions, turnFailure } from "./session-view.js";
 import { transcribe } from "./turn.js";
 const WAITING = "Waiting";
 export function appWorkflows(options) {
-    const { session, state, allowed, feedback } = options;
+    const { session, state, permissions, feedback } = options;
     async function command(text) {
         const activity = options.startActivity("command", `Running ${text.split(/\s+/)[0]}`);
         if (activity === undefined)
             return;
         try {
             const outcome = await handleCommand(text, session, {
-                emit: options.commandOutput,
+                emit: options.commandNotice,
                 signal: activity.control.signal,
+                showHelp: () => new Promise((resolve) => {
+                    state.open = { help: true, settle: resolve };
+                    options.render();
+                }),
                 choose: (picker) => new Promise((resolve) => {
                     state.open = { picker, settle: resolve };
                     options.render();
@@ -33,19 +37,13 @@ export function appWorkflows(options) {
                 reset: () => {
                     state.blocks.splice(0);
                     state.past.length = 0;
-                    allowed.clear();
+                    permissions.reset();
                     state.scroll = 0;
                     state.follow = true;
                     state.unseen = 0;
                     state.lastMaxScroll = 0;
                 },
-                permissions: () => [...allowed].map(([key, label]) => ({ key, label })),
-                revokePermission: (key) => {
-                    if (key === undefined)
-                        allowed.clear();
-                    else
-                        allowed.delete(key);
-                },
+                permissions,
                 exportTranscript: () => saveTranscript(options.transcriptRoot, state.blocks),
                 saveSettings: async (patch) => {
                     await updateSettings(patch);
@@ -76,11 +74,8 @@ export function appWorkflows(options) {
             emit: options.emit,
             render: options.render,
             palette: session.palette,
-            approved: (call) => session.config.autoApprove || allowed.has(scopeFor(call).key),
-            remember: (call) => {
-                const scope = scopeFor(call);
-                allowed.set(scope.key, scope.summary);
-            },
+            approved: (call) => permissions.approved(call),
+            remember: (call) => permissions.remember(call),
             ask: (prompt, settle) => {
                 state.open = { picker: prompt, settle: (index) => settle(answerAt(index)) };
                 options.render();
@@ -92,7 +87,7 @@ export function appWorkflows(options) {
         });
         let finishReason;
         try {
-            await runTurn(session.history, controllerOptions(session), events, activity.control.signal);
+            await runTurn(session.history, controllerOptions(session, permissions.availableTools()), events, activity.control.signal);
         }
         catch (error) {
             const interrupted = activity.control.signal.aborted;

package/dist/tui/app.js

@@ -18,6 +18,7 @@ import { transcriptRenderer } from "./transcript-view.js";
 import { appState } from "./app-state.js";
 import { appInput } from "./app-input.js";
 import { appWorkflows } from "./app-workflows.js";
+import { sessionPermissions } from "../permissions.js";
 const FRAME_MS = 16;
 const SPIN_MS = 80;
 /** How long a lone escape waits to prove it is not the start of a sequence. */
@@ -29,9 +30,7 @@ export async function runApp(session, transcriptRoot, environment = {}) {
     const transcript = transcriptRenderer();
     const workspace = await workspaceLabel(session.config.root);
     const state = appState();
-    // Tools the user said "always" to. It lives for the window and dies with it:
-    // a permission granted once, in one conversation, is not a setting.
-    const allowed = new Map();
+    const permissions = sessionPermissions(session.tools, session.config.autoApprove);
     let closed;
     let frameTimer;
     let spinTimer;
@@ -100,12 +99,8 @@ export async function runApp(session, transcriptRoot, environment = {}) {
         else
             state.unseen++;
     };
-    const commandOutput = (block) => {
-        const next = commandFeedback(block);
-        if (next === undefined)
-            emit(block);
-        else
-            feedback.show(next);
+    const commandNotice = (notice) => {
+        feedback.show(commandFeedback(notice));
     };
     const scrollBy = (amount) => {
         state.scroll = Math.max(0, state.scroll + amount);
@@ -177,10 +172,10 @@ export async function runApp(session, transcriptRoot, environment = {}) {
         session,
         transcriptRoot,
         state,
-        allowed,
+        permissions,
         feedback,
         emit,
-        commandOutput,
+        commandNotice,
         render,
         refreshSettings: () => {
             terminal.setReducedMotion(session.config.reducedMotion);

package/dist/tui/approve.js

@@ -4,28 +4,15 @@
 // worth more than a line of prose and a key to guess at. It is a menu — the
 // generic one — with an attention title and three answers written out.
 // Nothing is approved by a key nobody meant to press.
+import { scopeFor } from "../permissions.js";
+export { scopeFor };
 /**
- * The narrow permission represented by "always".
+ * The three answers, in the order a person actually wants them.
  *
- * File-changing tools share a grant for one displayed path. Shell grants are
- * tied to the exact command line. Unknown dangerous tools fall back to their
- * exact, stable input rather than silently inheriting a tool-wide grant.
+ * "Always" is scoped to the tool and to this session: it is a way to stop being
+ * asked about `write_file` twenty times in a row, not a setting that outlives
+ * the window it was granted in.
  */
-export function scopeFor(call) {
-    const path = typeof call.input.path === "string" ? call.input.path : undefined;
-    if ((call.name === "write_file" || call.name === "edit_file") && path !== undefined) {
-        return { key: `file\0${path}`, label: `changes to ${path}`, summary: `file changes · ${path}` };
-    }
-    const command = typeof call.input.command === "string" ? call.input.command : undefined;
-    if (call.name === "run_command" && command !== undefined) {
-        return { key: `command\0${command}`, label: "this exact command", summary: `command · ${command}` };
-    }
-    return {
-        key: `${call.name}\0${stable(call.input)}`,
-        label: "this exact call",
-        summary: `${call.name} · ${target(call.input)}`,
-    };
-}
 export function promptFor(call, target, pal) {
     const scope = scopeFor(call);
     const options = [
@@ -56,21 +43,6 @@ function scopeNoun(scope) {
         return "this command";
     return "this call";
 }
-function stable(value) {
-    if (Array.isArray(value))
-        return `[${value.map(stable).join(",")}]`;
-    if (value !== null && typeof value === "object") {
-        return `{${Object.entries(value)
-            .sort(([a], [b]) => a.localeCompare(b))
-            .map(([key, item]) => `${JSON.stringify(key)}:${stable(item)}`)
-            .join(",")}}`;
-    }
-    return JSON.stringify(value);
-}
-function target(input) {
-    const value = input.path ?? input.command;
-    return typeof value === "string" ? value : stable(input);
-}
 const ANSWERS = ["once", "always", "no"];
 /** What picking row `index` meant. Anything unrecognised refuses. */
 export function answerAt(index) {

package/dist/tui/blocks.js

@@ -1,6 +1,6 @@
 // Semantic transcript blocks routed to small, owned production components.
 import { renderAnswer, renderReasoning, renderUser } from "./components/messages.js";
-import { renderList, renderNotice } from "./components/misc.js";
+import { renderNotice } from "./components/misc.js";
 import { renderTool } from "./components/tool.js";
 export function render(block, width, pal, context = {}) {
     switch (block.kind) {
@@ -19,8 +19,6 @@ export function render(block, width, pal, context = {}) {
             });
         case "notice":
             return renderNotice(block, width, pal);
-        case "list":
-            return renderList(block, width, pal);
     }
 }
 export function renderAll(blocks, width, pal, context = {}) {

package/dist/tui/complete.js

@@ -1,9 +1,9 @@
 // Completing a slash command.
 //
-// A command the user cannot remember is a command that does not exist, and
-// `/help` only helps someone who already knows to ask. So the menu appears
-// while the line is being typed. Selection is state, not an edit: arrows move
-// through the list without rewriting what the user typed.
+// A command the user cannot remember is a command that does not exist. `/help`
+// owns keyboard controls; discovery belongs here, while the line is being
+// typed. Selection is state, not an edit: arrows move through the list without
+// rewriting what the user typed.
 import { COMMANDS } from "../commands.js";
 /**
  * The commands a half-typed line still matches.

package/dist/tui/components/menu.js

@@ -16,10 +16,11 @@ export function menuWindow(length, selected, visible) {
     return { first, last: Math.min(count, first + room) };
 }
 function renderEntry(entry, labelWidth, width, pal) {
-    // Colour terminals use one quiet selection band. In monochrome the arrow is
-    // structural rather than decorative, so selection remains unambiguous.
+    // Colour terminals use one quiet selection band and keep every label on the
+    // composer's content edge. Monochrome has no band, so it alone reserves a
+    // fixed arrow column to keep selection visible without shifting peer rows.
     const monochrome = !hasColor();
-    const selectedMark = entry.selected && monochrome ? "→ " : "  ";
+    const selectedMark = monochrome ? (entry.selected ? "→ " : "  ") : "";
     const fg = entry.selected ? pal.ink.bright : pal.ink.fg;
     const primary = [
         { text: selectedMark, fg: entry.selected ? pal.accent : fg },

package/dist/tui/components/misc.js

@@ -14,9 +14,3 @@ export function renderNotice(block, width, pal) {
         ], [], undefined, 1)),
     ];
 }
-export function renderList(block, width, pal) {
-    return [
-        "",
-        ...block.items.map((item) => row(width, [{ text: item.text, fg: item.dim ? pal.ink.muted : pal.ink.fg }], [], undefined, 1)),
-    ];
-}

package/dist/tui/components/status.js

@@ -16,15 +16,14 @@ export function renderStatus(info, pal) {
     return info.readiness === undefined ? [] : feedbackSegments(info.readiness, pal);
 }
 function feedbackSegments(feedback, pal) {
-    const mark = feedback.tone === "error" ? "×" : feedback.tone === "warn" ? "!" : "·";
-    const markColor = {
-        info: pal.accent,
-        warn: pal.ink.attention,
-        error: pal.ink.removed,
-    };
+    if (feedback.tone === "info") {
+        return [{ text: feedback.text, fg: pal.ink.muted }];
+    }
+    const mark = feedback.tone === "error" ? "×" : "!";
+    const markColor = feedback.tone === "error" ? pal.ink.removed : pal.ink.attention;
     const textColor = feedback.tone === "error" ? pal.ink.removed : pal.ink.muted;
     return [
-        { text: `${mark} `, fg: markColor[feedback.tone], bold: true },
+        { text: `${mark} `, fg: markColor, bold: true },
         { text: feedback.text, fg: textColor },
     ];
 }

package/dist/tui/feedback.js

@@ -1,5 +1,5 @@
 // Operational feedback belongs in the footer, not in the conversation.
-const INFO_MS = 2_800;
+const INFO_MS = 2_200;
 const WARN_MS = 4_200;
 const ERROR_MS = 6_000;
 /** Own replacement and expiry without leaking timers into the TUI shell. */
@@ -41,8 +41,6 @@ export function feedbackController(changed) {
 }
 /** Turn a command notice into one replaceable message in the footer status channel. */
 export function commandFeedback(block) {
-    if (block.kind !== "notice")
-        return undefined;
     return {
         text: block.text,
         tone: block.tone,

package/dist/tui/help.js

@@ -0,0 +1,29 @@
+// The compact, non-persistent keyboard reference shown inside the dock.
+import { row } from "../ui/render.js";
+import { textWidth } from "../ui/width.js";
+const CONTROL_WIDTH = 18;
+const CONTROLS = [
+    { key: "up / down", description: "move through menus or history" },
+    { key: "enter / tab", description: "select or send · complete" },
+    { key: "alt+enter", description: "insert a new line" },
+    { key: "esc", description: "close UI or interrupt work" },
+    { key: "ctrl+c", description: "interrupt work or exit" },
+    { key: "ctrl+o", description: "toggle reasoning or tool details" },
+    { key: "wheel / pgup/dn", description: "scroll the transcript" },
+    { key: "ctrl+l", description: "redraw the screen" },
+];
+export function panel(width, pal, maxRows = CONTROLS.length + 1) {
+    const heading = row(width, [
+        { text: "help  ", fg: pal.accent, bold: true },
+        { text: "keyboard controls", fg: pal.ink.fg },
+    ], [{ text: "esc close", fg: pal.ink.muted }]);
+    const controls = CONTROLS.map((control) => {
+        const gap = Math.max(2, CONTROL_WIDTH - textWidth(control.key));
+        return row(width, [
+            { text: control.key, fg: pal.ink.bright, bold: true },
+            { text: " ".repeat(gap) },
+            { text: control.description, fg: pal.ink.muted },
+        ]);
+    });
+    return [heading, ...controls].slice(0, Math.max(1, maxRows));
+}

package/dist/tui/modal.js

@@ -1,17 +1,23 @@
 // What can take the dock over, and how it draws.
 //
-// Two kinds, and the union exists so that everything between the command that
+// Three kinds, and the union exists so that everything between the command that
 // opens one and the frame that draws it — the view, the shell, the key handler
-// — speaks about "the thing that is open" rather than about a picker and a
-// field separately. A third kind would be added here and nowhere else.
+// — speaks about "the thing that is open" rather than about each interaction
+// separately.
 import * as picker from "./picker.js";
 import * as field from "./field.js";
+import * as help from "./help.js";
 export function panel(modal, width, pal, maxRows) {
-    return modal.kind === "pick"
-        ? picker.panel(modal.picker, width, pal, maxRows)
-        : maxRows === undefined
-            ? field.panel(modal.field, width, pal)
-            : field.panel(modal.field, width, pal).slice(0, maxRows);
+    switch (modal.kind) {
+        case "pick":
+            return picker.panel(modal.picker, width, pal, maxRows);
+        case "type":
+            return maxRows === undefined
+                ? field.panel(modal.field, width, pal)
+                : field.panel(modal.field, width, pal).slice(0, maxRows);
+        case "help":
+            return help.panel(width, pal, maxRows);
+    }
 }
 /**
  * Where the caret goes while this is open, if it goes anywhere.
@@ -20,7 +26,12 @@ export function panel(modal, width, pal, maxRows) {
  * query prompt and place the terminal caret at its real editing position.
  */
 export function caret(modal, width, maxRows) {
-    return modal.kind === "type"
-        ? field.caret(modal.field, width)
-        : picker.caret(modal.picker, width, maxRows);
+    switch (modal.kind) {
+        case "pick":
+            return picker.caret(modal.picker, width, maxRows);
+        case "type":
+            return field.caret(modal.field, width);
+        case "help":
+            return undefined;
+    }
 }

package/dist/tui/overlay.js

@@ -1,16 +1,23 @@
-// The modal interaction layer: one picker or one single-line field.
+// The modal interaction layer: a picker, a single-line field, or read-only help.
 import * as picker from "./picker.js";
 import { oneLine } from "./field.js";
 import { applyKey } from "./input.js";
 export function shown(open) {
     if (open === undefined)
         return undefined;
-    return "picker" in open ? { kind: "pick", picker: open.picker } : { kind: "type", field: open.field };
+    if ("picker" in open)
+        return { kind: "pick", picker: open.picker };
+    if ("field" in open)
+        return { kind: "type", field: open.field };
+    return { kind: "help" };
 }
 export function cancel(open) {
     if (open === undefined)
         return undefined;
-    open.settle(undefined);
+    if ("help" in open)
+        open.settle();
+    else
+        open.settle(undefined);
     return undefined;
 }
 export function handle(open, key) {
@@ -26,7 +33,11 @@ export function handle(open, key) {
         cancel(open);
         return {};
     }
-    return "picker" in open ? handlePicker(open, key) : handleField(open, key);
+    if ("picker" in open)
+        return handlePicker(open, key);
+    if ("field" in open)
+        return handleField(open, key);
+    return { open };
 }
 function handlePicker(open, key) {
     switch (key.name) {

package/dist/tui/picker.js

@@ -64,7 +64,7 @@ function layout(picker, width, pal, maxRows) {
     const options = colors === undefined
         ? []
         : shown.length === 0
-            ? [row(width, [{ text: "  no matches", fg: colors.ink.muted }])]
+            ? [row(width, [{ text: "no matches", fg: colors.ink.muted }])]
             : renderMenuRows(shown.map(({ option, index }) => ({
                 label: option.label,
                 hint: option.hint,

package/dist/tui/session-view.js

@@ -1,10 +1,10 @@
 // Small projections of the live session used by the shell and footer.
 import { credentialSource } from "../credentials.js";
 import { providerFailure } from "../provider-errors.js";
-export function controllerOptions(session) {
+export function controllerOptions(session, tools = session.tools) {
     return {
         provider: session.provider,
-        tools: session.tools,
+        tools,
         model: session.model,
         system: session.system,
         maxTokens: session.config.maxTokens,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giovannijecha/jecode",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "An owned coding agent with zero external runtime dependencies.",
   "license": "MIT",
   "repository": {