> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# セッション制御

`query()` はデフォルトで毎回の呼び出し時に新しいセッションを開始します。`options` のいくつかのフィールドを通じて、セッション ID の指定、履歴セッションの復元、既存セッションからのフォークが可能です。

<div id="コンセプト" />

## コンセプト

1つのセッションは CLI 側で永続化された1つの対話履歴（コンテキスト、ツール呼び出し記録、圧縮境界などを含む）に対応し、UUID で識別されます。システムメッセージ `init` に今回の `session_id` が含まれ、これが後続の resume / fork のアンカーポイントとなります。

以下の例にある `auth: accessTokenFromEnv()` は、プロジェクトで使用している他の認証方法に置き換えることもできます。詳細は [SDK 認証](/ja/cli/sdk/authentication) を参照してください。

<div id="新規セッションの作成" />

## 新規セッションの作成

<div id="デフォルト" />

### デフォルト

セッション関連フィールドを渡さない場合、毎回新規作成されます：

```typescript theme={null}
const q = query({
  prompt: 'Hello',
  options: { auth: accessTokenFromEnv() },
});
```

<div id="セッション-id-の指定" />

### セッション ID の指定

呼び出し側がセッションの UUID を決定します（ホストが独自にセッションインデックスを管理する場合に適します）：

```typescript theme={null}
import { randomUUID } from 'node:crypto';

const sessionId = randomUUID();
const q = query({
  prompt: 'Hello',
  options: {
    auth: accessTokenFromEnv(),
    sessionId,
  },
});
```

<div id="セッションの復元" />

## セッションの復元

<div id="id-による復元" />

### ID による復元

```typescript theme={null}
const q = query({
  prompt: 'Continue the previous conversation',
  options: {
    auth: accessTokenFromEnv(),
    resume: 'previous-session-id',
  },
});
```

<div id="最後のセッションの復元" />

### 最後のセッションの復元

セッション ID が不明な場合、`continue: true` で最後に変更されたセッションに接続します：

```typescript theme={null}
const q = query({
  prompt: 'Continue',
  options: {
    auth: accessTokenFromEnv(),
    continue: true,
  },
});
```

`resume` と `continue` は同時に渡さないでください。

<div id="セッションのフォーク" />

## セッションのフォーク

既存のセッションから新しいセッションを派生させ、元のコンテキストを保持しつつ新しいセッション ID を取得します。元のセッションは影響を受けません：

```typescript theme={null}
const q = query({
  prompt: 'Based on the prior context, explore a different direction',
  options: {
    auth: accessTokenFromEnv(),
    resume: 'source-session-id',
    forkSession: true,
  },
});
```

フォーク後の新しいセッションに ID を指定する場合：

```typescript theme={null}
options: {
  auth: accessTokenFromEnv(),
  resume: 'source-session-id',
  forkSession: true,
  sessionId: 'my-new-session-id',
}
```

<div id="フィールドクイックリファレンス" />

## フィールドクイックリファレンス

| フィールド         | 型         | 動作                                                  |
| ------------- | --------- | --------------------------------------------------- |
| `sessionId`   | `string`  | 単独使用：この ID で新規作成。`forkSession` と併用：フォーク後の新セッションの ID |
| `resume`      | `string`  | 復元するセッション ID                                        |
| `continue`    | `boolean` | `true` で最後のセッションを復元                                 |
| `forkSession` | `boolean` | `resume` と併用し、接続ではなくフォーク                            |

<div id="現在のセッション-id-の取得" />

## 現在のセッション ID の取得

`init` メッセージを監視します：

```typescript theme={null}
for await (const msg of q) {
  if (msg.type === 'system' && msg.subtype === 'init') {
    console.log('session_id:', msg.session_id);
  }
}
```