@crewx/cli 0.8.1 → 0.8.2-rc.1

package/bin/crewx

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
-require('../dist/main.js');
+#!/usr/bin/env node
+require('../dist/main.js');

package/dist/bootstrap/crewx-cli.js

@@ -1,12 +1,18 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createCliCrewx = createCliCrewx;
 const fs_1 = require("fs");
 const path_1 = require("path");
+const os_1 = require("os");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const sdk_1 = require("@crewx/sdk");
 const plugins_1 = require("@crewx/sdk/plugins");
 const register_builtin_tools_1 = require("../register-builtin-tools");
 const version_1 = require("../utils/version");
+const tasks_1 = require("../schema/tasks");
 /**
  * Build a Crewx instance with CLI-standard plugins (FileLogger + SqliteTracing)
  * and built-in tools registered. Use this from any CLI command that needs a
@@ -39,6 +45,12 @@ async function createCliCrewx(configPath = process.env.CREWX_CONFIG ?? 'crewx.ya
         // No explicit config and file doesn't exist — built-in-only mode
         yamlPath = undefined;
     }
+    // Ensure ~/.crewx/crewx.db schema exists before SqliteTracingPlugin opens it.
+    const dbDir = (0, path_1.join)((0, os_1.homedir)(), '.crewx');
+    (0, fs_1.mkdirSync)(dbDir, { recursive: true });
+    const schemaDb = new better_sqlite3_1.default((0, path_1.join)(dbDir, 'crewx.db'));
+    (0, tasks_1.ensureTasksSchema)(schemaDb);
+    schemaDb.close();
     // Pass ourselves back to the SDK: when this Crewx encounters a file:// remote
     // agent, the SDK uses this factory to bootstrap the target Crewx instance
     // with the same plugin set (FileLogger + SqliteTracing + built-in tools).

package/dist/commands/agent.js

@@ -219,28 +219,28 @@ function loadAgentSkills() {
     }
 }
 function printAgentHelp() {
-    console.log(`
-CrewX Agent Management
-
-Usage:
-  crewx agent             # List configured agents (default)
-  crewx agent ls          # List configured agents
-  crewx agent list        # Alias for ls
-  crewx agent prompt <id> # Inspect rendered agent prompt
-
-Filter Options (for agent ls):
-  --role <value>      Filter by agent role (comma-separated for multiple: PM,Dev)
-  --team <value>      Filter by agent team (comma-separated for multiple)
-  --provider <value>  Filter by provider (comma-separated, partial match: claude)
-
-Examples:
-  crewx agent
-  crewx agent ls
-  crewx agent ls --role=PM
-  crewx agent ls --team="CrewX Core 개발팀"
-  crewx agent ls --provider=claude
-  crewx agent ls --role=PM --provider=claude
-  crewx agent ls --role=PM,general
-  CREWX_CONFIG=./crewx.yaml crewx agent list
+    console.log(`
+CrewX Agent Management
+
+Usage:
+  crewx agent             # List configured agents (default)
+  crewx agent ls          # List configured agents
+  crewx agent list        # Alias for ls
+  crewx agent prompt <id> # Inspect rendered agent prompt
+
+Filter Options (for agent ls):
+  --role <value>      Filter by agent role (comma-separated for multiple: PM,Dev)
+  --team <value>      Filter by agent team (comma-separated for multiple)
+  --provider <value>  Filter by provider (comma-separated, partial match: claude)
+
+Examples:
+  crewx agent
+  crewx agent ls
+  crewx agent ls --role=PM
+  crewx agent ls --team="CrewX Core 개발팀"
+  crewx agent ls --provider=claude
+  crewx agent ls --role=PM --provider=claude
+  crewx agent ls --role=PM,general
+  CREWX_CONFIG=./crewx.yaml crewx agent list
 `.trim());
 }

package/dist/commands/init.js

@@ -56,27 +56,27 @@ function escapeYamlBlock(text) {
 }
 function generateDefaultYaml(agents) {
     const agentBlocks = agents
-        .map((a) => `  - id: "${a.id}"
-    name: "${a.name}"
-    role: "${a.role}"
-    team: "${a.team}"
-    provider: "${a.provider}"
-    default_model: "${a.default_model}"
-    working_directory: "${a.working_directory}"
-    description: "${a.description}"
-    system_prompt: |
+        .map((a) => `  - id: "${a.id}"
+    name: "${a.name}"
+    role: "${a.role}"
+    team: "${a.team}"
+    provider: "${a.provider}"
+    default_model: "${a.default_model}"
+    working_directory: "${a.working_directory}"
+    description: "${a.description}"
+    system_prompt: |
 ${escapeYamlBlock(a.system_prompt)}`)
         .join('\n\n');
-    return `# CrewX Agents Configuration
-# Generated by 'crewx init'
-
-agents:
-${agentBlocks}
-
-# Usage examples:
-#   crewx query "@planner analyze this codebase"
-#   crewx execute "@developer implement the feature described above"
-#   crewx agent ls
+    return `# CrewX Agents Configuration
+# Generated by 'crewx init'
+
+agents:
+${agentBlocks}
+
+# Usage examples:
+#   crewx query "@planner analyze this codebase"
+#   crewx execute "@developer implement the feature described above"
+#   crewx agent ls
 `;
 }
 /**

package/dist/commands/parse-common-flags.d.ts

@@ -3,7 +3,11 @@
  *
  * Supports both `--flag=value` and `--flag value` forms.
  * Handles: --thread, --provider, --metadata, --verbose, --config/-c,
- *          --output-format, --effort.
+ *          --output-format, --effort, --prompt-file/-f.
+ *
+ * Strict mode: unknown --xxx tokens after known flags are consumed throw an
+ * error instead of silently leaking into the message prompt.
+ * Use `--` sentinel to pass literal flag-like tokens as positional args.
  */
 export interface CommonFlags {
     /** Thread name for conversation continuity. */
@@ -22,12 +26,24 @@ export interface CommonFlags {
     effort?: string;
     /** Path to a file whose content is used as the prompt body (-f/--prompt-file). */
     promptFile?: string;
-    /** Remaining non-flag arguments. */
+    /** Remaining non-flag positional arguments. */
     rest: string[];
 }
+/**
+ * Thrown by parseCommonFlags when an unrecognized --xxx flag is encountered.
+ * Callers can distinguish this from other errors to map to exit code 2.
+ */
+export declare class UnknownOptionError extends Error {
+    constructor(message: string);
+}
 /**
  * Parse common CLI flags from an args array.
- * Returns parsed flags and remaining positional arguments.
+ *
+ * Strict mode: any unconsumed `--xxx` token (outside a `--` escape block)
+ * throws `UnknownOptionError: Unknown option: --xxx.`
+ *
+ * Tokens after `--` are treated as positional and included in `rest` as-is.
+ * The `--` sentinel itself is NOT included in `rest`.
  */
 export declare function parseCommonFlags(args: string[]): CommonFlags;
 /**

package/dist/commands/parse-common-flags.js

@@ -4,9 +4,14 @@
  *
  * Supports both `--flag=value` and `--flag value` forms.
  * Handles: --thread, --provider, --metadata, --verbose, --config/-c,
- *          --output-format, --effort.
+ *          --output-format, --effort, --prompt-file/-f.
+ *
+ * Strict mode: unknown --xxx tokens after known flags are consumed throw an
+ * error instead of silently leaking into the message prompt.
+ * Use `--` sentinel to pass literal flag-like tokens as positional args.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnknownOptionError = void 0;
 exports.parseCommonFlags = parseCommonFlags;
 exports.parseMetadata = parseMetadata;
 /**
@@ -35,9 +40,25 @@ function parseFlag(args, ...names) {
 function hasFlag(args, ...names) {
     return names.some(name => args.includes(name));
 }
+/**
+ * Thrown by parseCommonFlags when an unrecognized --xxx flag is encountered.
+ * Callers can distinguish this from other errors to map to exit code 2.
+ */
+class UnknownOptionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnknownOptionError';
+    }
+}
+exports.UnknownOptionError = UnknownOptionError;
 /**
  * Parse common CLI flags from an args array.
- * Returns parsed flags and remaining positional arguments.
+ *
+ * Strict mode: any unconsumed `--xxx` token (outside a `--` escape block)
+ * throws `UnknownOptionError: Unknown option: --xxx.`
+ *
+ * Tokens after `--` are treated as positional and included in `rest` as-is.
+ * The `--` sentinel itself is NOT included in `rest`.
  */
 function parseCommonFlags(args) {
     const thread = parseFlag(args, '--thread');
@@ -48,7 +69,7 @@ function parseCommonFlags(args) {
     const effort = parseFlag(args, '--effort');
     const promptFile = parseFlag(args, '--prompt-file', '-f');
     const verbose = hasFlag(args, '--verbose');
-    // Collect the set of consumed positions
+    // Collect consumed positions for known flags
     const consumed = new Set();
     const flagPairs = [
         { names: ['--thread'] },
@@ -61,12 +82,10 @@ function parseCommonFlags(args) {
     ];
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
-        // Boolean flags
         if (arg === '--verbose') {
             consumed.add(i);
             continue;
         }
-        // Value flags
         for (const { names } of flagPairs) {
             for (const name of names) {
                 if (arg.startsWith(`${name}=`)) {
@@ -80,7 +99,28 @@ function parseCommonFlags(args) {
             }
         }
     }
-    const rest = args.filter((_, i) => !consumed.has(i));
+    // Build rest with strict unknown-flag detection and -- escape support
+    const rest = [];
+    let escapeMode = false;
+    for (let i = 0; i < args.length; i++) {
+        if (consumed.has(i))
+            continue;
+        const token = args[i];
+        if (!escapeMode && token === '--') {
+            escapeMode = true; // consume -- sentinel; everything after is positional
+            continue;
+        }
+        if (!escapeMode && token.startsWith('--')) {
+            throw new UnknownOptionError(`Unknown option: ${token}. Use "--" to pass literal flag-like tokens as message.\n` +
+                `   Did you mean: crewx serve ${token}\n` +
+                `              or: crewx q -- ${token} <message>   (to include in message)`);
+        }
+        // Reject short -x flags that are not numeric (e.g. -f was consumed above)
+        if (!escapeMode && token.startsWith('-') && token.length > 1 && !/^-?\d/.test(token)) {
+            throw new UnknownOptionError(`Unknown option: ${token}`);
+        }
+        rest.push(token);
+    }
     return { thread, provider, metadata, verbose, config, outputFormat, effort, promptFile, rest };
 }
 /**

package/dist/commands/registry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * CLI command registry — SSOT for commands handled by the CLI engine.
+ *
+ * Consumed by:
+ *   - main.ts dispatch (to avoid switch/case literal drift)
+ *   - bin/__tests__/crewx-entrypoint.test.ts (SSOT assertion vs CLI_SUBCOMMANDS)
+ */
+/** Core commands handled by the main.ts switch/case or hook routing. */
+export declare const KNOWN_COMMANDS: Set<string>;
+/** Built-in tool commands routed via handleBuiltin(). */
+export declare const BUILTIN_COMMAND_NAMES: Set<string>;
+/** Commands not yet migrated from cli-bak — show a migration message. */
+export declare const NOT_YET_MIGRATED: Set<string>;

package/dist/commands/registry.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * CLI command registry — SSOT for commands handled by the CLI engine.
+ *
+ * Consumed by:
+ *   - main.ts dispatch (to avoid switch/case literal drift)
+ *   - bin/__tests__/crewx-entrypoint.test.ts (SSOT assertion vs CLI_SUBCOMMANDS)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOT_YET_MIGRATED = exports.BUILTIN_COMMAND_NAMES = exports.KNOWN_COMMANDS = void 0;
+/** Core commands handled by the main.ts switch/case or hook routing. */
+exports.KNOWN_COMMANDS = new Set([
+    'q', 'query',
+    'x', 'execute',
+    'agent',
+    'ps', 'kill', 'result', 'log',
+    'doctor', 'init',
+    'help',
+    'slack', 'slack:files',
+    'hook', 'hook-dispatch',
+]);
+/** Built-in tool commands routed via handleBuiltin(). */
+exports.BUILTIN_COMMAND_NAMES = new Set([
+    'memory', 'search', 'doc', 'wbs', 'cron', 'workflow', 'skill',
+]);
+/** Commands not yet migrated from cli-bak — show a migration message. */
+exports.NOT_YET_MIGRATED = new Set([
+    'template', 'templates', 'chat', 'mcp',
+]);

package/dist/commands/task-db.js

@@ -33,8 +33,8 @@ function getRunningTasks(dbRoot) {
     if (!db)
         return [];
     try {
-        return db.prepare(`SELECT id, agent_id, prompt, mode, status, pid, started_at, completed_at,
-              result, error, duration_ms
+        return db.prepare(`SELECT id, agent_id, prompt, mode, status, pid, started_at, completed_at,
+              result, error, duration_ms
        FROM tasks WHERE status = 'running' ORDER BY started_at DESC`).all();
     }
     finally {
@@ -47,8 +47,8 @@ function getAllTasks(dbRoot) {
     if (!db)
         return [];
     try {
-        return db.prepare(`SELECT id, agent_id, prompt, mode, status, pid, started_at, completed_at,
-              result, error, duration_ms
+        return db.prepare(`SELECT id, agent_id, prompt, mode, status, pid, started_at, completed_at,
+              result, error, duration_ms
        FROM tasks ORDER BY started_at DESC`).all();
     }
     finally {
@@ -61,8 +61,8 @@ function getTask(id, dbRoot) {
     if (!db)
         return undefined;
     try {
-        return db.prepare(`SELECT id, agent_id, prompt, mode, status, pid, started_at, completed_at,
-              result, error, duration_ms
+        return db.prepare(`SELECT id, agent_id, prompt, mode, status, pid, started_at, completed_at,
+              result, error, duration_ms
        FROM tasks WHERE id = ?`).get(id);
     }
     finally {
@@ -97,7 +97,7 @@ function killTask(id, dbRoot) {
                 // ESRCH = process already gone — still clean up the record
             }
         }
-        db.prepare(`UPDATE tasks SET status='failed', error='killed by user',
+        db.prepare(`UPDATE tasks SET status='failed', error='killed by user',
        completed_at=?, pid=NULL WHERE id=?`).run(new Date().toISOString(), id);
         return { ok: true, message: `Killed task ${id}${task.pid ? ` (PID: ${task.pid})` : ''}` };
     }

package/dist/examples/deny-secrets-plugin.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DenyIfTouchesSecretsPlugin — Phase 0 demo HookPlugin.
+ *
+ * Denies Bash tool calls whose command string contains ".env".
+ * Pure string matching — trivially bypassable (see README).
+ *
+ * SECURITY NOTE:
+ *   Do NOT include tool.input content in deny reasons.
+ *   Use static messages only to prevent prompt injection.
+ *   ✅ return ctx.deny('Secrets-related command');
+ *   ❌ return ctx.deny(`Blocked: ${cmd}`);
+ */
+import { HookPlugin } from '@crewx/sdk/hooks';
+import type { HookContext, HookResult } from '@crewx/sdk/hooks';
+export declare class DenyIfTouchesSecretsPlugin extends HookPlugin {
+    readonly name = "deny-secrets";
+    readonly version = "0.1.0";
+    readonly capabilities: {
+        required: readonly ["deny"];
+    };
+    run(ctx: HookContext): Promise<HookResult>;
+}

package/dist/examples/deny-secrets-plugin.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * DenyIfTouchesSecretsPlugin — Phase 0 demo HookPlugin.
+ *
+ * Denies Bash tool calls whose command string contains ".env".
+ * Pure string matching — trivially bypassable (see README).
+ *
+ * SECURITY NOTE:
+ *   Do NOT include tool.input content in deny reasons.
+ *   Use static messages only to prevent prompt injection.
+ *   ✅ return ctx.deny('Secrets-related command');
+ *   ❌ return ctx.deny(`Blocked: ${cmd}`);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DenyIfTouchesSecretsPlugin = void 0;
+const hooks_1 = require("@crewx/sdk/hooks");
+const SECRET_PATTERNS = ['.env', 'credentials.json', 'service-account-key.json'];
+const SHELL_TOOL_NAMES = new Set(['Bash', 'shell', 'local_shell']);
+class DenyIfTouchesSecretsPlugin extends hooks_1.HookPlugin {
+    name = 'deny-secrets';
+    version = '0.1.0';
+    capabilities = { required: ['deny'] };
+    async run(ctx) {
+        if (!SHELL_TOOL_NAMES.has(ctx.tool.rawName) && ctx.tool.name !== 'shell') {
+            return ctx.pass();
+        }
+        const input = ctx.tool.input;
+        const command = input?.command;
+        if (typeof command !== 'string') {
+            return ctx.pass();
+        }
+        for (const pattern of SECRET_PATTERNS) {
+            if (command.includes(pattern)) {
+                return ctx.deny('Secrets-related command');
+            }
+        }
+        return ctx.pass();
+    }
+}
+exports.DenyIfTouchesSecretsPlugin = DenyIfTouchesSecretsPlugin;

package/dist/main.js

@@ -9,6 +9,39 @@
  *   2. Parse command
  *   3. Dispatch to handler
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 // ─── P0-1: Env Bootstrap ─────────────────────────────────────────────────────
 // Must run before any other code that might use process.env.CREWX_CLI.
@@ -31,15 +64,36 @@ const install_1 = require("./commands/hook/install");
 const uninstall_1 = require("./commands/hook/uninstall");
 const status_1 = require("./commands/hook/status");
 const hook_dispatch_1 = require("./commands/hook-dispatch");
+const parse_common_flags_1 = require("./commands/parse-common-flags");
+const registry_1 = require("./commands/registry");
 const version_1 = require("./utils/version");
-// Commands deferred to future rounds
-const NOT_YET_MIGRATED = new Set([
-    'template',
-    'templates',
-    'chat',
-    'mcp',
-]);
+/**
+ * Dev-only SSOT assertion: bin/cli-commands.js must be the exact union of
+ * KNOWN_COMMANDS ∪ BUILTIN_COMMAND_NAMES ∪ NOT_YET_MIGRATED from registry.ts.
+ * Throws on drift so the discrepancy is caught immediately during development.
+ */
+async function assertSsotParity() {
+    const { join } = await Promise.resolve().then(() => __importStar(require('path')));
+    const { createRequire } = await Promise.resolve().then(() => __importStar(require('module')));
+    // Use createRequire(__filename) + plain path to avoid TypeScript compiling import() → require()
+    // in the CJS dist. Node.js 22.12+ supports require(esm), so this loads ESM cli-commands.js fine.
+    const req = createRequire(__filename);
+    const cliCommandsPath = join(__dirname, '../../../bin/cli-commands.js');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const { CLI_SUBCOMMANDS } = req(cliCommandsPath);
+    const union = new Set([...registry_1.KNOWN_COMMANDS, ...registry_1.BUILTIN_COMMAND_NAMES, ...registry_1.NOT_YET_MIGRATED]);
+    const missing = [...union].filter((c) => !CLI_SUBCOMMANDS.has(c));
+    const extra = [...CLI_SUBCOMMANDS].filter((c) => !union.has(c));
+    if (missing.length > 0 || extra.length > 0) {
+        throw new Error(`[crewx dev] SSOT drift detected!\n` +
+            (missing.length ? `  registry has, CLI_SUBCOMMANDS missing: ${missing.join(', ')}\n` : '') +
+            (extra.length ? `  CLI_SUBCOMMANDS has, registry missing: ${extra.join(', ')}` : ''));
+    }
+}
 async function main() {
+    if (process.env['NODE_ENV'] === 'development') {
+        await assertSsotParity();
+    }
     const args = process.argv.slice(2);
     const command = args[0];
     if (!command) {
@@ -131,7 +185,7 @@ async function main() {
         }
     }
     // Not yet migrated commands (SDK-009)
-    if (NOT_YET_MIGRATED.has(command)) {
+    if (registry_1.NOT_YET_MIGRATED.has(command)) {
         console.error(`Command '${command}' is not yet migrated in SDK refactor round. ` +
             'See packages/cli-bak for reference.');
         process.exit(1);
@@ -162,68 +216,80 @@ async function main() {
     process.exit(1);
 }
 function printHelp() {
-    console.log(`
-CrewX CLI v${version_1.CLI_VERSION}
-
-Usage:
-  crewx <command> [options]
-
-Query / Execute:
-  q|query "@agent <message>"     Query an agent (quoted single string)
-  x|execute "@agent <task>"      Execute a task with an agent (quoted single string)
-
-  @agent is optional — defaults to @crewx when omitted.
-
-  Common flags:
-    --thread <name>              Conversation thread
-    --provider <cli/xxx>         Provider override
-    --metadata <json>            Extra metadata (JSON object, double-quoted). Propagated to events/hooks/tracing.
-                                 Invalid JSON aborts with exit code 2.
-                                 e.g. --metadata='{"workflow_id":"wf-1"}'
-    --verbose                    Debug output mode (default: raw response only)
-    --config/-c <path>           Config file path (default: CREWX_CONFIG or crewx.yaml)
-    --output-format <fmt>        Output format (json|text|stream-json)
-    --effort <level>             Model effort (high|medium|low)
-
-Agent Management:
-  agent ls [options]             List configured agents
-    --role <value>               Filter by role (comma-separated for OR match)
-    --team <value>               Filter by team (comma-separated for OR match)
-    --provider <value>           Filter by provider (comma-separated for OR match)
-  agent prompt <@id>             Show rendered system prompt for an agent
-
-Task Management:
-  ps                             List running tasks
-  kill <task-id>                 Kill a running task
-  kill --all                     Kill all running tasks
-  result [task-id]               Get task result (or list recent tasks)
-
-Logs & Diagnostics:
-  log [ls|<task-id>]             View task logs
-  doctor [--config <path>]       Run system diagnosis
-  init [--force] [--config <p>]  Initialize crewx.yaml
-
-Built-in Tools:
-  memory <args>                  Memory tool
-  search <args>                  Search tool
-  doc <args>                     Doc tool
-  wbs <args>                     WBS tool
-  cron <args>                    Cron tool
-  workflow <args>                Workflow tool
-  skill <args>                   Skill tool
-
-Hook Platform:
-  hook install [--yes]           Install PreToolUse hook in .claude/settings.json
-  hook uninstall                 Remove crewx hook from .claude/settings.json
-  hook status                    Show hook installation status and plugins
-  hook-dispatch                  Internal: IPC router called by Claude (stdin→stdout)
-
-Global Options:
-  --help, -h                     Show this help
-  --version, -v                  Show version
+    console.log(`
+CrewX CLI v${version_1.CLI_VERSION}
+
+Usage:
+  crewx                          Launch web dashboard + open browser (default)
+  crewx <command> [options]
+
+UI Modes:
+  crewx                          Web dashboard (port 8150, random token, auto-open)
+  crewx serve [options]          Web server (explicit)
+    --port <N>                   Port (default: 8150)
+    --token <T>                  MCP bearer token (⚠️  use --token-file in shared shells)
+    --token-file <PATH>          Read bearer token from file
+    --no-open                    Do not auto-open browser
+  crewx electron [--overlay]     Launch Electron (desktop or overlay window)
+
+Query / Execute:
+  q|query "@agent <message>"     Query an agent (quoted single string)
+  x|execute "@agent <task>"      Execute a task with an agent (quoted single string)
+
+  @agent is optional — defaults to @crewx when omitted.
+
+  Common flags:
+    --thread <name>              Conversation thread
+    --provider <cli/xxx>         Provider override
+    --metadata <json>            Extra metadata (JSON object, double-quoted). Propagated to events/hooks/tracing.
+                                 Invalid JSON aborts with exit code 2.
+                                 e.g. --metadata='{"workflow_id":"wf-1"}'
+    --verbose                    Debug output mode (default: raw response only)
+    --config/-c <path>           Config file path (default: CREWX_CONFIG or crewx.yaml)
+    --output-format <fmt>        Output format (json|text|stream-json)
+    --effort <level>             Model effort (high|medium|low)
+    --                           End of flags; remaining tokens treated as message text
+                                 e.g. crewx q "@agent label" -- --flag-in-message
+
+Agent Management:
+  agent ls [options]             List configured agents
+    --role <value>               Filter by role (comma-separated for OR match)
+    --team <value>               Filter by team (comma-separated for OR match)
+    --provider <value>           Filter by provider (comma-separated for OR match)
+  agent prompt <@id>             Show rendered system prompt for an agent
+
+Task Management:
+  ps                             List running tasks
+  kill <task-id>                 Kill a running task
+  kill --all                     Kill all running tasks
+  result [task-id]               Get task result (or list recent tasks)
+
+Logs & Diagnostics:
+  log [ls|<task-id>]             View task logs
+  doctor [--config <path>]       Run system diagnosis
+  init [--force] [--config <p>]  Initialize crewx.yaml
+
+Built-in Tools:
+  memory <args>                  Memory tool
+  search <args>                  Search tool
+  doc <args>                     Doc tool
+  wbs <args>                     WBS tool
+  cron <args>                    Cron tool
+  workflow <args>                Workflow tool
+  skill <args>                   Skill tool
+
+Hook Platform:
+  hook install [--yes]           Install PreToolUse hook in .claude/settings.json
+  hook uninstall                 Remove crewx hook from .claude/settings.json
+  hook status                    Show hook installation status and plugins
+  hook-dispatch                  Internal: IPC router called by Claude (stdin→stdout)
+
+Global Options:
+  --help, -h                     Show this help
+  --version, -v                  Show version
 `.trim());
 }
 main().catch((err) => {
     console.error(err instanceof Error ? err.message : String(err));
-    process.exit(1);
+    process.exit(err instanceof parse_common_flags_1.UnknownOptionError ? 2 : 1);
 });

package/dist/plugins/examples/echo-hook.d.ts

@@ -0,0 +1,24 @@
+/**
+ * EchoObserverPlugin — Tool observer that echoes events to a JSONL log.
+ *
+ * Observes tool:before / tool:after events from the Crewx event bus
+ * and appends them as JSONL to ~/.crewx/logs/echo-hook.log.
+ * Pure observer — no flow control (deny/inject/modify not applicable).
+ */
+import { ToolObserverPlugin } from '@crewx/sdk/hooks';
+import type { ObserverContext, ObserverResult } from '@crewx/sdk/hooks';
+export declare class EchoHookPlugin extends ToolObserverPlugin {
+    readonly name = "echo-hook";
+    readonly version = "0.0.1";
+    readonly on: {
+        beforeTool: true;
+        afterTool: true;
+        beforePrompt: true;
+        sessionStart: true;
+    };
+    private readonly logPath;
+    constructor(logDir?: string);
+    run(ctx: ObserverContext): Promise<ObserverResult>;
+    private ensureLogDir;
+    private echo;
+}

package/dist/plugins/examples/echo-hook.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * EchoObserverPlugin — Tool observer that echoes events to a JSONL log.
+ *
+ * Observes tool:before / tool:after events from the Crewx event bus
+ * and appends them as JSONL to ~/.crewx/logs/echo-hook.log.
+ * Pure observer — no flow control (deny/inject/modify not applicable).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EchoHookPlugin = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const hooks_1 = require("@crewx/sdk/hooks");
+class EchoHookPlugin extends hooks_1.ToolObserverPlugin {
+    name = 'echo-hook';
+    version = '0.0.1';
+    on = {
+        beforeTool: true,
+        afterTool: true,
+        beforePrompt: true,
+        sessionStart: true,
+    };
+    logPath;
+    constructor(logDir) {
+        super();
+        this.logPath = (0, path_1.join)(logDir ?? (0, os_1.homedir)(), '.crewx', 'logs', 'echo-hook.log');
+        this.ensureLogDir();
+    }
+    async run(ctx) {
+        this.echo(ctx);
+        return ctx.pass();
+    }
+    ensureLogDir() {
+        const dir = (0, path_1.dirname)(this.logPath);
+        if (!(0, fs_1.existsSync)(dir)) {
+            (0, fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+        }
+    }
+    echo(ctx) {
+        try {
+            const line = JSON.stringify({
+                timestamp: new Date().toISOString(),
+                event: ctx.event,
+                traceId: ctx.traceId,
+                agent: ctx.agent,
+                provider: ctx.provider,
+                thread: ctx.thread,
+                tool: ctx.tool,
+                cwd: ctx.cwd,
+                sessionId: ctx.sessionId,
+            });
+            (0, fs_1.appendFileSync)(this.logPath, line + '\n', { encoding: 'utf8', mode: 0o600 });
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+}
+exports.EchoHookPlugin = EchoHookPlugin;

package/dist/plugins/examples/verify-echo-hook.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env npx tsx
+/**
+ * Phase 0 e2e verification — EchoHookPlugin logs Claude Code tool calls.
+ *
+ * Run: npx tsx packages/cli/src/plugins/examples/verify-echo-hook.ts
+ * Prereq: claude CLI installed, crewx.yaml with @claude agent
+ */
+export {};

package/dist/plugins/examples/verify-echo-hook.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env npx tsx
+"use strict";
+/**
+ * Phase 0 e2e verification — EchoHookPlugin logs Claude Code tool calls.
+ *
+ * Run: npx tsx packages/cli/src/plugins/examples/verify-echo-hook.ts
+ * Prereq: claude CLI installed, crewx.yaml with @claude agent
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const sdk_1 = require("@crewx/sdk");
+const echo_hook_1 = require("./echo-hook");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const LOG_PATH = (0, path_1.join)((0, os_1.homedir)(), '.crewx', 'logs', 'echo-hook.log');
+async function main() {
+    if ((0, fs_1.existsSync)(LOG_PATH))
+        (0, fs_1.unlinkSync)(LOG_PATH);
+    const crewx = await sdk_1.Crewx.loadYaml('crewx.yaml');
+    await crewx.use(new echo_hook_1.EchoHookPlugin());
+    console.log('[verify] querying @claude with "ls"...');
+    await crewx.query('@claude', 'Run ls in the current directory. Use the Bash tool.');
+    await crewx.close();
+    if (!(0, fs_1.existsSync)(LOG_PATH)) {
+        console.error('[FAIL] echo-hook.log not created');
+        process.exit(1);
+    }
+    const lines = (0, fs_1.readFileSync)(LOG_PATH, 'utf8').trim().split('\n');
+    const entries = lines.map((l) => JSON.parse(l));
+    const hasBeforeTool = entries.some((e) => e.event === 'beforeTool');
+    const hasTraceId = entries.every((e) => e.traceId?.startsWith('tsk_'));
+    const hasToolName = entries
+        .filter((e) => e.event === 'beforeTool')
+        .every((e) => typeof e.tool?.rawName === 'string' && e.tool.rawName.length > 0);
+    console.log(`[verify] entries: ${entries.length}`);
+    console.log(`[verify] beforeTool: ${hasBeforeTool}`);
+    console.log(`[verify] traceId:    ${hasTraceId}`);
+    console.log(`[verify] toolName:   ${hasToolName}`);
+    if (hasBeforeTool && hasTraceId && hasToolName) {
+        console.log('[PASS] Phase 0 e2e verification passed');
+    }
+    else {
+        console.error('[FAIL] Some checks failed');
+        process.exit(1);
+    }
+}
+main().catch((err) => { console.error(err); process.exit(1); });

package/dist/plugins/sqlite-tracing.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-export of SqliteTracingPlugin with a CLI-friendly constructor that
+ * accepts a plain dbRoot string (in addition to the SDK's options-object form).
+ */
+import { SqliteTracingPlugin as SdkSqliteTracingPlugin } from '@crewx/sdk/plugins';
+export declare class SqliteTracingPlugin extends SdkSqliteTracingPlugin {
+    constructor(dbRootOrOpts?: string | {
+        dbRoot?: string;
+        version?: string;
+    });
+}

package/dist/plugins/sqlite-tracing.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteTracingPlugin = void 0;
+/**
+ * Re-export of SqliteTracingPlugin with a CLI-friendly constructor that
+ * accepts a plain dbRoot string (in addition to the SDK's options-object form).
+ */
+const plugins_1 = require("@crewx/sdk/plugins");
+class SqliteTracingPlugin extends plugins_1.SqliteTracingPlugin {
+    constructor(dbRootOrOpts) {
+        if (typeof dbRootOrOpts === 'string') {
+            super({ dbRoot: dbRootOrOpts });
+        }
+        else {
+            super(dbRootOrOpts);
+        }
+    }
+}
+exports.SqliteTracingPlugin = SqliteTracingPlugin;

package/dist/schema/tasks.d.ts

@@ -0,0 +1,7 @@
+import type BetterSqlite3 from 'better-sqlite3';
+/**
+ * Ensure the `tasks` table exists in the given database.
+ * Safe to call multiple times — CREATE TABLE IF NOT EXISTS is idempotent.
+ * Owns the canonical schema for the CLI-side tasks table.
+ */
+export declare function ensureTasksSchema(db: InstanceType<typeof BetterSqlite3>): void;

package/dist/schema/tasks.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureTasksSchema = ensureTasksSchema;
+/**
+ * Ensure the `tasks` table exists in the given database.
+ * Safe to call multiple times — CREATE TABLE IF NOT EXISTS is idempotent.
+ * Owns the canonical schema for the CLI-side tasks table.
+ */
+function ensureTasksSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS tasks (
+      id                    TEXT PRIMARY KEY,
+      agent_id              TEXT,
+      user_id               TEXT,
+      prompt                TEXT,
+      mode                  TEXT,
+      status                TEXT NOT NULL,
+      result                TEXT,
+      error                 TEXT,
+      started_at            TEXT NOT NULL,
+      completed_at          TEXT,
+      duration_ms           INTEGER,
+      metadata              TEXT,
+      project_id            TEXT,
+      project_name          TEXT,
+      trace_id              TEXT,
+      parent_task_id        TEXT,
+      caller_agent_id       TEXT,
+      model                 TEXT,
+      platform              TEXT,
+      crewx_version         TEXT,
+      input_tokens          INTEGER DEFAULT 0,
+      output_tokens         INTEGER DEFAULT 0,
+      cost_usd              REAL,
+      pid                   INTEGER,
+      rendered_prompt       TEXT,
+      command               TEXT,
+      coding_agent_command  TEXT,
+      exit_code             INTEGER,
+      logs                  TEXT,
+      thread_id             TEXT,
+      project_ref           TEXT,
+      workspace_id          TEXT,
+      workspace_name        TEXT,
+      cached_input_tokens   INTEGER DEFAULT 0
+    )
+  `);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewx/cli",
-  "version": "0.8.1",
+  "version": "0.8.2-rc.1",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=20.19.0"
@@ -27,15 +27,15 @@
   "dependencies": {
     "@crewx/adapter-slack": "^0.1.4",
     "better-sqlite3": "*",
-    "@crewx/sdk": "0.8.1",
+    "@crewx/sdk": "0.8.2-rc.1",
     "@crewx/memory": "0.1.9",
-    "@crewx/wbs": "0.1.8",
-    "@crewx/search": "0.1.8",
     "@crewx/doc": "0.1.7",
-    "@crewx/workflow": "0.3.8",
+    "@crewx/search": "0.1.8",
+    "@crewx/wbs": "0.1.8",
     "@crewx/skill": "0.1.7",
-    "@crewx/shared": "0.0.4",
-    "@crewx/cron": "0.1.7"
+    "@crewx/cron": "0.1.7",
+    "@crewx/workflow": "0.3.8",
+    "@crewx/shared": "0.0.4"
   },
   "devDependencies": {
     "@types/better-sqlite3": "*",