@with-logic/elwood 0.1.1 → 0.1.2

package/prd/05-api/5.2-resuming-claude.md

@@ -0,0 +1,86 @@
+## 5.2 Resuming Claude
+
+```ts
+type ResumeClaudeOptions = {
+  readonly elwoodSessionId: string;
+  readonly cwd?: string;
+  readonly stateDir?: string;
+  readonly hooks?: ClaudeHookHandlers;
+  readonly initialSize?: TerminalSize;
+  readonly reasoningEffort?: ClaudeReasoningEffort;
+  readonly permissionMode?: ClaudePermissionMode;
+  readonly allowedTools?: readonly ClaudeToolRule[];
+  readonly disallowedTools?: readonly ClaudeToolRule[];
+  readonly tools?: readonly ClaudeToolRule[];
+  readonly highTrust?: boolean;
+  readonly autoupdate?: boolean;
+  readonly autotrust?: boolean;
+  readonly hookTimeoutMs?: number;
+  readonly strictVersionCheck?: boolean;
+};
+
+declare function resumeClaude(options: ResumeClaudeOptions): Promise<ClaudeSessionApi>;
+```
+
+Resume uses Elwood's minimal persisted session record (§8.2) to relaunch or
+reattach the wrapped Claude session through Claude Code's own resume mechanism. Callers should
+not need Claude's session ID. Because the default state store is project-local,
+callers that resume from a different process working directory must pass the
+original `cwd` or the explicit `stateDir` used at start time. Calling
+`resumeClaude({ elwoodSessionId })` without `cwd` or `stateDir` uses the current
+process working directory to discover the project-local state store.
+
+`resumeClaude` must verify that the persisted Elwood session record belongs to
+the Claude adapter before launching. Passing a Codex session ID to `resumeClaude`
+must fail with a typed error instead of launching a Claude process.
+If Elwood has not observed and persisted Claude Code's internal session id from
+`SessionStart`, `resumeClaude` must fail explicitly with `resume_unavailable`.
+It must not silently launch a fresh Claude conversation under the same Elwood
+session ID.
+
+Decision note: MVP resume re-establishes the Elwood wrapper, hook routing, and the
+agent's internal conversation resume id. It does NOT restore a persisted terminal
+size — that is not persisted (§8.2); the caller passes
+`initialSize` on resume (it otherwise falls back to the default). The launch
+posture (privilege and tool policy) is persisted in the session record at
+start, and resume defaults to it: a bare `resumeClaude` relaunches with the
+same `permissionMode`, `allowedTools`, `disallowedTools`, and `tools` the
+session started with, so tool restrictions cannot silently loosen across a
+resume. Explicit resume options override the persisted posture field by
+field, and the effective posture is re-persisted. Other adapter launch policy
+such as model, reasoning effort, and caller config overrides remains
+caller-supplied-per-call and is intentionally not persisted yet — a resumed
+session that wants a non-default reasoning effort must re-supply `reasoningEffort`,
+exactly as it must re-supply `model`. `highTrust: true` on resume expands to the
+same explicit `permissionMode: "bypassPermissions"` override as on start (and
+conflicts with an explicit `permissionMode` the same way); a bare resume keeps
+the persisted posture, including one that a high-trust start persisted.
+
+Because every persisting parent writes the same try-resume-else-start dance,
+Elwood provides it directly:
+
+```ts
+type StartOrResumeClaudeOptions = StartClaudeOptions & {
+  readonly elwoodSessionId?: string;
+};
+
+declare function startOrResumeClaude(
+  options: StartOrResumeClaudeOptions,
+): Promise<{ readonly session: ClaudeSessionApi; readonly resumed: boolean }>;
+```
+
+When `elwoodSessionId` is set, `startOrResumeClaude` attempts a resume,
+forwarding every start option the resume entry point accepts: `cwd`,
+`stateDir`, `hooks`, `initialSize`, `reasoningEffort`, `permissionMode`,
+`allowedTools`, `disallowedTools`, `tools`, `autoupdate`, `autotrust`,
+`highTrust`, `hookTimeoutMs`, and `strictVersionCheck` (for Codex: the same shared options
+plus `sandbox` and `approvalPolicy`). Non-persisted per-call policy such as
+`reasoningEffort` therefore reaches a resumed session exactly as it reaches a
+fresh one. It falls back to a fresh `startClaude` only for the
+error names that mean "no resumable session": `state_not_found`,
+`resume_unavailable`, and `adapter_mismatch`. Every other error — including
+`state_corrupt` — is a real failure and is rethrown, so data problems are
+never silently papered over by a fresh session. The result reports which path
+ran so callers can re-persist a new `elwoodSessionId` after a fallback.
+`startOrResumeCodex` behaves identically for Codex. `persona` follows its
+normal rules: delivered on a fresh start, never re-sent on resume.