feat(brain): add memory, hooks, maxTurns; deprecate --initial-prompt (#635)

Wirasm · web-flow · commit ad384fedd1c3 · 2026-03-17T15:56:34.000+02:00
* Investigate issue #520: rename *Manager types to domain-role names * feat(brain): add memory, hooks, maxTurns to kild-brain agent; deprecate --initial-prompt - Add `memory: user`, `maxTurns: 200`, and agent-scoped `hooks:` to kild-brain frontmatter (PreToolUse bash guard + Stop fleet snapshot) - Create `.claude/hooks/brain-bash-guard.sh` to enforce "no source code access" constraint at the hook level - Replace ~40 lines of manual memory management with auto-memory note - Fix router skill to use create-then-inject instead of --initial-prompt - Deprecate --initial-prompt in CLI help text with runtime warnings - Update CLAUDE.md with deprecation notes and inject-based brain setup * fix: address review findings on brain hooks and deprecation warnings - Guard: switch from fragile grep+sed JSON parsing to jq, fail closed on parse failure, add ERR trap, block subshell invocations (bash -c, sh -c), remove overly broad src/ pattern, document advisory nature - Deprecation: eliminate contradictory double-warning for fleet sessions by branching into fleet-specific vs general paths (not both) - Deprecation: use color::warning/color::hint consistently in open.rs (was bare eprintln, now matches create.rs) - Deprecation: remove redundant initial_prompt_for_warning clone in create.rs, clone at use site instead - Logging: add structured error!() events for inbox fallback failures in both create.rs and open.rs - Stop hook: log stderr to file instead of /dev/null, ensure dir exists - SKILL.md: add session-active check after sleep 5 before injecting, warn user if session not ready instead of silently losing the message
diff --git a/.claude/agents/kild-brain.md b/.claude/agents/kild-brain.md
@@ -4,9 +4,22 @@ description: Honryū — KILD fleet supervisor. Manages parallel AI coding agent
 model: opus
 tools: Bash, Read, Write, Glob, Grep, Task
 permissionMode: acceptEdits
+maxTurns: 200
+memory: user
 skills:
   - kild
   - kild-wave-planner
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: ".claude/hooks/brain-bash-guard.sh"
+  Stop:
+    - hooks:
+        - type: command
+          command: "mkdir -p ~/.kild/brain && kild list --json > ~/.kild/brain/state.json 2>> ~/.kild/brain/stop-hook.log || echo \"$(date): kild list failed on Stop hook\" >> ~/.kild/brain/stop-hook.log"
+          timeout: 10
 ---
 
 You are Honryū, the KILD fleet supervisor. You are the Tōryō's (human's) right hand — you do everything they would do from the CLI, but faster and in parallel. You coordinate a fleet of AI coding agents running in isolated git worktrees called kilds.
@@ -82,7 +95,7 @@ Communication uses two channels that work together. You don't need to think abou
 
 ### Sending instructions to workers
 
-**Always use `kild inject` — never use `--initial-prompt`.**
+**Always use `kild inject`.** The `--initial-prompt` flag is deprecated.
 
 ```bash
 # Create a worker (no task yet — just boot the agent)
@@ -104,7 +117,7 @@ kild inject <branch> "Your next task: <instruction>"
 
 For non-Claude agents (Codex, Kiro, etc.), inject writes to PTY stdin + dropbox.
 
-**Do NOT use `--initial-prompt` on `kild create` or `kild open`.** The `--initial-prompt` flag has unreliable delivery for fleet sessions. Always create/open first, then inject separately.
+**Do NOT use `--initial-prompt` on `kild create` or `kild open`.** This flag is deprecated and will be removed in a future release. Always create/open first, wait for the agent to initialize, then inject separately.
 
 **Never use `kild stop` to deliver messages.** Stopping kills the agent process.
 
@@ -279,53 +292,36 @@ These files contain project-specific rules like forbidden file zones, required r
 
 ## Memory
 
-### On startup — orient yourself
-```bash
-cat ~/.kild/brain/state.json 2>/dev/null          # Last known fleet state
-tail -50 ~/.kild/brain/sessions/$(date +%Y-%m-%d).md 2>/dev/null  # Today's log
-cat ~/.kild/brain/knowledge/MEMORY.md 2>/dev/null  # Durable knowledge
-cat .kild/wave-plan.json 2>/dev/null               # Pending wave plan
-```
+Your persistent memory is managed automatically by Claude Code at `~/.claude/agent-memory/kild-brain/MEMORY.md`. The first 200 lines are injected into your context on every startup. Use Read/Write/Edit tools to update it directly — no bash commands needed.
+
+**What to remember:** Project patterns, worker quirks, conflict history, Tōryō preferences, lessons learned.
 
-If a wave plan exists, mention it:
-> "There's a wave plan from {planned_at} with {N} kilds. Say 'start the wave' to execute, or 'plan a new wave' to replace it."
+**One-time migration:** If `~/.kild/brain/knowledge/MEMORY.md` exists and your auto-memory is empty, read the old file and copy relevant content to your auto-memory. Then note that migration is complete.
 
-### After significant events — log
+### Session Logging
+
+After significant events, log to the daily session file:
 ```bash
-# Daily session log (append)
 cat >> ~/.kild/brain/sessions/$(date +%Y-%m-%d).md << 'EOF'
 ## HH:MM — <event summary>
 Worker: <branch> | Decision: <what you decided> | Action: <what you did>
 EOF
-
-# Fleet snapshot after major changes
-kild list --json > ~/.kild/brain/state.json
 ```
 
-### Your brain — persistent memory
+### On Startup
 
-`~/.kild/brain/knowledge/MEMORY.md` is your long-term memory. It persists across restarts and sessions. This is where you store things you've learned so future-you remembers them:
-
-- Project patterns: "kild project X has slow CI, allow 10min for checks"
-- Worker quirks: "codex agents need explicit test commands, they don't auto-run tests"
-- Conflict history: "sessions/ and git/ modules conflict frequently, never wave together"
-- Tōryō preferences: "prefers squash merges", "wants PR reviews before merge"
-- Lessons learned: "branch names with slashes break fleet inbox paths"
-
-```bash
-# Write to your memory
-echo "- <learned fact>" >> ~/.kild/brain/knowledge/MEMORY.md
-
-# Read your memory (do this on startup)
-cat ~/.kild/brain/knowledge/MEMORY.md 2>/dev/null
-```
+1. Your memory is auto-loaded (no action needed)
+2. Check fleet state: `kild list --json`
+3. Check today's log: `tail -50 ~/.kild/brain/sessions/$(date +%Y-%m-%d).md 2>/dev/null`
+4. Check wave plan: `cat .kild/wave-plan.json 2>/dev/null`
+5. Fleet state snapshot is auto-loaded from `~/.kild/brain/state.json` (saved on shutdown)
 
-Update or remove memories that turn out to be wrong. Keep it concise — this is for facts, not session transcripts.
+If a wave plan exists, mention it to the Tōryō.
 
 ## Constraints
 
 - **Never read project source code** — only `.kild/`, `~/.kild/`, and `~/.claude/teams/`
-- **Never `kild stop` to deliver a message** — use `kild inject` or `kild open --initial-prompt`
+- **Never `kild stop` to deliver a message** — use `kild inject`
 - **Never use `--no-attach`** unless the Tōryō explicitly asks for headless operation
 - **Never destroy a kild with an open PR** unless the Tōryō explicitly asks
 - **Never force-push** under any circumstances
diff --git a/.claude/hooks/brain-bash-guard.sh b/.claude/hooks/brain-bash-guard.sh
@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+#
+# brain-bash-guard.sh — PreToolUse hook for the kild-brain agent.
+# Blocks bash commands that access project source code.
+# The brain operates the fleet via the kild CLI, not by reading source.
+#
+# Exit 0 = allow, Exit 2 = block with reason on stderr.
+#
+# ADVISORY: This guard catches common direct access patterns but cannot
+# prevent all indirect execution (e.g., bash -c, sh -c, subshells).
+# It is a best-effort safety net, not a sandbox.
+
+set -uo pipefail
+
+# Fail closed on unexpected errors.
+trap 'echo "brain-bash-guard: unexpected error, blocking as safety measure" >&2; exit 2' ERR
+
+# Extract the command from CLAUDE_CODE_TOOL_INPUT (JSON with "command" field).
+COMMAND="${CLAUDE_CODE_TOOL_INPUT:-}"
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Extract the "command" field value from JSON.
+CMD=$(printf '%s' "$COMMAND" | jq -r '.command // empty' 2>/dev/null)
+
+if [ -z "$CMD" ]; then
+  # Parse failure or missing field — block rather than allow.
+  echo "BLOCKED: could not parse tool input command field." >&2
+  exit 2
+fi
+
+# --- Blocklist: patterns that indicate source code access ---
+# NOTE: This is advisory — subshell invocations (bash -c, sh -c) can bypass
+# these checks. The brain agent instructions also prohibit source access.
+
+# Source code paths (anchored to word boundary to reduce false positives)
+for pattern in "crates/" "target/" "tests/"; do
+  if [[ "$CMD" == *"$pattern"* ]]; then
+    echo "BLOCKED: Brain must not access source code (matched: $pattern)." >&2
+    echo "Use kild CLI commands (kild diff, kild stats) instead of reading source directly." >&2
+    exit 2
+  fi
+done
+
+# Build/compile commands
+for pattern in "^cargo " "^rustc" "^rustup"; do
+  if echo "$CMD" | grep -qE "$pattern"; then
+    echo "BLOCKED: Brain must not run build tools (matched: $pattern)." >&2
+    echo "Workers handle builds. Use kild CLI to manage the fleet." >&2
+    exit 2
+  fi
+done
+
+# Subshell invocations that could bypass the guard
+for pattern in "^bash -c" "^sh -c" "^env bash" "^env sh"; do
+  if echo "$CMD" | grep -qE "$pattern"; then
+    echo "BLOCKED: Brain must not use subshell invocations (matched: $pattern)." >&2
+    echo "Run commands directly so the guard can inspect them." >&2
+    exit 2
+  fi
+done
+
+# Raw git commands that have kild CLI equivalents
+if echo "$CMD" | grep -qE "^git diff"; then
+  echo "BLOCKED: Use 'kild diff <branch>' instead of raw git diff." >&2
+  exit 2
+fi
+
+if echo "$CMD" | grep -qE "^git log"; then
+  echo "BLOCKED: Use 'kild stats <branch>' instead of raw git log." >&2
+  exit 2
+fi
+
+# If no blocklist pattern matched, allow the command.
+exit 0
diff --git a/.claude/skills/kild-brain/SKILL.md b/.claude/skills/kild-brain/SKILL.md
@@ -43,12 +43,26 @@ case "$STATUS" in
     echo "Honryū is already running."
     ;;
   stopped)
-    kild open honryu --resume --initial-prompt "You've been restarted by the Tōryō. Orient yourself: check kild list --json, ~/.kild/brain/state.json, today's session log, and .kild/wave-plan.json (if it exists, mention it). Then greet the Tōryō and summarize the fleet state."
-    echo "Honryū restarted."
+    kild open honryu --resume
+    echo "Waiting for Honryū to initialize..."
+    sleep 5
+    if kild list --json 2>/dev/null | jq -e '.sessions[] | select(.branch == "honryu" and .status == "active")' >/dev/null 2>&1; then
+      kild inject honryu "You've been restarted by the Tōryō. Orient yourself: check kild list --json, today's session log, and .kild/wave-plan.json (if it exists, mention it). Then greet the Tōryō and summarize the fleet state."
+      echo "Honryū restarted."
+    else
+      echo "Warning: honryu session not active after 5s. Run: kild inject honryu \"...\" once it starts." >&2
+    fi
     ;;
   *)
-    kild create honryu --daemon --main --agent claude --yolo --note "Honryū fleet supervisor" --initial-prompt "You are Honryū, the KILD fleet supervisor. You have just been initialized by the Tōryō. Orient yourself: run kild list --json, read ~/.kild/brain/state.json, today's session log, and .kild/wave-plan.json if they exist. If a wave plan exists, mention it. Then greet the Tōryō and report fleet state. You are running on the main branch — do not create worktrees for yourself."
-    echo "Honryū initialized."
+    kild create honryu --daemon --main --agent claude --yolo --note "Honryū fleet supervisor"
+    echo "Waiting for Honryū to initialize..."
+    sleep 5
+    if kild list --json 2>/dev/null | jq -e '.sessions[] | select(.branch == "honryu" and .status == "active")' >/dev/null 2>&1; then
+      kild inject honryu "You are Honryū, the KILD fleet supervisor. You have just been initialized by the Tōryō. Orient yourself: run kild list --json, check today's session log, and .kild/wave-plan.json if they exist. If a wave plan exists, mention it. Then greet the Tōryō and report fleet state."
+      echo "Honryū initialized."
+    else
+      echo "Warning: honryu session not active after 5s. Run: kild inject honryu \"...\" once it starts." >&2
+    fi
     ;;
 esac
 ```
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -91,15 +91,15 @@ cargo run -p kild -- create my-branch                  # Create kild with defaul
 cargo run -p kild -- create my-branch --note "Auth"    # Create with description
 cargo run -p kild -- create my-branch --yolo           # Create with autonomous mode
 cargo run -p kild -- create my-branch --main           # Run from project root (no worktree)
-cargo run -p kild -- create my-branch --initial-prompt "Start with auth"  # Inject prompt on startup
+cargo run -p kild -- create my-branch --initial-prompt "Start with auth"  # [DEPRECATED] Use: create && sleep 5 && kild inject
 cargo run -p kild -- list                              # List all kilds
 cargo run -p kild -- list --json                       # JSON output
 cargo run -p kild -- open my-branch                    # Reopen agent in existing kild
 cargo run -p kild -- open --all                        # Open all stopped kilds
 cargo run -p kild -- open my-branch --resume           # Resume previous conversation
 cargo run -p kild -- open my-branch --no-attach        # Open daemon session without attach window
 cargo run -p kild -- open my-branch --no-attach --resume  # Headless resume (brain reopening workers)
-cargo run -p kild -- open my-branch --initial-prompt "Next task: ..."  # Inject prompt on reopen
+cargo run -p kild -- open my-branch --initial-prompt "Next task: ..."  # [DEPRECATED] Use: open && sleep 5 && kild inject
 cargo run -p kild -- inject my-branch "do the thing"  # Send to worker (inbox for claude, PTY for others)
 cargo run -p kild -- inject my-branch "msg" --inbox   # Force Claude Code inbox protocol
 cargo run -p kild -- inject my-branch "msg" --queue   # Queue task for later delivery (FIFO)
@@ -459,7 +459,10 @@ Inspect dropbox state with `kild inbox <branch>` (or `--all` for all fleet sessi
 
 ```
 kild create honryu --daemon --main   # brain: runs from project root, no worktree
+sleep 5                               # wait for agent init
+kild inject honryu "Orient yourself"  # deliver initial task via inject
 kild create <worker> --daemon        # worker: auto-joins fleet with team flags
+sleep 5
 kild inject <worker> "do the thing"  # brain → worker message
 ```
 
diff --git a/crates/kild/src/app/session.rs b/crates/kild/src/app/session.rs
@@ -98,7 +98,7 @@ pub fn create_command() -> Command {
         .arg(
             Arg::new("initial-prompt")
                 .long("initial-prompt")
-                .help("Write this text to the agent's PTY stdin immediately after startup (daemon sessions only)")
+                .help("[DEPRECATED] Inject a prompt after agent starts. Use 'kild inject' instead — it's more reliable for fleet sessions")
                 .value_name("TEXT")
                 .conflicts_with("no-agent")
                 .conflicts_with("no-daemon"),
@@ -185,7 +185,7 @@ pub fn open_command() -> Command {
         .arg(
             Arg::new("initial-prompt")
                 .long("initial-prompt")
-                .help("Write this text to the agent's PTY stdin immediately after startup (daemon sessions only)")
+                .help("[DEPRECATED] Inject a prompt after agent starts. Use 'kild inject' instead — it's more reliable for fleet sessions")
                 .value_name("TEXT")
                 .conflicts_with("no-agent")
                 .conflicts_with("no-daemon")
diff --git a/crates/kild/src/commands/create.rs b/crates/kild/src/commands/create.rs
@@ -87,7 +87,6 @@ pub(crate) fn handle_create_command(
 
     let use_main = matches.get_flag("main");
     let initial_prompt = matches.get_one::<String>("initial-prompt").cloned();
-    let initial_prompt_for_warning = initial_prompt.clone();
     let issue = matches.get_one::<u32>("issue").copied();
 
     let rows = matches.get_one::<u16>("rows").copied();
@@ -99,7 +98,7 @@ pub(crate) fn handle_create_command(
         .with_no_fetch(no_fetch)
         .with_runtime_mode(runtime_mode)
         .with_main_worktree(use_main)
-        .with_initial_prompt(initial_prompt)
+        .with_initial_prompt(initial_prompt.clone())
         .with_pty_size(rows, cols);
 
     match session_ops::create_session(request, &config) {
@@ -137,41 +136,64 @@ pub(crate) fn handle_create_command(
                 color::status(&status_str)
             );
 
-            // Warn fleet claude sessions about --initial-prompt deprecation.
-            // Deliver the prompt via the reliable inbox path instead.
-            if let Some(ref prompt) = initial_prompt_for_warning
-                && fleet::fleet_mode_active(&session.branch)
-                && fleet::is_claude_fleet_agent(&session.agent)
-            {
-                eprintln!();
-                eprintln!(
-                    "{}",
-                    color::warning("Warning: --initial-prompt is unreliable for fleet sessions.")
-                );
-                eprintln!(
-                    "  {}",
-                    color::hint(&format!(
-                        "Use instead: kild inject {} \"<your message>\"",
-                        session.branch
-                    ))
-                );
+            // Deprecation warning for --initial-prompt.
+            let is_fleet_claude = fleet::fleet_mode_active(&session.branch)
+                && fleet::is_claude_fleet_agent(&session.agent);
 
-                // Best-effort: deliver via inbox (the path that actually works).
-                let safe_name = fleet::fleet_safe_name(&session.branch);
-                match fleet::write_to_inbox(fleet::BRAIN_BRANCH, &safe_name, prompt) {
-                    Ok(()) => {
-                        eprintln!("  {} Delivered via inbox as fallback.", color::muted("→"));
-                    }
-                    Err(e) => {
-                        eprintln!("  {} Inbox fallback also failed: {}", color::error("✗"), e);
-                        eprintln!(
-                            "  {}",
-                            color::hint(&format!(
-                                "Manually run: kild inject {} \"...\"",
-                                session.branch
-                            ))
-                        );
+            if let Some(ref prompt) = initial_prompt {
+                eprintln!();
+                if is_fleet_claude {
+                    // Fleet-specific warning with inbox fallback.
+                    eprintln!(
+                        "{}",
+                        color::warning(
+                            "Warning: --initial-prompt is deprecated. Fleet sessions: prompt delivered via inbox as fallback."
+                        )
+                    );
+                    eprintln!(
+                        "  {}",
+                        color::hint(&format!(
+                            "Use instead: kild inject {} \"<your message>\"",
+                            session.branch
+                        ))
+                    );
+
+                    let safe_name = fleet::fleet_safe_name(&session.branch);
+                    match fleet::write_to_inbox(fleet::BRAIN_BRANCH, &safe_name, prompt) {
+                        Ok(()) => {
+                            eprintln!("  {} Delivered via inbox as fallback.", color::muted("→"));
+                        }
+                        Err(e) => {
+                            error!(
+                                event = "cli.create.inbox_fallback_failed",
+                                branch = %session.branch,
+                                error = %e
+                            );
+                            eprintln!("  {} Inbox fallback also failed: {}", color::error("✗"), e);
+                            eprintln!(
+                                "  {}",
+                                color::hint(&format!(
+                                    "Manually run: kild inject {} \"...\"",
+                                    session.branch
+                                ))
+                            );
+                        }
                     }
+                } else {
+                    // General deprecation warning for non-fleet sessions.
+                    eprintln!(
+                        "{}",
+                        color::warning(
+                            "Warning: --initial-prompt is deprecated and will be removed in a future release."
+                        )
+                    );
+                    eprintln!(
+                        "  {}",
+                        color::hint(&format!(
+                            "Use instead: kild create {} && sleep 5 && kild inject {} \"...\"",
+                            session.branch, session.branch
+                        ))
+                    );
                 }
             }
 
diff --git a/crates/kild/src/commands/open.rs b/crates/kild/src/commands/open.rs
