Skip to content

Self-improving AI Employees for everyone

docs(cli_agent): reflect --continue cutover + mtime-based JSONL discovery

trohitg8c6ed2ebf2f5
diff --git a/CLAUDE.md b/CLAUDE.md
index 0fe7d829..1d3e81e0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -47,7 +47,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[RLM Service](./docs-internal/rlm_service.md)** | Recursive Language Model agent with REPL-based execution (llm_query, rlm_query, FINAL) |
| **[Claude Code Agent](./docs-internal/claude_code_agent_architecture.md)** | Claude Code integration internals (LangGraph reference; companion to `cli_agent_framework.md`) |
| **[CLI Agent Framework](./docs-internal/cli_agent_framework.md)** | Multi-provider CLI runtime (Claude Code / Codex / Gemini): `AICliService.run_batch`, per-task worktree isolation, FastMCP bridge, **memory bridge** (native `--resume` via stable `cwd=repo_root` + UUID5/`last_session_id` round-trip + auto-clear on stale UUID + `node_parameters_updated` broadcast). |
-| **[Claude Code Interactive Mode](./docs-internal/claude_code_interactive_mode.md)** | The interactive-TUI cutover: MachinaOs no longer uses `claude -p` headless. Cross-platform PTY (`ptyprocess` POSIX / `pywinpty>=3.0.3` Windows) keeps `claude` alive; events come from the on-disk session JSONL. `ClaudeSessionPool` keyed by `simpleMemory.node_id` reuses warm processes across batches (non-disruptive — preserves memory continuity). Four typed CloudEvents (`claude.session.{spawned,cleared,terminated,usage}`) fire from the pool. `/compact` events forward to `CompactionService`. `/usage` data sourced from `result` events (TUI scraping not parseable per Anthropic). |
+| **[Claude Code Interactive Mode](./docs-internal/claude_code_interactive_mode.md)** | The interactive-TUI cutover: MachinaOs no longer uses `claude -p` headless. Cross-platform PTY (`ptyprocess` POSIX / `pywinpty>=3.0.3` Windows) keeps `claude` alive; events come from the on-disk session JSONL discovered via mtime. `ClaudeSessionPool` keyed by `simpleMemory.node_id` reuses warm processes across batches (non-disruptive — preserves memory continuity; explicit `pool.clear()` for reset). Memory bridge drives continuity via `--continue` (claude auto-finds latest under cwd) rather than ferrying a UUID through `simpleMemory.last_session_id`. Four typed CloudEvents (`claude.session.{spawned,cleared,terminated,usage}`) fire from the pool. `/compact` events forward to `CompactionService`. `/usage` data sourced from `result` events (TUI scraping not parseable per Anthropic). |
| **[CLI Agent Canonical Patterns RFC](./docs-internal/cli_agent_canonical_patterns_rfc.md)** | Audit of MachinaOs's `services/cli_agent` against the official Claude Code spec — six invariants (skills-as-files, MCP-only transport, `list_changed`, deferral, visible-tool filtering, native-session-continuity-via-stable-cwd) with current implementation status. |
| **[Claude Code CLI Reference (snapshot)](./docs-internal/claude_code_cli_reference.md)** | Verbatim snapshot of [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference) — every CLI subcommand + flag + system-prompt-flag matrix + the subset we emit from `services/cli_agent/providers/anthropic_claude.py`. Fetched 2026-05-11. |
| **[Claude Code Env Vars (snapshot)](./docs-internal/claude_code_env_vars_reference.md)** | Categorised [code.claude.com/docs/en/env-vars](https://code.claude.com/docs/en/env-vars) snapshot — auth, Bedrock/Vertex, model, bash, MCP, telemetry, session/debug, paths. Documents `CLAUDE_CONFIG_DIR`, `MAX_MCP_OUTPUT_TOKENS`, `ENABLE_TOOL_SEARCH` which we touch directly. |
diff --git a/docs-internal/claude_code_interactive_mode.md b/docs-internal/claude_code_interactive_mode.md
index f706e249..4b9d4572 100644
--- a/docs-internal/claude_code_interactive_mode.md
+++ b/docs-internal/claude_code_interactive_mode.md
@@ -27,8 +27,9 @@ because the on-disk JSONL is the same format `-p` wrote to stdout
(Claude Code CHANGELOG 2.1.101 / 2.1.126 — shared writer). The argv
flags we care about — `--mcp-config`, `--strict-mcp-config`,
`--allowedTools`, `--permission-mode`, `--append-system-prompt`,
-`--resume`, `--model`, `--effort`, `--add-dir`, `--disallowedTools`,
-`--agent` — all work in interactive mode.
+`--resume`, **`--continue`** (new primary continuity flag — see
+"Memory bridge" below), `--model`, `--effort`, `--add-dir`,
+`--disallowedTools`, `--agent` — all work in interactive mode.
## What we dropped
@@ -58,7 +59,7 @@ Two orthogonal layers:
| **Send turn** | `pty.write((text + '\r').encode())` (NOT close stdin — see [#15553](https://github.com/anthropics/claude-code/issues/15553)) | identical |
| **Send slash command** | `pty.write(b"/clear\r")` | identical |
| **Completion detect** | JSONL `result` entry | identical |
-| **Resume across spawns** | `claude --resume <UUID>` | identical |
+| **Session continuity** | `claude --continue` (memory-bound) — claude auto-finds latest under cwd | identical |
`pywinpty` v3.x is now production-grade (used by Jupyter Lab terminals
and Spyder's IPython console) so the historical reason to route Windows
@@ -95,9 +96,11 @@ memory node reuse the same warm `claude` PTY:
JSONL so the conversation continues. This is the load-bearing
invariant for `simpleMemory` continuity.
- **Acquire (cold)** — spawn fresh via `PtyTransport`, locate the
- newly-created JSONL by mtime, start a `JsonlWatcher` on it. Stash
- the MCP bearer token on the `PooledClaudeSession` so re-acquires
- use the same token the spawned claude already has in its argv.
+ JSONL by mtime (newest `.jsonl` with `mtime >= spawn_time - 1s`
+ works uniformly for fresh `claude` and `claude --continue`), start
+ a `JsonlWatcher` on it. Stash the MCP bearer token on the
+ `PooledClaudeSession` so re-acquires use the same token the
+ spawned claude already has in its argv.
- **Explicit `clear(session)`** — sends `/clear` to the PTY, awaits
the new JSONL filename via the persistent `JsonlDirWatcher`, swaps
the file watcher. Per
@@ -196,25 +199,50 @@ interactive dialogs, kill the session, or open a browser):
`/config`, `/install-github-app`, `/install-slack-app`, `/teleport`,
`/heapdump`.
-## Memory bridge — unchanged
+## Memory bridge — `--continue`, not UUID round-trip
-The `simpleMemory.last_session_id` ↔ `--resume <UUID>` contract works
-identically in interactive mode because the on-disk JSONL is the
-same format. The invariants:
+Late-stage simplification: the agent no longer ferries a UUID through
+`simpleMemory.last_session_id` to drive continuity. Instead it passes
+`--continue` and lets claude track its own latest session per cwd.
+
+`ClaudeTaskSpec` carries a `continue_session: bool` field. The
+argv-builder emits one of:
+
+- `--resume <UUID>` if `task.resume_session_id` is set (explicit
+ wins — used for `--fork-session` later, or any caller that already
+ knows the exact UUID).
+- `--continue` if `task.continue_session=True` (the memory-bound
+ default; per
+ [`code.claude.com/docs/en/cli-reference`](https://code.claude.com/docs/en/cli-reference)
+ this loads the most recent conversation under the cwd).
+- Neither — fresh session; claude assigns a new UUID.
+
+`claude_code_agent.execute_op` sets `continue_session=True` when a
+memory node is wired; it no longer reads `last_session_id` from the
+memory data. The invariants:
- `memory_bound=True` makes the spawn cwd = `repo_root` so claude's
`project_key` stays constant across batches.
-- First run: claude assigns its own UUID; the pool / `AICliSession`
- discovers it via the new JSONL filename, saves it to
- `simpleMemory.last_session_id`.
-- Subsequent runs (non-pooled): argv `--resume <last_session_id>`.
-- Subsequent runs (pooled, warm): no respawn — the warm PTY continues
- in its current UUID.
-- Subsequent runs (pooled, after `pool.clear`): a new UUID is captured
- on the next `result` event and persisted.
-- Auto-clear-stale: if claude reports `No conversation found with
- session ID: <UUID>`, `_persist_memory` wipes the broken
- `last_session_id` so the next run falls into the first-run branch.
+- First run with memory wired: argv `--continue` (no prior conversation
+ under cwd → claude starts fresh). The post-spawn `_wait_for_session_jsonl`
+ helper finds the new JSONL via mtime (newest `.jsonl` with
+ `mtime >= spawn_time - 1s`).
+- Subsequent runs with memory wired: argv `--continue` — claude
+ loads the latest conversation under cwd and continues.
+- Pooled (warm): no respawn — the warm PTY continues in its current
+ UUID; the next prompt appends to its existing JSONL.
+- Pooled (after `pool.clear`): a new UUID is captured via the
+ persistent `JsonlDirWatcher` and the file watcher swapped.
+
+`simpleMemory.last_session_id` is now **display-only metadata** —
+`_persist_memory` still writes it from the latest result for UI /
+diagnostic display, but the agent doesn't read it. Field is kept on
+the schema for back-compat.
+
+**Stale UUID auto-clear** (`_clear_stale_session_id`) still applies if
+someone explicitly sets `resume_session_id` (e.g. the future
+`--fork-session` UI). With `--continue` there's nothing to be stale —
+claude itself decides what's available.
## Out-of-process pty-host (deferred upgrade path)