@namzu/cli 18.1.0 → 20.0.0

package/dist/tui/slashCommands.js

@@ -15,17 +15,18 @@
  * already carries. A command that had to compute its own answer would be a
  * second source for a fact the kernel already owns, and the two would drift.
  *
- * `/expand` is the same discipline with the split drawn one step earlier. The
+ * Ctrl+O's reprint is the same discipline with the split drawn one step earlier. The
  * lines it prints were captured when the tool ran and are held on the transcript
- * row, which this module cannot see and must not: it validates the argument and
- * hands App a `which`, and App — the only thing that knows what rows exist —
- * resolves it. Giving this module the transcript to search would put the answer
+ * row, which this module cannot see and must not: App — the only thing that knows
+ * what rows exist — resolves it. Giving this module the transcript to search
+ * would put the answer
  * to "does block 4 exist" in two places at once.
  */
 import { kernelHostCommands, } from '@namzu/sdk';
 import { renderConfigDebug } from '../config/debug.js';
-import { isPermissionMode } from '../permissions/mode.js';
-import { expandCommand } from '../user-commands/store.js';
+import { effectivePermissionMode, isPermissionMode, permissionModeDescription, permissionModeLabel, } from '../permissions/mode.js';
+import { readChangelog, renderReleaseNotes } from '../release-notes.js';
+import { ARGUMENTS_TOKEN, expandCommand } from '../user-commands/store.js';
 import { isCompletionArgument } from './login-prompt.js';
 function renameConversationAction(_ctx, args) {
     const text = args.join(' ').trim();
@@ -107,7 +108,7 @@ export class CommandNameCollisionError extends Error {
  * {@link CommandNameCollisionError} exists to prevent; naming each one here
  * keeps the refusal for every collision nobody decided about.
  */
-export const HOST_OWNED_COMMAND_NAMES = ['skills'];
+export const HOST_OWNED_COMMAND_NAMES = ['skills', 'agents', 'goal'];
 export function mergeHostCommands(descriptors, locals = CLI_LOCAL_COMMANDS) {
     const localNames = new Set(locals.map((c) => c.name));
     const owned = new Set(HOST_OWNED_COMMAND_NAMES);
@@ -121,6 +122,11 @@ export function mergeHostCommands(descriptors, locals = CLI_LOCAL_COMMANDS) {
         ...fromKernel.map((descriptor) => ({
             name: descriptor.name,
             description: descriptor.description,
+            help: {
+                // An arbitrary JSON Schema does not declare positional CLI syntax.
+                usage: [`/${descriptor.name}${descriptor.args ? ' [arguments]' : ''}`],
+                ...(descriptor.hint ? { details: [descriptor.hint] } : {}),
+            },
             action: (_ctx, args) => ({
                 kind: 'host-command',
                 name: descriptor.name,
@@ -187,6 +193,62 @@ export function parseSlash(line) {
         return null;
     return { name, args };
 }
+/** Help reads metadata only: even a mutating or unavailable command is safe to inspect. */
+function commandHelp(ctx, args) {
+    const name = args[0]?.replace(/^\//, '');
+    if (args.length !== 1 || !name) {
+        return {
+            kind: 'message',
+            role: 'system',
+            content: 'Usage: /help [command]. For example: /help permissions.',
+        };
+    }
+    const command = (ctx.builtins ?? CLI_LOCAL_COMMANDS).find((entry) => entry.name === name);
+    if (command) {
+        const reason = command.unavailable?.(ctx);
+        return {
+            kind: 'message',
+            role: 'system',
+            content: [
+                `/${command.name}`,
+                command.description,
+                '',
+                'Usage:',
+                ...(command.help?.usage ?? [`/${command.name}`]).map((usage) => `  ${usage}`),
+                ...(command.help?.details?.length ? ['', ...command.help.details] : []),
+                ...(reason ? ['', `Unavailable: ${reason}`] : []),
+            ].join('\n'),
+        };
+    }
+    const user = ctx.userCommands.find((entry) => entry.name === name);
+    if (user) {
+        const acceptsArguments = user.template.includes(ARGUMENTS_TOKEN);
+        return {
+            kind: 'message',
+            role: 'system',
+            content: [
+                `/${user.name}`,
+                user.description,
+                '',
+                ...(user.problem
+                    ? []
+                    : [
+                        'Usage:',
+                        `  /${user.name}${acceptsArguments ? ' [arguments]' : ''}`,
+                        '',
+                        'Running this command sends its saved prompt to the model.',
+                    ]),
+                `${user.source === 'project' ? 'Project command' : 'User command (all projects)'}: ${user.path}`,
+                ...(user.problem ? [`Unavailable: ${user.problem}`] : []),
+            ].join('\n'),
+        };
+    }
+    return {
+        kind: 'message',
+        role: 'system',
+        content: `Unknown command: /${name}. Use /help to browse available commands.`,
+    };
+}
 /**
  * The commands that are genuinely this host's.
  *
@@ -196,10 +258,61 @@ export function parseSlash(line) {
  * being restated in this file.
  */
 export const CLI_LOCAL_COMMANDS = [
+    {
+        name: 'settings',
+        description: 'View current settings and change model, reasoning or permissions.',
+        action: () => ({ kind: 'settings-picker' }),
+    },
+    {
+        name: 'agents',
+        description: 'Inspect delegated agents; /agents available lists configured agents.',
+        help: { usage: ['/agents [running|available]'] },
+        action: (_ctx, args) => args.length === 0 || (args.length === 1 && args[0] === 'running')
+            ? { kind: 'agent-cockpit' }
+            : args.length === 1 && args[0] === 'available'
+                ? { kind: 'host-command', name: 'agents', args: [] }
+                : { kind: 'message', role: 'system', content: 'Usage: /agents [running|available]' },
+    },
+    {
+        name: 'goal',
+        description: 'Manage this conversation’s goal and automatic continuation.',
+        help: {
+            usage: [
+                '/goal',
+                '/goal status',
+                '/goal set [objective]',
+                '/goal edit [objective]',
+                '/goal pause|resume|clear',
+            ],
+            details: [
+                'Set and edit open an editor when no objective is supplied. Direct /goal <objective> also creates a goal.',
+                'Creating or resuming a goal enables automatic work. Pausing or clearing stops future automatic turns.',
+            ],
+        },
+        action: (_ctx, args) => {
+            if (args.length === 0)
+                return { kind: 'goal-picker' };
+            if (args.length === 1 && args[0] === 'status') {
+                return { kind: 'host-command', name: 'goal', args: [] };
+            }
+            if (args.length === 1 && (args[0] === 'set' || args[0] === 'edit')) {
+                return { kind: 'goal-editor', edit: args[0] === 'edit' };
+            }
+            return { kind: 'host-command', name: 'goal', args };
+        },
+    },
     {
         name: 'help',
-        description: 'Choose and run an available slash command.',
-        action: (ctx) => {
+        description: 'Browse commands, or show usage with /help <command>.',
+        help: {
+            usage: ['/help', '/help <command>'],
+            details: [
+                'Without a name, opens the command menu. With a name, shows help without running the command.',
+            ],
+        },
+        action: (ctx, args) => {
+            if (args.length > 0)
+                return commandHelp(ctx, args);
             // Reads what this session OFFERS, not a module constant. A command the
             // kernel registered and `/help` did not list is a command nobody
             // discovers. Refused command files remain rows with their reason; App
@@ -212,6 +325,7 @@ export const CLI_LOCAL_COMMANDS = [
                         .map((command) => ({
                         name: command.name,
                         description: command.description,
+                        ...(command.unavailable?.(ctx) ? { problem: command.unavailable(ctx) } : {}),
                     })),
                     ...ctx.userCommands.map((command) => ({
                         name: command.name,
@@ -222,14 +336,12 @@ export const CLI_LOCAL_COMMANDS = [
             };
         },
     },
-    {
-        name: 'agent',
-        description: 'Compatibility alias for the automatic delegated-work panel.',
-        discoverable: false,
-        action: () => ({ kind: 'agent-cockpit' }),
-    },
     {
         name: 'feedback',
+        help: { usage: ['/feedback', '/feedback good|bad [note]'] },
+        unavailable: (ctx) => ctx.lastAssistantMessageId()
+            ? undefined
+            : 'Nothing to rate yet. Wait for an assistant answer.',
         description: 'Rate the last answer; choose good/bad or add an optional note.',
         action: (ctx, args) => {
             if (args.length === 0) {
@@ -282,73 +394,100 @@ export const CLI_LOCAL_COMMANDS = [
         action: () => ({ kind: 'archive-picker' }),
     },
     {
-        name: 'clear-screen',
-        description: 'Clear only the terminal transcript; keep this conversation context.',
-        action: () => ({ kind: 'clear-screen' }),
-    },
-    {
-        name: 'quit',
+        name: 'exit',
         description: 'Exit namzu.',
         action: () => ({ kind: 'exit' }),
     },
     {
-        name: 'exit',
-        description: 'Alias of /quit.',
-        action: () => ({ kind: 'exit' }),
+        name: 'rename',
+        help: { usage: ['/rename [name]', '/rename clear'] },
+        description: 'Rename this conversation; opens an editor when no name is supplied. /rename clear removes the saved name.',
+        action: renameConversationAction,
     },
     {
-        name: 'tools',
-        description: 'List tools the agent can call.',
-        action: (ctx) => {
-            // Asked now, not when the session was built. Some of these register
-            // during the first turn, so a list captured earlier is a list of what
-            // was callable then — and this command is asked in the present tense.
-            const tools = ctx.availableTools();
-            return {
-                kind: 'message',
-                role: 'system',
-                content: tools.length === 0
-                    ? 'No tools registered yet — the agent session may still be connecting.'
-                    : `Registered tools (${tools.length}):\n  ${tools.join('\n  ')}`,
-            };
-        },
+        name: 'fork',
+        description: 'Continue in a copy of this conversation, leaving the original where it is.',
+        action: () => ({ kind: 'fork' }),
     },
     {
-        name: 'remember',
-        description: 'Save a fact to durable memory: /remember <text>.',
-        action: (_ctx, args) => {
-            const text = args.join(' ').trim();
-            return text.length === 0
-                ? {
+        name: 'add-dir',
+        help: {
+            usage: ['/add-dir [path]'],
+            details: ['Without a path, lists added directories. Paths may contain spaces.'],
+        },
+        description: 'Let the file tools reach another directory this session: /add-dir <path>. Alone, list them.',
+        action: (ctx, args) => {
+            const path = args.join(' ').trim();
+            if (path.length === 0) {
+                const dirs = ctx.directories?.() ?? [];
+                return {
                     kind: 'message',
                     role: 'system',
-                    content: 'Usage: /remember <something to remember>',
-                }
-                : { kind: 'remember', text };
+                    content: dirs.length === 0
+                        ? 'No added directories. The file tools reach the working directory only. /add-dir <path> adds one for this session; `additionalDirectories` in the config file adds one for every session.'
+                        : `Added directories (reachable by absolute path, bound into the sandbox):\n${dirs.map((d) => `  ${d}`).join('\n')}`,
+                };
+            }
+            return { kind: 'add-dir', path };
         },
     },
     {
-        name: 'rename',
-        description: 'Rename this conversation; opens an editor when no name is supplied.',
-        action: renameConversationAction,
-    },
-    {
-        name: 'title',
-        description: 'Alias for /rename; /title clear removes the saved name.',
-        action: renameConversationAction,
-    },
-    {
-        name: 'fork',
-        description: 'Continue in a copy of this conversation, leaving the original where it is.',
-        action: () => ({ kind: 'fork' }),
+        name: 'restore',
+        help: {
+            usage: ['/restore [turn]'],
+            details: ['Run /restore to list checkpoints before choosing a turn to restore.'],
+        },
+        description: 'Put files back to before a turn: /restore lists the checkpoints, /restore N restores.',
+        action: (_ctx, args) => {
+            const raw = args[0]?.trim();
+            if (!raw)
+                return { kind: 'restore' };
+            const turn = Number.parseInt(raw, 10);
+            if (!Number.isInteger(turn) || turn < 1 || String(turn) !== raw) {
+                return {
+                    kind: 'message',
+                    role: 'system',
+                    content: `/restore takes a turn number from the list: /restore 3. Not: ${raw}`,
+                };
+            }
+            return { kind: 'restore', turn };
+        },
     },
     {
         name: 'memory',
-        description: 'Show what namzu remembers (USER.md + MEMORY.md).',
-        action: () => ({ kind: 'show-memory' }),
+        help: {
+            usage: ['/memory [show|list]', '/memory add <text>', '/memory --user add <text>'],
+            details: [
+                'Show and list read saved memory. Add saves a project note; --user saves a note for all projects.',
+                'Direct /memory <text> also saves a note. To save a reserved word as a note, use /memory add show.',
+            ],
+        },
+        description: 'Show curated memory, or save a fact with /memory add <text>. Use /memory --user add <text> for every project.',
+        action: (_ctx, args) => {
+            const user = args[0] === '--user';
+            const memoryArgs = user ? args.slice(1) : args;
+            const text = memoryArgs.join(' ').trim();
+            // Reserve standalone inspection words while retaining multiword facts.
+            if (text.length === 0 || ['show', 'list'].includes(text.toLowerCase())) {
+                return { kind: 'show-memory' };
+            }
+            if (memoryArgs[0]?.toLowerCase() === 'add') {
+                const fact = memoryArgs.slice(1).join(' ').trim();
+                if (fact.length === 0) {
+                    return {
+                        kind: 'message',
+                        role: 'system',
+                        content: 'Usage: /memory add <text> or /memory --user add <text>. /memory show displays saved memory.',
+                    };
+                }
+                return { kind: 'remember', text: fact, scope: user ? 'user' : 'project' };
+            }
+            return { kind: 'remember', text, scope: user ? 'user' : 'project' };
+        },
     },
     {
         name: 'skills',
+        help: { usage: ['/skills', '/skills list', '/skills <name>'] },
         description: 'Choose an available skill; use /skills list for the full roster.',
         action: (_ctx, args) => {
             const choice = args.join(' ').trim();
@@ -364,77 +503,33 @@ export const CLI_LOCAL_COMMANDS = [
         description: 'Resume a past conversation in this folder.',
         action: () => ({ kind: 'resume' }),
     },
-    {
-        name: 'mention',
-        description: 'Insert @ so a project file can be mentioned in the next prompt.',
-        action: () => ({ kind: 'composer-draft', text: '@' }),
-    },
-    {
-        name: 'expand',
-        description: 'Print a collapsed tool output in full: /expand [n].',
-        action: (_ctx, args) => {
-            const arg = args.join(' ').trim();
-            // Bare `/expand` means the most recent one. That is what a person types
-            // the moment output truncates in front of them, and making them read a
-            // number back off the screen first would be a toll on the common case.
-            if (arg.length === 0)
-                return { kind: 'expand', which: 'last' };
-            // Matched as the literal decimal a hint can print, and nothing else.
-            //
-            // `parseInt` would read `2nd` as 2 and expand a block the operator did
-            // not name. `Number` plus `Number.isInteger` fixes that one and still
-            // admits `0x10`, `1e2`, `+3` and `3.0` — four spellings no hint has
-            // ever shown, each of which turns a typo into a valid reference to
-            // some OTHER block. What this accepts is exactly what the screen can
-            // produce, which is the only set with no silently-wrong answer in it.
-            if (!/^[1-9][0-9]*$/.test(arg)) {
-                return {
-                    kind: 'message',
-                    role: 'system',
-                    content: 'Usage: /expand [n], where n is the number in the "… +N lines · /expand n" hint under a collapsed tool output. /expand on its own takes the most recent one.',
-                };
-            }
-            return { kind: 'expand', which: Number(arg) };
-        },
-    },
-    {
-        name: 'skill',
-        description: 'Alias for /skills; choose a skill or type its name.',
-        action: (_ctx, args) => {
-            const name = args.join(' ').trim();
-            return name.length === 0 ? { kind: 'skill-picker' } : { kind: 'load-skill', name };
-        },
-    },
-    {
-        name: 'provider',
-        description: 'Show the current provider + model.',
-        action: (ctx) => ({
-            kind: 'message',
-            role: 'system',
-            content: ctx.providerSummary === null
-                ? 'No provider configured. Run /model to pick one, or set an LLM env var (ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY) and restart namzu.'
-                : `Provider: ${ctx.providerSummary}${ctx.modelSummary ? `\nModel: ${ctx.modelSummary}` : ''}`,
-        }),
-    },
-    {
-        name: 'pwd',
-        description: 'Show the active working directory.',
-        action: (ctx) => ({ kind: 'message', role: 'system', content: ctx.cwd }),
-    },
     {
         name: 'model',
-        description: 'Re-open the provider picker to switch the primary provider.',
+        description: 'Choose a model for the current provider, or change providers.',
+        help: {
+            usage: ['/model'],
+            details: [
+                'Press p in the model picker to change providers. Normal selections are saved for future launches; temporary credentials keep the selection in this session.',
+            ],
+        },
         action: () => ({ kind: 'repick' }),
     },
     {
         name: 'login',
         description: 'Sign in with a Claude or Codex subscription.',
+        help: {
+            usage: ['/login', '/login <callback-address-or-code>'],
+            details: [
+                'Start sign-in with /login, then paste the callback address or code when requested.',
+            ],
+        },
         action: (_ctx, args) => isCompletionArgument(args)
             ? { kind: 'login', pasted: args.join(' ').trim() }
             : { kind: 'login' },
     },
     {
         name: 'logout',
+        help: { usage: ['/logout [claude|codex|all]'] },
         description: 'Remove a Namzu-owned subscription credential: /logout [claude|codex|all].',
         action: (_ctx, args) => {
             const target = args.join(' ').trim().toLowerCase();
@@ -456,15 +551,52 @@ export const CLI_LOCAL_COMMANDS = [
     },
     {
         name: 'cost',
-        description: 'Show tokens and spend for this run.',
+        help: { usage: ['/cost [details]'] },
+        description: 'Show usage and cost for the current or latest run.',
+        action: (ctx, args) => reportCommand('cost', args, (details) => renderCost(ctx.usage, ctx.compaction, details)),
+    },
+    {
+        name: 'jobs',
+        description: 'List background jobs started this session, running and ended.',
+        action: (ctx) => ({
+            kind: 'message',
+            role: 'system',
+            content: renderJobs(ctx.jobs()),
+        }),
+    },
+    {
+        name: 'release-notes',
+        help: { usage: ['/release-notes [version]'] },
+        description: 'Show what changed in the version that is running: /release-notes [version].',
+        action: (_ctx, args) => ({
+            kind: 'message',
+            role: 'system',
+            content: renderReleaseNotes(readChangelog(), args[0]?.trim() || undefined),
+        }),
+    },
+    {
+        name: 'hooks',
+        description: 'List the shell hooks this session runs, by event.',
         action: (ctx) => ({
             kind: 'message',
             role: 'system',
-            content: renderCost(ctx.usage),
+            content: renderHooks(ctx.hooks?.()),
         }),
     },
+    {
+        name: 'context',
+        help: { usage: ['/context [details]'] },
+        description: 'Show context usage and automatic cleanup.',
+        action: (ctx, args) => reportCommand('context', args, (details) => renderContext(ctx.usage, ctx.compaction, details)),
+    },
     {
         name: 'review',
+        help: {
+            usage: ['/review [instructions]'],
+            details: [
+                'Without instructions, opens the review target menu. Starting a review uses the selected model.',
+            ],
+        },
         description: 'Choose a review target, or provide custom instructions: /review [instructions].',
         action: (_ctx, args) => {
             const instructions = args.join(' ').trim();
@@ -473,12 +605,9 @@ export const CLI_LOCAL_COMMANDS = [
     },
     {
         name: 'mcp',
-        description: 'Show current tool-server connections, tools, and failures.',
-        action: (ctx) => ({
-            kind: 'message',
-            role: 'system',
-            content: renderMcp(ctx.mcp()),
-        }),
+        help: { usage: ['/mcp [tools|details]'] },
+        description: 'Show connected tool servers and connection problems.',
+        action: (ctx, args) => reportCommand('mcp', args, (details) => renderMcp(ctx.mcp(), details), 'tools'),
     },
     {
         name: 'diff',
@@ -488,6 +617,10 @@ export const CLI_LOCAL_COMMANDS = [
     {
         name: 'compact',
         description: 'Summarise the older half of this conversation to free up context.',
+        help: {
+            usage: ['/compact'],
+            details: ['Compaction uses a model call to summarise older context.'],
+        },
         action: () => ({ kind: 'compact' }),
     },
     {
@@ -497,6 +630,7 @@ export const CLI_LOCAL_COMMANDS = [
     },
     {
         name: 'raw',
+        help: { usage: ['/raw [on|off]'] },
         description: 'Toggle copy-friendly plain transcript rendering: /raw [on|off].',
         action: (_ctx, args) => {
             const choice = args.join(' ').trim().toLowerCase();
@@ -515,6 +649,12 @@ export const CLI_LOCAL_COMMANDS = [
     },
     {
         name: 'export',
+        help: {
+            usage: ['/export [path]'],
+            details: [
+                'Without a path, choose the clipboard or a Markdown file. Existing files are not overwritten. Paths may contain spaces.',
+            ],
+        },
         description: 'Export this verified conversation to the clipboard or a Markdown file.',
         action: (_ctx, args) => {
             const path = args.join(' ').trim();
@@ -523,40 +663,76 @@ export const CLI_LOCAL_COMMANDS = [
     },
     {
         name: 'status',
-        description: 'Show what this session is, where it may write, and when it stops to ask.',
-        action: (ctx) => ({
-            kind: 'message',
-            role: 'system',
-            content: renderStatus(ctx),
-        }),
-    },
-    {
-        name: 'debug-config',
-        description: 'Show the winning source for every resolved config key.',
-        action: (ctx) => ({
-            kind: 'message',
-            role: 'system',
-            content: renderConfigDebug(ctx.configDebug),
-        }),
+        help: { usage: ['/status [details|config|tools]'] },
+        description: 'Show the model, permissions, workspace and latest cost.',
+        action: (ctx, args) => {
+            const which = args.join(' ').trim().toLowerCase();
+            if (which === 'config') {
+                return {
+                    kind: 'message',
+                    role: 'system',
+                    content: renderConfigDebug(ctx.configDebug),
+                };
+            }
+            if (which === 'tools') {
+                const tools = ctx.availableTools();
+                return {
+                    kind: 'message',
+                    role: 'system',
+                    content: tools.length === 0
+                        ? 'No tools registered yet — the agent session may still be connecting.'
+                        : `Registered tools (${tools.length}):\n  ${tools.join('\n  ')}`,
+                };
+            }
+            if (which.length > 0 && which !== 'details') {
+                return {
+                    kind: 'message',
+                    role: 'system',
+                    content: 'Usage: /status [details|config|tools]',
+                };
+            }
+            return { kind: 'message', role: 'system', content: renderStatus(ctx, which === 'details') };
+        },
     },
     {
         name: 'permissions',
-        description: 'Choose how undecided tool calls are handled: /permissions [mode].',
-        action: (_ctx, args) => {
+        description: 'Choose which actions need your approval.',
+        help: {
+            usage: ['/permissions', '/permissions details', '/permissions <mode>'],
+            details: [
+                'Choose a preset in the menu, or use a typed mode:',
+                ...['prompt', 'accept-edits', 'plan', 'auto', 'strict'].map((mode) => `  ${mode}: ${permissionModeLabel(mode)}`),
+                'Changes apply to this session. Explicit deny rules and sandbox restrictions still apply.',
+            ],
+        },
+        action: (ctx, args) => {
             if (args.length === 0)
                 return { kind: 'permission-mode-picker' };
             const mode = args.length === 1 ? args[0]?.toLowerCase() : undefined;
+            if (mode === 'details') {
+                return {
+                    kind: 'message',
+                    role: 'system',
+                    content: renderPermissions(ctx.permissions, true),
+                };
+            }
             if (isPermissionMode(mode))
                 return { kind: 'permission-mode', mode };
             return {
                 kind: 'message',
                 role: 'system',
-                content: 'Usage: /permissions [prompt|auto|strict]',
+                content: 'Usage: /permissions opens the permission menu. Choose a preset there, or use /permissions details to view rules.',
             };
         },
     },
     {
         name: 'effort',
+        help: {
+            usage: ['/effort [level|default]'],
+            details: [
+                'Run /effort to see the levels supported by the selected model and usable fallbacks. Changes affect future main-query turns in this session.',
+            ],
+        },
         description: 'Choose reasoning effort for future turns: /effort [level|default].',
         action: (ctx, args) => {
             if (args.length === 0) {
@@ -608,6 +784,12 @@ export const CLI_LOCAL_COMMANDS = [
     {
         name: 'init',
         description: 'Write an AGENTS.md describing this project to future agents.',
+        help: {
+            usage: ['/init'],
+            details: [
+                'Asks the selected model to read the project and write instructions. Existing instructions are read before changes are proposed.',
+            ],
+        },
         action: (ctx) => {
             if (!ctx.providerSummary) {
                 return {
@@ -667,53 +849,131 @@ export function initPrompt(instructionFiles) {
         'future run, so a sentence that says nothing is not free.',
     ].join('\n');
 }
-/**
- * Spend, stated as spend.
- *
- * `totalTokens` is cumulative and monotone; it is NOT how full the context is,
- * and the two were conflated once already — the gauge divided cumulative spend
- * by a guessed window, so it climbed with turn count and read FULL on a
- * conversation with room to spare. This command prints the spend and says which
- * quantity it is, so that nobody reads it as the other one.
- */
-export function renderCost(usage) {
-    if (usage === null) {
-        return 'No usage reported yet. The kernel emits it as a turn runs, so this fills in after the first exchange.';
+/** The session's shell hooks, by event, in the order the config file gave them. */
+export function renderHooks(hooks) {
+    const events = Object.entries(hooks ?? {}).filter(([, entries]) => (entries?.length ?? 0) > 0);
+    if (events.length === 0) {
+        return 'No hooks. Add a `hooks` key to namzu.config.json or ~/.namzu/config.yaml: event → list of { command, matcher?, timeoutMs? }.';
     }
-    // Three states, and the third used to read as the first.
-    //
-    // This printed `'$0.0000 (this provider reported no price)'` for any total
-    // that was not above zero — which was every run, because nothing fed the
-    // kernel's cost calculation at all. Two things were wrong with it beyond
-    // the number. A run on a local model costs nothing and is NOT the same
-    // event as a run nobody can price; and the parenthetical asserted a fact
-    // about the provider that no code had checked. What was actually known is
-    // that this side has no rate for the model — a statement about namzu, not
-    // about the vendor, and the difference decides who the operator goes to.
-    //
-    // The kernel exports `describeCost` for exactly this distinction and it is
-    // deliberately NOT used here: it renders through `formatCost`, which rounds
-    // to two decimals above a cent, and this command exists to print exact
-    // figures (see `SlashContext.usage`). Rounding `$0.0731` to `$0.07` to
-    // reuse a helper would trade the property someone asked for against tidy
-    // code. The status bar, which must fit, is where the short form belongs.
-    const amount = `$${usage.cost.totalCost.toFixed(4)}`;
-    const unpriced = usage.cost.unpricedTokens > 0;
-    const lines = [
-        `Tokens: ${usage.totalTokens.toLocaleString('en-US')}`,
-        `Cost:   ${unpriced && usage.cost.totalCost === 0 ? 'not known' : amount}${unpriced && usage.cost.totalCost > 0 ? ' and counting — see below' : ''}`,
+    const lines = [];
+    for (const [event, entries] of events) {
+        lines.push(`${event}`);
+        for (const entry of entries ?? []) {
+            const when = entry.matcher ? ` · matches ${entry.matcher}` : '';
+            const deadline = entry.timeoutMs !== undefined ? ` · ${Math.round(entry.timeoutMs / 1000)}s` : '';
+            lines.push(`  ${entry.command}${when}${deadline}`);
+        }
+    }
+    return lines.join('\n');
+}
+/** The session's background jobs, as an operator would ask about them. */
+export function renderJobs(jobs) {
+    if (jobs.length === 0) {
+        return 'No background jobs this session. The agent starts one with `run_in_background` on bash; under a sandbox none can be started.';
+    }
+    const lines = jobs.map((job) => {
+        const state = job.status === 'running'
+            ? `running for ${Math.max(1, Math.round((Date.now() - job.startedAt) / 1000))}s`
+            : job.status === 'killed'
+                ? 'stopped'
+                : `exited ${job.exitCode ?? '?'}`;
+        return `${job.id}  ${state.padEnd(16)}  ${job.command}`;
+    });
+    return [
+        `${jobs.length} background job${jobs.length === 1 ? '' : 's'} this session:`,
+        ...lines,
         '',
+        'The agent reads one with the job tool; ask it to stop one, or /exit stops them all.',
+    ].join('\n');
+}
+/** Reports validate their subcommand instead of silently ignoring mistyped arguments. */
+function reportCommand(name, args, render, detailName = 'details') {
+    const option = args.join(' ').trim().toLowerCase();
+    const details = option === detailName || option === 'details';
+    return {
+        kind: 'message',
+        role: 'system',
+        content: option.length === 0 || details ? render(details) : `Usage: /${name} [${detailName}]`,
+    };
+}
+function contextMeasurement(usage) {
+    const context = usage?.context;
+    if (!context || context.windowTokens <= 0)
+        return ['No context measurement yet.'];
+    const percent = Math.min(999, Math.round((context.tokens / context.windowTokens) * 100));
+    const approx = context.measured && !context.windowAssumed ? '' : '~';
+    return [
+        `Context: ${context.tokens.toLocaleString('en-US')} / ${context.windowTokens.toLocaleString('en-US')} tokens (${approx}${percent}%)`,
+        `${context.measured ? 'Counted by the provider' : 'Estimated by Namzu'}; window ${context.windowAssumed ? 'assumed from a table or default' : 'declared by the provider or config'}.`,
+    ];
+}
+export function renderContext(usage, compaction, details = false) {
+    const lines = contextMeasurement(usage);
+    if (usage?.context)
+        lines.push('Latest reported context size; not cumulative token usage.');
+    if (!compaction) {
+        lines.push('Automatic cleanup: unavailable before a session starts.');
+    }
+    else {
+        lines.push(`Cleanup this session: ${compaction.passes} passes, ~${compaction.reclaimedTokens.toLocaleString('en-US')} tokens freed.`);
+        if (details) {
+            const pct = (fraction) => `${Math.round(fraction * 100)}%`;
+            lines.push(`Strategy: ${compaction.strategy}`);
+            if (compaction.strategy === 'salience') {
+                lines.push(`Older, less useful content is shortened from ${pct(compaction.softTarget)} of the window; older history is summarised at ${pct(compaction.triggerThreshold)}.`);
+            }
+            else {
+                lines.push(`Older tool results are cleared at ${pct(compaction.triggerThreshold)} of the window; history is summarised if needed.`);
+            }
+            lines.push(`Tool results cleared: ${compaction.clearedResults.toLocaleString('en-US')}`, `Messages shortened: ${compaction.stubbedNarrations.toLocaleString('en-US')}`, `Summaries written: ${compaction.summaries.toLocaleString('en-US')}`);
+        }
+    }
+    if (!details)
+        lines.push('/context details for cleanup history.');
+    return lines.join('\n');
+}
+/** Keep unknown prices distinct from measured zero, in status and cost alike. */
+function costAmount(cost) {
+    if (cost.unpricedTokens > 0) {
+        return cost.totalCost > 0 ? `at least $${cost.totalCost.toFixed(4)}` : 'not known';
+    }
+    return `$${cost.totalCost.toFixed(4)}${cost.totalCost === 0 ? ' (measured zero)' : ''}`;
+}
+export function renderCost(usage, compaction = null, details = false) {
+    if (usage === null)
+        return 'No usage reported yet. Send a message to begin.';
+    const lines = [
+        'Current or latest run',
+        `Tokens: ${usage.totalTokens.toLocaleString('en-US')} (own model calls)`,
+        `Cost: ${costAmount(usage.cost)}`,
     ];
-    if (unpriced) {
-        lines.push(`${usage.cost.unpricedTokens.toLocaleString('en-US')} tokens ran on a model namzu has no rate`, 'for, so what they cost is not in this figure and cannot be. This is not', 'a claim that they were free. Declare the rate to price them.');
+    if (usage.cost.unpricedTokens > 0) {
+        lines.push(`${usage.cost.unpricedTokens.toLocaleString('en-US')} tokens have no known price and are excluded from the cost.`);
     }
-    else if (usage.cost.totalCost === 0) {
-        lines.push('A measured zero, not a missing figure: the model that served this run', 'bills nothing per token.');
+    if (usage.budget) {
+        lines.push(`Including delegated agents: ${usage.budget.treeTokens.toLocaleString('en-US')} tokens; limit ${usage.budget.limit === 0 ? 'unlimited' : usage.budget.limit.toLocaleString('en-US')}.`);
+        if (usage.budget.poisoned)
+            lines.push('Further spending is blocked until unresolved request usage is reconciled.');
+    }
+    if (details) {
+        lines.push('Cost covers this run’s own model calls, excluding delegated calls and earlier runs. These are not conversation totals.');
+        if (usage.cost.unpricedTokens > 0) {
+            lines.push('Missing prices do not mean those tokens were free.');
+        }
+        else {
+            lines.push('All reported tokens have a known rate.');
+        }
+        if (usage.cost.cacheDiscount > 0)
+            lines.push(`Cache discount: $${usage.cost.cacheDiscount.toFixed(4)}`);
+        if (usage.context && usage.context.windowTokens > 0) {
+            lines.push('', ...contextMeasurement(usage), '/context details for automatic cleanup.');
+        }
+        if (compaction)
+            lines.push(`Cleanup passes this session: ${compaction.passes}.`);
     }
     else {
-        lines.push('Every token in this run was charged at a known rate.');
+        lines.push('/cost details for scope and pricing; /context for context size.');
     }
-    lines.push('', 'Cumulative for this run, across every turn. Not a measure of how full', 'the context is — that is a different quantity and it goes down when the', 'conversation is compacted, while this only ever grows.');
     return lines.join('\n');
 }
 /** What decides a tool call, in the order it actually decides it. */
@@ -797,146 +1057,93 @@ function reviewTargetPrompt(target) {
         'Say plainly what you did not examine.',
     ].join('\n');
 }
-export function renderMcp(mcp) {
+export function renderMcp(mcp, details = false) {
     if (mcp === null)
-        return 'No session yet — no tool servers have been contacted.';
-    const lines = [];
+        return 'No session yet. Tool servers have not been checked.';
     if (mcp.connected.length === 0 && mcp.failed.length === 0) {
-        return 'No tool servers configured. Add an `mcpServers` block to namzu.config.json.';
+        return 'No tool servers configured. Add mcpServers to namzu.config.json.';
     }
+    const lines = [
+        `Tool servers: ${mcp.connected.length} connected, ${mcp.failed.length} unavailable.`,
+    ];
     for (const server of mcp.connected) {
-        lines.push(`${server.name} — connected, ${server.tools.length} tool(s)`);
-        // Named, not counted. A count answers "did it work"; the operator's
-        // actual question is whether the tool they wanted is among them.
-        for (const tool of server.tools)
-            lines.push(`  ${tool}`);
-    }
-    if (mcp.failed.length > 0) {
-        if (lines.length > 0)
-            lines.push('');
-        for (const server of mcp.failed) {
-            lines.push(`${server.name} — NOT available: ${server.reason}`);
-        }
+        lines.push(`${server.name}: connected, ${server.tools.length} tools`);
+        if (details)
+            for (const tool of server.tools)
+                lines.push(`  ${tool}`);
     }
+    for (const server of mcp.failed)
+        lines.push(`${server.name}: unavailable — ${server.reason}`);
+    if (!details && mcp.connected.length > 0)
+        lines.push('/mcp tools to list available tools.');
     return lines.join('\n');
 }
-export function renderStatus(ctx) {
-    const lines = [];
-    lines.push(`Provider: ${ctx.providerSummary ?? 'none — run /model to pick one'}`);
-    lines.push(`Model:    ${ctx.modelSummary ?? '—'}`);
-    lines.push('');
-    lines.push('Where it may write');
+export function renderStatus(ctx, details = false) {
+    const lines = [
+        `Provider: ${ctx.providerSummary ?? 'none — run /model to choose one'}`,
+        `Model: ${ctx.modelSummary ?? 'not selected'}`,
+        `Working directory: ${ctx.cwd}`,
+        ...renderPermissions(ctx.permissions, details).split('\n'),
+    ];
     const sandbox = ctx.sandbox;
     if (!sandbox) {
-        lines.push('  Not resolved yet — no session has started.');
+        lines.push('Sandbox: not resolved yet.');
     }
     else if (sandbox.unconfined) {
-        // The loudest line on the page, and deliberately not softened by the
-        // environment name: a tier that enforces nothing is not a weaker
-        // sandbox, it is the absence of one.
-        lines.push('  Anywhere this shell can. Commands are NOT confined.');
-        if (sandbox.environment) {
-            lines.push(`  The sandbox is attached (${sandbox.environment}) and enforces nothing here.`);
-        }
-        lines.push('  Name what you need under `sandbox.requireIsolation` to be refused instead.');
+        lines.push('Sandbox: commands are not confined; they have this shell’s access.');
     }
     else {
-        lines.push(`  Confined to this session's sandbox (${sandbox.environment ?? 'unknown'}).`);
-        lines.push(`  Enforced here: ${sandbox.enforced.join(', ')}.`);
-    }
-    if (sandbox && sandbox.required.length > 0) {
-        // Worth its own line even when it matches what is enforced: a demand
-        // travels to the next machine and a coincidence does not.
-        lines.push(`  Required by config: ${sandbox.required.join(', ')} — a host without them refuses to run.`);
+        lines.push(`Sandbox: ${sandbox.environment ?? 'active'}; enforces ${sandbox.enforced.join(', ') || 'no reported restrictions'}.`);
     }
-    else if (sandbox) {
-        lines.push('  Required by config: nothing — this host decides what you get.');
+    if (sandbox?.workspace === 'ephemeral') {
+        lines.push('Workspace: temporary files; removed when the run ends.');
     }
-    if (sandbox?.workspace === 'working-directory') {
-        lines.push('  Workspace: real project files — changes persist across turns.');
+    else if (sandbox?.workspace === 'working-directory' || sandbox?.workspace === 'host') {
+        lines.push('Workspace: real project files; edits persist.');
     }
-    else if (sandbox?.workspace === 'ephemeral') {
-        lines.push('  Workspace: disposable per run — changes are removed at teardown.');
-    }
-    else if (sandbox?.workspace === 'host') {
-        lines.push('  Workspace: real project files on the host.');
-    }
-    lines.push('');
-    lines.push('When it stops to ask');
-    for (const line of renderPermissions(ctx.permissions).split('\n')) {
-        lines.push(line.length > 0 ? `  ${line}` : '');
-    }
-    if (ctx.usage) {
-        lines.push('');
-        lines.push(`Spend: ${renderCost(ctx.usage).split('\n')[0] ?? ''}`);
+    if (details) {
+        for (const dir of ctx.directories?.() ?? [])
+            lines.push(`Additional directory: ${dir}`);
+        if (sandbox) {
+            lines.push(`Required isolation: ${sandbox.required.length > 0 ? sandbox.required.join(', ') : 'none'}.`);
+            if (sandbox.required.length > 0)
+                lines.push('A host missing required isolation cannot start the session.');
+        }
+        lines.push('/status config for setting sources; /status tools for available tools.');
     }
-    return lines.join('\n').trimEnd();
+    if (ctx.usage)
+        lines.push(`Spend (current or latest run, own calls): ${costAmount(ctx.usage.cost)}`);
+    if (!details)
+        lines.push('/status details for rules and workspace details.');
+    return lines.join('\n');
 }
-export function renderPermissions(permissions) {
-    const lines = [];
+export function renderPermissions(permissions, details = false) {
     const current = permissions.currentMode();
-    lines.push(`Current mode: ${current.mode}.`);
-    lines.push('');
-    // Four effective states, most permissive first, and the approve-all one is the reason this
-    // function was rewritten: it is reachable from a single keystroke at a
-    // prompt, it silently outranks the default, and it used to be invisible
-    // here — so the page answering "how do tool calls get approved" gave the
-    // safe answer to an operator who had already turned the safety off.
-    if (current.mode === 'auto') {
-        lines.push(current.source === 'launch-bypass'
-            ? 'Unreviewed calls: approved automatically (--dangerously-skip-permissions).'
-            : 'Unreviewed calls: approved automatically for future turns (/permissions auto).');
-    }
-    else if (current.mode === 'strict') {
-        lines.push('Unreviewed calls: rejected automatically for future turns (/permissions strict).');
-        lines.push('Only calls an explicit allow rule covers may run; no approval prompt can widen that.');
-    }
-    else if (permissions.approvalLatched()) {
-        lines.push('Unreviewed calls: approved automatically — "approve all" was chosen at');
-        lines.push('an earlier prompt. Run /permissions prompt to revoke that latch and ask again.');
-    }
-    else {
-        lines.push('Unreviewed calls: you are asked before they run.');
-    }
-    // Stated in every mode, because it is true in every mode and an operator
-    // cannot discover it by using namzu: these tools simply never appear at a
-    // prompt, so their absence reads as "the agent did not use any".
-    const neverPrompted = permissions.neverPrompted();
-    if (neverPrompted.length > 0) {
-        lines.push('');
-        lines.push(`Never prompted for (${neverPrompted.length}):`);
-        lines.push(`  ${neverPrompted.join(', ')}`);
-        lines.push('Each of these declares itself read-only, or is a named exception');
-        lines.push("for the agent's own task list. A rule can still deny one, and any");
-        lines.push('call the kernel flags destructive is prompted for regardless.');
+    const effective = effectivePermissionMode(current.mode, permissions.approvalLatched());
+    const approvedAll = effective !== current.mode;
+    const lines = [
+        `Permissions: ${permissionModeLabel(effective)}. ${approvedAll ? 'Tools are approved automatically for this session.' : permissionModeDescription(effective)}`,
+    ];
+    if (approvedAll)
+        lines.push('Choose a preset in /permissions to change this.');
+    if (!details)
+        return lines.join('\n');
+    if (current.source === 'launch-bypass')
+        lines.push('Selected at launch with --dangerously-skip-permissions.');
+    lines.push('Explicit deny rules and the built-in safety gate apply in every mode.');
+    if (current.mode === 'plan')
+        lines.push('Plan mode also blocks writes that an allow rule would otherwise permit.');
+    const exempt = permissions.neverPrompted();
+    if (exempt.length > 0) {
+        lines.push(`Tools exempt from ordinary prompts: ${exempt.join(', ')}.`);
+        lines.push('Destructive calls still require review; the selected mode decides whether to allow, ask or refuse. Plan mode still requires read-only tools.');
     }
-    if (permissions.rules.length === 0) {
-        lines.push('');
-        lines.push('No rules configured. Add a "permissions" object to namzu.config.json');
-        lines.push('to allow or deny tools by name without being asked each time.');
+    if (permissions.rules.length > 0) {
+        lines.push(`Rules (${permissions.rules.length}):`, ...permissions.rules.map((rule) => `  ${describeRule(rule)}`));
     }
     else {
-        lines.push('');
-        lines.push(`Rules (${permissions.rules.length}), from your config:`);
-        for (const rule of permissions.rules)
-            lines.push(`  ${describeRule(rule)}`);
+        lines.push('No custom rules. Configure permissions in namzu.config.json.');
     }
-    lines.push('');
-    // The order this function claims to describe starts here, and the page used
-    // to begin one step in. Omitting the gate is not a false statement, but it
-    // makes "a rule decides first" read as the whole story when something
-    // outranks the rules too — and a true-but-incomplete order is a wrong order
-    // for anyone reasoning about what can still get through.
-    lines.push('Before any of the below: a built-in safety gate hard-denies a narrow set');
-    lines.push('of catastrophic shell patterns (rm -rf /, mkfs, fork bombs, curl|sh, …).');
-    lines.push('It applies in every mode, including --dangerously-skip-permissions, and');
-    lines.push('nothing here can switch it off.');
-    lines.push('');
-    // Stated because the precedence is the part people get wrong, and getting it
-    // wrong in this direction is the dangerous one: assuming the flag lifts a
-    // `deny` they wrote.
-    lines.push('Then a rule decides. The approval setting above only reaches calls');
-    lines.push('no rule covered, so it can never reopen what a `deny` closed.');
     return lines.join('\n');
 }
 /** Render the exact session control without inventing a global effort menu. */
@@ -1044,8 +1251,13 @@ export function runSlash(line, ctx, builtins = CLI_LOCAL_COMMANDS) {
     // a `problem` so their author is told, rather than leaving them to wonder
     // why the file never ran.
     const cmd = builtins.find((c) => c.name === parsed.name);
-    if (cmd)
-        return cmd.action(ctx, parsed.args);
+    if (cmd) {
+        const commandContext = { ...ctx, builtins };
+        const reason = cmd.unavailable?.(commandContext);
+        return reason
+            ? { kind: 'message', role: 'system', content: reason }
+            : cmd.action(commandContext, parsed.args);
+    }
     const user = ctx.userCommands.find((c) => c.name === parsed.name);
     if (user) {
         const expanded = expandCommand(user, parsed.args.join(' '));