ikie-cli 0.1.3 → 0.1.5

package/README.md

@@ -4,13 +4,13 @@
 
 ```bash
 npm install -g ikie-cli
+ikie login
 ikie "write a rust web server"
 ```
 
 ## Features
 
-- Streaming AI chat completions via Fireworks AI (default: Kimi K2)
-- 10 built-in tools: read/write/edit files, bash, search, grep, memory, agent spawn
+- 12 built-in tools: read/write/edit files, bash, search, grep, memory, agent spawn, web fetch & search
 - Interactive REPL with slash commands, markdown rendering, and session management
 - One-shot mode: `ikie "your prompt"`
 - Image paste support (Ctrl+V)
@@ -22,14 +22,22 @@ ikie "write a rust web server"
 # Install
 npm install -g ikie
 
-# Set your API key
-export FIREWORKS_API_KEY=fw_...
+# Sign in to your ikie account
+ikie login
 
 # Start coding
 ikie "refactor this file and add tests"
 ```
 
+## Web access
+
+ikie can read pages and search the web:
+
+- **`fetch_url`** — read any page or URL (HTML is stripped to plain text).
+- **`web_search`** — search the web and get back titles, URLs, and snippets. Powered by the ikie
+  server — no separate search API key needed; your ikie login is enough.
+
 ## Requirements
 
 - Node.js 20+
-- A Fireworks AI API key (or any OpenAI-compatible endpoint via `--base-url`)
+- An ikie account — sign in with `ikie login`

package/dist/agent.d.ts

@@ -7,6 +7,8 @@ export interface AgentOptions {
     signal?: AbortSignal;
     startedAt?: number;
 }
+/** Plan = read-only research + propose; Agent = full execution. */
+export type AgentMode = 'agent' | 'plan';
 export interface AgentTurnStats {
     modelCalls: number;
     toolCalls: number;
@@ -37,11 +39,14 @@ export declare class Agent {
     private activeTurnStats;
     private activeChangedFiles;
     private lastTurnStats;
+    private mode;
     constructor(client: OpenAI, config: IkieConfig, systemPrompt: string, depth?: number);
     clearConversation(): void;
     getConversation(): ChatCompletionMessageParam[];
     setConversation(messages: ChatCompletionMessageParam[]): void;
     getLastTurnStats(): AgentTurnStats;
+    getMode(): AgentMode;
+    setMode(mode: AgentMode): void;
     send(userMessage: string | UserContentPart[], opts?: AgentOptions): Promise<void>;
     private recordChangedFile;
     private groupToolCalls;
@@ -59,4 +64,5 @@ export declare class Agent {
     private checkPermission;
 }
 export declare const SUBAGENT_FRAMING = "You are a focused sub-agent spawned by Ikie to autonomously complete ONE specific task.\nWork independently \u2014 do not ask the user questions. Use your tools to gather what you\nneed, do the work, and verify it. When finished, your FINAL message must be a concise\nsummary of what you did and any key results (paths changed, findings, answers). That\nsummary is the only thing returned to the main agent, so make it self-contained.";
+export declare const PLAN_MODE_ADDENDUM = "\n\n## PLAN MODE (read-only)\nYou are currently in **plan mode**. You have ONLY read-only tools (read_file,\nlist_dir, search_files, grep, fetch_url, web_search, spawn_agent, ask_user). You CANNOT write files, edit\nfiles, run shell commands, or change anything \u2014 those tools are unavailable and any\nattempt will be blocked.\n\nYour job is to investigate and produce a clear, actionable plan:\n- Explore the relevant files and understand the current state before proposing anything.\n- Do NOT describe changes as if you already made them. You haven't.\n- End your response with a concise plan: a short **## Plan** heading followed by\n  numbered steps. Name the specific files to change and what to change in each. Call\n  out risks, assumptions, or open questions.\n- Keep it tight \u2014 enough to execute from, not an essay.\n\nAfter you present the plan, the user will be asked whether to execute it. On approval,\nyou'll be switched to agent mode and asked to carry out exactly this plan.";
 export declare function buildSystemPrompt(projectContext: string, memoryContext: string): string;

package/dist/agent.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import * as readline from 'node:readline';
-import { TOOL_DEFS, SAFE_TOOLS, formatToolArgs, executeTool } from './tools.js';
+import { TOOL_DEFS, SAFE_TOOLS, PLAN_TOOLS, formatToolArgs, executeTool } from './tools.js';
 import { renderMarkdown, extractThinkTags } from './renderer.js';
 import { c, toolLine, permissionPrompt, toolSuccessLine, toolErrorLine, InlineSpinner } from './theme.js';
 export function estimateTokens(chars) {
@@ -47,6 +47,8 @@ function toolPhaseLabel(name) {
         case 'list_dir': return 'Listing directory';
         case 'search_files': return 'Searching';
         case 'grep': return 'Searching';
+        case 'fetch_url': return 'Fetching';
+        case 'web_search': return 'Searching web';
         default: return `Preparing ${name}`;
     }
 }
@@ -62,6 +64,7 @@ export class Agent {
     activeTurnStats = null;
     activeChangedFiles = new Set();
     lastTurnStats = { modelCalls: 0, toolCalls: 0, filesChanged: 0 };
+    mode = 'agent';
     constructor(client, config, systemPrompt, depth = 0) {
         this.client = client;
         this.config = config;
@@ -81,6 +84,12 @@ export class Agent {
     getLastTurnStats() {
         return { ...this.lastTurnStats };
     }
+    getMode() {
+        return this.mode;
+    }
+    setMode(mode) {
+        this.mode = mode;
+    }
     async send(userMessage, opts = {}) {
         this.activeTurnStats = { modelCalls: 0, toolCalls: 0, filesChanged: 0 };
         this.activeChangedFiles = new Set();
@@ -170,6 +179,21 @@ export class Agent {
                         return {};
                     }
                 });
+                // Plan mode is read-only. The model normally isn't even offered mutating
+                // tools (see buildParams), but refuse here too as defense-in-depth.
+                if (this.mode === 'plan' && !PLAN_TOOLS.has(group[0].name)) {
+                    if (this.activeTurnStats)
+                        this.activeTurnStats.toolCalls += group.length;
+                    process.stdout.write(`\n${this.indent}${toolLine(group[0].name, formatToolArgs(group[0].name, inputs[0])).trimStart()}\n`);
+                    process.stdout.write(`${this.indent}${toolErrorLine('blocked · plan mode is read-only')}\n`);
+                    for (const tc of group) {
+                        this.conversation.push({
+                            role: 'tool', tool_call_id: tc.id,
+                            content: 'Blocked: plan mode is read-only. Do not attempt changes — propose a plan instead. The user can switch to agent mode to apply it.',
+                        });
+                    }
+                    continue;
+                }
                 if (group.length === 1) {
                     if (this.activeTurnStats)
                         this.activeTurnStats.toolCalls++;
@@ -220,8 +244,8 @@ export class Agent {
                     }
                     const ms = Date.now() - t0;
                     const lineStr = errors === 0
-                        ? toolSuccessLine(ms, `Executed ${group.length} operations`)
-                        : toolErrorLine(`${errors} of ${group.length} operations failed`);
+                        ? toolSuccessLine(ms, `${group.length} operations`)
+                        : toolErrorLine(`${errors} of ${group.length} operations`);
                     process.stdout.write(`${this.indent}${lineStr}\n`);
                 }
             }
@@ -240,9 +264,15 @@ export class Agent {
         }
     }
     buildParams() {
-        const tools = this.depth >= 1
+        let tools = this.depth >= 1
             ? TOOL_DEFS.filter(t => t.function.name !== 'spawn_agent')
             : TOOL_DEFS;
+        // Plan mode: only offer read-only tools, and steer toward proposing a plan.
+        let systemContent = this.systemPrompt;
+        if (this.mode === 'plan') {
+            tools = tools.filter(t => PLAN_TOOLS.has(t.function.name));
+            systemContent += PLAN_MODE_ADDENDUM;
+        }
         return {
             model: this.config.model,
             max_tokens: this.config.maxTokens,
@@ -252,7 +282,7 @@ export class Agent {
             presence_penalty: this.config.presencePenalty,
             frequency_penalty: this.config.frequencyPenalty,
             messages: [
-                { role: 'system', content: this.systemPrompt },
+                { role: 'system', content: systemContent },
                 ...this.conversation,
             ],
             tools,
@@ -587,9 +617,29 @@ Work independently — do not ask the user questions. Use your tools to gather w
 need, do the work, and verify it. When finished, your FINAL message must be a concise
 summary of what you did and any key results (paths changed, findings, answers). That
 summary is the only thing returned to the main agent, so make it self-contained.`;
+// Appended to the system prompt while in PLAN mode. The model is given only
+// read-only tools (see buildParams); this steers it to research and propose.
+export const PLAN_MODE_ADDENDUM = `
+
+## PLAN MODE (read-only)
+You are currently in **plan mode**. You have ONLY read-only tools (read_file,
+list_dir, search_files, grep, fetch_url, web_search, spawn_agent, ask_user). You CANNOT write files, edit
+files, run shell commands, or change anything — those tools are unavailable and any
+attempt will be blocked.
+
+Your job is to investigate and produce a clear, actionable plan:
+- Explore the relevant files and understand the current state before proposing anything.
+- Do NOT describe changes as if you already made them. You haven't.
+- End your response with a concise plan: a short **## Plan** heading followed by
+  numbered steps. Name the specific files to change and what to change in each. Call
+  out risks, assumptions, or open questions.
+- Keep it tight — enough to execute from, not an essay.
+
+After you present the plan, the user will be asked whether to execute it. On approval,
+you'll be switched to agent mode and asked to carry out exactly this plan.`;
 export function buildSystemPrompt(projectContext, memoryContext) {
     const parts = [
-        `You are Ikie, an expert agentic coding assistant running in the terminal.
+        `You are Ikie, an elite agentic software engineer running in the terminal.
 
 ## Identity
 Your name is Ikie. If asked what you are, who made you, or what model powers you,
@@ -598,42 +648,64 @@ Claude, ChatGPT, GPT, Gemini, Llama, or any other named model or company's assis
 Do not speculate about your underlying model.
 
 You help developers write, debug, understand, and refactor code. You work autonomously
-using your tools to accomplish tasks. Be direct, concise, and practical.
+using your tools to accomplish tasks. Be direct, concise, and pragmatic. Optimize for
+the user's actual goal, not the literal letter of the request — but never overstep into
+changes they didn't ask for.
 
 ## Response Formatting
 - Use **markdown formatting** in all your responses for better readability
-- Use **bold** for emphasis: **important text**
-- Use *italics* for secondary emphasis: *note*
-- Use \`inline code\` for: variable names, file names, short code snippets, commands
-- Use code blocks with language tags for multi-line code (triple backticks)
-- Use bullet points (-, *, +) or numbered lists for steps and options
-- Use headers (##, ###) to organize longer responses
-- Use tables for structured data comparisons
-- Keep responses **concise but well-formatted** - the terminal renderer supports rich markdown
+- Use **bold** for key takeaways, \`inline code\` for identifiers, file names, commands
+- Use fenced code blocks with language tags for multi-line code
+- Use bullet/numbered lists for steps and options; headers (##, ###) to organize long replies
+- Use tables for structured comparisons
+- Keep responses **concise but well-formatted** — lead with the answer, then detail.
+  Don't narrate routine tool calls; show results. The terminal renders rich markdown.
 
 ## Working Style
 - ALWAYS provide complete, valid arguments to tools. Never omit required fields like \`path\`.
-- When creating files, use the FULL file path (relative or absolute) — not just a filename.
-- Read files before editing them
-- Prefer \`edit_file\` over \`write_file\` for modifications (surgical edits > full rewrites)
-- Run tests or sanity checks after making meaningful changes
-- For complex tasks, break them down and tackle one step at a time
-- Acknowledge errors and self-correct; don't pretend failures didn't happen
-- When writing large files, write the COMPLETE content. Never truncate or use placeholders.
-- For long-running servers/processes, use \`nohup cmd &\` or \`setsid cmd\` so they survive after the session.
+- When creating files, use the FULL file path — not just a filename.
+- Read files before editing them. Prefer \`edit_file\` (surgical) over \`write_file\` (full rewrite).
+- When writing files, write the COMPLETE content. Never truncate or leave \`// ...\` placeholders.
+- For complex tasks, break them down and tackle one step at a time.
+- Acknowledge errors and self-correct; never pretend a failure didn't happen.
+- For long-running servers/processes, use \`nohup cmd &\` or \`setsid cmd\` so they survive the session.
+
+## Engineering Principles
+- **Match the codebase.** Before writing code, infer the project's conventions — language,
+  framework, formatting, naming, error handling, file layout — and follow them. Check
+  imports/neighboring files for the libraries actually in use; never assume a dependency exists.
+- **Smallest correct change.** Solve the problem at its root, not with a patch over a symptom.
+  Avoid unrelated refactors and scope creep. Don't reformat code you aren't changing.
+- **Type safety & correctness.** Honor existing types; avoid \`any\`/unsafe casts. Handle the
+  error and edge cases (empty, null, boundary, concurrency), not just the happy path.
+- **No secrets in code.** Never hardcode keys, tokens, or credentials. Read from env/config.
+  Never log or echo secrets. Validate and sanitize all external input.
+- **Clarity over cleverness.** Write code a teammate can read. Name things well. Add comments
+  only for non-obvious *why*, not to restate the *what*.
+- **Leave it green.** Don't introduce dead code, unused imports, or commented-out blocks.
+
+## Modern Design (when building UI / frontend)
+- **Aesthetic by default.** Produce clean, modern, professional interfaces — generous
+  whitespace, clear visual hierarchy, consistent spacing scale, restrained palette.
+- **Design tokens, not magic numbers.** Reuse the project's theme/variables (Tailwind config,
+  CSS custom properties, design system). Don't scatter ad-hoc hex colors or pixel values.
+- **Responsive & accessible.** Mobile-first; fluid layouts. Semantic HTML, proper
+  labels/alt text, keyboard focus states, sufficient contrast (WCAG AA), respect reduced-motion.
+- **Layout with flex/grid.** Use flexbox and CSS grid for fluid, mobile-first layouts.
+- **Polish the details.** Hover/focus/active/disabled states, loading and empty states, smooth
+  but subtle transitions, sensible defaults. Avoid layout shift.
+- **Reuse before you build.** Prefer existing components and utilities over new one-offs.
 
 ## Approach
-- Understand before acting: read the relevant files and explore the structure
-  instead of guessing. A few targeted reads beat one wrong edit.
-- For multi-step work, form a short plan, then execute it step by step and adapt
-  as you learn. Keep momentum — don't stall on decisions you can reverse later.
-- Verify your work: after edits, re-read the changed regions and run the build,
-  tests, or linter. Fix what you broke before you call a task done.
+- Understand before acting: read the relevant files and explore the structure instead of
+  guessing. A few targeted reads beat one wrong edit.
+- For multi-step work, form a short plan, then execute it step by step and adapt as you learn.
+  Keep momentum — don't stall on decisions you can reverse later.
+- Verify your work: after edits, re-read the changed regions and run the build, tests, or
+  linter. Fix what you broke before you call a task done.
 - Delegate isolated or parallelizable investigation to \`spawn_agent\` to stay focused.
-- **Format your responses beautifully**: Use markdown syntax consistently - headers, lists,
-  code blocks, bold/italics. The terminal has excellent markdown rendering.
-- Be concise but clear: explain what you did and why in well-formatted points.
-  Show code/results rather than narrating. Use \`ask_user\` only when genuinely blocked.
+- Be concise but clear: explain what you did and why in well-formatted points. Show
+  code/results rather than narrating. Use \`ask_user\` only when genuinely blocked.
 - Never leave a task half-finished or claim a success you have not verified.
 
 ## Tools Available
@@ -645,6 +717,11 @@ using your tools to accomplish tasks. Be direct, concise, and practical.
 - \`search_files\`: Find files by glob pattern
 - \`grep\`: Search file contents by regex
 - \`memory_write\`: Persist important notes across sessions
+- \`fetch_url\`: Fetch a web page or URL and return its readable text (HTML is stripped to plain text).
+  Use it to read docs, articles, or API responses when you have a URL.
+- \`web_search\`: Search the web for a query and get back titles, URLs, and snippets. Works
+  automatically for logged-in ikie users — no separate API key needed. Combine with \`fetch_url\`
+  to read a promising result in full.
 - \`ask_user\`: Ask the user a clarifying question when you need more info to proceed.
   The user's answer is returned as the tool result. Use sparingly — only when genuinely
   unsure. Don't ask for confirmation on safe operations.

package/dist/auth.js

@@ -85,5 +85,5 @@ export async function login() {
 }
 export function logout() {
     clearLogin();
-    console.log(successLine('Logged out. ikie will use your local API key / Fireworks again.'));
+    console.log(successLine('Logged out. Run `ikie login` to sign back in.'));
 }

package/dist/config.d.ts

@@ -37,5 +37,5 @@ export declare function getApiKey(cfg: IkieConfig): string | undefined;
 export declare function isLoggedIn(cfg: IkieConfig): boolean;
 /** Persist the hosted account login (ik_live_ key from `ikie login`). */
 export declare function saveLogin(apiKey: string): void;
-/** Clear the hosted account login and revert to the default base URL. */
+/** Clear the hosted account login. */
 export declare function clearLogin(): void;

package/dist/config.js

@@ -17,7 +17,7 @@ const DEFAULTS = {
     model: DEFAULT_MODEL,
     maxTokens: 32768,
     autoApprove: false,
-    baseURL: FIREWORKS_BASE_URL,
+    baseURL: IKIE_API_BASE,
     temperature: 0.6,
     topP: 0.95,
     topK: 40,
@@ -47,10 +47,7 @@ export function saveConfig(patch) {
     writeFileSync(CONFIG_FILE, JSON.stringify({ ...current, ...patch }, null, 2));
 }
 export function getApiKey(cfg) {
-    return (process.env.FIREWORKS_API_KEY ??
-        process.env.IKIE_API_KEY ??
-        cfg.account?.apiKey ??
-        cfg.apiKey);
+    return cfg.account?.apiKey;
 }
 /** True when signed into a hosted ikie account. */
 export function isLoggedIn(cfg) {
@@ -60,10 +57,9 @@ export function isLoggedIn(cfg) {
 export function saveLogin(apiKey) {
     saveConfig({ account: { apiKey, loggedInAt: Date.now() }, baseURL: IKIE_API_BASE });
 }
-/** Clear the hosted account login and revert to the default base URL. */
+/** Clear the hosted account login. */
 export function clearLogin() {
     const current = loadConfig();
     delete current.account;
-    current.baseURL = FIREWORKS_BASE_URL;
     writeFileSync(CONFIG_FILE, JSON.stringify(current, null, 2));
 }

package/dist/index.js

@@ -2,7 +2,7 @@
 import process from 'process';
 import OpenAI from 'openai';
 import minimist from 'minimist';
-import { loadConfig, getApiKey, FIREWORKS_BASE_URL, DEFAULT_MODEL, isLoggedIn, IKIE_API_BASE } from './config.js';
+import { loadConfig, getApiKey, IKIE_API_BASE, DEFAULT_MODEL } from './config.js';
 import { detectProjectContext, formatContextForPrompt } from './context.js';
 import { loadAllMemory, formatMemoryForPrompt } from './memory.js';
 import { buildSystemPrompt, Agent } from './agent.js';
@@ -10,7 +10,7 @@ import { startREPL } from './repl.js';
 import { login, logout } from './auth.js';
 import { c, errorLine } from './theme.js';
 const argv = minimist(process.argv.slice(2), {
-    string: ['model', 'api-key', 'base-url', 'rpm'],
+    string: ['model', 'rpm'],
     boolean: ['help', 'version', 'yes', 'verbose'],
     alias: { h: 'help', v: 'version', y: 'yes', m: 'model' },
 });
@@ -28,19 +28,14 @@ ${c.primary('Usage:')}
 ${c.primary('Options:')}
   ${c.accent('-m, --model')} ${c.muted('<id>')}     Model ID (default: ${c.dim(DEFAULT_MODEL)})
   ${c.accent('-y, --yes')}              Auto-approve all tool executions
-  ${c.accent('--api-key')} ${c.muted('<key>')}       Fireworks API key
-  ${c.accent('--base-url')} ${c.muted('<url>')}      API base URL (default: Fireworks AI)
   ${c.accent('--rpm')} ${c.muted('<number>')}        Max model requests per minute (default: 10)
   ${c.accent('--verbose')}             Debug output
   ${c.accent('-h, --help')}            Show this help
   ${c.accent('-v, --version')}         Show version
 
-${c.primary('Environment:')}
-  ${c.muted('FIREWORKS_API_KEY')}        Fireworks AI API key
-  ${c.muted('IKIE_API_KEY')}             Alternative key env var
-
 ${c.primary('In-session commands:')}
-  ${c.muted('/help  /clear  /memory  /session  /context  /model  /rpm  /exit')}
+  ${c.muted('/help  /clear  /memory  /session  /plan  /agent  /usage  /model  /exit')}
+  ${c.muted('Shift+Tab  Toggle plan ⇄ agent mode')}
   ${c.muted('!<cmd>   Run shell command directly')}
   ${c.muted('Ctrl+V  Paste image from clipboard')}
 `);
@@ -78,37 +73,24 @@ async function main() {
         config.model = argv.model;
     if (argv.yes)
         config.autoApprove = true;
-    if (argv['api-key'])
-        config.apiKey = argv['api-key'];
-    if (argv['base-url'])
-        config.baseURL = argv['base-url'];
     if (argv.rpm) {
         const rpm = Number(argv.rpm);
         if (Number.isFinite(rpm) && rpm > 0)
             config.requestsPerMinute = Math.floor(rpm);
     }
-    // When signed into a hosted account, default to the ikie API endpoint
-    // unless the user explicitly overrode it on the CLI.
-    if (isLoggedIn(config) && !argv['base-url']) {
-        config.baseURL = IKIE_API_BASE;
-    }
     const apiKey = getApiKey(config);
     if (!apiKey) {
         console.error(`
 ${errorLine('Not signed in.')}
 
-  Sign in to your ikie account (recommended):
+  Sign in to continue:
     ${c.accent('ikie login')}
-
-  Or bring your own Fireworks key:
-    ${c.accent('export FIREWORKS_API_KEY=fw_...')}
-    ${c.accent('ikie --api-key fw_...')}
 `);
         process.exit(1);
     }
     const client = new OpenAI({
         apiKey,
-        baseURL: config.baseURL ?? FIREWORKS_BASE_URL,
+        baseURL: config.baseURL ?? IKIE_API_BASE,
     });
     const projectCtx = detectProjectContext();
     const projectContextStr = formatContextForPrompt(projectCtx);

package/dist/repl.js

@@ -1,16 +1,16 @@
 import * as readline from 'node:readline';
 import { execSync } from 'child_process';
 import { restoreStdinListeners } from './agent.js';
-import { c, PROMPT, CONTINUE_PROMPT, printPromptHeader, drawBanner, infoLine, successLine, errorLine, THEMES, setTheme, stripAnsi, } from './theme.js';
+import { c, PROMPT, CONTINUE_PROMPT, printPromptHeader, modeTag, drawBanner, infoLine, successLine, errorLine, THEMES, setTheme, stripAnsi, } from './theme.js';
 import { renderMarkdown } from './renderer.js';
 import { loadAllMemory } from './memory.js';
-import { HOME_DIR, saveConfig, DEFAULT_MODEL, FIREWORKS_BASE_URL, IKIE_HOST, isLoggedIn } from './config.js';
+import { HOME_DIR, saveConfig, DEFAULT_MODEL, IKIE_HOST, IKIE_API_BASE, isLoggedIn, getApiKey } from './config.js';
 import { login, logout } from './auth.js';
 import { join as pathJoin } from 'path';
 import { deleteSession, listSessions, loadSession, normalizeSessionName, saveSession } from './session.js';
 import { buildUserContent, formatBytes, loadClipboardImageAttachment, loadImageAttachment, hasClipboardImage } from './attachments.js';
 async function fetchModelsFromServer(config) {
-    const baseUrl = config.baseURL || FIREWORKS_BASE_URL;
+    const baseUrl = config.baseURL || IKIE_API_BASE;
     const apiUrl = baseUrl.includes('/api/v1')
         ? baseUrl.replace('/api/v1', '/api/models')
         : `${IKIE_HOST}/api/models`;
@@ -63,10 +63,9 @@ const SLASH_CMDS = [
     },
     {
         name: 'session',
-        desc: 'Save/load chat sessions',
+        desc: 'Load/manage chat sessions',
         subs: [
             { name: 'list', desc: 'List sessions' },
-            { name: 'save', desc: 'Save current session' },
             { name: 'load', desc: 'Load a session' },
             { name: 'new', desc: 'Start fresh session' },
             { name: 'delete', desc: 'Delete a session' },
@@ -94,6 +93,10 @@ const SLASH_CMDS = [
     { name: 'theme', desc: 'Change visual theme', args: '[name]' },
     { name: 'rpm', desc: 'Set request limit', args: '[number]' },
     { name: 'tokens', desc: 'Token estimate' },
+    { name: 'usage', desc: 'Show account usage & credit' },
+    { name: 'mode', desc: 'Show/set mode (plan|agent)', args: '[plan|agent]' },
+    { name: 'plan', desc: 'Switch to plan mode (read-only)' },
+    { name: 'agent', desc: 'Switch to agent mode (full)' },
     { name: 'login', desc: 'Sign in to ikie account' },
     { name: 'logout', desc: 'Sign out of ikie account' },
     { name: 'exit', desc: 'Exit Ikie' },
@@ -128,9 +131,8 @@ ${c.primary.bold('Ikie Commands')}
   ${c.warning('/image list')}       List queued images
   ${c.warning('/image clear')}      Clear queued images
   ${c.warning('/session list')}    List saved sessions
-  ${c.warning('/session save')}    Save current chat
   ${c.warning('/session load')}    Load saved chat
-  ${c.warning('/session new')}     Start a fresh chat
+  ${c.warning('/session new')}     Start a fresh chat (auto-saved)
   ${c.warning('/context')}         Show current project context
   ${c.warning('/models')}          List available models
   ${c.warning('/model <name>')}    Switch AI model
@@ -148,6 +150,10 @@ ${c.primary.bold('Ikie Commands')}
   ${c.warning('/theme')}           Pick a theme interactively
   ${c.warning('/rpm [number]')}    Show or set request limit
   ${c.warning('/tokens')}          Show conversation token estimate
+  ${c.warning('/usage')}           Show account usage & credit balance
+  ${c.warning('/plan')}            Plan mode — research & propose, no changes
+  ${c.warning('/agent')}           Agent mode — full execution (default)
+  ${c.warning('/mode')}            Show or set mode  ${c.muted('(Shift+Tab toggles)')}
   ${c.warning('/login')}           Sign in to ikie account
   ${c.warning('/logout')}          Sign out of ikie account
   ${c.warning('/exit')}            Exit Ikie
@@ -258,7 +264,7 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
             if (sub === 'list' || sub === 'ls') {
                 const sessions = listSessions();
                 if (!sessions.length) {
-                    console.log(infoLine('No saved sessions yet. Use /session save <name>.'));
+                    console.log(infoLine('No saved sessions yet. Every chat is saved automatically.'));
                     return true;
                 }
                 console.log(`\n${c.primary.bold('Sessions')}`);
@@ -268,13 +274,7 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
                     const model = s.model ? ` ${c.muted(s.model.split('/').pop() ?? s.model)}` : '';
                     console.log(`  ${active} ${c.secondary(s.name.padEnd(24))} ${c.muted(String(s.messageCount).padStart(3) + ' msgs')} ${c.dim(when)}${model}`);
                 }
-                return true;
-            }
-            if (sub === 'save') {
-                const name = normalizeSessionName(nameArg || sessionState.activeName);
-                const saved = saveSession(name, config.model, agent.getConversation());
-                sessionState.activeName = saved.name;
-                console.log(successLine(`Session saved as "${saved.name}".`));
+                console.log(`\n  ${c.muted('Resume with')} ${c.warning('/session load <name>')}\n`);
                 return true;
             }
             if (sub === 'load') {
@@ -297,8 +297,8 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
             }
             if (sub === 'new') {
                 agent.clearConversation();
-                sessionState.activeName = nameArg ? normalizeSessionName(nameArg) : undefined;
-                console.log(successLine(sessionState.activeName ? `Started new session "${sessionState.activeName}".` : 'Started a fresh session.'));
+                sessionState.activeName = nameArg ? normalizeSessionName(nameArg) : normalizeSessionName();
+                console.log(successLine(`Started new session "${sessionState.activeName}" (auto-saved).`));
                 return true;
             }
             if (sub === 'delete' || sub === 'rm') {
@@ -318,7 +318,7 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
                 }
                 return true;
             }
-            console.log(errorLine('Usage: /session list|save [name]|load <name>|new [name]|delete <name>'));
+            console.log(errorLine('Usage: /session list|load <name>|new [name]|delete <name>'));
             return true;
         }
         case 'context':
@@ -371,7 +371,7 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
                 console.log(`  ${c.secondary('Auto Approve:')}     ${c.white(config.autoApprove ? 'Yes' : 'No')}`);
                 console.log(`  ${c.secondary('Requests/min:')}     ${c.white(config.requestsPerMinute)}`);
                 console.log(`  ${c.secondary('Theme:')}            ${c.white(config.theme)}`);
-                console.log(`  ${c.secondary('Base URL:')}         ${c.white(config.baseURL ?? FIREWORKS_BASE_URL)}`);
+                console.log(`  ${c.secondary('Base URL:')}         ${c.white(config.baseURL ?? IKIE_API_BASE)}`);
                 console.log(`\n  ${c.muted('Use')} ${c.warning('/settings <option> <value>')} ${c.muted('to change settings')}`);
                 console.log(`  ${c.muted('Options:')} model, temperature, max-tokens, top-p, top-k, auto-approve, rpm, theme`);
                 return true;
@@ -530,6 +530,56 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
             console.log(infoLine(`~${Math.round(approxTokens).toLocaleString()} tokens in conversation`));
             return true;
         }
+        case 'plan': {
+            agent.setMode('plan');
+            console.log(successLine(`Switched to ${modeTag('plan')} mode — read-only. Ikie will research and propose a plan.`));
+            return true;
+        }
+        case 'agent': {
+            agent.setMode('agent');
+            console.log(successLine(`Switched to ${modeTag('agent')} mode — full execution.`));
+            return true;
+        }
+        case 'mode': {
+            const want = (args[0] ?? '').toLowerCase();
+            if (want === 'plan' || want === 'agent') {
+                agent.setMode(want);
+                console.log(successLine(`Mode set to ${modeTag(want)}.`));
+            }
+            else if (want) {
+                console.log(errorLine('Usage: /mode [plan|agent]'));
+            }
+            else {
+                console.log(infoLine(`Current mode: ${modeTag(agent.getMode())}  ${c.muted('· Shift+Tab to toggle')}`));
+            }
+            return true;
+        }
+        case 'usage': {
+            if (!isLoggedIn(config)) {
+                console.log(infoLine('Not signed in. Run /login to connect your ikie account.'));
+                return true;
+            }
+            const apiKey = getApiKey(config);
+            if (!apiKey) {
+                console.log(errorLine('No API key found. Run /login again.'));
+                return true;
+            }
+            try {
+                const res = await fetch(`${IKIE_HOST}/api/usage`, {
+                    headers: { Authorization: `Bearer ${apiKey}` },
+                });
+                if (!res.ok) {
+                    console.log(errorLine(`Couldn't fetch usage (HTTP ${res.status}).`));
+                    return true;
+                }
+                const data = (await res.json());
+                printUsage(data);
+            }
+            catch (err) {
+                console.log(errorLine(`Couldn't reach ikie at ${IKIE_HOST}: ${err instanceof Error ? err.message : String(err)}`));
+            }
+            return true;
+        }
         case 'exit':
         case 'quit':
         case 'q':
@@ -540,6 +590,43 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
             return true;
     }
 }
+function fmtUsd(n) {
+    if (n === 0)
+        return '$0.00';
+    if (n < 0.01)
+        return `$${n.toFixed(6)}`;
+    return `$${n.toFixed(2)}`;
+}
+function fmtTokens(n) {
+    if (n < 1000)
+        return String(n);
+    if (n < 1_000_000)
+        return (n / 1000).toFixed(1).replace(/\.0$/, '') + 'K';
+    return (n / 1_000_000).toFixed(2).replace(/\.00$/, '') + 'M';
+}
+function printUsage(data) {
+    const s = data.stats;
+    const row = (label, value) => console.log(`  ${c.secondary(label.padEnd(18))} ${c.white(value)}`);
+    console.log(`\n${c.primary.bold('Account Usage')}\n`);
+    row('Credit balance', c.success.bold(fmtUsd(data.balance)).toString());
+    row('Total spent', fmtUsd(s.totalCost));
+    console.log();
+    row('Requests · 30d', s.requests30d.toLocaleString());
+    row('Requests · 24h', s.requests24h.toLocaleString());
+    row('Requests · all', s.totalRequests.toLocaleString());
+    console.log();
+    row('Total tokens', fmtTokens(s.totalTokens));
+    row('Read / Write', `${fmtTokens(s.readTokens)} / ${fmtTokens(s.writeTokens)}`);
+    row('Cached tokens', fmtTokens(s.cachedTokens));
+    console.log();
+    row('Avg latency', s.avgLatencyMs ? `${s.avgLatencyMs}ms` : '—');
+    row('Cache hit rate', `${(s.cacheHitRate * 100).toFixed(1)}%`);
+    if (data.model) {
+        row('Model', data.model.name);
+        row('Context window', `${data.model.context_window.toLocaleString()} tokens`);
+    }
+    console.log(`\n  ${c.muted('Full dashboard:')} ${c.info(`${IKIE_HOST}/dashboard`)}\n`);
+}
 function promptLine(prompt) {
     return new Promise((resolve) => {
         const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -549,6 +636,30 @@ function promptLine(prompt) {
         });
     });
 }
+/**
+ * After a plan-mode turn, ask whether to execute the proposed plan.
+ * Reads a single keypress. Assumes stdin is already in raw mode (it is, during
+ * a turn). Returns true on y / Enter, false otherwise.
+ */
+function confirmExecutePlan() {
+    return new Promise((resolve) => {
+        if (!process.stdin.isTTY) {
+            resolve(false);
+            return;
+        }
+        process.stdout.write(`\n  ${c.primary('▸')} ${c.white.bold('Plan ready.')} ${c.muted('Execute it now?')}  ` +
+            `${c.success.bold('y')} ${c.muted('yes')}   ${c.error.bold('n')} ${c.muted('keep planning')}\n` +
+            `  ${c.muted('❯')} `);
+        const onKey = (d) => {
+            process.stdin.removeListener('data', onKey);
+            const k = d.toString().toLowerCase();
+            const yes = k === 'y' || k === '\r' || k === '\n';
+            process.stdout.write(yes ? c.success('y\n') : c.muted('n\n'));
+            resolve(yes);
+        };
+        process.stdin.on('data', onKey);
+    });
+}
 function printGoodbye(sessionState, agent, config) {
     const msgs = agent.getConversation();
     const hasConversation = msgs.length > 0;
@@ -562,15 +673,11 @@ function printGoodbye(sessionState, agent, config) {
         }
     }
     console.log(`\n${c.primary.bold('Goodbye!')}\n`);
-    if (sessionState.activeName) {
-        console.log(`  ${c.muted('Your session')} ${c.secondary.bold(sessionState.activeName)} ${c.muted('has been saved.')}`);
-        console.log(`\n  ${c.muted('To continue:')}`);
-        console.log(`    ${c.accent('ikie')} ${c.warning(`/session load ${sessionState.activeName}`)}\n`);
-    }
-    else if (hasConversation) {
-        console.log(`  ${c.warning('\u26A0')}  ${c.muted('Your current conversation was not saved.')}`);
-        console.log(`\n  ${c.muted('To save next time:')}`);
-        console.log(`    ${c.warning('/session save')} ${c.muted('<name>')}\n`);
+    if (sessionState.activeName && hasConversation) {
+        console.log(`  ${c.muted('Your session')} ${c.secondary.bold(sessionState.activeName)} ${c.muted('was saved.')}`);
+        console.log(`\n  ${c.muted('To pick up where you left off:')}`);
+        console.log(`    ${c.accent('ikie')} ${c.warning(`/session load ${sessionState.activeName}`)}`);
+        console.log(`\n  ${c.muted('Or list everything with')} ${c.warning('/session list')}\n`);
     }
     console.log(`  ${c.muted('Happy coding!')}\n`);
 }
@@ -677,7 +784,11 @@ function selectThemeInteractively(rl, config) {
 }
 export async function startREPL(agent, config, projectContext, oneShot) {
     void HISTORY_FILE;
-    if (oneShot) {
+    // A `/`-prefixed launch arg (e.g. `ikie /session load foo`) is a slash
+    // COMMAND, not a prompt — run it after setup, then stay interactive.
+    // A plain launch arg is a one-shot prompt: run it once and exit.
+    const initialCommand = oneShot && oneShot.trim().startsWith('/') ? oneShot.trim() : undefined;
+    if (oneShot && !initialCommand) {
         try {
             await agent.send(oneShot, { autoApprove: config.autoApprove });
         }
@@ -699,7 +810,9 @@ export async function startREPL(agent, config, projectContext, oneShot) {
     let multilineBuffer = '';
     let busy = false;
     let ctrlCCount = 0;
-    const sessionState = {};
+    // Every session auto-saves. Start with a generated name so there's always
+    // somewhere to persist to; /session load can resume it later.
+    const sessionState = { activeName: normalizeSessionName() };
     const imageState = { nextId: 1, pending: [] };
     let pasteSeq = 0;
     let pasteMode = false;
@@ -731,6 +844,18 @@ export async function startREPL(agent, config, projectContext, oneShot) {
     };
     const routeInputData = (data) => {
         const text = data.toString('utf8');
+        // Shift+Tab (CSI Z) → cycle agent⇄plan mode live at the prompt.
+        if (text === '\x1b[Z') {
+            const next = agent.getMode() === 'agent' ? 'plan' : 'agent';
+            agent.setMode(next);
+            const saved = rl.line || '';
+            process.stdout.write('\r\x1b[2K'); // clear the current prompt line
+            process.stdout.write(`  ${c.muted('▸')} ${modeTag(next)} ${c.muted('mode')}\n`);
+            printPromptHeader(next);
+            rl.setPrompt(PROMPT);
+            process.stdout.write(rl.getPrompt() + saved);
+            return;
+        }
         // Check for Ctrl+V (0x16) - try to paste image from clipboard
         if (data.length === 1 && data[0] === 0x16) {
             // Check if clipboard has an image
@@ -813,7 +938,7 @@ export async function startREPL(agent, config, projectContext, oneShot) {
             rl.setPrompt(CONTINUE_PROMPT);
         }
         else {
-            printPromptHeader();
+            printPromptHeader(agent.getMode());
             if (imageState.pending.length) {
                 const labels = imageState.pending.map(image => `[Image #${image.id}]`).join(' ');
                 process.stdout.write(`${c.muted('   attached')} ${c.secondary(labels)}\n`);
@@ -883,8 +1008,10 @@ export async function startREPL(agent, config, projectContext, oneShot) {
         const userContent = buildUserContent(agentInput, imagesForTurn);
         imageState.pending = [];
         let restoredImages = false;
+        // Clear the (now-submitted) prompt line. The agent's InlineSpinner provides
+        // the "Working… · Esc to interrupt" feedback and clears itself when done, so
+        // we don't print a static line here (it would never get cleared).
         process.stdout.write('\r\x1b[2K');
-        process.stdout.write(`${c.muted('  Working. Press Esc to interrupt.')}\n`);
         busy = true;
         rl.pause();
         const taskStartedAt = Date.now();
@@ -926,6 +1053,24 @@ export async function startREPL(agent, config, projectContext, oneShot) {
             if (sessionState.activeName && !abortController.signal.aborted) {
                 saveSession(sessionState.activeName, config.model, agent.getConversation());
             }
+            // Plan mode: a plan was just proposed — offer to execute it.
+            if (agent.getMode() === 'plan' && !abortController.signal.aborted) {
+                process.stdin.removeListener('data', cancelHandler);
+                const go = await confirmExecutePlan();
+                process.stdin.on('data', cancelHandler);
+                if (go && !abortController.signal.aborted) {
+                    agent.setMode('agent');
+                    process.stdout.write(`  ${c.muted('→ switching to')} ${modeTag('agent')} ${c.muted('mode, executing…')}\n`);
+                    await agent.send('Execute the plan you just proposed. Make the changes now.', {
+                        autoApprove: config.autoApprove,
+                        signal: abortController.signal,
+                        startedAt: taskStartedAt,
+                    });
+                    if (sessionState.activeName && !abortController.signal.aborted) {
+                        saveSession(sessionState.activeName, config.model, agent.getConversation());
+                    }
+                }
+            }
         }
         catch (err) {
             if (!abortController.signal.aborted) {
@@ -944,13 +1089,16 @@ export async function startREPL(agent, config, projectContext, oneShot) {
             }
             const elapsed = formatElapsed(Date.now() - taskStartedAt);
             process.stdin.removeListener('data', cancelHandler);
-            if (process.stdin.isTTY)
-                process.stdin.setRawMode(false);
             process.stdin.pause();
             restoreStdinListeners(savedDataListeners, savedKeypressListeners);
             busy = false;
             ctrlCCount = 0;
             rl.resume();
+            // readline was created with terminal:true and owns echo while in raw mode.
+            // Re-enable raw mode (the turn's cancel handler may have toggled it) so the
+            // TTY doesn't also echo input — otherwise every line is echoed twice.
+            if (process.stdin.isTTY)
+                process.stdin.setRawMode(true);
             const status = abortController.signal.aborted
                 ? c.warning(formatTaskTimeline(agent, elapsed, 'cancelled'))
                 : taskFailed
@@ -964,5 +1112,15 @@ export async function startREPL(agent, config, projectContext, oneShot) {
     rl.on('line', (raw) => {
         chain = chain.then(() => handleLine(raw));
     });
+    // If launched with a slash command (e.g. `ikie /session load foo`), run it
+    // once now, then hand control to the user with the result already applied.
+    if (initialCommand) {
+        try {
+            await handleSlashCommand(initialCommand, agent, config, projectContext, rl, sessionState, imageState);
+        }
+        catch (err) {
+            console.error(errorLine(err instanceof Error ? err.message : String(err)));
+        }
+    }
     showPrompt();
 }

package/dist/theme.d.ts

@@ -38,7 +38,8 @@ export declare const c: {
 export declare function stripAnsi(str: string): string;
 export declare const BANNER_ROWS = 9;
 export declare function drawBanner(model: string): void;
-export declare function printPromptHeader(): void;
+export declare function modeTag(mode: 'agent' | 'plan'): string;
+export declare function printPromptHeader(mode?: 'agent' | 'plan'): void;
 export declare const PROMPT: string;
 export declare const CONTINUE_PROMPT: string;
 export declare class InlineSpinner {

package/dist/theme.js

@@ -182,6 +182,8 @@ function truncate(str, max) {
     return str.slice(0, Math.max(0, max - 3)) + '...';
 }
 function formatModel(model) {
+    if (!model)
+        return 'none';
     const parts = model.split('/');
     return parts[parts.length - 1] || model;
 }
@@ -248,22 +250,24 @@ export function drawBanner(model) {
         '',
         `${c.muted('/help')} ${c.muted('·')} ${c.muted('/theme')} ${c.muted('·')} ${c.muted('Esc cancels running work')}`,
     ];
-    process.stdout.write(c.muted('╭' + '─'.repeat(innerWidth) + '╮') + '\n');
+    process.stdout.write('\n');
     for (let i = 0; i < Math.max(art.length, meta.length); i++) {
         const artLine = art[i] ?? '';
         const artColored = chalk.hex(colors[i % colors.length]).bold(padVisible(artLine, artWidth));
-        const metaLine = meta[i] ? `  ${c.muted('│')}  ${meta[i]}` : '';
-        const row = `${artColored}${metaLine}`;
-        process.stdout.write(`${c.muted('│')} ${padVisible(row, innerWidth - 1)}${c.muted('│')}\n`);
+        const metaLine = meta[i] ? `   ${meta[i]}` : '';
+        process.stdout.write(`  ${artColored}${metaLine}\n`);
     }
-    process.stdout.write(c.muted('╰' + '─'.repeat(innerWidth) + '╯') + '\n');
+    process.stdout.write('\n');
 }
-export function printPromptHeader() {
+export function modeTag(mode) {
+    return mode === 'plan' ? c.warning.bold('plan') : c.success('agent');
+}
+export function printPromptHeader(mode = 'agent') {
     const cwdName = basename(process.cwd()) || '/';
     const branch = getGitBranchFast();
     const gitSegment = branch ? ` ${c.muted('on')} ${c.secondary(branch)}` : '';
     const themeSegment = ` ${c.muted('theme')} ${c.secondary(activeTheme.name)}`;
-    process.stdout.write(`\n${c.primary('╭─')} ${c.primary.bold('ikie')}${gitSegment}${themeSegment} ${c.muted('in')} ${c.accent(cwdName)}\n`);
+    process.stdout.write(`\n${c.primary('╭─')} ${c.primary.bold('ikie')} ${c.muted('·')} ${modeTag(mode)}${gitSegment}${themeSegment} ${c.muted('in')} ${c.accent(cwdName)}\n`);
 }
 export const PROMPT = c.primary('╰─❯ ');
 export const CONTINUE_PROMPT = c.primary('│  ');
@@ -326,21 +330,45 @@ export class InlineSpinner {
         this.draw();
     }
 }
+// Maps a tool name to a clean verb + a dot color reflecting its effect.
+// Read-only tools are calm (info), mutating tools warn, exec/agent stand out.
+function toolMeta(rawName) {
+    const base = rawName.split(/\s|×/)[0];
+    switch (base) {
+        case 'read_file': return { verb: 'read', tint: c.info };
+        case 'write_file': return { verb: 'write', tint: c.warning };
+        case 'edit_file': return { verb: 'edit', tint: c.warning };
+        case 'bash': return { verb: 'run', tint: c.accent };
+        case 'list_dir': return { verb: 'list', tint: c.info };
+        case 'grep': return { verb: 'grep', tint: c.info };
+        case 'search_files': return { verb: 'find', tint: c.info };
+        case 'memory_write': return { verb: 'memory', tint: c.secondary };
+        case 'spawn_agent': return { verb: 'agent', tint: c.secondary };
+        case 'ask_user': return { verb: 'ask', tint: c.info };
+        default: return { verb: base, tint: c.primary };
+    }
+}
 export function toolLine(name, args) {
-    const tag = name === 'read_file' ? 'READ' :
-        name === 'write_file' ? 'WRITE' :
-            name === 'edit_file' ? 'EDIT' :
-                name === 'bash' ? 'EXEC' :
-                    name === 'list_dir' ? 'LIST' :
-                        name === 'grep' || name === 'search_files' ? 'FIND' : 'TOOL';
-    return `${c.primary('╭─')} ${c.accent.bold(`[${tag}]`)} ${c.warning.bold(name)}${c.muted('(')}${c.accent(args)}${c.muted(')')}`;
+    const { verb, tint } = toolMeta(name);
+    // Surface a "×N" batch suffix as a subtle count badge.
+    const countMatch = name.match(/×(\d+)/);
+    const badge = countMatch ? ` ${c.muted(`×${countMatch[1]}`)}` : '';
+    const label = c.white.bold(verb.padEnd(6));
+    return `${tint('●')} ${label}${badge} ${c.dim(args)}`;
 }
 export function toolSuccessLine(ms, preview) {
-    const tail = preview ? ` ${c.muted('│')} ${c.dim(preview)}` : '';
-    return `${c.primary('╰─')} ${c.success('ok')} ${c.muted(`${ms}ms`)}${tail}`;
+    const time = c.muted(formatDuration(ms));
+    const tail = preview ? `  ${c.dim(preview)}` : '';
+    return `  ${c.muted('⎿')} ${time}${tail}`;
 }
 export function toolErrorLine(msg) {
-    return `${c.primary('╰─')} ${c.error('err')} ${c.error(msg)}`;
+    return `  ${c.muted('⎿')} ${c.error('failed')} ${c.error(msg)}`;
+}
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const s = ms / 1000;
+    return s < 10 ? `${s.toFixed(1)}s` : `${Math.round(s)}s`;
 }
 export function successLine(msg) {
     return `  ${c.success('ok')} ${c.muted(msg)}`;
@@ -355,11 +383,12 @@ export function infoLine(msg) {
     return `  ${c.info('info')} ${c.muted(msg)}`;
 }
 export function permissionPrompt(toolName, preview) {
-    return (`\n  ${c.primary('╭─')} ${c.warning.bold('permission')} ${c.white.bold('Allow')} ${c.warning.bold(toolName)}${c.muted('?')}\n` +
-        `  ${c.primary('│')}  ${c.muted(preview)}\n` +
-        `  ${c.primary('│')}  ${c.muted('[')}${c.success.bold('y')}${c.muted(']')} allow  ` +
-        `${c.muted('[')}${c.error.bold('n')}${c.muted(']')} deny  ` +
-        `${c.muted('[')}${c.info.bold('a')}${c.muted(']')} always allow  ` +
-        `${c.muted('[')}${c.muted.bold('!')}${c.muted(']')} always deny\n` +
-        `  ${c.primary('╰─❯')} `);
+    const { verb, tint } = toolMeta(toolName);
+    return (`\n  ${tint('●')} ${c.white.bold('permission')} ${c.muted('·')} ${c.white(verb)} ${c.dim(preview)}\n` +
+        `  ${c.muted('⎿')} ` +
+        `${c.success.bold('y')} ${c.muted('allow')}   ` +
+        `${c.error.bold('n')} ${c.muted('deny')}   ` +
+        `${c.info.bold('a')} ${c.muted('always')}   ` +
+        `${c.muted.bold('!')} ${c.muted('never')}\n` +
+        `  ${c.muted('❯')} `);
 }

package/dist/tools.d.ts

@@ -1,5 +1,6 @@
 import type OpenAI from 'openai';
 export declare const TOOL_DEFS: OpenAI.Chat.ChatCompletionTool[];
 export declare const SAFE_TOOLS: Set<string>;
+export declare const PLAN_TOOLS: Set<string>;
 export declare function formatToolArgs(name: string, input: Record<string, unknown>): string;
 export declare function executeTool(name: string, input: Record<string, unknown>): Promise<string>;

package/dist/tools.js

@@ -167,11 +167,45 @@ export const TOOL_DEFS = [
             },
         },
     },
+    {
+        type: 'function',
+        function: {
+            name: 'fetch_url',
+            description: 'Fetch a web page (or any URL) over HTTP(S) and return its readable text content. HTML is stripped to plain text; JSON and plain-text responses are returned as-is. Use this to read documentation, articles, or API responses from the web.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    url: { type: 'string', description: 'The URL to fetch. If no scheme is given, https:// is assumed.' },
+                    max_chars: { type: 'number', description: 'Maximum characters to return (default 10000). The result is truncated past this.' },
+                },
+                required: ['url'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'web_search',
+            description: 'Search the web and return a list of results (title, URL, snippet). Requires a search API key configured in the environment (BRAVE_API_KEY, or GOOGLE_API_KEY + GOOGLE_CX). If no key is configured the tool reports that and returns no results — pair it with fetch_url to read a result page in full.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'The search query.' },
+                    count: { type: 'number', description: 'Number of results to return (default 5, max 10).' },
+                },
+                required: ['query'],
+            },
+        },
+    },
 ];
 // ─── Safe tools (auto-approved) ───────────────────────────────────────────────
 // spawn_agent is "safe" at the dispatch layer — the tools the sub-agent itself
 // runs go through their own approval inside the sub-agent loop.
-export const SAFE_TOOLS = new Set(['read_file', 'list_dir', 'search_files', 'grep', 'memory_write', 'spawn_agent', 'ask_user']);
+export const SAFE_TOOLS = new Set(['read_file', 'list_dir', 'search_files', 'grep', 'memory_write', 'spawn_agent', 'ask_user', 'fetch_url', 'web_search']);
+// Tools available in PLAN mode — read-only exploration plus delegation/questions.
+// Everything that mutates the filesystem or runs commands (write_file, edit_file,
+// bash, memory_write) is intentionally excluded so plan mode can only research.
+export const PLAN_TOOLS = new Set(['read_file', 'list_dir', 'search_files', 'grep', 'spawn_agent', 'ask_user', 'fetch_url', 'web_search']);
 // ─── Display helpers ──────────────────────────────────────────────────────────
 export function formatToolArgs(name, input) {
     const p = (v) => v != null && v !== 'undefined' ? String(v) : '(missing)';
@@ -202,6 +236,12 @@ export function formatToolArgs(name, input) {
             const task = String(input.task ?? '');
             return `"${task.length > 56 ? task.slice(0, 56) + '…' : task}"`;
         }
+        case 'fetch_url':
+            return `"${p(input.url)}"`;
+        case 'web_search': {
+            const q = String(input.query ?? '');
+            return `"${q.length > 56 ? q.slice(0, 56) + '…' : q}"`;
+        }
         default:
             return JSON.stringify(input).slice(0, 80);
     }
@@ -466,6 +506,112 @@ async function memoryWrite(input) {
         return `Error saving to ${scope} memory: ${msg}`;
     }
 }
+// ─── Web ──────────────────────────────────────────────────────────────────────
+function htmlToText(html) {
+    return html
+        // Drop non-content blocks entirely.
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/<(script|style|noscript|head|svg)[\s\S]*?<\/\1>/gi, '')
+        // Turn block-level boundaries into newlines so text doesn't run together.
+        .replace(/<\/(p|div|section|article|header|footer|li|tr|h[1-6]|ul|ol|table|blockquote)>/gi, '\n')
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<li[^>]*>/gi, '\n• ')
+        // Strip all remaining tags.
+        .replace(/<[^>]+>/g, '')
+        // Decode the handful of entities that actually matter.
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;|&apos;/gi, "'")
+        .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+        // Collapse whitespace and excess blank lines.
+        .replace(/[ \t]+/g, ' ')
+        .replace(/\n[ \t]+/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+async function fetchUrl(input) {
+    let url = (input.url ?? '').trim();
+    if (!url || url === 'undefined')
+        return 'Error: url is required for fetch_url';
+    if (!/^[a-z]+:\/\//i.test(url))
+        url = `https://${url}`;
+    const maxChars = input.max_chars && input.max_chars > 0 ? input.max_chars : 10000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 15000);
+    try {
+        const res = await fetch(url, {
+            redirect: 'follow',
+            signal: controller.signal,
+            headers: {
+                'User-Agent': 'Mozilla/5.0 (compatible; IkieBot/1.0; +https://ikie.dev)',
+                Accept: 'text/html,application/xhtml+xml,application/json;q=0.9,text/plain;q=0.8,*/*;q=0.5',
+            },
+        });
+        if (!res.ok)
+            return `Error: HTTP ${res.status} ${res.statusText} for ${url}`;
+        const contentType = res.headers.get('content-type') ?? '';
+        const body = await res.text();
+        const text = /text\/html|application\/xhtml/i.test(contentType) ? htmlToText(body) : body.trim();
+        const header = `URL: ${res.url}\nContent-Type: ${contentType || 'unknown'}\n\n`;
+        if (!text)
+            return `${header}(empty response)`;
+        if (text.length > maxChars) {
+            return `${header}${text.slice(0, maxChars)}\n\n…[truncated ${text.length - maxChars} more chars]`;
+        }
+        return `${header}${text}`;
+    }
+    catch (err) {
+        const e = err;
+        if (e.name === 'AbortError')
+            return `Error: request to ${url} timed out after 15s`;
+        return `Error fetching ${url}: ${e.message ?? err}`;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function webSearch(input) {
+    const query = (input.query ?? '').trim();
+    if (!query || query === 'undefined')
+        return 'Error: query is required for web_search';
+    const count = Math.min(Math.max(input.count ?? 5, 1), 10);
+    // Load account key at call time (same pattern as memoryWrite's dynamic import).
+    const { loadConfig, getApiKey, IKIE_API_BASE } = await import('./config.js');
+    const apiKey = getApiKey(loadConfig());
+    if (!apiKey) {
+        return 'web_search requires an ikie account. Sign in with `ikie login` — search is included with your account.';
+    }
+    try {
+        const u = new URL(`${IKIE_API_BASE}/search`);
+        u.searchParams.set('q', query);
+        u.searchParams.set('count', String(count));
+        const res = await fetch(u, {
+            headers: { Authorization: `Bearer ${apiKey}`, Accept: 'application/json' },
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => res.statusText);
+            return `Error: web_search HTTP ${res.status}: ${body}`;
+        }
+        const data = await res.json();
+        return formatSearchResults(query, data.results ?? []);
+    }
+    catch (err) {
+        const e = err;
+        return `Error during web_search: ${e.message ?? err}`;
+    }
+}
+function formatSearchResults(query, results) {
+    if (!results.length)
+        return `No results for "${query}".`;
+    const lines = results.map((r, i) => {
+        const snippet = (r.snippet ?? '').replace(/\s+/g, ' ').trim();
+        return `${i + 1}. ${r.title ?? '(untitled)'}\n   ${r.url ?? ''}${snippet ? `\n   ${snippet}` : ''}`;
+    });
+    return `Results for "${query}":\n\n${lines.join('\n\n')}`;
+}
 // ─── Dispatcher ───────────────────────────────────────────────────────────────
 export async function executeTool(name, input) {
     switch (name) {
@@ -477,6 +623,8 @@ export async function executeTool(name, input) {
         case 'search_files': return searchFiles(input);
         case 'grep': return grepFiles(input);
         case 'memory_write': return memoryWrite(input);
+        case 'fetch_url': return fetchUrl(input);
+        case 'web_search': return webSearch(input);
         default: return `Unknown tool: ${name}`;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ikie-cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Agentic coding CLI — your terminal AI pair programmer",
   "type": "module",
   "bin": {