feat: session continuation for claude adapter (--continue, --resume, --session-id)

opengap run -a claude previously had no way to continue a prior Claude Code
conversation — every run started fresh. Adds three flags mapped to Claude
Code's native session flags:

- -c, --continue: continue the most recent session in the working directory
  (pairs with --workspace, which decides where the session is looked up)
- --resume <sessionId>: reopen an exact session by ID
- --session-id <uuid>: pin a new session to a known UUID so scripts can
  resume deterministically later

Guards: --continue and --resume are mutually exclusive; --session-id must
be a valid UUID; all three are rejected with a clear error for non-claude
adapters instead of being silently ignored. Docs updated with a session-
continuation section and examples.

Author: shreyas-lyzr

docs.md

@@ -633,9 +633,14 @@ opengap run [options]
 | `--refresh` | `false` | Force re-clone (pull latest) |
 | `--no-cache` | `false` | Clone to temp dir, delete on exit |
 | `-p, --prompt <query>` | — | Initial prompt (non-interactive for some adapters) |
+| `-c, --continue` | `false` | Continue the most recent session in the working directory (claude adapter only) |
+| `--resume <sessionId>` | — | Resume a specific session by ID (claude adapter only) |
+| `--session-id <uuid>` | — | Start with a specific session ID so it can be resumed later (claude adapter only) |
 
 Either `--repo` or `--dir` is required.
 
+**Session continuation (claude adapter).** `--continue` resumes the most recent Claude Code conversation in the working directory — combine it with `--workspace` to pick which directory's session to continue. `--resume <sessionId>` reopens an exact session, and `--session-id <uuid>` pins a new session to a known ID so scripts can resume it deterministically later. `--continue` and `--resume` are mutually exclusive. These flags are rejected for non-claude adapters rather than silently ignored.
+
 `--workspace` lets an agent definition live separately from the repository it operates on. It is honored by adapters that can safely set the spawned process working directory directly, including `claude`, `openai`, `crewai`, `openclaw`, and `nanobot`. Adapters that generate an isolated runtime workspace, such as `opencode`, `gemini`, and `gitclaw`, continue to run from that prepared workspace to avoid overwriting files such as `AGENTS.md`, `GEMINI.md`, or `agent.yaml` in the target repository.
 
 **Available adapters:**
@@ -674,6 +679,13 @@ opengap run -d ./my-agent -p "Review my authentication code"
 # Run an agent definition against a separate target workspace
 opengap run -d ./agents/reviewer --workspace ~/code/my-app -a claude -p "Review this repository"
 
+# Continue the most recent session in that workspace
+opengap run -d ./agents/reviewer --workspace ~/code/my-app -a claude -c -p "Now fix the issues you found"
+
+# Pin a session ID on first run, resume it later
+opengap run -d ./my-agent --session-id 3f9f74a6-6b7c-4a3e-9e1d-2f1f0a9b8c7d -p "Start the audit"
+opengap run -d ./my-agent --resume 3f9f74a6-6b7c-4a3e-9e1d-2f1f0a9b8c7d -p "Continue the audit"
+
 # Run a specific branch, force refresh
 opengap run -r https://github.com/user/agent -b develop --refresh
 

src/commands/run.ts

@@ -25,6 +25,9 @@ interface RunOptions {
   prompt?: string;
   dir?: string;
   workspace?: string;
+  continue?: boolean;
+  resume?: string;
+  sessionId?: string;
 }
 
 export const runCommand = new Command('run')
@@ -37,6 +40,9 @@ export const runCommand = new Command('run')
   .option('-p, --prompt <query>', 'Initial prompt to send to the agent')
   .option('-d, --dir <dir>', 'Use local directory instead of git URL')
   .option('-w, --workspace <dir>', 'Working directory for the spawned agent process')
+  .option('-c, --continue', 'Continue the most recent session in the working directory (claude adapter)', false)
+  .option('--resume <sessionId>', 'Resume a specific session by ID (claude adapter)')
+  .option('--session-id <uuid>', 'Start with a specific session ID so it can be resumed later (claude adapter)')
   .action(async (options: RunOptions) => {
     let agentDir: string;
     let cleanup: (() => void) | undefined;
@@ -96,11 +102,24 @@ export const runCommand = new Command('run')
     }
     divider();
 
+    // Session flags are claude-adapter-only — warn instead of silently dropping
+    if ((options.continue || options.resume || options.sessionId) && options.adapter !== 'claude') {
+      error(`--continue / --resume / --session-id are only supported by the claude adapter (got: ${options.adapter})`);
+      if (cleanup) cleanup();
+      process.exit(1);
+    }
+
     // Run with selected adapter
     try {
       switch (options.adapter) {
         case 'claude':
-          runWithClaude(agentDir, manifest, { prompt: options.prompt, workspace: options.workspace });
+          runWithClaude(agentDir, manifest, {
+            prompt: options.prompt,
+            workspace: options.workspace,
+            continue: options.continue,
+            resume: options.resume,
+            sessionId: options.sessionId,
+          });
           break;
         case 'openai':
           runWithOpenAI(agentDir, manifest, { workspace: options.workspace });

src/runners/claude.ts

@@ -12,6 +12,12 @@ import { error, info, warn } from '../utils/format.js';
 export interface ClaudeRunOptions {
   prompt?: string;
   workspace?: string;
+  /** Continue the most recent Claude Code conversation in the working directory. */
+  continue?: boolean;
+  /** Resume a specific Claude Code session by its session ID. */
+  resume?: string;
+  /** Start the conversation with a specific session ID (UUID) so it can be resumed later. */
+  sessionId?: string;
 }
 
 export function runWithClaude(agentDir: string, manifest: AgentManifest, options: ClaudeRunOptions = {}): void {
@@ -72,6 +78,31 @@ export function runWithClaude(agentDir: string, manifest: AgentManifest, options
     tmpFiles.push(settingsFile);
   }
 
+  // Session continuation — maps to Claude Code's native session flags.
+  // --continue resumes the most recent conversation in the working directory,
+  // so it pairs with --workspace: the session is looked up in runCwd.
+  if (options.continue && options.resume) {
+    error('--continue and --resume are mutually exclusive');
+    process.exitCode = 1;
+    return;
+  }
+  if (options.continue) {
+    args.push('--continue');
+    info('Continuing most recent Claude Code session in the working directory');
+  }
+  if (options.resume) {
+    args.push('--resume', options.resume);
+    info(`Resuming Claude Code session ${options.resume}`);
+  }
+  if (options.sessionId) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(options.sessionId)) {
+      error(`--session-id must be a valid UUID, got: ${options.sessionId}`);
+      process.exitCode = 1;
+      return;
+    }
+    args.push('--session-id', options.sessionId);
+  }
+
   // Initial prompt (print mode)
   if (options.prompt) {
     args.push('-p', options.prompt);