ikanban 0.4.9 → 0.5.0

package/hooks/plan-gate.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// iKanban: no code change before the task has a checked plan (plan 7 P4-T3, decisions D1, D2, D7).
+// An agent hook runs this before each tool call (Claude Code PreToolUse, Gemini CLI BeforeTool,
+// Copilot CLI preToolUse; `npx ikanban hooks install` wires them). An edit, or a shell command that
+// is not on the read list below, needs the task's plan to pass the plan check:
+//   the plan is docs/plans/<KEY>.json, KEY is the task key in the branch name (feat/ABC-12-name).
+// Writing the plan itself, reading, and files outside the repository are never refused. There is
+// no bypass (D2). Input the gate cannot read is refused with exit 2, never passed.
+// `node .iKanban/hooks/plan-gate.js check <plan.json>` runs the same check by hand.
+// It runs no git command: it reads .git directly, as deploy-check.js does.
+const fs = require("node:fs");
+const path = require("node:path");
+
+function checker() {
+  try {
+    return require("./plancheck.js"); // the kit: `ikanban hooks install` copies it next to this file
+  } catch {
+    return require("../../vibe-cli/lib/plancheck.js"); // iKanban's own checkout, where it lives
+  }
+}
+
+const PLAN_DIR = "docs/plans";
+const PROMPT = ".iKanban/prompts/feature-plan.md";
+const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit", "write_file", "replace", "edit", "create"]);
+const SHELL_TOOLS = new Set(["Bash", "PowerShell", "run_shell_command", "bash", "powershell", "run_command"]);
+// Antigravity (agy) documents no list of its tools: these reads pass, every other agy tool is judged as an edit.
+const AGY_READS = new Set(["read_file", "view_file", "list_dir", "grep_search", "find_by_name"]);
+// A shell command passes without a plan only when every part starts with one of these and has no
+// redirect, command substitution or writing flag. shortcut: a list, not a parser; anything else needs the plan.
+const READS = new Set(["ls", "cat", "head", "tail", "wc", "grep", "rg", "pwd", "echo", "which", "stat", "tree", "diff", "cd"]);
+// Long options are allowed only from this list: git and rg accept abbreviations (--out for --output),
+// so a list of bad spellings always leaks. Short-flag groups may not hold a letter that writes or runs
+// a program: git grep -O (a pager), tree -o (a file).
+const SAFE_LONG = new Set(["--", "--oneline", "--stat", "--short", "--porcelain", "--name-only", "--name-status", "--cached", "--staged"]);
+const BAD_SHORT = { git: /O/, tree: /o/ };
+const GIT_READS = new Set(["status", "diff", "log", "show", "rev-parse", "ls-files", "blame", "grep"]);
+
+function repoRoot(cwd) {
+  let start = cwd;
+  while (!fs.existsSync(start) && path.dirname(start) !== start) start = path.dirname(start); // a new file's folder
+  for (let dir = fs.realpathSync(start); ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+function gitDir(root) {
+  const dot = path.join(root, ".git");
+  if (fs.statSync(dot).isDirectory()) return dot;
+  const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dot, "utf8"));
+  return m ? path.resolve(root, m[1].trim()) : null;
+}
+
+/** The branch, or null on a detached HEAD; mid-rebase, the branch being rebased. */
+function branchOf(root) {
+  const dir = gitDir(root);
+  const head = fs.readFileSync(path.join(dir, "HEAD"), "utf8");
+  const m = /^ref:\s*refs\/heads\/(.+)$/m.exec(head);
+  if (m) return m[1].trim();
+  for (const state of ["rebase-merge", "rebase-apply"]) {
+    try {
+      const name = fs.readFileSync(path.join(dir, state, "head-name"), "utf8").trim();
+      if (name.startsWith("refs/heads/")) return name.slice("refs/heads/".length);
+    } catch { /* not this kind of rebase */ }
+  }
+  return null;
+}
+
+const keyOf = (branch) => ((/(?:^|[/_-])([A-Za-z][A-Za-z0-9]{0,9}-\d+)(?=$|[/_-])/.exec(branch) || [])[1] || "").toUpperCase();
+
+/** The tool's arguments from any of the three agents (Copilot may send them as a JSON string). */
+function argsOf(event) {
+  let args = event.tool_input || event.toolArgs || event.tool_args || (event.toolCall && event.toolCall.args) || {};
+  if (typeof args === "string") args = JSON.parse(args);
+  return args && typeof args === "object" ? args : {};
+}
+
+/** The real path of a file that may not exist yet: its nearest existing folder, resolved through links. */
+function real(file) {
+  let dir = file;
+  while (!fs.existsSync(dir) && path.dirname(dir) !== dir) dir = path.dirname(dir);
+  return path.join(fs.realpathSync(dir), path.relative(dir, file));
+}
+
+function filesOf(args) {
+  return ["file_path", "path", "notebook_path", "filePath", "absolute_path", "Path", "TargetFile", "AbsolutePath"]
+    .map((k) => args[k]).filter((v) => typeof v === "string");
+}
+
+function readOnly(command) {
+  // Shell syntax the gate does not model is a write: any $ ($VAR, ${x}, $'\x2d', $(…)), backticks, process
+  // substitution, and any brace or glob ({--output=x,} and --out* expand into flags; ls *.js needs the plan too).
+  if (/[`${}*?[\]]|<\(|>\(/.test(command)) return false;
+  // Any redirect other than to /dev/null or between streams writes; a ">" in quotes counts too (safe side).
+  const plain = command.replace(/(?:\d|&)?>{1,2}\s*\/dev\/null(?=$|[\s;&|)])|\d*>&(?:\d+|-)(?=$|[\s;&|)])/g, "");
+  if (/>/.test(plain)) return false;
+  if (/&/.test(plain.replace(/&&/g, ""))) return false; // a lone & runs the next command where the split cannot see it
+  return command.split(/&&|\|\||[;|\n]/).map((p) => p.trim()).filter(Boolean).every((part) => {
+    // Words as the shell sees them: quotes and backslashes removed ("-exec", -e\xec and '--out'put all count).
+    const w = part.split(/\s+/).map((x) => x.replace(/["'\\]/g, ""));
+    part = w.join(" ");
+    if (/^(node\s+\.iKanban\/hooks\/plan-gate\.js\s+check|npx\s+(-y\s+)?ikanban\s+plan\s+check|ikanban\s+plan\s+check)\s/.test(part + " ")) return true;
+    // Making the plan folder is part of writing the plan: mkdir [-p] of paths inside docs/plans only.
+    if (w[0] === "mkdir") return w.length > 1 && w.slice(1).every((x) => x === "-p" || /^(\.\/)?docs\/plans(\/[\w.-]+)*\/?$/.test(x) && !x.includes(".."));
+    if (w[0] === "find") return !w.some((x) => /^-(exec|ok|delete|fprint|fls)/.test(x));
+    for (const x of w.slice(1)) {
+      if (x.startsWith("--") && !SAFE_LONG.has(x)) return false;
+      // Every character of a short-flag word: -nO./run.sh and -1O hide the letter (a value with it is refused too, safe side).
+      if (/^-[^-]/.test(x) && BAD_SHORT[w[0]] && BAD_SHORT[w[0]].test(x.slice(1))) return false;
+    }
+    if (w[0] === "git") return GIT_READS.has(w[1]) || (w[1] === "branch" && !w.some((x) => /^-[dDmMcC]$|^--(delete|move|copy)/.test(x)));
+    return READS.has(w[0]);
+  });
+}
+
+/** Each repository this call writes to, with why it needs that repository's plan. Each edited file
+ *  is judged in its own repository (walking up to its .git), a shell command in its own folder. */
+function targets(event, cwd) {
+  const agy = Boolean(event.toolCall);
+  const tool = event.tool_name || event.toolName || (agy && event.toolCall.name) || "";
+  const args = argsOf(event);
+  if (SHELL_TOOLS.has(tool)) {
+    // One command field per agent; two of them is input the gate cannot judge.
+    if (typeof args.command === "string" && typeof args.CommandLine === "string") throw new Error("the call names two commands");
+    const command = agy ? args.CommandLine : args.command;
+    if (typeof command === "string" && readOnly(command)) return [];
+    // The agent names the folder (agy Cwd): judge the command in the workspace repository and in that one.
+    const roots = new Set([repoRoot(cwd), agy && typeof args.Cwd === "string" ? repoRoot(args.Cwd) : null].filter(Boolean));
+    if (!roots.size) throw new Error("the shell command runs outside every repository the gate knows");
+    return [...roots].map((root) => ({ root, why: "this shell command can write" }));
+  }
+  // agy lists no edit tools: any agy tool that is not a known read is judged as an edit (deny by default).
+  if (agy ? AGY_READS.has(tool) : !EDIT_TOOLS.has(tool)) return [];
+  const files = filesOf(args).map((f) => real(path.resolve(cwd, f)));
+  if (!files.length) {
+    const root = repoRoot(cwd);
+    return root ? [{ root, why: `this ${tool || "tool"} call names no file the gate can read` }] : [];
+  }
+  const out = [];
+  for (const f of files) {
+    const root = repoRoot(path.dirname(f));
+    if (!root) continue; // outside every repository
+    const plans = path.join(root, PLAN_DIR);
+    const rel = path.relative(plans, f);
+    if (rel && !rel.startsWith("..") && !path.isAbsolute(rel) && f.endsWith(".json")) continue; // the plan itself
+    out.push({ root, why: `this edit changes ${path.relative(root, f)}` });
+  }
+  return out;
+}
+
+/** The refusal, or null when the task's plan passes. */
+function refusal(root, why) {
+  const branch = branchOf(root);
+  if (!branch) return `${why}, and the repository is on a detached HEAD, so no task's plan can open it. Run: git switch -c feat/<TASK-KEY>-<short-name>`;
+  const key = keyOf(branch);
+  if (!key) return `${why}, and branch ${branch} names no task key, so no plan can open it. Run: git switch -c feat/<TASK-KEY>-<short-name> (for example feat/ABC-12-login)`;
+  const rel = `${PLAN_DIR}/${key}.json`;
+  const how = `Write the plan for ${key} from ${PROMPT} (template: .iKanban/templates/feature-plan-template.json) at ${rel}, then run: node .iKanban/hooks/plan-gate.js check ${rel} (the same check as ikanban plan check). There is no setting that turns the gate off: a passing plan is the only way through`;
+  let plan;
+  try {
+    plan = JSON.parse(fs.readFileSync(path.join(root, rel), "utf8"));
+  } catch (e) {
+    return `${why}, and task ${key} has no plan the gate can read at ${rel} (${e.code === "ENOENT" ? "not found" : e.message}). ${how}`;
+  }
+  const { errors } = checker().check(plan);
+  if (!errors.length) return null;
+  const list = errors.slice(0, 8).map((e) => `${e.where}: ${e.problem}. Fix: ${e.fix}.`).join("\n");
+  return `${why}, and the plan ${rel} does not pass the check yet:\n${list}${errors.length > 8 ? `\n…and ${errors.length - 8} more` : ""}\n${how}`;
+}
+
+function answer(event, reason) {
+  if (event.toolName !== undefined || event.toolArgs !== undefined) return { permissionDecision: "deny", permissionDecisionReason: `iKanban plan gate: ${reason}` };
+  if (event.hook_event_name === "BeforeTool" || event.toolCall) return { decision: "deny", reason: `iKanban plan gate: ${reason}` };
+  return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: `iKanban plan gate: ${reason}` } };
+}
+
+function main(input) {
+  const event = JSON.parse(input);
+  if (!event || typeof event !== "object") throw new Error("the hook input is not a JSON object");
+  // agy sends no cwd, only its workspace folders (and runs the hook from .agents/); a relative path
+  // there resolves against the first, and each file is then judged in its own repository.
+  const given = typeof event.cwd === "string" ? event.cwd : Array.isArray(event.workspacePaths) ? event.workspacePaths[0] : undefined;
+  const dir = typeof given === "string" && fs.existsSync(given) ? given : process.cwd();
+  for (const { root, why } of targets(event, dir)) {
+    const reason = refusal(root, why);
+    if (reason) return answer(event, reason);
+  }
+  return {};
+}
+
+if (process.argv[2] === "check") {
+  process.exit(checker().run(process.argv.slice(2)));
+} else {
+  let input = "";
+  process.stdin.on("data", (c) => { input += c; });
+  process.stdin.on("end", () => {
+    try {
+      process.stdout.write(`${JSON.stringify(main(input))}\n`);
+      process.exit(0);
+    } catch (e) {
+      // Fail closed: every agent treats exit 2 as a refusal and shows stderr.
+      process.stderr.write(`iKanban plan gate: could not check this call (${e.message}), so it is refused. Run: node .iKanban/hooks/plan-gate.js check ${PLAN_DIR}/<TASK-KEY>.json\n`);
+      process.exit(2);
+    }
+  });
+}

package/hooks/trace.js

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+// iKanban: record what the agent did (plan 35 V6-T3, V13-T4). Each turn (the first tool call up to
+// the end of the turn) becomes one trace on iKAgent → Agentification → What agent did: every tool
+// call, its result or error, and the reply, with times (and the turn's tokens for Claude Code).
+// - Claude Code runs it on PostToolUse, PostToolUseFailure and Stop.
+// - Gemini CLI on AfterTool and AfterAgent (geminicli.com/docs/hooks/reference).
+// - Copilot CLI on postToolUse, postToolUseFailure and agentStop; its input names no event, so the
+//   wiring passes it: `trace.js copilot:postToolUse` (docs.github.com/en/copilot/reference/hooks-configuration).
+// - Antigravity CLI (agy, where Gemini users went) on PostToolUse and Stop, passed the same way:
+//   `trace.js agy:PostToolUse` (antigravity.google/docs/hooks). Recorded as agent "gemini", as the runner does.
+//
+// - Off until the developer runs `node .iKanban/hooks/trace.js --on` in the repository (owner Q6).
+//   The opt-in and the key are copied to ~/.ikanban/trace.json, outside the repository; a
+//   repository cannot turn tracing on by committing a settings file (security review).
+// - The hook runs no git command: a repository's own git config could run one.
+// - The hook records, never the model: the trace's write token is kept in ~/.ikanban/traces/,
+//   outside the repository, and sent only to iKanban's API (ikanbanFetch). The server scrubs
+//   secrets from every step and cuts it at 8 KB.
+// - The task is IKANBAN_TASK, else the key in the branch name (ika-123-fix → IKA-123), read from .git/HEAD.
+// - It never blocks the agent: it always exits 0 and prints "{}"; problems go to stderr.
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { runCommand, ikanbanFetch, teamId } = require("./ikanban-safe.js");
+
+const MAX_BODY = 8 * 1024;
+const TIMEOUT_MS = 5000;
+
+/** The repository root: the nearest folder up from cwd that holds `.git` (a folder, or the
+ *  file a worktree has). Found without running git: a repository's own git config (for example
+ *  core.fsmonitor) can make git run a command, and the hook must run nothing before the opt-in. */
+function repoRoot(cwd) {
+  for (let dir = fs.realpathSync(cwd); ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+/** The git folder of a repository (a worktree's `.git` file names it). */
+function gitDir(root) {
+  const dot = path.join(root, ".git");
+  if (fs.statSync(dot).isDirectory()) return dot;
+  const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dot, "utf8"));
+  return m ? path.resolve(root, m[1].trim()) : null;
+}
+
+const optInFile = () => path.join(os.homedir(), ".ikanban", "trace.json");
+
+function readOptIn() {
+  try {
+    return JSON.parse(fs.readFileSync(optInFile(), "utf8"));
+  } catch {
+    return { repos: {} };
+  }
+}
+
+function writeOptIn(doc) {
+  fs.mkdirSync(path.dirname(optInFile()), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(optInFile(), JSON.stringify(doc, null, 2), { mode: 0o600 });
+  fs.chmodSync(optInFile(), 0o600);
+}
+
+/** What this work sends to, or null: only a repository the developer turned on with
+ *  `trace.js --on`, kept outside the repository (owner Q6; security review). V13-T1: or a
+ *  folder above it turned on with `--on --nested` (a workspace that holds project repositories). */
+function settings(cwd) {
+  const repos = readOptIn().repos || {};
+  const root = repoRoot(cwd);
+  if (root && repos[root]) return repos[root];
+  // Only a folder turned on with --nested covers the repositories inside it.
+  for (let dir = root ? path.dirname(root) : fs.realpathSync(cwd); ; dir = path.dirname(dir)) {
+    if (repos[dir] && repos[dir].nested) return repos[dir];
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+/** git with the repository's command hooks switched off, for `--on` only. */
+function safeGit(root, args) {
+  return runCommand("git", ["-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", ...args], {
+    cwd: root, encoding: "utf8", env: { ...process.env, GIT_CONFIG_NOSYSTEM: "1" },
+  });
+}
+
+/** `trace.js --on`: the developer turns tracing on for this repository. The settings file must
+ *  be the developer's own: not committed (in any letter case), not a symlink. */
+function turnOn(cwd, nested) {
+  const root = repoRoot(cwd);
+  if (!root) throw new Error("not inside a git repository");
+  let file = null;
+  for (const kit of [".iKanban", ".i-kanban"]) {
+    const dir = path.join(root, kit);
+    const f = path.join(dir, "settings-local.json");
+    if (!fs.existsSync(f)) continue;
+    if (fs.lstatSync(dir).isSymbolicLink() || fs.lstatSync(f).isSymbolicLink()) {
+      throw new Error(`${kit}/settings-local.json is a symlink; use the file Set up wrote`);
+    }
+    file = f;
+    break;
+  }
+  if (!file) throw new Error("no .iKanban/settings-local.json here; run Set up in the desktop app first");
+  const tracked = safeGit(root, ["ls-files", "-z"]);
+  if (tracked.status !== 0) throw new Error("git could not list this repository's files");
+  if (tracked.stdout.split("\0").some((p) => /^\.i-?kanban\/settings-local\.json$/i.test(p))) {
+    throw new Error("settings-local.json is committed to this repository, so it is not used; it must stay git-ignored");
+  }
+  const cfg = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (!cfg.api_url || !cfg.api_key || !cfg.team) throw new Error("settings-local.json has no api_url, api_key or team");
+  const doc = readOptIn();
+  doc.repos = doc.repos || {};
+  doc.repos[root] = { api_url: cfg.api_url, api_key: cfg.api_key, team: cfg.team, trace_plan: cfg.trace_plan, trace_phase: cfg.trace_phase, nested: nested || undefined };
+  writeOptIn(doc);
+  return `What agent did is on for ${root}${nested ? " and the repositories inside it" : ""}: traces go to team ${cfg.team} at ${cfg.api_url}`;
+}
+
+function turnOff(cwd) {
+  const root = repoRoot(cwd);
+  const doc = readOptIn();
+  if (root && doc.repos) delete doc.repos[root];
+  writeOptIn(doc);
+  return `What agent did is off for ${root}`;
+}
+
+function taskKey(root) {
+  const own = (process.env.IKANBAN_TASK || "").trim();
+  if (/^[A-Za-z][A-Za-z0-9]{0,9}-\d+$/.test(own)) return own.toUpperCase();
+  let head = "";
+  try {
+    head = fs.readFileSync(path.join(gitDir(root), "HEAD"), "utf8");
+  } catch {
+    return null;
+  }
+  const branch = (/^ref:\s*refs\/heads\/(.+)$/m.exec(head) || [])[1] || "";
+  const m = /(?:^|[/_-])([A-Za-z][A-Za-z0-9]{0,9}-\d+)(?=$|[/_-])/.exec(branch.trim());
+  return m ? m[1].toUpperCase() : null;
+}
+
+const stateDir = () => path.join(os.homedir(), ".ikanban", "traces");
+const stateFile = (session) => path.join(stateDir(), `${String(session).replace(/[^A-Za-z0-9-]/g, "").slice(0, 80) || "session"}.json`);
+
+function readState(session) {
+  try {
+    return JSON.parse(fs.readFileSync(stateFile(session), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeState(session, state) {
+  fs.mkdirSync(stateDir(), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(stateFile(session), JSON.stringify(state), { mode: 0o600 });
+}
+
+/** One hook at a time per session: Claude Code runs the hooks of parallel tool calls side by
+ *  side, and two that read an empty state would start two traces. A lock older than the
+ *  hook's own time limit is from a hook that died, so it is taken over. */
+async function withLock(session, fn) {
+  fs.mkdirSync(stateDir(), { recursive: true, mode: 0o700 });
+  const lock = `${stateFile(session)}.lock`;
+  for (let waited = 0; ; waited += 25) {
+    try {
+      fs.closeSync(fs.openSync(lock, "wx", 0o600));
+      break;
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      let age = 0;
+      try { age = Date.now() - fs.statSync(lock).mtimeMs; } catch { continue; }
+      if (age > 3 * TIMEOUT_MS || waited > 3 * TIMEOUT_MS) fs.rmSync(lock, { force: true });
+      await new Promise((r) => setTimeout(r, 25));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    fs.rmSync(lock, { force: true });
+  }
+}
+
+/** Text for a step, cut before it leaves the laptop (the server scrubs and cuts again). */
+function text(value) {
+  const s = typeof value === "string" ? value : JSON.stringify(value ?? "");
+  return s.length > MAX_BODY ? `${s.slice(0, MAX_BODY)}…[cut]` : s;
+}
+
+/** This turn's tokens and model from the transcript: assistant messages after the last prompt,
+ *  each message once (the transcript repeats a message's usage on each of its blocks). */
+function turnUsage(transcriptPath) {
+  let lines = [];
+  try {
+    lines = fs.readFileSync(transcriptPath, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+  } catch {
+    return {};
+  }
+  let start = 0;
+  lines.forEach((r, i) => {
+    const c = r.type === "user" && r.message && r.message.content;
+    if (typeof c === "string" || (Array.isArray(c) && c.some((x) => x && x.type === "text"))) start = i;
+  });
+  const seen = new Map();
+  let model;
+  for (const r of lines.slice(start)) {
+    if (r.type !== "assistant" || !r.message) continue;
+    model = r.message.model || model;
+    seen.set(r.message.id, r.message.usage || {});
+  }
+  let tokensIn = 0, tokensOut = 0;
+  for (const u of seen.values()) {
+    tokensIn += (u.input_tokens || 0) + (u.cache_creation_input_tokens || 0) + (u.cache_read_input_tokens || 0);
+    tokensOut += u.output_tokens || 0;
+  }
+  return seen.size ? { tokensIn, tokensOut, model } : {};
+}
+
+async function api(cfg, apiPath, body, token) {
+  const res = await ikanbanFetch(apiPath, {
+    base: cfg.api_url, token: cfg.api_key, method: "POST", body, timeoutMs: TIMEOUT_MS,
+    headers: token ? { "X-Trace-Token": token } : {},
+  });
+  if (!res.ok) throw new Error(`iKanban answered ${res.status}`);
+  return (await res.json()).data;
+}
+
+/** One shape for the three agents' hook inputs: which agent, what happened (tool, failed or
+ *  end), and its parts. Anything else is null and records nothing. */
+function normalize(event, arg) {
+  const agy = /^agy:(PostToolUse|Stop)$/.exec(arg || "");
+  if (agy) {
+    const call = event.toolCall && typeof event.toolCall === "object" ? event.toolCall : {};
+    const what = agy[1] === "Stop" ? "end" : event.error ? "failed" : "tool";
+    return { agent: "gemini", what, session: event.conversationId, name: call.name, input: call.args, output: "", error: event.error, reply: "" };
+  }
+  const copilot = /^copilot:(postToolUse|postToolUseFailure|agentStop)$/.exec(arg || "");
+  if (copilot) {
+    const what = { postToolUse: "tool", postToolUseFailure: "failed", agentStop: "end" }[copilot[1]];
+    const result = event.toolResult && typeof event.toolResult === "object" ? event.toolResult.textResultForLlm : event.toolResult;
+    return { agent: "copilot", what, session: event.sessionId, name: event.toolName, input: event.toolArgs, output: result, error: event.error, reply: "" };
+  }
+  const what = { PostToolUse: "tool", PostToolUseFailure: "failed", Stop: "end", AfterTool: "tool", AfterAgent: "end" }[event.hook_event_name];
+  if (!what) return null;
+  const gemini = event.hook_event_name === "AfterTool" || event.hook_event_name === "AfterAgent";
+  return {
+    agent: gemini ? "gemini" : "claude", what, session: event.session_id, name: event.tool_name || event.toolName,
+    input: event.tool_input, output: event.tool_response, error: event.error, duration_ms: event.duration_ms,
+    reply: gemini ? event.prompt_response : event.last_assistant_message, transcript: gemini ? null : event.transcript_path,
+  };
+}
+
+async function main(input, arg) {
+  const event = JSON.parse(input || "{}");
+  const dir = typeof event.cwd === "string" ? event.cwd : Array.isArray(event.workspacePaths) ? event.workspacePaths[0] : undefined;
+  const cwd = typeof dir === "string" && fs.existsSync(dir) ? dir : process.cwd();
+  const cfg = settings(cwd);
+  if (!cfg || !cfg.api_url || !cfg.api_key || !cfg.team) return;
+  const e = normalize(event, arg);
+  if (!e) return;
+  const session = e.session || "session";
+  return withLock(session, () => record(cfg, cwd, session, e));
+}
+
+async function record(cfg, cwd, session, e) {
+  const team = encodeURIComponent(await teamId({ base: cfg.api_url, token: cfg.api_key, team: cfg.team }));
+  const now = new Date().toISOString();
+
+  let state = readState(session);
+  if (!state) {
+    const started = await api(cfg, `/api/teams/${team}/agent-traces`, {
+      task: taskKey(repoRoot(cwd)), run: session, agent: e.agent, source: "kit",
+      plan: cfg.trace_plan || undefined, phase: cfg.trace_phase || undefined,
+    });
+    state = { id: started.id, token: started.write_token, seq: 0 };
+    writeState(session, state);
+  }
+  const spans = [];
+  const add = (span) => spans.push({ seq: ++state.seq, at: now, ...span });
+  const name = e.name || "tool";
+  // Claude Code's transcript gives the turn's tokens and model; the other agents' are not read.
+  const u = e.transcript ? turnUsage(e.transcript) : {};
+  if (e.what === "end") {
+    add({ kind: "reply", name: "reply", body: text(e.reply || ""), tokens_in: u.tokensIn, tokens_out: u.tokensOut });
+  } else {
+    add({ kind: "tool_call", name, body: text(e.input), duration_ms: e.duration_ms });
+    add(e.what === "tool" ? { kind: "tool_result", name, body: text(e.output) } : { kind: "error", name, body: text(e.error) });
+  }
+  const base = `/api/teams/${team}/agent-traces/${encodeURIComponent(state.id)}`;
+  await api(cfg, `${base}/spans`, { spans }, state.token);
+  if (e.what === "end") {
+    await api(cfg, `${base}/end`, { outcome: "passed", model: u.model }, state.token);
+    fs.rmSync(stateFile(session), { force: true });
+    await sendPlan(cfg, cwd, team, e.agent).catch((err) => process.stderr.write(`iKanban trace hook: plan not sent: ${err.message}\n`));
+  } else {
+    writeState(session, state);
+  }
+}
+
+const MAX_PLAN = 256 * 1024;
+const planState = (key) => path.join(os.homedir(), ".ikanban", "plans", `${key}.sha256`);
+
+/** IKA-2741 (plan 7 P6-T6): the task's plan, checked with the kit's own checker, goes to the Plan
+ *  stage in Pipelines ("checked on laptop"). Only a regular file at docs/plans/<KEY>.json, and only
+ *  when it changed since the last send. It is never a merge verdict: only the runner gives one. */
+async function sendPlan(cfg, cwd, team, agent) {
+  const root = repoRoot(cwd);
+  const key = root && taskKey(root);
+  if (!key) return;
+  const file = path.join(root, "docs", "plans", `${key}.json`);
+  let st;
+  try {
+    st = fs.lstatSync(file);
+  } catch {
+    return; // no plan for this task yet
+  }
+  if (!st.isFile() || st.size > MAX_PLAN) return;
+  const text = fs.readFileSync(file, "utf8");
+  const sha = require("node:crypto").createHash("sha256").update(text).digest("hex");
+  try {
+    if (fs.readFileSync(planState(key), "utf8") === sha) return;
+  } catch {
+    // never sent
+  }
+  let plan;
+  try {
+    plan = JSON.parse(text);
+  } catch {
+    return; // the plan gate reports an unreadable plan; nothing to show
+  }
+  if (!Array.isArray(plan.phases)) return;
+  const { errors } = checker().check(plan);
+  const first = errors[0];
+  const detail = first ? `${first.where}: ${first.problem}`.replace(/\s+/g, " ").slice(0, 300) : undefined;
+  await api(cfg, `/api/teams/${team}/laptop-plans`, { task: key, agent, status: errors.length ? "failed" : "passed", detail, plan: plan.phases,
+    decisions: Array.isArray(plan.decisions) ? plan.decisions : undefined });
+  fs.mkdirSync(path.dirname(planState(key)), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(planState(key), sha, { mode: 0o600 });
+}
+
+function checker() {
+  try {
+    return require("./plancheck.js"); // the kit: `ikanban hooks install` copies it next to this file
+  } catch {
+    return require("../../vibe-cli/lib/plancheck.js"); // iKanban's own checkout, where it lives
+  }
+}
+
+const mode = process.argv[2];
+if (mode === "--on" || mode === "--off") {
+  try {
+    process.stdout.write(`${mode === "--on" ? turnOn(process.cwd(), process.argv[3] === "--nested") : turnOff(process.cwd())}\n`);
+    process.exit(0);
+  } catch (e) {
+    process.stderr.write(`iKanban trace: ${e.message}\n`);
+    process.exit(1);
+  }
+}
+
+let input = "";
+process.stdin.on("data", (c) => { input += c; });
+process.stdin.on("end", async () => {
+  try {
+    await main(input, process.argv[2]);
+  } catch (e) {
+    process.stderr.write(`iKanban trace hook: ${e.message}\n`);
+  }
+  // Antigravity's Stop needs a decision; any value but "continue" lets the agent stop.
+  process.stdout.write(process.argv[2] === "agy:Stop" ? '{"decision":"allow"}\n' : "{}\n");
+  process.exit(0);
+});

package/lib/ikanban-safe.js

@@ -64,16 +64,20 @@ function apiOrigin(base) {
 
 /**
  * fetch() to iKanban's API. opts: base (the signed-in api_url), token, method, body (sent as
- * JSON), timeoutMs. Refuses another host, an absolute or protocol-relative path, and redirects.
+ * JSON), timeoutMs, headers (only X-Trace-Token is passed on). Refuses another host, an absolute or protocol-relative path, and redirects.
  */
-async function ikanbanFetch(apiPath, { base, token, method = "GET", body, timeoutMs = 60000 } = {}) {
+async function ikanbanFetch(apiPath, { base, token, method = "GET", body, timeoutMs = 60000, headers: extra = {} } = {}) {
   const origin = apiOrigin(base);
   if (typeof apiPath !== "string" || !apiPath.startsWith("/") || apiPath.startsWith("//")) {
     throw new Error(`"${apiPath}" is not a path on the iKanban API; the key was not sent`);
   }
   const url = new URL(apiPath, origin);
   if (url.origin !== origin) throw new Error(`"${apiPath}" leaves ${origin}; the key was not sent`);
+  // Plan 35: X-Trace-Token (a trace's write token) is the one extra header; nothing may replace the key's.
   const headers = { Authorization: `Bearer ${token}` };
+  for (const [k, v] of Object.entries(extra)) {
+    if (k.toLowerCase() === "x-trace-token" && typeof v === "string" && /^[A-Za-z0-9]{16,128}$/.test(v)) headers["X-Trace-Token"] = v;
+  }
   if (body !== undefined) headers["Content-Type"] = "application/json";
   let res;
   try {
@@ -93,4 +97,23 @@ async function ikanbanFetch(apiPath, { base, token, method = "GET", body, timeou
   return res;
 }
 
-module.exports = { runCommand, startCommand, ikanbanFetch, apiOrigin };
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The team's id for API paths. Set up writes the team's key ("IKA") into settings-local.json,
+ *  and the API's routes take the id, so a key is looked up among the caller's teams. */
+async function teamId({ base, token, team }) {
+  if (UUID.test(String(team || ""))) return team;
+  const res = await ikanbanFetch("/api/teams", { base, token, timeoutMs: 5000 });
+  if (!res.ok) throw new Error(`iKanban answered ${res.status} for the team list`);
+  const json = await res.json();
+  const list = Array.isArray(json.data) ? json.data : (json.data && json.data.teams) || [];
+  // Security review: the key first; a name only when no key matches; never a guess between two.
+  const want = String(team || "").toLowerCase();
+  const byKey = list.filter((t) => String(t.identifier || "").toLowerCase() === want);
+  const hits = byKey.length ? byKey : list.filter((t) => String(t.name || "").toLowerCase() === want);
+  if (hits.length > 1) throw new Error(`more than one team is called "${team}"; put the team's id in settings-local.json`);
+  if (!hits.length || !UUID.test(String(hits[0].id))) throw new Error(`no team "${team}" for this key`);
+  return hits[0].id;
+}
+
+module.exports = { runCommand, startCommand, ikanbanFetch, apiOrigin, teamId };