diff --git a/.claude/commands/opsx/apply.md b/.claude/commands/opsx/apply.md
index ae14f0f..45003f8 100644
--- a/.claude/commands/opsx/apply.md
+++ b/.claude/commands/opsx/apply.md
@@ -26,6 +26,7 @@ Implement tasks from an OpenSpec change.
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
    - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
 
 3. **Get apply instructions**
@@ -45,6 +46,8 @@ Implement tasks from an OpenSpec change.
    - If `state: "all_done"`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
+   **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
 4. **Read context files**
 
    Read every file path listed under `contextFiles` from the apply instructions output.
diff --git a/.claude/commands/opsx/archive.md b/.claude/commands/opsx/archive.md
index 5e91608..4af9687 100644
--- a/.claude/commands/opsx/archive.md
+++ b/.claude/commands/opsx/archive.md
@@ -26,8 +26,11 @@ Archive a completed change in the experimental workflow.
 
    Parse the JSON to understand:
    - `schemaName`: The workflow being used
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
    - `artifacts`: List of artifacts with their status (`done` or other)
 
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
    **If any artifacts are not `done`:**
    - Display warning listing incomplete artifacts
    - Prompt user for confirmation to continue
@@ -48,7 +51,7 @@ Archive a completed change in the experimental workflow.
 
 4. **Assess delta spec sync state**
 
-   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
 
    **If delta specs exist:**
    - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
@@ -63,19 +66,19 @@ Archive a completed change in the experimental workflow.
 
 5. **Perform the archive**
 
-   Create the archive directory if it doesn't exist:
+   Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
    ```bash
-   mkdir -p openspec/changes/archive
+   mkdir -p "<planningHome.changesDir>/archive"
    ```
 
    Generate target name using current date: `YYYY-MM-DD-<change-name>`
 
    **Check if target already exists:**
    - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
+   - If no: Move `changeRoot` to the archive directory
 
    ```bash
-   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
    ```
 
 6. **Display summary**
@@ -94,7 +97,7 @@ Archive a completed change in the experimental workflow.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** ✓ Synced to main specs
 
 All artifacts complete. All tasks complete.
@@ -107,7 +110,7 @@ All artifacts complete. All tasks complete.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** No delta specs
 
 All artifacts complete. All tasks complete.
@@ -120,7 +123,7 @@ All artifacts complete. All tasks complete.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** Sync skipped (user chose to skip)
 
 **Warnings:**
@@ -137,7 +140,7 @@ Review the archive if this was not intentional.
 ## Archive Failed
 
 **Change:** <change-name>
-**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Target:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 
 Target archive directory already exists.
 
diff --git a/.claude/commands/opsx/explore.md b/.claude/commands/opsx/explore.md
index 1757907..8655619 100644
--- a/.claude/commands/opsx/explore.md
+++ b/.claude/commands/opsx/explore.md
@@ -107,11 +107,10 @@ Think freely. When insights crystallize, you might offer:
 
 If the user mentions a change or you detect one is relevant:
 
-1. **Read existing artifacts for context**
-   - `openspec/changes/<name>/proposal.md`
-   - `openspec/changes/<name>/design.md`
-   - `openspec/changes/<name>/tasks.md`
-   - etc.
+1. **Resolve and read existing artifacts for context**
+   - Run `openspec status --change "<name>" --json`.
+   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
+   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
 
 2. **Reference them naturally in conversation**
    - "Your design mentions using Redis, but we just realized SQLite fits better..."
diff --git a/.claude/commands/opsx/propose.md b/.claude/commands/opsx/propose.md
index 05276f4..90ba344 100644
--- a/.claude/commands/opsx/propose.md
+++ b/.claude/commands/opsx/propose.md
@@ -33,7 +33,7 @@ When ready to implement, run /opsx:apply
    ```bash
    openspec new change "<name>"
    ```
-   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+   This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
 
 3. **Get the artifact build order**
    ```bash
@@ -42,6 +42,7 @@ When ready to implement, run /opsx:apply
    Parse the JSON to get:
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
    - `artifacts`: list of all artifacts with their status and dependencies
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
 
 4. **Create artifacts in sequence until apply-ready**
 
@@ -59,10 +60,10 @@ When ready to implement, run /opsx:apply
         - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
         - `template`: The structure to use for your output file
         - `instruction`: Schema-specific guidance for this artifact type
-        - `outputPath`: Where to write the artifact
+        - `resolvedOutputPath`: Resolved path or pattern to write the artifact
         - `dependencies`: Completed artifacts to read for context
       - Read any completed dependency files for context
-      - Create the artifact file using `template` as the structure
+      - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath`
       - Apply `context` and `rules` as constraints - but do NOT copy them into the file
       - Show brief progress: "Created <artifact-id>"
 
diff --git a/.claude/skills/openspec-apply-change/SKILL.md b/.claude/skills/openspec-apply-change/SKILL.md
index 70fbdb8..db4d8ce 100644
--- a/.claude/skills/openspec-apply-change/SKILL.md
+++ b/.claude/skills/openspec-apply-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Implement tasks from an OpenSpec change.
@@ -30,6 +30,7 @@ Implement tasks from an OpenSpec change.
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
    - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
 
 3. **Get apply instructions**
@@ -49,6 +50,8 @@ Implement tasks from an OpenSpec change.
    - If `state: "all_done"`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
+   **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
 4. **Read context files**
 
    Read every file path listed under `contextFiles` from the apply instructions output.
diff --git a/.claude/skills/openspec-archive-change/SKILL.md b/.claude/skills/openspec-archive-change/SKILL.md
index 12e2f70..97c3e5e 100644
--- a/.claude/skills/openspec-archive-change/SKILL.md
+++ b/.claude/skills/openspec-archive-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Archive a completed change in the experimental workflow.
@@ -30,8 +30,11 @@ Archive a completed change in the experimental workflow.
 
    Parse the JSON to understand:
    - `schemaName`: The workflow being used
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
    - `artifacts`: List of artifacts with their status (`done` or other)
 
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
    **If any artifacts are not `done`:**
    - Display warning listing incomplete artifacts
    - Use **AskUserQuestion tool** to confirm user wants to proceed
@@ -52,7 +55,7 @@ Archive a completed change in the experimental workflow.
 
 4. **Assess delta spec sync state**
 
-   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
 
    **If delta specs exist:**
    - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
@@ -67,19 +70,19 @@ Archive a completed change in the experimental workflow.
 
 5. **Perform the archive**
 
-   Create the archive directory if it doesn't exist:
+   Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
    ```bash
-   mkdir -p openspec/changes/archive
+   mkdir -p "<planningHome.changesDir>/archive"
    ```
 
    Generate target name using current date: `YYYY-MM-DD-<change-name>`
 
    **Check if target already exists:**
    - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
+   - If no: Move `changeRoot` to the archive directory
 
    ```bash
-   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
    ```
 
 6. **Display summary**
@@ -98,7 +101,7 @@ Archive a completed change in the experimental workflow.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
 
 All artifacts complete. All tasks complete.
diff --git a/.claude/skills/openspec-explore/SKILL.md b/.claude/skills/openspec-explore/SKILL.md
index 6858d3f..1e97aaa 100644
--- a/.claude/skills/openspec-explore/SKILL.md
+++ b/.claude/skills/openspec-explore/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
@@ -102,11 +102,10 @@ Think freely. When insights crystallize, you might offer:
 
 If the user mentions a change or you detect one is relevant:
 
-1. **Read existing artifacts for context**
-   - `openspec/changes/<name>/proposal.md`
-   - `openspec/changes/<name>/design.md`
-   - `openspec/changes/<name>/tasks.md`
-   - etc.
+1. **Resolve and read existing artifacts for context**
+   - Run `openspec status --change "<name>" --json`.
+   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
+   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
 
 2. **Reference them naturally in conversation**
    - "Your design mentions using Redis, but we just realized SQLite fits better..."
diff --git a/.claude/skills/openspec-propose/SKILL.md b/.claude/skills/openspec-propose/SKILL.md
index 4b7e204..9fc8513 100644
--- a/.claude/skills/openspec-propose/SKILL.md
+++ b/.claude/skills/openspec-propose/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Propose a new change - create the change and generate all artifacts in one step.
@@ -37,7 +37,7 @@ When ready to implement, run /opsx:apply
    ```bash
    openspec new change "<name>"
    ```
-   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+   This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
 
 3. **Get the artifact build order**
    ```bash
@@ -46,6 +46,7 @@ When ready to implement, run /opsx:apply
    Parse the JSON to get:
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
    - `artifacts`: list of all artifacts with their status and dependencies
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
 
 4. **Create artifacts in sequence until apply-ready**
 
@@ -63,10 +64,10 @@ When ready to implement, run /opsx:apply
         - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
         - `template`: The structure to use for your output file
         - `instruction`: Schema-specific guidance for this artifact type
-        - `outputPath`: Where to write the artifact
+        - `resolvedOutputPath`: Resolved path or pattern to write the artifact
         - `dependencies`: Completed artifacts to read for context
       - Read any completed dependency files for context
-      - Create the artifact file using `template` as the structure
+      - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath`
       - Apply `context` and `rules` as constraints - but do NOT copy them into the file
       - Show brief progress: "Created <artifact-id>"
 
diff --git a/.codex/skills/openspec-apply-change/SKILL.md b/.codex/skills/openspec-apply-change/SKILL.md
new file mode 100644
index 0000000..db4d8ce
--- /dev/null
+++ b/.codex/skills/openspec-apply-change/SKILL.md
@@ -0,0 +1,159 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.4.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+   **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.codex/skills/openspec-archive-change/SKILL.md b/.codex/skills/openspec-archive-change/SKILL.md
new file mode 100644
index 0000000..97c3e5e
--- /dev/null
+++ b/.codex/skills/openspec-archive-change/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.4.1"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
+   ```bash
+   mkdir -p "<planningHome.changesDir>/archive"
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move `changeRoot` to the archive directory
+
+   ```bash
+   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.codex/skills/openspec-explore/SKILL.md b/.codex/skills/openspec-explore/SKILL.md
new file mode 100644
index 0000000..1e97aaa
--- /dev/null
+++ b/.codex/skills/openspec-explore/SKILL.md
@@ -0,0 +1,287 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.4.1"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Resolve and read existing artifacts for context**
+   - Run `openspec status --change "<name>" --json`.
+   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
+   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │          CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.codex/skills/openspec-propose/SKILL.md b/.codex/skills/openspec-propose/SKILL.md
new file mode 100644
index 0000000..9fc8513
--- /dev/null
+++ b/.codex/skills/openspec-propose/SKILL.md
@@ -0,0 +1,111 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.4.1"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `resolvedOutputPath`: Resolved path or pattern to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath`
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.cursor/commands/opsx-apply.md b/.cursor/commands/opsx-apply.md
index fcfa6c9..9c17178 100644
--- a/.cursor/commands/opsx-apply.md
+++ b/.cursor/commands/opsx-apply.md
@@ -26,6 +26,7 @@ Implement tasks from an OpenSpec change.
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
    - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
 
 3. **Get apply instructions**
@@ -45,6 +46,8 @@ Implement tasks from an OpenSpec change.
    - If `state: "all_done"`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
+   **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
 4. **Read context files**
 
    Read every file path listed under `contextFiles` from the apply instructions output.
diff --git a/.cursor/commands/opsx-archive.md b/.cursor/commands/opsx-archive.md
index e5cdd0e..8e3553c 100644
--- a/.cursor/commands/opsx-archive.md
+++ b/.cursor/commands/opsx-archive.md
@@ -26,8 +26,11 @@ Archive a completed change in the experimental workflow.
 
    Parse the JSON to understand:
    - `schemaName`: The workflow being used
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
    - `artifacts`: List of artifacts with their status (`done` or other)
 
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
    **If any artifacts are not `done`:**
    - Display warning listing incomplete artifacts
    - Prompt user for confirmation to continue
@@ -48,7 +51,7 @@ Archive a completed change in the experimental workflow.
 
 4. **Assess delta spec sync state**
 
-   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
 
    **If delta specs exist:**
    - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
@@ -63,19 +66,19 @@ Archive a completed change in the experimental workflow.
 
 5. **Perform the archive**
 
-   Create the archive directory if it doesn't exist:
+   Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
    ```bash
-   mkdir -p openspec/changes/archive
+   mkdir -p "<planningHome.changesDir>/archive"
    ```
 
    Generate target name using current date: `YYYY-MM-DD-<change-name>`
 
    **Check if target already exists:**
    - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
+   - If no: Move `changeRoot` to the archive directory
 
    ```bash
-   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
    ```
 
 6. **Display summary**
@@ -94,7 +97,7 @@ Archive a completed change in the experimental workflow.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** ✓ Synced to main specs
 
 All artifacts complete. All tasks complete.
@@ -107,7 +110,7 @@ All artifacts complete. All tasks complete.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** No delta specs
 
 All artifacts complete. All tasks complete.
@@ -120,7 +123,7 @@ All artifacts complete. All tasks complete.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** Sync skipped (user chose to skip)
 
 **Warnings:**
@@ -137,7 +140,7 @@ Review the archive if this was not intentional.
 ## Archive Failed
 
 **Change:** <change-name>
-**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Target:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 
 Target archive directory already exists.
 
diff --git a/.cursor/commands/opsx-explore.md b/.cursor/commands/opsx-explore.md
index f1aceec..ba1339b 100644
--- a/.cursor/commands/opsx-explore.md
+++ b/.cursor/commands/opsx-explore.md
@@ -107,11 +107,10 @@ Think freely. When insights crystallize, you might offer:
 
 If the user mentions a change or you detect one is relevant:
 
-1. **Read existing artifacts for context**
-   - `openspec/changes/<name>/proposal.md`
-   - `openspec/changes/<name>/design.md`
-   - `openspec/changes/<name>/tasks.md`
-   - etc.
+1. **Resolve and read existing artifacts for context**
+   - Run `openspec status --change "<name>" --json`.
+   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
+   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
 
 2. **Reference them naturally in conversation**
    - "Your design mentions using Redis, but we just realized SQLite fits better..."
diff --git a/.cursor/commands/opsx-propose.md b/.cursor/commands/opsx-propose.md
index 4d75466..1744ba3 100644
--- a/.cursor/commands/opsx-propose.md
+++ b/.cursor/commands/opsx-propose.md
@@ -33,7 +33,7 @@ When ready to implement, run /opsx:apply
    ```bash
    openspec new change "<name>"
    ```
-   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+   This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
 
 3. **Get the artifact build order**
    ```bash
@@ -42,6 +42,7 @@ When ready to implement, run /opsx:apply
    Parse the JSON to get:
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
    - `artifacts`: list of all artifacts with their status and dependencies
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
 
 4. **Create artifacts in sequence until apply-ready**
 
@@ -59,10 +60,10 @@ When ready to implement, run /opsx:apply
         - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
         - `template`: The structure to use for your output file
         - `instruction`: Schema-specific guidance for this artifact type
-        - `outputPath`: Where to write the artifact
+        - `resolvedOutputPath`: Resolved path or pattern to write the artifact
         - `dependencies`: Completed artifacts to read for context
       - Read any completed dependency files for context
-      - Create the artifact file using `template` as the structure
+      - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath`
       - Apply `context` and `rules` as constraints - but do NOT copy them into the file
       - Show brief progress: "Created <artifact-id>"
 
diff --git a/.cursor/rules/codegraph.mdc b/.cursor/rules/codegraph.mdc
new file mode 100644
index 0000000..00a3f81
--- /dev/null
+++ b/.cursor/rules/codegraph.mdc
@@ -0,0 +1,39 @@
+---
+description: CodeGraph MCP usage guide — when to use which tool
+alwaysApply: true
+---
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+This project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
+
+### When to prefer codegraph over native search
+
+Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
+
+| Question | Tool |
+|---|---|
+| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |
+| "What calls function Y?" | `codegraph_callers` |
+| "What does Y call?" | `codegraph_callees` |
+| "How does X reach/become Y? / trace the flow from X to Y" | `codegraph_trace` (one call = the whole path, incl. callback/React/JSX dynamic hops) |
+| "What would break if I changed Z?" | `codegraph_impact` |
+| "Show me Y's signature / source / docstring" | `codegraph_node` |
+| "Give me focused context for a task/area" | `codegraph_context` |
+| "See several related symbols' source at once" | `codegraph_explore` |
+| "What files exist under path/" | `codegraph_files` |
+| "Is the index healthy?" | `codegraph_status` |
+
+### Rules of thumb
+
+- **Answer directly — don't delegate exploration.** For "how does X work" / architecture questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. For a specific **flow** ("how does X reach Y") start with `codegraph_trace` from→to — one call returns the whole path with dynamic hops bridged — then ONE `codegraph_explore` for the bodies; don't rebuild the path with `codegraph_search` + `codegraph_callers`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
+- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
+- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.
+- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call.
+- **Don't loop `codegraph_node` over many symbols** — one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
+- **Index lag — check the staleness banner, don't guess a wait.** When a codegraph response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. `codegraph_status` also lists pending files under "Pending sync".
+
+### If `.codegraph/` doesn't exist
+
+The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*
+<!-- CODEGRAPH_END -->
diff --git a/.cursor/skills/openspec-apply-change/SKILL.md b/.cursor/skills/openspec-apply-change/SKILL.md
index 70fbdb8..db4d8ce 100644
--- a/.cursor/skills/openspec-apply-change/SKILL.md
+++ b/.cursor/skills/openspec-apply-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Implement tasks from an OpenSpec change.
@@ -30,6 +30,7 @@ Implement tasks from an OpenSpec change.
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
    - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
 
 3. **Get apply instructions**
@@ -49,6 +50,8 @@ Implement tasks from an OpenSpec change.
    - If `state: "all_done"`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
+   **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
 4. **Read context files**
 
    Read every file path listed under `contextFiles` from the apply instructions output.
diff --git a/.cursor/skills/openspec-archive-change/SKILL.md b/.cursor/skills/openspec-archive-change/SKILL.md
index 12e2f70..97c3e5e 100644
--- a/.cursor/skills/openspec-archive-change/SKILL.md
+++ b/.cursor/skills/openspec-archive-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Archive a completed change in the experimental workflow.
@@ -30,8 +30,11 @@ Archive a completed change in the experimental workflow.
 
    Parse the JSON to understand:
    - `schemaName`: The workflow being used
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
    - `artifacts`: List of artifacts with their status (`done` or other)
 
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
    **If any artifacts are not `done`:**
    - Display warning listing incomplete artifacts
    - Use **AskUserQuestion tool** to confirm user wants to proceed
@@ -52,7 +55,7 @@ Archive a completed change in the experimental workflow.
 
 4. **Assess delta spec sync state**
 
-   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
 
    **If delta specs exist:**
    - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
@@ -67,19 +70,19 @@ Archive a completed change in the experimental workflow.
 
 5. **Perform the archive**
 
-   Create the archive directory if it doesn't exist:
+   Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
    ```bash
-   mkdir -p openspec/changes/archive
+   mkdir -p "<planningHome.changesDir>/archive"
    ```
 
    Generate target name using current date: `YYYY-MM-DD-<change-name>`
 
    **Check if target already exists:**
    - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
+   - If no: Move `changeRoot` to the archive directory
 
    ```bash
-   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
    ```
 
 6. **Display summary**
@@ -98,7 +101,7 @@ Archive a completed change in the experimental workflow.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
 
 All artifacts complete. All tasks complete.
diff --git a/.cursor/skills/openspec-explore/SKILL.md b/.cursor/skills/openspec-explore/SKILL.md
index 6858d3f..1e97aaa 100644
--- a/.cursor/skills/openspec-explore/SKILL.md
+++ b/.cursor/skills/openspec-explore/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
@@ -102,11 +102,10 @@ Think freely. When insights crystallize, you might offer:
 
 If the user mentions a change or you detect one is relevant:
 
-1. **Read existing artifacts for context**
-   - `openspec/changes/<name>/proposal.md`
-   - `openspec/changes/<name>/design.md`
-   - `openspec/changes/<name>/tasks.md`
-   - etc.
+1. **Resolve and read existing artifacts for context**
+   - Run `openspec status --change "<name>" --json`.
+   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
+   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
 
 2. **Reference them naturally in conversation**
    - "Your design mentions using Redis, but we just realized SQLite fits better..."
diff --git a/.cursor/skills/openspec-propose/SKILL.md b/.cursor/skills/openspec-propose/SKILL.md
index 4b7e204..9fc8513 100644
--- a/.cursor/skills/openspec-propose/SKILL.md
+++ b/.cursor/skills/openspec-propose/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Propose a new change - create the change and generate all artifacts in one step.
@@ -37,7 +37,7 @@ When ready to implement, run /opsx:apply
    ```bash
    openspec new change "<name>"
    ```
-   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+   This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
 
 3. **Get the artifact build order**
    ```bash
@@ -46,6 +46,7 @@ When ready to implement, run /opsx:apply
    Parse the JSON to get:
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
    - `artifacts`: list of all artifacts with their status and dependencies
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
 
 4. **Create artifacts in sequence until apply-ready**
 
@@ -63,10 +64,10 @@ When ready to implement, run /opsx:apply
         - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
         - `template`: The structure to use for your output file
         - `instruction`: Schema-specific guidance for this artifact type
-        - `outputPath`: Where to write the artifact
+        - `resolvedOutputPath`: Resolved path or pattern to write the artifact
         - `dependencies`: Completed artifacts to read for context
       - Read any completed dependency files for context
-      - Create the artifact file using `template` as the structure
+      - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath`
       - Apply `context` and `rules` as constraints - but do NOT copy them into the file
       - Show brief progress: "Created <artifact-id>"
 
diff --git a/.github/prompts/opsx-apply.prompt.md b/.github/prompts/opsx-apply.prompt.md
index e23ec64..cb53869 100644
--- a/.github/prompts/opsx-apply.prompt.md
+++ b/.github/prompts/opsx-apply.prompt.md
@@ -23,6 +23,7 @@ Implement tasks from an OpenSpec change.
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
    - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
 
 3. **Get apply instructions**
@@ -42,6 +43,8 @@ Implement tasks from an OpenSpec change.
    - If `state: "all_done"`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
+   **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
 4. **Read context files**
 
    Read every file path listed under `contextFiles` from the apply instructions output.
diff --git a/.github/prompts/opsx-archive.prompt.md b/.github/prompts/opsx-archive.prompt.md
index 1163776..b30dcd0 100644
--- a/.github/prompts/opsx-archive.prompt.md
+++ b/.github/prompts/opsx-archive.prompt.md
@@ -23,8 +23,11 @@ Archive a completed change in the experimental workflow.
 
    Parse the JSON to understand:
    - `schemaName`: The workflow being used
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
    - `artifacts`: List of artifacts with their status (`done` or other)
 
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
    **If any artifacts are not `done`:**
    - Display warning listing incomplete artifacts
    - Prompt user for confirmation to continue
@@ -45,7 +48,7 @@ Archive a completed change in the experimental workflow.
 
 4. **Assess delta spec sync state**
 
-   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
 
    **If delta specs exist:**
    - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
@@ -60,19 +63,19 @@ Archive a completed change in the experimental workflow.
 
 5. **Perform the archive**
 
-   Create the archive directory if it doesn't exist:
+   Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
    ```bash
-   mkdir -p openspec/changes/archive
+   mkdir -p "<planningHome.changesDir>/archive"
    ```
 
    Generate target name using current date: `YYYY-MM-DD-<change-name>`
 
    **Check if target already exists:**
    - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
+   - If no: Move `changeRoot` to the archive directory
 
    ```bash
-   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
    ```
 
 6. **Display summary**
@@ -91,7 +94,7 @@ Archive a completed change in the experimental workflow.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** ✓ Synced to main specs
 
 All artifacts complete. All tasks complete.
@@ -104,7 +107,7 @@ All artifacts complete. All tasks complete.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** No delta specs
 
 All artifacts complete. All tasks complete.
@@ -117,7 +120,7 @@ All artifacts complete. All tasks complete.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** Sync skipped (user chose to skip)
 
 **Warnings:**
@@ -134,7 +137,7 @@ Review the archive if this was not intentional.
 ## Archive Failed
 
 **Change:** <change-name>
-**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Target:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 
 Target archive directory already exists.
 
diff --git a/.github/prompts/opsx-explore.prompt.md b/.github/prompts/opsx-explore.prompt.md
index 3b674eb..32ec8d2 100644
--- a/.github/prompts/opsx-explore.prompt.md
+++ b/.github/prompts/opsx-explore.prompt.md
@@ -104,11 +104,10 @@ Think freely. When insights crystallize, you might offer:
 
 If the user mentions a change or you detect one is relevant:
 
-1. **Read existing artifacts for context**
-   - `openspec/changes/<name>/proposal.md`
-   - `openspec/changes/<name>/design.md`
-   - `openspec/changes/<name>/tasks.md`
-   - etc.
+1. **Resolve and read existing artifacts for context**
+   - Run `openspec status --change "<name>" --json`.
+   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
+   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
 
 2. **Reference them naturally in conversation**
    - "Your design mentions using Redis, but we just realized SQLite fits better..."
diff --git a/.github/prompts/opsx-propose.prompt.md b/.github/prompts/opsx-propose.prompt.md
index cf30b2a..30bd6fd 100644
--- a/.github/prompts/opsx-propose.prompt.md
+++ b/.github/prompts/opsx-propose.prompt.md
@@ -30,7 +30,7 @@ When ready to implement, run /opsx:apply
    ```bash
    openspec new change "<name>"
    ```
-   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+   This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
 
 3. **Get the artifact build order**
    ```bash
@@ -39,6 +39,7 @@ When ready to implement, run /opsx:apply
    Parse the JSON to get:
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
    - `artifacts`: list of all artifacts with their status and dependencies
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
 
 4. **Create artifacts in sequence until apply-ready**
 
@@ -56,10 +57,10 @@ When ready to implement, run /opsx:apply
         - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
         - `template`: The structure to use for your output file
         - `instruction`: Schema-specific guidance for this artifact type
-        - `outputPath`: Where to write the artifact
+        - `resolvedOutputPath`: Resolved path or pattern to write the artifact
         - `dependencies`: Completed artifacts to read for context
       - Read any completed dependency files for context
-      - Create the artifact file using `template` as the structure
+      - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath`
       - Apply `context` and `rules` as constraints - but do NOT copy them into the file
       - Show brief progress: "Created <artifact-id>"
 
diff --git a/.github/skills/openspec-apply-change/SKILL.md b/.github/skills/openspec-apply-change/SKILL.md
index 70fbdb8..db4d8ce 100644
--- a/.github/skills/openspec-apply-change/SKILL.md
+++ b/.github/skills/openspec-apply-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Implement tasks from an OpenSpec change.
@@ -30,6 +30,7 @@ Implement tasks from an OpenSpec change.
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
    - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
 
 3. **Get apply instructions**
@@ -49,6 +50,8 @@ Implement tasks from an OpenSpec change.
    - If `state: "all_done"`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
+   **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
 4. **Read context files**
 
    Read every file path listed under `contextFiles` from the apply instructions output.
diff --git a/.github/skills/openspec-archive-change/SKILL.md b/.github/skills/openspec-archive-change/SKILL.md
index 12e2f70..97c3e5e 100644
--- a/.github/skills/openspec-archive-change/SKILL.md
+++ b/.github/skills/openspec-archive-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Archive a completed change in the experimental workflow.
@@ -30,8 +30,11 @@ Archive a completed change in the experimental workflow.
 
    Parse the JSON to understand:
    - `schemaName`: The workflow being used
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
    - `artifacts`: List of artifacts with their status (`done` or other)
 
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
    **If any artifacts are not `done`:**
    - Display warning listing incomplete artifacts
    - Use **AskUserQuestion tool** to confirm user wants to proceed
@@ -52,7 +55,7 @@ Archive a completed change in the experimental workflow.
 
 4. **Assess delta spec sync state**
 
-   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
 
    **If delta specs exist:**
    - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
@@ -67,19 +70,19 @@ Archive a completed change in the experimental workflow.
 
 5. **Perform the archive**
 
-   Create the archive directory if it doesn't exist:
+   Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
    ```bash
-   mkdir -p openspec/changes/archive
+   mkdir -p "<planningHome.changesDir>/archive"
    ```
 
    Generate target name using current date: `YYYY-MM-DD-<change-name>`
 
    **Check if target already exists:**
    - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
+   - If no: Move `changeRoot` to the archive directory
 
    ```bash
-   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
    ```
 
 6. **Display summary**
@@ -98,7 +101,7 @@ Archive a completed change in the experimental workflow.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
 **Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
 
 All artifacts complete. All tasks complete.
diff --git a/.github/skills/openspec-explore/SKILL.md b/.github/skills/openspec-explore/SKILL.md
index 6858d3f..1e97aaa 100644
--- a/.github/skills/openspec-explore/SKILL.md
+++ b/.github/skills/openspec-explore/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
@@ -102,11 +102,10 @@ Think freely. When insights crystallize, you might offer:
 
 If the user mentions a change or you detect one is relevant:
 
-1. **Read existing artifacts for context**
-   - `openspec/changes/<name>/proposal.md`
-   - `openspec/changes/<name>/design.md`
-   - `openspec/changes/<name>/tasks.md`
-   - etc.
+1. **Resolve and read existing artifacts for context**
+   - Run `openspec status --change "<name>" --json`.
+   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
+   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
 
 2. **Reference them naturally in conversation**
    - "Your design mentions using Redis, but we just realized SQLite fits better..."
diff --git a/.github/skills/openspec-propose/SKILL.md b/.github/skills/openspec-propose/SKILL.md
index 4b7e204..9fc8513 100644
--- a/.github/skills/openspec-propose/SKILL.md
+++ b/.github/skills/openspec-propose/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.1"
+  generatedBy: "1.4.1"
 ---
 
 Propose a new change - create the change and generate all artifacts in one step.
@@ -37,7 +37,7 @@ When ready to implement, run /opsx:apply
    ```bash
    openspec new change "<name>"
    ```
-   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+   This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
 
 3. **Get the artifact build order**
    ```bash
@@ -46,6 +46,7 @@ When ready to implement, run /opsx:apply
    Parse the JSON to get:
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
    - `artifacts`: list of all artifacts with their status and dependencies
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
 
 4. **Create artifacts in sequence until apply-ready**
 
@@ -63,10 +64,10 @@ When ready to implement, run /opsx:apply
         - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
         - `template`: The structure to use for your output file
         - `instruction`: Schema-specific guidance for this artifact type
-        - `outputPath`: Where to write the artifact
+        - `resolvedOutputPath`: Resolved path or pattern to write the artifact
         - `dependencies`: Completed artifacts to read for context
       - Read any completed dependency files for context
-      - Create the artifact file using `template` as the structure
+      - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath`
       - Apply `context` and `rules` as constraints - but do NOT copy them into the file
       - Show brief progress: "Created <artifact-id>"
 
diff --git a/README.md b/README.md
index 34efb8a..d1ed043 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,24 @@
 
 **注：本仓库仅提供基础渲染框架，不包含任何 Live2d 模型及其接口**
 
+## Live2D Agent
+
+当前版本的核心能力是让看板娘不只“会聊天”，还可以在站长授权范围内理解当前站点、调用工具并协助访客完成一些真实操作。
+
+启用 AI 聊天后，站长可以在 `插件设置 -> AI 聊天配置` 中选择访问模式，分别控制匿名用户和登录用户是否只能对话，或同时允许使用 Agent 能力。Agent 能力不会因为旧版“公共聊天”配置自动开放，需要站长明确选择带 Agent 的访问模式。
+
+内置 Agent 能力覆盖 Halo 站点的常见访问场景：
+
+- 当前页面上下文：让模型知道访客当前在哪个页面、页面标题、路径、描述、选中文本，以及当前页面是否具备评论/留言入口。
+- Halo 内容搜索：复用 Halo 自身全文搜索能力，帮助访客查找文章、独立页面等公开内容。
+- Halo 资源导航：让模型打开后端查询得到的可信 Halo 资源，例如帮访客跳转到某篇文章、分类、标签或独立页面。
+- 评论与留言辅助：可滚动到评论区、生成评论草稿；如站长开启提交能力，则在访客确认后尝试提交评论。
+- 网络访问：允许模型通过后端读取站长白名单中的公网 URL，并内置阻止 localhost、内网、链路本地地址和未授权 Origin 的安全策略。
+
+站长还可以通过“自定义 Agent 工具 JSON”扩展站点专属能力，例如打开主题里的联系面板、展示站长最新动态、触发自定义前台事件、滚动到指定区域或调用主题注册的浏览器工具。工具声明、参数、权限和是否需要确认都由站长配置，前台脚本只能绑定执行器，不能临时把未知工具暴露给模型。
+
+Agent 的设计目标是：让看板娘能帮访客更快找到内容、理解当前页面并完成轻量站点操作，同时保持清晰的权限边界。
+
 ## 下载及使用说明
 1. 前往 [Github Release](https://github.com/LIlGG/plugin-live2d/releases/latest) 下载 jar 包
 2. 通过 Halo-2.x [安装插件](https://docs.halo.run/user-guide/plugins#%E5%AE%89%E8%A3%85%E6%8F%92%E4%BB%B6) 功能安装本插件
@@ -42,6 +60,7 @@ pnpm --dir packages/live2d dev
 - [x] 自定义看板娘接口
 - [x] 支持外部自定义 TIPS 文件，更适合你的网站
 - [x] 支持自定义工具栏
+- [x] 支持 Agent 能力，让 AI 在授权范围内搜索 Halo 内容、打开可信资源并协助访客完成站点操作
 
 ## 自定义配置
 > 此部分内容建议初步尝试过 Live2d 的用户观看。
@@ -135,6 +154,86 @@ live2d 渲染页面时将自动读取当前启用主题下的文件。
 - 触发命名空间自定义事件
 - 加载指定模型
 
+### Agent 能力
+启用 AI 聊天后，可以在 Halo 后台 `插件设置 -> Agent 能力` 配置模型可调用的站点能力。
+
+AI 聊天访问模式分为四种：
+
+- 匿名用户可对话：匿名和登录用户都能聊天，但不能使用 Agent 操作能力。
+- 匿名用户可对话和使用 Agent：匿名和登录用户都能聊天，并可使用已启用的 Agent 能力。
+- 登录用户可对话：只有登录用户能聊天，不能使用 Agent 操作能力。
+- 登录用户可对话和使用 Agent：只有登录用户能聊天，并可使用已启用的 Agent 能力。
+
+升级旧版本配置时，原“公共聊天”只会迁移到聊天模式，不会自动开放 Agent 能力。
+
+内置预设能力包括：
+
+- 当前页面上下文：读取页面标题、路径、描述和选中文本，不读取表单、Cookie 或本地存储。
+- Halo 内容搜索：使用 Halo 自身全文搜索引擎查询公开内容。
+- Halo 资源导航：仅能打开后端工具返回过的可信资源。
+- 评论能力：关闭时不暴露评论工具；辅助模式可打开评论区、读取评论状态并生成评论草稿；提交模式需要站长明确启用，并在访客确认后尝试提交评论。
+- 网络访问：通过后端读取站长白名单中的公网 URL，默认关闭；运行时会拒绝 localhost、内网、链路本地地址、未授权 Origin 和重定向访问。
+
+站长可以通过“自定义 Agent 工具 JSON”声明浏览器侧工具。第一版支持的动作类型：
+
+- `navigate`
+- `scroll-to`
+- `highlight`
+- `dispatch-event`
+- `registered`
+
+这些工具可用于扩展主题或站点专属能力，例如：
+
+- 打开自定义留言面板，并把模型生成的留言草稿交给主题处理。
+- 展示站长最新动态、公告栏或个人资料区域。
+- 跳转到主题内的特殊页面，或滚动并高亮某个内容区块。
+- 调用主题脚本注册的受控浏览器能力。
+
+示例：打开联系面板并把留言草稿交给主题处理：
+
+```json
+[
+  {
+    "name": "open_contact_form",
+    "enabled": true,
+    "description": "打开站长留言面板，并传入留言草稿",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "message": {
+          "type": "string",
+          "description": "留言草稿"
+        }
+      },
+      "required": ["message"]
+    },
+    "approval": "default",
+    "requiredAuth": "none",
+    "action": {
+      "type": "dispatch-event",
+      "event": "site:open-contact-form"
+    }
+  }
+]
+```
+
+主题或前台脚本可以为已声明的 `registered` 工具绑定执行器：
+
+```ts
+window.Live2DAI?.registerTool("show_owner_updates", async ({ input }) => {
+  window.dispatchEvent(new CustomEvent("site:show-updates", { detail: input }));
+  return { ok: true };
+});
+```
+
+运行时脚本只能绑定执行器，不能把新工具声明给模型。工具名称、描述、参数和权限必须来自插件设置。
+
+安全边界：
+
+- 不支持声明式 `eval`、任意 `fetch`、任意选择器点击或任意表单提交。
+- 外部链接需要站长 allowlist，并默认请求访客确认。
+- 工具执行结果会回传给模型，但不会直接把原始 JSON 展示给访客。
+
 ## 鸣谢
 - 本插件代码借鉴了 [live2d-widget](https://github.com/stevenjoezhang/live2d-widget) 的理念并完全重写
 - 使用了 [hitokoto](https://hitokoto.cn/) 的一言接口
diff --git a/api.jar b/api.jar
new file mode 100644
index 0000000..a4d576b
Binary files /dev/null and b/api.jar differ
diff --git a/build.gradle b/build.gradle
index 330191c..e41192b 100644
--- a/build.gradle
+++ b/build.gradle
@@ -1,12 +1,18 @@
 plugins {
     id 'java'
     id "io.freefair.lombok" version "9.2.0"
-    id "run.halo.plugin.devtools" version "0.6.2"
+    id "run.halo.plugin.devtools" version "0.8.0"
 }
 
 group 'run.halo.live2d'
 
 repositories {
+    maven {
+        url = uri('https://central.sonatype.com/repository/maven-snapshots/')
+        mavenContent {
+            snapshotsOnly()
+        }
+    }
     mavenCentral()
 }
 
@@ -16,11 +22,12 @@ configurations.runtimeClasspath {
 
 dependencies {
     implementation platform('run.halo.tools.platform:plugin:2.24.0')
-    implementation 'com.theokanning.openai-gpt3-java:api:0.17.0'
 
     compileOnly 'run.halo.app:api'
+    compileOnly 'run.halo.aifoundation:api:1.0.0-SNAPSHOT'
 
     testImplementation 'run.halo.app:api'
+    testImplementation 'run.halo.aifoundation:api:1.0.0-SNAPSHOT'
     testImplementation 'org.springframework.boot:spring-boot-starter-test'
     testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
 }
@@ -80,11 +87,10 @@ tasks.named("processResources") {
 }
 
 halo {
-    version = '2.24.2'
-    port = 8090
+    version = '2.25'
+    port = 8092
     superAdminUsername = 'admin'
     superAdminPassword = 'admin'
-    externalUrl = 'http://localhost:8090'
     debug = true
 }
 
diff --git a/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/.openspec.yaml b/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/.openspec.yaml
new file mode 100644
index 0000000..9f70866
--- /dev/null
+++ b/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-15
diff --git a/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/design.md b/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/design.md
new file mode 100644
index 0000000..a313b9c
--- /dev/null
+++ b/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/design.md
@@ -0,0 +1,80 @@
+## Context
+
+Live2D chat currently sends the frontend's message history to `/live2d/ai/chat-process`, where the plugin prepends a system prompt and then delegates generation to plugin-owned `ChatClient` implementations. The only concrete client today is an OpenAI-specific streaming client backed by plugin settings for proxy, token, base URL, and model selection.
+
+The target state is to keep the Live2D chat UX and endpoint shape stable while delegating model discovery and invocation to Halo AI 基础设施. The upstream SDK is not yet available from a published repository, so this change must integrate through the provided `api-1.0.0-SNAPSHOT.jar` and the documented `AiServices` / `AiModelService` APIs.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Route Live2D chat generation through Halo AI foundation instead of the plugin's custom OpenAI client stack.
+- Preserve the existing frontend chat contract so the widget keeps working with minimal behavioral change.
+- Reduce plugin-owned AI configuration to chat-specific controls only: enablement, anonymous access, role prompt, model selection, and frontend timing values.
+- Remove obsolete backend classes, settings, and dependencies once Halo AI integration is in place.
+
+**Non-Goals:**
+- Redesign the Live2D chat UI or change the existing streaming presentation model.
+- Add provider management, credential storage, or model provisioning inside the Live2D plugin.
+- Generalize this change into a reusable abstraction for non-chat AI features.
+
+## Decisions
+
+### Use Halo AI foundation as the only chat backend
+The backend will replace `ChatClient`-based provider dispatch with a single service path built on `AiServices.getModelService()`. The endpoint will obtain the configured Halo model name, resolve a `LanguageModel`, build a foundation `ChatRequest`, and stream foundation `ChatChunk` events back into the existing SSE response format consumed by the frontend.
+
+**Why this approach**
+- It removes duplicated provider integration code from the plugin.
+- It aligns provider credentials and model lifecycle with Halo's centralized AI management.
+- It minimizes frontend churn because the SSE endpoint can still emit the current `ChatResult` payload shape.
+
+**Alternatives considered**
+- Keep the `ChatClient` abstraction and add a Halo-backed implementation: rejected because the abstraction exists only to multiplex plugin-owned providers and would preserve unnecessary complexity.
+- Proxy raw Halo AI responses directly to the frontend: rejected because the frontend already depends on `ChatResult` chunks and changing that contract would widen the migration surface.
+
+### Keep a plugin-level model selector, but not provider credentials
+The plugin will retain a single AI-model identifier field that stores the Halo AI model resource name (for example `openai/gpt-4o`) alongside the existing persona prompt and access-control settings. Provider token, base URL, proxy, and provider enablement will move fully out of this plugin.
+
+**Why this approach**
+- Halo AI foundation still requires the caller to request a concrete model.
+- Selecting a model per plugin preserves expected plugin autonomy without reintroducing provider-specific configuration.
+- It avoids brittle "first configured model wins" behavior.
+
+**Alternatives considered**
+- Always use the first available Halo model: rejected because availability order is undefined and can change across environments.
+- Add no plugin-level model choice and wait for a Halo-wide default model API: rejected because the current SDK and documentation do not define that capability.
+
+### Depend on the local SDK jar until the upstream artifact is published
+The Gradle build will reference the provided `api-1.0.0-SNAPSHOT.jar` as a compile-time dependency and remove the old OpenAI SDK dependency that is no longer needed.
+
+**Why this approach**
+- It matches the currently available distribution mechanism.
+- It keeps the migration unblockable without inventing a separate publishing pipeline.
+
+**Alternatives considered**
+- Depend on a Maven coordinate that is not yet published: rejected because builds would not be reproducible in the current repository state.
+- Vendor copied source or decompiled classes: rejected because it would increase maintenance cost and drift from the upstream SDK.
+
+### Preserve backend-to-frontend error semantics at the plugin boundary
+The endpoint will translate Halo AI foundation failures into readable plugin responses consistent with the current chat UX: unauthorized access remains an HTTP 401, while model/plugin/provider failures stream a user-facing error message through the existing SSE contract and terminate cleanly.
+
+**Why this approach**
+- The current frontend already handles 401 and streamed error text.
+- It avoids exposing raw provider internals in the browser while still giving administrators actionable logs on the server side.
+
+## Risks / Trade-offs
+
+- **[SDK distribution friction]** Local jar dependency is less ergonomic than a published artifact → Document the dependency strategy in the change and isolate it so it can be swapped to a Maven coordinate later.
+- **[Model selection discoverability]** A free-form model name field is easier to misconfigure than a populated dropdown → Validate the field on use, surface a clear error when the model cannot be resolved, and consider a follow-up enhancement for dynamic options if Halo exposes them.
+- **[Streaming contract translation]** Halo AI chunk types may not map 1:1 to the plugin's current `[DONE]`-terminated SSE stream → Normalize chunk types in one backend adapter layer and keep the frontend contract unchanged.
+- **[Plugin dependency coupling]** Live2D chat will now require the ai-foundation plugin at runtime when AI chat is enabled → Fail fast with a clear administrative message when the dependency is missing or disabled.
+
+## Migration Plan
+
+1. Add the Halo AI SDK dependency from the provided jar and remove the obsolete OpenAI SDK usage.
+2. Replace the custom backend generation path with a Halo AI-backed service that adapts foundation chunks into existing `ChatResult` SSE events.
+3. Simplify `settings.yaml` and runtime config shaping to remove provider/proxy fields while keeping chat-specific controls.
+4. Verify the frontend works unchanged against the preserved endpoint contract, then remove dead backend classes and configuration paths.
+
+## Open Questions
+
+- Whether Halo will soon expose a canonical default chat model API; if it does, the plugin-level model name field could be simplified in a follow-up change.
diff --git a/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/proposal.md b/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/proposal.md
new file mode 100644
index 0000000..3a25613
--- /dev/null
+++ b/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/proposal.md
@@ -0,0 +1,28 @@
+## Why
+
+Live2D chat currently depends on plugin-owned AI settings, custom OpenAI client logic, and proxy/token management that duplicate capabilities Halo is beginning to provide centrally. Migrating to Halo AI 基础设施 will reduce duplicated backend code, align chat behavior with Halo-wide model management, and let administrators configure AI once instead of per plugin.
+
+## What Changes
+
+- Replace the Live2D chat backend integration with Halo AI 基础设施 instead of the plugin's custom OpenAI client pipeline.
+- Use the AI foundation SDK from the provided `api-1.0.0-SNAPSHOT.jar` until the upstream repository artifact is publicly available.
+- Keep the existing Live2D chat entry point and streaming user experience, but source model access and streaming responses from Halo AI services.
+- Simplify plugin settings so AI chat keeps only widget-specific behavior controls and persona prompt configuration.
+- **BREAKING** Remove plugin-specific provider settings such as OpenAI token/base URL/model and proxy configuration from the Live2D plugin.
+- Remove unused custom backend AI classes and dependency wiring after Halo AI integration is in place.
+
+## Capabilities
+
+### New Capabilities
+- `halo-ai-chat-integration`: Live2D chat streams replies through Halo AI foundation services while preserving the widget-facing chat API and persona behavior.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- Backend chat flow under `src/main/java/run/halo/live2d/chat/**`
+- Plugin settings schema in `src/main/resources/extensions/settings.yaml`
+- Runtime config shaping in `src/main/java/run/halo/live2d/Live2dSettingProcess.java`
+- Frontend chat client and widget integration in `packages/live2d/src/**`
+- Build dependency management in `build.gradle`
diff --git a/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/specs/halo-ai-chat-integration/spec.md b/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/specs/halo-ai-chat-integration/spec.md
new file mode 100644
index 0000000..1a0fab3
--- /dev/null
+++ b/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/specs/halo-ai-chat-integration/spec.md
@@ -0,0 +1,46 @@
+## ADDED Requirements
+
+### Requirement: Live2D chat SHALL stream replies through Halo AI foundation
+When AI chat is enabled, the Live2D backend SHALL invoke Halo AI foundation for chat generation instead of any plugin-owned provider client, while preserving the existing widget-facing streaming endpoint contract.
+
+#### Scenario: Chat requests are fulfilled by Halo AI foundation
+- **WHEN** a user sends a chat message to `/live2d/ai/chat-process`
+- **THEN** the backend MUST resolve the configured Halo AI language model through `AiServices.getModelService()`
+- **AND** it MUST submit the system prompt plus conversation history to that model
+- **AND** it MUST stream assistant text chunks back through the existing SSE response format
+
+#### Scenario: Stream completion preserves the current frontend terminator
+- **WHEN** Halo AI foundation reports a successful end of generation
+- **THEN** the backend MUST emit the plugin's existing completion marker payload for the frontend consumer
+- **AND** it MUST complete the SSE response without requiring frontend protocol changes
+
+### Requirement: Live2D AI chat settings SHALL only keep plugin-specific chat controls
+The plugin SHALL configure Live2D chat through Halo-integrated settings that keep widget-specific behavior in this plugin and remove provider-specific connection settings from the plugin schema.
+
+#### Scenario: Plugin settings retain persona and model selection
+- **WHEN** an administrator enables AI chat in the Live2D plugin settings
+- **THEN** the plugin MUST allow configuration of anonymous-access behavior, persona/system prompt, Halo AI model identifier, and frontend timing controls
+- **AND** those settings MUST be used to build chat requests and widget behavior
+
+#### Scenario: Provider-specific settings are removed from the plugin
+- **WHEN** an administrator opens the Live2D AI chat settings after this change
+- **THEN** OpenAI token, base URL, provider toggle, proxy host, and proxy port settings MUST NOT be present in the plugin configuration form
+- **AND** provider credentials and provider enablement MUST be managed through Halo AI infrastructure instead
+
+#### Scenario: Public runtime config excludes backend-only AI foundation settings
+- **WHEN** the plugin exposes public runtime configuration to the frontend
+- **THEN** it MUST continue exposing AI chat enablement and widget timing fields needed by the browser
+- **AND** it MUST NOT expose backend-only Halo model identifiers or provider configuration details to the public config payload
+
+### Requirement: Live2D chat SHALL surface Halo AI dependency failures clearly
+The Live2D chat integration SHALL translate Halo AI foundation availability and model-resolution failures into stable plugin behavior for both users and administrators.
+
+#### Scenario: Anonymous-disabled chat still enforces login
+- **WHEN** AI chat is enabled but anonymous chat is disabled and an unauthenticated user sends a message
+- **THEN** the endpoint MUST reject the request with HTTP 401
+- **AND** it MUST NOT invoke Halo AI foundation for that request
+
+#### Scenario: Missing AI foundation dependency or model configuration is reported cleanly
+- **WHEN** the ai-foundation plugin is unavailable, disabled, or the configured Halo model cannot be resolved
+- **THEN** the backend MUST log the failure for administrators
+- **AND** it MUST return a user-facing chat failure message through the existing plugin response flow instead of an unhandled server error
diff --git a/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/tasks.md b/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/tasks.md
new file mode 100644
index 0000000..5770881
--- /dev/null
+++ b/openspec/changes/archive/2026-05-15-migrate-chat-to-halo-ai/tasks.md
@@ -0,0 +1,21 @@
+## 1. Dependency and integration setup
+
+- [x] 1.1 Add the Halo AI foundation SDK from `api-1.0.0-SNAPSHOT.jar` to the Gradle build and remove the obsolete OpenAI SDK dependency.
+- [x] 1.2 Introduce a Halo AI-backed chat service path that obtains `AiModelService` via `AiServices` and resolves the configured language model.
+
+## 2. Backend chat migration
+
+- [x] 2.1 Replace the current `ChatClient`-based backend flow with a single Halo AI streaming adapter that converts foundation chunks into existing `ChatResult` SSE events.
+- [x] 2.2 Preserve current access-control behavior in `AiChatEndpoint`, including anonymous toggle handling and HTTP 401 responses for unauthenticated requests.
+- [x] 2.3 Add backend error handling for missing ai-foundation availability, disabled providers, and unknown model names so failures become readable plugin responses and server logs.
+
+## 3. Settings and runtime config cleanup
+
+- [x] 3.1 Simplify `settings.yaml` to remove OpenAI and proxy settings while adding or retaining only chat-specific controls needed after the Halo migration.
+- [x] 3.2 Update `Live2dSettingProcess` so public runtime config still exposes frontend timing fields but does not leak backend-only Halo model configuration.
+- [x] 3.3 Remove dead custom AI backend classes, configuration records, and other unused code paths after the Halo AI integration is wired.
+
+## 4. Frontend compatibility verification
+
+- [x] 4.1 Confirm the frontend chat client continues to work against the preserved `/live2d/ai/chat-process` SSE contract without protocol changes.
+- [x] 4.2 Update any frontend typing or config handling needed to stay compatible with the simplified backend settings shape.
diff --git a/openspec/changes/archive/2026-06-16-add-agent-capabilities/.openspec.yaml b/openspec/changes/archive/2026-06-16-add-agent-capabilities/.openspec.yaml
new file mode 100644
index 0000000..e767a17
--- /dev/null
+++ b/openspec/changes/archive/2026-06-16-add-agent-capabilities/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-15
diff --git a/openspec/changes/archive/2026-06-16-add-agent-capabilities/design.md b/openspec/changes/archive/2026-06-16-add-agent-capabilities/design.md
new file mode 100644
index 0000000..972decf
--- /dev/null
+++ b/openspec/changes/archive/2026-06-16-add-agent-capabilities/design.md
@@ -0,0 +1,214 @@
+## Context
+
+Live2D AI chat currently streams UI Message responses through Halo AI Foundation and renders assistant text/reasoning in the widget. It does not declare model-callable tools, execute browser tools, or expose site-owner extensibility for Agent actions.
+
+The plugin already has useful foundations:
+
+- The backend AI chat endpoint enforces AI chat enablement and anonymous-vs-login access with `aiChatBaseSetting.isAnonymous`.
+- The frontend uses `@halo-dev/ai-foundation-sdk` `Chat`, which can receive tool calls and send tool outputs or approval responses.
+- The Live2D runtime exposes a controller capable of transitions by behavior state, emotion, filter, and duration.
+- Public runtime config already separates frontend-safe settings from backend-only settings.
+- Halo API provides `SearchService`, `SearchOption`, `SearchResult`, and `HaloDocument` for full-text search over indexed public content.
+
+The new Agent capability layer must let site owners enable controlled site operations without turning the widget into an arbitrary browser automation surface.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Add an `Agent 能力` settings tab after AI chat settings.
+- Replace the single anonymous-chat boolean with a four-mode access model that distinguishes chat access from Agent access.
+- Use AI Foundation UI Message tools for both backend-executed Halo tools and browser-executed tools.
+- Let site owners configure declarative browser tools and theme-provided registered executors.
+- Provide Halo CMS preset capabilities for search, content resources, latest resources, taxonomies, pages, posts, and comments.
+- Enforce safe defaults for navigation, approvals, authentication, schemas, and side effects.
+
+**Non-Goals:**
+
+- Do not provide a Java extension point for other plugins in this change.
+- Do not expose arbitrary `fetch`, arbitrary selector clicking, arbitrary form submission, or `eval` as declarative actions.
+- Do not expose Live2D model action control as an Agent tool in this change.
+- Do not automatically submit comments or contact forms unless a site owner explicitly enables a future supported path with approval.
+- Do not make frontend runtime scripts expand the set of model-visible tools by themselves.
+
+## Decisions
+
+### Access model
+
+The existing `isAnonymous` setting will be upgraded to `accessMode`:
+
+- `anonymous_chat`: anonymous and authenticated visitors can chat, Agent tools are unavailable.
+- `anonymous_chat_agent`: anonymous and authenticated visitors can chat and use enabled Agent tools.
+- `authenticated_chat`: only authenticated visitors can chat, Agent tools are unavailable.
+- `authenticated_chat_agent`: only authenticated visitors can chat and use enabled Agent tools.
+
+For backward compatibility:
+
+- `isAnonymous=true` maps to `anonymous_chat`.
+- `isAnonymous=false` maps to `authenticated_chat`.
+
+This keeps Agent enablement opt-in during upgrades. A tool-level `requiredAuth` still applies after the global mode gate:
+
+- `none`: available to any visitor whose access mode allows Agent.
+- `authenticated`: available only to logged-in visitors whose access mode allows Agent.
+
+Unavailable tools are not declared to the model. The frontend also checks the normalized runtime config before executing any tool call that may remain in history.
+
+### Tool declaration and execution separation
+
+The backend is the source of truth for model-visible tool declarations. It reads saved settings, applies access-mode/auth filters, validates schemas, and passes enabled tools to `UIMessageChatHandlers.streamText`.
+
+Browser tools are declared on the backend without a server executor. The frontend receives the SDK tool call through `onToolCall`, executes the matching normalized browser action, then sends the result with `addToolOutput` or sends approval decisions with `addToolApprovalResponse`/rejection helpers.
+
+The model sees only:
+
+- tool name
+- description with safety/approval hints
+- input schema
+
+The model does not see execution details such as URLs, selectors, event names, or registered executor internals.
+
+### Declarative browser tools
+
+Site owners can configure `aiTools` in the `Agent 能力` tab. Each tool has a constrained name, description, execution mode, input schema, approval policy, required auth, and action.
+
+Tool names must be lower snake_case, start with a letter, be 3-64 characters, and not duplicate built-in or custom tools.
+
+The supported JSON Schema subset is intentionally small:
+
+- object root
+- properties
+- required
+- primitive field types: string, number, integer, boolean
+- enum
+- description
+- default
+- minimum/maximum
+- minLength/maxLength
+
+Unsupported schema features such as `$ref`, nested objects, arbitrary arrays, `oneOf`, `anyOf`, `allOf`, and `patternProperties` are rejected or ignored as invalid.
+
+First-version declarative action types:
+
+- `navigate`
+- `scroll-to`
+- `highlight`
+- `dispatch-event`
+- `registered`
+
+The first version will not include `set-form-values`; form behavior should be implemented through `dispatch-event` or `registered` executors because Halo themes and form plugins differ too much.
+
+### Frontend registered executors
+
+Themes or site scripts may bind an executor for a declared tool:
+
+```ts
+window.Live2DAI.registerTool("show_owner_updates", async ({ input }) => {
+  return { ok: true }
+})
+```
+
+Frontend registration only binds execution for a tool already declared in saved plugin settings or built-in capability config. It cannot add new model-visible tools, descriptions, schemas, or permissions at runtime.
+
+If a registered executor is missing, the frontend returns a structured tool failure such as `TOOL_EXECUTOR_NOT_FOUND` and shows a short user-facing status.
+
+### Approval policy
+
+Tools use a simple approval enum:
+
+- `default`
+- `never`
+- `always`
+
+Default approval is determined by action type:
+
+- Page context, scroll, highlight, trusted same-origin resource navigation: no approval by default.
+- External navigation, registered executors, dispatch events with side effects, and comment submission paths: approval by default.
+
+Approval UI belongs to the Live2D chat/widget experience, not `window.confirm`. Tool execution results are sent back to the SDK; raw JSON output is not shown directly to visitors.
+
+### Navigation model
+
+Generic `navigate_to_url` is not exposed to the model by default. Navigation is performed through specific tools or trusted resources.
+
+For declared `navigate` actions:
+
+- relative URLs and same-origin URLs are allowed.
+- external origins require an allowlist and approval.
+- `javascript:`, `mailto:`, and `tel:` are disallowed by default.
+- `_blank` requires explicit site-owner permission.
+
+For Halo resources returned from server tools, the frontend keeps a short-lived in-memory trusted resource cache. `open_halo_resource` can only navigate to a resource present in the current runtime cache. The cache is not restored from persisted chat history.
+
+On non-SPA/PJAX themes, navigation may reload the page and interrupt the current tool chain. Navigation tools should send a success tool output and a short Live2D status before calling `location.assign`. SPA/PJAX support can be added later through registered tools or a navigation mode hook.
+
+### Halo preset tools
+
+Backend-executed preset tools should use Halo backend APIs wherever possible. Browser-only actions are reserved for operations that require the visitor page.
+
+Search uses Halo `SearchService` as the primary source:
+
+- `search_halo_resources`
+- defaults to public, published, non-recycled content
+- limits result size
+- filters `includeTypes` through a site-owner allowlist
+- returns resource metadata, permalink, description, and a short excerpt, not full content
+
+Detail lookup uses a separate tool:
+
+- `get_halo_resource_detail`
+- only for trusted/current public resources
+- returns bounded content with `truncated` metadata
+- max content length is configurable with a hard upper bound
+
+Latest resources use structured resource queries rather than full-text search, because latest lists are not keyword searches:
+
+- `get_latest_halo_resources`
+- first version must support posts
+- pages and other types can be enabled where reliable adapters exist
+
+Taxonomies and pages use structured Halo content queries:
+
+- `get_categories`
+- `get_tags`
+- `get_posts_by_category`
+- `get_posts_by_tag`
+- `get_pages`
+- `search_pages` where useful
+
+Comments are a Halo preset capability with three levels:
+
+- `off`: no comment tools
+- `assist`: open comment area, read public comments where available, draft comment content
+- `submit`: includes assist and may submit comments only when site policy, authentication, approval, and Halo comment requirements allow it
+
+The default comment capability is `assist`.
+
+### Configuration UI
+
+The `Agent 能力` tab is shown after AI chat settings. It remains visible even when AI chat or Agent access is disabled, but shows a clear notice when the saved configuration will not currently affect visitors.
+
+The first version may use JSON textarea configuration for custom tools with validation and examples. A visual FormKit builder can be added later. The tab should include grouped built-in capability toggles and advanced per-tool overrides.
+
+## Risks / Trade-offs
+
+- [Risk] Tool declarations and frontend execution config diverge. → Normalize the same saved settings on backend and frontend, and reject unknown tool calls at execution time.
+- [Risk] Browser navigation reloads the page before model continuation completes. → Send tool output and short status before navigation, and treat full-page navigation as a terminal side effect.
+- [Risk] Site-owner custom JSON is difficult to configure. → Start with JSON plus examples and validation; add a visual builder later.
+- [Risk] Search results may include types that do not have stable detail adapters. → Use SearchService for result discovery, but limit detail lookup to supported public resource types.
+- [Risk] Registered executors can do arbitrary site-specific work. → Do not let them declare new tools, default them to authenticated where appropriate, and require approval by default.
+- [Risk] Comment submission interacts with auth, captcha, review, and anti-spam flows. → Default comments to assist mode and only submit through explicit enabled paths with approval and Halo validation.
+
+## Migration Plan
+
+1. Add `accessMode` while reading existing `isAnonymous` as a fallback.
+2. Keep upgraded sites in chat-only modes by default.
+3. Add Agent settings without enabling page operations unless the site owner opts in.
+4. Keep old AI chat behavior when no Agent tools are enabled.
+5. If rollback is needed, ignore `accessMode` and Agent settings; existing chat settings remain sufficient for text chat.
+
+## Open Questions
+
+- Which Halo content APIs should be used for latest posts, pages, category/tag permalinks, and comments in the first implementation pass?
+- Should the first version include a dedicated frontend approval overlay, or reuse an existing chat panel/message interaction component?
+- How much of the Agent settings validation can be enforced directly in FormKit versus runtime normalization?
diff --git a/openspec/changes/archive/2026-06-16-add-agent-capabilities/proposal.md b/openspec/changes/archive/2026-06-16-add-agent-capabilities/proposal.md
new file mode 100644
index 0000000..dff0860
--- /dev/null
+++ b/openspec/changes/archive/2026-06-16-add-agent-capabilities/proposal.md
@@ -0,0 +1,31 @@
+## Why
+
+Live2D AI chat can now use Halo AI Foundation UI Message tool calls, but the plugin only streams assistant text today. Site owners need a controlled way to let the Live2D agent operate approved site capabilities and use Halo CMS content/search primitives without hard-coding every site-specific behavior into this plugin.
+
+## What Changes
+
+- Add an Agent capabilities configuration area after AI chat settings, with access modes that separately control chat and Agent availability for anonymous and authenticated visitors.
+- Allow the backend to declare AI Foundation tools from enabled built-in capabilities and site-owner configuration.
+- Add browser-executed tools through the SDK UI tool-call flow, including trusted resource navigation, page context, declaration-based actions, and registered frontend executors.
+- Add server-executed Halo CMS preset tools for public resource search, resource detail lookup, latest resources, categories, tags, pages, posts, and comments where Halo backend APIs can provide the data.
+- Support site-owner declarative tools with constrained JSON Schema inputs, approval policy, auth requirements, and safe browser action types.
+- Add frontend registration for site/theme executors without allowing runtime scripts to expand the model-visible tool declarations.
+- Add approval and safety behavior for side-effectful tools, external navigation, comments, and registered actions.
+
+## Capabilities
+
+### New Capabilities
+- `agent-capability-runtime`: Declares, filters, approves, and executes Agent tools across backend and browser runtimes.
+- `halo-agent-presets`: Provides Halo CMS preset search, navigation resources, latest content, taxonomy, pages, and comment assistance tools.
+
+### Modified Capabilities
+- `halo-ai-chat-integration`: Upgrade AI chat access settings and streaming behavior to include UI Message tool declarations, tool-call continuation, and Agent availability boundaries.
+- `live2d-public-runtime-config`: Expose frontend-safe Agent runtime configuration needed to execute browser tools while keeping model declarations and backend-only settings controlled by the server.
+
+## Impact
+
+- Backend chat endpoint and service will need to resolve access mode, authentication state, enabled Agent tools, Halo search/resource tools, and UI Message tool definitions.
+- Frontend chat API will need to wire SDK `onToolCall`, tool output, approval response, trusted resource cache, and browser action execution.
+- Settings schema will gain an `Agent 能力` tab and migrate the current anonymous-chat boolean into a four-mode access model with backward compatibility.
+- Public runtime config will include only safe browser execution metadata, not model identifiers, provider credentials, or arbitrary executable code.
+- Halo SearchService and content/comment extension APIs may be used for server-side preset tools.
diff --git a/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/agent-capability-runtime/spec.md b/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/agent-capability-runtime/spec.md
new file mode 100644
index 0000000..b28f071
--- /dev/null
+++ b/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/agent-capability-runtime/spec.md
@@ -0,0 +1,113 @@
+## ADDED Requirements
+
+### Requirement: Agent access modes SHALL control chat and tool availability
+The plugin SHALL use a four-mode AI access model to control whether anonymous and authenticated visitors can chat and whether Agent tools are available.
+
+#### Scenario: Anonymous chat without Agent
+- **WHEN** the access mode is `anonymous_chat`
+- **THEN** anonymous visitors MUST be allowed to send chat messages
+- **AND** authenticated visitors MUST be allowed to send chat messages
+- **AND** no Agent tools MUST be declared to the model
+
+#### Scenario: Anonymous chat with Agent
+- **WHEN** the access mode is `anonymous_chat_agent`
+- **THEN** anonymous visitors MUST be allowed to chat and use Agent tools that do not require authentication
+- **AND** authenticated visitors MUST be allowed to chat and use all enabled Agent tools they are authorized to use
+
+#### Scenario: Authenticated chat without Agent
+- **WHEN** the access mode is `authenticated_chat`
+- **THEN** anonymous visitors MUST be rejected before invoking the model
+- **AND** authenticated visitors MUST be allowed to chat
+- **AND** no Agent tools MUST be declared to the model
+
+#### Scenario: Authenticated chat with Agent
+- **WHEN** the access mode is `authenticated_chat_agent`
+- **THEN** anonymous visitors MUST be rejected before invoking the model
+- **AND** authenticated visitors MUST be allowed to chat and use enabled Agent tools
+
+### Requirement: Tool declarations SHALL be generated from saved settings and runtime permissions
+The backend SHALL be the source of truth for model-visible Agent tool declarations.
+
+#### Scenario: Backend declares only currently available tools
+- **WHEN** a chat request is accepted
+- **THEN** the backend MUST normalize enabled built-in and custom Agent tools from saved settings
+- **AND** it MUST filter tools by access mode, authentication state, enabled status, required auth, and schema validity
+- **AND** it MUST pass only the remaining tool definitions to Halo AI Foundation
+
+#### Scenario: Unavailable tools are hidden from the model
+- **WHEN** a tool is disabled, invalid, requires authentication for an anonymous visitor, or Agent access is not enabled
+- **THEN** the backend MUST NOT include that tool in the request tool definitions
+
+#### Scenario: Execution details are not model-visible
+- **WHEN** the backend builds a tool definition
+- **THEN** the tool definition MUST include the tool name, description, and input schema
+- **AND** it MUST NOT expose browser action URLs, selectors, event names, registered executor internals, or other execution-only metadata to the model
+
+### Requirement: Browser tools SHALL execute through the SDK UI tool flow
+Browser-executed Agent tools SHALL be handled by the frontend using the AI Foundation SDK UI tool-call workflow.
+
+#### Scenario: Frontend executes browser tool call
+- **WHEN** the SDK `Chat` receives a browser tool call through `onToolCall`
+- **THEN** the frontend MUST resolve the tool against normalized public Agent runtime config
+- **AND** it MUST execute the configured browser action only if the tool is allowed
+- **AND** it MUST send a structured tool result with `addToolOutput`
+
+#### Scenario: Frontend rejects unknown or forbidden tool call
+- **WHEN** a browser tool call is not present in the normalized runtime config or is forbidden for the current visitor
+- **THEN** the frontend MUST NOT execute the action
+- **AND** it MUST return a structured failure result to the SDK tool flow
+
+#### Scenario: Missing registered executor reports failure
+- **WHEN** a declared `registered` browser tool is called but no matching frontend executor is registered
+- **THEN** the frontend MUST return a structured `TOOL_EXECUTOR_NOT_FOUND` failure
+- **AND** it MUST show a short visitor-facing status instead of failing silently
+
+### Requirement: Site owners SHALL configure declarative browser tools safely
+The plugin SHALL support site-owner custom Agent tools with constrained names, schemas, approvals, auth requirements, and browser actions.
+
+#### Scenario: Custom tool names are constrained
+- **WHEN** a site owner configures a custom Agent tool
+- **THEN** the tool name MUST be lower snake_case, start with a letter, be 3 to 64 characters long, and not duplicate a built-in or custom tool name
+
+#### Scenario: Custom tool schemas use a constrained subset
+- **WHEN** a custom Agent tool defines an input schema
+- **THEN** the plugin MUST accept only the supported JSON Schema subset for object inputs and primitive properties
+- **AND** it MUST treat unsupported schema constructs as invalid for Agent declaration
+
+#### Scenario: Custom tool action types are limited
+- **WHEN** a custom Agent tool is normalized
+- **THEN** only `navigate`, `scroll-to`, `highlight`, `dispatch-event`, and `registered` actions MUST be accepted
+- **AND** arbitrary fetch, arbitrary JavaScript execution, arbitrary selector clicking, and arbitrary form submission MUST NOT be accepted as declarative actions
+
+### Requirement: Approval policy SHALL guard side-effectful Agent tools
+The plugin SHALL apply approval rules before executing Agent tools that can create side effects or surprise the visitor.
+
+#### Scenario: Tool requests visitor approval
+- **WHEN** a tool policy resolves to approval required
+- **THEN** the frontend MUST present an approval UI in the Live2D chat/widget experience
+- **AND** it MUST continue, reject, or report the tool call through the SDK approval workflow based on the visitor response
+
+#### Scenario: Default approval follows action risk
+- **WHEN** a tool uses the default approval policy
+- **THEN** low-risk page context, trusted same-origin navigation, scroll, and highlight actions MUST execute without approval
+- **AND** external navigation, registered executors, comment submission, and configured side-effectful actions MUST require approval
+
+### Requirement: Navigation SHALL be constrained to declared actions or trusted resources
+The plugin SHALL avoid exposing unrestricted URL navigation to the model.
+
+#### Scenario: Declared navigation validates destination
+- **WHEN** a `navigate` action is executed
+- **THEN** relative URLs and same-origin URLs MUST be allowed
+- **AND** external origins MUST require both allowlist membership and approval
+- **AND** unsafe protocols MUST be rejected by default
+
+#### Scenario: Trusted resource navigation uses a short-lived cache
+- **WHEN** a backend tool returns Halo resources with permalinks
+- **THEN** the frontend MUST store those resources in a current-page in-memory trusted resource cache
+- **AND** resource navigation MUST only open resources that are present in that cache
+- **AND** the cache MUST NOT be restored from persisted chat history after page reload
+
+#### Scenario: Full-page navigation may terminate continuation
+- **WHEN** a navigation action will reload the page
+- **THEN** the frontend MUST send a success tool result and short Live2D status before navigating
+- **AND** it MUST NOT require the same model turn to continue after the page unloads
diff --git a/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/halo-agent-presets/spec.md b/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/halo-agent-presets/spec.md
new file mode 100644
index 0000000..52d711e
--- /dev/null
+++ b/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/halo-agent-presets/spec.md
@@ -0,0 +1,85 @@
+## ADDED Requirements
+
+### Requirement: Halo search tool SHALL use Halo full-text search
+The plugin SHALL provide a server-executed Agent tool that searches public Halo resources through Halo SearchService.
+
+#### Scenario: Search returns public trusted resources
+- **WHEN** the model calls `search_halo_resources` with a keyword
+- **THEN** the backend MUST call Halo `SearchService` with that keyword
+- **AND** it MUST request public, published, non-recycled content by default
+- **AND** it MUST return bounded resource metadata suitable for model selection and frontend trusted navigation
+
+#### Scenario: Search filters allowed resource types
+- **WHEN** the model provides `includeTypes`
+- **THEN** the backend MUST intersect the requested types with the site-owner configured type allowlist
+- **AND** it MUST NOT search or return types outside the allowlist
+
+#### Scenario: Search result omits full content
+- **WHEN** the backend returns search results to the model
+- **THEN** each resource MUST include title, type, metadata name, permalink, description or excerpt where available
+- **AND** it MUST NOT include the full document content
+
+### Requirement: Halo resource detail tool SHALL return bounded public content
+The plugin SHALL provide a server-executed Agent tool for reading limited details from trusted or current public Halo resources.
+
+#### Scenario: Detail lookup enforces public resource constraints
+- **WHEN** the model calls `get_halo_resource_detail`
+- **THEN** the backend MUST only return details for public, published, non-recycled resources that are supported by the plugin
+- **AND** it MUST reject or fail gracefully for unsupported, private, recycled, or unpublished resources
+
+#### Scenario: Detail content is length limited
+- **WHEN** the backend returns resource detail content
+- **THEN** the content MUST be capped by the configured maximum and hard upper bound
+- **AND** the result MUST indicate whether content was truncated
+
+### Requirement: Halo latest resources SHALL be exposed through backend resource queries
+The plugin SHALL provide a server-executed Agent tool for listing recent public Halo resources.
+
+#### Scenario: Latest resources returns posts at minimum
+- **WHEN** the model calls `get_latest_halo_resources`
+- **THEN** the backend MUST return recent public posts at minimum
+- **AND** it MUST include trusted resource metadata and permalinks for frontend navigation
+
+#### Scenario: Latest resources respects type configuration
+- **WHEN** the site owner configures additional supported latest resource types
+- **THEN** the backend MUST include only supported and allowed public types in the latest resource result
+
+### Requirement: Halo taxonomy and page tools SHALL use structured backend queries
+The plugin SHALL provide server-executed tools for categories, tags, pages, and resource lists associated with taxonomies.
+
+#### Scenario: Categories and tags return navigable resources
+- **WHEN** the model requests categories or tags
+- **THEN** the backend MUST return structured public taxonomy resources with names and permalinks where available
+- **AND** those resources MUST be eligible for trusted frontend navigation
+
+#### Scenario: Posts by taxonomy return public post resources
+- **WHEN** the model requests posts by a category or tag
+- **THEN** the backend MUST return only public, published, non-recycled posts in that taxonomy
+- **AND** it MUST include bounded metadata for model responses and frontend navigation
+
+#### Scenario: Pages are searchable and navigable
+- **WHEN** the model requests public pages or searches pages
+- **THEN** the backend MUST return public page resources with titles and permalinks
+- **AND** those resources MUST be eligible for trusted frontend navigation
+
+### Requirement: Halo comment capability SHALL support configurable assistance levels
+The plugin SHALL provide Halo comment Agent capabilities according to the site owner's selected comment level.
+
+#### Scenario: Comment capability disabled
+- **WHEN** the comment capability is `off`
+- **THEN** no comment tools MUST be declared to the model
+
+#### Scenario: Comment assist capability
+- **WHEN** the comment capability is `assist`
+- **THEN** the plugin MAY declare tools to open the comment area, read public comments where available, and draft comment content
+- **AND** it MUST NOT submit comments automatically
+
+#### Scenario: Comment submit capability
+- **WHEN** the comment capability is `submit`
+- **THEN** the plugin MAY declare a comment submission tool only when the site policy supports it
+- **AND** each submission MUST require visitor approval
+- **AND** the tool MUST respect Halo comment authentication, captcha, moderation, and validation requirements
+
+#### Scenario: Comment flow requires visitor completion
+- **WHEN** a required comment precondition such as login, captcha, profile fields, or moderation cannot be satisfied by the tool
+- **THEN** the tool MUST return a structured result telling the model that the visitor must complete the site comment flow manually
diff --git a/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/halo-ai-chat-integration/spec.md b/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/halo-ai-chat-integration/spec.md
new file mode 100644
index 0000000..c6d45dd
--- /dev/null
+++ b/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/halo-ai-chat-integration/spec.md
@@ -0,0 +1,68 @@
+## MODIFIED Requirements
+
+### Requirement: Live2D chat SHALL stream replies through Halo AI foundation
+When AI chat is enabled, the Live2D backend SHALL invoke Halo AI foundation for chat generation, UI Message streaming, and enabled Agent tool declarations instead of any plugin-owned provider client, while preserving the widget-facing streaming endpoint contract.
+
+#### Scenario: Chat requests are fulfilled by Halo AI foundation
+- **WHEN** a user sends a chat message to `/live2d/ai/chat-process`
+- **THEN** the backend MUST resolve the configured Halo AI language model through Halo AI foundation
+- **AND** it MUST submit the system prompt plus conversation history to that model
+- **AND** it MUST stream assistant UI Message chunks back through the plugin SSE response flow
+
+#### Scenario: Stream completion preserves the current frontend terminator
+- **WHEN** Halo AI foundation reports a successful end of generation
+- **THEN** the backend MUST emit the Halo UI Message stream done marker for the frontend consumer
+- **AND** it MUST complete the SSE response without requiring non-SDK frontend parsing
+
+#### Scenario: Agent-enabled chat declares available tools
+- **WHEN** AI chat is enabled and the current access mode allows Agent capabilities for the visitor
+- **THEN** the backend MUST pass the currently available Agent tool definitions to Halo AI foundation
+- **AND** browser-executed tools MUST be declared without server executors
+- **AND** server-executed Halo preset tools MUST include executors
+
+### Requirement: Live2D AI chat settings SHALL only keep plugin-specific chat controls
+The plugin SHALL configure Live2D chat through Halo-integrated settings that keep widget-specific behavior in this plugin and remove provider-specific connection settings from the plugin schema.
+
+#### Scenario: Plugin settings retain persona, access mode, and model selection
+- **WHEN** an administrator enables AI chat in the Live2D plugin settings
+- **THEN** the plugin MUST allow configuration of AI access mode, persona/system prompt, Halo AI model identifier, and frontend timing controls
+- **AND** those settings MUST be used to build chat requests and widget behavior
+
+#### Scenario: Legacy anonymous setting maps to chat-only access mode
+- **WHEN** existing settings contain `isAnonymous=true` and no access mode
+- **THEN** the plugin MUST treat the setting as `anonymous_chat`
+- **AND** it MUST NOT enable Agent capabilities implicitly
+
+#### Scenario: Legacy authenticated setting maps to chat-only access mode
+- **WHEN** existing settings contain `isAnonymous=false` and no access mode
+- **THEN** the plugin MUST treat the setting as `authenticated_chat`
+- **AND** it MUST NOT enable Agent capabilities implicitly
+
+#### Scenario: Provider-specific settings are removed from the plugin
+- **WHEN** an administrator opens the Live2D AI chat settings after this change
+- **THEN** OpenAI token, base URL, provider toggle, proxy host, and proxy port settings MUST NOT be present in the plugin configuration form
+- **AND** provider credentials and provider enablement MUST be managed through Halo AI infrastructure instead
+
+#### Scenario: Public runtime config excludes backend-only AI foundation settings
+- **WHEN** the plugin exposes public runtime configuration to the frontend
+- **THEN** it MUST continue exposing AI chat enablement and widget timing fields needed by the browser
+- **AND** it MUST NOT expose backend-only Halo model identifiers or provider configuration details to the public config payload
+
+### Requirement: Live2D chat SHALL surface Halo AI dependency failures clearly
+The Live2D chat integration SHALL translate Halo AI foundation availability, model-resolution failures, and Agent access failures into stable plugin behavior for both users and administrators.
+
+#### Scenario: Authenticated-only chat still enforces login
+- **WHEN** AI chat is enabled but the access mode requires authentication and an unauthenticated user sends a message
+- **THEN** the endpoint MUST reject the request with HTTP 401
+- **AND** it MUST NOT invoke Halo AI foundation for that request
+
+#### Scenario: Agent-disabled chat does not declare tools
+- **WHEN** AI chat is enabled but the access mode does not allow Agent capabilities for the visitor
+- **THEN** the backend MUST still allow chat according to the access mode
+- **AND** it MUST NOT declare any Agent tools to Halo AI foundation
+- **AND** the system prompt MUST avoid promising direct site operations
+
+#### Scenario: Missing AI foundation dependency or model configuration is reported cleanly
+- **WHEN** the ai-foundation plugin is unavailable, disabled, or the configured Halo model cannot be resolved
+- **THEN** the backend MUST log the failure for administrators
+- **AND** it MUST return a user-facing chat failure message through the existing plugin response flow instead of an unhandled server error
diff --git a/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/live2d-public-runtime-config/spec.md b/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/live2d-public-runtime-config/spec.md
new file mode 100644
index 0000000..d93b829
--- /dev/null
+++ b/openspec/changes/archive/2026-06-16-add-agent-capabilities/specs/live2d-public-runtime-config/spec.md
@@ -0,0 +1,37 @@
+## MODIFIED Requirements
+
+### Requirement: Backend SHALL publish a frontend-safe Live2D runtime config payload
+The plugin backend SHALL publish a dedicated public config payload for the Live2D frontend instead of exposing a broad merged settings object directly to inline initialization code.
+
+#### Scenario: Public payload contains only frontend-safe runtime fields
+- **WHEN** the backend prepares Live2D configuration for page rendering
+- **THEN** it MUST map settings into a dedicated public payload that includes only fields required by the frontend runtime
+- **AND** backend-only or sensitive settings MUST be excluded from that payload by construction
+
+#### Scenario: Public payload remains compatible with the modern runtime
+- **WHEN** the frontend bootstrap reads the public config payload
+- **THEN** it MUST receive the fields needed to preserve current widget behavior, including runtime toggles, tips sources, model defaults, AI-chat runtime timings, and declarative custom tool definitions when configured
+- **AND** it MUST not require the backend to expose raw settings groups that are not part of the frontend contract
+
+#### Scenario: Public payload includes safe Agent browser execution metadata
+- **WHEN** Agent capabilities are configured
+- **THEN** the public payload MUST include only normalized browser execution metadata needed by the frontend to execute allowed browser tools
+- **AND** it MUST exclude backend-only model identifiers, provider configuration, server executor details, and invalid tool definitions
+
+#### Scenario: Public payload cannot expand model-visible tools
+- **WHEN** frontend scripts register Agent tool executors at runtime
+- **THEN** those registrations MUST only bind executors for tools already present in the normalized public Agent runtime config
+- **AND** they MUST NOT create additional model-visible tool declarations
+
+### Requirement: Halo bootstrap SHALL deliver config separately from execution logic
+The plugin SHALL provide the runtime config payload in a transport that is separate from the frontend execution bundle so configuration and code loading can evolve independently.
+
+#### Scenario: Config is embedded without rebuilding executable inline logic
+- **WHEN** a Halo page is rendered with the Live2D plugin enabled
+- **THEN** the backend MUST emit the public config payload in a machine-readable form that the frontend bundle can read at startup
+- **AND** the backend MUST not need to serialize a broad JavaScript object directly into inline runtime initialization code
+
+#### Scenario: Development and production share the same config contract
+- **WHEN** the frontend is loaded from packaged assets or from a dev server
+- **THEN** both startup modes MUST read the same public config payload shape
+- **AND** environment-specific bootstrap differences MUST not require a second config format
diff --git a/openspec/changes/archive/2026-06-16-add-agent-capabilities/tasks.md b/openspec/changes/archive/2026-06-16-add-agent-capabilities/tasks.md
new file mode 100644
index 0000000..fc3c389
--- /dev/null
+++ b/openspec/changes/archive/2026-06-16-add-agent-capabilities/tasks.md
@@ -0,0 +1,63 @@
+## 1. Settings and Configuration Model
+
+- [x] 1.1 Add Agent access mode types and map legacy `isAnonymous` values to chat-only access modes.
+- [x] 1.2 Add Agent capability settings records for built-in capabilities, custom tools, security policy, approval policy, comment level, and search type allowlist.
+- [x] 1.3 Add backend normalization for custom Agent tool names, enabled status, required auth, approval policy, action type, and supported JSON Schema subset.
+- [x] 1.4 Add frontend normalization types for the public Agent runtime config.
+- [x] 1.5 Update public setting processing so only frontend-safe Agent browser execution metadata is exposed.
+- [x] 1.6 Add the `Agent 能力` settings tab after AI chat settings with access-mode guidance and JSON custom-tool configuration.
+
+## 2. Backend Tool Declaration Runtime
+
+- [x] 2.1 Add an Agent tool registry/service that builds tool definitions from normalized built-in and custom settings.
+- [x] 2.2 Filter tool definitions by access mode, authentication state, enabled status, required auth, and schema validity.
+- [x] 2.3 Update AI chat request handling to resolve access mode and pass available tools into `UIMessageChatHandlers.streamText`.
+- [x] 2.4 Add system prompt capability/boundary text for Agent-enabled and Agent-disabled modes.
+- [x] 2.5 Ensure browser-executed tools are declared without executors and server-executed Halo preset tools include executors.
+- [x] 2.6 Add tests for access-mode migration, anonymous/authenticated filtering, disabled Agent mode, and invalid custom tool rejection.
+
+## 3. Halo Preset Server Tools
+
+- [x] 3.1 Implement `search_halo_resources` using Halo `SearchService` with public/published/non-recycled defaults and type allowlist filtering.
+- [x] 3.2 Implement bounded search result mapping with resource IDs, types, titles, descriptions/excerpts, metadata names, and permalinks.
+- [x] 3.3 Implement `get_halo_resource_detail` for supported public resources with configurable content length and truncation metadata.
+- [x] 3.4 Implement `get_latest_halo_resources` with stable public post support.
+- [x] 3.5 Implement category and tag tools for listing taxonomies and listing public posts by taxonomy.
+- [x] 3.6 Implement page tools for listing/searching public single pages and returning trusted resource metadata.
+- [x] 3.7 Implement comment capability levels `off`, `assist`, and `submit` with safe defaults and structured failure for unmet auth/captcha/site-flow requirements.
+- [x] 3.8 Add backend tests for Halo preset tool outputs, filtering, and failure cases.
+
+## 4. Frontend Agent Tool Runtime
+
+- [x] 4.1 Wire SDK `Chat` `onToolCall`, tool output, approval response, and rejection handling in the Live2D chat API.
+- [x] 4.2 Add a browser tool executor registry for built-in actions, declarative tools, and site-registered executors.
+- [x] 4.3 Expose `window.Live2DAI.registerTool(name, executor)` without allowing runtime scripts to declare new model-visible tools.
+- [x] 4.4 Implement short-lived trusted resource cache and `open_halo_resource` navigation.
+- [x] 4.5 Implement safe declarative actions: `navigate`, `scroll-to`, `highlight`, `dispatch-event`, and `registered`.
+- [x] 4.6 Add navigation behavior that sends tool output and visitor status before full-page navigation.
+- [x] 4.7 Add structured failure results and visitor-facing status messages for unknown, forbidden, invalid, and missing-executor tools.
+- [x] 4.8 Add frontend tests for tool execution, trusted navigation, registered executor binding, and failure handling.
+
+## 5. Live2D Action Execution
+
+- [x] 5.1 Remove Live2D action execution from Agent capabilities.
+- [x] 5.2 Keep the Live2D runtime controller available for native widget behavior only.
+- [x] 5.3 Remove site-owner action alias configuration from Agent settings.
+- [x] 5.4 Reject custom declarative Agent actions that try to use `perform-live2d-action`.
+- [x] 5.5 Remove Agent runtime tests that expected model-controlled Live2D transitions.
+
+## 6. Approval and User Experience
+
+- [x] 6.1 Add approval policy resolution for default, never, and always modes.
+- [x] 6.2 Add Live2D-side approval UI for tool calls that require visitor confirmation.
+- [x] 6.3 Add default short status messages for tool pending, success, and error states.
+- [x] 6.4 Ensure raw tool output JSON is returned to the model but not directly rendered as visitor chat text.
+- [x] 6.5 Add tests for approval accept, approval reject, and side-effectful default approval behavior.
+
+## 7. Validation and Documentation
+
+- [x] 7.1 Update README or admin documentation for access modes, Agent capability groups, custom tools, registered executors, and safety boundaries.
+- [x] 7.2 Add examples for common Halo preset navigation/search and custom dispatch-event/registered tools.
+- [x] 7.3 Run backend tests and frontend build/type checks.
+- [ ] 7.4 Manually verify anonymous chat-only, anonymous chat-agent, authenticated chat-only, and authenticated chat-agent behavior.
+- [ ] 7.5 Manually verify a full-page navigation theme flow and a no-reload registered navigation flow.
diff --git a/openspec/config.yaml b/openspec/config.yaml
new file mode 100644
index 0000000..392946c
--- /dev/null
+++ b/openspec/config.yaml
@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours
diff --git a/openspec/specs/agent-capability-runtime/spec.md b/openspec/specs/agent-capability-runtime/spec.md
new file mode 100644
index 0000000..4ec1aa8
--- /dev/null
+++ b/openspec/specs/agent-capability-runtime/spec.md
@@ -0,0 +1,118 @@
+# agent-capability-runtime Specification
+
+## Purpose
+Define how Live2D Agent access, browser tool execution, custom tools, approvals, and constrained navigation work.
+
+## Requirements
+
+### Requirement: Agent access modes SHALL control chat and tool availability
+The plugin SHALL use a four-mode AI access model to control whether anonymous and authenticated visitors can chat and whether Agent tools are available.
+
+#### Scenario: Anonymous chat without Agent
+- **WHEN** the access mode is `anonymous_chat`
+- **THEN** anonymous visitors MUST be allowed to send chat messages
+- **AND** authenticated visitors MUST be allowed to send chat messages
+- **AND** no Agent tools MUST be declared to the model
+
+#### Scenario: Anonymous chat with Agent
+- **WHEN** the access mode is `anonymous_chat_agent`
+- **THEN** anonymous visitors MUST be allowed to chat and use Agent tools that do not require authentication
+- **AND** authenticated visitors MUST be allowed to chat and use all enabled Agent tools they are authorized to use
+
+#### Scenario: Authenticated chat without Agent
+- **WHEN** the access mode is `authenticated_chat`
+- **THEN** anonymous visitors MUST be rejected before invoking the model
+- **AND** authenticated visitors MUST be allowed to chat
+- **AND** no Agent tools MUST be declared to the model
+
+#### Scenario: Authenticated chat with Agent
+- **WHEN** the access mode is `authenticated_chat_agent`
+- **THEN** anonymous visitors MUST be rejected before invoking the model
+- **AND** authenticated visitors MUST be allowed to chat and use enabled Agent tools
+
+### Requirement: Tool declarations SHALL be generated from saved settings and runtime permissions
+The backend SHALL be the source of truth for model-visible Agent tool declarations.
+
+#### Scenario: Backend declares only currently available tools
+- **WHEN** a chat request is accepted
+- **THEN** the backend MUST normalize enabled built-in and custom Agent tools from saved settings
+- **AND** it MUST filter tools by access mode, authentication state, enabled status, required auth, and schema validity
+- **AND** it MUST pass only the remaining tool definitions to Halo AI Foundation
+
+#### Scenario: Unavailable tools are hidden from the model
+- **WHEN** a tool is disabled, invalid, requires authentication for an anonymous visitor, or Agent access is not enabled
+- **THEN** the backend MUST NOT include that tool in the request tool definitions
+
+#### Scenario: Execution details are not model-visible
+- **WHEN** the backend builds a tool definition
+- **THEN** the tool definition MUST include the tool name, description, and input schema
+- **AND** it MUST NOT expose browser action URLs, selectors, event names, registered executor internals, or other execution-only metadata to the model
+
+### Requirement: Browser tools SHALL execute through the SDK UI tool flow
+Browser-executed Agent tools SHALL be handled by the frontend using the AI Foundation SDK UI tool-call workflow.
+
+#### Scenario: Frontend executes browser tool call
+- **WHEN** the SDK `Chat` receives a browser tool call through `onToolCall`
+- **THEN** the frontend MUST resolve the tool against normalized public Agent runtime config
+- **AND** it MUST execute the configured browser action only if the tool is allowed
+- **AND** it MUST send a structured tool result with `addToolOutput`
+
+#### Scenario: Frontend rejects unknown or forbidden tool call
+- **WHEN** a browser tool call is not present in the normalized runtime config or is forbidden for the current visitor
+- **THEN** the frontend MUST NOT execute the action
+- **AND** it MUST return a structured failure result to the SDK tool flow
+
+#### Scenario: Missing registered executor reports failure
+- **WHEN** a declared `registered` browser tool is called but no matching frontend executor is registered
+- **THEN** the frontend MUST return a structured `TOOL_EXECUTOR_NOT_FOUND` failure
+- **AND** it MUST show a short visitor-facing status instead of failing silently
+
+### Requirement: Site owners SHALL configure declarative browser tools safely
+The plugin SHALL support site-owner custom Agent tools with constrained names, schemas, approvals, auth requirements, and browser actions.
+
+#### Scenario: Custom tool names are constrained
+- **WHEN** a site owner configures a custom Agent tool
+- **THEN** the tool name MUST be lower snake_case, start with a letter, be 3 to 64 characters long, and not duplicate a built-in or custom tool name
+
+#### Scenario: Custom tool schemas use a constrained subset
+- **WHEN** a custom Agent tool defines an input schema
+- **THEN** the plugin MUST accept only the supported JSON Schema subset for object inputs and primitive properties
+- **AND** it MUST treat unsupported schema constructs as invalid for Agent declaration
+
+#### Scenario: Custom tool action types are limited
+- **WHEN** a custom Agent tool is normalized
+- **THEN** only `navigate`, `scroll-to`, `highlight`, `dispatch-event`, and `registered` actions MUST be accepted
+- **AND** arbitrary fetch, arbitrary JavaScript execution, arbitrary selector clicking, and arbitrary form submission MUST NOT be accepted as declarative actions
+
+### Requirement: Approval policy SHALL guard side-effectful Agent tools
+The plugin SHALL apply approval rules before executing Agent tools that can create side effects or surprise the visitor.
+
+#### Scenario: Tool requests visitor approval
+- **WHEN** a tool policy resolves to approval required
+- **THEN** the frontend MUST present an approval UI in the Live2D chat/widget experience
+- **AND** it MUST continue, reject, or report the tool call through the SDK approval workflow based on the visitor response
+
+#### Scenario: Default approval follows action risk
+- **WHEN** a tool uses the default approval policy
+- **THEN** low-risk page context, trusted same-origin navigation, scroll, and highlight actions MUST execute without approval
+- **AND** external navigation, registered executors, comment submission, and configured side-effectful actions MUST require approval
+
+### Requirement: Navigation SHALL be constrained to declared actions or trusted resources
+The plugin SHALL avoid exposing unrestricted URL navigation to the model.
+
+#### Scenario: Declared navigation validates destination
+- **WHEN** a `navigate` action is executed
+- **THEN** relative URLs and same-origin URLs MUST be allowed
+- **AND** external origins MUST require both allowlist membership and approval
+- **AND** unsafe protocols MUST be rejected by default
+
+#### Scenario: Trusted resource navigation uses a short-lived cache
+- **WHEN** a backend tool returns Halo resources with permalinks
+- **THEN** the frontend MUST store those resources in a current-page in-memory trusted resource cache
+- **AND** resource navigation MUST only open resources that are present in that cache
+- **AND** the cache MUST NOT be restored from persisted chat history after page reload
+
+#### Scenario: Full-page navigation may terminate continuation
+- **WHEN** a navigation action will reload the page
+- **THEN** the frontend MUST send a success tool result and short Live2D status before navigating
+- **AND** it MUST NOT require the same model turn to continue after the page unloads
diff --git a/openspec/specs/halo-agent-presets/spec.md b/openspec/specs/halo-agent-presets/spec.md
new file mode 100644
index 0000000..4435064
--- /dev/null
+++ b/openspec/specs/halo-agent-presets/spec.md
@@ -0,0 +1,90 @@
+# halo-agent-presets Specification
+
+## Purpose
+Define built-in Halo server-side Agent tools for public resource search, resource detail, latest content, taxonomy navigation, pages, and comments.
+
+## Requirements
+
+### Requirement: Halo search tool SHALL use Halo full-text search
+The plugin SHALL provide a server-executed Agent tool that searches public Halo resources through Halo SearchService.
+
+#### Scenario: Search returns public trusted resources
+- **WHEN** the model calls `search_halo_resources` with a keyword
+- **THEN** the backend MUST call Halo `SearchService` with that keyword
+- **AND** it MUST request public, published, non-recycled content by default
+- **AND** it MUST return bounded resource metadata suitable for model selection and frontend trusted navigation
+
+#### Scenario: Search filters allowed resource types
+- **WHEN** the model provides `includeTypes`
+- **THEN** the backend MUST intersect the requested types with the site-owner configured type allowlist
+- **AND** it MUST NOT search or return types outside the allowlist
+
+#### Scenario: Search result omits full content
+- **WHEN** the backend returns search results to the model
+- **THEN** each resource MUST include title, type, metadata name, permalink, description or excerpt where available
+- **AND** it MUST NOT include the full document content
+
+### Requirement: Halo resource detail tool SHALL return bounded public content
+The plugin SHALL provide a server-executed Agent tool for reading limited details from trusted or current public Halo resources.
+
+#### Scenario: Detail lookup enforces public resource constraints
+- **WHEN** the model calls `get_halo_resource_detail`
+- **THEN** the backend MUST only return details for public, published, non-recycled resources that are supported by the plugin
+- **AND** it MUST reject or fail gracefully for unsupported, private, recycled, or unpublished resources
+
+#### Scenario: Detail content is length limited
+- **WHEN** the backend returns resource detail content
+- **THEN** the content MUST be capped by the configured maximum and hard upper bound
+- **AND** the result MUST indicate whether content was truncated
+
+### Requirement: Halo latest resources SHALL be exposed through backend resource queries
+The plugin SHALL provide a server-executed Agent tool for listing recent public Halo resources.
+
+#### Scenario: Latest resources returns posts at minimum
+- **WHEN** the model calls `get_latest_halo_resources`
+- **THEN** the backend MUST return recent public posts at minimum
+- **AND** it MUST include trusted resource metadata and permalinks for frontend navigation
+
+#### Scenario: Latest resources respects type configuration
+- **WHEN** the site owner configures additional supported latest resource types
+- **THEN** the backend MUST include only supported and allowed public types in the latest resource result
+
+### Requirement: Halo taxonomy and page tools SHALL use structured backend queries
+The plugin SHALL provide server-executed tools for categories, tags, pages, and resource lists associated with taxonomies.
+
+#### Scenario: Categories and tags return navigable resources
+- **WHEN** the model requests categories or tags
+- **THEN** the backend MUST return structured public taxonomy resources with names and permalinks where available
+- **AND** those resources MUST be eligible for trusted frontend navigation
+
+#### Scenario: Posts by taxonomy return public post resources
+- **WHEN** the model requests posts by a category or tag
+- **THEN** the backend MUST return only public, published, non-recycled posts in that taxonomy
+- **AND** it MUST include bounded metadata for model responses and frontend navigation
+
+#### Scenario: Pages are searchable and navigable
+- **WHEN** the model requests public pages or searches pages
+- **THEN** the backend MUST return public page resources with titles and permalinks
+- **AND** those resources MUST be eligible for trusted frontend navigation
+
+### Requirement: Halo comment capability SHALL support configurable assistance levels
+The plugin SHALL provide Halo comment Agent capabilities according to the site owner's selected comment level.
+
+#### Scenario: Comment capability disabled
+- **WHEN** the comment capability is `off`
+- **THEN** no comment tools MUST be declared to the model
+
+#### Scenario: Comment assist capability
+- **WHEN** the comment capability is `assist`
+- **THEN** the plugin MAY declare tools to open the comment area, read public comments where available, and draft comment content
+- **AND** it MUST NOT submit comments automatically
+
+#### Scenario: Comment submit capability
+- **WHEN** the comment capability is `submit`
+- **THEN** the plugin MAY declare a comment submission tool only when the site policy supports it
+- **AND** each submission MUST require visitor approval
+- **AND** the tool MUST respect Halo comment authentication, captcha, moderation, and validation requirements
+
+#### Scenario: Comment flow requires visitor completion
+- **WHEN** a required comment precondition such as login, captcha, profile fields, or moderation cannot be satisfied by the tool
+- **THEN** the tool MUST return a structured result telling the model that the visitor must complete the site comment flow manually
diff --git a/openspec/specs/halo-ai-chat-integration/spec.md b/openspec/specs/halo-ai-chat-integration/spec.md
new file mode 100644
index 0000000..c7c6474
--- /dev/null
+++ b/openspec/specs/halo-ai-chat-integration/spec.md
@@ -0,0 +1,73 @@
+# halo-ai-chat-integration Specification
+
+## Purpose
+Define how Live2D AI chat integrates with Halo AI Foundation, UI Message streaming, access modes, and Agent tool declaration.
+
+## Requirements
+
+### Requirement: Live2D chat SHALL stream replies through Halo AI foundation
+When AI chat is enabled, the Live2D backend SHALL invoke Halo AI foundation for chat generation, UI Message streaming, and enabled Agent tool declarations instead of any plugin-owned provider client, while preserving the widget-facing streaming endpoint contract.
+
+#### Scenario: Chat requests are fulfilled by Halo AI foundation
+- **WHEN** a user sends a chat message to `/live2d/ai/chat-process`
+- **THEN** the backend MUST resolve the configured Halo AI language model through Halo AI foundation
+- **AND** it MUST submit the system prompt plus conversation history to that model
+- **AND** it MUST stream assistant UI Message chunks back through the plugin SSE response flow
+
+#### Scenario: Stream completion preserves the current frontend terminator
+- **WHEN** Halo AI foundation reports a successful end of generation
+- **THEN** the backend MUST emit the Halo UI Message stream done marker for the frontend consumer
+- **AND** it MUST complete the SSE response without requiring non-SDK frontend parsing
+
+#### Scenario: Agent-enabled chat declares available tools
+- **WHEN** AI chat is enabled and the current access mode allows Agent capabilities for the visitor
+- **THEN** the backend MUST pass the currently available Agent tool definitions to Halo AI foundation
+- **AND** browser-executed tools MUST be declared without server executors
+- **AND** server-executed Halo preset tools MUST include executors
+
+### Requirement: Live2D AI chat settings SHALL only keep plugin-specific chat controls
+The plugin SHALL configure Live2D chat through Halo-integrated settings that keep widget-specific behavior in this plugin and remove provider-specific connection settings from the plugin schema.
+
+#### Scenario: Plugin settings retain persona, access mode, and model selection
+- **WHEN** an administrator enables AI chat in the Live2D plugin settings
+- **THEN** the plugin MUST allow configuration of AI access mode, persona/system prompt, Halo AI model identifier, and frontend timing controls
+- **AND** those settings MUST be used to build chat requests and widget behavior
+
+#### Scenario: Legacy anonymous setting maps to chat-only access mode
+- **WHEN** existing settings contain `isAnonymous=true` and no access mode
+- **THEN** the plugin MUST treat the setting as `anonymous_chat`
+- **AND** it MUST NOT enable Agent capabilities implicitly
+
+#### Scenario: Legacy authenticated setting maps to chat-only access mode
+- **WHEN** existing settings contain `isAnonymous=false` and no access mode
+- **THEN** the plugin MUST treat the setting as `authenticated_chat`
+- **AND** it MUST NOT enable Agent capabilities implicitly
+
+#### Scenario: Provider-specific settings are removed from the plugin
+- **WHEN** an administrator opens the Live2D AI chat settings after this change
+- **THEN** OpenAI token, base URL, provider toggle, proxy host, and proxy port settings MUST NOT be present in the plugin configuration form
+- **AND** provider credentials and provider enablement MUST be managed through Halo AI infrastructure instead
+
+#### Scenario: Public runtime config excludes backend-only AI foundation settings
+- **WHEN** the plugin exposes public runtime configuration to the frontend
+- **THEN** it MUST continue exposing AI chat enablement and widget timing fields needed by the browser
+- **AND** it MUST NOT expose backend-only Halo model identifiers or provider configuration details to the public config payload
+
+### Requirement: Live2D chat SHALL surface Halo AI dependency failures clearly
+The Live2D chat integration SHALL translate Halo AI foundation availability, model-resolution failures, and Agent access failures into stable plugin behavior for both users and administrators.
+
+#### Scenario: Authenticated-only chat still enforces login
+- **WHEN** AI chat is enabled but the access mode requires authentication and an unauthenticated user sends a message
+- **THEN** the endpoint MUST reject the request with HTTP 401
+- **AND** it MUST NOT invoke Halo AI foundation for that request
+
+#### Scenario: Agent-disabled chat does not declare tools
+- **WHEN** AI chat is enabled but the access mode does not allow Agent capabilities for the visitor
+- **THEN** the backend MUST still allow chat according to the access mode
+- **AND** it MUST NOT declare any Agent tools to Halo AI foundation
+- **AND** the system prompt MUST avoid promising direct site operations
+
+#### Scenario: Missing AI foundation dependency or model configuration is reported cleanly
+- **WHEN** the ai-foundation plugin is unavailable, disabled, or the configured Halo model cannot be resolved
+- **THEN** the backend MUST log the failure for administrators
+- **AND** it MUST return a user-facing chat failure message through the existing plugin response flow instead of an unhandled server error
diff --git a/openspec/specs/live2d-public-runtime-config/spec.md b/openspec/specs/live2d-public-runtime-config/spec.md
index 6ffb630..6086478 100644
--- a/openspec/specs/live2d-public-runtime-config/spec.md
+++ b/openspec/specs/live2d-public-runtime-config/spec.md
@@ -1,8 +1,10 @@
 # live2d-public-runtime-config Specification
 
 ## Purpose
-TBD - created by archiving change integrate-modern-live2d-frontend. Update Purpose after archive.
+Define the frontend-safe runtime configuration contract emitted by the backend for the modern Live2D runtime.
+
 ## Requirements
+
 ### Requirement: Backend SHALL publish a frontend-safe Live2D runtime config payload
 The plugin backend SHALL publish a dedicated public config payload for the Live2D frontend instead of exposing a broad merged settings object directly to inline initialization code.
 
@@ -16,6 +18,16 @@ The plugin backend SHALL publish a dedicated public config payload for the Live2
 - **THEN** it MUST receive the fields needed to preserve current widget behavior, including runtime toggles, tips sources, model defaults, AI-chat runtime timings, and declarative custom tool definitions when configured
 - **AND** it MUST not require the backend to expose raw settings groups that are not part of the frontend contract
 
+#### Scenario: Public payload includes safe Agent browser execution metadata
+- **WHEN** Agent capabilities are configured
+- **THEN** the public payload MUST include only normalized browser execution metadata needed by the frontend to execute allowed browser tools
+- **AND** it MUST exclude backend-only model identifiers, provider configuration, server executor details, and invalid tool definitions
+
+#### Scenario: Public payload cannot expand model-visible tools
+- **WHEN** frontend scripts register Agent tool executors at runtime
+- **THEN** those registrations MUST only bind executors for tools already present in the normalized public Agent runtime config
+- **AND** they MUST NOT create additional model-visible tool declarations
+
 ### Requirement: Halo bootstrap SHALL deliver config separately from execution logic
 The plugin SHALL provide the runtime config payload in a transport that is separate from the frontend execution bundle so configuration and code loading can evolve independently.
 
@@ -28,4 +40,3 @@ The plugin SHALL provide the runtime config payload in a transport that is separ
 - **WHEN** the frontend is loaded from packaged assets or from a dev server
 - **THEN** both startup modes MUST read the same public config payload shape
 - **AND** environment-specific bootstrap differences MUST not require a second config format
-
diff --git a/packages/live2d/package.json b/packages/live2d/package.json
index b6aa04e..3be2bc1 100644
--- a/packages/live2d/package.json
+++ b/packages/live2d/package.json
@@ -21,6 +21,7 @@
     "check": "pnpm sync:custom-tool-actions && biome check --write"
   },
   "dependencies": {
+    "@halo-dev/ai-foundation-sdk": "1.0.0-beta.1",
     "@lit/context": "^1.1.6",
     "@lit/react": "^1.0.8",
     "@pixi/sound": "^6.0.1",
diff --git a/packages/live2d/src/api/__tests__/agent-tool-runtime.test.ts b/packages/live2d/src/api/__tests__/agent-tool-runtime.test.ts
new file mode 100644
index 0000000..8f6594a
--- /dev/null
+++ b/packages/live2d/src/api/__tests__/agent-tool-runtime.test.ts
@@ -0,0 +1,272 @@
+import type { AgentRuntimeConfig } from "@/live2d/config/agent-tools/agent-tool-config";
+import type { ToolPart } from "@halo-dev/ai-foundation-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { AgentToolRuntime } from "../agent-tool-runtime";
+
+const baseConfig = (): AgentRuntimeConfig => ({
+  builtIn: {
+    pageContext: true,
+    haloNavigation: true,
+    haloContentSearch: true,
+    networkAccess: false,
+    commentCapability: "assist",
+  },
+  aiTools: [],
+  toolSecurity: {
+    allowedExternalOrigins: [],
+    allowNewTab: false,
+  },
+  haloSearch: {
+    allowedTypes: ["post.content.halo.run", "singlepage.content.halo.run"],
+    defaultLimit: 5,
+  },
+  haloResourceDetail: {
+    maxContentChars: 3000,
+  },
+});
+
+const toolPart = (
+  toolName: string,
+  input: Record<string, unknown> = {},
+): ToolPart => ({
+  type: `tool-${toolName}`,
+  toolCallId: `call-${toolName}`,
+  toolName,
+  state: "input-available",
+  input,
+});
+
+describe("AgentToolRuntime", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    sessionStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("binds registered executor only for declared tools", async () => {
+    const config = baseConfig();
+    config.aiTools = [
+      {
+        name: "show_owner_updates",
+        description: "展示站长动态",
+        inputSchema: { type: "object", properties: {} },
+        approval: "never",
+        requiredAuth: "none",
+        actionType: "registered",
+        action: { type: "registered" },
+      },
+    ];
+    const runtime = new AgentToolRuntime({ config });
+    window.Live2DAI?.registerTool("show_owner_updates", ({ input }) => ({
+      received: input,
+    }));
+
+    const result = await runtime.execute(
+      toolPart("show_owner_updates", { limit: 3 }),
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.output).toEqual({ received: { limit: 3 } });
+    expect(runtime.canExecute("not_declared")).toBe(false);
+  });
+
+  it("does not navigate to resources that are not trusted by previous outputs", async () => {
+    const runtime = new AgentToolRuntime({ config: baseConfig() });
+
+    const result = await runtime.execute(
+      toolPart("open_halo_resource", {
+        resourceId: "post.content.halo.run:demo",
+      }),
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.errorCode).toBe("RESOURCE_NOT_TRUSTED");
+  });
+
+  it("reports page comment capability before comment actions", async () => {
+    document.title = "首页";
+    document.body.innerHTML = `
+      <main>
+        <h1>首页</h1>
+        <a href="/archives/demo">文章</a>
+        <form id="search"><input name="keyword" /><button>搜索</button></form>
+      </main>
+    `;
+    const runtime = new AgentToolRuntime({ config: baseConfig() });
+
+    const result = await runtime.execute(toolPart("get_current_page_context"));
+
+    expect(result.ok).toBe(true);
+    expect(result.capabilities).toMatchObject({
+      comment: {
+        hasArea: false,
+        hasInput: false,
+        hasSubmitButton: false,
+      },
+    });
+    expect(result.headings).toEqual([{ level: 1, text: "首页" }]);
+  });
+
+  it("executes default page context tool when runtime config is not provided", async () => {
+    document.title = "默认配置页面";
+    document.body.innerHTML = "<main><h1>默认配置页面</h1></main>";
+    const runtime = new AgentToolRuntime();
+
+    expect(runtime.canExecute("get_current_page_context")).toBe(true);
+
+    const result = await runtime.execute(toolPart("get_current_page_context"));
+
+    expect(result).toMatchObject({
+      ok: true,
+      title: "默认配置页面",
+      capabilities: {
+        comment: {
+          hasArea: false,
+        },
+      },
+    });
+  });
+
+  it("reports writable comment controls when present", async () => {
+    document.body.innerHTML = `
+      <section id="comments">
+        <textarea name="content"></textarea>
+        <button type="submit">提交评论</button>
+      </section>
+    `;
+    const runtime = new AgentToolRuntime({ config: baseConfig() });
+
+    const result = await runtime.execute(toolPart("get_current_page_context"));
+
+    expect(result.capabilities).toMatchObject({
+      comment: {
+        hasArea: true,
+        hasInput: true,
+        hasSubmitButton: true,
+      },
+    });
+  });
+
+  it("does not draft comments when current page has no comment area", async () => {
+    document.body.innerHTML = "<main><h1>首页</h1></main>";
+    const runtime = new AgentToolRuntime({ config: baseConfig() });
+
+    const result = await runtime.execute(
+      toolPart("draft_comment", { content: "我想留言" }),
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.errorCode).toBe("COMMENT_INPUT_NOT_FOUND");
+    expect(result.message).toBe("当前页面没有检测到评论区，无法填写评论");
+  });
+
+  it("fills comment draft in assist mode without submitting", async () => {
+    document.body.innerHTML = `
+      <section id="comments">
+        <textarea name="content"></textarea>
+        <button type="submit">提交评论</button>
+      </section>
+    `;
+    const submit = document.querySelector<HTMLButtonElement>("button");
+    const click = vi.spyOn(submit as HTMLButtonElement, "click");
+    const runtime = new AgentToolRuntime({ config: baseConfig() });
+
+    const result = await runtime.execute(
+      toolPart("draft_comment", { content: "这篇文章很有帮助" }),
+    );
+
+    expect(result.ok).toBe(true);
+    expect(document.querySelector<HTMLTextAreaElement>("textarea")?.value).toBe(
+      "这篇文章很有帮助",
+    );
+    expect(click).not.toHaveBeenCalled();
+  });
+
+  it("submits comment only when submit capability is enabled", async () => {
+    document.body.innerHTML = `
+      <section id="comments">
+        <textarea name="content"></textarea>
+        <button type="submit">提交评论</button>
+      </section>
+    `;
+    const config = baseConfig();
+    config.builtIn.commentCapability = "submit";
+    const submit = document.querySelector<HTMLButtonElement>("button");
+    const click = vi.spyOn(submit as HTMLButtonElement, "click");
+    const runtime = new AgentToolRuntime({ config });
+
+    const result = await runtime.execute(
+      toolPart("submit_comment", { content: "请帮我提交这条评论" }),
+    );
+
+    expect(result.ok).toBe(true);
+    expect(document.querySelector<HTMLTextAreaElement>("textarea")?.value).toBe(
+      "请帮我提交这条评论",
+    );
+    expect(click).toHaveBeenCalledOnce();
+  });
+
+  it("remembers chat recovery intent before opening trusted resources", async () => {
+    vi.useFakeTimers();
+    const assign = vi.fn();
+    const originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      value: { ...originalLocation, assign },
+    });
+    const runtime = new AgentToolRuntime({ config: baseConfig() });
+    runtime.ingestMessages([
+      {
+        id: "assistant-1",
+        role: "assistant",
+        parts: [
+          {
+            type: "tool-search_halo_contents",
+            toolCallId: "call-search",
+            toolName: "search_halo_contents",
+            state: "output-available",
+            input: {},
+            output: {
+              resources: [
+                {
+                  resourceId: "post.content.halo.run:demo",
+                  permalink: "/archives/demo",
+                  title: "Demo",
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ]);
+
+    const result = await runtime.execute(
+      toolPart("open_halo_resource", {
+        resourceId: "post.content.halo.run:demo",
+      }),
+    );
+    vi.runAllTimers();
+
+    expect(result.ok).toBe(true);
+    expect(assign).toHaveBeenCalledWith("/archives/demo");
+    expect(sessionStorage.getItem("live2d:agent-after-navigation")).toContain(
+      '"openChat":true',
+    );
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      value: originalLocation,
+    });
+    vi.useRealTimers();
+  });
+
+  it("resolves approval overlay from visitor choice", async () => {
+    const runtime = new AgentToolRuntime({ config: baseConfig() });
+
+    const approval = runtime.requestApproval("要执行这个动作吗？");
+    document
+      .querySelector<HTMLButtonElement>("#live2d-agent-approval button")
+      ?.click();
+
+    await expect(approval).resolves.toBe(true);
+  });
+});
diff --git a/packages/live2d/src/api/__tests__/chat-api.test.ts b/packages/live2d/src/api/__tests__/chat-api.test.ts
new file mode 100644
index 0000000..518a547
--- /dev/null
+++ b/packages/live2d/src/api/__tests__/chat-api.test.ts
@@ -0,0 +1,647 @@
+import {
+  STREAM_MESSAGE_EVENT_NAME,
+  type StreamMessageEventDetail,
+} from "@/live2d/events/stream-message";
+import {
+  HALO_UI_MESSAGE_STREAM_HEADER,
+  HALO_UI_MESSAGE_STREAM_VERSION,
+  type UIMessageChunk,
+} from "@halo-dev/ai-foundation-sdk";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ChatApi } from "../chat-api";
+
+const streamResponse = (chunks: UIMessageChunk[]) => {
+  const encoder = new TextEncoder();
+  return new Response(
+    new ReadableStream({
+      start(controller) {
+        for (const chunk of chunks) {
+          controller.enqueue(
+            encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`),
+          );
+        }
+        controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+        controller.close();
+      },
+    }),
+    {
+      headers: {
+        "Content-Type": "text/event-stream",
+        [HALO_UI_MESSAGE_STREAM_HEADER]: HALO_UI_MESSAGE_STREAM_VERSION,
+      },
+    },
+  );
+};
+
+describe("ChatApi", () => {
+  beforeEach(() => {
+    document.title = "首页";
+    document.body.innerHTML = "<main><h1>首页</h1></main>";
+    localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("continues the SDK UI message stream after a browser tool call", async () => {
+    const streamMessages: StreamMessageEventDetail[] = [];
+    window.addEventListener(STREAM_MESSAGE_EVENT_NAME, (event) => {
+      streamMessages.push(
+        (event as CustomEvent<StreamMessageEventDetail>).detail,
+      );
+    });
+    const requests: unknown[] = [];
+    const fetchMock = vi.fn(async (_url: string | URL | Request, init) => {
+      requests.push(JSON.parse(String(init?.body)));
+      if (requests.length === 1) {
+        return streamResponse([
+          { type: "text-start", id: "txt-1" },
+          { type: "text-delta", id: "txt-1", delta: "我先看一下页面。" },
+          { type: "text-end", id: "txt-1" },
+          {
+            type: "tool-input-available",
+            toolCallId: "call-ctx",
+            toolName: "get_current_page_context",
+            input: {},
+          },
+          {
+            type: "finish-step",
+            stepIndex: 0,
+            finishReason: "tool-calls",
+            rawFinishReason: "TOOL_CALLS",
+          },
+          {
+            type: "finish",
+            finishReason: "tool-calls",
+            rawFinishReason: "TOOL_CALLS",
+          },
+        ]);
+      }
+      return streamResponse([
+        { type: "text-start", id: "txt-2" },
+        {
+          type: "text-delta",
+          id: "txt-2",
+          delta: "当前页面没有检测到评论区，不能直接留言。",
+        },
+      ]);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const chatApi = new ChatApi({
+      apiEndpoint: "/api/chat",
+      chunkTimeout: 1,
+      showChatMessageTimeout: 1,
+    });
+
+    await chatApi.sendMessage("帮我给站长留个言", []);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const secondRequest = requests[1] as {
+      messages: Array<{
+        role: string;
+        parts: Array<Record<string, unknown>>;
+      }>;
+    };
+    const assistant = secondRequest.messages.find(
+      (message) => message.role === "assistant",
+    );
+    expect(assistant?.parts).toContainEqual(
+      expect.objectContaining({
+        toolCallId: "call-ctx",
+        toolName: "get_current_page_context",
+        state: "output-available",
+        output: expect.objectContaining({
+          ok: true,
+          capabilities: expect.objectContaining({
+            comment: expect.objectContaining({
+              hasArea: false,
+            }),
+          }),
+        }),
+      }),
+    );
+    const storedHistory = JSON.parse(
+      localStorage.getItem("historyMessages") ?? "[]",
+    ) as Array<{
+      role: string;
+      parts: Array<Record<string, unknown>>;
+    }>;
+    const storedToolParts = storedHistory
+      .flatMap((message) => message.parts)
+      .filter((part) => part.toolCallId === "call-ctx");
+    expect(storedToolParts).toHaveLength(1);
+    expect(storedToolParts[0]).toEqual(
+      expect.objectContaining({
+        state: "output-available",
+      }),
+    );
+    expect(streamMessages).not.toContainEqual(
+      expect.objectContaining({
+        mode: "replace",
+        text: "",
+      }),
+    );
+    expect(replayStreamMessage(streamMessages)).toBe(
+      "当前页面没有检测到评论区，不能直接留言。",
+    );
+  });
+
+  it("keeps the pre-tool text visible before replacing it with automatic continuation text", async () => {
+    const streamMessages: StreamMessageEventDetail[] = [];
+    const listener = (event: Event) => {
+      streamMessages.push(
+        (event as CustomEvent<StreamMessageEventDetail>).detail,
+      );
+    };
+    window.addEventListener(STREAM_MESSAGE_EVENT_NAME, listener);
+    const fetchMock = vi.fn(async () => {
+      if (fetchMock.mock.calls.length === 1) {
+        return streamResponse([
+          { type: "text-start", id: "txt-before-tool" },
+          {
+            type: "text-delta",
+            id: "txt-before-tool",
+            delta: "我先看一下页面。",
+          },
+          {
+            type: "tool-input-available",
+            toolCallId: "call-delayed-replace",
+            toolName: "get_current_page_context",
+            input: {},
+          },
+          {
+            type: "finish",
+            finishReason: "tool-calls",
+            rawFinishReason: "TOOL_CALLS",
+          },
+        ]);
+      }
+      return streamResponse([
+        { type: "text-start", id: "txt-after-tool" },
+        {
+          type: "text-delta",
+          id: "txt-after-tool",
+          delta: "首页没有评论框，不能直接留言。",
+        },
+      ]);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const chatApi = new ChatApi({
+      apiEndpoint: "/api/chat",
+      chunkTimeout: 1,
+      showChatMessageTimeout: 1,
+      autoContinuationMessageMinVisibleMs: 250,
+    });
+
+    try {
+      const sendPromise = chatApi.sendMessage("帮我给站长留个言", []);
+      await waitForCondition(() => fetchMock.mock.calls.length === 2);
+
+      expect(replayStreamMessage(streamMessages)).toContain("我先看一下页面。");
+      expect(replayStreamMessage(streamMessages)).not.toContain(
+        "首页没有评论框，不能直接留言。",
+      );
+
+      await waitForCondition(() =>
+        replayStreamMessage(streamMessages).includes(
+          "首页没有评论框，不能直接留言。",
+        ),
+      );
+      await sendPromise;
+
+      expect(replayStreamMessage(streamMessages)).toBe(
+        "首页没有评论框，不能直接留言。",
+      );
+    } finally {
+      window.removeEventListener(STREAM_MESSAGE_EVENT_NAME, listener);
+    }
+  });
+
+  it("does not keep auto-submitting after the completed tool output has already continued once", async () => {
+    const requests: unknown[] = [];
+    const fetchMock = vi.fn(async (_url: string | URL | Request, init) => {
+      requests.push(JSON.parse(String(init?.body)));
+      if (requests.length === 1) {
+        return streamResponse([
+          { type: "text-start", id: "txt-1" },
+          { type: "text-delta", id: "txt-1", delta: "我先看看当前页面。" },
+          {
+            type: "tool-input-available",
+            toolCallId: "call-page-context",
+            toolName: "get_current_page_context",
+            input: {},
+          },
+          {
+            type: "finish",
+            finishReason: "tool-calls",
+            rawFinishReason: "TOOL_CALLS",
+          },
+        ]);
+      }
+      if (requests.length === 2) {
+        return streamResponse([
+          { type: "start", messageId: "assistant-after-tool" },
+          { type: "text-start", id: "txt-2" },
+          {
+            type: "text-delta",
+            id: "txt-2",
+            delta: "首页没有评论框，不能直接给站长留言。",
+          },
+        ]);
+      }
+      throw new Error("Unexpected automatic continuation without a new tool.");
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const chatApi = new ChatApi({
+      apiEndpoint: "/api/chat",
+      chunkTimeout: 1,
+      showChatMessageTimeout: 1,
+    });
+
+    await chatApi.sendMessage("帮我给站长留个言", []);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const secondRequest = requests[1] as {
+      messages: Array<{
+        role: string;
+        parts: Array<Record<string, unknown>>;
+      }>;
+    };
+    const assistant = secondRequest.messages.find(
+      (message) => message.role === "assistant",
+    );
+    expect(assistant?.parts).toContainEqual(
+      expect.objectContaining({
+        toolCallId: "call-page-context",
+        state: "output-available",
+      }),
+    );
+  });
+
+  it("continues after an async browser tool resolves later than the first stream", async () => {
+    window.Live2DAI?.registerTool("slow_page_context", async () => {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      return { page: "home" };
+    });
+
+    const requests: unknown[] = [];
+    const fetchMock = vi.fn(async (_url: string | URL | Request, init) => {
+      requests.push(JSON.parse(String(init?.body)));
+      if (requests.length === 1) {
+        return streamResponse([
+          { type: "text-start", id: "txt-1" },
+          { type: "text-delta", id: "txt-1", delta: "我先看一下。" },
+          {
+            type: "tool-input-available",
+            toolCallId: "call-slow",
+            toolName: "slow_page_context",
+            input: {},
+          },
+          {
+            type: "finish-step",
+            stepIndex: 0,
+            finishReason: "tool-calls",
+            rawFinishReason: "TOOL_CALLS",
+          },
+          {
+            type: "finish",
+            finishReason: "tool-calls",
+            rawFinishReason: "TOOL_CALLS",
+          },
+        ]);
+      }
+      return streamResponse([
+        { type: "text-start", id: "txt-2" },
+        { type: "text-delta", id: "txt-2", delta: "已经看完了。" },
+      ]);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const chatApi = new ChatApi({
+      apiEndpoint: "/api/chat",
+      chunkTimeout: 1,
+      showChatMessageTimeout: 1,
+      agent: {
+        builtIn: {
+          pageContext: false,
+          haloNavigation: false,
+          haloContentSearch: false,
+          networkAccess: false,
+          commentCapability: "off",
+        },
+        aiTools: [
+          {
+            name: "slow_page_context",
+            description: "读取页面上下文",
+            inputSchema: {},
+            approval: "never",
+            requiredAuth: "none",
+            actionType: "registered",
+            action: { type: "registered" },
+          },
+        ],
+        toolSecurity: {
+          allowedExternalOrigins: [],
+          allowNewTab: false,
+        },
+        haloSearch: {
+          allowedTypes: [],
+          defaultLimit: 5,
+        },
+        haloResourceDetail: {
+          maxContentChars: 1000,
+        },
+      },
+    });
+
+    await chatApi.sendMessage("帮我看看页面", []);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const secondRequest = requests[1] as {
+      messages: Array<{
+        role: string;
+        parts: Array<Record<string, unknown>>;
+      }>;
+    };
+    const assistant = secondRequest.messages.find(
+      (message) => message.role === "assistant",
+    );
+    expect(assistant?.parts).toContainEqual(
+      expect.objectContaining({
+        toolCallId: "call-slow",
+        toolName: "slow_page_context",
+        state: "output-available",
+        output: expect.objectContaining({
+          ok: true,
+          output: { page: "home" },
+        }),
+      }),
+    );
+  });
+
+  it("continues even when the first assistant step only contains a tool call", async () => {
+    const fetchMock = vi.fn(async () => {
+      if (fetchMock.mock.calls.length === 1) {
+        return streamResponse([
+          {
+            type: "tool-input-available",
+            toolCallId: "call-ctx-only",
+            toolName: "get_current_page_context",
+            input: {},
+          },
+          {
+            type: "finish",
+            finishReason: "tool-calls",
+            rawFinishReason: "TOOL_CALLS",
+          },
+        ]);
+      }
+      return streamResponse([
+        { type: "text-start", id: "txt-final" },
+        { type: "text-delta", id: "txt-final", delta: "页面看完了。" },
+      ]);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const chatApi = new ChatApi({
+      apiEndpoint: "/api/chat",
+      chunkTimeout: 1,
+      showChatMessageTimeout: 1,
+    });
+
+    await chatApi.sendMessage("查看当前页面", []);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("shows automatic text when the second stream reuses the previous text part id", async () => {
+    const streamMessages: StreamMessageEventDetail[] = [];
+    window.addEventListener(STREAM_MESSAGE_EVENT_NAME, (event) => {
+      streamMessages.push(
+        (event as CustomEvent<StreamMessageEventDetail>).detail,
+      );
+    });
+    const fetchMock = vi.fn(async () => {
+      if (fetchMock.mock.calls.length === 1) {
+        return streamResponse([
+          { type: "text-start", id: "txt-shared" },
+          { type: "text-delta", id: "txt-shared", delta: "我先看一下页面。" },
+          {
+            type: "tool-input-available",
+            toolCallId: "call-reused-text",
+            toolName: "get_current_page_context",
+            input: {},
+          },
+          {
+            type: "finish",
+            finishReason: "tool-calls",
+            rawFinishReason: "TOOL_CALLS",
+          },
+        ]);
+      }
+      return streamResponse([
+        { type: "reasoning-start", id: "rsn-1" },
+        { type: "reasoning-delta", id: "rsn-1", delta: "正在分析页面" },
+        { type: "reasoning-end", id: "rsn-1" },
+        {
+          type: "text-delta",
+          id: "txt-shared",
+          delta: "当前页面可以继续处理。",
+        },
+      ]);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const chatApi = new ChatApi({
+      apiEndpoint: "/api/chat",
+      chunkTimeout: 1,
+      showChatMessageTimeout: 1,
+    });
+
+    await chatApi.sendMessage("查看当前页面", []);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(replayStreamMessage(streamMessages)).toBe("当前页面可以继续处理。");
+  });
+
+  it("compacts duplicate final tool results before sending history", async () => {
+    const requests: unknown[] = [];
+    const fetchMock = vi.fn(async (_url: string | URL | Request, init) => {
+      requests.push(JSON.parse(String(init?.body)));
+      return streamResponse([
+        { type: "text-start", id: "txt-reply" },
+        { type: "text-delta", id: "txt-reply", delta: "可以继续聊天。" },
+      ]);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const chatApi = new ChatApi({
+      apiEndpoint: "/api/chat",
+      chunkTimeout: 1,
+      showChatMessageTimeout: 1,
+    });
+
+    await chatApi.sendMessage("继续", [
+      {
+        id: "msg-user",
+        role: "user",
+        parts: [{ type: "text", id: "txt-user", text: "查看页面" }],
+      },
+      {
+        id: "msg-assistant",
+        role: "assistant",
+        parts: [
+          {
+            type: "tool-get_current_page_context",
+            toolCallId: "call-duplicated",
+            toolName: "get_current_page_context",
+            state: "output-available",
+            input: {},
+            output: { ok: true, stale: true },
+          },
+          {
+            type: "tool-get_current_page_context",
+            toolCallId: "call-duplicated",
+            toolName: "get_current_page_context",
+            state: "output-available",
+            input: {},
+            output: { ok: true, fresh: true },
+          },
+        ],
+      },
+    ]);
+
+    const firstRequest = requests[0] as {
+      messages: Array<{ parts: Array<Record<string, unknown>> }>;
+    };
+    const duplicatedToolParts = firstRequest.messages
+      .flatMap((message) => message.parts)
+      .filter((part) => part.toolCallId === "call-duplicated");
+    expect(duplicatedToolParts).toHaveLength(1);
+    expect(duplicatedToolParts[0]).toEqual(
+      expect.objectContaining({
+        output: { ok: true, fresh: true },
+      }),
+    );
+  });
+
+  it("stores an agent resume intent when a tool navigates with page reload", async () => {
+    window.Live2DAI?.registerTool("reload_navigation", () => ({
+      ok: true,
+      navigating: true,
+      pageReload: true,
+    }));
+
+    const fetchMock = vi.fn(async () => {
+      if (fetchMock.mock.calls.length === 1) {
+        return streamResponse([
+          {
+            type: "tool-input-available",
+            toolCallId: "call-reload",
+            toolName: "reload_navigation",
+            input: {},
+          },
+          {
+            type: "finish",
+            finishReason: "tool-calls",
+            rawFinishReason: "TOOL_CALLS",
+          },
+        ]);
+      }
+      return streamResponse([
+        { type: "text-start", id: "txt-after-reload" },
+        { type: "text-delta", id: "txt-after-reload", delta: "继续处理。" },
+      ]);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const chatApi = new ChatApi({
+      apiEndpoint: "/api/chat",
+      chunkTimeout: 1,
+      showChatMessageTimeout: 1,
+      agent: {
+        builtIn: {
+          pageContext: false,
+          haloNavigation: false,
+          haloContentSearch: false,
+          networkAccess: false,
+          commentCapability: "off",
+        },
+        aiTools: [
+          {
+            name: "reload_navigation",
+            description: "刷新当前页面",
+            inputSchema: {},
+            approval: "never",
+            requiredAuth: "none",
+            actionType: "registered",
+            action: { type: "registered" },
+          },
+        ],
+        toolSecurity: {
+          allowedExternalOrigins: [],
+          allowNewTab: false,
+        },
+        haloSearch: {
+          allowedTypes: [],
+          defaultLimit: 5,
+        },
+        haloResourceDetail: {
+          maxContentChars: 1000,
+        },
+      },
+    });
+
+    await chatApi.sendMessage("打开一篇文章后继续留言", []);
+
+    const intent = JSON.parse(
+      sessionStorage.getItem("live2d:agent-after-navigation") ?? "{}",
+    ) as {
+      openChat?: boolean;
+      resume?: {
+        message?: string;
+        historyMessages?: Array<{ parts: Array<Record<string, unknown>> }>;
+      };
+    };
+    expect(intent.openChat).toBe(true);
+    expect(intent.resume?.message).toContain("继续完成上一条用户请求");
+    const resumeToolParts = intent.resume?.historyMessages
+      ?.flatMap((message) => message.parts)
+      .filter((part) => part.toolCallId === "call-reload");
+    expect(resumeToolParts).toHaveLength(1);
+    expect(resumeToolParts?.[0]).toEqual(
+      expect.objectContaining({
+        state: "output-available",
+        output: expect.objectContaining({
+          output: expect.objectContaining({
+            navigating: true,
+            pageReload: true,
+          }),
+        }),
+      }),
+    );
+  });
+});
+
+const replayStreamMessage = (messages: StreamMessageEventDetail[]) =>
+  messages.reduce((current, message) => {
+    if (message.mode === "replace") {
+      return message.text;
+    }
+    return `${current}${message.text}`;
+  }, "");
+
+const waitForCondition = async (condition: () => boolean, timeoutMs = 1000) => {
+  const startedAt = Date.now();
+  while (!condition()) {
+    if (Date.now() - startedAt > timeoutMs) {
+      throw new Error("Timed out waiting for condition");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+};
diff --git a/packages/live2d/src/api/agent-navigation-intent.ts b/packages/live2d/src/api/agent-navigation-intent.ts
new file mode 100644
index 0000000..0016a2b
--- /dev/null
+++ b/packages/live2d/src/api/agent-navigation-intent.ts
@@ -0,0 +1,88 @@
+import type { UIMessage } from "@halo-dev/ai-foundation-sdk";
+
+export interface AgentAfterNavigationResume {
+  message: string;
+  historyMessages: UIMessage[];
+}
+
+export interface AgentAfterNavigationIntent {
+  openChat: boolean;
+  focusChatInput: boolean;
+  resume?: AgentAfterNavigationResume;
+  expiresAt: number;
+}
+
+const STORAGE_KEY = "live2d:agent-after-navigation";
+const DEFAULT_TTL_MS = 15_000;
+const DEFAULT_RESUME_MESSAGE =
+  "我已经打开了新的页面，请基于当前页面继续完成上一条用户请求。必要时先查看当前页面上下文。";
+
+export interface RememberAgentAfterNavigationOptions {
+  resume?: {
+    message?: string;
+    historyMessages?: UIMessage[];
+  };
+}
+
+export const rememberAgentAfterNavigationIntent = (
+  options: RememberAgentAfterNavigationOptions = {},
+  storage: Storage = window.sessionStorage,
+): void => {
+  const intent: AgentAfterNavigationIntent = {
+    openChat: true,
+    focusChatInput: true,
+    expiresAt: Date.now() + DEFAULT_TTL_MS,
+  };
+  if (options.resume?.historyMessages?.length) {
+    intent.resume = {
+      message: options.resume.message?.trim() || DEFAULT_RESUME_MESSAGE,
+      historyMessages: options.resume.historyMessages,
+    };
+  }
+  storage.setItem(STORAGE_KEY, JSON.stringify(intent));
+};
+
+export const consumeAgentAfterNavigationIntent = (
+  storage: Storage = window.sessionStorage,
+): AgentAfterNavigationIntent | undefined => {
+  const raw = storage.getItem(STORAGE_KEY);
+  storage.removeItem(STORAGE_KEY);
+  if (!raw) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as Partial<AgentAfterNavigationIntent>;
+    if (typeof parsed.expiresAt !== "number" || parsed.expiresAt < Date.now()) {
+      return undefined;
+    }
+    return {
+      openChat: parsed.openChat === true,
+      focusChatInput: parsed.focusChatInput !== false,
+      resume: normalizeResume(parsed.resume),
+      expiresAt: parsed.expiresAt,
+    };
+  } catch {
+    return undefined;
+  }
+};
+
+const normalizeResume = (
+  resume: unknown,
+): AgentAfterNavigationResume | undefined => {
+  if (typeof resume !== "object" || resume === null) {
+    return undefined;
+  }
+  const candidate = resume as Partial<AgentAfterNavigationResume>;
+  if (
+    typeof candidate.message !== "string" ||
+    !candidate.message.trim() ||
+    !Array.isArray(candidate.historyMessages)
+  ) {
+    return undefined;
+  }
+  return {
+    message: candidate.message.trim(),
+    historyMessages: candidate.historyMessages,
+  };
+};
diff --git a/packages/live2d/src/api/agent-tool-runtime.ts b/packages/live2d/src/api/agent-tool-runtime.ts
new file mode 100644
index 0000000..3c44f0a
--- /dev/null
+++ b/packages/live2d/src/api/agent-tool-runtime.ts
@@ -0,0 +1,695 @@
+import { rememberAgentAfterNavigationIntent } from "@/live2d/api/agent-navigation-intent";
+import type { AgentRuntimeConfig } from "@/live2d/config/agent-tools/agent-tool-config";
+import { normalizeAgentRuntimeConfig } from "@/live2d/config/agent-tools/normalize-agent-tools";
+import { sendMessage } from "@/live2d/helpers/sendMessage";
+import type { ToolPart, UIMessage } from "@halo-dev/ai-foundation-sdk";
+
+export interface AgentToolRuntimeOptions {
+  config?: AgentRuntimeConfig;
+}
+
+export interface AgentToolResult {
+  ok: boolean;
+  [key: string]: unknown;
+}
+
+type RegisteredExecutor = (context: {
+  input: Record<string, unknown>;
+  toolName: string;
+}) => Promise<unknown> | unknown;
+
+interface TrustedResource {
+  resourceId: string;
+  permalink: string;
+  title?: string;
+}
+
+const registeredExecutors = new Map<string, RegisteredExecutor>();
+
+declare global {
+  interface Window {
+    Live2DAI?: {
+      registerTool: (name: string, executor: RegisteredExecutor) => void;
+    };
+  }
+}
+
+const ensureGlobalRegistry = () => {
+  if (window.Live2DAI) {
+    return;
+  }
+  window.Live2DAI = {
+    registerTool(name, executor) {
+      if (!/^[a-z][a-z0-9_]{2,63}$/.test(name)) {
+        return;
+      }
+      registeredExecutors.set(name, executor);
+    },
+  };
+};
+
+ensureGlobalRegistry();
+
+export class AgentToolRuntime {
+  private readonly config: AgentRuntimeConfig;
+  private readonly trustedResources = new Map<string, TrustedResource>();
+
+  constructor(options: AgentToolRuntimeOptions = {}) {
+    this.config = normalizeAgentRuntimeConfig(options.config);
+  }
+
+  canExecute(toolName: string): boolean {
+    return (
+      this.builtInToolNames().has(toolName) ||
+      this.config.aiTools.some((tool) => tool.name === toolName)
+    );
+  }
+
+  ingestMessages(messages: UIMessage[]): void {
+    for (const message of messages) {
+      for (const part of message.parts) {
+        if (!isToolPart(part) || part.state !== "output-available") {
+          continue;
+        }
+        this.ingestToolOutput(part.output);
+      }
+    }
+  }
+
+  async execute(part: ToolPart): Promise<AgentToolResult> {
+    const input = part.input ?? {};
+    try {
+      if (part.toolName === "get_current_page_context") {
+        return this.getCurrentPageContext();
+      }
+      if (part.toolName === "open_halo_resource") {
+        return this.openHaloResource(input);
+      }
+      if (part.toolName === "open_comment_area") {
+        return this.scrollToCommentArea();
+      }
+      if (part.toolName === "draft_comment") {
+        if (this.config.builtIn.commentCapability === "off") {
+          return failure("TOOL_NOT_ALLOWED", "评论辅助能力未启用");
+        }
+        return this.fillCommentDraft(input);
+      }
+      if (part.toolName === "submit_comment") {
+        if (this.config.builtIn.commentCapability !== "submit") {
+          return failure("TOOL_NOT_ALLOWED", "评论提交能力未启用");
+        }
+        return this.submitComment(input);
+      }
+      const customTool = this.config.aiTools.find(
+        (tool) => tool.name === part.toolName,
+      );
+      if (!customTool) {
+        return failure("TOOL_NOT_FOUND", "这个功能还没有配置好");
+      }
+      const action = customTool.action;
+      if (this.requiresApproval(customTool.approval, action)) {
+        const approved = await this.requestApproval(
+          `要我帮你执行「${customTool.description}」吗？`,
+        );
+        if (!approved) {
+          return failure("TOOL_APPROVAL_DENIED", "访客取消了这次操作");
+        }
+      }
+      this.showStatus(action.pendingMessage ?? "我来帮你处理一下～");
+      let result: AgentToolResult;
+      switch (action.type) {
+        case "navigate":
+          result = this.navigate(action.url, action.target);
+          break;
+        case "scroll-to":
+          result = this.scrollToSelector(action.selector, action.behavior);
+          break;
+        case "highlight":
+          result = this.highlight(action.selector, action.duration);
+          break;
+        case "dispatch-event":
+          window.dispatchEvent(
+            new CustomEvent(action.event, {
+              detail: input,
+            }),
+          );
+          result = { ok: true };
+          break;
+        case "registered": {
+          const executor = registeredExecutors.get(part.toolName);
+          if (!executor) {
+            return failure(
+              "TOOL_EXECUTOR_NOT_FOUND",
+              "这个站点还没有启用对应能力",
+            );
+          }
+          result = {
+            ok: true,
+            output: await executor({ input, toolName: part.toolName }),
+          };
+          break;
+        }
+      }
+      this.showStatus(
+        result.ok
+          ? (action.successMessage ?? "已经处理好啦～")
+          : (action.errorMessage ?? "这个功能暂时没处理成功～"),
+      );
+      return result;
+    } catch (error) {
+      return failure(
+        "TOOL_EXECUTION_FAILED",
+        error instanceof Error ? error.message : "工具执行失败",
+      );
+    }
+  }
+
+  private builtInToolNames(): Set<string> {
+    const names = new Set<string>();
+    const builtIn = this.config.builtIn;
+    if (builtIn.pageContext) {
+      names.add("get_current_page_context");
+    }
+    if (builtIn.haloNavigation) {
+      names.add("open_halo_resource");
+    }
+    if (builtIn.commentCapability !== "off") {
+      names.add("open_comment_area");
+      names.add("draft_comment");
+    }
+    if (builtIn.commentCapability === "submit") {
+      names.add("submit_comment");
+    }
+    return names;
+  }
+
+  private getCurrentPageContext(): AgentToolResult {
+    const selectedText = window.getSelection()?.toString().trim() ?? "";
+    const commentInput = this.findCommentInput();
+    const commentArea = this.findCommentArea();
+    const commentSubmit = commentInput?.container
+      ? this.findCommentSubmitButton(commentInput.container)
+      : undefined;
+    return {
+      ok: true,
+      title: document.title,
+      url: window.location.href,
+      path: window.location.pathname,
+      description:
+        document
+          .querySelector<HTMLMetaElement>("meta[name='description']")
+          ?.content.trim() ?? "",
+      headings: this.collectHeadings(),
+      selectedText: selectedText.slice(0, 1000),
+      capabilities: {
+        comment: {
+          hasArea: !!commentArea,
+          hasInput: !!commentInput,
+          hasSubmitButton: !!commentSubmit,
+          reason: !commentArea
+            ? "当前页面没有检测到评论区"
+            : !commentInput
+              ? "当前页面有评论区，但没有检测到可写评论输入框"
+              : !commentSubmit
+                ? "当前页面有可写评论输入框，但没有检测到提交按钮"
+                : "当前页面支持填写评论",
+        },
+        forms: this.collectFormSummaries(),
+        links: this.collectLinkSummaries(),
+      },
+    };
+  }
+
+  private openHaloResource(input: Record<string, unknown>): AgentToolResult {
+    const resourceId = stringInput(input.resourceId);
+    if (!resourceId) {
+      return failure("INVALID_INPUT", "resourceId is required");
+    }
+    const resource = this.trustedResources.get(resourceId);
+    if (!resource) {
+      return failure("RESOURCE_NOT_TRUSTED", "没有找到可信资源");
+    }
+    this.showStatus("我带你过去看看～");
+    window.setTimeout(() => {
+      rememberAgentAfterNavigationIntent();
+      window.location.assign(resource.permalink);
+    }, 50);
+    return { ok: true, navigating: true, pageReload: true, resourceId };
+  }
+
+  private scrollToCommentArea(): AgentToolResult {
+    const commentArea = this.findCommentArea();
+    if (!commentArea) {
+      this.showStatus("当前页面没有检测到评论区");
+      return failure("COMMENT_AREA_NOT_FOUND", "当前页面没有检测到评论区");
+    }
+    commentArea.scrollIntoView?.({ behavior: "smooth", block: "center" });
+    this.showStatus("已经帮你定位到评论区啦～");
+    return { ok: true };
+  }
+
+  private fillCommentDraft(input: Record<string, unknown>): AgentToolResult {
+    const content = stringInput(input.content);
+    if (!content) {
+      return failure("INVALID_INPUT", "content is required");
+    }
+    const target = this.findCommentInput();
+    if (!target) {
+      this.scrollToCommentArea();
+      return failure(
+        "COMMENT_INPUT_NOT_FOUND",
+        this.findCommentArea()
+          ? "当前页面有评论区，但没有找到可写评论输入框"
+          : "当前页面没有检测到评论区，无法填写评论",
+      );
+    }
+    target.container?.scrollIntoView?.({ behavior: "smooth", block: "center" });
+    this.writeCommentInput(target.input, content);
+    target.input.focus();
+    this.showStatus("评论草稿已经帮你填好了～");
+    return { ok: true, drafted: true };
+  }
+
+  private submitComment(input: Record<string, unknown>): AgentToolResult {
+    const draftResult = this.fillCommentDraft(input);
+    if (!draftResult.ok) {
+      return draftResult;
+    }
+    const target = this.findCommentInput();
+    const submitButton = target?.container
+      ? this.findCommentSubmitButton(target.container)
+      : undefined;
+    if (!submitButton) {
+      return failure("COMMENT_SUBMIT_NOT_FOUND", "没有找到评论提交按钮");
+    }
+    submitButton.click();
+    this.showStatus("已经尝试提交评论啦～");
+    return { ok: true, submitted: true };
+  }
+
+  private navigate(
+    url: string,
+    target: "_self" | "_blank" = "_self",
+  ): AgentToolResult {
+    const destination = new URL(url, window.location.origin);
+    if (!this.isAllowedUrl(destination)) {
+      return failure("URL_NOT_ALLOWED", "这个链接不在允许范围内");
+    }
+    const useBlank =
+      target === "_blank" && this.config.toolSecurity.allowNewTab;
+    window.setTimeout(() => {
+      if (useBlank) {
+        window.open(destination.href, "_blank", "noopener,noreferrer");
+      } else {
+        rememberAgentAfterNavigationIntent();
+        window.location.assign(destination.href);
+      }
+    }, 50);
+    return {
+      ok: true,
+      navigating: true,
+      pageReload: !useBlank,
+      url: destination.href,
+    };
+  }
+
+  private scrollToSelector(
+    selector: string,
+    behavior: ScrollBehavior = "smooth",
+  ): AgentToolResult {
+    const element = document.querySelector(selector);
+    if (!element) {
+      return failure("ELEMENT_NOT_FOUND", "没有找到对应的位置");
+    }
+    element.scrollIntoView?.({ behavior, block: "center" });
+    return { ok: true };
+  }
+
+  private highlight(selector: string, duration = 1600): AgentToolResult {
+    const element = document.querySelector<HTMLElement>(selector);
+    if (!element) {
+      return failure("ELEMENT_NOT_FOUND", "没有找到对应的位置");
+    }
+    const previousOutline = element.style.outline;
+    const previousOutlineOffset = element.style.outlineOffset;
+    element.style.outline = "2px solid #ffab5c";
+    element.style.outlineOffset = "3px";
+    window.setTimeout(() => {
+      element.style.outline = previousOutline;
+      element.style.outlineOffset = previousOutlineOffset;
+    }, duration);
+    return { ok: true };
+  }
+
+  private isAllowedUrl(url: URL): boolean {
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return false;
+    }
+    if (url.origin === window.location.origin) {
+      return true;
+    }
+    return this.config.toolSecurity.allowedExternalOrigins.includes(url.origin);
+  }
+
+  private requiresApproval(
+    approval: "default" | "never" | "always",
+    action: { type: string; url?: string },
+  ): boolean {
+    if (approval === "always") {
+      return true;
+    }
+    if (approval === "never") {
+      return false;
+    }
+    if (action.type === "registered" || action.type === "dispatch-event") {
+      return true;
+    }
+    if (action.type === "navigate" && action.url) {
+      const destination = new URL(action.url, window.location.origin);
+      return destination.origin !== window.location.origin;
+    }
+    return false;
+  }
+
+  requestApproval(message: string): Promise<boolean> {
+    return new Promise((resolve) => {
+      const existing = document.getElementById("live2d-agent-approval");
+      existing?.remove();
+      const container = document.createElement("div");
+      container.id = "live2d-agent-approval";
+      container.style.cssText = [
+        "position:fixed",
+        "left:50%",
+        "bottom:5.5rem",
+        "z-index:10001",
+        "transform:translateX(-50%)",
+        "display:flex",
+        "align-items:center",
+        "gap:.5rem",
+        "max-width:min(28rem,calc(100vw - 1rem))",
+        "padding:.5rem .625rem",
+        "border:1px solid #eadfce",
+        "border-radius:.75rem",
+        "background:rgba(255,250,244,.98)",
+        "box-shadow:0 10px 24px rgba(15,23,42,.12)",
+        "font-size:13px",
+        "color:#334155",
+      ].join(";");
+      const text = document.createElement("span");
+      text.textContent = message;
+      text.style.cssText = "line-height:1.4;min-width:0;flex:1;";
+      const allow = document.createElement("button");
+      allow.type = "button";
+      allow.textContent = "允许";
+      allow.style.cssText = buttonStyle("#ffab5c", "#fff");
+      const deny = document.createElement("button");
+      deny.type = "button";
+      deny.textContent = "取消";
+      deny.style.cssText = buttonStyle("#eee7de", "#475569");
+      const cleanup = (approved: boolean) => {
+        container.remove();
+        resolve(approved);
+      };
+      allow.addEventListener("click", () => cleanup(true), { once: true });
+      deny.addEventListener("click", () => cleanup(false), { once: true });
+      container.append(text, allow, deny);
+      document.body.append(container);
+    });
+  }
+
+  private ingestToolOutput(output: unknown): void {
+    if (!output || typeof output !== "object") {
+      return;
+    }
+    const resources = (output as { resources?: unknown }).resources;
+    if (!Array.isArray(resources)) {
+      return;
+    }
+    for (const resource of resources) {
+      if (!resource || typeof resource !== "object") {
+        continue;
+      }
+      const item = resource as Partial<TrustedResource>;
+      if (item.resourceId && item.permalink) {
+        this.trustedResources.set(item.resourceId, {
+          resourceId: item.resourceId,
+          permalink: item.permalink,
+          title: item.title,
+        });
+      }
+    }
+  }
+
+  private showStatus(message?: string): void {
+    if (message) {
+      sendMessage(message, 3000, 3);
+    }
+  }
+
+  private findCommentInput():
+    | { container: Element | undefined; input: WritableCommentInput }
+    | undefined {
+    const containers = this.commentContainers();
+    for (const container of containers) {
+      const input = this.findWritableCommentInput(container);
+      if (input) {
+        return { container, input };
+      }
+    }
+    return this.findWritableCommentInput(document.body)
+      ? {
+          container: undefined,
+          input: this.findWritableCommentInput(
+            document.body,
+          ) as WritableCommentInput,
+        }
+      : undefined;
+  }
+
+  private commentContainers(): Element[] {
+    const selectors = [
+      "#comment",
+      "#comments",
+      "halo-comment",
+      "[data-comment]",
+      ".comment",
+      ".comments",
+      ".comment-form",
+    ].join(",");
+    return [...document.querySelectorAll(selectors)];
+  }
+
+  private findCommentArea(): Element | undefined {
+    return this.commentContainers()[0];
+  }
+
+  private collectHeadings(): Array<{ level: number; text: string }> {
+    return [...document.querySelectorAll<HTMLHeadingElement>("h1,h2,h3")]
+      .map((heading) => ({
+        level: Number(heading.tagName.slice(1)),
+        text: (heading.textContent ?? "").trim(),
+      }))
+      .filter((heading) => heading.text)
+      .slice(0, 8);
+  }
+
+  private collectFormSummaries(): Array<{
+    id?: string;
+    name?: string;
+    fields: string[];
+    submitLabels: string[];
+  }> {
+    return [...document.querySelectorAll<HTMLFormElement>("form")]
+      .map((form) => ({
+        id: form.id || undefined,
+        name: form.getAttribute("name") || undefined,
+        fields: [
+          ...form.querySelectorAll<
+            HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
+          >("input,textarea,select"),
+        ]
+          .map(
+            (field) =>
+              field.getAttribute("name") ||
+              field.getAttribute("aria-label") ||
+              field.id,
+          )
+          .filter((field): field is string => !!field)
+          .slice(0, 12),
+        submitLabels: [
+          ...form.querySelectorAll<HTMLButtonElement | HTMLInputElement>(
+            "button,input[type='submit']",
+          ),
+        ]
+          .map((button) =>
+            (
+              button.textContent ||
+              button.getAttribute("value") ||
+              button.getAttribute("aria-label") ||
+              ""
+            ).trim(),
+          )
+          .filter((label) => label)
+          .slice(0, 6),
+      }))
+      .slice(0, 6);
+  }
+
+  private collectLinkSummaries(): Array<{ text: string; href: string }> {
+    return [...document.querySelectorAll<HTMLAnchorElement>("a[href]")]
+      .map((link) => ({
+        text: (link.textContent ?? "").trim().replace(/\s+/g, " "),
+        href: link.href,
+      }))
+      .filter(
+        (link) => link.text && link.href.startsWith(window.location.origin),
+      )
+      .slice(0, 10);
+  }
+
+  private findWritableCommentInput(
+    root: ParentNode,
+  ): WritableCommentInput | undefined {
+    const selectors = [
+      "textarea:not([disabled]):not([readonly])",
+      "[contenteditable='true']",
+      "[contenteditable='']",
+      "input[name='content']:not([disabled]):not([readonly])",
+      "input[name='comment']:not([disabled]):not([readonly])",
+    ];
+    for (const selector of selectors) {
+      const found = this.deepQuerySelector<WritableCommentInput>(
+        root,
+        selector,
+      );
+      if (found && this.isWritableCommentInput(found)) {
+        return found;
+      }
+    }
+    return undefined;
+  }
+
+  private findCommentSubmitButton(root: ParentNode): HTMLElement | undefined {
+    const selectors = [
+      "button[type='submit']:not([disabled])",
+      "input[type='submit']:not([disabled])",
+      "button:not([disabled])",
+      "[role='button']:not([aria-disabled='true'])",
+    ];
+    for (const selector of selectors) {
+      const elements = this.deepQuerySelectorAll<HTMLElement>(root, selector);
+      const submit = elements.find((element) => {
+        const text = `${element.textContent ?? ""} ${
+          element.getAttribute("aria-label") ?? ""
+        } ${element.getAttribute("value") ?? ""}`.trim();
+        return /提交|评论|发送|发布|回复|submit|send|post|reply/i.test(text);
+      });
+      if (submit) {
+        return submit;
+      }
+    }
+    return undefined;
+  }
+
+  private deepQuerySelector<T extends Element>(
+    root: ParentNode,
+    selector: string,
+  ): T | undefined {
+    return this.deepQuerySelectorAll<T>(root, selector)[0];
+  }
+
+  private deepQuerySelectorAll<T extends Element>(
+    root: ParentNode,
+    selector: string,
+  ): T[] {
+    const results: T[] = [];
+    const visit = (node: ParentNode) => {
+      if ("querySelectorAll" in node) {
+        results.push(
+          ...[
+            ...(
+              node as Document | DocumentFragment | Element
+            ).querySelectorAll<T>(selector),
+          ],
+        );
+        for (const element of [
+          ...(node as Document | DocumentFragment | Element).querySelectorAll(
+            "*",
+          ),
+        ]) {
+          if (element.shadowRoot) {
+            visit(element.shadowRoot);
+          }
+        }
+      }
+    };
+    visit(root);
+    return results;
+  }
+
+  private isWritableCommentInput(
+    input: Element,
+  ): input is WritableCommentInput {
+    return (
+      input instanceof HTMLTextAreaElement ||
+      input instanceof HTMLInputElement ||
+      (input instanceof HTMLElement && input.isContentEditable)
+    );
+  }
+
+  private writeCommentInput(
+    input: WritableCommentInput,
+    content: string,
+  ): void {
+    if (
+      input instanceof HTMLTextAreaElement ||
+      input instanceof HTMLInputElement
+    ) {
+      const descriptor = Object.getOwnPropertyDescriptor(
+        Object.getPrototypeOf(input),
+        "value",
+      );
+      descriptor?.set?.call(input, content);
+    } else {
+      input.textContent = content;
+    }
+    const inputEvent =
+      typeof InputEvent === "function"
+        ? new InputEvent("input", {
+            bubbles: true,
+            inputType: "insertText",
+            data: content,
+          })
+        : new Event("input", { bubbles: true });
+    input.dispatchEvent(inputEvent);
+    input.dispatchEvent(new Event("change", { bubbles: true }));
+  }
+}
+
+const stringInput = (value: unknown): string | undefined =>
+  typeof value === "string" && value.trim() ? value.trim() : undefined;
+
+const failure = (errorCode: string, message: string): AgentToolResult => ({
+  ok: false,
+  errorCode,
+  message,
+});
+
+const buttonStyle = (background: string, color: string): string =>
+  [
+    "border:none",
+    "border-radius:999px",
+    "padding:.25rem .625rem",
+    "font-size:12px",
+    "cursor:pointer",
+    `background:${background}`,
+    `color:${color}`,
+  ].join(";");
+
+const isToolPart = (part: UIMessage["parts"][number]): part is ToolPart =>
+  part.type.startsWith("tool-");
+
+type WritableCommentInput =
+  | HTMLTextAreaElement
+  | HTMLInputElement
+  | HTMLElement;
diff --git a/packages/live2d/src/api/chat-api.ts b/packages/live2d/src/api/chat-api.ts
index 4dcfc86..5b958f1 100644
--- a/packages/live2d/src/api/chat-api.ts
+++ b/packages/live2d/src/api/chat-api.ts
@@ -1,18 +1,32 @@
+import { rememberAgentAfterNavigationIntent } from "@/live2d/api/agent-navigation-intent";
+import { AgentToolRuntime } from "@/live2d/api/agent-tool-runtime";
+import type { AgentRuntimeConfig } from "@/live2d/config/agent-tools/agent-tool-config";
 import { createStreamMessage } from "@/live2d/helpers/createStreamMessage";
 import { sendMessage } from "@/live2d/helpers/sendMessage";
+import {
+  Chat,
+  DefaultChatTransport,
+  type ToolPart,
+  type UIMessage,
+  lastAssistantMessageHasCompletedToolContinuations,
+  pruneMessages,
+  validateUIMessages,
+} from "@halo-dev/ai-foundation-sdk";
+
+const DEFAULT_REASONING_MESSAGES = [
+  "我正在认真想一想～",
+  "让我整理一下思路，很快就好～",
+  "稍等一下，我正在组织语言呢～",
+];
+const WAITING_MESSAGE = "正在接收来自母星的消息，请耐心等待～";
 
 /**
  * 聊天消息角色
  */
-export type ChatRole = "user" | "assistant";
-
 /**
  * 聊天消息
  */
-export interface ChatMessage {
-  role: ChatRole;
-  content: string;
-}
+export type ChatMessage = UIMessage;
 
 /**
  * 聊天 API 配置
@@ -24,14 +38,18 @@ export interface ChatApiConfig {
   chunkTimeout?: number;
   // 消息显示时间（秒）
   showChatMessageTimeout?: number;
-}
-
-/**
- * 聊天响应结果
- */
-export interface ChatResponse {
-  text: string;
-  status: number;
+  // Agent 自动续写时，上一段助手消息最短可见时间（毫秒）
+  autoContinuationMessageMinVisibleMs?: number;
+  // 请求已收到时的即时提示语
+  requestAcceptedMessage?: string;
+  // 模型思考阶段的提示语
+  reasoningMessages?: string[] | string | { message?: string }[];
+  // 思考提示语轮换间隔（秒）
+  reasoningMessageInterval?: number;
+  // 保留上下文轮数
+  chatContextRounds?: number;
+  // Agent 能力运行时配置
+  agent?: AgentRuntimeConfig;
 }
 
 /**
@@ -39,7 +57,8 @@ export interface ChatResponse {
  */
 export class ChatApi {
   private config: ChatApiConfig;
-  private controller: AbortController | null = null;
+  private chat: Chat | null = null;
+  private agentRuntime: AgentToolRuntime;
   private requestTimeoutId: number | null = null;
   private messageTimer: number | null = null;
 
@@ -50,7 +69,24 @@ export class ChatApi {
         "/apis/api.live2d.halo.run/v1alpha1/live2d/ai/chat-process",
       chunkTimeout: config.chunkTimeout || 60,
       showChatMessageTimeout: config.showChatMessageTimeout || 10,
+      autoContinuationMessageMinVisibleMs:
+        this.normalizeAutoContinuationMessageMinVisibleMs(
+          config.autoContinuationMessageMinVisibleMs,
+        ),
+      requestAcceptedMessage:
+        config.requestAcceptedMessage || "收到啦，马上就来陪你啦～",
+      reasoningMessages: this.normalizeReasoningMessages(
+        config.reasoningMessages,
+      ),
+      reasoningMessageInterval: this.normalizeReasoningMessageInterval(
+        config.reasoningMessageInterval,
+      ),
+      chatContextRounds: this.normalizeContextRounds(config.chatContextRounds),
+      agent: config.agent,
     };
+    this.agentRuntime = new AgentToolRuntime({
+      config: this.config.agent,
+    });
   }
 
   /**
@@ -63,15 +99,9 @@ export class ChatApi {
     message: string,
     historyMessages: ChatMessage[],
   ): Promise<void> {
-    // 添加用户消息到历史
-    const userMessage: ChatMessage = {
-      role: "user",
-      content: message,
-    };
-    historyMessages.push(userMessage);
-
-    // 创建 AbortController 用于取消请求
-    this.controller = new AbortController();
+    const trimmedHistory = this.trimHistory(
+      this.normalizeHistory(historyMessages),
+    );
 
     // 设置请求超时
     const timeoutMs = (this.config.chunkTimeout || 60) * 1000;
@@ -79,42 +109,14 @@ export class ChatApi {
       this.abort();
     }, timeoutMs) as unknown as number;
 
-    // 显示等待消息
-    if (this.messageTimer) {
-      clearTimeout(this.messageTimer);
-      this.messageTimer = null;
-    }
-    this.messageTimer = setTimeout(() => {
-      sendMessage("正在接收来自母星的消息，请耐心等待～", 2000, 2);
-    }, 5000) as unknown as number;
-
     try {
       const apiEndpoint = this.config.apiEndpoint;
       if (!apiEndpoint) {
         throw new Error("API endpoint is not configured");
       }
 
-      const response = await fetch(apiEndpoint, {
-        method: "POST",
-        cache: "no-cache",
-        keepalive: true,
-        headers: {
-          "Content-Type": "application/json",
-          Accept: "text/event-stream",
-        },
-        body: JSON.stringify({
-          message: historyMessages,
-        }),
-        signal: this.controller.signal,
-      });
-
-      if (!response.ok) {
-        this.handleErrorResponse(response);
-        return;
-      }
-
       // 处理流式响应
-      await this.handleStreamResponse(response, historyMessages);
+      await this.handleStreamResponse(apiEndpoint, message, trimmedHistory);
     } catch (error) {
       if ((error as Error).name !== "AbortError") {
         console.error("[Chat API] Request failed:", error);
@@ -125,24 +127,12 @@ export class ChatApi {
     }
   }
 
-  /**
-   * 处理错误响应
-   */
-  private handleErrorResponse(response: Response): void {
-    if (response.status === 401) {
-      sendMessage("请先登录！", 2000, 4);
-    } else {
-      sendMessage("对话接口异常了哦～快去联系我的主人吧！", 5000, 4);
-    }
-    console.error("[Chat API] Response error:", response);
-    this.abort();
-  }
-
   /**
    * 处理流式响应
    */
   private async handleStreamResponse(
-    response: Response,
+    apiEndpoint: string,
+    messageTextValue: string,
     historyMessages: ChatMessage[],
   ): Promise<void> {
     // 清除定时器
@@ -159,70 +149,400 @@ export class ChatApi {
     const streamTimeout = (this.config.chunkTimeout || 60) * 1000;
     const showTimeout = (this.config.showChatMessageTimeout || 10) * 1000;
     const chat = createStreamMessage(streamTimeout, showTimeout);
+    chat.setMessage(this.config.requestAcceptedMessage || "");
 
-    if (!response.body) {
-      throw new Error("Response body is null");
-    }
-
-    const reader = response.body.getReader();
-    const textDecoder = new TextDecoder();
-
-    const chatMessage: ChatMessage = {
-      role: "assistant",
-      content: "",
+    let unsubscribe: (() => void) | undefined;
+    let hasVisibleAssistantContent = false;
+    let waitingMessageTimer: number | null = setTimeout(() => {
+      if (!hasVisibleAssistantContent) {
+        chat.setMessage(WAITING_MESSAGE);
+      }
+      waitingMessageTimer = null;
+    }, 5000) as unknown as number;
+    let reasoningMessageTimer: number | null = null;
+    let reasoningMessageVisible = false;
+    const stopWaitingMessage = () => {
+      if (waitingMessageTimer) {
+        clearTimeout(waitingMessageTimer);
+        waitingMessageTimer = null;
+      }
+    };
+    const stopReasoningMessages = () => {
+      if (reasoningMessageTimer) {
+        clearInterval(reasoningMessageTimer);
+        reasoningMessageTimer = null;
+      }
+    };
+    const showReasoningMessage = () => {
+      const message = this.pickReasoningMessage();
+      if (!message) {
+        return;
+      }
+      stopWaitingMessage();
+      hasVisibleAssistantContent = true;
+      reasoningMessageVisible = true;
+      chat.setMessage(message);
+    };
+    const startReasoningMessages = () => {
+      if (reasoningMessageTimer) {
+        return;
+      }
+      showReasoningMessage();
+      reasoningMessageTimer = setInterval(
+        showReasoningMessage,
+        (this.config.reasoningMessageInterval || 5) * 1000,
+      ) as unknown as number;
+    };
+    let streamedText = "";
+    let displayedTextAnchor = "";
+    let displayedTextBaseline = "";
+    let lastVisibleAssistantText = "";
+    let lastVisibleAssistantTextAt = 0;
+    let automaticContinuationHoldUntil = 0;
+    let deferredReplaceText: string | null = null;
+    let deferredReplaceTimer: number | null = null;
+    const markVisibleAssistantText = (text: string) => {
+      lastVisibleAssistantText = text;
+      lastVisibleAssistantTextAt = Date.now();
+    };
+    const clearDeferredReplaceTimer = () => {
+      if (deferredReplaceTimer) {
+        clearTimeout(deferredReplaceTimer);
+        deferredReplaceTimer = null;
+      }
+    };
+    const flushDeferredReplace = () => {
+      if (deferredReplaceText === null) {
+        return;
+      }
+      const text = deferredReplaceText;
+      deferredReplaceText = null;
+      clearDeferredReplaceTimer();
+      stopWaitingMessage();
+      stopReasoningMessages();
+      hasVisibleAssistantContent = true;
+      chat.setMessage(text);
+      reasoningMessageVisible = false;
+      streamedText = text;
+      markVisibleAssistantText(text);
+    };
+    const scheduleDeferredReplace = (text: string) => {
+      deferredReplaceText = text;
+      const remaining = automaticContinuationHoldUntil - Date.now();
+      if (remaining <= 0) {
+        flushDeferredReplace();
+        return false;
+      }
+      if (!deferredReplaceTimer) {
+        deferredReplaceTimer = setTimeout(
+          flushDeferredReplace,
+          remaining,
+        ) as unknown as number;
+      }
+      return true;
+    };
+    const shouldHoldAutomaticContinuationReplace = (
+      willReplaceIncomingText: boolean,
+    ) =>
+      willReplaceIncomingText &&
+      lastVisibleAssistantText.length > 0 &&
+      automaticContinuationHoldUntil > Date.now();
+    const shouldKeepVisibleAssistantTextDuringToolWait = () =>
+      (this.config.autoContinuationMessageMinVisibleMs ?? 0) > 0 &&
+      lastVisibleAssistantText.length > 0;
+    const waitForDeferredReplace = async () => {
+      if (deferredReplaceText === null) {
+        return;
+      }
+      const remaining = automaticContinuationHoldUntil - Date.now();
+      if (remaining > 0) {
+        await new Promise((resolve) => setTimeout(resolve, remaining));
+      }
+      flushDeferredReplace();
     };
-
     try {
-      while (true) {
-        const { value, done } = await reader.read();
-        if (done) {
-          break;
-        }
-
-        const text = textDecoder.decode(value);
-        const textArrays = text.split("\n\n");
-
-        for (let decoderText of textArrays) {
-          if (!decoderText) continue;
-
-          // 移除 "data:" 前缀
-          if (decoderText.startsWith("data:")) {
-            const dataIndex = decoderText.indexOf("data:");
-            if (dataIndex !== -1) {
-              decoderText = decoderText.substring(dataIndex + 5);
-            }
+      const pendingContinuations = new Set<Promise<void>>();
+      const queuedToolCalls = new Map<string, ToolPart>();
+      const submittedAutomaticContinuationKeys = new Set<string>();
+      const trackContinuation = (continuation: Promise<void>) => {
+        const tracked = continuation.finally(() =>
+          pendingContinuations.delete(tracked),
+        );
+        pendingContinuations.add(tracked);
+        return tracked;
+      };
+      const waitForContinuations = async () => {
+        while (pendingContinuations.size > 0 || queuedToolCalls.size > 0) {
+          flushQueuedToolCalls();
+          if (pendingContinuations.size === 0) {
+            break;
           }
-
-          try {
-            const chatResult: ChatResponse = JSON.parse(decoderText);
-            const { text, status } = chatResult;
-
-            if (status === 200) {
-              if (text === "[DONE]") {
-                // 消息接收完成，保存到历史记录
-                historyMessages.push(chatMessage);
-                localStorage.setItem(
-                  "historyMessages",
-                  JSON.stringify(historyMessages),
+          await Promise.allSettled([...pendingContinuations]);
+        }
+      };
+      let sdkChat: Chat;
+      const handledToolCalls = new Set<string>();
+      const shouldQueueToolCall = () =>
+        sdkChat.status === "submitted" || sdkChat.status === "streaming";
+      const executeToolCall = (part: ToolPart) => {
+        if (handledToolCalls.has(part.toolCallId)) {
+          return;
+        }
+        if (shouldQueueToolCall()) {
+          queuedToolCalls.set(part.toolCallId, part);
+          return;
+        }
+        handledToolCalls.add(part.toolCallId);
+        if (!this.agentRuntime.canExecute(part.toolName)) {
+          return trackContinuation(
+            sdkChat
+              .addToolOutput({
+                toolCallId: part.toolCallId,
+                toolName: part.toolName,
+                state: "output-error",
+                errorText: "当前页面没有启用这个浏览器能力",
+              })
+              .then(() => undefined),
+          );
+        }
+        return trackContinuation(
+          this.agentRuntime
+            .execute(part)
+            .then((output) => {
+              if (this.shouldResumeAfterNavigation(output)) {
+                rememberAgentAfterNavigationIntent({
+                  resume: {
+                    historyMessages: this.historyWithToolOutput(
+                      sdkChat.messages,
+                      part,
+                      output,
+                    ),
+                  },
+                });
+              }
+              return sdkChat
+                .addToolOutput({
+                  toolCallId: part.toolCallId,
+                  toolName: part.toolName,
+                  output,
+                })
+                .then(() => output);
+            })
+            .then((output) => {
+              if (this.shouldResumeAfterNavigation(output)) {
+                rememberAgentAfterNavigationIntent({
+                  resume: {
+                    historyMessages: this.stabilizeHistory(sdkChat.messages),
+                  },
+                });
+              }
+            })
+            .then(() => undefined),
+        );
+      };
+      const flushQueuedToolCalls = () => {
+        if (shouldQueueToolCall() || queuedToolCalls.size === 0) {
+          return;
+        }
+        const parts = [...queuedToolCalls.values()];
+        queuedToolCalls.clear();
+        for (const part of parts) {
+          executeToolCall(part);
+        }
+      };
+      sdkChat = new Chat({
+        id: "live2d-chat",
+        messages: historyMessages,
+        transport: new DefaultChatTransport({
+          api: apiEndpoint,
+          prepareSendMessagesRequest: (request) => {
+            const continuationKeys = this.automaticContinuationKeys(
+              request.messages,
+            );
+            if (continuationKeys.length > 0) {
+              for (const key of continuationKeys) {
+                submittedAutomaticContinuationKeys.add(key);
+              }
+              const minVisibleMs =
+                this.config.autoContinuationMessageMinVisibleMs ?? 0;
+              if (
+                minVisibleMs > 0 &&
+                lastVisibleAssistantText.length > 0 &&
+                lastVisibleAssistantTextAt > 0
+              ) {
+                automaticContinuationHoldUntil = Math.max(
+                  automaticContinuationHoldUntil,
+                  lastVisibleAssistantTextAt + minVisibleMs,
                 );
-                chat.stop();
-              } else {
-                // 追加文本片段
-                chatMessage.content += text;
-                chat.sendMessage(text);
               }
-            } else {
-              throw new Error(text);
             }
-          } catch (e) {
-            console.error("[Chat API] Parse error:", decoderText, e);
-            chat.sendMessage(`聊天接口出现异常了：${decoderText}`);
+            return {};
+          },
+        }),
+        onError: (error) => {
+          console.error("[Chat API] Stream error:", error);
+        },
+        onToolCall: (part) => {
+          return executeToolCall(part);
+        },
+        sendAutomaticallyWhen: ({ messages }) => {
+          const continuationKeys = this.automaticContinuationKeys(messages);
+          const unsubmittedContinuationKeys = continuationKeys.filter(
+            (key) => !submittedAutomaticContinuationKeys.has(key),
+          );
+          const shouldSend =
+            this.shouldAutoSend(messages) &&
+            unsubmittedContinuationKeys.length > 0;
+          return shouldSend;
+        },
+        maxAutomaticSteps: 5,
+        onAutomaticStepLimitExceeded: () => {
+          sendMessage(
+            "工具连续执行次数达到上限啦，请换个说法再试试～",
+            5000,
+            3,
+          );
+        },
+        onFinish: ({ messages, isAbort, isError }) => {
+          if (!isAbort && !isError) {
+            localStorage.setItem(
+              "historyMessages",
+              JSON.stringify(this.stabilizeHistory(messages)),
+            );
+          }
+        },
+      });
+      this.chat = sdkChat;
+      const handledApprovals = new Set<string>();
+      unsubscribe = sdkChat.subscribe(() => {
+        const latest = sdkChat.messages[sdkChat.messages.length - 1];
+        if (!latest || latest.role !== "assistant") {
+          flushQueuedToolCalls();
+          return;
+        }
+        this.agentRuntime.ingestMessages(sdkChat.messages);
+        for (const part of latest.parts) {
+          if (this.isToolPart(part) && part.state === "input-available") {
+            executeToolCall(part);
+          }
+          if (
+            !this.isToolPart(part) ||
+            part.state !== "approval-requested" ||
+            !part.approval?.id ||
+            handledApprovals.has(part.approval.id)
+          ) {
+            continue;
+          }
+          handledApprovals.add(part.approval.id);
+          trackContinuation(
+            this.agentRuntime
+              .requestApproval(`要我帮你执行「${part.toolName}」吗？`)
+              .then((approved) => {
+                return sdkChat.addToolApprovalResponse({
+                  id: part.approval?.id,
+                  toolCallId: part.toolCallId,
+                  toolName: part.toolName,
+                  approved,
+                  reason: approved
+                    ? "Approved by visitor"
+                    : "Denied by visitor",
+                });
+              })
+              .then(() => undefined),
+          );
+        }
+        const textAnchor = this.displayTextAnchor(latest);
+        const allText = this.messageText(latest);
+        let shouldReplaceIncomingText = false;
+        if (
+          textAnchor !== displayedTextAnchor ||
+          this.displayText(latest, displayedTextBaseline).length <
+            streamedText.length
+        ) {
+          const hadDisplayedTextAnchor = displayedTextAnchor.length > 0;
+          const previousDisplayedTextBaseline = displayedTextBaseline;
+          displayedTextAnchor = textAnchor;
+          displayedTextBaseline = this.displayTextBaseline(latest);
+          streamedText = "";
+          const text = this.displayText(latest, displayedTextBaseline);
+          if (text.length === 0 && this.hasPendingOrCompletedTool(latest)) {
+            if (!shouldKeepVisibleAssistantTextDuringToolWait()) {
+              startReasoningMessages();
+            }
+          } else if (text.length === 0 && hadDisplayedTextAnchor) {
+            if (!shouldKeepVisibleAssistantTextDuringToolWait()) {
+              startReasoningMessages();
+            }
+          } else if (text.length > 0) {
+            shouldReplaceIncomingText =
+              hadDisplayedTextAnchor ||
+              reasoningMessageVisible ||
+              allText.startsWith(previousDisplayedTextBaseline);
+          }
+        }
+        const text = this.displayText(latest, displayedTextBaseline);
+        if (deferredReplaceText !== null) {
+          scheduleDeferredReplace(text);
+          flushQueuedToolCalls();
+          return;
+        }
+        if (text.length > streamedText.length) {
+          stopWaitingMessage();
+          hasVisibleAssistantContent = true;
+          stopReasoningMessages();
+          const isFirstTextAfterTool =
+            displayedTextBaseline.length > 0 &&
+            streamedText.length === 0 &&
+            lastVisibleAssistantText.length > 0;
+          const willReplaceIncomingText =
+            shouldReplaceIncomingText ||
+            isFirstTextAfterTool ||
+            (reasoningMessageVisible && streamedText.length === 0);
+          if (willReplaceIncomingText) {
+            if (
+              shouldHoldAutomaticContinuationReplace(willReplaceIncomingText) &&
+              scheduleDeferredReplace(text)
+            ) {
+              flushQueuedToolCalls();
+              return;
+            }
+            chat.setMessage(text);
+            reasoningMessageVisible = false;
+            markVisibleAssistantText(text);
+          } else {
+            chat.sendMessage(text.slice(streamedText.length));
+            markVisibleAssistantText(text);
           }
+        } else if (text.length === 0 && this.hasReasoningContent(latest)) {
+          startReasoningMessages();
         }
+        streamedText = text;
+        flushQueuedToolCalls();
+      });
+      await sdkChat.sendMessage({ text: messageTextValue });
+      flushQueuedToolCalls();
+      await waitForContinuations();
+      await waitForDeferredReplace();
+      if (sdkChat.error) {
+        throw sdkChat.error;
       }
+      chat.stop();
     } catch (error) {
       console.error("[Chat API] Stream error:", error);
-      throw error;
+      stopWaitingMessage();
+      stopReasoningMessages();
+      if ((error as Error).name !== "AbortError") {
+        if (reasoningMessageVisible) {
+          chat.setMessage("");
+        }
+        chat.sendMessage(this.resolveErrorMessage(error));
+      }
+      chat.stop();
+    } finally {
+      stopWaitingMessage();
+      stopReasoningMessages();
+      clearDeferredReplaceTimer();
+      unsubscribe?.();
     }
   }
 
@@ -230,9 +550,7 @@ export class ChatApi {
    * 中止当前请求
    */
   abort(): void {
-    if (this.controller) {
-      this.controller.abort();
-    }
+    this.chat?.stop();
     this.cleanup();
   }
 
@@ -248,13 +566,315 @@ export class ChatApi {
       clearTimeout(this.requestTimeoutId);
       this.requestTimeoutId = null;
     }
-    this.controller = null;
+    this.chat = null;
   }
 
   /**
    * 检查是否正在加载
    */
   isLoading(): boolean {
-    return this.controller !== null;
+    return this.chat !== null;
+  }
+
+  private normalizeContextRounds(rounds: number | undefined): number {
+    if (!Number.isFinite(rounds) || !rounds || rounds < 1) {
+      return 20;
+    }
+    return Math.floor(rounds);
+  }
+
+  private trimHistory(historyMessages: ChatMessage[]): ChatMessage[] {
+    const maxMessages = this.config.chatContextRounds
+      ? this.config.chatContextRounds * 2
+      : 40;
+    return this.stabilizeHistory(historyMessages, maxMessages);
+  }
+
+  private normalizeReasoningMessages(messages: unknown): string[] {
+    if (typeof messages === "string" && messages.trim()) {
+      return [messages.trim()];
+    }
+    if (!Array.isArray(messages)) {
+      return [...DEFAULT_REASONING_MESSAGES];
+    }
+    const normalized = messages
+      .map((message) => {
+        if (typeof message === "string" && message.trim()) {
+          return message.trim();
+        }
+        if (
+          typeof message === "object" &&
+          message !== null &&
+          "message" in message &&
+          typeof message.message === "string" &&
+          message.message.trim()
+        ) {
+          return message.message.trim();
+        }
+        return undefined;
+      })
+      .filter((message): message is string => message !== undefined);
+    return normalized.length > 0 ? normalized : [...DEFAULT_REASONING_MESSAGES];
+  }
+
+  private normalizeReasoningMessageInterval(
+    interval: number | undefined,
+  ): number {
+    if (!Number.isFinite(interval) || !interval || interval < 1) {
+      return 5;
+    }
+    return Math.floor(interval);
+  }
+
+  private normalizeAutoContinuationMessageMinVisibleMs(
+    minVisibleMs: number | undefined,
+  ): number {
+    if (!Number.isFinite(minVisibleMs) || !minVisibleMs || minVisibleMs < 0) {
+      return 0;
+    }
+    return Math.floor(Math.min(minVisibleMs, 10_000));
+  }
+
+  private pickReasoningMessage(): string | undefined {
+    const messages = this.config.reasoningMessages;
+    if (!Array.isArray(messages) || messages.length === 0) {
+      return;
+    }
+    const message = messages[Math.floor(Math.random() * messages.length)];
+    if (typeof message === "string") {
+      return message;
+    }
+    return message?.message;
+  }
+
+  private hasReasoningContent(message: UIMessage): boolean {
+    return this.partsAfterLastTool(message).some(
+      (part) => part.type === "reasoning" && part.text.trim().length > 0,
+    );
+  }
+
+  private hasPendingOrCompletedTool(message: UIMessage): boolean {
+    return message.parts.some((part) => this.isToolPart(part));
+  }
+
+  private messageText(message: UIMessage): string {
+    return message.parts
+      .filter(
+        (part): part is Extract<typeof part, { type: "text" }> =>
+          part.type === "text",
+      )
+      .map((part) => part.text)
+      .join("");
+  }
+
+  private displayText(message: UIMessage, baseline = ""): string {
+    const textAfterLastTool = this.partsAfterLastTool(message)
+      .filter(
+        (part): part is Extract<typeof part, { type: "text" }> =>
+          part.type === "text",
+      )
+      .map((part) => part.text)
+      .join("");
+    if (textAfterLastTool.length > 0) {
+      return textAfterLastTool;
+    }
+    const text = this.messageText(message);
+    if (baseline.length > 0) {
+      return text.startsWith(baseline) ? text.slice(baseline.length) : text;
+    }
+    return this.hasPendingOrCompletedTool(message) ? "" : text;
+  }
+
+  private displayTextBaseline(message: UIMessage): string {
+    const lastToolIndex = this.lastToolPartIndex(message);
+    if (lastToolIndex === -1) {
+      return "";
+    }
+    return message.parts
+      .slice(0, lastToolIndex)
+      .filter(
+        (part): part is Extract<typeof part, { type: "text" }> =>
+          part.type === "text",
+      )
+      .map((part) => part.text)
+      .join("");
+  }
+
+  private displayTextAnchor(message: UIMessage): string {
+    const lastToolIndex = this.lastToolPartIndex(message);
+    if (lastToolIndex === -1) {
+      return `${message.id}:initial`;
+    }
+    const part = message.parts[lastToolIndex];
+    if (!this.isToolPart(part)) {
+      return `${message.id}:initial`;
+    }
+    return `${message.id}:${part.toolCallId}:${lastToolIndex}`;
+  }
+
+  private partsAfterLastTool(message: UIMessage): UIMessage["parts"] {
+    const lastToolIndex = this.lastToolPartIndex(message);
+    return lastToolIndex === -1
+      ? message.parts
+      : message.parts.slice(lastToolIndex + 1);
+  }
+
+  private lastToolPartIndex(message: UIMessage): number {
+    for (let index = message.parts.length - 1; index >= 0; index -= 1) {
+      if (this.isToolPart(message.parts[index])) {
+        return index;
+      }
+    }
+    return -1;
+  }
+
+  private normalizeHistory(messages: unknown): ChatMessage[] {
+    if (!Array.isArray(messages)) {
+      return [];
+    }
+    const normalizedMessages = this.stabilizeHistory(messages as ChatMessage[]);
+    const issues = validateUIMessages(normalizedMessages);
+    if (issues.length > 0) {
+      console.warn("[Chat API] Ignore invalid UI message history:", issues);
+      return [];
+    }
+    return normalizedMessages;
+  }
+
+  private resolveErrorMessage(error: unknown): string {
+    if (error instanceof Error && error.message.trim()) {
+      return error.message;
+    }
+    if (typeof error === "string" && error.trim()) {
+      return error;
+    }
+    return "对话接口异常了哦～快去联系我的主人吧！";
+  }
+
+  private isToolPart(part: UIMessage["parts"][number]): part is ToolPart {
+    return part.type.startsWith("tool-");
+  }
+
+  private shouldAutoSend(messages: UIMessage[]): boolean {
+    return lastAssistantMessageHasCompletedToolContinuations({ messages });
+  }
+
+  private automaticContinuationKeys(messages: UIMessage[]): string[] {
+    const assistant = [...messages]
+      .reverse()
+      .find((message) => message.role === "assistant");
+    if (!assistant) {
+      return [];
+    }
+    const keys = assistant.parts
+      .filter((part): part is ToolPart => this.isToolPart(part))
+      .filter((part) => this.isContinuableToolPart(part))
+      .map((part) => this.automaticContinuationKey(part));
+    return [...new Set(keys)];
+  }
+
+  private isContinuableToolPart(part: ToolPart): boolean {
+    return (
+      this.hasFinalToolResultState(part) || part.state === "approval-responded"
+    );
+  }
+
+  private automaticContinuationKey(part: ToolPart): string {
+    return JSON.stringify({
+      toolCallId: part.toolCallId,
+      toolName: part.toolName,
+      state: part.state,
+      approvalId: part.approval?.id,
+      approved: part.approval?.approved,
+    });
+  }
+
+  private hasFinalToolResultState(part: ToolPart): boolean {
+    return (
+      part.state === "output-available" ||
+      part.state === "output-error" ||
+      part.state === "output-denied"
+    );
+  }
+
+  private shouldResumeAfterNavigation(output: unknown): boolean {
+    if (typeof output !== "object" || output === null) {
+      return false;
+    }
+    const record = output as Record<string, unknown>;
+    if (record.navigating === true) {
+      return record.pageReload !== false;
+    }
+    return this.shouldResumeAfterNavigation(record.output);
+  }
+
+  private historyWithToolOutput(
+    messages: UIMessage[],
+    part: ToolPart,
+    output: unknown,
+  ): ChatMessage[] {
+    return this.stabilizeHistory(
+      messages.map((message) => {
+        if (message.role !== "assistant") {
+          return message;
+        }
+        const parts = message.parts.map((messagePart) => {
+          if (
+            !this.isToolPart(messagePart) ||
+            messagePart.toolCallId !== part.toolCallId
+          ) {
+            return messagePart;
+          }
+          return {
+            ...messagePart,
+            type: `tool-${part.toolName}`,
+            toolName: part.toolName,
+            toolCallId: part.toolCallId,
+            state: "output-available",
+            output,
+          } satisfies ToolPart;
+        });
+        return { ...message, parts };
+      }),
+    );
+  }
+
+  private stabilizeHistory(
+    messages: ChatMessage[],
+    maxMessages?: number,
+  ): ChatMessage[] {
+    return this.sanitizeHistory(pruneMessages(messages, { maxMessages }));
+  }
+
+  private sanitizeHistory(messages: ChatMessage[]): ChatMessage[] {
+    const seenFinalToolCallIds = new Set<string>();
+    return [...messages]
+      .reverse()
+      .map((message) => {
+        if (message.role !== "assistant") {
+          return message;
+        }
+        const parts = [...message.parts]
+          .reverse()
+          .filter((part) => {
+            if (!this.isToolPart(part)) {
+              return true;
+            }
+            if (!this.hasFinalToolResultState(part)) {
+              return true;
+            }
+            if (seenFinalToolCallIds.has(part.toolCallId)) {
+              return false;
+            }
+            seenFinalToolCallIds.add(part.toolCallId);
+            return true;
+          })
+          .reverse();
+        return parts.length === message.parts.length
+          ? message
+          : { ...message, parts };
+      })
+      .reverse()
+      .filter((message) => message.parts.length > 0);
   }
 }
diff --git a/packages/live2d/src/components/Live2dCanvas.tsx b/packages/live2d/src/components/Live2dCanvas.tsx
index 44da9c3..7fc49bf 100644
--- a/packages/live2d/src/components/Live2dCanvas.tsx
+++ b/packages/live2d/src/components/Live2dCanvas.tsx
@@ -6,6 +6,10 @@ import {
 import { BeforeInitEvent } from "@/live2d/events/before-init.js";
 import { ModelReadyEvent } from "@/live2d/events/model-ready";
 import Model from "@/live2d/live2d/model";
+import {
+  clearCurrentLive2dModel,
+  setCurrentLive2dModel,
+} from "@/live2d/live2d/model-store";
 import { consume } from "@lit/context";
 import { type PropertyValues, type TemplateResult, html } from "lit";
 import { property, query, state } from "lit/decorators.js";
@@ -36,6 +40,7 @@ export class Live2dCanvas extends UnoLitElement {
 
   disconnectedCallback(): void {
     super.disconnectedCallback();
+    clearCurrentLive2dModel(this.model);
     this.model?.destroy();
     this.model = null;
     this._modelInitialized = false;
@@ -62,6 +67,7 @@ export class Live2dCanvas extends UnoLitElement {
 
     try {
       this.model = await Model.create(this._live2d, this.config);
+      setCurrentLive2dModel(this.model);
       window.dispatchEvent(new ModelReadyEvent({ model: this.model }));
     } catch (error) {
       this._modelInitialized = false;
diff --git a/packages/live2d/src/components/Live2dChatWindow.tsx b/packages/live2d/src/components/Live2dChatWindow.tsx
index 2573925..b7a50e3 100644
--- a/packages/live2d/src/components/Live2dChatWindow.tsx
+++ b/packages/live2d/src/components/Live2dChatWindow.tsx
@@ -1,9 +1,14 @@
+import {
+  type AgentAfterNavigationResume,
+  consumeAgentAfterNavigationIntent,
+} from "@/live2d/api/agent-navigation-intent";
 import { ChatApi, type ChatMessage } from "@/live2d/api/chat-api";
 import { UnoLitElement } from "@/live2d/common/UnoLitElement";
 import {
   type Live2dConfig,
   configContext,
 } from "@/live2d/context/config-context";
+import { loadMergedTips } from "@/live2d/helpers/loadMergedTips";
 import { sendMessage } from "@/live2d/helpers/sendMessage";
 import { DraggableMixin } from "@/live2d/mixins/draggable";
 import { consume } from "@lit/context";
@@ -98,7 +103,6 @@ export class Live2dChatWindow extends DraggableUnoLitElement {
             class="h-8.5 w-full appearance-none rounded-full border border-solid border-[#eadbc5] bg-white/98 px-3.5 py-0.5 text-3.25 text-slate-700 shadow-none outline-none transition-colors placeholder:text-slate-400 focus:border-[#ffbb72] focus:ring-1 focus:ring-[#ffd8ac] focus:shadow-none"
             @input=${this.handleInput}
             @keydown=${this.handleKeydown}
-            ?disabled=${this._isLoading}
           />
           <button
             id="live2d-chat-send"
@@ -138,7 +142,16 @@ export class Live2dChatWindow extends DraggableUnoLitElement {
     `;
   }
 
-  handleToggle = (): void => {
+  handleToggle = (event?: Event): void => {
+    const detail = event instanceof CustomEvent ? event.detail : undefined;
+    if (detail?.open === true) {
+      void this.showChat(detail.focus !== false);
+      return;
+    }
+    if (detail?.open === false) {
+      this.hideChat();
+      return;
+    }
     if (this._isShow) {
       this.hideChat();
       return;
@@ -181,39 +194,102 @@ export class Live2dChatWindow extends DraggableUnoLitElement {
     this._input.value = "";
     this._canSend = false;
     this._isLoading = true;
+    this.focusInput();
+
+    try {
+      await this.sendChatMessage(message, this.readStoredHistoryMessages());
+    } catch (error) {
+      console.error("[Live2dChatWindow] Send message error:", error);
+    } finally {
+      this._isLoading = false;
+      if (this._input) {
+        this._canSend = this._input.value.length > 0;
+      }
+      this.focusInput();
+    }
+  }
+
+  protected firstUpdated(_changedProperties: PropertyValues): void {
+    super.firstUpdated(_changedProperties);
+    this._input?.addEventListener("focus", () => {
+      sendMessage("按下回车键可以快速发送消息哦", 2000, 1);
+    });
+    const intent = consumeAgentAfterNavigationIntent();
+    if (intent?.openChat) {
+      void this.showChat(intent.focusChatInput).then(() => {
+        if (intent.resume) {
+          void this.resumeAgentAfterNavigation(intent.resume);
+        }
+      });
+    }
+  }
 
+  private async ensureChatApi(): Promise<ChatApi> {
     if (!this.chatApi) {
+      const mergedTips = this.config
+        ? await loadMergedTips(this.config).catch(() => undefined)
+        : undefined;
       this.chatApi = new ChatApi({
         chunkTimeout: Number(this.config?.chunkTimeout || 60),
         showChatMessageTimeout: Number(
           this.config?.showChatMessageTimeout || 10,
         ),
+        autoContinuationMessageMinVisibleMs: Number(
+          this.config?.autoContinuationMessageMinVisibleMs ?? 1500,
+        ),
+        requestAcceptedMessage: this.config?.requestAcceptedMessage,
+        reasoningMessages:
+          this.config?.reasoningMessages ?? mergedTips?.message.reasoning,
+        reasoningMessageInterval: Number(
+          this.config?.reasoningMessageInterval || 5,
+        ),
+        chatContextRounds: Number(this.config?.chatContextRounds || 20),
+        agent: this.config?.agent,
       });
     }
+    return this.chatApi;
+  }
 
+  private readStoredHistoryMessages(): ChatMessage[] {
     const historyJson = localStorage.getItem("historyMessages");
     this.historyMessages = historyJson ? JSON.parse(historyJson) : [];
+    return this.historyMessages;
+  }
+
+  private async sendChatMessage(
+    message: string,
+    historyMessages: ChatMessage[],
+  ): Promise<void> {
+    const chatApi = await this.ensureChatApi();
+    await chatApi.sendMessage(message, historyMessages);
+  }
 
+  private async resumeAgentAfterNavigation(
+    resume: AgentAfterNavigationResume,
+  ): Promise<void> {
+    if (this._isLoading) {
+      return;
+    }
+    this._isLoading = true;
+    this._canSend = false;
+    this.focusInput();
     try {
-      await this.chatApi.sendMessage(message, this.historyMessages);
+      await this.sendChatMessage(resume.message, resume.historyMessages);
     } catch (error) {
-      console.error("[Live2dChatWindow] Send message error:", error);
+      console.error(
+        "[Live2dChatWindow] Resume agent after navigation error:",
+        error,
+      );
     } finally {
       this._isLoading = false;
       if (this._input) {
         this._canSend = this._input.value.length > 0;
       }
+      this.focusInput();
     }
   }
 
-  protected firstUpdated(_changedProperties: PropertyValues): void {
-    super.firstUpdated(_changedProperties);
-    this._input?.addEventListener("focus", () => {
-      sendMessage("按下回车键可以快速发送消息哦", 2000, 1);
-    });
-  }
-
-  private async showChat(): Promise<void> {
+  private async showChat(focus = true): Promise<void> {
     this.clearHidePopoverTimer();
     await this.updateComplete;
     if (
@@ -225,9 +301,11 @@ export class Live2dChatWindow extends DraggableUnoLitElement {
 
     requestAnimationFrame(() => {
       this._isShow = true;
-      void this.updateComplete.then(() => {
-        this._input?.focus();
-      });
+      if (focus) {
+        void this.updateComplete.then(() => {
+          this.focusInput();
+        });
+      }
     });
   }
 
@@ -266,6 +344,12 @@ export class Live2dChatWindow extends DraggableUnoLitElement {
       this._hidePopoverTimer = undefined;
     }
   }
+
+  private focusInput(): void {
+    requestAnimationFrame(() => {
+      this._input?.focus();
+    });
+  }
 }
 
 customElements.define("live2d-chat-window", Live2dChatWindow);
diff --git a/packages/live2d/src/components/Live2dTips.tsx b/packages/live2d/src/components/Live2dTips.tsx
index 75ccf41..6cddefe 100644
--- a/packages/live2d/src/components/Live2dTips.tsx
+++ b/packages/live2d/src/components/Live2dTips.tsx
@@ -34,6 +34,7 @@ export class Live2dTips extends UnoLitElement {
   private _bottomOffset = Live2dTips.DEFAULT_BOTTOM_OFFSET;
   private priority = -1;
   private messageTimer: number | null = null;
+  private streamInactivityTimeout = 60_000;
   // 流式消息模式标志
   private isStreamMode = false;
   private readonly onMessage = (event: Event) => {
@@ -108,6 +109,7 @@ export class Live2dTips extends UnoLitElement {
     window.removeEventListener("live2d:stream-message", this.onStreamMessage);
     window.removeEventListener("live2d:stream-message-stop", this.onStreamStop);
     window.removeEventListener("live2d:model-layout", this.onModelLayout);
+    this.clearMessageTimer();
   }
 
   handleMessage(e: SendMessageEvent): void {
@@ -122,10 +124,7 @@ export class Live2dTips extends UnoLitElement {
     if (priority < this.priority) {
       return;
     }
-    if (this.messageTimer) {
-      clearTimeout(this.messageTimer);
-      this.messageTimer = null;
-    }
+    this.clearMessageTimer();
     const message = randomSelection(text);
     if (!isNotEmpty(message)) {
       return;
@@ -147,23 +146,13 @@ export class Live2dTips extends UnoLitElement {
     const STREAM_PRIORITY = 99999;
     this.priority = STREAM_PRIORITY;
     this.isStreamMode = true;
+    this.streamInactivityTimeout = timeout;
 
     // 清空消息并显示
     this._message = "";
     this._isShow = true;
 
-    // 清除旧的定时器
-    if (this.messageTimer) {
-      clearTimeout(this.messageTimer);
-      this.messageTimer = null;
-    }
-
-    // 设置超时自动关闭
-    this.messageTimer = setTimeout(() => {
-      this._isShow = false;
-      this.priority = -1;
-      this.isStreamMode = false;
-    }, timeout);
+    this.scheduleStreamInactivityTimeout(timeout);
   }
 
   /**
@@ -174,6 +163,11 @@ export class Live2dTips extends UnoLitElement {
       return;
     }
     const { text } = e.detail;
+    this.scheduleStreamInactivityTimeout(this.streamInactivityTimeout);
+    if (e.detail.mode === "replace") {
+      this._message = text;
+      return;
+    }
     this._message += text;
   }
 
@@ -186,11 +180,7 @@ export class Live2dTips extends UnoLitElement {
     }
     const { showTimeout } = e.detail;
 
-    // 清除旧的定时器
-    if (this.messageTimer) {
-      clearTimeout(this.messageTimer);
-      this.messageTimer = null;
-    }
+    this.clearMessageTimer();
 
     // 设置新的定时器，在指定时间后关闭
     this.messageTimer = setTimeout(() => {
@@ -211,6 +201,25 @@ export class Live2dTips extends UnoLitElement {
   private applyHostPosition(): void {
     this.style.bottom = `${this._bottomOffset}px`;
   }
+
+  private clearMessageTimer(): void {
+    if (this.messageTimer) {
+      clearTimeout(this.messageTimer);
+      this.messageTimer = null;
+    }
+  }
+
+  private scheduleStreamInactivityTimeout(timeout?: number): void {
+    this.clearMessageTimer();
+    this.messageTimer = setTimeout(
+      () => {
+        this._isShow = false;
+        this.priority = -1;
+        this.isStreamMode = false;
+      },
+      timeout ?? Number(this.config?.chunkTimeout || 60) * 1000,
+    );
+  }
 }
 
 customElements.define("live2d-tips", Live2dTips);
diff --git a/packages/live2d/src/config/agent-tools/agent-tool-config.ts b/packages/live2d/src/config/agent-tools/agent-tool-config.ts
new file mode 100644
index 0000000..bdb03b7
--- /dev/null
+++ b/packages/live2d/src/config/agent-tools/agent-tool-config.ts
@@ -0,0 +1,81 @@
+export type AgentAccessMode =
+  | "anonymous_chat"
+  | "anonymous_chat_agent"
+  | "authenticated_chat"
+  | "authenticated_chat_agent";
+
+export type AgentToolApproval = "default" | "never" | "always";
+export type AgentToolAuth = "none" | "authenticated";
+export type AgentCommentCapability = "off" | "assist" | "submit";
+
+export type AgentBrowserAction =
+  | {
+      type: "navigate";
+      url: string;
+      target?: "_self" | "_blank";
+      pendingMessage?: string;
+      successMessage?: string;
+      errorMessage?: string;
+    }
+  | {
+      type: "scroll-to";
+      selector: string;
+      behavior?: ScrollBehavior;
+      pendingMessage?: string;
+      successMessage?: string;
+      errorMessage?: string;
+    }
+  | {
+      type: "highlight";
+      selector: string;
+      duration?: number;
+      pendingMessage?: string;
+      successMessage?: string;
+      errorMessage?: string;
+    }
+  | {
+      type: "dispatch-event";
+      event: string;
+      pendingMessage?: string;
+      successMessage?: string;
+      errorMessage?: string;
+    }
+  | {
+      type: "registered";
+      pendingMessage?: string;
+      successMessage?: string;
+      errorMessage?: string;
+    };
+
+export interface AgentToolConfig {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  approval: AgentToolApproval;
+  requiredAuth: AgentToolAuth;
+  actionType: AgentBrowserAction["type"];
+  action: AgentBrowserAction;
+  testInput?: unknown;
+}
+
+export interface AgentRuntimeConfig {
+  builtIn: {
+    pageContext: boolean;
+    haloNavigation: boolean;
+    haloContentSearch: boolean;
+    networkAccess: boolean;
+    commentCapability: AgentCommentCapability;
+  };
+  aiTools: AgentToolConfig[];
+  toolSecurity: {
+    allowedExternalOrigins: string[];
+    allowNewTab: boolean;
+  };
+  haloSearch: {
+    allowedTypes: string[];
+    defaultLimit: number;
+  };
+  haloResourceDetail: {
+    maxContentChars: number;
+  };
+}
diff --git a/packages/live2d/src/config/agent-tools/normalize-agent-tools.ts b/packages/live2d/src/config/agent-tools/normalize-agent-tools.ts
new file mode 100644
index 0000000..7aafac4
--- /dev/null
+++ b/packages/live2d/src/config/agent-tools/normalize-agent-tools.ts
@@ -0,0 +1,183 @@
+import type {
+  AgentBrowserAction,
+  AgentCommentCapability,
+  AgentRuntimeConfig,
+  AgentToolApproval,
+  AgentToolAuth,
+  AgentToolConfig,
+} from "@/live2d/config/agent-tools/agent-tool-config";
+import {
+  isRecord,
+  pickBoolean,
+  pickNumber,
+  pickString,
+} from "@/live2d/config/normalize-helpers";
+import { isNotEmptyString } from "@/live2d/utils/isString";
+
+const ACTION_TYPES = new Set([
+  "navigate",
+  "scroll-to",
+  "highlight",
+  "dispatch-event",
+  "registered",
+]);
+
+const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]{2,63}$/;
+
+const pickApproval = (value: unknown): AgentToolApproval =>
+  value === "never" || value === "always" ? value : "default";
+
+const pickAuth = (value: unknown): AgentToolAuth =>
+  value === "authenticated" ? "authenticated" : "none";
+
+const pickCommentCapability = (value: unknown): AgentCommentCapability =>
+  value === "off" || value === "submit" ? value : "assist";
+
+const normalizeStringArray = (value: unknown): string[] => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter(isNotEmptyString);
+};
+
+const normalizeObjectStringArray = (
+  value: unknown,
+  objectKey: string,
+): string[] => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((item) =>
+    isRecord(item) && isNotEmptyString(item[objectKey])
+      ? [item[objectKey]]
+      : [],
+  );
+};
+
+const normalizeAction = (value: unknown): AgentBrowserAction | undefined => {
+  if (!isRecord(value)) {
+    return;
+  }
+  const type = pickString(value.type);
+  if (!type || !ACTION_TYPES.has(type)) {
+    return;
+  }
+  if (type === "navigate") {
+    const url = pickString(value.url);
+    if (!url) {
+      return;
+    }
+    return {
+      ...pickMessages(value),
+      type,
+      url,
+      target: value.target === "_blank" ? "_blank" : "_self",
+    };
+  }
+  if (type === "scroll-to" || type === "highlight") {
+    const selector = pickString(value.selector);
+    if (!selector) {
+      return;
+    }
+    return {
+      ...pickMessages(value),
+      type,
+      selector,
+      ...(type === "scroll-to"
+        ? { behavior: value.behavior === "auto" ? "auto" : "smooth" }
+        : { duration: pickNumber(value.duration) }),
+    } as AgentBrowserAction;
+  }
+  if (type === "dispatch-event") {
+    const event = pickString(value.event);
+    if (!event) {
+      return;
+    }
+    return { ...pickMessages(value), type, event };
+  }
+  if (type === "registered") {
+    return { ...pickMessages(value), type };
+  }
+  return;
+};
+
+const pickMessages = (value: Record<string, unknown>) => ({
+  pendingMessage: pickString(value.pendingMessage),
+  successMessage: pickString(value.successMessage),
+  errorMessage: pickString(value.errorMessage),
+});
+
+const normalizeTool = (value: unknown): AgentToolConfig | undefined => {
+  if (!isRecord(value)) {
+    return;
+  }
+  const name = pickString(value.name);
+  const description = pickString(value.description);
+  const action = normalizeAction(value.action);
+  if (!name || !TOOL_NAME_PATTERN.test(name) || !description || !action) {
+    return;
+  }
+  const inputSchema = isRecord(value.inputSchema)
+    ? value.inputSchema
+    : { type: "object", properties: {} };
+  return {
+    name,
+    description,
+    inputSchema,
+    approval: pickApproval(value.approval),
+    requiredAuth: pickAuth(value.requiredAuth),
+    actionType: action.type,
+    action,
+    testInput: value.testInput,
+  };
+};
+
+export const normalizeAgentRuntimeConfig = (
+  input: unknown,
+): AgentRuntimeConfig => {
+  const source = isRecord(input) ? input : {};
+  const builtIn = isRecord(source.builtIn) ? source.builtIn : {};
+  const toolSecurity = isRecord(source.toolSecurity) ? source.toolSecurity : {};
+  const haloSearch = isRecord(source.haloSearch) ? source.haloSearch : {};
+  const haloResourceDetail = isRecord(source.haloResourceDetail)
+    ? source.haloResourceDetail
+    : {};
+  const allowedTypes = normalizeStringArray(haloSearch.allowedTypes);
+
+  return {
+    builtIn: {
+      pageContext: pickBoolean(builtIn.pageContext, true) ?? true,
+      haloNavigation: pickBoolean(builtIn.haloNavigation, true) ?? true,
+      haloContentSearch: pickBoolean(builtIn.haloContentSearch, true) ?? true,
+      networkAccess: pickBoolean(builtIn.networkAccess, false) ?? false,
+      commentCapability: pickCommentCapability(builtIn.commentCapability),
+    },
+    aiTools: Array.isArray(source.aiTools)
+      ? source.aiTools.flatMap((tool) => {
+          const normalized = normalizeTool(tool);
+          return normalized ? [normalized] : [];
+        })
+      : [],
+    toolSecurity: {
+      allowedExternalOrigins: normalizeStringArray(
+        toolSecurity.allowedExternalOrigins,
+      ).concat(
+        normalizeObjectStringArray(
+          toolSecurity.allowedExternalOrigins,
+          "origin",
+        ),
+      ),
+      allowNewTab: pickBoolean(toolSecurity.allowNewTab, false) ?? false,
+    },
+    haloSearch: {
+      allowedTypes:
+        allowedTypes.length > 0
+          ? allowedTypes
+          : ["post.content.halo.run", "singlepage.content.halo.run"],
+      defaultLimit: pickNumber(haloSearch.defaultLimit) ?? 5,
+    },
+    haloResourceDetail: {
+      maxContentChars: pickNumber(haloResourceDetail.maxContentChars) ?? 3000,
+    },
+  };
+};
diff --git a/packages/live2d/src/config/default-config.ts b/packages/live2d/src/config/default-config.ts
index 5353f73..c16abf4 100644
--- a/packages/live2d/src/config/default-config.ts
+++ b/packages/live2d/src/config/default-config.ts
@@ -29,8 +29,39 @@ export const createDefaultLive2dConfig = (): Live2dConfig => ({
   isTools: true,
   tools: [...DEFAULT_TOOL_NAMES],
   isAiChat: true,
+  accessMode: "anonymous_chat",
+  agent: {
+    builtIn: {
+      pageContext: true,
+      haloNavigation: true,
+      haloContentSearch: true,
+      networkAccess: false,
+      commentCapability: "assist",
+    },
+    aiTools: [],
+    toolSecurity: {
+      allowedExternalOrigins: [],
+      allowNewTab: false,
+    },
+    haloSearch: {
+      allowedTypes: ["post.content.halo.run", "singlepage.content.halo.run"],
+      defaultLimit: 5,
+    },
+    haloResourceDetail: {
+      maxContentChars: 3000,
+    },
+  },
   chunkTimeout: 10,
   showChatMessageTimeout: 10,
+  autoContinuationMessageMinVisibleMs: 1500,
+  requestAcceptedMessage: "收到啦，马上就来陪你啦～",
+  reasoningMessages: [
+    "我正在认真想一想～",
+    "让我整理一下思路，很快就好～",
+    "稍等一下，我正在组织语言呢～",
+  ],
+  reasoningMessageInterval: 5,
+  chatContextRounds: 20,
   screenshotName: "live2d",
   filterQuality: "high",
   proceduralAnimation: {
diff --git a/packages/live2d/src/config/normalize-config.ts b/packages/live2d/src/config/normalize-config.ts
index 851a1d3..09e5e2b 100644
--- a/packages/live2d/src/config/normalize-config.ts
+++ b/packages/live2d/src/config/normalize-config.ts
@@ -1,3 +1,4 @@
+import { normalizeAgentRuntimeConfig } from "@/live2d/config/agent-tools/normalize-agent-tools";
 import { normalizeCustomTools } from "@/live2d/config/custom-tools/normalize-custom-tools";
 import { createDefaultLive2dConfig } from "@/live2d/config/default-config";
 import {
@@ -13,6 +14,13 @@ export interface LegacyLive2dConfigInput extends Partial<Live2dConfig> {
   aiChatBaseSetting?: {
     chunkTimeout?: number | string;
     showChatMessageTimeout?: number | string;
+    autoContinuationMessageMinVisibleMs?: number | string;
+    requestAcceptedMessage?: string;
+    reasoningMessages?: string[] | string | { message?: string }[];
+    reasoningMessageInterval?: number | string;
+    chatContextRounds?: number | string;
+    accessMode?: Live2dConfig["accessMode"];
+    isAnonymous?: boolean;
   };
   consoleShowStatu?: boolean;
   photoName?: string;
@@ -26,6 +34,47 @@ const normalizeTools = (tools: unknown): string[] | undefined => {
   return tools.filter((tool): tool is string => isNotEmptyString(tool));
 };
 
+const normalizeMessages = (messages: unknown): string[] | undefined => {
+  if (isNotEmptyString(messages)) {
+    return [messages];
+  }
+  if (!Array.isArray(messages)) {
+    return;
+  }
+  const normalized = messages
+    .map((message) => {
+      if (isNotEmptyString(message)) {
+        return message;
+      }
+      if (
+        typeof message === "object" &&
+        message !== null &&
+        "message" in message &&
+        isNotEmptyString(message.message)
+      ) {
+        return message.message;
+      }
+      return undefined;
+    })
+    .filter((message): message is string => message !== undefined);
+  return normalized.length > 0 ? normalized : undefined;
+};
+
+const normalizeAccessMode = (
+  accessMode: unknown,
+  legacyAnonymous: unknown,
+): Live2dConfig["accessMode"] => {
+  if (
+    accessMode === "anonymous_chat" ||
+    accessMode === "anonymous_chat_agent" ||
+    accessMode === "authenticated_chat" ||
+    accessMode === "authenticated_chat_agent"
+  ) {
+    return accessMode;
+  }
+  return legacyAnonymous === false ? "authenticated_chat" : "anonymous_chat";
+};
+
 export const normalizeLive2dConfig = (
   assetPath: string,
   input: LegacyLive2dConfigInput = {},
@@ -58,6 +107,11 @@ export const normalizeLive2dConfig = (
       defaults.screenshotName,
     tools: normalizeTools(input.tools) ?? [...(defaults.tools ?? [])],
     customTools: normalizeCustomTools(input.customTools) ?? [],
+    accessMode: normalizeAccessMode(
+      input.accessMode ?? input.aiChatBaseSetting?.accessMode,
+      input.aiChatBaseSetting?.isAnonymous,
+    ),
+    agent: normalizeAgentRuntimeConfig(input.agent),
     chunkTimeout:
       pickNumber(
         input.chunkTimeout,
@@ -70,6 +124,35 @@ export const normalizeLive2dConfig = (
         input.aiChatBaseSetting?.showChatMessageTimeout,
         defaults.showChatMessageTimeout,
       ) ?? defaults.showChatMessageTimeout,
+    autoContinuationMessageMinVisibleMs:
+      pickNumber(
+        input.autoContinuationMessageMinVisibleMs,
+        input.aiChatBaseSetting?.autoContinuationMessageMinVisibleMs,
+        defaults.autoContinuationMessageMinVisibleMs,
+      ) ?? defaults.autoContinuationMessageMinVisibleMs,
+    requestAcceptedMessage:
+      pickString(
+        input.requestAcceptedMessage,
+        input.aiChatBaseSetting?.requestAcceptedMessage,
+        defaults.requestAcceptedMessage,
+      ) ?? defaults.requestAcceptedMessage,
+    reasoningMessages:
+      normalizeMessages(input.reasoningMessages) ??
+      normalizeMessages(input.aiChatBaseSetting?.reasoningMessages) ??
+      normalizeMessages(defaults.reasoningMessages) ??
+      [],
+    reasoningMessageInterval:
+      pickNumber(
+        input.reasoningMessageInterval,
+        input.aiChatBaseSetting?.reasoningMessageInterval,
+        defaults.reasoningMessageInterval,
+      ) ?? defaults.reasoningMessageInterval,
+    chatContextRounds:
+      pickNumber(
+        input.chatContextRounds,
+        input.aiChatBaseSetting?.chatContextRounds,
+        defaults.chatContextRounds,
+      ) ?? defaults.chatContextRounds,
     backSite: pickBoolean(input.backSite, defaults.backSite),
     copyContent: pickBoolean(input.copyContent, defaults.copyContent),
     openConsole: pickBoolean(input.openConsole, defaults.openConsole),
diff --git a/packages/live2d/src/context/config-context.ts b/packages/live2d/src/context/config-context.ts
index 450909a..abfcb5c 100644
--- a/packages/live2d/src/context/config-context.ts
+++ b/packages/live2d/src/context/config-context.ts
@@ -1,6 +1,10 @@
+import type {
+  AgentAccessMode,
+  AgentRuntimeConfig,
+} from "@/live2d/config/agent-tools/agent-tool-config";
 import type { CustomToolConfig } from "@/live2d/live2d/tools/custom-tool-config";
-import type { ProceduralConfig } from "@/live2d/runtime/procedural";
 import type { EmotionTimelineConfig } from "@/live2d/runtime/emotion";
+import type { ProceduralConfig } from "@/live2d/runtime/procedural";
 import { createContext } from "@lit/context";
 
 export interface ObjectAny extends Record<string, unknown> {}
@@ -30,6 +34,7 @@ export interface TipMessage extends ObjectAny {
   console?: string[] | string;
   copy?: string[] | string;
   loading?: string[] | string;
+  reasoning?: string[] | string;
   visibilitychange?: string[] | string;
 }
 
@@ -50,12 +55,26 @@ export interface Live2dToolsConfig {
   customTools?: CustomToolConfig[];
   // 是否启用 AI 聊天功能
   isAiChat?: boolean;
+  // AI 聊天与 Agent 能力访问模式
+  accessMode?: AgentAccessMode;
+  // Agent 能力运行时配置
+  agent?: AgentRuntimeConfig;
   // openai 图标
   openaiIcon?: string;
   // 聊天请求超时时间（秒）
   chunkTimeout?: number;
   // 聊天消息显示时间（秒）
   showChatMessageTimeout?: number;
+  // Agent 自动续写时，上一段助手消息最短可见时间（毫秒）
+  autoContinuationMessageMinVisibleMs?: number;
+  // 用户请求已收到时的即时提示语
+  requestAcceptedMessage?: string;
+  // 模型思考阶段的提示语
+  reasoningMessages?: string[] | string;
+  // 思考提示语轮换间隔（秒）
+  reasoningMessageInterval?: number;
+  // 保留上下文轮数
+  chatContextRounds?: number;
   // 一言图标
   hitokotoIcon?: string;
   // 一言API
@@ -127,6 +146,13 @@ export interface Live2dConfig extends Live2dToolsConfig {
   aiChatBaseSetting?: {
     chunkTimeout?: number | string;
     showChatMessageTimeout?: number | string;
+    autoContinuationMessageMinVisibleMs?: number | string;
+    requestAcceptedMessage?: string;
+    reasoningMessages?: string[] | string | { message?: string }[];
+    reasoningMessageInterval?: number | string;
+    chatContextRounds?: number | string;
+    accessMode?: AgentAccessMode;
+    isAnonymous?: boolean;
   };
   // 滤镜质量等级 (low / medium / high)
   filterQuality?: "low" | "medium" | "high";
diff --git a/packages/live2d/src/events/stream-message.ts b/packages/live2d/src/events/stream-message.ts
index 26a85f6..330b615 100644
--- a/packages/live2d/src/events/stream-message.ts
+++ b/packages/live2d/src/events/stream-message.ts
@@ -22,6 +22,8 @@ export interface StreamMessageStartEventDetail {
 export interface StreamMessageEventDetail {
   // 流式消息文本片段
   text: string;
+  // 消息写入模式：默认追加；思考提示等临时内容可替换当前消息
+  mode?: "append" | "replace";
 }
 
 export interface StreamMessageStopEventDetail {
diff --git a/packages/live2d/src/events/toggle-chat-window.ts b/packages/live2d/src/events/toggle-chat-window.ts
index f186016..4121bfc 100644
--- a/packages/live2d/src/events/toggle-chat-window.ts
+++ b/packages/live2d/src/events/toggle-chat-window.ts
@@ -3,6 +3,11 @@ import { Live2dEvent } from "@/live2d/events/types";
 export const TOGGLE_CHAT_WINDOW_EVENT_NAME =
   "live2d:toggle-chat-window" as const;
 
+export interface ToggleChatWindowEventDetail {
+  open?: boolean;
+  focus?: boolean;
+}
+
 declare global {
   interface GlobalEventHandlersEventMap {
     [TOGGLE_CHAT_WINDOW_EVENT_NAME]: ToggleChatWindowEvent;
@@ -10,11 +15,11 @@ declare global {
 }
 
 /**
- * 切换聊天窗口事件
- * 不需要传递参数，每次触发都会切换显示状态
+ * 切换或设置聊天窗口显示状态。
+ * 不传 open 时保持原有切换语义。
  */
-export class ToggleChatWindowEvent extends Live2dEvent<Record<string, never>> {
-  constructor() {
-    super(TOGGLE_CHAT_WINDOW_EVENT_NAME, {});
+export class ToggleChatWindowEvent extends Live2dEvent<ToggleChatWindowEventDetail> {
+  constructor(detail: ToggleChatWindowEventDetail = {}) {
+    super(TOGGLE_CHAT_WINDOW_EVENT_NAME, detail);
   }
 }
diff --git a/packages/live2d/src/halo.ts b/packages/live2d/src/halo.ts
index 95d607a..430e9bb 100644
--- a/packages/live2d/src/halo.ts
+++ b/packages/live2d/src/halo.ts
@@ -1,7 +1,7 @@
 import {
   HALO_LIVE2D_CONFIG_ELEMENT_ID,
   readHaloLive2dConfig,
-} from "@/live2d/halo-config";
+} from "./halo-config";
 
 let bootstrapPromise: Promise<void> | undefined;
 
@@ -12,7 +12,10 @@ export const bootstrapFromHalo = async (): Promise<void> => {
 
   bootstrapPromise = (async () => {
     const config = readHaloLive2dConfig();
-    const { createLive2d } = await import("@/live2d/live2d/runtime");
+    if (import.meta.env.DEV) {
+      await import("@vitejs/plugin-react/preamble");
+    }
+    const { createLive2d } = await import("./live2d/runtime");
     const live2d = window.live2d ?? createLive2d();
     if (!window.live2d) {
       window.live2d = live2d;
diff --git a/packages/live2d/src/helpers/createStreamMessage.ts b/packages/live2d/src/helpers/createStreamMessage.ts
index 91820d5..bcbc67c 100644
--- a/packages/live2d/src/helpers/createStreamMessage.ts
+++ b/packages/live2d/src/helpers/createStreamMessage.ts
@@ -27,6 +27,14 @@ export function createStreamMessage(
     window.dispatchEvent(new StreamMessageEvent({ text }));
   };
 
+  /**
+   * 替换流式消息框中的文本
+   * @param text 要显示的文本
+   */
+  const setMessage = (text: string) => {
+    window.dispatchEvent(new StreamMessageEvent({ text, mode: "replace" }));
+  };
+
   /**
    * 停止流式消息，并在指定时间后关闭消息框
    */
@@ -36,6 +44,7 @@ export function createStreamMessage(
 
   return {
     sendMessage,
+    setMessage,
     stop,
   };
 }
@@ -45,6 +54,10 @@ export interface StreamMessageController {
    * 发送消息片段
    */
   sendMessage: (text: string) => void;
+  /**
+   * 替换当前消息内容
+   */
+  setMessage: (text: string) => void;
   /**
    * 停止流式消息
    */
diff --git a/packages/live2d/src/helpers/loadTipsResource.ts b/packages/live2d/src/helpers/loadTipsResource.ts
index d952305..d421ec7 100644
--- a/packages/live2d/src/helpers/loadTipsResource.ts
+++ b/packages/live2d/src/helpers/loadTipsResource.ts
@@ -85,6 +85,7 @@ const isTipMessage = (value: unknown): value is TipMessage => {
     "console",
     "copy",
     "loading",
+    "reasoning",
     "visibilitychange",
   ];
   return optionalFields.every((field) => {
diff --git a/packages/live2d/src/live2d/model-store.ts b/packages/live2d/src/live2d/model-store.ts
new file mode 100644
index 0000000..dfcd49b
--- /dev/null
+++ b/packages/live2d/src/live2d/model-store.ts
@@ -0,0 +1,15 @@
+import type Model from "@/live2d/live2d/model";
+
+let currentModel: Model | null = null;
+
+export const setCurrentLive2dModel = (model: Model): void => {
+  currentModel = model;
+};
+
+export const clearCurrentLive2dModel = (model?: Model | null): void => {
+  if (!model || currentModel === model) {
+    currentModel = null;
+  }
+};
+
+export const getCurrentLive2dModel = (): Model | null => currentModel;
diff --git a/packages/live2d/vite.config.ts b/packages/live2d/vite.config.ts
index 1ae787b..dcf8739 100644
--- a/packages/live2d/vite.config.ts
+++ b/packages/live2d/vite.config.ts
@@ -6,6 +6,11 @@ export default defineConfig({
   test: {
     environment: "jsdom",
     globals: true,
+    server: {
+      deps: {
+        inline: ["@halo-dev/ai-foundation-sdk"],
+      },
+    },
   },
   plugins: [
     react({
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0dedc40..c3578cb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -17,6 +17,9 @@ importers:
 
   packages/live2d:
     dependencies:
+      '@halo-dev/ai-foundation-sdk':
+        specifier: 1.0.0-beta.1
+        version: 1.0.0-beta.1(vue@3.5.38(typescript@5.7.3))
       '@lit/context':
         specifier: ^1.1.6
         version: 1.1.6
@@ -56,7 +59,7 @@ importers:
         version: 19.2.3(@types/react@19.2.14)
       '@unocss/postcss':
         specifier: ^66.6.8
-        version: 66.6.8(postcss@8.5.14)
+        version: 66.6.8(postcss@8.5.15)
       '@vitejs/plugin-react':
         specifier: ^6.0.2
         version: 6.0.2(vite@8.0.13(@types/node@22.13.1)(jiti@2.7.0)(terser@5.38.0)(tsx@4.19.2))
@@ -68,7 +71,7 @@ importers:
         version: 2.0.2
       unocss:
         specifier: ^66.6.8
-        version: 66.6.8(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)(@unocss/postcss@66.6.8(postcss@8.5.14))(vite@8.0.13(@types/node@22.13.1)(jiti@2.7.0)(terser@5.38.0)(tsx@4.19.2))
+        version: 66.6.8(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)(@unocss/postcss@66.6.8(postcss@8.5.15))(vite@8.0.13(@types/node@22.13.1)(jiti@2.7.0)(terser@5.38.0)(tsx@4.19.2))
       vite:
         specifier: ^8.0.13
         version: 8.0.13(@types/node@22.13.1)(jiti@2.7.0)(terser@5.38.0)(tsx@4.19.2)
@@ -96,10 +99,27 @@ packages:
   '@asamuzakjp/nwsapi@2.3.9':
     resolution: {integrity: sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==}
 
+  '@babel/helper-string-parser@7.29.7':
+    resolution: {integrity: sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-identifier@7.29.7':
+    resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/parser@7.29.7':
+    resolution: {integrity: sha512-hnORnjP/1P/zFEndoeX+n+t1RwWRJiJpM/jO7FW32Kn9r5+sJB2JWOdYo4L6k78j15eCwY3Gm/7364B1EMwtNg==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
   '@babel/runtime@7.26.7':
     resolution: {integrity: sha512-AOPI3D+a8dXnja+iwsUqGRjr1BbZIe771sXdapOtYI531gSqpi92vXivKcq2asu/DFpdl1ceFAKZyRzK2PCVcQ==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/types@7.29.7':
+    resolution: {integrity: sha512-4zBIxpPzowiZpusoFkyGVwakdRJUyuH5PxQ/PrqghfdFWWasvnCdPfQXHrenDai+gyLARulZjZowCOj6fjT4pA==}
+    engines: {node: '>=6.9.0'}
+
   '@biomejs/biome@1.9.4':
     resolution: {integrity: sha512-1rkd7G70+o9KkTn5KLmDYXihGoTaIGO9PIIN2ZB7UJxFrWw04CZHPYiMRjYsaDvVV7hP1dYNRLxSANLaBFGpog==}
     engines: {node: '>=14.21.3'}
@@ -359,6 +379,15 @@ packages:
       '@noble/hashes':
         optional: true
 
+  '@halo-dev/ai-foundation-sdk@1.0.0-beta.1':
+    resolution: {integrity: sha512-r9bOT0Azso7iJldN8k2AiSBJrTJjFQ9lmRegPxbA2hueZ9xdGnvYl6eM5M25sJvzA0yO1lpvZnji5v/WP/SJVQ==}
+    peerDependencies:
+      vue: ^3.5.x
+      zod: '*'
+    peerDependenciesMeta:
+      zod:
+        optional: true
+
   '@iconify/types@2.0.0':
     resolution: {integrity: sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==}
 
@@ -813,6 +842,35 @@ packages:
   '@vscode/web-custom-data@0.4.13':
     resolution: {integrity: sha512-2ZUIRfhofZ/npLlf872EBnPmn27Kt4M2UssmQIfnJvgGgMYZJ5fvtHEDnttBBf2hnVtBgNCqZMVHJA+wsFVqTA==}
 
+  '@vue/compiler-core@3.5.38':
+    resolution: {integrity: sha512-s99aGxWYig9ErHbct27KXEGhrBYlRI6c4MwAgXErOAbX9xiW37/uMa+XUDO69zLz83dng8UUZ70CTOJrLrYrEQ==}
+
+  '@vue/compiler-dom@3.5.38':
+    resolution: {integrity: sha512-JTqp25l8aFfJYF7/KmsXZjAxJz7T+SjmTJLoXVjHtc2BrSgSiW2n9Aem/cWq1OPe68A8JL06B3eVdhlP0H4TVw==}
+
+  '@vue/compiler-sfc@3.5.38':
+    resolution: {integrity: sha512-DuA2GiZawSEW442iw/9+Fkol8hTgb4Ke5KkhmSry65QA7YuyMbIdy8p0XZRMvNwJdgRz307W8g1CSzdvS4nuNg==}
+
+  '@vue/compiler-ssr@3.5.38':
+    resolution: {integrity: sha512-7s+W5Gc42FGxZMcuwl8H5B29T8BJPMdBT7KHFE+BbAuZ/iTEdTtv7z2XiMjiaUUw4w3ZcCEdHs36RuYJ2VA7bA==}
+
+  '@vue/reactivity@3.5.38':
+    resolution: {integrity: sha512-pG6LV/NDNRbKizcUjFFLAfjaL8mcv4DmR9avNcUw2gDHBzZneuS2TWCmp633ynzxz9YYKNeEPK2I8Wraqy2HUQ==}
+
+  '@vue/runtime-core@3.5.38':
+    resolution: {integrity: sha512-iyW8WVfF1CpCXxncZY5Ei6rSd6oZr5DgEom//fUjRBRl56AXPD+s9ATvukRt77ZFTuYlnVA1bxY+dJB94tWVYw==}
+
+  '@vue/runtime-dom@3.5.38':
+    resolution: {integrity: sha512-apX2wt9sdfDshS+a2xueFZLVpt0GkRJZSoPmrW/SA4yzXTznhfcMVW59gr7h4YQeY0vJhdJkk2rsIDwgfFgC5A==}
+
+  '@vue/server-renderer@3.5.38':
+    resolution: {integrity: sha512-vue8vbf2QlV4quHqzwmJy6dWfmRhP1J8l4wtZg60CL6VoKqcPY2oe7may3+1d9qfpedjK5PRLFqd5k3Isj9mUw==}
+    peerDependencies:
+      vue: 3.5.38
+
+  '@vue/shared@3.5.38':
+    resolution: {integrity: sha512-FTW0AFZNaK5/mOqvGBwVfUlNLU38TiQn4+DQgIFUnrBBJQ1crMJ82yeGQLV5jyKFsO8yRukpbuP7x+nRbH6aug==}
+
   '@webgpu/types@0.1.70':
     resolution: {integrity: sha512-LFiNHHKMvmAEvwVew3JLJmTdShhbdwRFSImUshGhE2mGE8ybQzIo63l5uRp+YKnNx+8Qno8Kf6gN+DKMreIJCA==}
 
@@ -941,6 +999,10 @@ packages:
   emoji-regex@8.0.0:
     resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
 
+  entities@7.0.1:
+    resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==}
+    engines: {node: '>=0.12'}
+
   entities@8.0.0:
     resolution: {integrity: sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA==}
     engines: {node: '>=20.19.0'}
@@ -961,6 +1023,9 @@ packages:
     resolution: {integrity: sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==}
     engines: {node: '>=0.8.0'}
 
+  estree-walker@2.0.2:
+    resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==}
+
   estree-walker@3.0.3:
     resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
 
@@ -1254,6 +1319,10 @@ packages:
     resolution: {integrity: sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==}
     engines: {node: ^10 || ^12 || >=14}
 
+  postcss@8.5.15:
+    resolution: {integrity: sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==}
+    engines: {node: ^10 || ^12 || >=14}
+
   punycode@2.3.1:
     resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
     engines: {node: '>=6'}
@@ -1582,6 +1651,14 @@ packages:
   vscode-uri@2.1.2:
     resolution: {integrity: sha512-8TEXQxlldWAuIODdukIb+TR5s+9Ds40eSJrw+1iDDA9IFORPjMELarNQE3myz5XIkWWpdprmJjm1/SxMlWOC8A==}
 
+  vue@3.5.38:
+    resolution: {integrity: sha512-vAMKHfImQlYSy0C+PBue4s3ERZ2xGKfgZg5GXAsLInq1dyh2H78ILVP5sK0KPFPVW4kv+OGCIvBEondcjpZp7A==}
+    peerDependencies:
+      typescript: '*'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
   w3c-xmlserializer@5.0.0:
     resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==}
     engines: {node: '>=18'}
@@ -1660,10 +1737,23 @@ snapshots:
 
   '@asamuzakjp/nwsapi@2.3.9': {}
 
+  '@babel/helper-string-parser@7.29.7': {}
+
+  '@babel/helper-validator-identifier@7.29.7': {}
+
+  '@babel/parser@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
   '@babel/runtime@7.26.7':
     dependencies:
       regenerator-runtime: 0.14.1
 
+  '@babel/types@7.29.7':
+    dependencies:
+      '@babel/helper-string-parser': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+
   '@biomejs/biome@1.9.4':
     optionalDependencies:
       '@biomejs/cli-darwin-arm64': 1.9.4
@@ -1817,6 +1907,10 @@ snapshots:
 
   '@exodus/bytes@1.15.0': {}
 
+  '@halo-dev/ai-foundation-sdk@1.0.0-beta.1(vue@3.5.38(typescript@5.7.3))':
+    dependencies:
+      vue: 3.5.38(typescript@5.7.3)
+
   '@iconify/types@2.0.0': {}
 
   '@iconify/utils@3.1.3':
@@ -2087,13 +2181,13 @@ snapshots:
       gzip-size: 6.0.0
       sirv: 3.0.2
 
-  '@unocss/postcss@66.6.8(postcss@8.5.14)':
+  '@unocss/postcss@66.6.8(postcss@8.5.15)':
     dependencies:
       '@unocss/config': 66.6.8
       '@unocss/core': 66.6.8
       '@unocss/rule-utils': 66.6.8
       css-tree: 3.2.1
-      postcss: 8.5.14
+      postcss: 8.5.15
       tinyglobby: 0.2.16
 
   '@unocss/preset-attributify@66.6.8':
@@ -2237,6 +2331,60 @@ snapshots:
 
   '@vscode/web-custom-data@0.4.13': {}
 
+  '@vue/compiler-core@3.5.38':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@vue/shared': 3.5.38
+      entities: 7.0.1
+      estree-walker: 2.0.2
+      source-map-js: 1.2.1
+
+  '@vue/compiler-dom@3.5.38':
+    dependencies:
+      '@vue/compiler-core': 3.5.38
+      '@vue/shared': 3.5.38
+
+  '@vue/compiler-sfc@3.5.38':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@vue/compiler-core': 3.5.38
+      '@vue/compiler-dom': 3.5.38
+      '@vue/compiler-ssr': 3.5.38
+      '@vue/shared': 3.5.38
+      estree-walker: 2.0.2
+      magic-string: 0.30.21
+      postcss: 8.5.15
+      source-map-js: 1.2.1
+
+  '@vue/compiler-ssr@3.5.38':
+    dependencies:
+      '@vue/compiler-dom': 3.5.38
+      '@vue/shared': 3.5.38
+
+  '@vue/reactivity@3.5.38':
+    dependencies:
+      '@vue/shared': 3.5.38
+
+  '@vue/runtime-core@3.5.38':
+    dependencies:
+      '@vue/reactivity': 3.5.38
+      '@vue/shared': 3.5.38
+
+  '@vue/runtime-dom@3.5.38':
+    dependencies:
+      '@vue/reactivity': 3.5.38
+      '@vue/runtime-core': 3.5.38
+      '@vue/shared': 3.5.38
+      csstype: 3.2.3
+
+  '@vue/server-renderer@3.5.38(vue@3.5.38(typescript@5.7.3))':
+    dependencies:
+      '@vue/compiler-ssr': 3.5.38
+      '@vue/shared': 3.5.38
+      vue: 3.5.38(typescript@5.7.3)
+
+  '@vue/shared@3.5.38': {}
+
   '@webgpu/types@0.1.70': {}
 
   '@xmldom/xmldom@0.8.13': {}
@@ -2345,6 +2493,8 @@ snapshots:
 
   emoji-regex@8.0.0: {}
 
+  entities@7.0.1: {}
+
   entities@8.0.0: {}
 
   es-module-lexer@2.1.0: {}
@@ -2381,6 +2531,8 @@ snapshots:
 
   escape-string-regexp@1.0.5: {}
 
+  estree-walker@2.0.2: {}
+
   estree-walker@3.0.3:
     dependencies:
       '@types/estree': 1.0.9
@@ -2696,6 +2848,12 @@ snapshots:
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
+  postcss@8.5.15:
+    dependencies:
+      nanoid: 3.3.12
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
   punycode@2.3.1: {}
 
   quansync@1.0.0: {}
@@ -2887,7 +3045,7 @@ snapshots:
 
   undici@7.25.0: {}
 
-  unocss@66.6.8(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)(@unocss/postcss@66.6.8(postcss@8.5.14))(vite@8.0.13(@types/node@22.13.1)(jiti@2.7.0)(terser@5.38.0)(tsx@4.19.2)):
+  unocss@66.6.8(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)(@unocss/postcss@66.6.8(postcss@8.5.15))(vite@8.0.13(@types/node@22.13.1)(jiti@2.7.0)(terser@5.38.0)(tsx@4.19.2)):
     dependencies:
       '@unocss/cli': 66.6.8
       '@unocss/core': 66.6.8
@@ -2907,7 +3065,7 @@ snapshots:
       '@unocss/transformer-variant-group': 66.6.8
       '@unocss/vite': 66.6.8(vite@8.0.13(@types/node@22.13.1)(jiti@2.7.0)(terser@5.38.0)(tsx@4.19.2))
     optionalDependencies:
-      '@unocss/postcss': 66.6.8(postcss@8.5.14)
+      '@unocss/postcss': 66.6.8(postcss@8.5.15)
     transitivePeerDependencies:
       - '@emnapi/core'
       - '@emnapi/runtime'
@@ -2994,6 +3152,16 @@ snapshots:
 
   vscode-uri@2.1.2: {}
 
+  vue@3.5.38(typescript@5.7.3):
+    dependencies:
+      '@vue/compiler-dom': 3.5.38
+      '@vue/compiler-sfc': 3.5.38
+      '@vue/runtime-dom': 3.5.38
+      '@vue/server-renderer': 3.5.38(vue@3.5.38(typescript@5.7.3))
+      '@vue/shared': 3.5.38
+    optionalDependencies:
+      typescript: 5.7.3
+
   w3c-xmlserializer@5.0.0:
     dependencies:
       xml-name-validator: 5.0.0
diff --git a/src/main/java/run/halo/live2d/Live2dSettingProcess.java b/src/main/java/run/halo/live2d/Live2dSettingProcess.java
index a6242b8..17ded8d 100644
--- a/src/main/java/run/halo/live2d/Live2dSettingProcess.java
+++ b/src/main/java/run/halo/live2d/Live2dSettingProcess.java
@@ -1,6 +1,7 @@
 package run.halo.live2d;
 
 import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ArrayNode;
 import com.fasterxml.jackson.databind.node.JsonNodeFactory;
 import com.fasterxml.jackson.databind.node.ObjectNode;
@@ -9,6 +10,8 @@
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Component;
 import reactor.core.publisher.Mono;
+import run.halo.live2d.agent.AgentSettings;
+import run.halo.live2d.agent.AgentToolNormalizer;
 import run.halo.app.plugin.ReactiveSettingFetcher;
 
 /**
@@ -29,8 +32,14 @@ public class Live2dSettingProcess implements Live2dSetting {
         "openConsole", "openConsoleTip", "selectorTips", "tipsPath");
     private static final List<String> ADVANCED_FIELDS = List.of(
         "consoleShowStatu", "photoName", "live2dLocation");
+    private static final List<String> AI_CHAT_PUBLIC_FIELDS = List.of(
+        "chunkTimeout", "showChatMessageTimeout", "autoContinuationMessageMinVisibleMs",
+        "requestAcceptedMessage", "reasoningMessages", "reasoningMessageInterval",
+        "chatContextRounds");
 
     private final ReactiveSettingFetcher settingFetcher;
+    private final AgentToolNormalizer agentToolNormalizer;
+    private final ObjectMapper objectMapper = new ObjectMapper();
 
     @Override
     public Mono<JsonNode> getGroup(String groupName) {
@@ -51,6 +60,7 @@ public Mono<JsonNode> getPublicConfig(String themeTipsPath) {
             copyFields(objectNode, data.get("tips"), TIPS_FIELDS);
             copyFields(objectNode, data.get("advanced"), ADVANCED_FIELDS);
             copyAiChatFields(objectNode, data.get("aichat"));
+            copyAgentFields(objectNode, data.get("agent"));
             copyCustomTools(objectNode, data.get("customTools"));
             if (themeTipsPath != null && !themeTipsPath.isBlank()) {
                 objectNode.put("themeTipsPath", themeTipsPath);
@@ -86,8 +96,46 @@ private void copyAiChatFields(ObjectNode target, JsonNode source) {
             return;
         }
 
-        copyField(target, aiChatBaseSetting, "chunkTimeout");
-        copyField(target, aiChatBaseSetting, "showChatMessageTimeout");
+        copyFields(target, aiChatBaseSetting, AI_CHAT_PUBLIC_FIELDS);
+    }
+
+    private void copyAgentFields(ObjectNode target, JsonNode source) {
+        if (source == null || source.isNull()) {
+            return;
+        }
+
+        AgentSettings settings = objectMapper.convertValue(source, AgentSettings.class);
+        ObjectNode agentNode = JsonNodeFactory.instance.objectNode();
+        agentNode.set("builtIn", objectMapper.valueToTree(settings.builtIn()));
+        ObjectNode securityNode = JsonNodeFactory.instance.objectNode();
+        securityNode.set("allowedExternalOrigins",
+            objectMapper.valueToTree(settings.toolSecurity().normalizedAllowedExternalOrigins()));
+        securityNode.put("allowNewTab", settings.toolSecurity().allowNewTab());
+        agentNode.set("toolSecurity", securityNode);
+        ObjectNode searchNode = JsonNodeFactory.instance.objectNode();
+        searchNode.set("allowedTypes",
+            objectMapper.valueToTree(settings.haloSearch().normalizedAllowedTypes()));
+        searchNode.put("defaultLimit", settings.haloSearch().normalizedDefaultLimit());
+        agentNode.set("haloSearch", searchNode);
+        agentNode.set("haloResourceDetail", objectMapper.valueToTree(settings.haloResourceDetail()));
+
+        ArrayNode tools = JsonNodeFactory.instance.arrayNode();
+        agentToolNormalizer.normalizeCustomTools(settings).forEach(tool -> {
+            ObjectNode toolNode = JsonNodeFactory.instance.objectNode();
+            toolNode.put("name", tool.name());
+            toolNode.put("description", tool.description());
+            toolNode.set("inputSchema", objectMapper.valueToTree(tool.inputSchema()));
+            toolNode.put("approval", tool.approval().value());
+            toolNode.put("requiredAuth", tool.requiredAuth().value());
+            toolNode.put("actionType", tool.actionType());
+            toolNode.set("action", tool.action());
+            if (tool.testInput() != null && !tool.testInput().isNull()) {
+                toolNode.set("testInput", tool.testInput());
+            }
+            tools.add(toolNode);
+        });
+        agentNode.set("aiTools", tools);
+        target.set("agent", agentNode);
     }
 
     private void copyCustomTools(ObjectNode target, JsonNode source) {
diff --git a/src/main/java/run/halo/live2d/agent/AgentAccessMode.java b/src/main/java/run/halo/live2d/agent/AgentAccessMode.java
new file mode 100644
index 0000000..f464dff
--- /dev/null
+++ b/src/main/java/run/halo/live2d/agent/AgentAccessMode.java
@@ -0,0 +1,48 @@
+package run.halo.live2d.agent;
+
+public enum AgentAccessMode {
+    ANONYMOUS_CHAT("anonymous_chat", true, false, false),
+    ANONYMOUS_CHAT_AGENT("anonymous_chat_agent", true, true, false),
+    AUTHENTICATED_CHAT("authenticated_chat", false, false, true),
+    AUTHENTICATED_CHAT_AGENT("authenticated_chat_agent", false, true, true);
+
+    private final String value;
+    private final boolean anonymousChatAllowed;
+    private final boolean agentAllowed;
+    private final boolean authenticationRequired;
+
+    AgentAccessMode(String value, boolean anonymousChatAllowed, boolean agentAllowed,
+        boolean authenticationRequired) {
+        this.value = value;
+        this.anonymousChatAllowed = anonymousChatAllowed;
+        this.agentAllowed = agentAllowed;
+        this.authenticationRequired = authenticationRequired;
+    }
+
+    public String value() {
+        return value;
+    }
+
+    public boolean anonymousChatAllowed() {
+        return anonymousChatAllowed;
+    }
+
+    public boolean agentAllowed() {
+        return agentAllowed;
+    }
+
+    public boolean authenticationRequired() {
+        return authenticationRequired;
+    }
+
+    public static AgentAccessMode from(String value, boolean legacyAnonymous) {
+        if (value != null) {
+            for (var mode : values()) {
+                if (mode.value.equals(value)) {
+                    return mode;
+                }
+            }
+        }
+        return legacyAnonymous ? ANONYMOUS_CHAT : AUTHENTICATED_CHAT;
+    }
+}
diff --git a/src/main/java/run/halo/live2d/agent/AgentBrowserActionType.java b/src/main/java/run/halo/live2d/agent/AgentBrowserActionType.java
new file mode 100644
index 0000000..6dcbe2e
--- /dev/null
+++ b/src/main/java/run/halo/live2d/agent/AgentBrowserActionType.java
@@ -0,0 +1,22 @@
+package run.halo.live2d.agent;
+
+import java.util.Set;
+
+public final class AgentBrowserActionType {
+    public static final String NAVIGATE = "navigate";
+    public static final String SCROLL_TO = "scroll-to";
+    public static final String HIGHLIGHT = "highlight";
+    public static final String DISPATCH_EVENT = "dispatch-event";
+    public static final String REGISTERED = "registered";
+
+    public static final Set<String> SUPPORTED = Set.of(
+        NAVIGATE,
+        SCROLL_TO,
+        HIGHLIGHT,
+        DISPATCH_EVENT,
+        REGISTERED
+    );
+
+    private AgentBrowserActionType() {
+    }
+}
diff --git a/src/main/java/run/halo/live2d/agent/AgentCommentCapability.java b/src/main/java/run/halo/live2d/agent/AgentCommentCapability.java
new file mode 100644
index 0000000..a00928a
--- /dev/null
+++ b/src/main/java/run/halo/live2d/agent/AgentCommentCapability.java
@@ -0,0 +1,33 @@
+package run.halo.live2d.agent;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonValue;
+
+public enum AgentCommentCapability {
+    OFF("off"),
+    ASSIST("assist"),
+    SUBMIT("submit");
+
+    private final String value;
+
+    AgentCommentCapability(String value) {
+        this.value = value;
+    }
+
+    @JsonValue
+    public String value() {
+        return value;
+    }
+
+    @JsonCreator
+    public static AgentCommentCapability from(String value) {
+        if (value != null) {
+            for (var capability : values()) {
+                if (capability.value.equals(value)) {
+                    return capability;
+                }
+            }
+        }
+        return ASSIST;
+    }
+}
diff --git a/src/main/java/run/halo/live2d/agent/AgentSettings.java b/src/main/java/run/halo/live2d/agent/AgentSettings.java
new file mode 100644
index 0000000..d372294
--- /dev/null
+++ b/src/main/java/run/halo/live2d/agent/AgentSettings.java
@@ -0,0 +1,198 @@
+package run.halo.live2d.agent;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record AgentSettings(
+    AgentBuiltInCapabilities builtIn,
+    Object aiTools,
+    AgentToolSecurity toolSecurity,
+    AgentHaloSearchSettings haloSearch,
+    AgentHaloResourceDetailSettings haloResourceDetail,
+    AgentNetworkAccessSettings networkAccess
+) {
+    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
+    public AgentSettings {
+        builtIn = builtIn == null ? AgentBuiltInCapabilities.defaults() : builtIn;
+        aiTools = aiTools == null ? List.of() : aiTools;
+        toolSecurity = toolSecurity == null ? AgentToolSecurity.defaults() : toolSecurity;
+        haloSearch = haloSearch == null ? AgentHaloSearchSettings.defaults() : haloSearch;
+        haloResourceDetail = haloResourceDetail == null
+            ? AgentHaloResourceDetailSettings.defaults()
+            : haloResourceDetail;
+        networkAccess = networkAccess == null
+            ? AgentNetworkAccessSettings.defaults()
+            : networkAccess;
+    }
+
+    public static AgentSettings defaults() {
+        return new AgentSettings(null, List.of(), null, null, null, null);
+    }
+
+    public List<AgentToolConfig> normalizedAiTools() {
+        if (aiTools instanceof List<?> list) {
+            return list.stream()
+                .map(item -> OBJECT_MAPPER.convertValue(item, AgentToolConfig.class))
+                .toList();
+        }
+        if (aiTools instanceof String text && !text.isBlank()) {
+            try {
+                return OBJECT_MAPPER.readerForListOf(AgentToolConfig.class).readValue(text);
+            } catch (Exception e) {
+                return List.of();
+            }
+        }
+        return List.of();
+    }
+
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public record AgentBuiltInCapabilities(
+        boolean pageContext,
+        boolean haloNavigation,
+        boolean haloContentSearch,
+        boolean networkAccess,
+        AgentCommentCapability commentCapability
+    ) {
+        public AgentBuiltInCapabilities {
+            commentCapability = commentCapability == null
+                ? AgentCommentCapability.ASSIST
+                : commentCapability;
+        }
+
+        public static AgentBuiltInCapabilities defaults() {
+            return new AgentBuiltInCapabilities(true, true, true, false,
+                AgentCommentCapability.ASSIST);
+        }
+    }
+
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public record AgentToolSecurity(
+        Object allowedExternalOrigins,
+        boolean allowNewTab
+    ) {
+        public static AgentToolSecurity defaults() {
+            return new AgentToolSecurity(List.of(), false);
+        }
+
+        public List<String> normalizedAllowedExternalOrigins() {
+            return normalizeStringList(allowedExternalOrigins, "origin");
+        }
+    }
+
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public record AgentHaloSearchSettings(
+        List<String> allowedTypes,
+        int defaultLimit
+    ) {
+        public static AgentHaloSearchSettings defaults() {
+            return new AgentHaloSearchSettings(List.of(), 5);
+        }
+
+        public List<String> normalizedAllowedTypes() {
+            var normalized = normalizeStringList(allowedTypes);
+            return normalized.isEmpty()
+                ? List.of("post.content.halo.run", "singlepage.content.halo.run")
+                : normalized;
+        }
+
+        public int normalizedDefaultLimit() {
+            return defaultLimit < 1 || defaultLimit > 20 ? 5 : defaultLimit;
+        }
+    }
+
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public record AgentHaloResourceDetailSettings(
+        int maxContentChars
+    ) {
+        public AgentHaloResourceDetailSettings {
+            if (maxContentChars < 500) {
+                maxContentChars = 3000;
+            }
+            if (maxContentChars > 10000) {
+                maxContentChars = 10000;
+            }
+        }
+
+        public static AgentHaloResourceDetailSettings defaults() {
+            return new AgentHaloResourceDetailSettings(3000);
+        }
+    }
+
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public record AgentNetworkAccessSettings(
+        Object allowedOrigins,
+        int maxResponseChars,
+        int timeoutSeconds
+    ) {
+        public static AgentNetworkAccessSettings defaults() {
+            return new AgentNetworkAccessSettings(List.of(), 4000, 5);
+        }
+
+        public List<String> normalizedAllowedOrigins() {
+            return normalizeStringList(allowedOrigins, "origin");
+        }
+
+        public int normalizedMaxResponseChars() {
+            return maxResponseChars < 1000 || maxResponseChars > 20000
+                ? 4000
+                : maxResponseChars;
+        }
+
+        public int normalizedTimeoutSeconds() {
+            return timeoutSeconds < 1 || timeoutSeconds > 15 ? 5 : timeoutSeconds;
+        }
+    }
+
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public record AgentToolConfig(
+        String name,
+        boolean enabled,
+        String description,
+        JsonNode inputSchema,
+        AgentToolApproval approval,
+        AgentToolAuth requiredAuth,
+        JsonNode action,
+        JsonNode testInput
+    ) {
+        public AgentToolConfig {
+            approval = approval == null ? AgentToolApproval.DEFAULT : approval;
+            requiredAuth = requiredAuth == null ? AgentToolAuth.NONE : requiredAuth;
+        }
+    }
+
+    @SuppressWarnings("unchecked")
+    private static List<String> normalizeStringList(Object value, String objectField) {
+        if (!(value instanceof List<?> list)) {
+            return List.of();
+        }
+        List<String> normalized = new ArrayList<>();
+        for (var item : list) {
+            if (item instanceof String text && !text.isBlank()) {
+                normalized.add(text.trim());
+                continue;
+            }
+            if (item instanceof Map<?, ?> map) {
+                var nested = map.get(objectField);
+                if (nested instanceof String text && !text.isBlank()) {
+                    normalized.add(text.trim());
+                }
+            }
+        }
+        return List.copyOf(normalized);
+    }
+
+    private static List<String> normalizeStringList(List<?> list) {
+        return list.stream()
+            .filter(String.class::isInstance)
+            .map(String.class::cast)
+            .map(String::trim)
+            .filter(text -> !text.isBlank())
+            .toList();
+    }
+}
diff --git a/src/main/java/run/halo/live2d/agent/AgentToolApproval.java b/src/main/java/run/halo/live2d/agent/AgentToolApproval.java
new file mode 100644
index 0000000..1580e6e
--- /dev/null
+++ b/src/main/java/run/halo/live2d/agent/AgentToolApproval.java
@@ -0,0 +1,33 @@
+package run.halo.live2d.agent;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonValue;
+
+public enum AgentToolApproval {
+    DEFAULT("default"),
+    NEVER("never"),
+    ALWAYS("always");
+
+    private final String value;
+
+    AgentToolApproval(String value) {
+        this.value = value;
+    }
+
+    @JsonValue
+    public String value() {
+        return value;
+    }
+
+    @JsonCreator
+    public static AgentToolApproval from(String value) {
+        if (value != null) {
+            for (var approval : values()) {
+                if (approval.value.equals(value)) {
+                    return approval;
+                }
+            }
+        }
+        return DEFAULT;
+    }
+}
diff --git a/src/main/java/run/halo/live2d/agent/AgentToolAuth.java b/src/main/java/run/halo/live2d/agent/AgentToolAuth.java
new file mode 100644
index 0000000..18c4d5e
--- /dev/null
+++ b/src/main/java/run/halo/live2d/agent/AgentToolAuth.java
@@ -0,0 +1,36 @@
+package run.halo.live2d.agent;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonValue;
+
+public enum AgentToolAuth {
+    NONE("none"),
+    AUTHENTICATED("authenticated");
+
+    private final String value;
+
+    AgentToolAuth(String value) {
+        this.value = value;
+    }
+
+    @JsonValue
+    public String value() {
+        return value;
+    }
+
+    @JsonCreator
+    public static AgentToolAuth from(String value) {
+        return from(value, NONE);
+    }
+
+    public static AgentToolAuth from(String value, AgentToolAuth defaultValue) {
+        if (value != null) {
+            for (var auth : values()) {
+                if (auth.value.equals(value)) {
+                    return auth;
+                }
+            }
+        }
+        return defaultValue;
+    }
+}
diff --git a/src/main/java/run/halo/live2d/agent/AgentToolNormalizer.java b/src/main/java/run/halo/live2d/agent/AgentToolNormalizer.java
new file mode 100644
index 0000000..524fded
--- /dev/null
+++ b/src/main/java/run/halo/live2d/agent/AgentToolNormalizer.java
@@ -0,0 +1,201 @@
+package run.halo.live2d.agent;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Set;
+import java.util.regex.Pattern;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.stereotype.Component;
+
+@Slf4j
+@Component
+public class AgentToolNormalizer {
+    private static final Pattern TOOL_NAME_PATTERN = Pattern.compile("^[a-z][a-z0-9_]{2,63}$");
+    private static final Set<String> SCALAR_TYPES = Set.of("string", "number", "integer",
+        "boolean");
+    private static final Set<String> PROPERTY_KEYWORDS = Set.of("type", "description", "enum",
+        "default", "minimum", "maximum", "minLength", "maxLength");
+    private static final Set<String> ROOT_KEYWORDS = Set.of("type", "properties", "required",
+        "description");
+    private static final Set<String> RESERVED_TOOL_NAMES = Set.of(
+        "perform_live2d_action",
+        "get_current_page_context",
+        "open_halo_resource",
+        "search_halo_resources",
+        "get_halo_resource_detail",
+        "get_latest_halo_resources",
+        "get_categories",
+        "get_tags",
+        "get_posts_by_category",
+        "get_posts_by_tag",
+        "get_pages",
+        "fetch_allowed_url",
+        "open_comment_area",
+        "get_recent_comments",
+        "draft_comment",
+        "submit_comment"
+    );
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    public List<NormalizedAgentTool> normalizeCustomTools(AgentSettings settings) {
+        if (settings == null) {
+            return List.of();
+        }
+        List<NormalizedAgentTool> normalized = new ArrayList<>();
+        Set<String> names = new HashSet<>(RESERVED_TOOL_NAMES);
+        for (var tool : settings.normalizedAiTools()) {
+            normalizeCustomTool(tool, names).ifPresent(normalized::add);
+        }
+        return List.copyOf(normalized);
+    }
+
+    public java.util.Optional<NormalizedAgentTool> normalizeCustomTool(
+        AgentSettings.AgentToolConfig tool, Set<String> usedNames) {
+        if (tool == null || !tool.enabled()) {
+            return java.util.Optional.empty();
+        }
+
+        var name = StringUtils.trimToEmpty(tool.name()).toLowerCase(Locale.ROOT);
+        if (!TOOL_NAME_PATTERN.matcher(name).matches()) {
+            log.warn("Ignore invalid Agent tool name: {}", tool.name());
+            return java.util.Optional.empty();
+        }
+        if (!usedNames.add(name)) {
+            log.warn("Ignore duplicated or reserved Agent tool name: {}", name);
+            return java.util.Optional.empty();
+        }
+
+        var description = StringUtils.trimToNull(tool.description());
+        if (description == null) {
+            log.warn("Ignore Agent tool {} because description is blank", name);
+            return java.util.Optional.empty();
+        }
+
+        var inputSchema = normalizeSchema(tool.inputSchema());
+        if (inputSchema == null) {
+            log.warn("Ignore Agent tool {} because input schema is invalid", name);
+            return java.util.Optional.empty();
+        }
+
+        var action = tool.action();
+        var actionType = action == null || action.isNull() ? null : textValue(action, "type");
+        if (!AgentBrowserActionType.SUPPORTED.contains(actionType)) {
+            log.warn("Ignore Agent tool {} because action type is invalid: {}", name, actionType);
+            return java.util.Optional.empty();
+        }
+
+        return java.util.Optional.of(new NormalizedAgentTool(
+            name,
+            description,
+            inputSchema,
+            tool.approval(),
+            tool.requiredAuth(),
+            actionType,
+            action,
+            tool.testInput()
+        ));
+    }
+
+    @SuppressWarnings("unchecked")
+    public Map<String, Object> normalizeSchema(JsonNode schema) {
+        if (schema == null || schema.isNull()) {
+            return Map.of("type", "object", "properties", Map.of());
+        }
+        if (!schema.isObject() || !"object".equals(textValue(schema, "type"))) {
+            return null;
+        }
+        if (!allowedKeys(schema, ROOT_KEYWORDS)) {
+            return null;
+        }
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("type", "object");
+        putIfText(result, "description", textValue(schema, "description"));
+
+        Map<String, Object> properties = new LinkedHashMap<>();
+        var propertyNode = schema.get("properties");
+        if (propertyNode != null && !propertyNode.isNull()) {
+            if (!propertyNode.isObject()) {
+                return null;
+            }
+            var fields = propertyNode.fields();
+            while (fields.hasNext()) {
+                var entry = fields.next();
+                if (!entry.getValue().isObject()) {
+                    return null;
+                }
+                var propertySchema = normalizePropertySchema(entry.getValue());
+                if (propertySchema == null) {
+                    return null;
+                }
+                properties.put(entry.getKey(), propertySchema);
+            }
+        }
+        result.put("properties", properties);
+
+        var required = schema.get("required");
+        if (required != null && !required.isNull()) {
+            if (!required.isArray()) {
+                return null;
+            }
+            List<String> requiredNames = new ArrayList<>();
+            required.forEach(item -> {
+                if (item.isTextual() && properties.containsKey(item.asText())) {
+                    requiredNames.add(item.asText());
+                }
+            });
+            if (!requiredNames.isEmpty()) {
+                result.put("required", requiredNames);
+            }
+        }
+        return result;
+    }
+
+    private Map<String, Object> normalizePropertySchema(JsonNode schema) {
+        if (!allowedKeys(schema, PROPERTY_KEYWORDS)) {
+            return null;
+        }
+        var type = textValue(schema, "type");
+        if (!SCALAR_TYPES.contains(type)) {
+            return null;
+        }
+        Map<String, Object> result = objectMapper.convertValue(schema,
+            new TypeReference<Map<String, Object>>() {
+            });
+        result.keySet().retainAll(PROPERTY_KEYWORDS);
+        result.put("type", type);
+        return result;
+    }
+
+    private boolean allowedKeys(JsonNode node, Set<String> allowed) {
+        var fields = node.fieldNames();
+        while (fields.hasNext()) {
+            if (!allowed.contains(fields.next())) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    private void putIfText(Map<String, Object> target, String key, String value) {
+        if (StringUtils.isNotBlank(value)) {
+            target.put(key, value);
+        }
+    }
+
+    private String textValue(JsonNode source, String field) {
+        if (source == null || source.isNull()) {
+            return null;
+        }
+        var value = source.get(field);
+        return value == null || value.isNull() ? null : StringUtils.trimToNull(value.asText());
+    }
+}
diff --git a/src/main/java/run/halo/live2d/agent/AgentToolService.java b/src/main/java/run/halo/live2d/agent/AgentToolService.java
new file mode 100644
index 0000000..0a5182b
--- /dev/null
+++ b/src/main/java/run/halo/live2d/agent/AgentToolService.java
@@ -0,0 +1,224 @@
+package run.halo.live2d.agent;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+import run.halo.aifoundation.schema.JsonSchema;
+import run.halo.aifoundation.tool.ToolDefinition;
+
+@Component
+@RequiredArgsConstructor
+public class AgentToolService {
+    private final AgentToolNormalizer normalizer;
+    private final HaloAgentPresetToolService haloPresetToolService;
+
+    public AgentToolSet buildTools(AgentSettings settings, AgentAccessMode accessMode,
+        boolean authenticated) {
+        if (!accessMode.agentAllowed()) {
+            return AgentToolSet.disabled();
+        }
+
+        var resolvedSettings = settings == null ? AgentSettings.defaults() : settings;
+        List<ToolDefinition> tools = new ArrayList<>();
+        addBuiltInBrowserTools(tools, resolvedSettings);
+        addHaloPresetTools(tools, resolvedSettings);
+        normalizer.normalizeCustomTools(resolvedSettings).stream()
+            .filter(tool -> isAllowed(tool.requiredAuth(), authenticated))
+            .map(this::toBrowserToolDefinition)
+            .forEach(tools::add);
+        return new AgentToolSet(true, List.copyOf(tools));
+    }
+
+    private void addHaloPresetTools(List<ToolDefinition> tools, AgentSettings settings) {
+        var builtIn = settings.builtIn();
+        if (builtIn.haloContentSearch()) {
+            tools.add(ToolDefinition.builder()
+                .name("search_halo_resources")
+                .description("使用 Halo 自身全文搜索引擎搜索公开内容资源，适合查找文章、页面或其他已接入搜索索引的公开内容。")
+                .inputSchema(JsonSchema.object()
+                    .property("keyword", JsonSchema.string().description("搜索关键词"))
+                    .property("limit", JsonSchema.integer().description("返回数量，1 到 20"))
+                    .property("includeTypes", JsonSchema.array(JsonSchema.string().build())
+                        .description("可选内容类型列表，只会使用站点允许的类型"))
+                    .required("keyword")
+                    .build())
+                .executor(context -> haloPresetToolService.searchHaloResources(context.getInput(),
+                    settings))
+                .build());
+            tools.add(ToolDefinition.builder()
+                .name("get_halo_resource_detail")
+                .description("读取已查询到的公开 Halo 资源的有限详情，用于总结或介绍资源内容。")
+                .inputSchema(JsonSchema.object()
+                    .property("resourceId", JsonSchema.string().description("可信资源 ID"))
+                    .required("resourceId")
+                    .build())
+                .executor(context -> haloPresetToolService.getHaloResourceDetail(context.getInput(),
+                    settings))
+                .build());
+            tools.add(ToolDefinition.builder()
+                .name("get_latest_halo_resources")
+                .description("查看站点最新公开内容资源。第一版稳定支持最新文章。")
+                .inputSchema(JsonSchema.object()
+                    .property("limit", JsonSchema.integer().description("返回数量，1 到 20"))
+                    .build())
+                .executor(context -> haloPresetToolService.getLatestHaloResources(
+                    context.getInput()))
+                .build());
+            tools.add(ToolDefinition.builder()
+                .name("get_categories")
+                .description("查看站点公开分类列表。")
+                .inputSchema(JsonSchema.object()
+                    .property("limit", JsonSchema.integer().description("返回数量，1 到 100"))
+                    .build())
+                .executor(context -> haloPresetToolService.getCategories(context.getInput()))
+                .build());
+            tools.add(ToolDefinition.builder()
+                .name("get_tags")
+                .description("查看站点公开标签列表。")
+                .inputSchema(JsonSchema.object()
+                    .property("limit", JsonSchema.integer().description("返回数量，1 到 100"))
+                    .build())
+                .executor(context -> haloPresetToolService.getTags(context.getInput()))
+                .build());
+            tools.add(ToolDefinition.builder()
+                .name("get_posts_by_category")
+                .description("查看指定分类下的公开文章。")
+                .inputSchema(JsonSchema.object()
+                    .property("categoryName", JsonSchema.string().description("分类元数据名称"))
+                    .property("limit", JsonSchema.integer().description("返回数量，1 到 20"))
+                    .required("categoryName")
+                    .build())
+                .executor(context -> haloPresetToolService.getPostsByCategory(context.getInput()))
+                .build());
+            tools.add(ToolDefinition.builder()
+                .name("get_posts_by_tag")
+                .description("查看指定标签下的公开文章。")
+                .inputSchema(JsonSchema.object()
+                    .property("tagName", JsonSchema.string().description("标签元数据名称"))
+                    .property("limit", JsonSchema.integer().description("返回数量，1 到 20"))
+                    .required("tagName")
+                    .build())
+                .executor(context -> haloPresetToolService.getPostsByTag(context.getInput()))
+                .build());
+            tools.add(ToolDefinition.builder()
+                .name("get_pages")
+                .description("查看站点公开独立页面列表。")
+                .inputSchema(JsonSchema.object()
+                    .property("limit", JsonSchema.integer().description("返回数量，1 到 100"))
+                    .build())
+                .executor(context -> haloPresetToolService.getPages(context.getInput()))
+                .build());
+        }
+        if (builtIn.networkAccess()) {
+            tools.add(ToolDefinition.builder()
+                .name("fetch_allowed_url")
+                .description("通过后端读取站长白名单中的公网 URL。仅支持 GET，只能访问网络访问安全策略允许的 Origin，不能访问 localhost、内网或链路本地地址。适合读取公开 API、公开 JSON、文本页面或文档摘要。")
+                .inputSchema(JsonSchema.object()
+                    .property("url", JsonSchema.string().description("要读取的完整公网 URL，必须属于站长配置的允许 Origin"))
+                    .required("url")
+                    .build())
+                .executor(context -> haloPresetToolService.fetchAllowedUrl(context.getInput(),
+                    settings))
+                .build());
+        }
+        if (builtIn.commentCapability() == AgentCommentCapability.ASSIST
+            || builtIn.commentCapability() == AgentCommentCapability.SUBMIT) {
+            tools.add(ToolDefinition.builder()
+                .name("draft_comment")
+                .description("滚动到评论区，并将评论草稿写入当前页面的评论输入框。该工具不会自动提交评论。")
+                .inputSchema(JsonSchema.object()
+                    .property("content", JsonSchema.string().description("评论草稿内容"))
+                    .required("content")
+                    .build())
+                .build());
+        }
+        if (builtIn.commentCapability() == AgentCommentCapability.SUBMIT) {
+            tools.add(ToolDefinition.builder()
+                .name("submit_comment")
+                .description("滚动到评论区，写入评论内容，并在访客审批后尝试提交评论。只有站点评论流程允许且必要校验满足时才可成功。")
+                .inputSchema(JsonSchema.object()
+                    .property("content", JsonSchema.string().description("评论内容"))
+                    .required("content")
+                    .build())
+                .requiresApproval(true)
+                .build());
+        }
+    }
+
+    public String appendCapabilityPrompt(String systemMessage, AgentToolSet toolSet) {
+        if (toolSet == null || !toolSet.agentEnabled() || toolSet.tools().isEmpty()) {
+            return systemMessage + "\n\n【Agent 能力边界】\n"
+                + "当前站点未向访客开放 Agent 操作能力。你可以正常聊天，但不能承诺打开页面、提交内容或控制站点功能。";
+        }
+        return systemMessage + "\n\n【Agent 能力】\n"
+            + "- 你可以在工具可用时协助访客执行已授权的站点操作。\n"
+            + "- 只能调用当前已声明的工具；不要承诺未声明或未授权的能力。\n"
+            + "- 执行评论、表单填写、页面定位等依赖当前页面结构的操作前，应先读取当前页面上下文；如果页面不具备对应能力，应如实说明。\n"
+            + "- 需要访客确认的操作必须等待确认，不能声称已经完成。\n"
+            + "- 导航、搜索和评论都应以工具结果为准。";
+    }
+
+    private void addBuiltInBrowserTools(List<ToolDefinition> tools, AgentSettings settings) {
+        var builtIn = settings.builtIn();
+        if (builtIn.pageContext()) {
+            tools.add(ToolDefinition.builder()
+                .name("get_current_page_context")
+                .description("读取当前访客页面上下文和可操作能力，例如页面标题、地址、主要标题、选中文本、评论区/评论输入框/提交按钮是否存在、页面表单摘要和站内链接摘要。不会读取表单当前值、Cookie 或本地存储。执行评论、表单填写或页面定位前应先使用该工具判断当前页面是否支持对应操作。")
+                .inputSchema(JsonSchema.object().build())
+                .build());
+        }
+        if (builtIn.haloNavigation()) {
+            tools.add(ToolDefinition.builder()
+                .name("open_halo_resource")
+                .description("打开刚由 Halo 查询工具返回的可信资源。只能打开工具结果中出现过的资源。")
+                .inputSchema(JsonSchema.object()
+                    .property("resourceId", JsonSchema.string().description("可信资源 ID"))
+                    .required("resourceId")
+                    .build())
+                .build());
+        }
+        if (builtIn.commentCapability() != AgentCommentCapability.OFF) {
+            tools.add(ToolDefinition.builder()
+                .name("open_comment_area")
+                .description("打开或滚动到当前页面评论区。该工具不会自动提交评论。")
+                .inputSchema(JsonSchema.object().build())
+                .build());
+        }
+    }
+
+    private ToolDefinition toBrowserToolDefinition(NormalizedAgentTool tool) {
+        return ToolDefinition.builder()
+            .name(tool.name())
+            .description(descriptionWithPolicy(tool))
+            .inputSchema(tool.inputSchema())
+            .build();
+    }
+
+    private String descriptionWithPolicy(NormalizedAgentTool tool) {
+        String description = tool.description();
+        if (tool.approval() == AgentToolApproval.ALWAYS) {
+            description += "。该工具需要访客确认后才会执行。";
+        }
+        if ("dispatch-event".equals(tool.actionType())) {
+            description += "。该工具只会触发站点声明的事件，具体行为由站点实现。";
+        }
+        if ("registered".equals(tool.actionType())) {
+            description += "。该工具由站点注册的前端执行器处理。";
+        }
+        return description;
+    }
+
+    private boolean isAllowed(AgentToolAuth requiredAuth, boolean authenticated) {
+        return requiredAuth != AgentToolAuth.AUTHENTICATED || authenticated;
+    }
+
+    public static Map<String, Object> emptyObjectSchema() {
+        Map<String, Object> schema = new LinkedHashMap<>();
+        schema.put("type", "object");
+        schema.put("properties", Map.of());
+        return schema;
+    }
+}
diff --git a/src/main/java/run/halo/live2d/agent/AgentToolSet.java b/src/main/java/run/halo/live2d/agent/AgentToolSet.java
new file mode 100644
index 0000000..8fa33d7
--- /dev/null
+++ b/src/main/java/run/halo/live2d/agent/AgentToolSet.java
@@ -0,0 +1,13 @@
+package run.halo.live2d.agent;
+
+import java.util.List;
+import run.halo.aifoundation.tool.ToolDefinition;
+
+public record AgentToolSet(
+    boolean agentEnabled,
+    List<ToolDefinition> tools
+) {
+    public static AgentToolSet disabled() {
+        return new AgentToolSet(false, List.of());
+    }
+}
diff --git a/src/main/java/run/halo/live2d/agent/HaloAgentPresetToolService.java b/src/main/java/run/halo/live2d/agent/HaloAgentPresetToolService.java
new file mode 100644
index 0000000..546c274
--- /dev/null
+++ b/src/main/java/run/halo/live2d/agent/HaloAgentPresetToolService.java
@@ -0,0 +1,464 @@
+package run.halo.live2d.agent;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.IDN;
+import java.net.Inet6Address;
+import java.net.InetAddress;
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.time.Duration;
+import java.util.Comparator;
+import java.util.HashSet;
+import java.util.Locale;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import lombok.RequiredArgsConstructor;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.stereotype.Component;
+import reactor.core.publisher.Mono;
+import reactor.core.scheduler.Schedulers;
+import run.halo.app.core.extension.content.Category;
+import run.halo.app.core.extension.content.Post;
+import run.halo.app.core.extension.content.SinglePage;
+import run.halo.app.core.extension.content.Tag;
+import run.halo.app.extension.ReactiveExtensionClient;
+import run.halo.app.search.HaloDocument;
+import run.halo.app.search.SearchOption;
+import run.halo.app.search.SearchService;
+
+@Component
+@RequiredArgsConstructor
+public class HaloAgentPresetToolService {
+    public static final String TYPE_POST = "post.content.halo.run";
+    public static final String TYPE_SINGLE_PAGE = "singlepage.content.halo.run";
+    public static final String TYPE_CATEGORY = "category.content.halo.run";
+    public static final String TYPE_TAG = "tag.content.halo.run";
+
+    private final SearchService searchService;
+    private final ReactiveExtensionClient extensionClient;
+    private final HttpClient httpClient = HttpClient.newBuilder()
+        .followRedirects(HttpClient.Redirect.NEVER)
+        .connectTimeout(Duration.ofSeconds(5))
+        .build();
+
+    public Mono<Object> searchHaloResources(Map<String, Object> input, AgentSettings settings) {
+        var keyword = stringInput(input, "keyword");
+        if (StringUtils.isBlank(keyword)) {
+            return Mono.just(failure("INVALID_INPUT", "keyword is required"));
+        }
+        var search = settings.haloSearch();
+        var allowedTypes = new HashSet<>(search.normalizedAllowedTypes());
+        var requestedTypes = stringList(input.get("includeTypes"));
+        var includeTypes = requestedTypes.isEmpty()
+            ? List.copyOf(allowedTypes)
+            : requestedTypes.stream().filter(allowedTypes::contains).toList();
+
+        var option = new SearchOption();
+        option.setKeyword(keyword);
+        option.setLimit(limit(input, search.normalizedDefaultLimit(), 1, 20));
+        option.setFilterExposed(true);
+        option.setFilterPublished(true);
+        option.setFilterRecycled(false);
+        option.setIncludeTypes(includeTypes);
+        option.setHighlightPreTag("");
+        option.setHighlightPostTag("");
+        return searchService.search(option)
+            .map(result -> Map.of(
+                "ok", true,
+                "keyword", keyword,
+                "total", result.getTotal() == null ? 0 : result.getTotal(),
+                "resources", result.getHits() == null ? List.of()
+                    : result.getHits().stream().map(this::fromDocument).toList()
+            ));
+    }
+
+    public Mono<Object> getHaloResourceDetail(Map<String, Object> input, AgentSettings settings) {
+        var resourceId = stringInput(input, "resourceId");
+        if (StringUtils.isBlank(resourceId)) {
+            return Mono.just(failure("INVALID_INPUT", "resourceId is required"));
+        }
+        var parts = resourceId.split(":", 2);
+        if (parts.length != 2) {
+            return Mono.just(failure("INVALID_RESOURCE", "resourceId is invalid"));
+        }
+        var maxChars = settings.haloResourceDetail().maxContentChars();
+        if (TYPE_POST.equals(parts[0])) {
+            return extensionClient.fetch(Post.class, parts[1])
+                .filter(this::isPublicPost)
+                .map(post -> detailFromPost(post, maxChars))
+                .cast(Object.class)
+                .defaultIfEmpty(failure("RESOURCE_NOT_FOUND", "post is not available"));
+        }
+        if (TYPE_SINGLE_PAGE.equals(parts[0])) {
+            return extensionClient.fetch(SinglePage.class, parts[1])
+                .filter(this::isPublicPage)
+                .map(page -> detailFromPage(page, maxChars))
+                .cast(Object.class)
+                .defaultIfEmpty(failure("RESOURCE_NOT_FOUND", "page is not available"));
+        }
+        return Mono.just(failure("UNSUPPORTED_RESOURCE", "resource type is not supported"));
+    }
+
+    public Mono<Object> getLatestHaloResources(Map<String, Object> input) {
+        var limit = limit(input, 5, 1, 20);
+        return extensionClient.list(Post.class, this::isPublicPost,
+                Comparator.comparing(this::postTime, Comparator.nullsLast(Comparator.naturalOrder()))
+                    .reversed())
+            .take(limit)
+            .map(this::fromPost)
+            .collectList()
+            .map(resources -> Map.of("ok", true, "resources", resources));
+    }
+
+    public Mono<Object> getCategories(Map<String, Object> input) {
+        var limit = limit(input, 20, 1, 100);
+        return extensionClient.list(Category.class, category -> !category.isDeleted(),
+                Comparator.comparing(category -> category.getSpec().getDisplayName(),
+                    Comparator.nullsLast(String::compareToIgnoreCase)))
+            .take(limit)
+            .map(this::fromCategory)
+            .collectList()
+            .map(resources -> Map.of("ok", true, "resources", resources));
+    }
+
+    public Mono<Object> getTags(Map<String, Object> input) {
+        var limit = limit(input, 20, 1, 100);
+        return extensionClient.list(Tag.class, tag -> true,
+                Comparator.comparing(tag -> tag.getSpec().getDisplayName(),
+                    Comparator.nullsLast(String::compareToIgnoreCase)))
+            .take(limit)
+            .map(this::fromTag)
+            .collectList()
+            .map(resources -> Map.of("ok", true, "resources", resources));
+    }
+
+    public Mono<Object> getPostsByCategory(Map<String, Object> input) {
+        var category = stringInput(input, "categoryName");
+        var limit = limit(input, 10, 1, 20);
+        return extensionClient.list(Post.class,
+                post -> isPublicPost(post) && contains(post.getSpec().getCategories(), category),
+                Comparator.comparing(this::postTime, Comparator.nullsLast(Comparator.naturalOrder()))
+                    .reversed())
+            .take(limit)
+            .map(this::fromPost)
+            .collectList()
+            .map(resources -> Map.of("ok", true, "resources", resources));
+    }
+
+    public Mono<Object> getPostsByTag(Map<String, Object> input) {
+        var tag = stringInput(input, "tagName");
+        var limit = limit(input, 10, 1, 20);
+        return extensionClient.list(Post.class,
+                post -> isPublicPost(post) && contains(post.getSpec().getTags(), tag),
+                Comparator.comparing(this::postTime, Comparator.nullsLast(Comparator.naturalOrder()))
+                    .reversed())
+            .take(limit)
+            .map(this::fromPost)
+            .collectList()
+            .map(resources -> Map.of("ok", true, "resources", resources));
+    }
+
+    public Mono<Object> getPages(Map<String, Object> input) {
+        var limit = limit(input, 20, 1, 100);
+        return extensionClient.list(SinglePage.class, this::isPublicPage,
+                Comparator.comparing(page -> page.getSpec().getTitle(),
+                    Comparator.nullsLast(String::compareToIgnoreCase)))
+            .take(limit)
+            .map(this::fromPage)
+            .collectList()
+            .map(resources -> Map.of("ok", true, "resources", resources));
+    }
+
+    public Mono<Object> fetchAllowedUrl(Map<String, Object> input, AgentSettings settings) {
+        return Mono.fromCallable(() -> validateNetworkTarget(stringInput(input, "url"), settings))
+            .subscribeOn(Schedulers.boundedElastic())
+            .flatMap(target -> {
+                var request = HttpRequest.newBuilder(target.uri())
+                    .GET()
+                    .timeout(Duration.ofSeconds(
+                        settings.networkAccess().normalizedTimeoutSeconds()))
+                    .header("Accept", "text/plain, application/json, application/xml, text/*;q=0.9, */*;q=0.1")
+                    .header("User-Agent", "Halo-Live2D-Agent/1.0")
+                    .build();
+                return Mono.fromFuture(httpClient.sendAsync(request,
+                        HttpResponse.BodyHandlers.ofInputStream()))
+                    .map(response -> readNetworkResponse(response,
+                        settings.networkAccess().normalizedMaxResponseChars()))
+                    .cast(Object.class);
+            })
+            .onErrorResume(IllegalArgumentException.class,
+                throwable -> Mono.just(failure("NETWORK_ACCESS_DENIED", throwable.getMessage())))
+            .onErrorResume(IOException.class,
+                throwable -> Mono.just(failure("NETWORK_READ_FAILED", "网络响应读取失败")))
+            .onErrorResume(Exception.class,
+                throwable -> Mono.just(failure("NETWORK_REQUEST_FAILED", "后端网络请求失败")));
+    }
+
+    public Object commentUnavailable(String message) {
+        return failure("COMMENT_FLOW_REQUIRED", message);
+    }
+
+    private Map<String, Object> fromDocument(HaloDocument document) {
+        return resource(
+            document.getType() + ":" + document.getMetadataName(),
+            document.getType(),
+            document.getMetadataName(),
+            document.getTitle(),
+            StringUtils.defaultIfBlank(document.getDescription(), excerpt(document.getContent(), 220)),
+            document.getPermalink()
+        );
+    }
+
+    private Map<String, Object> fromPost(Post post) {
+        return resource(
+            TYPE_POST + ":" + post.getMetadata().getName(),
+            TYPE_POST,
+            post.getMetadata().getName(),
+            post.getSpec().getTitle(),
+            excerpt(StringUtils.defaultIfBlank(post.getStatusOrDefault().getExcerpt(),
+                Optional.ofNullable(post.getSpec().getExcerpt()).map(Post.Excerpt::getRaw).orElse(null)), 220),
+            post.getStatusOrDefault().getPermalink()
+        );
+    }
+
+    private Map<String, Object> fromPage(SinglePage page) {
+        return resource(
+            TYPE_SINGLE_PAGE + ":" + page.getMetadata().getName(),
+            TYPE_SINGLE_PAGE,
+            page.getMetadata().getName(),
+            page.getSpec().getTitle(),
+            excerpt(StringUtils.defaultIfBlank(page.getStatusOrDefault().getExcerpt(),
+                Optional.ofNullable(page.getSpec().getExcerpt()).map(Post.Excerpt::getRaw).orElse(null)), 220),
+            page.getStatusOrDefault().getPermalink()
+        );
+    }
+
+    private Map<String, Object> fromCategory(Category category) {
+        return resource(
+            TYPE_CATEGORY + ":" + category.getMetadata().getName(),
+            TYPE_CATEGORY,
+            category.getMetadata().getName(),
+            category.getSpec().getDisplayName(),
+            category.getSpec().getDescription(),
+            category.getStatusOrDefault().getPermalink()
+        );
+    }
+
+    private Map<String, Object> fromTag(Tag tag) {
+        return resource(
+            TYPE_TAG + ":" + tag.getMetadata().getName(),
+            TYPE_TAG,
+            tag.getMetadata().getName(),
+            tag.getSpec().getDisplayName(),
+            tag.getSpec().getDescription(),
+            tag.getStatusOrDefault().getPermalink()
+        );
+    }
+
+    private Map<String, Object> detailFromPost(Post post, int maxChars) {
+        var content = excerpt(StringUtils.defaultIfBlank(post.getStatusOrDefault().getExcerpt(),
+            Optional.ofNullable(post.getSpec().getExcerpt()).map(Post.Excerpt::getRaw).orElse("")), maxChars);
+        return Map.of("ok", true, "resource", fromPost(post), "content", content,
+            "truncated", content.length() >= maxChars);
+    }
+
+    private Map<String, Object> detailFromPage(SinglePage page, int maxChars) {
+        var content = excerpt(StringUtils.defaultIfBlank(page.getStatusOrDefault().getExcerpt(),
+            Optional.ofNullable(page.getSpec().getExcerpt()).map(Post.Excerpt::getRaw).orElse("")), maxChars);
+        return Map.of("ok", true, "resource", fromPage(page), "content", content,
+            "truncated", content.length() >= maxChars);
+    }
+
+    private Map<String, Object> resource(String id, String type, String metadataName, String title,
+        String excerpt, String permalink) {
+        return Map.of(
+            "resourceId", id,
+            "resourceType", type,
+            "metadataName", metadataName,
+            "title", StringUtils.defaultString(title),
+            "excerpt", StringUtils.defaultString(excerpt),
+            "permalink", StringUtils.defaultString(permalink)
+        );
+    }
+
+    private Map<String, Object> failure(String code, String message) {
+        return Map.of("ok", false, "errorCode", code, "message", message);
+    }
+
+    private NetworkTarget validateNetworkTarget(String rawUrl, AgentSettings settings) {
+        if (StringUtils.isBlank(rawUrl)) {
+            throw new IllegalArgumentException("url is required");
+        }
+        URI uri;
+        try {
+            uri = new URI(rawUrl.trim()).normalize();
+        } catch (URISyntaxException e) {
+            throw new IllegalArgumentException("url is invalid");
+        }
+        if (!"https".equalsIgnoreCase(uri.getScheme())
+            && !"http".equalsIgnoreCase(uri.getScheme())) {
+            throw new IllegalArgumentException("只允许访问 http 或 https URL");
+        }
+        if (StringUtils.isNotBlank(uri.getUserInfo())) {
+            throw new IllegalArgumentException("URL 不能包含用户信息");
+        }
+        var host = StringUtils.trimToNull(uri.getHost());
+        if (host == null) {
+            throw new IllegalArgumentException("URL host is required");
+        }
+        var normalizedOrigin = originOf(uri);
+        var allowedOrigins = settings.networkAccess().normalizedAllowedOrigins().stream()
+            .map(this::normalizeOrigin)
+            .flatMap(Optional::stream)
+            .toList();
+        if (allowedOrigins.isEmpty() || !allowedOrigins.contains(normalizedOrigin)) {
+            throw new IllegalArgumentException("URL Origin 未被站长允许");
+        }
+        if (isDangerousHost(host)) {
+            throw new IllegalArgumentException("禁止访问 localhost、内网或链路本地地址");
+        }
+        try {
+            for (var address : InetAddress.getAllByName(host)) {
+                if (isDangerousAddress(address)) {
+                    throw new IllegalArgumentException("禁止访问 localhost、内网或链路本地地址");
+                }
+            }
+        } catch (IOException e) {
+            throw new IllegalArgumentException("无法解析目标地址");
+        }
+        return new NetworkTarget(uri, normalizedOrigin);
+    }
+
+    private Map<String, Object> readNetworkResponse(HttpResponse<InputStream> response,
+        int maxChars) {
+        try (var body = response.body()) {
+            var bytes = body.readNBytes(maxChars + 1);
+            var truncated = bytes.length > maxChars;
+            var length = Math.min(bytes.length, maxChars);
+            var text = new String(bytes, 0, length, StandardCharsets.UTF_8);
+            return Map.of(
+                "ok", true,
+                "url", response.uri().toString(),
+                "status", response.statusCode(),
+                "contentType", response.headers().firstValue("content-type").orElse(""),
+                "body", text,
+                "truncated", truncated
+            );
+        } catch (IOException e) {
+            throw new RuntimeException(e);
+        }
+    }
+
+    private Optional<String> normalizeOrigin(String rawOrigin) {
+        if (StringUtils.isBlank(rawOrigin)) {
+            return Optional.empty();
+        }
+        try {
+            return Optional.of(originOf(new URI(rawOrigin.trim())));
+        } catch (URISyntaxException | IllegalArgumentException e) {
+            return Optional.empty();
+        }
+    }
+
+    private String originOf(URI uri) {
+        var scheme = StringUtils.lowerCase(uri.getScheme(), Locale.ROOT);
+        var host = IDN.toASCII(uri.getHost()).toLowerCase(Locale.ROOT);
+        var port = uri.getPort();
+        var defaultPort = "https".equals(scheme) ? 443 : 80;
+        return port < 0 || port == defaultPort
+            ? scheme + "://" + host
+            : scheme + "://" + host + ":" + port;
+    }
+
+    private boolean isDangerousHost(String host) {
+        var normalized = host.toLowerCase(Locale.ROOT);
+        return "localhost".equals(normalized)
+            || normalized.endsWith(".localhost")
+            || normalized.endsWith(".local");
+    }
+
+    private boolean isDangerousAddress(InetAddress address) {
+        return address.isAnyLocalAddress()
+            || address.isLoopbackAddress()
+            || address.isLinkLocalAddress()
+            || address.isSiteLocalAddress()
+            || address.isMulticastAddress()
+            || isUniqueLocalIpv6(address);
+    }
+
+    private boolean isUniqueLocalIpv6(InetAddress address) {
+        if (!(address instanceof Inet6Address)) {
+            return false;
+        }
+        var firstByte = address.getAddress()[0] & 0xff;
+        return (firstByte & 0xfe) == 0xfc;
+    }
+
+    private boolean isPublicPost(Post post) {
+        return post != null
+            && post.getSpec() != null
+            && post.isPublished()
+            && !post.isDeleted()
+            && Post.isPublic(post.getSpec());
+    }
+
+    private boolean isPublicPage(SinglePage page) {
+        return page != null
+            && page.getSpec() != null
+            && page.isPublished()
+            && !Boolean.TRUE.equals(page.getSpec().getDeleted())
+            && (page.getSpec().getVisible() == null
+            || Post.VisibleEnum.PUBLIC.equals(page.getSpec().getVisible()));
+    }
+
+    private Instant postTime(Post post) {
+        return Optional.ofNullable(post.getSpec().getPublishTime())
+            .orElse(post.getMetadata().getCreationTimestamp());
+    }
+
+    private boolean contains(List<String> values, String value) {
+        return StringUtils.isBlank(value)
+            || values != null && values.stream().anyMatch(item -> Objects.equals(item, value));
+    }
+
+    private int limit(Map<String, Object> input, int defaultValue, int min, int max) {
+        var value = input == null ? null : input.get("limit");
+        int parsed = value instanceof Number number ? number.intValue() : defaultValue;
+        return Math.max(min, Math.min(max, parsed));
+    }
+
+    private String stringInput(Map<String, Object> input, String key) {
+        var value = input == null ? null : input.get(key);
+        return value == null ? null : StringUtils.trimToNull(String.valueOf(value));
+    }
+
+    private List<String> stringList(Object value) {
+        if (!(value instanceof List<?> list)) {
+            return List.of();
+        }
+        return list.stream()
+            .filter(String.class::isInstance)
+            .map(String.class::cast)
+            .filter(StringUtils::isNotBlank)
+            .toList();
+    }
+
+    private String excerpt(String content, int maxChars) {
+        var text = StringUtils.defaultString(content).replaceAll("\\s+", " ").trim();
+        if (text.length() <= maxChars) {
+            return text;
+        }
+        return text.substring(0, maxChars);
+    }
+
+    private record NetworkTarget(URI uri, String origin) {
+    }
+}
diff --git a/src/main/java/run/halo/live2d/agent/NormalizedAgentTool.java b/src/main/java/run/halo/live2d/agent/NormalizedAgentTool.java
new file mode 100644
index 0000000..7178dff
--- /dev/null
+++ b/src/main/java/run/halo/live2d/agent/NormalizedAgentTool.java
@@ -0,0 +1,16 @@
+package run.halo.live2d.agent;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import java.util.Map;
+
+public record NormalizedAgentTool(
+    String name,
+    String description,
+    Map<String, Object> inputSchema,
+    AgentToolApproval approval,
+    AgentToolAuth requiredAuth,
+    String actionType,
+    JsonNode action,
+    JsonNode testInput
+) {
+}
diff --git a/src/main/java/run/halo/live2d/chat/AIChatServiceImpl.java b/src/main/java/run/halo/live2d/chat/AIChatServiceImpl.java
index 30d13f8..ca7f1db 100644
--- a/src/main/java/run/halo/live2d/chat/AIChatServiceImpl.java
+++ b/src/main/java/run/halo/live2d/chat/AIChatServiceImpl.java
@@ -1,54 +1,107 @@
 package run.halo.live2d.chat;
 
-import com.theokanning.openai.completion.chat.ChatMessage;
-import java.util.List;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
-import org.springframework.context.ApplicationContext;
-import org.springframework.http.codec.ServerSentEvent;
+import org.apache.commons.lang3.StringUtils;
 import org.springframework.stereotype.Component;
-import org.springframework.web.reactive.function.client.WebClientRequestException;
-import org.springframework.web.reactive.function.client.WebClientResponseException;
-import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
-import run.halo.live2d.chat.client.ChatClient;
-import run.halo.live2d.chat.client.DefaultChatClient;
+import run.halo.aifoundation.AiModelService;
+import run.halo.aifoundation.chat.StopCondition;
+import run.halo.aifoundation.exception.ModelDisabledException;
+import run.halo.aifoundation.exception.ModelNotFoundException;
+import run.halo.aifoundation.exception.ProviderApiException;
+import run.halo.aifoundation.exception.ProviderDisabledException;
+import run.halo.aifoundation.ui.InvalidUIMessageException;
+import run.halo.aifoundation.ui.UIMessageChatHandlers;
+import run.halo.aifoundation.ui.UIMessageChatRequest;
+import run.halo.aifoundation.ui.UIMessageChunks;
+import run.halo.aifoundation.ui.UIMessageStreamResponse;
+import run.halo.aifoundation.ui.UIMessageStreams;
+import run.halo.aifoundation.tool.ToolChoice;
+import run.halo.app.plugin.extensionpoint.ExtensionGetter;
+import run.halo.live2d.agent.AgentToolSet;
 
 @Slf4j
 @Component
 @RequiredArgsConstructor
 public class AIChatServiceImpl implements AiChatService {
-    private final ApplicationContext applicationContext;
-
-    public Flux<ServerSentEvent<ChatResult>> streamChatCompletion(List<ChatMessage> messages) {
-        log.debug("Stream chat completion with messages: {}", messages);
-        return Flux.fromIterable(this.applicationContext.getBeansOfType(ChatClient.class).values())
-            .filterWhen(ChatClient::supports)
-            .switchIfEmpty(Mono.just(new DefaultChatClient()))
-            .concatMap(aiClient -> aiClient.generate(messages)
-                .onErrorResume(throwable -> {
-                    log.error("Error occurred while generating ai result", throwable);
-                    if (throwable instanceof WebClientResponseException) {
-                        return Mono.just(
-                            ServerSentEvent.builder(
-                                ChatResult.builder()
-                                    .status(((WebClientResponseException) throwable).getStatusCode()
-                                        .value())
-                                    .text(((WebClientResponseException) throwable).getStatusText())
-                                    .build()
-                            ).build()
-                        );
-                    }
-                    if (throwable instanceof WebClientRequestException) {
-                        return Mono.just(
-                            ServerSentEvent.builder(
-                                ChatResult.error(throwable.getMessage())
-                            ).build()
-                        );
-                    }
-                    return Mono.error(throwable);
-                })
-                .switchIfEmpty(Flux.empty())
-            );
+
+    private final ExtensionGetter extensionGetter;
+
+    private Mono<AiModelService> aiModelService() {
+        return extensionGetter.getEnabledExtension(AiModelService.class);
+    }
+
+    @Override
+    public Mono<UIMessageStreamResponse> streamChatCompletion(String modelName,
+        String systemMessage, UIMessageChatRequest<Void> chatRequest, AgentToolSet agentToolSet) {
+        if (StringUtils.isBlank(modelName)) {
+            return Mono.just(errorResponse("请先在插件设置中配置 Halo AI 模型"));
+        }
+
+        return aiModelService()
+            .flatMap(service -> service.languageModel(modelName))
+            .map(model -> {
+                var chat = UIMessageChatHandlers.<Void>streamText(options -> options
+                    .model(model)
+                    .chatRequest(chatRequest)
+                    .request(builder -> builder
+                        .system(systemMessage)
+                        .tools(agentToolSet == null ? null : agentToolSet.tools())
+                        .toolChoice(agentToolSet == null || agentToolSet.tools().isEmpty()
+                            ? ToolChoice.none()
+                            : ToolChoice.auto())
+                        .stopWhen(agentToolSet == null || agentToolSet.tools().isEmpty()
+                            ? null
+                            : StopCondition.stepCountIs(3)))
+                    .onError(this::resolveErrorMessage));
+                return chat.response();
+            })
+            .onErrorResume(throwable -> {
+                logChatError(modelName, throwable);
+                return Mono.just(errorResponse(resolveErrorMessage(throwable)));
+            });
+    }
+
+    @Override
+    public UIMessageStreamResponse errorResponse(String message) {
+        var stream = UIMessageStreams.create(writer -> writer.write(UIMessageChunks.error(
+            resolveErrorMessageText(message))));
+        return new UIMessageStreamResponse(stream);
+    }
+
+    private String resolveErrorMessageText(String message) {
+        return StringUtils.defaultIfBlank(message, "对话接口异常了哦～快去联系我的主人吧！");
+    }
+
+    private String resolveErrorMessage(Throwable throwable) {
+        if (throwable instanceof InvalidUIMessageException) {
+            return "对话上下文异常了，请刷新后重试";
+        }
+        if (throwable instanceof ModelNotFoundException
+            || throwable instanceof ModelDisabledException) {
+            return "当前配置的 Halo AI 模型不可用，请联系站长检查配置";
+        }
+        if (throwable instanceof ProviderDisabledException) {
+            return "Halo AI 提供商未启用，请联系站长检查配置";
+        }
+        if (throwable instanceof ProviderApiException) {
+            return "Halo AI 提供商调用失败，请稍后再试";
+        }
+        if (throwable instanceof IllegalStateException) {
+            return "AI 基础设施未启用，请联系站长";
+        }
+        return StringUtils.defaultIfBlank(throwable.getMessage(),
+            "对话接口异常了哦～快去联系我的主人吧！");
+    }
+
+    private void logChatError(String modelName, Throwable throwable) {
+        if (throwable instanceof InvalidUIMessageException invalid) {
+            log.error("Invalid Halo UI messages for model: {}, issues: {}", modelName,
+                invalid.issues(), throwable);
+            return;
+        }
+        log.error("Error occurred while generating Halo AI chat result, model: {}",
+            modelName, throwable);
     }
 }
diff --git a/src/main/java/run/halo/live2d/chat/AiChatEndpoint.java b/src/main/java/run/halo/live2d/chat/AiChatEndpoint.java
index 93585d3..5d3c8c8 100644
--- a/src/main/java/run/halo/live2d/chat/AiChatEndpoint.java
+++ b/src/main/java/run/halo/live2d/chat/AiChatEndpoint.java
@@ -4,10 +4,9 @@
 import static org.springdoc.core.fn.builders.content.Builder.contentBuilder;
 import static org.springdoc.core.fn.builders.requestbody.Builder.requestBodyBuilder;
 
-import com.theokanning.openai.completion.chat.ChatMessage;
-import com.theokanning.openai.completion.chat.ChatMessageRole;
-import java.util.ArrayList;
-import java.util.List;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.util.Map;
 import lombok.AllArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.apache.commons.lang3.StringUtils;
@@ -24,11 +23,18 @@
 import org.springframework.web.reactive.function.server.ServerRequest;
 import org.springframework.web.reactive.function.server.ServerResponse;
 import org.springframework.web.server.ResponseStatusException;
-import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 import run.halo.app.core.extension.endpoint.CustomEndpoint;
 import run.halo.app.extension.GroupVersion;
 import run.halo.app.plugin.ReactiveSettingFetcher;
+import run.halo.aifoundation.ui.InvalidUIMessageException;
+import run.halo.aifoundation.ui.UIMessageChatRequest;
+import run.halo.aifoundation.ui.UIMessageChunk;
+import run.halo.aifoundation.ui.UIMessageStreamResponse;
+import run.halo.aifoundation.ui.UIMessageTransportCodec;
+import run.halo.live2d.agent.AgentAccessMode;
+import run.halo.live2d.agent.AgentSettings;
+import run.halo.live2d.agent.AgentToolService;
 
 @Slf4j
 @Component
@@ -39,6 +45,10 @@ public class AiChatEndpoint implements CustomEndpoint {
 
     private final AiChatService aiChatService;
 
+    private final AgentToolService agentToolService;
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
     @Override
     public RouterFunction<ServerResponse> endpoint() {
         var tag = groupVersion().toString();
@@ -51,52 +61,79 @@ public RouterFunction<ServerResponse> endpoint() {
                     .requestBody(requestBodyBuilder()
                         .required(true)
                         .content(contentBuilder()
-                            .mediaType(MediaType.TEXT_EVENT_STREAM_VALUE)
+                            .mediaType(MediaType.APPLICATION_JSON_VALUE)
                             .schema(Builder.schemaBuilder()
-                                .implementation(ChatRequest.class)
+                                .implementation(Map.class)
                             )
                         ))
                     .response(responseBuilder()
-                        .implementation(ServerSentEvent.class))
+                        .implementation(String.class))
             )
             .build();
     }
 
     private Mono<ServerResponse> chatProcess(ServerRequest request) {
-        return request.bodyToMono(ChatRequest.class)
-            .map(this::chatCompletion)
-            .onErrorResume(throwable -> {
-                if (throwable instanceof IllegalArgumentException) {
-                    return Mono.just(
-                        Flux.just(
-                            ServerSentEvent.builder(
-                                ChatResult.ok(throwable.getMessage())).build()
-                        )
-                    );
-                }
-                return Mono.error(throwable);
-            })
-            .flatMap(sse -> ServerResponse.ok()
+        return request.bodyToMono(Map.class)
+            .map(this::toChatRequest)
+            .flatMap(this::chatCompletion)
+            .onErrorMap(InvalidUIMessageException.class,
+                throwable -> new ResponseStatusException(HttpStatus.BAD_REQUEST,
+                    throwable.getMessage(), throwable))
+            .onErrorResume(IllegalArgumentException.class,
+                throwable -> Mono.just(aiChatService.errorResponse(throwable.getMessage())))
+            .flatMap(response -> ServerResponse.ok()
                 .contentType(MediaType.TEXT_EVENT_STREAM)
-                .body(sse, ServerSentEvent.class)
+                .headers(headers -> headers.setAll(response.headers()))
+                .body(response.stream()
+                    .map(chunk -> ServerSentEvent.builder(serializeChunk(chunk)).build())
+                    .concatWithValues(ServerSentEvent.builder(
+                        UIMessageStreamResponse.DONE_MARKER).build()), ServerSentEvent.class)
             );
     }
 
 
-    private Flux<ServerSentEvent<ChatResult>> chatCompletion(ChatRequest body) {
+    private Mono<UIMessageStreamResponse> chatCompletion(UIMessageChatRequest<Void> chatRequest) {
         return reactiveSettingFetcher.fetch("aichat", AiChatConfig.class)
-            .map(aiChatConfig -> ReactiveSecurityContextHolder.getContext()
-                .map(SecurityContext::getAuthentication)
-                .flatMapMany(authentication -> {
-                    if (!aiChatConfig.aiChatBaseSetting.isAnonymous && !isAuthenticated(
-                        authentication)) {
-                        throw new ResponseStatusException(HttpStatus.UNAUTHORIZED, "请先登录");
-                    }
-                    String systemMessage = aiChatConfig.aiChatBaseSetting.systemMessage;
-                    List<ChatMessage> messages = this.buildChatMessage(systemMessage, body);
-                    return aiChatService.streamChatCompletion(messages);
-                }))
-            .flatMapMany(Flux::from);
+            .flatMap(aiChatConfig -> {
+                if (!aiChatConfig.isAiChat()) {
+                    return Mono.just(aiChatService.errorResponse("AI 聊天功能未启用"));
+                }
+
+                var baseSetting = aiChatConfig.aiChatBaseSetting();
+                var accessMode = baseSetting.resolvedAccessMode();
+
+                if (!accessMode.authenticationRequired()) {
+                    return loadAgentSettings()
+                        .map(settings -> agentToolService.buildTools(settings, accessMode, false))
+                        .flatMap(toolSet -> aiChatService.streamChatCompletion(
+                            baseSetting.modelName(),
+                            agentToolService.appendCapabilityPrompt(
+                                baseSetting.systemMessage(), toolSet),
+                            chatRequest,
+                            toolSet));
+                }
+
+                return ReactiveSecurityContextHolder.getContext()
+                    .map(SecurityContext::getAuthentication)
+                    .filter(this::isAuthenticated)
+                    .switchIfEmpty(Mono.error(
+                        new ResponseStatusException(HttpStatus.UNAUTHORIZED, "请先登录")))
+                    .flatMap(authentication -> loadAgentSettings()
+                        .map(settings -> agentToolService.buildTools(settings, accessMode, true))
+                        .flatMap(toolSet -> aiChatService.streamChatCompletion(
+                            baseSetting.modelName(),
+                            agentToolService.appendCapabilityPrompt(
+                                baseSetting.systemMessage(), toolSet),
+                            chatRequest,
+                            toolSet)));
+            });
+    }
+
+    private Mono<AgentSettings> loadAgentSettings() {
+        return reactiveSettingFetcher.get("agent")
+            .map(node -> objectMapper.convertValue(node, AgentSettings.class))
+            .defaultIfEmpty(AgentSettings.defaults())
+            .onErrorReturn(AgentSettings.defaults());
     }
 
     private boolean isAuthenticated(Authentication authentication) {
@@ -108,23 +145,41 @@ private boolean isAnonymousUser(String name) {
         return "anonymousUser".equals(name);
     }
 
-    private List<ChatMessage> buildChatMessage(String systemMessage, ChatRequest body) {
-        ChatMessage chatMessage =
-            new ChatMessage(ChatMessageRole.SYSTEM.value(), systemMessage);
-        final List<ChatMessage> messages = new ArrayList<>();
-        messages.add(chatMessage);
-        messages.addAll(body.getMessage());
-        return messages;
+    @SuppressWarnings("unchecked")
+    private UIMessageChatRequest<Void> toChatRequest(Map<?, ?> body) {
+        return UIMessageTransportCodec.chatRequestFromMap((Map<String, Object>) body,
+            ignored -> null);
     }
 
-    record AiChatConfig(String isAiChat, AiChatBaseSetting aiChatBaseSetting) {
+    private String serializeChunk(UIMessageChunk chunk) {
+        try {
+            return objectMapper.writeValueAsString(UIMessageTransportCodec.chunkToMap(chunk));
+        } catch (JsonProcessingException e) {
+            throw new IllegalStateException("Failed to serialize UI message chunk", e);
+        }
+    }
+
+    record AiChatConfig(boolean isAiChat, AiChatBaseSetting aiChatBaseSetting) {
+        AiChatConfig {
+            if (isAiChat && aiChatBaseSetting == null) {
+                throw new IllegalArgumentException("ai chat base setting must not be null");
+            }
+        }
     }
 
-    record AiChatBaseSetting(boolean isAnonymous, String systemMessage) {
+    record AiChatBaseSetting(boolean isAnonymous, String accessMode, String systemMessage,
+                             String modelName) {
         AiChatBaseSetting {
             if (StringUtils.isBlank(systemMessage)) {
                 throw new IllegalArgumentException("system message must not be null");
             }
+            if (StringUtils.isBlank(modelName)) {
+                throw new IllegalArgumentException("model name must not be null");
+            }
+        }
+
+        AgentAccessMode resolvedAccessMode() {
+            return AgentAccessMode.from(accessMode, isAnonymous);
         }
     }
 
diff --git a/src/main/java/run/halo/live2d/chat/AiChatService.java b/src/main/java/run/halo/live2d/chat/AiChatService.java
index c862990..cb4e01a 100644
--- a/src/main/java/run/halo/live2d/chat/AiChatService.java
+++ b/src/main/java/run/halo/live2d/chat/AiChatService.java
@@ -1,12 +1,14 @@
 package run.halo.live2d.chat;
 
-import com.theokanning.openai.completion.chat.ChatMessage;
-import java.util.List;
-import org.springframework.http.codec.ServerSentEvent;
-import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+import run.halo.aifoundation.ui.UIMessageChatRequest;
+import run.halo.aifoundation.ui.UIMessageStreamResponse;
+import run.halo.live2d.agent.AgentToolSet;
 
-@FunctionalInterface
 public interface AiChatService {
 
-    Flux<ServerSentEvent<ChatResult>> streamChatCompletion(List<ChatMessage> messages);
+    Mono<UIMessageStreamResponse> streamChatCompletion(String modelName, String systemMessage,
+        UIMessageChatRequest<Void> chatRequest, AgentToolSet agentToolSet);
+
+    UIMessageStreamResponse errorResponse(String message);
 }
diff --git a/src/main/java/run/halo/live2d/chat/ChatRequest.java b/src/main/java/run/halo/live2d/chat/ChatRequest.java
deleted file mode 100644
index 64eb5b4..0000000
--- a/src/main/java/run/halo/live2d/chat/ChatRequest.java
+++ /dev/null
@@ -1,13 +0,0 @@
-package run.halo.live2d.chat;
-
-import com.theokanning.openai.completion.chat.ChatMessage;
-import java.util.List;
-import lombok.Data;
-
-/**
- * @author LIlGG
- */
-@Data
-public class ChatRequest {
-    private List<ChatMessage> message;
-}
diff --git a/src/main/java/run/halo/live2d/chat/ChatResult.java b/src/main/java/run/halo/live2d/chat/ChatResult.java
deleted file mode 100644
index 5173e3c..0000000
--- a/src/main/java/run/halo/live2d/chat/ChatResult.java
+++ /dev/null
@@ -1,32 +0,0 @@
-package run.halo.live2d.chat;
-
-import lombok.Builder;
-import lombok.Value;
-import org.springframework.http.HttpStatus;
-
-@Value
-@Builder
-public class ChatResult {
-    final static String FINISH_TEXT = "[DONE]";
-
-    String text;
-
-    int status;
-
-    public static ChatResult ok(String content) {
-        return ChatResult.builder().text(content).status(HttpStatus.OK.value()).build();
-    }
-
-    public static ChatResult error(String content) {
-        return ChatResult.builder().text(content).status(HttpStatus.INTERNAL_SERVER_ERROR.value()).build();
-    }
-
-    public static ChatResult finish() {
-        return ChatResult.builder().text(FINISH_TEXT).status(HttpStatus.OK.value()).build();
-    }
-
-    @Override
-    public String toString() {
-        return "AiResult{" + "text='" + text + '\'' + ", status=" + status + '}';
-    }
-}
diff --git a/src/main/java/run/halo/live2d/chat/WebClientFactory.java b/src/main/java/run/halo/live2d/chat/WebClientFactory.java
deleted file mode 100644
index e164789..0000000
--- a/src/main/java/run/halo/live2d/chat/WebClientFactory.java
+++ /dev/null
@@ -1,48 +0,0 @@
-package run.halo.live2d.chat;
-
-import org.apache.commons.lang3.StringUtils;
-import org.springframework.http.client.reactive.ReactorClientHttpConnector;
-import org.springframework.stereotype.Component;
-import org.springframework.web.reactive.function.client.WebClient;
-import reactor.core.publisher.Mono;
-import reactor.netty.http.client.HttpClient;
-import reactor.netty.transport.ProxyProvider;
-import run.halo.app.plugin.ReactiveSettingFetcher;
-
-@Component
-public class WebClientFactory {
-    private final ReactiveSettingFetcher settingFetcher;
-
-    public WebClientFactory(ReactiveSettingFetcher settingFetcher) {
-        this.settingFetcher = settingFetcher;
-    }
-
-    public Mono<WebClient.Builder> createWebClientBuilder() {
-        return settingFetcher.fetch("aichat", ProxyConfig.class)
-            .map(proxyConfig -> {
-                if (proxyConfig.isProxy()) {
-                    return HttpClient.create()
-                        .proxy(proxy ->
-                            proxy.type(ProxyProvider.Proxy.HTTP)
-                                .host(proxyConfig.proxyHost)
-                                .port(proxyConfig.proxyPort));
-                } else {
-                    return HttpClient.create();
-                }
-            })
-            .map(httpClient -> WebClient.builder()
-                .clientConnector(new ReactorClientHttpConnector(httpClient))
-            );
-    }
-
-    record ProxyConfig(boolean isProxy, String proxyHost, String baseUrl, int proxyPort) {
-        ProxyConfig {
-            if (isProxy && StringUtils.isBlank(proxyHost)) {
-                throw new IllegalArgumentException("Proxy host must not be blank.");
-            }
-            if (isProxy && proxyPort <= 0) {
-                throw new IllegalArgumentException("Proxy port must be greater than 0.");
-            }
-        }
-    }
-}
diff --git a/src/main/java/run/halo/live2d/chat/client/ChatClient.java b/src/main/java/run/halo/live2d/chat/client/ChatClient.java
deleted file mode 100644
index ea09f70..0000000
--- a/src/main/java/run/halo/live2d/chat/client/ChatClient.java
+++ /dev/null
@@ -1,14 +0,0 @@
-package run.halo.live2d.chat.client;
-
-import com.theokanning.openai.completion.chat.ChatMessage;
-import java.util.List;
-import org.springframework.http.codec.ServerSentEvent;
-import reactor.core.publisher.Flux;
-import reactor.core.publisher.Mono;
-import run.halo.live2d.chat.ChatResult;
-
-public interface ChatClient {
-    Flux<ServerSentEvent<ChatResult>> generate(List<ChatMessage> messages);
-
-    Mono<Boolean> supports();
-}
diff --git a/src/main/java/run/halo/live2d/chat/client/DefaultChatClient.java b/src/main/java/run/halo/live2d/chat/client/DefaultChatClient.java
deleted file mode 100644
index 80f9a37..0000000
--- a/src/main/java/run/halo/live2d/chat/client/DefaultChatClient.java
+++ /dev/null
@@ -1,32 +0,0 @@
-package run.halo.live2d.chat.client;
-
-import com.theokanning.openai.completion.chat.ChatMessage;
-import java.util.List;
-import org.springframework.http.HttpStatus;
-import org.springframework.http.codec.ServerSentEvent;
-import reactor.core.publisher.Flux;
-import reactor.core.publisher.Mono;
-import run.halo.live2d.chat.ChatResult;
-
-public class DefaultChatClient implements ChatClient {
-    public DefaultChatClient() {
-        System.out.println("DefaultChatClient");
-    }
-    @Override
-    public Flux<ServerSentEvent<ChatResult>> generate(List<ChatMessage> messages) {
-        return Flux.just(
-            ServerSentEvent.builder(
-                    ChatResult.builder()
-                        .status(HttpStatus.NOT_FOUND.value())
-                        .text("没有激活的 AI Client，请联系站长")
-                        .build()
-                )
-                .build()
-        );
-    }
-
-    @Override
-    public Mono<Boolean> supports() {
-        return Mono.just(true);
-    }
-}
diff --git a/src/main/java/run/halo/live2d/chat/client/openai/OpenAiChatClient.java b/src/main/java/run/halo/live2d/chat/client/openai/OpenAiChatClient.java
deleted file mode 100644
index 8a1759b..0000000
--- a/src/main/java/run/halo/live2d/chat/client/openai/OpenAiChatClient.java
+++ /dev/null
@@ -1,130 +0,0 @@
-package run.halo.live2d.chat.client.openai;
-
-import com.theokanning.openai.completion.chat.ChatCompletionRequest;
-import com.theokanning.openai.completion.chat.ChatCompletionResult;
-import com.theokanning.openai.completion.chat.ChatMessage;
-import java.util.List;
-import java.util.Objects;
-import lombok.extern.slf4j.Slf4j;
-import org.apache.commons.lang3.StringUtils;
-import org.springframework.http.HttpHeaders;
-import org.springframework.http.MediaType;
-import org.springframework.http.codec.ServerSentEvent;
-import org.springframework.stereotype.Component;
-import reactor.core.publisher.Flux;
-import reactor.core.publisher.Mono;
-import run.halo.app.infra.utils.JsonUtils;
-import run.halo.app.plugin.ReactiveSettingFetcher;
-import run.halo.live2d.chat.ChatResult;
-import run.halo.live2d.chat.WebClientFactory;
-import run.halo.live2d.chat.client.ChatClient;
-
-@Slf4j
-@Component
-public class OpenAiChatClient implements ChatClient {
-    public final static String DEFAULT_OPEN_AI_API_URL = "https://api.openai.com";
-
-    public final static String CHAT_COMPLETION_PATH = "/v1/chat/completions";
-
-    public final static String DEFAULT_MODEL = "gpt-3.5-turbo";
-
-    private final ReactiveSettingFetcher reactiveSettingFetcher;
-
-    private final WebClientFactory webClientFactory;
-
-    public OpenAiChatClient(WebClientFactory webClientFactory,
-        ReactiveSettingFetcher reactiveSettingFetcher) {
-        this.webClientFactory = webClientFactory;
-        this.reactiveSettingFetcher = reactiveSettingFetcher;
-    }
-
-    @Override
-    public Flux<ServerSentEvent<ChatResult>> generate(List<ChatMessage> messages) {
-        return reactiveSettingFetcher.fetch("aichat", OpenAiConfig.class)
-            .filter(openAiConfig -> openAiConfig.openAiSetting.isOpenAi)
-            .flatMapMany(openAiConfig -> {
-                var webClient = webClientFactory
-                    .createWebClientBuilder()
-                    .map(build -> build.baseUrl(openAiConfig.openAiSetting.openAiBaseUrl)
-                        .defaultHeader(HttpHeaders.AUTHORIZATION,
-                            "Bearer " + openAiConfig.openAiSetting.openAiToken)
-                        .build()
-                    );
-
-
-                var request = ChatCompletionRequest.builder()
-                    .model(openAiConfig.openAiSetting.openAiModel)
-                    .messages(messages)
-                    .stream(true)
-                    .build();
-
-                return webClient.flatMapMany(client -> client.post()
-                        .uri(CHAT_COMPLETION_PATH)
-                        .accept(MediaType.TEXT_EVENT_STREAM)
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .bodyValue(JsonUtils.objectToJson(request))
-                        .retrieve()
-                        .bodyToFlux(String.class))
-                    .flatMap(data -> {
-                        if (StringUtils.equals("[DONE]", data)) {
-                            return Mono.just(ServerSentEvent.builder(ChatResult.finish()).build());
-                        }
-
-                        var chatCompletionResult =
-                            JsonUtils.jsonToObject(data, ChatCompletionResult.class);
-                        if (Objects.nonNull(chatCompletionResult.getChoices())) {
-                            var choice = chatCompletionResult.getChoices().get(0);
-                            if (StringUtils.isNotBlank(choice.getFinishReason())) {
-                                return Flux.empty();
-                            }
-
-                            if (Objects.isNull(choice.getMessage())
-                                || StringUtils.isEmpty(choice.getMessage().getContent())
-                            ) {
-                                return Flux.empty();
-                            } else {
-                                return Mono.just(
-                                    ServerSentEvent.builder(
-                                            ChatResult.ok(choice.getMessage().getContent()))
-                                        .build()
-                                );
-                            }
-                        }
-                        return Mono.just(ServerSentEvent.builder(ChatResult.finish()).build());
-                    })
-                    .onTerminateDetach()
-                    .doOnCancel(() -> {
-                        // 在中止事件时执行逻辑
-                        log.info("Client manually canceled the SSE stream.");
-                    });
-            });
-    }
-
-    @Override
-    public Mono<Boolean> supports() {
-        return reactiveSettingFetcher.fetch("aichat", OpenAiConfig.class)
-            .filter((openAiConfig) -> openAiConfig.openAiSetting.isOpenAi)
-            .hasElement();
-    }
-
-    record OpenAiConfig(OpenAiSetting openAiSetting){
-    }
-
-    record OpenAiSetting(boolean isOpenAi, String openAiToken, String openAiBaseUrl, String openAiModel) {
-        OpenAiSetting {
-            if (isOpenAi) {
-                if (StringUtils.isBlank(openAiToken)) {
-                    throw new IllegalArgumentException("OpenAI token must not be blank");
-                }
-
-                if (StringUtils.isBlank(openAiBaseUrl)) {
-                    openAiBaseUrl = DEFAULT_OPEN_AI_API_URL;
-                }
-
-                if (StringUtils.isBlank(openAiModel)) {
-                    openAiModel = DEFAULT_MODEL;
-                }
-            }
-        }
-    }
-}
diff --git a/src/main/resources/extensions/settings.yaml b/src/main/resources/extensions/settings.yaml
index b8ec65d..1a19018 100644
--- a/src/main/resources/extensions/settings.yaml
+++ b/src/main/resources/extensions/settings.yaml
@@ -165,7 +165,15 @@ spec:
           if: "$get(isAiChat).value === true"
           label: 聊天基本设置
           value:
-            isAnonymous: true
+            accessMode: anonymous_chat
+            modelName: ""
+            chatContextRounds: 20
+            requestAcceptedMessage: "收到啦，马上就来陪你啦～"
+            reasoningMessages:
+              - message: "我正在认真想一想～"
+              - message: "让我整理一下思路，很快就好～"
+              - message: "稍等一下，我正在组织语言呢～"
+            reasoningMessageInterval: 5
             systemMessage: |-
               你现在以 Live2D 二次元看板娘的身份与用户聊天，请始终稳定代入这个角色，不要跳出设定。
 
@@ -190,14 +198,31 @@ spec:
               - 始终保持看板娘人设稳定，不要频繁切换身份、语气或叙述视角。
               - 回复应以易读、自然为主，避免过长大段输出。
               - 在合适场景下可以表现出贴心、活泼、害羞、关心等情绪，但不要夸张失控。
-            timeout: 10
             chunkTimeout: 10
             showChatMessageTimeout: 10
+            autoContinuationMessageMinVisibleMs: 1500
           children:
-            - $formkit: switch
-              label: 是否开启公共聊天
-              help: 关闭后，用户需要登录后才能与 Live2d 进行对话
-              name: isAnonymous
+            - $formkit: select
+              label: 访问模式
+              help: 控制访客能否对话，以及是否允许 Live2D Agent 操作站点能力。旧版公共聊天开启会按“匿名用户可对话”兼容。
+              name: accessMode
+              options:
+                - value: anonymous_chat
+                  label: 匿名用户可对话
+                - value: anonymous_chat_agent
+                  label: 匿名用户可对话和使用 Agent
+                - value: authenticated_chat
+                  label: 登录用户可对话
+                - value: authenticated_chat_agent
+                  label: 登录用户可对话和使用 Agent
+            - $formkit: aiModelSelector
+              name: modelName
+              label: 对话模型
+              modelType: language
+              available: true
+              validation: required
+              placeholder: 请选择对话模型
+              searchPlaceholder: 搜索模型
             - $formkit: textarea
               label: 角色设定
               name: systemMessage
@@ -205,9 +230,30 @@ spec:
               rows: 16
               validation: String
             - $formkit: text
-              label: 接口超时时间（秒）
-              name: timeout
-              validation: Number
+              label: 请求已收到提示语
+              name: requestAcceptedMessage
+              help: 用户发送消息后，Live2D 会立刻展示这条提示语，减少等待时的空白感
+              validation: String
+            - $formkit: repeater
+              label: 思考中提示语
+              name: reasoningMessages
+              help: 当模型正在返回思考内容但还没有可展示回复时，Live2D 会随机展示其中一条。思考时间较长时会自动切换
+              min: 1
+              children:
+                - $formkit: text
+                  name: message
+                  label: 提示语
+                  validation: required
+            - $formkit: text
+              label: 思考提示切换间隔（秒）
+              name: reasoningMessageInterval
+              help: 模型长时间处于思考阶段时，提示语的自动切换间隔，默认 5 秒
+              validation: Number|between:1,60
+            - $formkit: text
+              label: 保留上下文轮数
+              name: chatContextRounds
+              help: 1 轮等于 1 次用户消息 + 1 次看板娘回复。超过后仅保留最近几轮上下文，默认 20
+              validation: Number|between:1,100
             - $formkit: text
               label: 看板娘消息框最大等待时间（秒）
               help: 请求接口数据时，看板娘消息框最大等待时间
@@ -218,65 +264,142 @@ spec:
               help: 获取到完整消息后，看板娘展示的时间
               name: showChatMessageTimeout
               validation: Number
+            - $formkit: text
+              label: Agent 自动续写前消息最短展示时间（毫秒）
+              help: Agent 自动调用工具并继续回复时，上一段看板娘回复至少展示这段时间，避免被后续回复过快覆盖；设置为 0 表示不延迟
+              name: autoContinuationMessageMinVisibleMs
+              validation: Number|between:0,10000
+    - group: agent
+      label: Agent 能力
+      formSchema:
         - $formkit: group
-          name: proxySetting
-          if: "$get(isAiChat).value === true"
-          label: 全局代理设置
-          help: 建议自建代理，而不是使用别人的公开代理
+          name: builtIn
+          label: 预设能力
           value:
-            isProxy: false
+            pageContext: true
+            haloNavigation: true
+            haloContentSearch: true
+            networkAccess: false
+            commentCapability: assist
           children:
             - $formkit: switch
-              label: 启用代理
-              name: isProxy
-              id: isProxy
-              key: isProxy
-            - $formkit: text
-              if: "$value.isProxy === true"
-              label: 代理地址
-              name: proxyHost
-            - $formkit: text
-              if: "$value.isProxy === true"
-              label: 代理端口
-              name: proxyPort
-              validation: Number|between:0,65535
+              name: pageContext
+              label: 当前页面上下文
+              help: 允许模型读取当前页面标题、地址和选中文本等基础上下文
+            - $formkit: switch
+              name: haloNavigation
+              label: Halo 导航
+              help: 允许模型打开可信的 Halo 资源链接
+            - $formkit: switch
+              name: haloContentSearch
+              label: Halo 内容搜索
+              help: 允许模型通过 Halo 搜索引擎查询公开内容
+            - $formkit: switch
+              name: networkAccess
+              label: 网络访问
+              help: 允许模型通过后端工具读取站长白名单中的公网 URL。默认关闭，且会阻止 localhost、内网、链路本地地址和未授权 Origin。
+            - $formkit: select
+              name: commentCapability
+              label: 评论能力
+              help: 关闭：不向模型开放评论相关工具。辅助：允许模型打开评论区、读取当前评论状态并生成评论草稿，但不提交。提交：在站点允许且访客确认后，允许模型尝试提交评论。
+              value: assist
+              options:
+                - value: off
+                  label: 关闭
+                - value: assist
+                  label: 辅助
+                - value: submit
+                  label: 提交
         - $formkit: group
-          name: openAiSetting
-          if: "$get(isAiChat).value === true"
-          label: OpenAI 设置
+          name: toolSecurity
+          label: 安全策略
           value:
-            isOpenAi: false
-            openAiBaseUrl: https://api.openai.com
-            openAiModel: gpt-3.5-turbo
+            allowedExternalOrigins: []
+            allowNewTab: false
           children:
+            - $formkit: repeater
+              name: allowedExternalOrigins
+              label: 允许打开的外部站点
+              help: 仅填写 origin，例如 https://github.com。外链仍会默认请求访客确认。
+              value: []
+              children:
+                - $formkit: text
+                  name: origin
+                  label: Origin
             - $formkit: switch
-              label: 启用 OpenAI
-              help: 基于 OpenAI 进行智能对话
-              name: isOpenAi
-              id: isOpenAi
-              key: isOpenAi
+              name: allowNewTab
+              label: 允许新窗口打开
+              value: false
+        - $formkit: group
+          name: haloSearch
+          label: Halo 搜索
+          value:
+            allowedTypes:
+              - post.content.halo.run
+              - singlepage.content.halo.run
+            defaultLimit: 5
+          children:
+            - $formkit: checkbox
+              name: allowedTypes
+              label: 允许搜索的内容类型
+              help: 只有选中的公开内容类型会暴露给 Agent 搜索。Moment 等类型需要对应插件已接入 Halo 搜索索引。
+              value:
+                - post.content.halo.run
+                - singlepage.content.halo.run
+              options:
+                - value: post.content.halo.run
+                  label: 文章
+                - value: singlepage.content.halo.run
+                  label: 独立页面
+                - value: moment.moment.halo.run
+                  label: 瞬间
+            - $formkit: text
+              name: defaultLimit
+              label: 默认返回数量
+              validation: Number|between:1,20
+        - $formkit: group
+          name: networkAccess
+          label: 网络访问安全策略
+          value:
+            allowedOrigins: []
+            maxResponseChars: 4000
+            timeoutSeconds: 5
+          children:
+            - $formkit: repeater
+              name: allowedOrigins
+              label: 允许访问的 Origin
+              help: 仅填写可信公网 Origin，例如 https://api.example.com。不会跟随重定向，也不会访问 localhost、内网或链路本地地址。
+              value: []
+              children:
+                - $formkit: text
+                  name: origin
+                  label: Origin
             - $formkit: text
-              if: "$value.isOpenAi === true"
-              label: TOKEN
-              help: sk-xxx，可在 https://beta.openai.com/account/api-keys 获取
-              name: openAiToken
-              validation: required|String
+              name: maxResponseChars
+              label: 最大响应字符数
+              help: 超出部分会被截断，范围 1000 到 20000，默认 4000
+              validation: Number|between:1000,20000
             - $formkit: text
-              if: "$value.isOpenAi === true"
-              label: API_BASE_URL
-              help: 接口地址，国内如果访问不了，可考虑使用 openai-api-proxy
-              name: openAiBaseUrl
-              validation: required|url
-            - $formkit: select
-              if: "$value.isOpenAi === true"
-              name: openAiModel
-              label: 模型
-              help: 使用的 OpenAi 模型，可在 https://platform.openai.com/docs/models 查看
-              options:
-                - value: gpt-4
-                  label: gpt-4
-                - value: gpt-3.5-turbo
-                  label: gpt-3.5-turbo
+              name: timeoutSeconds
+              label: 请求超时（秒）
+              help: 后端网络请求超时时间，范围 1 到 15，默认 5
+              validation: Number|between:1,15
+        - $formkit: group
+          name: haloResourceDetail
+          label: 资源详情
+          value:
+            maxContentChars: 3000
+          children:
+            - $formkit: text
+              name: maxContentChars
+              label: 最大正文字符数
+              validation: Number|between:500,10000
+        - $formkit: textarea
+          name: aiTools
+          label: 自定义 Agent 工具 JSON
+          help: 高级配置项。填写工具数组 JSON，支持 navigate、scroll-to、highlight、dispatch-event、registered。
+          rows: 12
+          value: "[]"
     - group: advanced
       label: 高级设置
       formSchema:
diff --git a/src/main/resources/plugin.yaml b/src/main/resources/plugin.yaml
index 3b72227..5c074a8 100644
--- a/src/main/resources/plugin.yaml
+++ b/src/main/resources/plugin.yaml
@@ -6,7 +6,9 @@ metadata:
     "store.halo.run/app-id": "app-oPNFQ"
 spec:
   enabled: true
-  requires: ">=2.22.0"
+  requires: ">=2.25.0"
+  pluginDependencies:
+    ai-foundation: "*"
   author:
     name: LIlGG
     website: https://lixingyong.com
diff --git a/src/test/java/run/halo/live2d/agent/AgentToolNormalizerTest.java b/src/test/java/run/halo/live2d/agent/AgentToolNormalizerTest.java
new file mode 100644
index 0000000..331dece
--- /dev/null
+++ b/src/test/java/run/halo/live2d/agent/AgentToolNormalizerTest.java
@@ -0,0 +1,130 @@
+package run.halo.live2d.agent;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+class AgentToolNormalizerTest {
+    private final ObjectMapper objectMapper = new ObjectMapper();
+    private final AgentToolNormalizer normalizer = new AgentToolNormalizer();
+
+    @Test
+    void mapsLegacyAccessModeToChatOnlyModes() {
+        assertThat(AgentAccessMode.from(null, true)).isEqualTo(AgentAccessMode.ANONYMOUS_CHAT);
+        assertThat(AgentAccessMode.from(null, false)).isEqualTo(
+            AgentAccessMode.AUTHENTICATED_CHAT);
+    }
+
+    @Test
+    void mapsFormValuesToAgentEnums() throws Exception {
+        var settings = objectMapper.readValue(
+            """
+                {
+                  "builtIn": {
+                    "commentCapability": "assist"
+                  },
+                  "aiTools": [{
+                    "name": "open_contact_form",
+                    "enabled": true,
+                    "description": "打开留言面板",
+                    "approval": "always",
+                    "requiredAuth": "authenticated",
+                    "action": {
+                      "type": "registered"
+                    }
+                  }]
+                }
+                """,
+            AgentSettings.class);
+
+        assertThat(settings.builtIn().commentCapability()).isEqualTo(AgentCommentCapability.ASSIST);
+        assertThat(settings.normalizedAiTools()).hasSize(1);
+        assertThat(settings.normalizedAiTools().getFirst().approval())
+            .isEqualTo(AgentToolApproval.ALWAYS);
+        assertThat(settings.normalizedAiTools().getFirst().requiredAuth())
+            .isEqualTo(AgentToolAuth.AUTHENTICATED);
+        assertThat(objectMapper.writeValueAsString(settings.builtIn()))
+            .contains("\"commentCapability\":\"assist\"");
+    }
+
+    @Test
+    void normalizesValidCustomTool() throws Exception {
+        var settings = new AgentSettings(
+            null,
+            """
+                [{
+                  "name": "open_contact_form",
+                  "enabled": true,
+                  "description": "打开留言面板",
+                  "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                      "message": {
+                        "type": "string",
+                        "description": "留言草稿"
+                      }
+                    },
+                    "required": ["message"]
+                  },
+                  "action": {
+                    "type": "dispatch-event",
+                    "event": "site:open-contact-form"
+                  }
+                }]
+                """,
+            null,
+            null,
+            null,
+            null
+        );
+
+        var tools = normalizer.normalizeCustomTools(settings);
+
+        assertThat(tools).hasSize(1);
+        assertThat(tools.getFirst().name()).isEqualTo("open_contact_form");
+        assertThat(tools.getFirst().actionType()).isEqualTo("dispatch-event");
+        assertThat(tools.getFirst().inputSchema()).containsEntry("type", "object");
+    }
+
+    @Test
+    void rejectsUnsupportedSchemaAndReservedNames() throws Exception {
+        var tools = List.of(
+            new AgentSettings.AgentToolConfig(
+                "perform_live2d_action",
+                true,
+                "reserved",
+                objectMapper.readTree("{\"type\":\"object\",\"properties\":{}}"),
+                AgentToolApproval.DEFAULT,
+                AgentToolAuth.NONE,
+                objectMapper.readTree("{\"type\":\"registered\"}"),
+                null
+            ),
+            new AgentSettings.AgentToolConfig(
+                "open_bad_tool",
+                true,
+                "bad schema",
+                objectMapper.readTree(
+                    "{\"type\":\"object\",\"properties\":{\"items\":{\"type\":\"array\"}}}"),
+                AgentToolApproval.DEFAULT,
+                AgentToolAuth.NONE,
+                objectMapper.readTree("{\"type\":\"registered\"}"),
+                null
+            ),
+            new AgentSettings.AgentToolConfig(
+                "old_live2d_action",
+                true,
+                "unsupported action",
+                objectMapper.readTree("{\"type\":\"object\",\"properties\":{}}"),
+                AgentToolApproval.DEFAULT,
+                AgentToolAuth.NONE,
+                objectMapper.readTree("{\"type\":\"perform-live2d-action\"}"),
+                null
+            )
+        );
+        var settings = new AgentSettings(null, tools, null, null, null, null);
+
+        assertThat(normalizer.normalizeCustomTools(settings)).isEmpty();
+    }
+}
diff --git a/src/test/java/run/halo/live2d/agent/AgentToolServiceTest.java b/src/test/java/run/halo/live2d/agent/AgentToolServiceTest.java
new file mode 100644
index 0000000..3880b23
--- /dev/null
+++ b/src/test/java/run/halo/live2d/agent/AgentToolServiceTest.java
@@ -0,0 +1,119 @@
+package run.halo.live2d.agent;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+class AgentToolServiceTest {
+    private final ObjectMapper objectMapper = new ObjectMapper();
+    private final AgentToolNormalizer normalizer = new AgentToolNormalizer();
+
+    @Test
+    void doesNotExposeToolsWhenAgentDisabled() {
+        var service = new AgentToolService(normalizer, null);
+
+        var tools = service.buildTools(AgentSettings.defaults(), AgentAccessMode.ANONYMOUS_CHAT,
+            false);
+
+        assertThat(tools.agentEnabled()).isFalse();
+        assertThat(tools.tools()).isEmpty();
+    }
+
+    @Test
+    void filtersAuthenticatedCustomToolsForAnonymousVisitors() throws Exception {
+        var service = new AgentToolService(normalizer, null);
+        var settings = new AgentSettings(
+            new AgentSettings.AgentBuiltInCapabilities(false, false, false, false,
+                AgentCommentCapability.OFF),
+            List.of(new AgentSettings.AgentToolConfig(
+                "secure_action",
+                true,
+                "登录后可用能力",
+                objectMapper.readTree("{\"type\":\"object\",\"properties\":{}}"),
+                AgentToolApproval.DEFAULT,
+                AgentToolAuth.AUTHENTICATED,
+                objectMapper.readTree("{\"type\":\"registered\"}"),
+                null
+            )),
+            null,
+            null,
+            null,
+            null
+        );
+
+        assertThat(service.buildTools(settings, AgentAccessMode.ANONYMOUS_CHAT_AGENT, false)
+            .tools()).isEmpty();
+        assertThat(service.buildTools(settings, AgentAccessMode.ANONYMOUS_CHAT_AGENT, true)
+            .tools()).extracting("name").containsExactly("secure_action");
+    }
+
+    @Test
+    void assistCommentCapabilityExposesDraftButNotSubmitTool() {
+        var service = new AgentToolService(normalizer, null);
+        var settings = new AgentSettings(
+            new AgentSettings.AgentBuiltInCapabilities(false, false, false, false,
+                AgentCommentCapability.ASSIST),
+            List.of(),
+            null,
+            null,
+            null,
+            null
+        );
+
+        var tools = service.buildTools(settings, AgentAccessMode.ANONYMOUS_CHAT_AGENT, false)
+            .tools();
+
+        assertThat(tools).extracting("name")
+            .contains("open_comment_area", "draft_comment")
+            .doesNotContain("submit_comment");
+        assertThat(tools.stream().filter(tool -> "draft_comment".equals(tool.getName()))
+            .findFirst().orElseThrow().getExecutor()).isNull();
+    }
+
+    @Test
+    void submitCommentCapabilityExposesApprovedBrowserSubmitTool() {
+        var service = new AgentToolService(normalizer, null);
+        var settings = new AgentSettings(
+            new AgentSettings.AgentBuiltInCapabilities(false, false, false, false,
+                AgentCommentCapability.SUBMIT),
+            List.of(),
+            null,
+            null,
+            null,
+            null
+        );
+
+        var submitTool = service.buildTools(settings, AgentAccessMode.ANONYMOUS_CHAT_AGENT, false)
+            .tools()
+            .stream()
+            .filter(tool -> "submit_comment".equals(tool.getName()))
+            .findFirst()
+            .orElseThrow();
+
+        assertThat(submitTool.getExecutor()).isNull();
+        assertThat(submitTool.getApprovalPolicy()).isNotNull();
+    }
+
+    @Test
+    void networkAccessToolIsExposedOnlyWhenEnabled() {
+        var service = new AgentToolService(normalizer, null);
+        var disabled = AgentSettings.defaults();
+        var enabled = new AgentSettings(
+            new AgentSettings.AgentBuiltInCapabilities(false, false, false, true,
+                AgentCommentCapability.OFF),
+            List.of(),
+            null,
+            null,
+            null,
+            new AgentSettings.AgentNetworkAccessSettings(
+                List.of("https://api.example.com"), 4000, 5)
+        );
+
+        assertThat(service.buildTools(disabled, AgentAccessMode.ANONYMOUS_CHAT_AGENT, false)
+            .tools()).extracting("name").doesNotContain("fetch_allowed_url");
+        assertThat(service.buildTools(enabled, AgentAccessMode.ANONYMOUS_CHAT_AGENT, false)
+            .tools()).extracting("name").contains("fetch_allowed_url");
+    }
+}
diff --git a/src/test/java/run/halo/live2d/agent/HaloAgentPresetToolServiceTest.java b/src/test/java/run/halo/live2d/agent/HaloAgentPresetToolServiceTest.java
new file mode 100644
index 0000000..516f6ef
--- /dev/null
+++ b/src/test/java/run/halo/live2d/agent/HaloAgentPresetToolServiceTest.java
@@ -0,0 +1,107 @@
+package run.halo.live2d.agent;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+import reactor.core.publisher.Mono;
+import run.halo.app.extension.ReactiveExtensionClient;
+import run.halo.app.search.HaloDocument;
+import run.halo.app.search.SearchOption;
+import run.halo.app.search.SearchResult;
+import run.halo.app.search.SearchService;
+
+class HaloAgentPresetToolServiceTest {
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void searchHaloResourcesUsesSearchServiceAndMapsBoundedResources() {
+        var searchService = mock(SearchService.class);
+        var extensionClient = mock(ReactiveExtensionClient.class);
+        var service = new HaloAgentPresetToolService(searchService, extensionClient);
+        var result = new SearchResult();
+        result.setKeyword("Halo");
+        result.setTotal(1L);
+        result.setHits(List.of(document()));
+        when(searchService.search(any(SearchOption.class))).thenReturn(Mono.just(result));
+
+        var output = (Map<String, Object>) service.searchHaloResources(
+            Map.of("keyword", "Halo", "includeTypes", List.of("post.content.halo.run")),
+            AgentSettings.defaults()).block();
+
+        assertThat(output).containsEntry("ok", true);
+        var resources = (List<Map<String, Object>>) output.get("resources");
+        assertThat(resources).hasSize(1);
+        assertThat(resources.getFirst())
+            .containsEntry("resourceId", "post.content.halo.run:demo-post")
+            .containsEntry("title", "Demo Post")
+            .containsEntry("permalink", "https://example.com/archives/demo");
+        verify(searchService).search(any(SearchOption.class));
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void fetchAllowedUrlRequiresAllowedOrigin() {
+        var service = new HaloAgentPresetToolService(mock(SearchService.class),
+            mock(ReactiveExtensionClient.class));
+
+        var output = (Map<String, Object>) service.fetchAllowedUrl(
+            Map.of("url", "https://api.example.com/data"),
+            AgentSettings.defaults()).block();
+
+        assertThat(output)
+            .containsEntry("ok", false)
+            .containsEntry("errorCode", "NETWORK_ACCESS_DENIED");
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void fetchAllowedUrlRejectsPrivateTargetsEvenWhenAllowed() {
+        var service = new HaloAgentPresetToolService(mock(SearchService.class),
+            mock(ReactiveExtensionClient.class));
+        var settings = new AgentSettings(
+            new AgentSettings.AgentBuiltInCapabilities(false, false, false, true,
+                AgentCommentCapability.OFF),
+            List.of(),
+            null,
+            null,
+            null,
+            new AgentSettings.AgentNetworkAccessSettings(
+                List.of("http://127.0.0.1"), 4000, 5)
+        );
+
+        var output = (Map<String, Object>) service.fetchAllowedUrl(
+            Map.of("url", "http://127.0.0.1/secret"), settings).block();
+
+        assertThat(output)
+            .containsEntry("ok", false)
+            .containsEntry("errorCode", "NETWORK_ACCESS_DENIED")
+            .extracting("message")
+            .asString()
+            .contains("禁止访问");
+    }
+
+    private HaloDocument document() {
+        var document = new HaloDocument();
+        document.setId("doc-1");
+        document.setMetadataName("demo-post");
+        document.setTitle("Demo Post");
+        document.setDescription("Demo Description");
+        document.setContent("Demo Content");
+        document.setPublished(true);
+        document.setExposed(true);
+        document.setRecycled(false);
+        document.setOwnerName("admin");
+        document.setCreationTimestamp(Instant.now());
+        document.setUpdateTimestamp(Instant.now());
+        document.setPermalink("https://example.com/archives/demo");
+        document.setType("post.content.halo.run");
+        return document;
+    }
+}