Add agent commands for AI-assisted task planning and execution

AGENTS.md

@@ -28,23 +28,114 @@ Example:
 git commit -m "Add logout button" --prompt "Add a logout button to the header. When clicked it should clear the session and redirect to /login"
 ```
 
-View prompts with:
+When `--prompt` is used, zagi automatically stores metadata in git notes:
+- `refs/notes/agent` - detected AI agent (claude, opencode, cursor, windsurf, vscode, terminal)
+- `refs/notes/prompt` - the user prompt text
+- `refs/notes/session` - full session transcript (for Claude Code, OpenCode)
+
+View metadata with:
 ```bash
-git log --prompts
+git log --prompts   # show prompts (truncated to 200 chars)
+git log --agent     # show which AI agent made each commit
+git log --session   # show session transcript (paginated, first 20k bytes)
+git log --session --session-offset=20000  # continue from byte 20000
 ```
 
-### Environment Setup
+### Agent Mode
 
-Set `ZAGI_AGENT` to enable prompt enforcement:
+Agent mode is automatically enabled when running inside AI tools:
+- Claude Code (sets `CLAUDECODE=1`)
+- OpenCode (sets `OPENCODE=1`)
+- VS Code, Cursor, Windsurf (detected from terminal environment)
 
+You can also enable it manually:
 ```bash
-export ZAGI_AGENT=claude-code
+export ZAGI_AGENT=my-agent
 ```
 
-When this is set:
+When agent mode is active:
 1. `git commit` will fail without `--prompt`, ensuring all AI-generated commits have their prompts recorded
 2. Destructive commands are blocked to prevent data loss
 
+## Agent Subcommands
+
+zagi provides two agent subcommands for autonomous task execution using the RALPH pattern (Recursive Agent Loop Pattern for Humans).
+
+### zagi agent plan
+
+Starts an interactive planning session where an AI agent collaborates with you to design and create tasks.
+
+```bash
+# Start an interactive session (agent will ask what you want to build)
+zagi agent plan
+
+# Start with initial context
+zagi agent plan "Add user authentication with JWT"
+
+# Preview the prompt without executing
+zagi agent plan --dry-run
+```
+
+The planning agent follows an interactive protocol:
+1. **Explore codebase**: Reads AGENTS.md and relevant code to understand architecture
+2. **Ask clarifying questions**: Asks about scope, constraints, and preferences before drafting any plan
+3. **Propose plan**: Presents a numbered implementation plan for your review
+4. **Create tasks**: Only creates tasks after you explicitly approve the plan
+
+This collaborative approach ensures the agent gathers all necessary context before committing to a task breakdown. The agent will ask 2-4 focused questions at a time about:
+- **Scope**: What's included/excluded, edge cases, MVP vs nice-to-haves
+- **Constraints**: Performance requirements, dependencies, compatibility
+- **Preferences**: Approach/patterns, integration with existing code, testing expectations
+- **Acceptance criteria**: How we know it's done, what success looks like
+
+### zagi agent run
+
+Executes the RALPH loop to automatically complete pending tasks.
+
+```bash
+# Run until all tasks complete (or fail 3x)
+zagi agent run
+
+# Run only one task then exit
+zagi agent run --once
+
+# Preview what would run without executing
+zagi agent run --dry-run
+
+# Set delay between tasks (default: 2 seconds)
+zagi agent run --delay 5
+
+# Safety limit - stop after N tasks
+zagi agent run --max-tasks 10
+```
+
+The run loop will:
+1. Pick the next pending task
+2. Execute it with the configured agent
+3. Mark it done on success (agent calls `zagi tasks done <task-id>`)
+4. Skip tasks that fail 3 consecutive times
+5. Continue until all tasks complete
+
+### Executor Configuration
+
+Control which AI agent executes tasks using environment variables:
+
+```bash
+# Use Claude Code (default)
+ZAGI_AGENT=claude zagi agent run
+
+# Use opencode
+ZAGI_AGENT=opencode zagi agent run
+
+# Use custom command with auto mode flags
+ZAGI_AGENT=claude ZAGI_AGENT_CMD="myclaude --flag" zagi agent run
+
+# Use completely custom tool (no auto flags)
+ZAGI_AGENT_CMD="aider --yes" zagi agent run
+```
+
+See [docs/setup.md](docs/setup.md) for full configuration details.
+
 ### Blocked Commands (in agent mode)
 
 These commands cause unrecoverable data loss and are blocked when `ZAGI_AGENT` is set:

CONTEXT.md

@@ -0,0 +1,89 @@
+# Context
+
+Ephemeral working context for this PR. Delete before merging to main.
+
+## Mission
+
+Build git-native task management and autonomous agent execution for zagi.
+
+## What is zagi?
+
+A Zig + libgit2 wrapper that makes git output concise and agent-friendly:
+- Smaller output (agents pay per token)
+- Guardrails block destructive commands when `ZAGI_AGENT` is set
+- Prompt provenance via `git commit --prompt "why this change"`
+- Task management via `zagi tasks` (stored in `refs/tasks/<branch>`)
+
+## Current Focus
+
+Implementing RALPH-driven development for autonomous agent execution.
+
+**RALPH**: https://lukeparker.dev/stop-chatting-with-ai-start-loops-ralph-driven-development
+
+The loop:
+1. `zagi agent plan` - Interactive planning session with user
+2. `zagi agent run` - Autonomous execution of tasks
+3. Tasks stored as git objects (`refs/tasks/<branch>`)
+4. Agent picks pending task, completes it, marks done
+5. Loop continues until all tasks complete
+
+## Work Streams
+
+### 1. Agent Execution (tasks 001-012) - DONE
+- Subcommand refactor (plan/run)
+- Executor config (ZAGI_AGENT, ZAGI_AGENT_CMD)
+- Validation and bug fixes
+
+### 2. Cleanup & Polish (tasks 013-023)
+- Memory leaks in tasks.zig
+- Hardcoded paths
+- Documentation updates
+- Style conformance
+
+### 3. Testing (tasks 024-030)
+- Agent plan/run tests
+- Error condition coverage
+- Full test suite pass
+
+### 4. git edit Feature (tasks 037-062)
+- jj-style mid-stack editing
+- Lets agents fix commits from earlier in history
+- Auto-rebases descendants after edit
+
+### 5. Interactive Planning (tasks 032-036)
+- Make `zagi agent plan` interactive (stdin/stdout passthrough)
+- Agent explores codebase, asks questions, builds plan with user
+- Convert approved plan to tasks
+
+### 6. Observability (tasks 064-067)
+- Streaming JSON output for debugging
+- CONTEXT.md generation during planning
+
+## Key Files
+
+- `src/cmds/tasks.zig` - Task CRUD operations
+- `src/cmds/agent.zig` - Agent plan/run subcommands
+- `start.sh` - Independent RALPH loop runner
+- `friction.md` - Issues encountered during development
+
+## Constraints
+
+- No external dependencies (everything in git)
+- Concise output (agents pay per token)
+- No emojis in code or output
+- Agents cannot edit/delete tasks (guardrail)
+- Always use `--prompt` when committing
+- Never `git push` (only commit)
+
+## Build & Test
+
+```bash
+zig build              # Build
+zig build test         # Zig unit tests
+cd test && bun run test  # Integration tests
+```
+
+## Environment
+
+- `ZAGI_AGENT=claude|opencode` - Executor, enables guardrails
+- `ZAGI_AGENT_CMD` - Custom command override

README.md

@@ -69,29 +69,45 @@ git fork --delete-all
 
 ### Agent mode
 
-Set `ZAGI_AGENT` to enable agent-specific features.
+Agent mode is automatically enabled when running inside AI tools (Claude Code, OpenCode, Cursor, Windsurf, VS Code). You can also enable it manually:
 
 ```bash
-export ZAGI_AGENT=claude-code
+export ZAGI_AGENT=my-agent
 ```
 
-The value can be any string describing your agent (e.g. `claude-code`, `cursor`, `opencode`) - this will be used in future features for agent-specific behavior.
-
 This enables:
 - **Prompt tracking**: `git commit` requires `--prompt` to record the user request that created the commit
+- **AI attribution**: Automatically detects and stores which AI agent made the commit
 - **Guardrails**: Blocks destructive commands (`reset --hard`, `checkout .`, `clean -f`, `push --force`) to prevent data loss
 
 ```bash
-git commit -m "Add feature" --prompt "Add a logout button to the header.."
-git log --prompts  # view prompts
+git commit -m "Add feature" --prompt "Add a logout button to the header"
+git log --prompts   # view prompts
+git log --agent     # view which AI agent made commits
+git log --session   # view full session transcript (with pagination)
 ```
 
-To prevent child processes from overriding `ZAGI_AGENT`, make it readonly:
+Metadata is stored in git notes (`refs/notes/agent`, `refs/notes/prompt`, `refs/notes/session`) which are local by default and don't affect commit history.
+
+### Environment variables
+
+| Variable | Description | Default | Valid values |
+|----------|-------------|---------|--------------|
+| `ZAGI_AGENT` | Manually enable agent mode. Auto-detected from `CLAUDECODE`, `OPENCODE`, or IDE environment. | (auto) | Any string enables agent mode. For executors: `claude`, `opencode` |
+| `ZAGI_AGENT_CMD` | Custom executor command override. When set, the prompt is appended as the final argument. | (unset) | Any shell command (e.g., `aider --yes`) |
+| `ZAGI_STRIP_COAUTHORS` | Strips `Co-Authored-By:` lines from commit messages. | (unset) | `1` to enable |
+
+**Agent detection**: Agent mode is automatically enabled when `CLAUDECODE=1` or `OPENCODE=1` is set (by Claude Code or OpenCode), or when running in VS Code/Cursor/Windsurf terminals.
 
 ```bash
-# bash/zsh
-export ZAGI_AGENT=claude-code
-readonly ZAGI_AGENT
+# Use Claude Code (default)
+ZAGI_AGENT=claude zagi agent run
+
+# Use opencode
+ZAGI_AGENT=opencode zagi agent run
+
+# Use a custom command
+ZAGI_AGENT_CMD="aider --yes" zagi agent run
 ```
 
 ### Strip co-authors

build.zig

@@ -93,13 +93,22 @@ pub fn build(b: *std.Build) void {
     });
     diff_tests.root_module.linkLibrary(libgit2_dep.artifact("git2"));
 
+    const agent_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/cmds/agent.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+
     const run_exe_unit_tests = b.addRunArtifact(exe_unit_tests);
     const run_log_tests = b.addRunArtifact(log_tests);
     const run_git_tests = b.addRunArtifact(git_tests);
     const run_alias_tests = b.addRunArtifact(alias_tests);
     const run_add_tests = b.addRunArtifact(add_tests);
     const run_commit_tests = b.addRunArtifact(commit_tests);
     const run_diff_tests = b.addRunArtifact(diff_tests);
+    const run_agent_tests = b.addRunArtifact(agent_tests);
 
     const test_step = b.step("test", "Run unit tests");
     test_step.dependOn(&run_exe_unit_tests.step);
@@ -109,4 +118,5 @@ pub fn build(b: *std.Build) void {
     test_step.dependOn(&run_add_tests.step);
     test_step.dependOn(&run_commit_tests.step);
     test_step.dependOn(&run_diff_tests.step);
+    test_step.dependOn(&run_agent_tests.step);
 }

docs/features.md

@@ -39,6 +39,11 @@ Options:
 - `--grep=<pattern>` - filter by commit message
 - `--since=<date>` - commits after date (e.g. "2025-01-01", "1 week ago")
 - `--until=<date>` - commits before date
+- `--prompts` - show AI prompts attached to commits
+- `--agent` - show which AI agent made the commit
+- `--session` - show session transcript (first 20k bytes)
+- `--session-offset=N` - start session display at byte N
+- `--session-limit=N` - limit session display to N bytes
 - `-- <path>...` - filter to commits affecting paths
 
 ### git diff
@@ -110,34 +115,48 @@ Forks are git worktrees. The `.forks/` directory is auto-added to `.gitignore`.
 - `--pick` performs a proper git merge, preserving both base and fork history
 - `--promote` moves HEAD to the fork's commit, discarding any base-only commits (stash uncommitted changes first)
 
-### --prompt
+### --prompt (AI Attribution)
 
-Store the user prompt that created a commit:
+Store the user prompt and AI metadata with a commit:
 
 ```bash
 git commit -m "Add feature" --prompt "Add a logout button to the header"
-git log --prompts  # view prompts in log output
 ```
 
-### ZAGI_AGENT
+When `--prompt` is used, zagi stores metadata in git notes:
+- `refs/notes/agent` - detected AI agent (claude, opencode, cursor, etc.)
+- `refs/notes/prompt` - the user prompt text
+- `refs/notes/session` - full session transcript (Claude Code, OpenCode)
 
-Set `ZAGI_AGENT` to enable agent-specific features. The value can be any string describing your agent (e.g. `claude-code`, `cursor`, `aider`) - this will be used in future features for agent-specific behavior.
+View with log flags:
+```bash
+git log --prompts   # show prompts (truncated to 200 chars)
+git log --agent     # show agent name
+git log --session   # show session transcript (paginated)
+git log --session --session-limit=1000  # first 1000 bytes
+git log --session --session-offset=1000 # start at byte 1000
+```
+
+Git notes are local by default and don't modify commit history.
 
+### Agent Mode
+
+Agent mode is automatically enabled when running inside AI tools:
+- Claude Code (`CLAUDECODE=1`)
+- OpenCode (`OPENCODE=1`)
+- VS Code, Cursor, Windsurf (detected from `VSCODE_GIT_ASKPASS_NODE`)
+
+You can also enable it manually:
 ```bash
-export ZAGI_AGENT=claude-code
-git commit -m "x"  # error: --prompt required
+export ZAGI_AGENT=my-agent
 ```
 
-When `ZAGI_AGENT` is set:
+When agent mode is active:
 - `git commit` requires `--prompt` to record the user request
 - Destructive commands are blocked (guardrails)
 
-To prevent child processes from overriding `ZAGI_AGENT`, make it readonly:
-
 ```bash
-# bash/zsh
-export ZAGI_AGENT=claude-code
-readonly ZAGI_AGENT
+git commit -m "x"  # error: --prompt required in agent mode
 ```
 
 ### ZAGI_STRIP_COAUTHORS