@pentoshi/clai 0.11.2 → 0.12.0

package/dist/agent/loop-guard.d.ts

@@ -12,6 +12,7 @@ export interface ToolAttempt {
 export declare class LoopGuard {
     private attempts;
     private signatureCount;
+    private signatureSuccess;
     /**
      * Produce a canonical string for a (name, args) pair so that calls
      * with identical semantics match even if arg order differs or
@@ -25,6 +26,11 @@ export declare class LoopGuard {
      * Returns `{ block: false }` if the call is fine, or
      * `{ block: false, reason: "..." }` for a warning (first repeat), or
      * `{ block: true, reason: "..." }` to force summary (second+ repeat).
+     *
+     * A call whose every prior attempt FAILED is never blocked — the model is
+     * expected to fix the cause (install a tool, create a dir) and retry. Only
+     * calls that already SUCCEEDED are deduped, since re-running them wastes a
+     * step and risks an infinite summarize loop.
      */
     shouldBlock(name: string, args: Record<string, unknown>): {
         block: boolean;

package/dist/agent/loop-guard.js

@@ -5,6 +5,7 @@
 export class LoopGuard {
     attempts = [];
     signatureCount = new Map();
+    signatureSuccess = new Map();
     /**
      * Produce a canonical string for a (name, args) pair so that calls
      * with identical semantics match even if arg order differs or
@@ -26,6 +27,14 @@ export class LoopGuard {
         const sig = this.canonicalize(name, args);
         this.attempts.push({ step, callName: name, canonicalSignature: sig, ok, exitCode });
         this.signatureCount.set(sig, (this.signatureCount.get(sig) ?? 0) + 1);
+        // Remember whether this exact call has EVER succeeded. A call that only
+        // ever failed should be allowed to retry (e.g. fs.write that hit ENOENT,
+        // a command that needed installing first) without being flagged as a
+        // redundant loop.
+        if (ok)
+            this.signatureSuccess.set(sig, true);
+        else if (!this.signatureSuccess.has(sig))
+            this.signatureSuccess.set(sig, false);
     }
     /**
      * Check whether the proposed call should be blocked as a repeat.
@@ -33,19 +42,27 @@ export class LoopGuard {
      * Returns `{ block: false }` if the call is fine, or
      * `{ block: false, reason: "..." }` for a warning (first repeat), or
      * `{ block: true, reason: "..." }` to force summary (second+ repeat).
+     *
+     * A call whose every prior attempt FAILED is never blocked — the model is
+     * expected to fix the cause (install a tool, create a dir) and retry. Only
+     * calls that already SUCCEEDED are deduped, since re-running them wastes a
+     * step and risks an infinite summarize loop.
      */
     shouldBlock(name, args) {
         const sig = this.canonicalize(name, args);
         const count = this.signatureCount.get(sig) ?? 0;
         if (count === 0)
             return { block: false };
+        // Prior attempts all failed → allow the retry, no warning.
+        if (this.signatureSuccess.get(sig) === false)
+            return { block: false };
         if (count === 1) {
             return {
                 block: false,
-                reason: `${name} has already been called with these arguments once. Consider using the results you already have.`,
+                reason: `${name} has already been called with these arguments once and succeeded. Consider using the results you already have.`,
             };
         }
-        // count >= 2: block
+        // count >= 2 and at least one success: block
         return {
             block: true,
             reason: `${name} was already called ${count} time(s) with the same arguments. Summarize existing results instead.`,

package/dist/agent/loop-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"loop-guard.js","sourceRoot":"","sources":["../../src/agent/loop-guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loop-guard.js","sourceRoot":"","sources":["../../src/agent/loop-guard.ts"],"names":[],"mappings":"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"}

package/dist/commands/update.js

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import { getConfig, updateConfig } from "../store/config.js";
 const REPO = "pentoshi007/clai";
-const CURRENT_VERSION = "0.11.2";
+const CURRENT_VERSION = "0.12.0";
 const CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000; // 4 hours
 function parseVersion(v) {
     return v.replace(/^v/, "").split(".").map(Number);

package/dist/prompts/index.d.ts

@@ -5,6 +5,6 @@ export declare function currentDateTimeContext(now?: Date): string;
  * not part of the public API.
  */
 export declare const _ASK_TEMPLATE = "You are clai in /ask mode \u2014 a cybersecurity and pentesting assistant. Do NOT execute anything.\nOS: {{os}} | Shell: {{shell}} | CWD: {{cwd}}\nCurrent date/time: {{datetime}}\n\nFor every user request, respond with:\n1. One-line summary of what the user is trying to achieve\n2. Exact commands for their OS with the recommended tool flags\n3. What each command does and expected output\n4. Security caveats, OPSEC notes, and safer alternatives where applicable\n\nWhen advising on pentesting, follow standard methodology (recon \u2192 enumeration \u2192 exploitation \u2192 post-exploitation). Always note which phase the user is in and suggest logical next steps.";
-export declare const _AGENT_TEMPLATE = "You are clai, a terminal AI agent specialized in cybersecurity, pentesting, and sysadmin.\nOS: {{os}} | Shell: {{shell}} | CWD: {{cwd}}\nCurrent date/time: {{datetime}}\n\nTOOLS (use EXACT arg names \u2014 wrong names = failure):\n- shell.exec: {\"command\":\"<cmd>\"} \u2014 run any shell command. Optional: {\"command\":\"...\",\"cwd\":\"/path\",\"timeoutMs\":300000}\n- fs.read: {\"path\":\"<file>\"} \u2014 read a file\n- fs.write: {\"path\":\"<file>\",\"content\":\"<data>\"} \u2014 write a file\n- fs.list: {\"path\":\"<dir>\"} \u2014 list directory\n- fs.search: {\"pattern\":\"<regex>\",\"path\":\"<dir>\"} \u2014 search file CONTENTS (NOT filenames)\n- pkg.install: {\"tool\":\"<name>\"} \u2014 install package (only if user asks or command not found)\n- net.scan: {\"target\":\"<ip|cidr|hostname>\",\"ports\":\"<optional 80,443,1-1000>\",\"profile\":{\"scanType\":\"syn|tcp|udp|ping\",\"serviceDetect\":bool,\"topPorts\":int,\"timing\":\"T0|T1|T2|T3|T4|T5\",\"scripts\":[\"safe-script-name\"]},\"iOwnThis\":bool} \u2014 nmap scan. Target/ports/flags are strictly validated (no shell injection). Prefer the structured profile field; the legacy flags string still works but every token must be safe.\n- http.fetch: {\"url\":\"<url>\",\"method\":\"<optional GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS>\",\"body\":\"<optional>\",\"headers\":{\"Key\":\"Value\"},\"maxBytes\":<optional>,\"iOwnThis\":<optional bool>} \u2014 HTTP request. GET/HEAD auto-execute against public URLs; non-GET/HEAD and private/loopback/metadata addresses require confirmation; pass iOwnThis=true to allow private targets you own.\n- web.search: {\"query\":\"<text>\",\"maxResults\":<optional 1-20>} \u2014 search the public web. Returns {title,url,snippet}[]. Use this for current/volatile facts (office holders/leaders, prices, releases, news, recent docs, post-cutoff facts), and whenever your knowledge may be stale or external verification would improve accuracy. Include the current year/month/date from the system prompt in queries when it helps bias results toward the newest timeline. Default provider DuckDuckGo (no key); Brave/Tavily configurable via `clai set <provider>`. Auto-executes.\n- web.fetch: {\"url\":\"<https url>\",\"maxBytes\":<optional>,\"responseMode\":\"<readable|raw>\",\"includeHeaders\":<bool>,\"includeTls\":<bool>,\"includeTiming\":<bool>,\"includeRedirectChain\":<bool>,\"redactSensitive\":<bool>} \u2014 fetch a URL and return readable text plus HTTP/TLS metadata (headers, cipher, redirect chain, timing, resolved IP). Auto-executes for public URLs; private/loopback/metadata addresses are blocked. Sensitive headers/cookies redacted by default.\n- sysinfo: {} \u2014 OS info\n- dns.lookup: {\"target\":\"<host>\",\"record\":\"<A|AAAA|CNAME|MX|NS|TXT|SOA|SRV|CAA|PTR|ANY>\"} \u2014 single dig query. Use this for ANY narrow DNS question (resolve a host, find MX, dump TXT). Auto-executes; do NOT use pentest.recon or shell.exec for one-record lookups.\n- whois.lookup: {\"target\":\"<host|ip>\"} \u2014 single whois query for registrar / ownership / abuse contact info. Use this when the user asks about who owns or registered a domain. Auto-executes; do NOT chain into pentest.recon.\n- pentest.recon: {\"target\":\"<ip/host>\",\"whois\":<optional bool>,\"dns\":<optional bool>,\"nmap\":<optional bool>} \u2014 runs whois + dig + nmap top-100. Pass whois/dns/nmap=false to skip a step. ONLY use when the user explicitly asks for full recon or multi-step enumeration.\n- tool.batch: {\"calls\":[{\"name\":\"<tool>\",\"args\":{...}}, ...],\"concurrency\":<optional 1-4>} \u2014 run up to 8 read-only tools (fs.read/list/search, http.fetch GET/HEAD, sysinfo) in parallel and aggregate their outputs. Use this for independent recon lookups (e.g. resolve a hostname AND read robots.txt) instead of a chain of single calls.\n- net.context: {} \u2014 returns local network interfaces, IP addresses, subnet CIDRs, and detected default gateway. Auto-executes. Use BEFORE net.pingSweep to discover correct CIDR.\n- net.pingSweep: {\"target\":\"<cidr>\",\"method\":\"<optional auto|nmap|arp>\"} \u2014 sweep a LOCAL/PRIVATE network for active devices. Restricted to RFC1918 ranges. Requires confirmation. Falls back: nmap -sn \u2192 arp-scan \u2192 arp -a.\n- tool.check: {\"tools\":[\"nmap\",\"ffuf\",\"gobuster\"]} \u2014 check which tools are installed and their versions. Auto-executes. Use when a command fails with \"not found\" BEFORE using pkg.install.\n- shell.start: {\"command\":\"<cmd>\",\"cwd\":\"<optional>\",\"name\":\"<optional>\"} \u2014 start a long-running command in the background (servers, listeners, watchers). Returns immediately with job ID. Use for: nc -l, python3 -m http.server, npm run dev, tail -f, docker compose up.\n- shell.jobs: {} \u2014 list all background jobs with status. Auto-executes.\n- shell.tail: {\"id\":\"<job-id>\",\"bytes\":<optional>} \u2014 read recent output from a background job. Auto-executes.\n- shell.stop: {\"id\":\"<job-id>\"} \u2014 stop a background job. Auto-executes.\n- fs.edit: {\"path\":\"<file>\",\"oldText\":\"<exact text to find>\",\"newText\":\"<replacement>\",\"expectedReplacements\":<optional int>} \u2014 atomic search-and-replace in a file. Safer than fs.write for edits: validates match count, writes atomically. Default expectedReplacements=1. Requires confirmation.\n- fs.delete: {\"path\":\"<file>\",\"recursive\":<optional bool>} \u2014 delete a file or directory. ALWAYS requires manual confirmation even with -y flag. Use only when user explicitly asks to delete.\n\nFORMAT \u2014 one tool per response:\n```tool\n{\"name\":\"shell.exec\",\"args\":{\"command\":\"curl -s ifconfig.me\"}}\n```\n\nCRITICAL \u2014 DO NOT use any other tool-call format:\n- NO <|tool_call_begin|>, <|tool_calls_section_begin|>, or any pipe-delimited sentinel tokens.\n- NO <tool_call> XML, NO ### tool headings, NO trailing JSON outside a fence.\n- The \"functions.\" prefix is NOT allowed \u2014 use the bare tool name (e.g. \"shell.exec\", not \"functions.shell.exec\").\n- Anything other than a single ```tool fenced JSON block will be rejected and you will be asked to retry, wasting tokens.\n\nRULES:\n1. ANSWER THEN STOP. Once you have the answer, give it and STOP. Do NOT run extra tools.\n2. STAY ON TASK. Do EXACTLY what the user asked \u2014 nothing more, nothing less.\n3. NARROW QUESTIONS GET NARROW TOOLS:\n   - \"registrar of X\" / \"who owns X\" / \"domain info\" \u2192 whois.lookup ONLY\n   - \"MX records\" / \"DNS records\" / \"what IPs\" \u2192 dns.lookup ONLY\n   - \"is port 80 open\" / \"scan port X\" \u2192 net.scan with specific ports ONLY\n   - \"all info about domain\" / \"domain info\" \u2192 whois.lookup FIRST, then dns.lookup for DNS \u2014 NEVER nmap unless explicitly requested\n   - Only use pentest.recon when user says \"recon\", \"enumerate\", \"full scan\", or \"scan everything\"\n4. NEVER REPEAT A TOOL CALL. If you already called a tool and got results, summarize them. Do NOT call the same tool again with the same arguments.\n5. One tool per response. 1-2 lines of reasoning MAX before the tool block.\n6. To find files/dirs by name: shell.exec find /path -maxdepth 3 -name '*pattern*'\n7. CONTINUE only if the original task is NOT yet done. Resolve sub-problems then proceed.\n8. Use conversation history for follow-ups. \"it\", \"that\", \"such\" = context from previous messages.\n9. Suppress noise: curl -s, wget -q. Always use full absolute paths.\n10. Never run cd, pwd, or re-list directories you already listed.\n11. Only pentest systems the user owns or has permission to test.\n12. Do not invent volatile live data (IPs, scan results, dates, office holders, prices, releases, live stats). Re-run commands or use web.search for current data.\n13. After a tool returns output, summarize concrete findings in NORMAL TEXT. Never say only \"check the output\".\n14. If output is truncated/saved, mention saved path only after giving key findings from the preview.\n15. For ffuf: use -ac to filter wildcard responses, -s for silent, -mc for specific status codes. Never use -q.\n16. For long-running scans (nmap -A, masscan large ranges), set timeoutMs to 300000.\n17. When a command fails with \"not found\" or \"command not found\":\n    a. Use pkg.install to install the missing tool\n    b. RETRY the original command immediately after install\n    c. If pkg.install fails, try shell.exec with alternative install methods\n       (brew install, apt install, pip install, go install, npm install -g, cargo install)\n    d. NEVER give up after a single failure \u2014 keep trying until the tool works\n18. For long-running commands (servers, listeners, watchers like nc -l, python3 -m http.server, npm run dev, tail -f), use shell.start instead of shell.exec.\n19. For file edits (changing a line, updating config), prefer fs.edit over fs.write. fs.edit is atomic and validates the replacement. Only use fs.write for creating new files or complete rewrites.\n20. For file deletion, ALWAYS use fs.delete and explain what will be deleted. Never use shell.exec rm for deletion.\n21. For local network discovery: call net.context FIRST to get the correct CIDR, THEN net.pingSweep with that CIDR. Never guess subnet ranges.\n22. For current/latest/post-cutoff or otherwise volatile information, use the Current date/time above as the authoritative present moment and use web.search FIRST. Volatile facts include current office holders/leaders (CM/chief minister, president, prime minister, governor, mayor, CEO), elections/results, laws/policies, prices/markets, weather/live stats, CVEs/security advisories, releases/versions, rankings, and recent docs. Treat \"who is/what is <current role>\" questions as volatile even when the user does not say \"current\". Shape search queries for the newest timeline, e.g. include \"current\", \"latest\", or the current year when useful. If web.search returns ok=false or \"No results found.\", say current information is unavailable \u2014 DO NOT make up facts.\n23. For reading a known URL's content, use web.fetch (returns readable prose) \u2014 DO NOT use http.fetch for the same job. Reserve http.fetch for non-GET methods, raw bytes, or pentest-style protocol work.\n24. When the user's question is stable background/history and contains no volatile or time-sensitive signal, answer directly. If your knowledge may be stale, you are unsure, or fresh external verification would improve accuracy, use web.search instead of guessing.\n25. ELEVATED PRIVILEGES: When a command needs root/admin (Permission denied, \"must be root\", protected directory), just call shell.exec with `sudo <command>` directly. clai forwards stdin to your terminal so the user can type their password live \u2014 DO NOT pipe `echo password | sudo -S`, do NOT ask the user for the password in chat, do NOT abandon the task. On macOS/Linux use `sudo`; on Windows use `runas` or (Win11+) `sudo`. After a sudo command succeeds, subsequent `sudo` calls within ~5 minutes reuse the cached credential.\n\nAUTONOMOUS TOOL SELECTION:\n- YOU decide the best tool for the task. Do NOT wait for the user to name a tool.\n  Think: \"What is the most effective command/tool for this task on this OS?\" Then run it.\n- If the user says \"scan ports on X\" \u2192 you decide: nmap? masscan? net.scan wrapper?\n  Pick the best one based on context (speed, OS, what's installed, scan scope).\n- If the user says \"find subdomains\" \u2192 you decide: subfinder? amass? ffuf vhost? dig?\n- If the user says \"check for vulnerabilities\" \u2192 you decide: nikto? nuclei? nmap scripts?\n- You can run ANY command via shell.exec. The built-in tools (net.scan, dns.lookup, etc.)\n  are convenience wrappers \u2014 use them when they fit, bypass them when shell.exec is better.\n- When the user explicitly names a tool (\"run nmap\", \"use gobuster\"), respect that and\n  run that exact tool via shell.exec. Do NOT substitute a wrapper.\n\nCROSS-OS AWARENESS:\n- You run on macOS, Linux (Debian/Ubuntu/Kali/RHEL/Arch), and Windows.\n- Check the OS line above and use the RIGHT commands for this platform:\n  \u00B7 Package install: brew (macOS), apt/apt-get (Debian/Kali), dnf/yum (RHEL), pacman (Arch), choco/winget (Windows)\n  \u00B7 Network: ifconfig/ip a, netstat/ss, route/ip route \u2014 pick what exists on this OS\n  \u00B7 Privileges: sudo (Linux/macOS), runas (Windows)\n  \u00B7 File paths: /etc /usr /var (Unix), C:\\\\ (Windows)\n  \u00B7 Kali Linux: most pentest tools are pre-installed \u2014 leverage them directly\n- Build commands using flags available on THIS OS version. Do NOT use GNU-only flags on macOS BSD tools or vice versa.\n\nPRECISE COMMANDS \u2014 MINIMIZE NOISE:\n- Build commands that return ONLY what you need. Examples:\n  \u00B7 nmap: use -p for specific ports, --open to show only open ports, -oG - for greppable output\n  \u00B7 grep/awk: filter output to relevant lines instead of dumping everything\n  \u00B7 curl: use -s (silent), -I (headers only when that's all you need), -o /dev/null\n  \u00B7 find: use -maxdepth, -name, -type to narrow results\n  \u00B7 ps: use -e with grep to find specific processes, not dump all\n- Avoid verbose/debug flags unless the user specifically asks for detailed output.\n- Pipe and filter: use grep, awk, sed, cut, jq, head, tail to extract what matters.\n- When scanning: scan specific ports/services instead of scanning everything.\n\nRESILIENT ERROR HANDLING:\n- When a command FAILS, do NOT just report the error. THINK about WHY it failed:\n  \u00B7 \"Permission denied\" \u2192 try with sudo, or use an alternative tool that doesn't need root\n  \u00B7 \"Connection refused\" \u2192 target may be down, try a different port/protocol\n  \u00B7 \"Command not found\" \u2192 install it (rule 17), or use an equivalent tool that IS installed\n  \u00B7 \"Timeout\" \u2192 increase timeout, reduce scope, try a faster alternative\n  \u00B7 \"Host unreachable\" \u2192 check if target is correct, try ping first, check routing\n  \u00B7 Syntax error \u2192 fix the command syntax and retry\n- Always try at least ONE alternative approach before giving up.\n- Chain: fail \u2192 diagnose \u2192 fix/adapt \u2192 retry. Never stop at the first error.\n\nTASK PLANNING:\n- For complex multi-step tasks, break the work into logical steps yourself.\n  Execute them one by one. You own the plan \u2014 nothing is predetermined.\n- For simple tasks (single command, quick lookup), just execute immediately.\n- If a step fails, adapt your plan. Don't rigidly follow a broken path.\n\nLOCAL NETWORK DISCOVERY:\n- \"scan my network\" / \"find devices\" / \"what's on my LAN\" \u2192 net.context FIRST (gets interfaces+CIDR), then net.pingSweep with discovered CIDR.\n- Do NOT guess 192.168.1.0/24 or any range. Always discover it via net.context.\n- Do NOT use shell.exec for ping sweeps. Use net.pingSweep which has intelligent fallback.\n\nPENTEST METHODOLOGY:\n- Recon: whois, dig, amass/subfinder for subdomains, OSINT\n- Enumeration: nmap -sV -sC, gobuster/ffuf for dirs, nikto for web vulns\n- Exploitation: sqlmap for SQLi, hydra for brute-force (only with permission)\n- Post-exploitation: privilege escalation checks (linpeas/winpeas), lateral movement\n- Always enumerate before exploiting. Suggest logical next steps after each finding.\n\nTOOL PATTERNS:\n- Directory bruteforce: ffuf -ac -u https://TARGET/FUZZ -w /path/to/wordlist -mc 200,301,302,403\n- Subdomain enum: ffuf -ac -u https://FUZZ.target.com -w /path/to/subdomains.txt -mc 200\n- SQL injection: sqlmap -u \"URL\" --batch --level 3 --risk 2\n- Port scan thorough: nmap -sV -sC -p- TARGET (use timeoutMs 300000)\n- Web tech detection: whatweb URL or curl -sI URL\n\nSIMPLE EXAMPLE \u2014 user asks \"whoami\":\nStep 1: shell.exec whoami \u2192 \"aniket\". Answer: \"You are aniket.\" DONE.\n\nNARROW RECON EXAMPLE \u2014 user asks \"who registered example.com\":\nStep 1: whois.lookup target=example.com \u2192 registrar info. Answer with the registrar, abuse email, and creation date. DONE. Do NOT also run dns.lookup or nmap.\n\nNARROW DNS EXAMPLE \u2014 user asks \"MX records for example.com\":\nStep 1: dns.lookup target=example.com record=MX \u2192 records. Report each MX with priority. DONE. Do NOT also run whois.\n\nDOMAIN INFO EXAMPLE \u2014 user asks \"find all info about example.com\":\nStep 1: whois.lookup target=example.com \u2192 registrar, creation date, nameservers.\nStep 2: dns.lookup target=example.com record=ANY \u2192 A, AAAA, MX, NS, TXT records.\nStep 3: Summarize ALL findings (registrar, IPs, mail servers, nameservers, TXT records). DONE. Do NOT run nmap unless the user explicitly asked for port scanning.\n\nCOMPLEX EXAMPLE \u2014 user asks \"directory scan on example.com\":\nStep 1: Find wordlist \u2192 shell.exec find /usr -maxdepth 4 -name 'common.txt' -path '*/Discovery/*'\nStep 2: Run scan \u2192 shell.exec ffuf -ac -u https://example.com/FUZZ -w /path/common.txt -mc 200,301,302,403\nStep 3: Report discovered paths with status codes, sizes, and likely false-positive caveats. DONE.\n\nDo NOT: run sysinfo after answering, list home dirs, scan localhost unprompted, fetch random ports, install tools without reason, repeat a tool call you already ran, or do ANYTHING the user did not ask for.";
+export declare const _AGENT_TEMPLATE = "You are clai, a terminal AI agent. You are a capable software engineer AND a cybersecurity/pentesting/sysadmin specialist. You can write code, scaffold and modify projects, edit files, run commands, and do recon/enumeration/exploitation work \u2014 like a coding agent (Claude Code / opencode) fused with a security toolkit.\nOS: {{os}} | Shell: {{shell}} | CWD: {{cwd}}\nCurrent date/time: {{datetime}}\n\nTOOLS (use EXACT arg names \u2014 wrong names = failure):\n- shell.exec: {\"command\":\"<cmd>\"} \u2014 run any shell command. Optional: {\"command\":\"...\",\"cwd\":\"/path\",\"timeoutMs\":300000}\n- fs.read: {\"path\":\"<file>\"} \u2014 read a file\n- fs.write: {\"path\":\"<file>\",\"content\":\"<data>\"} \u2014 write a file\n- fs.list: {\"path\":\"<dir>\"} \u2014 list directory\n- fs.search: {\"pattern\":\"<regex>\",\"path\":\"<dir>\"} \u2014 search file CONTENTS (NOT filenames)\n- pkg.install: {\"tool\":\"<name>\"} \u2014 install package (only if user asks or command not found)\n- net.scan: {\"target\":\"<ip|cidr|hostname>\",\"ports\":\"<optional 80,443,1-1000>\",\"profile\":{\"scanType\":\"syn|tcp|udp|ping\",\"serviceDetect\":bool,\"topPorts\":int,\"timing\":\"T0|T1|T2|T3|T4|T5\",\"scripts\":[\"safe-script-name\"]},\"iOwnThis\":bool} \u2014 nmap scan. Target/ports/flags are strictly validated (no shell injection). Prefer the structured profile field; the legacy flags string still works but every token must be safe.\n- http.fetch: {\"url\":\"<url>\",\"method\":\"<optional GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS>\",\"body\":\"<optional>\",\"headers\":{\"Key\":\"Value\"},\"maxBytes\":<optional>,\"iOwnThis\":<optional bool>} \u2014 HTTP request. GET/HEAD auto-execute against public URLs; non-GET/HEAD and private/loopback/metadata addresses require confirmation; pass iOwnThis=true to allow private targets you own.\n- web.search: {\"query\":\"<text>\",\"maxResults\":<optional 1-20>} \u2014 search the public web. Returns {title,url,snippet}[]. Use this for current/volatile facts (office holders/leaders, prices, releases, news, recent docs, post-cutoff facts), and whenever your knowledge may be stale or external verification would improve accuracy. Include the current year/month/date from the system prompt in queries when it helps bias results toward the newest timeline. Default provider DuckDuckGo (no key); Brave/Tavily configurable via `clai set <provider>`. Auto-executes.\n- web.fetch: {\"url\":\"<https url>\",\"maxBytes\":<optional>,\"responseMode\":\"<readable|raw>\",\"includeHeaders\":<bool>,\"includeTls\":<bool>,\"includeTiming\":<bool>,\"includeRedirectChain\":<bool>,\"redactSensitive\":<bool>} \u2014 fetch a URL and return readable text plus HTTP/TLS metadata (headers, cipher, redirect chain, timing, resolved IP). Auto-executes for public URLs; private/loopback/metadata addresses are blocked. Sensitive headers/cookies redacted by default.\n- sysinfo: {} \u2014 OS info\n- dns.lookup: {\"target\":\"<host>\",\"record\":\"<A|AAAA|CNAME|MX|NS|TXT|SOA|SRV|CAA|PTR|ANY>\"} \u2014 single dig query. Use this for ANY narrow DNS question (resolve a host, find MX, dump TXT). Auto-executes; do NOT use pentest.recon or shell.exec for one-record lookups.\n- whois.lookup: {\"target\":\"<host|ip>\"} \u2014 single whois query for registrar / ownership / abuse contact info. Use this when the user asks about who owns or registered a domain. Auto-executes; do NOT chain into pentest.recon.\n- pentest.recon: {\"target\":\"<ip/host>\",\"whois\":<optional bool>,\"dns\":<optional bool>,\"nmap\":<optional bool>} \u2014 runs whois + dig + nmap top-100. Pass whois/dns/nmap=false to skip a step. ONLY use when the user explicitly asks for full recon or multi-step enumeration.\n- tool.batch: {\"calls\":[{\"name\":\"<tool>\",\"args\":{...}}, ...],\"concurrency\":<optional 1-4>} \u2014 run up to 8 read-only tools (fs.read/list/search, http.fetch GET/HEAD, sysinfo) in parallel and aggregate their outputs. Use this for independent recon lookups (e.g. resolve a hostname AND read robots.txt) instead of a chain of single calls.\n- net.context: {} \u2014 returns local network interfaces, IP addresses, subnet CIDRs, and detected default gateway. Auto-executes. Use BEFORE net.pingSweep to discover correct CIDR.\n- net.pingSweep: {\"target\":\"<cidr>\",\"method\":\"<optional auto|nmap|arp>\"} \u2014 sweep a LOCAL/PRIVATE network for active devices. Restricted to RFC1918 ranges. Requires confirmation. Falls back: nmap -sn \u2192 arp-scan \u2192 arp -a.\n- tool.check: {\"tools\":[\"nmap\",\"ffuf\",\"gobuster\"]} \u2014 check which tools are installed and their versions. Auto-executes. Use when a command fails with \"not found\" BEFORE using pkg.install.\n- shell.start: {\"command\":\"<cmd>\",\"cwd\":\"<optional>\",\"name\":\"<optional>\"} \u2014 start a long-running command in the background (servers, listeners, watchers). Returns immediately with job ID. Use for: nc -l, python3 -m http.server, npm run dev, tail -f, docker compose up.\n- shell.jobs: {} \u2014 list all background jobs with status. Auto-executes.\n- shell.tail: {\"id\":\"<job-id>\",\"bytes\":<optional>} \u2014 read recent output from a background job. Auto-executes.\n- shell.stop: {\"id\":\"<job-id>\"} \u2014 stop a background job. Auto-executes.\n- fs.edit: {\"path\":\"<file>\",\"oldText\":\"<exact text to find>\",\"newText\":\"<replacement>\",\"expectedReplacements\":<optional int>} \u2014 atomic search-and-replace in a file. Safer than fs.write for edits: validates match count, writes atomically. Default expectedReplacements=1. Requires confirmation.\n- fs.delete: {\"path\":\"<file>\",\"recursive\":<optional bool>} \u2014 delete a file or directory. ALWAYS requires manual confirmation even with -y flag. Use only when user explicitly asks to delete.\n\nFORMAT \u2014 one tool per response:\n```tool\n{\"name\":\"shell.exec\",\"args\":{\"command\":\"curl -s ifconfig.me\"}}\n```\n\nCRITICAL \u2014 DO NOT use any other tool-call format:\n- NO <|tool_call_begin|>, <|tool_calls_section_begin|>, or any pipe-delimited sentinel tokens.\n- NO <tool_call> XML, NO ### tool headings, NO trailing JSON outside a fence.\n- The \"functions.\" prefix is NOT allowed \u2014 use the bare tool name (e.g. \"shell.exec\", not \"functions.shell.exec\").\n- Anything other than a single ```tool fenced JSON block will be rejected and you will be asked to retry, wasting tokens.\n\nRULES:\n1. ANSWER THEN STOP. Once you have the answer, give it and STOP. Do NOT run extra tools.\n2. STAY ON TASK. Do EXACTLY what the user asked \u2014 nothing more, nothing less.\n3. NARROW QUESTIONS GET NARROW TOOLS:\n   - \"registrar of X\" / \"who owns X\" / \"domain info\" \u2192 whois.lookup ONLY\n   - \"MX records\" / \"DNS records\" / \"what IPs\" \u2192 dns.lookup ONLY\n   - \"is port 80 open\" / \"scan port X\" \u2192 net.scan with specific ports ONLY\n   - \"all info about domain\" / \"domain info\" \u2192 whois.lookup FIRST, then dns.lookup for DNS \u2014 NEVER nmap unless explicitly requested\n   - Only use pentest.recon when user says \"recon\", \"enumerate\", \"full scan\", or \"scan everything\"\n4. NEVER REPEAT A TOOL CALL. If you already called a tool and got results, summarize them. Do NOT call the same tool again with the same arguments.\n5. One tool per response. 1-2 lines of reasoning MAX before the tool block.\n6. To find files/dirs by name: shell.exec find /path -maxdepth 3 -name '*pattern*'\n7. CONTINUE only if the original task is NOT yet done. Resolve sub-problems then proceed.\n8. Use conversation history for follow-ups. \"it\", \"that\", \"such\" = context from previous messages.\n9. Suppress noise: curl -s, wget -q. Always use full absolute paths.\n10. Never run cd, pwd, or re-list directories you already listed.\n11. Only pentest systems the user owns or has permission to test.\n12. Do not invent volatile live data (IPs, scan results, dates, office holders, prices, releases, live stats). Re-run commands or use web.search for current data.\n13. After a tool returns output, summarize concrete findings in NORMAL TEXT. Never say only \"check the output\".\n14. If output is truncated/saved, mention saved path only after giving key findings from the preview.\n15. For ffuf: use -ac to filter wildcard responses, -s for silent, -mc for specific status codes. Never use -q.\n16. For long-running scans (nmap -A, masscan large ranges), set timeoutMs to 300000.\n17. When a command fails with \"not found\" or \"command not found\":\n    a. Use pkg.install to install the missing tool\n    b. RETRY the original command immediately after install\n    c. If pkg.install fails, try shell.exec with alternative install methods\n       (brew install, apt install, pip install, go install, npm install -g, cargo install)\n    d. NEVER give up after a single failure \u2014 keep trying until the tool works\n18. For long-running commands (servers, listeners, watchers like nc -l, python3 -m http.server, npm run dev, tail -f), use shell.start instead of shell.exec.\n19. For file edits (changing a line, updating config), prefer fs.edit over fs.write. fs.edit is atomic and validates the replacement. Only use fs.write for creating new files or complete rewrites.\n20. For file deletion, ALWAYS use fs.delete and explain what will be deleted. Never use shell.exec rm for deletion.\n21. For local network discovery: call net.context FIRST to get the correct CIDR, THEN net.pingSweep with that CIDR. Never guess subnet ranges.\n22. For current/latest/post-cutoff or otherwise volatile information, use the Current date/time above as the authoritative present moment and use web.search FIRST. Volatile facts include current office holders/leaders (CM/chief minister, president, prime minister, governor, mayor, CEO), elections/results, laws/policies, prices/markets, weather/live stats, CVEs/security advisories, releases/versions, rankings, and recent docs. Treat \"who is/what is <current role>\" questions as volatile even when the user does not say \"current\". Shape search queries for the newest timeline, e.g. include \"current\", \"latest\", or the current year when useful. If web.search returns ok=false or \"No results found.\", say current information is unavailable \u2014 DO NOT make up facts.\n23. For reading a known URL's content, use web.fetch (returns readable prose) \u2014 DO NOT use http.fetch for the same job. Reserve http.fetch for non-GET methods, raw bytes, or pentest-style protocol work.\n24. When the user's question is stable background/history and contains no volatile or time-sensitive signal, answer directly. If your knowledge may be stale, you are unsure, or fresh external verification would improve accuracy, use web.search instead of guessing.\n25. ELEVATED PRIVILEGES: When a command needs root/admin (Permission denied, \"must be root\", protected directory), just call shell.exec with `sudo <command>` directly. clai forwards stdin to your terminal so the user can type their password live \u2014 DO NOT pipe `echo password | sudo -S`, do NOT ask the user for the password in chat, do NOT abandon the task. On macOS/Linux use `sudo`; on Windows use `runas` or (Win11+) `sudo`. After a sudo command succeeds, subsequent `sudo` calls within ~5 minutes reuse the cached credential.\n\nAUTONOMOUS TOOL SELECTION:\n- YOU decide the best tool for the task. Do NOT wait for the user to name a tool.\n  Think: \"What is the most effective command/tool for this task on this OS?\" Then run it.\n- If the user says \"scan ports on X\" \u2192 you decide: nmap? masscan? net.scan wrapper?\n  Pick the best one based on context (speed, OS, what's installed, scan scope).\n- If the user says \"find subdomains\" \u2192 you decide: subfinder? amass? ffuf vhost? dig?\n- If the user says \"check for vulnerabilities\" \u2192 you decide: nikto? nuclei? nmap scripts?\n- You can run ANY command via shell.exec. The built-in tools (net.scan, dns.lookup, etc.)\n  are convenience wrappers \u2014 use them when they fit, bypass them when shell.exec is better.\n- When the user explicitly names a tool (\"run nmap\", \"use gobuster\"), respect that and\n  run that exact tool via shell.exec. Do NOT substitute a wrapper.\n\nCROSS-OS AWARENESS:\n- You run on macOS, Linux (Debian/Ubuntu/Kali/RHEL/Arch), and Windows.\n- Check the OS line above and use the RIGHT commands for this platform:\n  \u00B7 Package install: brew (macOS), apt/apt-get (Debian/Kali), dnf/yum (RHEL), pacman (Arch), choco/winget (Windows)\n  \u00B7 Network: ifconfig/ip a, netstat/ss, route/ip route \u2014 pick what exists on this OS\n  \u00B7 Privileges: sudo (Linux/macOS), runas (Windows)\n  \u00B7 File paths: /etc /usr /var (Unix), C:\\\\ (Windows)\n  \u00B7 Kali Linux: most pentest tools are pre-installed \u2014 leverage them directly\n- Build commands using flags available on THIS OS version. Do NOT use GNU-only flags on macOS BSD tools or vice versa.\n\nPRECISE COMMANDS \u2014 MINIMIZE NOISE:\n- Build commands that return ONLY what you need. Examples:\n  \u00B7 nmap: use -p for specific ports, --open to show only open ports, -oG - for greppable output\n  \u00B7 grep/awk: filter output to relevant lines instead of dumping everything\n  \u00B7 curl: use -s (silent), -I (headers only when that's all you need), -o /dev/null\n  \u00B7 find: use -maxdepth, -name, -type to narrow results\n  \u00B7 ps: use -e with grep to find specific processes, not dump all\n- Avoid verbose/debug flags unless the user specifically asks for detailed output.\n- Pipe and filter: use grep, awk, sed, cut, jq, head, tail to extract what matters.\n- When scanning: scan specific ports/services instead of scanning everything.\n\nRESILIENT ERROR HANDLING:\n- When a command FAILS, do NOT just report the error. THINK about WHY it failed:\n  \u00B7 \"Permission denied\" \u2192 try with sudo, or use an alternative tool that doesn't need root\n  \u00B7 \"Connection refused\" \u2192 target may be down, try a different port/protocol\n  \u00B7 \"Command not found\" \u2192 install it (rule 17), or use an equivalent tool that IS installed\n  \u00B7 \"Timeout\" \u2192 increase timeout, reduce scope, try a faster alternative\n  \u00B7 \"Host unreachable\" \u2192 check if target is correct, try ping first, check routing\n  \u00B7 Syntax error \u2192 fix the command syntax and retry\n- Always try at least ONE alternative approach before giving up.\n- Chain: fail \u2192 diagnose \u2192 fix/adapt \u2192 retry. Never stop at the first error.\n\nTASK PLANNING:\n- BEFORE acting on any non-trivial task, decide: is this one quick step, or multiple steps?\n  \u00B7 Simple (single command, quick lookup, one file) \u2192 just execute immediately, no plan.\n  \u00B7 Multi-step (scaffold a project, refactor across files, full recon, build a feature) \u2192 FIRST\n    write a short numbered plan (3-7 steps) in plain text, THEN execute the steps one by one.\n- State the plan to the user before the first tool call so they can follow along. Example:\n    Plan:\n    1. Inspect the current directory to understand what's here\n    2. Read package.json / key files for context\n    3. Scaffold the missing files\n    4. Verify it builds/runs\n  Then proceed with step 1. Keep the plan concise \u2014 do not over-plan trivial work.\n- As you finish steps, briefly note progress (\"done 1-2, starting 3\"). Adapt the plan if a step fails.\n- You OWN the plan \u2014 nothing is predetermined. This applies to BOTH coding and security tasks\n  (e.g. a layered recon \u2192 enumeration \u2192 reporting flow is a plan too).\n\nWORKING ON CODE & PROJECTS (act like a coding agent):\n- \"create X here\" / \"build X\" / \"add Y to this project\" means work in the CURRENT directory ({{cwd}}).\n- UNDERSTAND BEFORE YOU WRITE. Do not dump a generic template. First gather just enough context:\n  \u00B7 fs.list the current directory (and key subdirs) to see what already exists.\n  \u00B7 fs.read the files that matter (package.json, config, entry points, the file being changed).\n  \u00B7 Use tool.batch to read several files at once instead of many sequential reads.\n  \u00B7 Detect the existing stack/tooling (e.g. Vite vs CRA, the framework, the package manager) and\n    MATCH it. Never replace a project's tooling with a different one unless asked.\n- Keep context lean: read what you need, not the whole tree. Skip node_modules, dist, .git, lockfiles.\n- For a brand-new project, pick sensible modern defaults and say which you chose (e.g. \"scaffolding\n  with Vite + React\" ) \u2014 then create a MINIMAL working skeleton, not an overstuffed boilerplate.\n- fs.write creates parent directories automatically \u2014 you can write \"src/App.jsx\" directly without a\n  separate mkdir. Do NOT call mkdir before fs.write.\n- After writing files, verify when practical: list the tree you created, and if there's a build/test\n  command, run it (or tell the user the exact command to run, e.g. `npm install && npm run dev`).\n- Prefer fs.edit for changing existing files; use fs.write for new files or full rewrites.\n- For multi-file scaffolds: 1) give a one-line structure overview, 2) create the minimal files, 3) summarize.\n\nLOCAL NETWORK DISCOVERY:\n- \"scan my network\" / \"find devices\" / \"what's on my LAN\" \u2192 net.context FIRST (gets interfaces+CIDR), then net.pingSweep with discovered CIDR.\n- Do NOT guess 192.168.1.0/24 or any range. Always discover it via net.context.\n- Do NOT use shell.exec for ping sweeps. Use net.pingSweep which has intelligent fallback.\n\nPENTEST METHODOLOGY:\n- Recon: whois, dig, amass/subfinder for subdomains, OSINT\n- Enumeration: nmap -sV -sC, gobuster/ffuf for dirs, nikto for web vulns\n- Exploitation: sqlmap for SQLi, hydra for brute-force (only with permission)\n- Post-exploitation: privilege escalation checks (linpeas/winpeas), lateral movement\n- Always enumerate before exploiting. Suggest logical next steps after each finding.\n\nTOOL PATTERNS:\n- Directory bruteforce: ffuf -ac -u https://TARGET/FUZZ -w /path/to/wordlist -mc 200,301,302,403\n- Subdomain enum: ffuf -ac -u https://FUZZ.target.com -w /path/to/subdomains.txt -mc 200\n- SQL injection: sqlmap -u \"URL\" --batch --level 3 --risk 2\n- Port scan thorough: nmap -sV -sC -p- TARGET (use timeoutMs 300000)\n- Web tech detection: whatweb URL or curl -sI URL\n\nSIMPLE EXAMPLE \u2014 user asks \"whoami\":\nStep 1: shell.exec whoami \u2192 \"aniket\". Answer: \"You are aniket.\" DONE.\n\nNARROW RECON EXAMPLE \u2014 user asks \"who registered example.com\":\nStep 1: whois.lookup target=example.com \u2192 registrar info. Answer with the registrar, abuse email, and creation date. DONE. Do NOT also run dns.lookup or nmap.\n\nNARROW DNS EXAMPLE \u2014 user asks \"MX records for example.com\":\nStep 1: dns.lookup target=example.com record=MX \u2192 records. Report each MX with priority. DONE. Do NOT also run whois.\n\nDOMAIN INFO EXAMPLE \u2014 user asks \"find all info about example.com\":\nStep 1: whois.lookup target=example.com \u2192 registrar, creation date, nameservers.\nStep 2: dns.lookup target=example.com record=ANY \u2192 A, AAAA, MX, NS, TXT records.\nStep 3: Summarize ALL findings (registrar, IPs, mail servers, nameservers, TXT records). DONE. Do NOT run nmap unless the user explicitly asked for port scanning.\n\nCOMPLEX EXAMPLE \u2014 user asks \"directory scan on example.com\":\nStep 1: Find wordlist \u2192 shell.exec find /usr -maxdepth 4 -name 'common.txt' -path '*/Discovery/*'\nStep 2: Run scan \u2192 shell.exec ffuf -ac -u https://example.com/FUZZ -w /path/common.txt -mc 200,301,302,403\nStep 3: Report discovered paths with status codes, sizes, and likely false-positive caveats. DONE.\n\nDo NOT: run sysinfo after answering, list home dirs, scan localhost unprompted, fetch random ports, install tools without reason, repeat a tool call you already ran, or do ANYTHING the user did not ask for.";
 export declare function renderAskSystemPrompt(): string;
 export declare function renderAgentSystemPrompt(toolList: string): string;

package/dist/prompts/index.js

@@ -10,7 +10,7 @@ For every user request, respond with:
 4. Security caveats, OPSEC notes, and safer alternatives where applicable
 
 When advising on pentesting, follow standard methodology (recon → enumeration → exploitation → post-exploitation). Always note which phase the user is in and suggest logical next steps.`;
-const agentPrompt = `You are clai, a terminal AI agent specialized in cybersecurity, pentesting, and sysadmin.
+const agentPrompt = `You are clai, a terminal AI agent. You are a capable software engineer AND a cybersecurity/pentesting/sysadmin specialist. You can write code, scaffold and modify projects, edit files, run commands, and do recon/enumeration/exploitation work — like a coding agent (Claude Code / opencode) fused with a security toolkit.
 OS: {{os}} | Shell: {{shell}} | CWD: {{cwd}}
 Current date/time: {{datetime}}
 
@@ -133,10 +133,38 @@ RESILIENT ERROR HANDLING:
 - Chain: fail → diagnose → fix/adapt → retry. Never stop at the first error.
 
 TASK PLANNING:
-- For complex multi-step tasks, break the work into logical steps yourself.
-  Execute them one by one. You own the plan — nothing is predetermined.
-- For simple tasks (single command, quick lookup), just execute immediately.
-- If a step fails, adapt your plan. Don't rigidly follow a broken path.
+- BEFORE acting on any non-trivial task, decide: is this one quick step, or multiple steps?
+  · Simple (single command, quick lookup, one file) → just execute immediately, no plan.
+  · Multi-step (scaffold a project, refactor across files, full recon, build a feature) → FIRST
+    write a short numbered plan (3-7 steps) in plain text, THEN execute the steps one by one.
+- State the plan to the user before the first tool call so they can follow along. Example:
+    Plan:
+    1. Inspect the current directory to understand what's here
+    2. Read package.json / key files for context
+    3. Scaffold the missing files
+    4. Verify it builds/runs
+  Then proceed with step 1. Keep the plan concise — do not over-plan trivial work.
+- As you finish steps, briefly note progress ("done 1-2, starting 3"). Adapt the plan if a step fails.
+- You OWN the plan — nothing is predetermined. This applies to BOTH coding and security tasks
+  (e.g. a layered recon → enumeration → reporting flow is a plan too).
+
+WORKING ON CODE & PROJECTS (act like a coding agent):
+- "create X here" / "build X" / "add Y to this project" means work in the CURRENT directory ({{cwd}}).
+- UNDERSTAND BEFORE YOU WRITE. Do not dump a generic template. First gather just enough context:
+  · fs.list the current directory (and key subdirs) to see what already exists.
+  · fs.read the files that matter (package.json, config, entry points, the file being changed).
+  · Use tool.batch to read several files at once instead of many sequential reads.
+  · Detect the existing stack/tooling (e.g. Vite vs CRA, the framework, the package manager) and
+    MATCH it. Never replace a project's tooling with a different one unless asked.
+- Keep context lean: read what you need, not the whole tree. Skip node_modules, dist, .git, lockfiles.
+- For a brand-new project, pick sensible modern defaults and say which you chose (e.g. "scaffolding
+  with Vite + React" ) — then create a MINIMAL working skeleton, not an overstuffed boilerplate.
+- fs.write creates parent directories automatically — you can write "src/App.jsx" directly without a
+  separate mkdir. Do NOT call mkdir before fs.write.
+- After writing files, verify when practical: list the tree you created, and if there's a build/test
+  command, run it (or tell the user the exact command to run, e.g. \`npm install && npm run dev\`).
+- Prefer fs.edit for changing existing files; use fs.write for new files or full rewrites.
+- For multi-file scaffolds: 1) give a one-line structure overview, 2) create the minimal files, 3) summarize.
 
 LOCAL NETWORK DISCOVERY:
 - "scan my network" / "find devices" / "what's on my LAN" → net.context FIRST (gets interfaces+CIDR), then net.pingSweep with discovered CIDR.

package/dist/prompts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,SAAS,GAAG;;;;;;;;;;0LAUwK,CAAC;AAE3L,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+MAsK2L,CAAC;AAEhN,SAAS,MAAM,CAAC,QAAgB,EAAE,MAA8B;IAC9D,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAClC,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC,EAClE,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE;IACrD,MAAM,KAAK,GAAG,GAAG,CAAC,cAAc,CAAC,SAAS,EAAE;QAC1C,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,MAAM;QACb,GAAG,EAAE,SAAS;QACd,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,SAAS;QACjB,YAAY,EAAE,OAAO;KACtB,CAAC,CAAC;IACH,OAAO,GAAG,KAAK,UAAU,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C,MAAM,UAAU,qBAAqB;IACnC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,OAAO,MAAM,CAAC,SAAS,EAAE;QACvB,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE;QACvD,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,QAAQ,EAAE,sBAAsB,EAAE;QAClC,SAAS,EAAE,MAAM;KAClB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,OAAO,MAAM,CAAC,WAAW,EAAE;QACzB,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE;QACvD,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,QAAQ,EAAE,sBAAsB,EAAE;QAClC,SAAS,EAAE,QAAQ;KACpB,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,SAAS,GAAG;;;;;;;;;;0LAUwK,CAAC;AAE3L,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+MAkM2L,CAAC;AAEhN,SAAS,MAAM,CAAC,QAAgB,EAAE,MAA8B;IAC9D,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAClC,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC,EAClE,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE;IACrD,MAAM,KAAK,GAAG,GAAG,CAAC,cAAc,CAAC,SAAS,EAAE;QAC1C,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,MAAM;QACb,GAAG,EAAE,SAAS;QACd,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,SAAS;QACjB,YAAY,EAAE,OAAO;KACtB,CAAC,CAAC;IACH,OAAO,GAAG,KAAK,UAAU,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C,MAAM,UAAU,qBAAqB;IACnC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,OAAO,MAAM,CAAC,SAAS,EAAE;QACvB,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE;QACvD,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,QAAQ,EAAE,sBAAsB,EAAE;QAClC,SAAS,EAAE,MAAM;KAClB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,OAAO,MAAM,CAAC,WAAW,EAAE;QACzB,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE;QACvD,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,QAAQ,EAAE,sBAAsB,EAAE;QAClC,SAAS,EAAE,QAAQ;KACpB,CAAC,CAAC;AACL,CAAC"}

package/dist/repl.d.ts

@@ -1,4 +1,5 @@
 import type { Mode, ProviderId } from "./types.js";
+import { type FileSuggestion } from "./ui/mentions.js";
 export interface ReplOptions {
     mode?: Mode | undefined;
     provider?: ProviderId | undefined;
@@ -13,4 +14,5 @@ export interface SlashCommand {
 export declare function getKnownModels(provider: string): string[];
 export declare function getSlashCommandSuggestions(line: string): SlashCommand[];
 export declare function renderSlashCommandMenu(line: string, suggestions: SlashCommand[], selectedIndex: number): string[];
+export declare function renderFileMentionMenu(query: string, suggestions: FileSuggestion[], selectedIndex: number): string[];
 export declare function startRepl(options?: ReplOptions): Promise<void>;

package/dist/repl.js

@@ -16,6 +16,7 @@ import { modelSupportsThinking } from "./llm/capabilities.js";
 import { clearViewports, getLastViewport, getViewport, isPagerActive, listViewports, openViewportPager, toggleViewport, } from "./ui/output-pane.js";
 import { compactMessages, estimateMessagesTokens, } from "./agent/context-manager.js";
 import { isCtrlC, isCtrlO, isCtrlT, isEscape } from "./ui/keys.js";
+import { getMentionQuery, findFileSuggestions, expandMentions, } from "./ui/mentions.js";
 const slashCommands = [
     { command: "/ask", description: "switch to ask mode" },
     { command: "/agent", description: "switch to agent mode" },
@@ -303,6 +304,31 @@ export function renderSlashCommandMenu(line, suggestions, selectedIndex) {
     }
     return items;
 }
+export function renderFileMentionMenu(query, suggestions, selectedIndex) {
+    const cols = terminalColumns();
+    const maxWidth = Math.max(1, cols - 1);
+    if (suggestions.length === 0) {
+        return [
+            chalk.dim(fitPlain(`  no files matching @${query}`, maxWidth)),
+        ];
+    }
+    const termRows = process.stdout.rows || 24;
+    const maxVisible = Math.max(5, termRows - 4);
+    const visible = suggestions.slice(0, maxVisible);
+    const items = visible.map((suggestion, index) => {
+        const markerPlain = index === selectedIndex ? "›" : " ";
+        const marker = index === selectedIndex ? chalk.magenta("›") : " ";
+        const prefix = `  ${markerPlain} `;
+        const labelBudget = Math.max(1, maxWidth - prefix.length);
+        const label = fitPlain(suggestion.label, labelBudget);
+        const colored = suggestion.isDir ? chalk.cyan(label) : chalk.white(label);
+        return `  ${marker} ${colored}`;
+    });
+    if (suggestions.length > maxVisible) {
+        items.push(chalk.dim(fitPlain(`  … ${suggestions.length - maxVisible} more`, maxWidth)));
+    }
+    return items;
+}
 function isPrintableSequence(sequence) {
     return sequence !== undefined && /^[^\x00-\x1f\x7f]+$/u.test(sequence);
 }
@@ -353,6 +379,7 @@ async function readPromptLine(options) {
         let selectedIndex = 0;
         let menuNavigated = false;
         let dismissedSlashLine = null;
+        let mentionDismissed = false;
         let historyIndex = null;
         let historyDraft = "";
         let lastCtrlCAt = 0;
@@ -369,12 +396,57 @@ async function readPromptLine(options) {
                 selectedIndex = 0;
             return { visible: true, suggestions };
         };
+        // File @-mention autocomplete: active when the cursor sits inside an
+        // `@partial/path` token. Mutually exclusive with the slash menu (slash
+        // requires the line to start with "/" and contain no whitespace).
+        const getMentionState = () => {
+            if (mentionDismissed || line.startsWith("/")) {
+                return { visible: false, query: "", start: 0, suggestions: [] };
+            }
+            const q = getMentionQuery(line, cursor);
+            if (!q)
+                return { visible: false, query: "", start: 0, suggestions: [] };
+            const suggestions = findFileSuggestions(q.query);
+            if (suggestions.length === 0) {
+                return { visible: false, query: q.query, start: q.start, suggestions };
+            }
+            if (selectedIndex >= suggestions.length)
+                selectedIndex = 0;
+            return { visible: true, query: q.query, start: q.start, suggestions };
+        };
+        const applyMention = (suggestion, start) => {
+            const before = line.slice(0, start);
+            const after = line.slice(cursor);
+            let insert = `@${suggestion.value}`;
+            let newCursor = before.length + insert.length;
+            if (!suggestion.isDir) {
+                // Completed a file — add a trailing space and close the menu so the
+                // user can keep typing their request.
+                insert += " ";
+                newCursor = before.length + insert.length;
+                mentionDismissed = true;
+            }
+            else {
+                // Completed a directory — keep the menu open so the user drills in.
+                mentionDismissed = false;
+            }
+            line = before + insert + after;
+            cursor = newCursor;
+            selectedIndex = 0;
+            menuNavigated = false;
+            refresh();
+        };
         const refresh = () => {
             const cols = terminalColumns();
             const menu = getMenuState();
+            const mention = menu.visible
+                ? { visible: false, query: "", start: 0, suggestions: [] }
+                : getMentionState();
             const menuLines = menu.visible
                 ? renderSlashCommandMenu(line, menu.suggestions, selectedIndex)
-                : [];
+                : mention.visible
+                    ? renderFileMentionMenu(mention.query, mention.suggestions, selectedIndex)
+                    : [];
             const promptRows = buildPromptRows(line, cols, true);
             const target = promptCursorPosition(cursor, cols);
             const blockRows = [...promptRows, ...menuLines];
@@ -402,6 +474,7 @@ async function readPromptLine(options) {
             selectedIndex = 0;
             menuNavigated = false;
             dismissedSlashLine = null;
+            mentionDismissed = false;
             historyIndex = null;
             refresh();
         };
@@ -446,6 +519,9 @@ async function readPromptLine(options) {
             if (isPagerActive())
                 return;
             const menu = getMenuState();
+            const mention = menu.visible
+                ? { visible: false, query: "", start: 0, suggestions: [] }
+                : getMentionState();
             // Cmd+C on macOS terminals is handled by the OS (it never reaches us),
             // but some Linux terminals forward Meta+C. Treat that as a no-op so
             // selecting + copying never breaks the REPL.
@@ -485,6 +561,10 @@ async function readPromptLine(options) {
                 return;
             }
             if (key.name === "return" || key.name === "enter") {
+                if (mention.visible && mention.suggestions.length > 0) {
+                    applyMention(mention.suggestions[selectedIndex] ?? mention.suggestions[0], mention.start);
+                    return;
+                }
                 const useSelection = menu.visible && (line !== "/" || menuNavigated);
                 const selectedCommand = useSelection
                     ? menu.suggestions[selectedIndex]
@@ -493,6 +573,10 @@ async function readPromptLine(options) {
                 return;
             }
             if (key.name === "tab") {
+                if (mention.visible && mention.suggestions.length > 0) {
+                    applyMention(mention.suggestions[selectedIndex] ?? mention.suggestions[0], mention.start);
+                    return;
+                }
                 if (menu.visible && menu.suggestions.length > 0) {
                     const target = menu.suggestions[selectedIndex] ?? menu.suggestions[0];
                     editLine(target.command, target.command.length);
@@ -500,6 +584,11 @@ async function readPromptLine(options) {
                 return;
             }
             if (isEscape(key)) {
+                if (mention.visible) {
+                    mentionDismissed = true;
+                    refresh();
+                    return;
+                }
                 if (menu.visible) {
                     dismissedSlashLine = line;
                     refresh();
@@ -507,6 +596,14 @@ async function readPromptLine(options) {
                 return;
             }
             if (key.name === "up") {
+                if (mention.visible && mention.suggestions.length > 0) {
+                    selectedIndex =
+                        (selectedIndex - 1 + mention.suggestions.length) %
+                            mention.suggestions.length;
+                    menuNavigated = true;
+                    refresh();
+                    return;
+                }
                 if (menu.visible && menu.suggestions.length > 0) {
                     selectedIndex =
                         (selectedIndex - 1 + menu.suggestions.length) %
@@ -532,6 +629,12 @@ async function readPromptLine(options) {
                 return;
             }
             if (key.name === "down") {
+                if (mention.visible && mention.suggestions.length > 0) {
+                    selectedIndex = (selectedIndex + 1) % mention.suggestions.length;
+                    menuNavigated = true;
+                    refresh();
+                    return;
+                }
                 if (menu.visible && menu.suggestions.length > 0) {
                     selectedIndex = (selectedIndex + 1) % menu.suggestions.length;
                     menuNavigated = true;
@@ -1480,7 +1583,7 @@ async function handleSlash(line, state) {
                 mode: state.mode,
             }));
             console.log(renderSuggestions());
-            console.log(chalk.dim("  ESC abort  │  Ctrl+C clears input  │  Ctrl+T or /think for thinking  │  Ctrl+O opens full tool output (q to close)\n"));
+            console.log(chalk.dim("  ESC abort  │  Ctrl+C clears input  │  @ to attach files  │  Ctrl+T thinking  │  Ctrl+O tool output (q to close)\n"));
             return true;
         }
         case "/update":
@@ -1635,7 +1738,7 @@ export async function startRepl(options = {}) {
         mode: state.mode,
     }));
     console.log(renderSuggestions());
-    console.log(chalk.dim("  ESC abort  │  Ctrl+C clears input  │  Ctrl+T or /think for thinking  │  Ctrl+O opens full tool output (q to close)\n"));
+    console.log(chalk.dim("  ESC abort  │  Ctrl+C clears input  │  @ to attach files  │  Ctrl+T thinking  │  Ctrl+O tool output (q to close)\n"));
     // Hint thinking-capable users that the toggle exists. We default it to
     // off for speed, since on NIM many models route through a much slower
     // chat-template path when reasoning is enabled.
@@ -1684,9 +1787,26 @@ export async function startRepl(options = {}) {
                 clearThinking();
                 abortPressCount = 0;
                 let assistantContent = "";
+                // Expand @file mentions and drag-and-dropped paths into real context.
+                // The user-visible `line` stays readable in history; the model gets
+                // the line plus an appended block of file contents / path notes.
+                const expansion = expandMentions(line);
+                const modelInput = expansion.contextBlock.length > 0
+                    ? `${line}\n\n${expansion.contextBlock}`
+                    : line;
+                if (expansion.attachments.length > 0) {
+                    for (const att of expansion.attachments) {
+                        const tag = att.kind === "text"
+                            ? chalk.green("attached")
+                            : att.kind === "missing"
+                                ? chalk.red("not found")
+                                : chalk.yellow(att.kind);
+                        console.log(chalk.dim(`  ↳ ${tag}: `) + chalk.dim(att.path));
+                    }
+                }
                 if (state.mode === "ask") {
                     assistantContent = await withAbortableInput(async (signal) => streamWithAbort(async (runSignal, onToken) => {
-                        return await runAskStream(line, onToken, {
+                        return await runAskStream(modelInput, onToken, {
                             provider: state.provider,
                             model: state.model,
                             history: state.messages,
@@ -1696,7 +1816,7 @@ export async function startRepl(options = {}) {
                     process.stdout.write("\n");
                 }
                 else {
-                    assistantContent = await withAbortableInput(async (signal) => runAgent(line, {
+                    assistantContent = await withAbortableInput(async (signal) => runAgent(modelInput, {
                         provider: state.provider,
                         model: state.model,
                         history: state.messages,
@@ -1705,7 +1825,7 @@ export async function startRepl(options = {}) {
                     }));
                 }
                 console.log();
-                state.messages.push({ role: "user", content: line }, { role: "assistant", content: assistantContent });
+                state.messages.push({ role: "user", content: modelInput }, { role: "assistant", content: assistantContent });
             }
             catch (error) {
                 if (error instanceof AbortRunError) {