klyro 1.0.1 → 1.0.2

package/dist/mcp/registry.js

@@ -15,7 +15,18 @@
  * write-only metadata today), so we pick the most restrictive class,
  * 'admin' — the same class as `spawn_agent`, since MCP tools execute
  * arbitrary external side effects (read/write/network) outside our control.
+ *
+ * Debug capture: when `KLYRO_MCP_DEBUG=1` is set, every MCP tool success
+ * AND error ALSO writes the UNREDACTED raw JSON payload (pre-redaction,
+ * may contain secrets — handle accordingly) to
+ * `<configDir>/tool-output/mcp-<server>-<ts>.json` (mode 0600) and notes
+ * the path on stderr. `<configDir>` is `$KLYRO_CONFIG_DIR` when set,
+ * otherwise `~/.klyro`. Default off: with the flag unset (or any value
+ * other than `1`) no file is written and behaviour is unchanged.
  */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { McpClient, McpError } from './client.js';
 import { loadMcpServers } from './config.js';
 import { evaluateMcpPolicy } from './policy.js';
@@ -48,7 +59,39 @@ export function sanitizeMcpName(server, tool) {
 function errMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
-async function executeMcpTool(spec, toolDef, client, input, ctx) {
+/** Debug-capture filename disambiguator when Date.now() collides. */
+let mcpDebugCounter = 0;
+/**
+ * `KLYRO_MCP_DEBUG=1` capture: write the UNREDACTED raw payload to
+ * `<configDir>/tool-output/mcp-<server>-<ts>.json` (mode 0600) + a stderr
+ * note. Best-effort and synchronous — never throws into the tool path.
+ */
+function captureMcpDebug(server, tool, payload) {
+    if (process.env.KLYRO_MCP_DEBUG !== '1')
+        return;
+    try {
+        const base = process.env.KLYRO_CONFIG_DIR ?? path.join(os.homedir() || process.cwd(), '.klyro');
+        const dir = path.join(base, 'tool-output');
+        fs.mkdirSync(dir, { recursive: true });
+        const safe = server.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 32) || 'server';
+        let file = path.join(dir, `mcp-${safe}-${Date.now()}.json`);
+        if (fs.existsSync(file)) {
+            mcpDebugCounter += 1;
+            file = path.join(dir, `mcp-${safe}-${Date.now()}-${mcpDebugCounter}.json`);
+        }
+        fs.writeFileSync(file, JSON.stringify({ server, tool, payload }, null, 2), { mode: 0o600 });
+        try {
+            process.stderr.write(`klyro: mcp debug captured ${server}/${tool} -> ${file}\n`);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    catch {
+        /* best-effort only */
+    }
+}
+async function executeMcpTool(server, spec, toolDef, client, input, ctx) {
     try {
         // (1) Deny-by-default — runs BEFORE any client I/O.
         const decision = evaluateMcpPolicy(spec.policy, toolDef.name);
@@ -67,16 +110,20 @@ async function executeMcpTool(spec, toolDef, client, input, ctx) {
             // (3) Typed server failures keep their code; everything else is TOOL_ERROR.
             // Redact BEFORE the message can reach the model/trace.
             if (err instanceof McpError) {
+                captureMcpDebug(server, toolDef.name, { code: err.code, message: err.message, details: err.details });
                 return { ok: false, error: { code: err.code, message: redact(err.message) } };
             }
+            captureMcpDebug(server, toolDef.name, { message: errMessage(err) });
             return { ok: false, error: { code: 'TOOL_ERROR', message: redact(errMessage(err)) } };
         }
         // (4) Server-reported error → TOOL_ERROR, redacted, bounded.
         if (res.isError) {
+            captureMcpDebug(server, toolDef.name, res.raw);
             return { ok: false, error: { code: 'TOOL_ERROR', message: redact(res.text).slice(0, 2000) } };
         }
         // (5) Success — redact BEFORE the value reaches the model/trace, then
         // truncate to a bounded size with a marker.
+        captureMcpDebug(server, toolDef.name, res.raw);
         const redacted = redact(res.text);
         if (redacted.length > MCP_SUCCESS_MAX_CHARS) {
             return {
@@ -177,7 +224,7 @@ export async function registerMcpServers(cfg, opts) {
                     // 'admin': most restrictive class — MCP tools run arbitrary
                     // external side effects; nothing in src reads this field yet.
                     permission: 'admin',
-                    execute: (input, ctx) => executeMcpTool(boundSpec, boundDef, boundClient, input, ctx),
+                    execute: (input, ctx) => executeMcpTool(server, boundSpec, boundDef, boundClient, input, ctx),
                 });
                 registry.register(tool);
                 registered.push(name);

package/dist/policy/engine.d.ts

@@ -84,6 +84,22 @@ export declare class PolicyEngine {
 /** Builtin set of rules. Order matters: first match wins. */
 export declare function builtinRules(): PolicyRule[];
 export declare function matchesGlobRule(call: ToolCallLike, rule: string): boolean;
+/** Branches that `git push` must never target without an explicit opt-out. */
+export declare const PROTECTED_BRANCHES: string[];
+/** Matches `push` with a protected branch name later on the same line. */
+export declare const PROTECTED_PUSH_RE: RegExp;
+/**
+ * True when the command is a `git push` with NO ref/positional args
+ * (e.g. `git push`, `git push -f`) — i.e. it pushes whatever is checked
+ * out. `git push origin feature` is explicit, not bare.
+ */
+export declare function isBareGitPush(cmd: string): boolean;
+/**
+ * Resolve the currently checked-out branch via `git branch --show-current`.
+ * Returns null on any failure (not a repo, git missing) — callers treat
+ * null as "unknown" and allow the normal policy flow to continue.
+ */
+export declare function currentGitBranch(cwd: string): string | null;
 /** Hard-deny for obviously destructive shell patterns. */
 export declare const shellDenyRule: PolicyRule;
 /** Allowlist for shell — exact or prefix. Anything not in the list asks. */

package/dist/policy/engine.js

@@ -66,7 +66,11 @@ export class PolicyEngine {
         }
         else if (ctx.config.mode === 'plan') {
             // plan mode: block all writes (edit)
-            if (call.name === 'write_file' || call.name === 'edit_file') {
+            if (call.name === 'write_file' ||
+                call.name === 'edit_file' ||
+                call.name === 'multi_edit' ||
+                call.name === 'apply_patch' ||
+                call.name === 'memory_write') {
                 return { action: 'deny', reason: 'plan mode: writes blocked — use /permissions to allow or switch mode' };
             }
         }
@@ -226,6 +230,48 @@ function startsWithAny(haystack, needles) {
         return h === nl || h.startsWith(nl + ' ') || h.startsWith(nl + '\t');
     });
 }
+/** Branches that `git push` must never target without an explicit opt-out. */
+export const PROTECTED_BRANCHES = ['main', 'master', 'production'];
+/** Matches `push` with a protected branch name later on the same line. */
+export const PROTECTED_PUSH_RE = /\bpush\b[^\n]*\b(main|master|production)\b/;
+const GIT_PUSH_RE = /\bgit\b[^\n]*\bpush\b/;
+/**
+ * True when the command is a `git push` with NO ref/positional args
+ * (e.g. `git push`, `git push -f`) — i.e. it pushes whatever is checked
+ * out. `git push origin feature` is explicit, not bare.
+ */
+export function isBareGitPush(cmd) {
+    if (!GIT_PUSH_RE.test(cmd))
+        return false;
+    const idx = cmd.search(/\bpush\b/);
+    const rest = idx >= 0 ? cmd.slice(idx + 4) : '';
+    const segment = (rest.split(/[;&|]/)[0] ?? '').split(/\n/)[0] ?? '';
+    const tokens = segment.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
+    const positionals = tokens.filter((t) => {
+        const unquoted = t.replace(/^["']|["']$/g, '');
+        return unquoted.length > 0 && !unquoted.startsWith('-');
+    });
+    return positionals.length === 0;
+}
+/**
+ * Resolve the currently checked-out branch via `git branch --show-current`.
+ * Returns null on any failure (not a repo, git missing) — callers treat
+ * null as "unknown" and allow the normal policy flow to continue.
+ */
+export function currentGitBranch(cwd) {
+    try {
+        const out = execFileSync('git', ['-C', cwd, 'branch', '--show-current'], {
+            timeout: 3000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+        });
+        const branch = String(out).trim();
+        return branch.length > 0 ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Hard-deny for obviously destructive shell patterns. */
 export const shellDenyRule = {
     name: 'shell-deny',
@@ -271,6 +317,16 @@ export const shellDenyRule = {
         if (/\b(Set-Content|Out-File)\b[^\n]*\.env/i.test(cmd)) {
             return { action: 'deny', reason: 'write to .env via Set-Content/Out-File denied' };
         }
+        // Shell-redirection containment: deny `>` / `>>` into dotfiles.
+        // Home/abs dotfile target (e.g. `> ~/.klyro/mcp.json`, `> /home/u/.config/x`).
+        // The `(?<![0-9])` guard excludes the `2>` stderr-redirect prefix.
+        if (/(?<![0-9])>+\s*["']?(~|\/)[^"'\s]*\/\.[^"'\s]+/.test(cmd)) {
+            return { action: 'deny', reason: 'redirect into dotfile under home/abs path denied' };
+        }
+        // Bare project dotfile target (e.g. `> .mcp.json`, `>> .env.local`).
+        if (/(?<![0-9])>+\s*["']?\.[^"'\s\/][^"'\s]*/.test(cmd)) {
+            return { action: 'deny', reason: 'redirect into project dotfile denied' };
+        }
         // Upload-form exfiltration (mirrors shell_exec DANGEROUS_PATTERNS).
         if (/\bcurl\b.*(?:\s-F\b|\s--form\b)/i.test(cmd)) {
             return { action: 'deny', reason: 'exfiltration: curl -F/--form denied' };
@@ -284,6 +340,22 @@ export const shellDenyRule = {
         if (/\bStart-BitsTransfer\b/i.test(cmd)) {
             return { action: 'deny', reason: 'exfiltration: Start-BitsTransfer denied' };
         }
+        // Protected-branch push deny (mirrors shell_exec DANGEROUS_PATTERNS).
+        // Explicit `git push ... main|master|production` is denied outright;
+        // a bare `git push` (no ref args) is denied when the checkout is on a
+        // protected branch. Escape hatch: KLYRO_ALLOW_MAIN_PUSH=1.
+        if (process.env.KLYRO_ALLOW_MAIN_PUSH !== '1') {
+            if (PROTECTED_PUSH_RE.test(cmd)) {
+                return { action: 'deny', reason: 'protected-branch push denied (main/master/production) — set KLYRO_ALLOW_MAIN_PUSH=1 to override' };
+            }
+            if (isBareGitPush(cmd)) {
+                const branch = currentGitBranch(ctx.cwd);
+                if (branch !== null && PROTECTED_BRANCHES.includes(branch)) {
+                    return { action: 'deny', reason: `bare git push on protected branch '${branch}' denied — set KLYRO_ALLOW_MAIN_PUSH=1 to override` };
+                }
+                // currentGitBranch null (not a repo / git missing) → allow normal flow.
+            }
+        }
         return null;
     },
 };
@@ -383,4 +455,5 @@ export async function evaluatePolicy(engine, call, ctx) {
 //  policy/ depending only on tools/normalize, no other tool code.)
 import * as path from 'node:path';
 import * as fsSync from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { resolveWithinCwd } from './path-guard.js';

package/dist/policy/path-guard.d.ts

@@ -28,3 +28,27 @@ export declare function resolveWithinCwd(cwd: string, requested: string): PathGu
  * Use this for read_file / write_file to defeat symlink-based escapes.
  */
 export declare function resolveAndFollowSymlinks(cwd: string, requested: string): Promise<PathGuardResult>;
+/**
+ * Symlink-swap guard: refuse when the FINAL path itself is a symlink.
+ *
+ * File tools resolve symlinks up front, but a racing swap between that
+ * check and the final write/rename could redirect an open-with-O_TRUNC /
+ * O_CREAT (or rename) through a freshly-planted symlink. Calling this
+ * immediately before the final write/rename shrinks that window to ~0:
+ * `lstat` never follows the final component, so a swapped-in link is
+ * caught. (POSIX `rename(2)` onto a symlink replaces the LINK itself, so
+ * the vulnerable op is opening/truncating through the link — which this
+ * denies first.) Supported on POSIX and Windows (both implement lstat).
+ * Missing paths (ENOENT) are fine — a nonexistent path is not a symlink.
+ */
+export declare function assertNotSymlink(p: string): Promise<void>;
+/**
+ * Open a file for writing without following a trailing symlink (POSIX).
+ *
+ * Uses O_WRONLY | O_CREAT | O_NOFOLLOW so the open itself fails (ELOOP)
+ * when the final component is a symlink, instead of truncating through
+ * it. On Windows there is no O_NOFOLLOW, so this falls back to a plain
+ * `'w'` open — symlink-swap protection there comes from
+ * `assertNotSymlink` (lstat) immediately before the write/rename instead.
+ */
+export declare function openNoFollowForWrite(dir: string, file: string): number;

package/dist/policy/path-guard.js

@@ -11,6 +11,7 @@
  */
 import * as path from 'node:path';
 import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
 import { TOOL_ERROR_CODES } from '../tools/normalize.js';
 export class PathGuardError extends Error {
     code;
@@ -96,3 +97,48 @@ export async function resolveAndFollowSymlinks(cwd, requested) {
     }
     return { resolved: real };
 }
+/**
+ * Symlink-swap guard: refuse when the FINAL path itself is a symlink.
+ *
+ * File tools resolve symlinks up front, but a racing swap between that
+ * check and the final write/rename could redirect an open-with-O_TRUNC /
+ * O_CREAT (or rename) through a freshly-planted symlink. Calling this
+ * immediately before the final write/rename shrinks that window to ~0:
+ * `lstat` never follows the final component, so a swapped-in link is
+ * caught. (POSIX `rename(2)` onto a symlink replaces the LINK itself, so
+ * the vulnerable op is opening/truncating through the link — which this
+ * denies first.) Supported on POSIX and Windows (both implement lstat).
+ * Missing paths (ENOENT) are fine — a nonexistent path is not a symlink.
+ */
+export async function assertNotSymlink(p) {
+    let st;
+    try {
+        st = await fs.lstat(p);
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return;
+        throw e;
+    }
+    if (st.isSymbolicLink()) {
+        throw new PathGuardError(TOOL_ERROR_CODES.PATH_ESCAPE, `Refusing to write through symlink: ${p}`);
+    }
+}
+/**
+ * Open a file for writing without following a trailing symlink (POSIX).
+ *
+ * Uses O_WRONLY | O_CREAT | O_NOFOLLOW so the open itself fails (ELOOP)
+ * when the final component is a symlink, instead of truncating through
+ * it. On Windows there is no O_NOFOLLOW, so this falls back to a plain
+ * `'w'` open — symlink-swap protection there comes from
+ * `assertNotSymlink` (lstat) immediately before the write/rename instead.
+ */
+export function openNoFollowForWrite(dir, file) {
+    const target = path.resolve(dir, file);
+    if (process.platform === 'win32') {
+        // Windows fallback: no O_NOFOLLOW — plain open; see comment above.
+        return fsSync.openSync(target, 'w');
+    }
+    const flags = fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_NOFOLLOW;
+    return fsSync.openSync(target, flags, 0o666);
+}

package/dist/providers/model-info.d.ts

@@ -32,4 +32,10 @@ export declare function ratesFor(modelId: string): {
     input: number;
     output: number;
 };
+/**
+ * True for Anthropic-family model ids (Claude). Used by the runtime's
+ * cache-aware cost math: only Anthropic bills cacheRead/cacheWrite, so
+ * other families keep ignoring those counters.
+ */
+export declare function isAnthropicModel(modelId: string): boolean;
 export declare function estimateCost(modelId: string, inputTokens: number, outputTokens: number): number;

package/dist/providers/model-info.js

@@ -43,6 +43,14 @@ export function ratesFor(modelId) {
         return { input: fam.input, output: fam.output };
     return { input: 0, output: 0 };
 }
+/**
+ * True for Anthropic-family model ids (Claude). Used by the runtime's
+ * cache-aware cost math: only Anthropic bills cacheRead/cacheWrite, so
+ * other families keep ignoring those counters.
+ */
+export function isAnthropicModel(modelId) {
+    return /anthropic|claude/i.test(modelId);
+}
 export function estimateCost(modelId, inputTokens, outputTokens) {
     // Single source: delegate to ratesFor so registry, family fallbacks, and
     // local-$0 rules live in exactly one place (no split-brain with getModelInfo).

package/dist/tools/fs/apply-patch.js

@@ -20,7 +20,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { z } from 'zod';
 import { defineTool } from '../types.js';
-import { resolveAndFollowSymlinks } from '../../policy/path-guard.js';
+import { resolveAndFollowSymlinks, assertNotSymlink } from '../../policy/path-guard.js';
 import { safe } from '../normalize.js';
 import { wasRead } from './read-history.js';
 // Extension-anchored: matches test.ts, foo.test.ts, foo-test.ts, foo.spec.js,
@@ -242,6 +242,9 @@ export const applyPatchTool = defineTool({
                     await guardWrite(ctx.cwd, sec.path, resolved);
                     await assertSameTarget(ctx.cwd, sec.path, resolved);
                     await fs.mkdir(path.dirname(resolved), { recursive: true });
+                    // Symlink-swap guard: refuse if the final dest became a symlink
+                    // since the up-front resolve (lstat never follows the final link).
+                    await assertNotSymlink(resolved);
                     await fs.writeFile(resolved, content ? content + '\n' : '', 'utf-8');
                     patchedFiles.push(sec.path);
                     continue;
@@ -264,6 +267,8 @@ export const applyPatchTool = defineTool({
                 const next = applyHunks(sec.path, fileLines, hunks);
                 await assertSameTarget(ctx.cwd, sec.path, resolved);
                 await fs.mkdir(path.dirname(resolved), { recursive: true });
+                // Symlink-swap guard (mirrors the creation path above).
+                await assertNotSymlink(resolved);
                 await fs.writeFile(resolved, next.join('\n') + (hasTrailingNewline ? '\n' : ''), 'utf-8');
                 patchedFiles.push(sec.path);
             }

package/dist/tools/fs/edit-file.js

@@ -7,7 +7,7 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { z } from 'zod';
 import { defineTool } from '../types.js';
-import { resolveAndFollowSymlinks } from '../../policy/path-guard.js';
+import { resolveAndFollowSymlinks, assertNotSymlink } from '../../policy/path-guard.js';
 import { safe } from '../normalize.js';
 import { wasRead } from './read-history.js';
 // Extension-anchored: matches test.ts, foo.test.ts, foo-test.ts, foo.spec.js,
@@ -187,6 +187,9 @@ export const editFileTool = defineTool({
             finally {
                 await fh.close().catch(() => undefined);
             }
+            // Symlink-swap guard: refuse if the final dest became a symlink
+            // since the up-front resolve (lstat never follows the final link).
+            await assertNotSymlink(resolved);
             try {
                 await fs.rename(tmp, resolved);
             }

package/dist/tools/fs/multi-edit.js

@@ -5,7 +5,7 @@ import * as fs from 'node:fs/promises';
 import * as crypto from 'node:crypto';
 import { z } from 'zod';
 import { defineTool } from '../types.js';
-import { resolveAndFollowSymlinks } from '../../policy/path-guard.js';
+import { resolveAndFollowSymlinks, assertNotSymlink } from '../../policy/path-guard.js';
 import { safe } from '../normalize.js';
 import { wasRead } from './read-history.js';
 import { checkStaleness, recordEditStaleness } from './edit-file.js';
@@ -112,6 +112,9 @@ export const multiEditTool = defineTool({
             }
             const tmp = `${resolved}.klyro-multi-${Date.now()}.tmp`;
             await fs.writeFile(tmp, content, 'utf-8');
+            // Symlink-swap guard: refuse if the final dest became a symlink
+            // since the up-front resolve (lstat never follows the final link).
+            await assertNotSymlink(resolved);
             try {
                 await fs.rename(tmp, resolved);
             }

package/dist/tools/fs/write-file.js

@@ -5,11 +5,12 @@
  * directories if needed.
  */
 import * as fs from 'node:fs/promises';
+import * as fsSyncNode from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { z } from 'zod';
 import { defineTool } from '../types.js';
-import { resolveAndFollowSymlinks } from '../../policy/path-guard.js';
+import { resolveAndFollowSymlinks, assertNotSymlink, openNoFollowForWrite } from '../../policy/path-guard.js';
 import { safe } from '../normalize.js';
 // Extension-anchored: matches test.ts, foo.test.ts, foo-test.ts, foo.spec.js,
 // __tests__ segments — but NOT latest.ts / attest.ts / contest-data.
@@ -111,15 +112,24 @@ export const writeFileTool = defineTool({
             if ((await canon(reResolved)) !== (await canon(resolved))) {
                 throw Object.assign(new Error(`Path target changed between check and write: ${input.path} (POLICY_DENIED)`), { code: 'POLICY_DENIED' });
             }
-            // Truncate to 8k tokens ~32k chars for result
-            const fh = await fs.open(tmp, 'w');
+            // Truncate to 8k tokens ~32k chars for result.
+            // The tmp file is opened O_NOFOLLOW (POSIX; plain 'w' on Windows —
+            // see openNoFollowForWrite) so a planted link at the fresh tmp name
+            // can't redirect the content write; atomic tmp+rename semantics stay.
+            const fd = openNoFollowForWrite(parent, path.basename(tmp));
             try {
-                await fh.writeFile(data);
-                await fh.sync();
+                fsSyncNode.writeFileSync(fd, data);
+                fsSyncNode.fsyncSync(fd);
             }
             finally {
-                await fh.close().catch(() => undefined);
+                try {
+                    fsSyncNode.closeSync(fd);
+                }
+                catch { /* already closed */ }
             }
+            // Symlink-swap guard: lstat the final dest immediately before rename
+            // and refuse if it became a symlink since the up-front resolve.
+            await assertNotSymlink(resolved);
             try {
                 await fs.rename(tmp, resolved);
             }

package/dist/tools/plan/todo-write.js

@@ -14,7 +14,7 @@ export const todoWriteTool = defineTool({
     name: 'todo_write',
     description: 'Update the live plan checklist. Persisted and re-injected when stale.',
     inputSchema: InputSchema,
-    permission: 'read',
+    permission: 'edit',
     isConcurrencySafe: true,
     execute: async (input, ctx) => {
         return safe(async () => {

package/dist/tools/shell/shell-exec.d.ts

@@ -18,6 +18,34 @@ declare const InputSchema: z.ZodObject<{
 /** Reset the sticky cwd (e.g. after /cd changes the session directory). */
 export declare function resetPersistentCwd(): void;
 export declare function filteredEnv(extra?: Record<string, string>): NodeJS.ProcessEnv;
+/**
+ * Protected-branch push helpers (mirror policy engine shellDenyRule).
+ * `git push` targeting main/master/production is denied outright; a bare
+ * `git push` (no ref args) is denied when the checkout sits on a protected
+ * branch. Escape hatch: KLYRO_ALLOW_MAIN_PUSH=1.
+ */
+export declare const PROTECTED_BRANCHES: string[];
+export declare const PROTECTED_PUSH_RE: RegExp;
+/**
+ * True when KLYRO_ALLOW_MAIN_PUSH=1 opts out of the protected-push deny. */
+export declare function isMainPushEscape(): boolean;
+/**
+ * True when the command is a `git push` with NO ref/positional args
+ * (e.g. `git push`, `git push -f`) — i.e. it pushes whatever is checked
+ * out. `git push origin feature` is explicit, not bare.
+ */
+export declare function isBareGitPush(cmd: string): boolean;
+/**
+ * Resolve the currently checked-out branch via `git branch --show-current`.
+ * Returns null on any failure (not a repo, git missing) — callers treat
+ * null as "unknown" and allow the normal flow to continue.
+ */
+export declare function currentGitBranch(cwd: string): string | null;
+/**
+ * Bare-push check with cwd: deny `git push` with no ref args when the
+ * checkout is on a protected branch. Returns the block reason or null.
+ */
+export declare function findBareProtectedPushReason(command: string, cwd: string): string | null;
 /**
  * Shared dangerous-command check (also used by background shells).
  * Returns the block reason, or null when the command is not hard-blocked.

package/dist/tools/shell/shell-exec.js

@@ -8,7 +8,7 @@
  *   - Non-zero exit is returned as a successful tool call (with exitCode in
  *     the output). The agent reads exitCode to decide what to do next.
  */
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn, spawnSync, execFileSync } from 'node:child_process';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import * as fsp from 'node:fs/promises';
@@ -73,6 +73,15 @@ export function filteredEnv(extra) {
 }
 // Interactive command detection (3.3)
 const INTERACTIVE_PATTERNS = [/^\s*vim\b/, /^\s*nano\b/, /^\s*htop\b/, /^\s*less\b/, /^\s*more\b/, /^\s*ssh\b/, /^\s*tmux\b/];
+/**
+ * Protected-branch push helpers (mirror policy engine shellDenyRule).
+ * `git push` targeting main/master/production is denied outright; a bare
+ * `git push` (no ref args) is denied when the checkout sits on a protected
+ * branch. Escape hatch: KLYRO_ALLOW_MAIN_PUSH=1.
+ */
+export const PROTECTED_BRANCHES = ['main', 'master', 'production'];
+export const PROTECTED_PUSH_RE = /\bpush\b[^\n]*\b(main|master|production)\b/;
+const GIT_PUSH_RE = /\bgit\b[^\n]*\bpush\b/;
 // Hard-coded dangerous patterns. These are non-overridable, configurable via --yolo only.
 const DANGEROUS_PATTERNS = [
     { pattern: /rm\s+-rf?\s+\//, reason: 'recursive delete at filesystem root' },
@@ -112,12 +121,79 @@ const DANGEROUS_PATTERNS = [
     // .env writes via tee / PowerShell (mirrors policy engine .env guard).
     { pattern: /\|\s*tee\b[^\n]*\.env/i, reason: 'write to .env via tee denied' },
     { pattern: /\b(Set-Content|Out-File)\b[^\n]*\.env/i, reason: 'write to .env via Set-Content/Out-File denied' },
+    // Shell-redirection containment (mirrors policy engine shellDenyRule):
+    // deny `>` / `>>` into dotfiles under home/abs paths or bare project
+    // dotfiles. `(?<![0-9])` excludes the `2>` stderr-redirect prefix.
+    { pattern: /(?<![0-9])>+\s*["']?(~|\/)[^"'\s]*\/\.[^"'\s]+/, reason: 'redirect into dotfile under home/abs path denied' },
+    { pattern: /(?<![0-9])>+\s*["']?\.[^"'\s\/][^"'\s]*/, reason: 'redirect into project dotfile denied' },
     // Upload-form exfiltration (mirrors policy engine shellDenyRule).
     { pattern: /\bcurl\b.*(?:\s-F\b|\s--form\b)/i, reason: 'exfiltration: curl -F/--form denied' },
     { pattern: /\bwget\b.*(?:\s--method=POST\b|\s--body-data\b)/i, reason: 'exfiltration: wget --method=POST/--body-data denied' },
     { pattern: /\bInvoke-RestMethod\b/i, reason: 'exfiltration: Invoke-RestMethod denied' },
     { pattern: /\bStart-BitsTransfer\b/i, reason: 'exfiltration: Start-BitsTransfer denied' },
+    // Protected-branch push deny (mirrors policy engine shellDenyRule).
+    // Explicit `git push ... main|master|production`. Honored only when
+    // KLYRO_ALLOW_MAIN_PUSH=1 is NOT set (see findBlockedReason). Bare
+    // `git push` on a protected checkout is handled in execute() with cwd.
+    { pattern: PROTECTED_PUSH_RE, reason: 'protected-branch push denied (main/master/production) — set KLYRO_ALLOW_MAIN_PUSH=1 to override' },
 ];
+/**
+ * True when KLYRO_ALLOW_MAIN_PUSH=1 opts out of the protected-push deny. */
+export function isMainPushEscape() {
+    return process.env.KLYRO_ALLOW_MAIN_PUSH === '1';
+}
+/**
+ * True when the command is a `git push` with NO ref/positional args
+ * (e.g. `git push`, `git push -f`) — i.e. it pushes whatever is checked
+ * out. `git push origin feature` is explicit, not bare.
+ */
+export function isBareGitPush(cmd) {
+    if (!GIT_PUSH_RE.test(cmd))
+        return false;
+    const idx = cmd.search(/\bpush\b/);
+    const rest = idx >= 0 ? cmd.slice(idx + 4) : '';
+    const segment = (rest.split(/[;&|]/)[0] ?? '').split(/\n/)[0] ?? '';
+    const tokens = segment.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
+    const positionals = tokens.filter((t) => {
+        const unquoted = t.replace(/^["']|["']$/g, '');
+        return unquoted.length > 0 && !unquoted.startsWith('-');
+    });
+    return positionals.length === 0;
+}
+/**
+ * Resolve the currently checked-out branch via `git branch --show-current`.
+ * Returns null on any failure (not a repo, git missing) — callers treat
+ * null as "unknown" and allow the normal flow to continue.
+ */
+export function currentGitBranch(cwd) {
+    try {
+        const out = execFileSync('git', ['-C', cwd, 'branch', '--show-current'], {
+            timeout: 3000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+        });
+        const branch = String(out).trim();
+        return branch.length > 0 ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Bare-push check with cwd: deny `git push` with no ref args when the
+ * checkout is on a protected branch. Returns the block reason or null.
+ */
+export function findBareProtectedPushReason(command, cwd) {
+    if (isMainPushEscape())
+        return null;
+    if (!isBareGitPush(command))
+        return null;
+    const branch = currentGitBranch(cwd);
+    if (branch !== null && PROTECTED_BRANCHES.includes(branch)) {
+        return `bare git push on protected branch '${branch}' — set KLYRO_ALLOW_MAIN_PUSH=1 to override`;
+    }
+    return null;
+}
 /**
  * Repair-guard mirror: heredoc/redirect writes to test paths, or test-path
  * rewrites via sed/python/perl/ruby/node/git (e.g. `> x.test.ts`,
@@ -133,6 +209,9 @@ const REPAIR_GUARD_SHELL_RE = />+\s*['"]?[^'"\s]*test[^'"\s]*|\b(sed|python|perl
  */
 export function findBlockedReason(command) {
     for (const { pattern, reason } of DANGEROUS_PATTERNS) {
+        // Protected-push entry honors the KLYRO_ALLOW_MAIN_PUSH=1 escape hatch.
+        if (pattern === PROTECTED_PUSH_RE && isMainPushEscape())
+            continue;
         if (pattern.test(command))
             return reason;
     }
@@ -204,6 +283,13 @@ export const shellExecTool = defineTool({
             const timeoutMs = Math.min(input.timeoutMs ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
             const env = filteredEnv(input.env);
             const start = Date.now();
+            // Protected-branch bare push: `git push` with no ref args while the
+            // effective checkout sits on main/master/production. Explicit
+            // `push ... main` was already denied by findBlockedReason above.
+            const barePushReason = findBareProtectedPushReason(input.command, cwd);
+            if (barePushReason) {
+                throw Object.assign(new Error(`Command blocked: ${barePushReason}`), { code: TOOL_ERROR_CODES.COMMAND_DENIED });
+            }
             // Detached on POSIX so timeout kills the whole process GROUP
             // (child.kill alone orphans grandchildren holding the pipes).
             // G1-2 — sandbox is ON BY DEFAULT whenever a backend is available

package/dist/trace/writer.d.ts

@@ -6,6 +6,13 @@
  * the serialized line is passed through redact() before it hits disk so
  * secrets never land in the trace. readAll skips corrupt lines instead of
  * discarding the whole trace.
+ *
+ * Trace-dir rationale (PRD divergence): the PRD places traces at
+ * `~/.klyro/projects/<hash>/traces/<session>.jsonl` (global store), but this
+ * writer defaults to `<cwd>/.klyro/traces/<session>.jsonl` (project-local)
+ * so traces travel with the working tree — inspectable offline, backed up
+ * with the repo, and resolvable without a global-project-hash lookup. The
+ * `dir` ctor param preserves the PRD path for callers that want it.
  */
 import type { KlyroEvent } from '../events/catalog.js';
 export declare class TraceWriter {

package/dist/trace/writer.js

@@ -6,6 +6,13 @@
  * the serialized line is passed through redact() before it hits disk so
  * secrets never land in the trace. readAll skips corrupt lines instead of
  * discarding the whole trace.
+ *
+ * Trace-dir rationale (PRD divergence): the PRD places traces at
+ * `~/.klyro/projects/<hash>/traces/<session>.jsonl` (global store), but this
+ * writer defaults to `<cwd>/.klyro/traces/<session>.jsonl` (project-local)
+ * so traces travel with the working tree — inspectable offline, backed up
+ * with the repo, and resolvable without a global-project-hash lookup. The
+ * `dir` ctor param preserves the PRD path for callers that want it.
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';