# Session Lifecycle Hooks

Mit Sitzungslebenszyklus-Hooks können Sie auf Start- und Endereignisse der Sitzung reagieren. Verwenden Sie sie für:

<!-- markdownlint-disable GHD046 GHD005 -->

<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->

* Initialisieren des Kontexts, wenn Sitzungen beginnen
* Bereinigen von Ressourcen beim Beenden von Sitzungen
* Sitzungsmetriken und Analysen nachverfolgen
* Dynamisches Konfigurieren des Sitzungsverhaltens

## Sitzungsstart-Hook {#session-start}

Der `onSessionStart` Hook wird aufgerufen, wenn eine Sitzung beginnt (neu oder fortgesetzt).

### Hook-Signatur

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

```typescript
type SessionStartHandler = (
  input: SessionStartHookInput,
  invocation: HookInvocation
) => Promise<SessionStartHookOutput | null | undefined>;
```

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

```python
SessionStartHandler = Callable[
    [SessionStartHookInput, dict[str, str]],
    Awaitable[SessionStartHookOutput | None]
]
```

</div>

<div class="ghd-codetab" data-lang="go" data-label="Go"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Go</div>

```golang
type SessionStartHandler func(
    input SessionStartHookInput,
    invocation HookInvocation,
) (*SessionStartHookOutput, error)
```

</div>

<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

```csharp
public delegate Task<SessionStartHookOutput?> SessionStartHandler(
    SessionStartHookInput input,
    HookInvocation invocation);
```

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

```java
@FunctionalInterface
public interface SessionStartHandler {
    CompletableFuture<SessionStartHookOutput> handle(
        SessionStartHookInput input,
        HookInvocation invocation);
}
```

</div>

</div>

### Eingabe

| Feld                            | Typ                         | Beschreibung                                         |
| ------------------------------- | --------------------------- | ---------------------------------------------------- |
| `timestamp`                     | number                      | Unix-Zeitstempel, zu dem der Hook ausgelöst wurde    |
| `cwd`                           | string                      | Aktuelles Arbeitsverzeichnis                         |
| `source`                        |                             |                                                      |
| `"startup"`                     |                             |                                                      |
| \|                              |                             |                                                      |
| `"resume"`                      |                             |                                                      |
| \|                              |                             |                                                      |
| `"new"`                         |                             |                                                      |
| Wie die Sitzung gestartet wurde |                             |                                                      |
| `initialPrompt`                 | Zeichenfolge \| undefiniert | Die anfängliche Eingabeaufforderung, falls angegeben |

### Output

| Feld                | Typ    | Beschreibung                             |
| ------------------- | ------ | ---------------------------------------- |
| `additionalContext` | string | Kontext zum Hinzufügen am Sitzungsstart  |
| `modifiedConfig`    | Objekt | Sitzungskonfiguration außer Kraft setzen |

### Beispiele

#### Projektkontext zu Beginn hinzufügen

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

```typescript
const session = await client.createSession({
  hooks: {
    onSessionStart: async (input, invocation) => {
      console.log(`Session ${invocation.sessionId} started (${input.source})`);
      
      const projectInfo = await detectProjectType(input.cwd);
      
      return {
        additionalContext: `
This is a ${projectInfo.type} project.
Main language: ${projectInfo.language}
Package manager: ${projectInfo.packageManager}
        `.trim(),
      };
    },
  },
});
```

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

```python
from copilot.session import PermissionHandler

async def on_session_start(input_data, invocation):
    print(f"Session {invocation['session_id']} started ({input_data['source']})")
    
    project_info = await detect_project_type(input_data["cwd"])
    
    return {
        "additionalContext": f"""
This is a {project_info['type']} project.
Main language: {project_info['language']}
Package manager: {project_info['packageManager']}
        """.strip()
    }

session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={"on_session_start": on_session_start})
```

</div>

</div>

#### Verwaltung der Sitzungswiederaufnahme

```typescript
const session = await client.createSession({
  hooks: {
    onSessionStart: async (input, invocation) => {
      if (input.source === "resume") {
        // Load previous session state
        const previousState = await loadSessionState(invocation.sessionId);
        
        return {
          additionalContext: `
Session resumed. Previous context:
- Last topic: ${previousState.lastTopic}
- Open files: ${previousState.openFiles.join(", ")}
          `.trim(),
        };
      }
      return null;
    },
  },
});
```

#### Laden von Benutzereinstellungen

```typescript
const session = await client.createSession({
  hooks: {
    onSessionStart: async () => {
      const preferences = await loadUserPreferences();
      
      const contextParts = [];
      
      if (preferences.language) {
        contextParts.push(`Preferred language: ${preferences.language}`);
      }
      if (preferences.codeStyle) {
        contextParts.push(`Code style: ${preferences.codeStyle}`);
      }
      if (preferences.verbosity === "concise") {
        contextParts.push("Keep responses brief and to the point.");
      }
      
      return {
        additionalContext: contextParts.join("\n"),
      };
    },
  },
});
```

## Hook für das Sitzungsende {#session-end}

Der `onSessionEnd` Hook wird aufgerufen, wenn eine Sitzung endet.

### Hook-Signatur

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

```typescript
type SessionEndHandler = (
  input: SessionEndHookInput,
  invocation: HookInvocation
) => Promise<SessionEndHookOutput | null | undefined>;
```

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

```python
SessionEndHandler = Callable[
    [SessionEndHookInput, dict[str, str]],
    Awaitable[SessionEndHookOutput | None]
]
```

</div>

<div class="ghd-codetab" data-lang="go" data-label="Go"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Go</div>

```golang
type SessionEndHandler func(
    input SessionEndHookInput,
    invocation HookInvocation,
) (*SessionEndHookOutput, error)
```

</div>

<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

```csharp
public delegate Task<SessionEndHookOutput?> SessionEndHandler(
    SessionEndHookInput input,
    HookInvocation invocation);
```

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

```java
@FunctionalInterface
public interface SessionEndHandler {
    CompletableFuture<SessionEndHookOutput> handle(
        SessionEndHookInput input,
        HookInvocation invocation);
}
```

</div>

</div>

### Eingabe

| Feld           | Typ                         | Beschreibung                                                         |
| -------------- | --------------------------- | -------------------------------------------------------------------- |
| `timestamp`    | number                      | Unix-Zeitstempel, zu dem der Hook ausgelöst wurde                    |
| `cwd`          | string                      | Aktuelles Arbeitsverzeichnis                                         |
| `reason`       | string                      | Warum die Sitzung beendet wurde (siehe unten)                        |
| `finalMessage` | Zeichenfolge \| undefiniert | Die letzte Nachricht aus der Sitzung                                 |
| `error`        | Zeichenfolge \| undefiniert | Fehlermeldung, wenn die Sitzung aufgrund eines Fehlers beendet wurde |

#### Endgründe

| Grund         | Beschreibung                                                      |
| ------------- | ----------------------------------------------------------------- |
| `"complete"`  | Die Sitzung wurde normal abgeschlossen.                           |
| `"error"`     | Sitzung aufgrund eines Fehlers beendet                            |
| `"abort"`     | Die Sitzung wurde durch den Benutzer oder durch Code abgebrochen. |
| `"timeout"`   | Timeout für die Sitzung                                           |
| `"user_exit"` | Der Benutzer hat die Sitzung explizit beendet.                    |

### Output

| Feld             | Typ       | Beschreibung                                            |
| ---------------- | --------- | ------------------------------------------------------- |
| `suppressOutput` | boolean   | Endgültige Sitzungsausgabe unterdrücken                 |
| `cleanupActions` | string\[] | Liste der auszuführenden Bereinigungsaktionen           |
| `sessionSummary` | string    | Zusammenfassung der Sitzung für Protokollierung/Analyse |

### Beispiele

#### Nachverfolgen von Sitzungsmetriken

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

```typescript
const sessionStartTimes = new Map<string, number>();

const session = await client.createSession({
  hooks: {
    onSessionStart: async (input, invocation) => {
      sessionStartTimes.set(invocation.sessionId, input.timestamp);
      return null;
    },
    onSessionEnd: async (input, invocation) => {
      const startTime = sessionStartTimes.get(invocation.sessionId);
      const duration = startTime ? input.timestamp - startTime : 0;
      
      await recordMetrics({
        sessionId: invocation.sessionId,
        duration,
        endReason: input.reason,
      });
      
      sessionStartTimes.delete(invocation.sessionId);
      return null;
    },
  },
});
```

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

```python
from copilot.session import PermissionHandler

session_start_times = {}

async def on_session_start(input_data, invocation):
    session_start_times[invocation["session_id"]] = input_data["timestamp"]
    return None

async def on_session_end(input_data, invocation):
    start_time = session_start_times.get(invocation["session_id"])
    duration = input_data["timestamp"] - start_time if start_time else 0
    
    await record_metrics({
        "session_id": invocation["session_id"],
        "duration": duration,
        "end_reason": input_data["reason"],
    })
    
    session_start_times.pop(invocation["session_id"], None)
    return None

session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={
        "on_session_start": on_session_start,
        "on_session_end": on_session_end,
    })
```

</div>

</div>

#### Bereinigen von Ressourcen

```typescript
const sessionResources = new Map<string, { tempFiles: string[] }>();

const session = await client.createSession({
  hooks: {
    onSessionStart: async (input, invocation) => {
      sessionResources.set(invocation.sessionId, { tempFiles: [] });
      return null;
    },
    onSessionEnd: async (input, invocation) => {
      const resources = sessionResources.get(invocation.sessionId);
      
      if (resources) {
        // Clean up temp files
        for (const file of resources.tempFiles) {
          await fs.unlink(file).catch(() => {});
        }
        sessionResources.delete(invocation.sessionId);
      }
      
      console.log(`Session ${invocation.sessionId} ended: ${input.reason}`);
      return null;
    },
  },
});
```

#### Sitzungsstatus zum Fortsetzen speichern

```typescript
const session = await client.createSession({
  hooks: {
    onSessionEnd: async (input, invocation) => {
      if (input.reason !== "error") {
        // Save state for potential resume
        await saveSessionState(invocation.sessionId, {
          endTime: input.timestamp,
          cwd: input.cwd,
          reason: input.reason,
        });
      }
      return null;
    },
  },
});
```

#### Protokollsitzungszusammenfassung

```typescript
const sessionData: Record<string, { prompts: number; tools: number; startTime: number }> = {};

const session = await client.createSession({
  hooks: {
    onSessionStart: async (input, invocation) => {
      sessionData[invocation.sessionId] = { 
        prompts: 0, 
        tools: 0, 
        startTime: input.timestamp 
      };
      return null;
    },
    onUserPromptSubmitted: async (_, invocation) => {
      sessionData[invocation.sessionId].prompts++;
      return null;
    },
    onPreToolUse: async (_, invocation) => {
      sessionData[invocation.sessionId].tools++;
      return { permissionDecision: "allow" };
    },
    onSessionEnd: async (input, invocation) => {
      const data = sessionData[invocation.sessionId];
      console.log(`
Session Summary:
  ID: ${invocation.sessionId}
  Duration: ${(input.timestamp - data.startTime) / 1000}s
  Prompts: ${data.prompts}
  Tool calls: ${data.tools}
  End reason: ${input.reason}
      `.trim());
      
      delete sessionData[invocation.sessionId];
      return null;
    },
  },
});
```

## Agent-Stopp-Hook {#agent-stop}

Der Agent-Stopp-Hook wird ausgeführt, wenn der Agent der obersten Ebene auf natürliche Weise das Ende einer Interaktion erreicht. Er ist getrennt von `onSessionEnd`: Die Sitzung bleibt aktiv, und der Hook kann einen weiteren Agent-Turn anfordern.

| Sprache              | Handler          |
| -------------------- | ---------------- |
| Node.js / TypeScript | `onAgentStop`    |
| Python               | `on_agent_stop`  |
| Go                   | `OnAgentStop`    |
| .NET                 | `OnAgentStop`    |
| Rust                 | `on_agent_stop`  |
| Java                 | `setOnAgentStop` |

### Eingabe

Die Namen der öffentlichen Mitglieder folgen den Groß-/Kleinschreibungskonventionen der einzelnen Sprachen:

| Bedeutung                                                                          | Node.js/Python   | Gehe zu /.NET    | Rust               | Java                  |
| ---------------------------------------------------------------------------------- | ---------------- | ---------------- | ------------------ | --------------------- |
| Warum der Agent gestoppt wurde, z. B. `end_turn`                                   | `stopReason`     | `StopReason`     | `stop_reason`      | `getStopReason()`     |
| Pfad zum Transkript der On-Disk-Sitzung                                            | `transcriptPath` | `TranscriptPath` | `transcript_path`  | `getTranscriptPath()` |
| Gibt an, ob eine frühere Blockentscheidung diese Fortsetzung bereits erzwungen hat | `stopHookActive` | `StopHookActive` | `stop_hook_active` | `getStopHookActive()` |

### Output

Gibt keine Ausgabe zurück, damit der Agent beendet werden kann. Geben Sie eine Blockierentscheidung zurück, um eine weitere Benutzernachricht in die Warteschlange zu stellen und fortzufahren:

```json
{
  "decision": "block",
  "reason": "Run the final validation and fix any failures."
}
```

Verwenden Sie das oben angegebene Active-Stop-Element, um zu vermeiden, dass ein Agent, der aufgrund dieses Hooks bereits weitergelaufen ist, erneut blockiert wird. Die Laufzeit begrenzt auch aufeinander folgende Blockierungsentscheidungen.

## Bewährte Methoden

1. **Sorgen Sie dafür, dass `onSessionStart` schnell bleibt** – Die Benutzer warten darauf, dass die Sitzung einsatzbereit ist.

2. **Berücksichtigen Sie alle Gründe für die Beendigung** – Gehen Sie nicht davon aus, dass Sitzungen immer ordnungsgemäß beendet werden; behandeln Sie auch Fehler und Abbrüche.

3. **Ressourcen freigeben** – Verwenden Sie `onSessionEnd`, um alle während der Sitzung zugewiesenen Ressourcen freizugeben.

4. **Speichern Sie so wenig Status wie möglich** - Wenn Sie Sitzungsdaten verfolgen, halten Sie sie so schlank wie möglich.

5. **Machen Sie die Bereinigung idempotent** - `onSessionEnd` wird möglicherweise nicht aufgerufen, wenn der Prozess abstürzt.

## Siehe auch

* [Verwenden Sie Hooks](/de/copilot/how-tos/copilot-sdk/hooks)
* [Fehlerbehandlung Hook](/de/copilot/how-tos/copilot-sdk/hooks/error-handling)
* [Debughandbuch](/de/copilot/how-tos/copilot-sdk/troubleshooting/debugging)