litclaude-ai 0.3.16 → 0.3.17

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.17 - 2026-07-01 — native `/goal` worker launcher
+
+- Add `litgoal native-worker` as a dry-run-first launcher for a separate Claude Code print/background worker whose first prompt is `/goal <condition>`.
+- Require explicit `--execute` before spawning `claude`, reject malformed or secret-like conditions, avoid shell interpolation, and propagate child worker failures.
+- Document the capability boundary clearly: this does not arm an already-open TUI, does not inject tmux keystrokes, and does not mutate private transcript metadata.
+
 ## 0.3.16 - 2026-06-27 — WSL2 HUD gradient hotfix
 
 - Restore truecolor neon gradient rendering for WSL2/Windows Terminal status lines when Claude Code drops `WT_SESSION` before invoking the HUD command.

package/README.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.16-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.17-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -22,14 +22,15 @@
 > `litclaude@litclaude-ai`, so normal `claude` launches can load the
 > LitClaude skills and hooks without a long `--plugin-dir` command.
 
-This checkout is prepared as `litclaude-ai@0.3.16` for personal install
+This checkout is prepared as `litclaude-ai@0.3.17` for personal install
 convenience. The repo can remain quiet; preparing npm package metadata here does
 not imply public repo promotion, marketplace publication, or advertisement.
-Future package releases still require explicit user approval. The v0.3.16
-release materials preserve the v0.3.15 Korean AI slop remover workflow and
-restore WSL2/Windows Terminal truecolor HUD gradients while retaining the
-v0.3.13 public-source reader runtime, litresearch activation/read-only polish,
-and installer permission-preference discipline.
+Future package releases still require explicit user approval. The v0.3.17
+release materials add the separate-worker native `/goal` launcher while
+preserving the v0.3.15 Korean AI slop remover workflow, the v0.3.16
+WSL2/Windows Terminal truecolor HUD gradient fix, the v0.3.13 public-source
+reader runtime, litresearch activation/read-only polish, and installer
+permission-preference discipline.
 
 ## Features
 
@@ -111,7 +112,7 @@ directory, the normal install command works:
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.16 install
+npx --yes litclaude-ai@0.3.17 install
 ```
 
 Validate the installed plugin:
@@ -124,7 +125,7 @@ The installer also sets Claude Code's `statusLine` command to the packaged
 LitClaude HUD. A typical no-color render starts like:
 
 ```text
-[🔥LITCLAUDE v0.3.16] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.17] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 The `↻` suffix is a compact rate-limit reset countdown. It is separated from
@@ -257,6 +258,17 @@ explicit `BLOCKED:` degraded-mode note instead of claiming success. In degraded
 mode, LitClaude keeps the durable `litgoal` ledger authoritative and may suggest
 one exact `/goal <completion condition>` or `claude -p "/goal <completion
 condition>"` for the native user surface.
+When you explicitly want a separate native `/goal` worker instead of binding the
+current TUI session, use the dry-run-first launcher:
+
+```bash
+litclaude litgoal native-worker --condition "<completion condition>" --json
+litclaude litgoal native-worker --condition "<completion condition>" --mode bg --name litgoal-worker --execute --json
+```
+
+`native-worker` starts a separate print/background Claude Code worker whose first
+prompt begins with `/goal`; it does not arm the already-open TUI, does not use
+tmux keystroke injection, and does not mutate private transcript metadata.
 For large independent work, LitClaude applies the same principle to Claude
 Code's available orchestration surfaces: `lit workflow`, `lit dynamic workflow`,
 and `lit ultracode` prefer current `ultracode` or explicit “run a workflow” /
@@ -345,6 +357,7 @@ litclaude litgoal create-goals --brief "<brief>" --json
 litclaude litgoal record-evidence --criterion <id> --status pass --json '{"artifact":"...","cleanup":"..."}'
 litclaude litgoal checkpoint --status active --note "<progress>" --json
 litclaude litgoal steer --kind scope --note "<what changed and why>" --json
+litclaude litgoal native-worker --condition "<native worker goal>" --json
 ```
 
 `record-review-blockers` captures unresolved review findings. Malformed JSON,

package/README_ko-KR.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.16-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.17-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -26,14 +26,14 @@
 > 설치되므로, 매번 긴 `--plugin-dir` 없이 일반 `claude` 실행에서
 > LitClaude skill과 hook을 불러올 수 있습니다.
 
-현재 checkout은 `litclaude-ai@0.3.16` 배포 준비용으로 정리되어 있습니다. 목적은
+현재 checkout은 `litclaude-ai@0.3.17` 배포 준비용으로 정리되어 있습니다. 목적은
 다른 PC에서도 빠르게 설치하기 위한 개인용 package metadata를 갖추는 것입니다.
 npm package metadata를 준비했다고 해서 홍보, 공개 저장소 운영, Claude
 marketplace 등록을 의미하지는 않습니다. 새 버전 배포는 항상 별도의 명시적
-승인 후에 진행합니다. v0.3.16 release material은 v0.3.15 Korean AI slop
-remover workflow를 보존하고, WSL2/Windows Terminal truecolor HUD gradient를
-복구하며, v0.3.13 public-source reader runtime과 litresearch activation/read-only
-polish를 유지합니다.
+승인 후에 진행합니다. v0.3.17 release material은 별도 worker 기반 native
+`/goal` launcher를 추가하면서, v0.3.15 Korean AI slop remover workflow와
+v0.3.16 WSL2/Windows Terminal truecolor HUD gradient fix, v0.3.13
+public-source reader runtime, litresearch activation/read-only polish를 유지합니다.
 
 ## 기능
 
@@ -114,7 +114,7 @@ checkout을 먼저 해석해서 `sh: litclaude-ai: command not found`로 실패
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.16 install
+npx --yes litclaude-ai@0.3.17 install
 ```
 
 설치 상태를 확인합니다.
@@ -127,7 +127,7 @@ installer는 Claude Code의 `statusLine` command도 packaged LitClaude HUD로
 설정합니다. 색상을 제거한 예시는 다음처럼 시작합니다.
 
 ```text
-[🔥LITCLAUDE v0.3.16] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.17] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 `↻` 표시는 rate-limit reset까지 남은 시간을 짧게 보여주는 countdown입니다.
@@ -251,6 +251,17 @@ goal이 없을 때만 `create_goal`을 호출하며, `update_goal`은 검증 완
 로컬 evidence ledger를 기준으로 계속 진행하고, 긴 실행 전에 필요한 경우에만
 정확한 `/goal <completion condition>`를 제안합니다. 큰 독립 작업에서는
 같은 원칙을 Claude Code가 노출한 orchestration surface에 적용합니다.
+현재 TUI session을 바인딩하는 대신 별도 native `/goal` worker를 명시적으로
+실행하고 싶다면 dry-run-first launcher를 사용합니다.
+
+```bash
+litclaude litgoal native-worker --condition "<completion condition>" --json
+litclaude litgoal native-worker --condition "<completion condition>" --mode bg --name litgoal-worker --execute --json
+```
+
+`native-worker`는 첫 prompt가 `/goal`로 시작하는 별도 print/background Claude
+Code worker를 시작합니다. 이미 열린 TUI를 arm하지 않고, tmux keystroke
+injection이나 private transcript metadata 변경도 사용하지 않습니다.
 `Workflow`가 노출되면 먼저 제안하고 사용자 opt-in 또는 이미 허용된 orchestration
 상태에서만 `Workflow` tool을 호출합니다. isolated edit lane이 model-facing
 worktree를 필요로 하면 `EnterWorktree`를 사용합니다. CLI surface만 가능한 새 격리
@@ -323,6 +334,7 @@ litclaude litgoal create-goals --brief "<brief>" --json
 litclaude litgoal record-evidence --criterion <id> --status pass --json '{"artifact":"...","cleanup":"..."}'
 litclaude litgoal checkpoint --status active --note "<progress>" --json
 litclaude litgoal steer --kind scope --note "<what changed and why>" --json
+litclaude litgoal native-worker --condition "<native worker goal>" --json
 ```
 
 `record-review-blockers`는 해결되지 않은 review finding을 기록합니다.

package/RELEASE_CHECKLIST.md

@@ -1,17 +1,16 @@
 # LitClaude Release Checklist
 
-Status: `litclaude-ai@0.3.16` is the current release candidate — a WSL2 HUD
-gradient hotfix on top of the Korean AI-slop removal workflow release,
-litresearch activation and usability polish track, JS-only public-source reader
-runtime, resilient public-source research pass, and Claude-native
-goal/workflow/team route hardening. It restores truecolor neon gradient
-rendering when Claude Code drops `WT_SESSION` before invoking the HUD command,
-while preserving the Korean polishing command, strict multi-agent review
-pipeline, fidelity guardrails, package hygiene checks, native route gates, and
-safe start-work handoff behavior.
-`package.json` is aligned to `0.3.16`,
-`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.16`, and the
-plugin-local MCP server reports `0.3.16`.
+Status: `litclaude-ai@0.3.17` is the current release candidate — a dry-run-first
+native `/goal` worker launcher on top of the WSL2 HUD gradient hotfix, Korean
+AI-slop removal workflow release, litresearch activation and usability polish
+track, JS-only public-source reader runtime, resilient public-source research
+pass, and Claude-native goal/workflow/team route hardening. It starts only a
+separate Claude Code print/background worker, while preserving the Korean
+polishing command, strict multi-agent review pipeline, fidelity guardrails,
+package hygiene checks, native route gates, and safe start-work handoff behavior.
+`package.json` is aligned to `0.3.17`,
+`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.17`, and the
+plugin-local MCP server reports `0.3.17`.
 
 This release carries the v0.2.2 Dynamic workflow hardening surfaces:
 `/dynamic-workflow`, `workflow-check --json`, native `/goal` fallback guidance,
@@ -60,9 +59,9 @@ No npm publication is required for this track.
 Before requesting publication approval, confirm these artifacts from the current
 checkout:
 
-- `package.json` version is `0.3.16`.
-- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.16`.
-- `plugins/litclaude/bin/litclaude-mcp.js` reports server version `0.3.16`.
+- `package.json` version is `0.3.17`.
+- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.17`.
+- `plugins/litclaude/bin/litclaude-mcp.js` reports server version `0.3.17`.
 - `lit search` and `lit query` route to `/litclaude:litresearch` without activating on slash mentions, code spans, or non-lit prompts.
 - Litresearch web lanes require public API/feed preference, validator-first checks, route traces, prompt-injection quarantine, and honest auth/paywall/private-data stop reasons.
 - `node bin/litclaude-ai.js public-read <public-url> --json` exposes the guarded JS runtime reader.

package/docs/hooks.md

@@ -66,6 +66,11 @@ Claude Code session, the hook returns explicit `BLOCKED:` / degraded-mode
 guidance, does not claim native goal success, keeps the local `litgoal` evidence
 ledger authoritative, and may suggest `/goal <completion condition>` or
 `claude -p "/goal <completion condition>"` for the native user surface.
+For a separate worker session, `litclaude-ai litgoal native-worker --condition
+"<completion condition>"` builds a dry-run native `/goal` worker command; adding
+`--execute` starts a print/background Claude Code worker whose first prompt begins
+with `/goal`. This worker launcher is not current-TUI auto-arm and must not be
+described as hook-driven slash-command dispatch.
 
 For broad work, the same context ports the LitClaude model-facing principle to
 Claude Code's exposed orchestration surfaces: `lit workflow`, `lit dynamic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litclaude-ai",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "description": "Claude Code-native workflow distribution.",
   "type": "module",
   "bin": {

package/plugins/litclaude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "litclaude",
   "description": "Claude Code-native workflow plugin.",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "author": {
     "name": "LitClaude contributors"
   },

package/plugins/litclaude/bin/litclaude-mcp.js

@@ -3,7 +3,7 @@
 import { readPublicSource } from "../lib/public-source-reader/reader.mjs";
 
 const protocolVersion = "2024-11-05";
-const serverVersion = "0.3.16";
+const serverVersion = "0.3.17";
 
 const publicSourceReadTool = {
   name: "public_source_read",

package/plugins/litclaude/lib/litgoal/cli.mjs

@@ -9,6 +9,7 @@ import {
 } from "./paths.mjs";
 import { readLitgoalState, LitgoalStateError, withLitgoalLock, writeLitgoalState } from "./state.mjs";
 import { resetAutoloopState } from "./autoloop.mjs";
+import { NativeWorkerError, runNativeWorker } from "./native-worker.mjs";
 
 const subcommands = [
   ["create-goals", "Create durable goal records from a brief."],
@@ -18,6 +19,7 @@ const subcommands = [
   ["checkpoint", "Write a continuation checkpoint."],
   ["steer", "Record a steering decision."],
   ["record-review-blockers", "Record review blockers."],
+  ["native-worker", "Launch a separate native /goal worker (dry-run by default)."],
 ];
 
 const helpText = `Usage: litclaude-ai litgoal <command> [...args]
@@ -240,6 +242,8 @@ const runCommand = (cwd, command, args) => {
       return steer(cwd, args);
     case "record-review-blockers":
       return recordReviewBlockers(cwd, args);
+    case "native-worker":
+      return runNativeWorker(args, { cwd });
     default:
       throw new LitgoalCliError(`Unknown litgoal command: ${command}`);
   }
@@ -262,9 +266,10 @@ export const runLitgoalCli = (argv, io = { stdout: process.stdout, stderr: proce
     const outputJson = hasFlag(rest, "--json");
     const result = runCommand(cwd, command, rest);
     emit(io, result, outputJson);
+    if (result?.status === "failed") return result.exitCode || 1;
     return 0;
   } catch (error) {
-    if (error instanceof LitgoalCliError || error instanceof LitgoalStateError) {
+    if (error instanceof LitgoalCliError || error instanceof LitgoalStateError || error instanceof NativeWorkerError) {
       io.stderr.write(`${error.message}\n`);
       return error.status;
     }

package/plugins/litclaude/lib/litgoal/native-worker.mjs

@@ -0,0 +1,102 @@
+import { spawnSync } from "node:child_process";
+
+const secretPatterns = [
+  /sk-[A-Za-z0-9_-]{20,}/u,
+  /(?:api[_-]?key|token|secret|password)\s*=\s*\S+/iu,
+];
+
+const allowedModes = new Set(["print", "bg"]);
+
+export class NativeWorkerError extends Error {
+  constructor(message, status = 64) {
+    super(message);
+    this.name = "NativeWorkerError";
+    this.status = status;
+  }
+}
+
+const hasFlag = (args, flag) => args.includes(flag);
+
+const optionValue = (args, flag) => {
+  const index = args.indexOf(flag);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) return "";
+  return value;
+};
+
+const normalizeSpaces = (value) => value.replace(/\s+/gu, " ").trim();
+
+export const normalizeNativeWorkerCondition = (value) => {
+  if (typeof value !== "string") return "";
+  return normalizeSpaces(value);
+};
+
+export const validateNativeWorkerCondition = (condition) => {
+  if (typeof condition !== "string" || condition.trim() === "") {
+    throw new NativeWorkerError("missing condition");
+  }
+  if (/[\r\n]/u.test(condition)) {
+    throw new NativeWorkerError("condition must be a single line");
+  }
+  const normalized = normalizeNativeWorkerCondition(condition);
+  if (!normalized) throw new NativeWorkerError("missing condition");
+  if (normalized.startsWith("/")) {
+    throw new NativeWorkerError("condition must not start with a slash command");
+  }
+  if (secretPatterns.some((pattern) => pattern.test(normalized))) {
+    throw new NativeWorkerError("condition contains secret-like material");
+  }
+  return normalized;
+};
+
+export const buildNativeWorkerCommand = (args) => {
+  const condition = validateNativeWorkerCondition(optionValue(args, "--condition") ?? "");
+  const mode = optionValue(args, "--mode") || "print";
+  if (!allowedModes.has(mode)) {
+    throw new NativeWorkerError("--mode must be one of print, bg");
+  }
+
+  const goalPrompt = `/goal ${condition}`;
+  const commandArgs = mode === "bg"
+    ? ["--bg", "--name", optionValue(args, "--name") || "", goalPrompt]
+    : ["-p", goalPrompt];
+
+  if (mode === "bg" && !commandArgs[2]) {
+    throw new NativeWorkerError("--name is required for --mode bg");
+  }
+
+  return {
+    status: hasFlag(args, "--execute") ? "ready" : "dry-run",
+    mode,
+    command: "claude",
+    args: commandArgs,
+    prompt: goalPrompt,
+    message: hasFlag(args, "--execute")
+      ? `Native /goal worker ready (${mode}).`
+      : `DRY_RUN: would launch native /goal worker (${mode}).`,
+  };
+};
+
+export const runNativeWorker = (args, { cwd = process.cwd(), env = process.env } = {}) => {
+  const plan = buildNativeWorkerCommand(args);
+  if (!hasFlag(args, "--execute")) return plan;
+
+  const child = spawnSync(plan.command, plan.args, {
+    cwd,
+    env,
+    encoding: "utf8",
+  });
+
+  return {
+    ...plan,
+    status: child.status === 0 ? "executed" : "failed",
+    exitCode: child.status,
+    signal: child.signal,
+    stdout: child.stdout ?? "",
+    stderr: child.stderr ?? (child.error ? String(child.error) : ""),
+    message: child.status === 0
+      ? `Native /goal worker launched (${plan.mode}).`
+      : `Native /goal worker failed (${plan.mode}).`,
+  };
+};

package/plugins/litclaude/skills/litgoal/SKILL.md

@@ -71,6 +71,20 @@ record in the local litgoal ledger. Never auto-type `/goal`, never claim
 slash-command activation without evidence, and never mark a goal complete until
 the local litgoal criteria have passed.
 
+When the user explicitly wants a separate native `/goal` worker rather than the
+current TUI session, use the package CLI launcher. It is dry-run by default:
+
+```sh
+litclaude-ai litgoal native-worker --condition "<completion condition>" --json
+litclaude-ai litgoal native-worker --condition "<completion condition>" --mode bg --name litgoal-worker --execute --json
+```
+
+This starts a separate print/background Claude Code worker whose first prompt
+begins with `/goal`. It does not arm the already-open TUI, does not rely on hook
+slash-command dispatch, does not use tmux keystroke injection, and does not edit
+private transcript metadata. Use worker stdout, `claude agents`, or worker logs as
+the evidence surface for that separate run.
+
 Forward-compat rule: if a future Claude Code build exposes model-facing goal
 tools, use them according to the no-clobber sequence above. Otherwise, the
 degraded-mode `/goal` proposal plus durable ledger is the honest mechanism.