chore: release v1.0.18 (#647)

Change-Id: Ibda8379838392a895f6afddb140fca7f06e5df50

.codecov.yml

@@ -6,3 +6,6 @@ coverage:
     patch:
       default:
         target: 60%
+
+github_checks:
+  annotations: true

.github/workflows/arch-audit.yml

@@ -0,0 +1,116 @@
+name: Architecture Audit
+
+on:
+  schedule:
+    - cron: '0 9 * * 1' # Monday 09:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - 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: Dead code detection
+        run: |
+          echo "## Dead Code" >> report.md
+          go run golang.org/x/tools/cmd/deadcode@v0.31.0 -test ./... 2>&1 | tee deadcode.txt
+          count=$(wc -l < deadcode.txt | tr -d ' ')
+          echo "Found **$count** unreachable functions" >> report.md
+          echo '```' >> report.md
+          cat deadcode.txt >> report.md
+          echo '```' >> report.md
+
+      - name: Package complexity
+        run: |
+          echo "## Package Complexity" >> report.md
+          echo "" >> report.md
+          echo "Packages exceeding 2 000 lines or 20 files:" >> report.md
+          echo "" >> report.md
+          echo "| Package | Files | Lines | Deps |" >> report.md
+          echo "|---------|-------|-------|------|" >> report.md
+          found=0
+          for pkg in $(go list ./cmd/... ./internal/... ./shortcuts/...); do
+            dir=$(go list -f '{{.Dir}}' "$pkg")
+            files=$(find "$dir" -maxdepth 1 -name '*.go' ! -name '*_test.go' | wc -l | tr -d ' ')
+            lines=$(find "$dir" -maxdepth 1 -name '*.go' ! -name '*_test.go' -exec cat {} + 2>/dev/null | wc -l | tr -d ' ')
+            deps=$(go list -f '{{len .Imports}}' "$pkg")
+            if [ "$lines" -gt 2000 ] || [ "$files" -gt 20 ]; then
+              echo "| **$pkg** | **$files** | **$lines** | **$deps** |" >> report.md
+              found=1
+            fi
+          done
+          if [ "$found" = "0" ]; then
+            echo "| _(none)_ | | | |" >> report.md
+          fi
+
+      - name: Dependency freshness
+        run: |
+          echo "## Outdated Dependencies" >> report.md
+          echo '```' >> report.md
+          go list -m -u all 2>/dev/null | grep '\[' >> report.md || echo "All dependencies up to date" >> report.md
+          echo '```' >> report.md
+
+      - name: Circular dependency check
+        run: |
+          echo "## Circular Dependencies" >> report.md
+          go list -f '{{.ImportPath}} {{join .Imports " "}}' ./... | \
+            go run golang.org/x/tools/cmd/digraph@v0.31.0 scc 2>&1 | tee cycles.txt
+          if [ -s cycles.txt ]; then
+            echo '```' >> report.md
+            cat cycles.txt >> report.md
+            echo '```' >> report.md
+          else
+            echo "No circular dependencies detected." >> report.md
+          fi
+
+      - name: E2E coverage gaps
+        run: |
+          echo "## E2E Coverage Gaps" >> report.md
+          echo "" >> report.md
+          echo "Shortcut domains without E2E tests:" >> report.md
+          echo "" >> report.md
+          found=0
+          for domain in $(ls -d shortcuts/*/); do
+            name=$(basename "$domain")
+            if [ "$name" = "common" ]; then continue; fi
+            if [ ! -d "tests/cli_e2e/$name" ]; then
+              echo "- **$name** (no tests/cli_e2e/$name/)" >> report.md
+              found=1
+            fi
+          done
+          if [ "$found" = "0" ]; then
+            echo "All shortcut domains have E2E test directories." >> report.md
+          fi
+
+      - name: Coverage
+        run: |
+          echo "## Coverage" >> report.md
+          packages=$(go list ./... | grep -v 'tests/cli_e2e')
+          go test -coverprofile=coverage.txt -covermode=atomic $packages 2>/dev/null || true
+          total=$(go tool cover -func=coverage.txt 2>/dev/null | grep total | awk '{print $3}')
+          echo "Current total coverage: **${total:-n/a}**" >> report.md
+
+      - name: Publish report
+        run: |
+          echo "# Architecture Audit Report — $(date +%Y-%m-%d)" > $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          cat report.md >> $GITHUB_STEP_SUMMARY
+
+      - name: Upload report artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: arch-audit-${{ github.run_number }}
+          path: report.md
+          retention-days: 90

.github/workflows/ci.yml

@@ -0,0 +1,334 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: read
+  checks: write
+  pull-requests: write
+
+jobs:
+  # ── Layer 1: Fast Gate ─────────────────────────────────────────────
+  fast-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - 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: Build
+        run: go build ./...
+      - name: Vet
+        run: go vet ./...
+      - name: Check formatting
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "$unformatted"
+            echo "::error::Unformatted Go files detected — run 'gofmt -w .' and commit"
+            exit 1
+          fi
+      - name: Check go.mod tidiness
+        run: |
+          go mod tidy
+          if ! git diff --quiet go.mod go.sum; then
+            echo "::error::go.mod or go.sum is not tidy. Run 'go mod tidy' and commit the changes."
+            git diff go.mod go.sum
+            exit 1
+          fi
+
+  # ── Layer 2: Quality Gate ──────────────────────────────────────────
+  unit-test:
+    needs: fast-gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - 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: Run tests
+        run: go test -v -race -count=1 -timeout=5m ./cmd/... ./internal/... ./shortcuts/...
+
+  lint:
+    needs: fast-gate
+    runs-on: ubuntu-latest
+    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: Run golangci-lint
+        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
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - 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: Run tests with coverage
+        run: |
+          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
+        uses: codecov/codecov-action@3f20e214133d0983f9a10f3d63b0faf9241a3daa # v6
+        with:
+          files: coverage.txt
+          token: ${{ secrets.CODECOV_TOKEN }}
+      - name: Check coverage threshold
+        run: |
+          total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}' | tr -d '%')
+          threshold=40
+          echo "Coverage: ${total}% (threshold: ${threshold}%)"
+          if (( $(echo "$total < $threshold" | bc -l) )); then
+            echo "::error::Coverage ${total}% is below threshold ${threshold}%"
+            exit 1
+          fi
+      - name: Coverage summary
+        if: ${{ !cancelled() }}
+        run: |
+          if [ ! -f coverage.txt ]; then
+            echo "No coverage data available" >> $GITHUB_STEP_SUMMARY
+            exit 0
+          fi
+          total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}')
+          echo "## Coverage Report" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Total coverage: ${total}**" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "<details><summary>Details</summary>" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          go tool cover -func=coverage.txt >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "</details>" >> $GITHUB_STEP_SUMMARY
+
+  deadcode:
+    needs: fast-gate
+    if: ${{ github.event_name == 'pull_request' }}
+    runs-on: ubuntu-latest
+    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: Dead code check (incremental)
+        run: |
+          # Analyze current HEAD (strip line:col for stable diff across line shifts)
+          # Filter "go: downloading ..." lines to avoid false diffs from module cache state
+          go run golang.org/x/tools/cmd/deadcode@v0.31.0 -test ./... 2>&1 | \
+            grep -v '^go: ' | \
+            sed 's/:[0-9][0-9]*:[0-9][0-9]*:/:/' | sort > /tmp/dc-head.txt
+
+          # Analyze base branch via worktree
+          git worktree add -q /tmp/dc-base "origin/${{ github.base_ref }}"
+          (cd /tmp/dc-base && python3 scripts/fetch_meta.py && \
+           go run golang.org/x/tools/cmd/deadcode@v0.31.0 -test ./... 2>&1 | \
+            grep -v '^go: ' | \
+            sed 's/:[0-9][0-9]*:[0-9][0-9]*:/:/' | sort > /tmp/dc-base.txt) || {
+            echo "::warning::Failed to analyze base branch — skipping incremental dead code check"
+            git worktree remove -f /tmp/dc-base 2>/dev/null || true
+            exit 0
+          }
+          git worktree remove -f /tmp/dc-base
+
+          # Only new dead code blocks the PR
+          comm -23 /tmp/dc-head.txt /tmp/dc-base.txt > /tmp/dc-new.txt
+          if [ -s /tmp/dc-new.txt ]; then
+            echo "::group::New dead code"
+            cat /tmp/dc-new.txt
+            echo "::endgroup::"
+            echo "::error::New dead code detected — remove unreachable functions before merging"
+            exit 1
+          fi
+          echo "No new dead code introduced"
+
+  # ── Layer 3: E2E Gate ──────────────────────────────────────────────
+  e2e-dry-run:
+    needs: [unit-test, lint]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.x'
+      - name: Build lark-cli
+        run: make build
+      - name: Run dry-run E2E tests
+        env:
+          LARK_CLI_BIN: ${{ github.workspace }}/lark-cli
+          LARKSUITE_CLI_APP_ID: dry-run
+          LARKSUITE_CLI_APP_SECRET: dry-run
+          LARKSUITE_CLI_BRAND: feishu
+        run: go test -v -count=1 -timeout=5m ./tests/cli_e2e/... -run 'DryRun|Regression'
+
+  e2e-live:
+    needs: [unit-test, lint]
+    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
+    runs-on: ubuntu-latest
+    env:
+      TEST_BOT1_APP_ID: ${{ secrets.TEST_BOT1_APP_ID }}
+      TEST_BOT1_APP_SECRET: ${{ secrets.TEST_BOT1_APP_SECRET }}
+      TEST_USER_ACCESS_TOKEN: ${{ secrets.TEST_USER_ACCESS_TOKEN }}
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.x'
+      - name: Build lark-cli
+        run: make build
+      - name: Configure bot credentials
+        run: |
+          if [ -z "$TEST_BOT1_APP_ID" ] || [ -z "$TEST_BOT1_APP_SECRET" ]; then
+            echo "::error::Missing required secrets: TEST_BOT1_APP_ID / TEST_BOT1_APP_SECRET"
+            exit 1
+          fi
+          printf '%s\n' "$TEST_BOT1_APP_SECRET" | ./lark-cli config init --app-id "$TEST_BOT1_APP_ID" --app-secret-stdin
+      - name: Run CLI E2E tests
+        env:
+          LARK_CLI_BIN: ${{ github.workspace }}/lark-cli
+        run: |
+          packages=$(go list ./tests/cli_e2e/... | grep -v '^github.com/larksuite/cli/tests/cli_e2e$' | grep -v '/demo$')
+          if [ -z "$packages" ]; then
+            echo "No CLI E2E packages to test after exclusions."
+            exit 1
+          fi
+          packages_arg=$(printf '%s\n' "$packages" | paste -sd' ' -)
+          go run gotest.tools/gotestsum@v1.12.3 --rerun-fails=2 --rerun-fails-max-failures=20 --packages="$packages_arg" --format testname --junitfile cli-e2e-report.xml -- -count=1 -v
+      - name: Publish CLI E2E test report
+        if: ${{ !cancelled() }}
+        uses: dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2 # v3.0.0
+        with:
+          name: CLI E2E Tests
+          path: cli-e2e-report.xml
+          reporter: java-junit
+          use-actions-summary: true
+          list-suites: all
+          list-tests: all
+
+  # ── Layer 4: Security & Compliance (parallel with L2-L3) ──────────
+  security:
+    runs-on: ubuntu-latest
+    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: Gitleaks
+        if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
+        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2.3.9
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_KEY }}
+      - name: govulncheck
+        continue-on-error: true
+        run: go run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./...
+      - name: Check dependency licenses
+        run: go run github.com/google/go-licenses/v2@v2.0.1 check ./... --disallowed_types=forbidden,restricted,reciprocal,unknown
+
+  license-header:
+    if: ${{ github.event_name == 'pull_request' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - name: Check license headers
+        uses: apache/skywalking-eyes/header@8c96ee223558797cdd9eba82c0919258e1cf2dad
+        with:
+          config: .licenserc.yaml
+
+  # ── Results Gate (single required check for branch protection) ─────
+  results:
+    if: ${{ always() }}
+    needs: [fast-gate, unit-test, lint, coverage, deadcode, e2e-dry-run, e2e-live, security, license-header]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Evaluate results
+        run: |
+          echo "## CI Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Layer | Job | Status |" >> $GITHUB_STEP_SUMMARY
+          echo "|-------|-----|--------|" >> $GITHUB_STEP_SUMMARY
+          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 | 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
+          echo "| L3 | e2e-live | ${{ needs.e2e-live.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L4 | security | ${{ needs.security.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L4 | license-header | ${{ needs.license-header.result }} |" >> $GITHUB_STEP_SUMMARY
+
+          # Any failure or cancellation in any job blocks the merge.
+          # Legitimately skipped jobs (deadcode on push, e2e-live on fork,
+          # license-header on push) are OK.
+          FAILED=0
+          for result in \
+            "${{ needs.fast-gate.result }}" \
+            "${{ needs.unit-test.result }}" \
+            "${{ needs.lint.result }}" \
+            "${{ needs.coverage.result }}" \
+            "${{ needs.deadcode.result }}" \
+            "${{ needs.e2e-dry-run.result }}" \
+            "${{ needs.e2e-live.result }}" \
+            "${{ needs.security.result }}" \
+            "${{ needs.license-header.result }}"; do
+            if [ "$result" = "failure" ] || [ "$result" = "cancelled" ]; then
+              FAILED=1
+            fi
+          done
+
+          if [ "$FAILED" = "1" ]; then
+            echo ""
+            echo "::error::One or more CI jobs failed — see table above"
+            exit 1
+          fi

.github/workflows/cli-e2e.yml

@@ -1,83 +0,0 @@
-name: CLI E2E Tests
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - Makefile
-      - scripts/fetch_meta.py
-      - tests/cli_e2e/**
-      - .github/workflows/cli-e2e.yml
-  pull_request:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - Makefile
-      - scripts/fetch_meta.py
-      - tests/cli_e2e/**
-      - .github/workflows/cli-e2e.yml
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  actions: read
-  checks: write
-
-jobs:
-  cli-e2e:
-    # Forked pull_request runs do not receive repository/org secrets except GITHUB_TOKEN.
-    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
-    runs-on: ubuntu-latest
-    env:
-      TEST_BOT1_APP_ID: ${{ secrets.TEST_BOT1_APP_ID }}
-      TEST_BOT1_APP_SECRET: ${{ secrets.TEST_BOT1_APP_SECRET }}
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        with:
-          go-version-file: go.mod
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
-        with:
-          python-version: '3.x'
-
-      - name: Build lark-cli
-        run: make build
-
-      - name: Configure bot credentials
-        run: |
-          if [ -z "$TEST_BOT1_APP_ID" ] || [ -z "$TEST_BOT1_APP_SECRET" ]; then
-            echo "::error::Missing required secrets: TEST_BOT1_APP_ID / TEST_BOT1_APP_SECRET"
-            exit 1
-          fi
-          printf '%s\n' "$TEST_BOT1_APP_SECRET" | ./lark-cli config init --app-id "$TEST_BOT1_APP_ID" --app-secret-stdin
-
-      - name: Run CLI E2E tests
-        env:
-          LARK_CLI_BIN: ${{ github.workspace }}/lark-cli
-        run: |
-          packages=$(go list ./tests/cli_e2e/... | grep -v '^github.com/larksuite/cli/tests/cli_e2e$' | grep -v '/demo$')
-          if [ -z "$packages" ]; then
-            echo "No CLI E2E packages to test after exclusions."
-            exit 1
-          fi
-          # gotestsum requires --packages when --rerun-fails is combined with go test args after --.
-          packages_arg=$(printf '%s\n' "$packages" | paste -sd' ' -)
-          go run gotest.tools/gotestsum@v1.12.3 --rerun-fails=2 --rerun-fails-max-failures=20 --packages="$packages_arg" --format testname --junitfile cli-e2e-report.xml -- -count=1 -v
-
-      - name: Publish CLI E2E test report
-        if: ${{ !cancelled() }}
-        uses: dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2 # v3.0.0
-        with:
-          name: CLI E2E Tests
-          path: cli-e2e-report.xml
-          reporter: java-junit
-          use-actions-summary: true
-          list-suites: all
-          list-tests: all

.github/workflows/coverage.yml

@@ -1,58 +0,0 @@
-name: Coverage
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - "**.go"
-      - "!tests/cli_e2e/**"
-      - go.mod
-      - go.sum
-      - .github/workflows/coverage.yml
-  pull_request:
-    branches: [main]
-    paths:
-      - "**.go"
-      - "!tests/cli_e2e/**"
-      - go.mod
-      - go.sum
-      - .github/workflows/coverage.yml
-
-permissions:
-  contents: read
-
-jobs:
-  coverage:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-
-      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
-        with:
-          go-version-file: go.mod
-
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
-        with:
-          python-version: '3.x'
-
-      - name: Fetch meta data
-        run: python3 scripts/fetch_meta.py
-
-      - name: Run tests with coverage
-        run: |
-          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: Generate coverage report
-        run: |
-          total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}')
-          echo "## Coverage Report" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "**Total coverage: ${total}**" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "<details><summary>Details</summary>" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo '```' >> $GITHUB_STEP_SUMMARY
-          go tool cover -func=coverage.txt >> $GITHUB_STEP_SUMMARY
-          echo '```' >> $GITHUB_STEP_SUMMARY
-          echo "</details>" >> $GITHUB_STEP_SUMMARY

.github/workflows/gitleaks.yml

@@ -1,28 +0,0 @@
-name: Gitleaks
-
-on:
-  pull_request:
-    branches: [main]
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  gitleaks:
-    # Forked pull_request runs do not receive repository/org secrets except GITHUB_TOKEN.
-    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        with:
-          fetch-depth: 0
-
-      - uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2.3.9
-        env:
-          # GITHUB_TOKEN is provided automatically by GitHub Actions.
-          # GITLEAKS_KEY must be configured as a repository secret.
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_KEY }}

.github/workflows/license-header.yml

@@ -1,26 +0,0 @@
-name: License Header
-
-on:
-  pull_request:
-    branches: [main]
-    paths:
-      - "**/*.go"
-      - "**/*.js"
-      - "**/*.py"
-      - .licenserc.yaml
-      - .github/workflows/license-header.yml
-
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  header-check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-
-      - name: Check license headers
-        uses: apache/skywalking-eyes/header@8c96ee223558797cdd9eba82c0919258e1cf2dad
-        with:
-          config: .licenserc.yaml

.github/workflows/lint.yml

@@ -1,60 +0,0 @@
-name: Lint
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - .golangci.yml
-      - .github/workflows/lint.yml
-  pull_request:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - .golangci.yml
-      - .github/workflows/lint.yml
-
-permissions:
-  contents: read
-
-jobs:
-  golangci-lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
-        with:
-          go-version-file: go.mod
-
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
-        with:
-          python-version: '3.x'
-
-      - name: Fetch meta_data.json
-        run: python3 scripts/fetch_meta.py
-
-      - name: Ensure go.mod and go.sum are tidy
-        run: |
-          go mod tidy
-          if ! git diff --quiet go.mod go.sum; then
-            echo "::error::go.mod or go.sum is not tidy. Run 'go mod tidy' and commit the changes."
-            git diff go.mod go.sum
-            exit 1
-          fi
-
-      - name: Run golangci-lint
-        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main
-
-      - name: Run govulncheck
-        continue-on-error: true # informational until Go version is upgraded
-        run: go run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./...
-
-      - name: Check dependency licenses
-        run: go run github.com/google/go-licenses/v2@v2.0.1 check ./... --disallowed_types=forbidden,restricted,reciprocal,unknown

.github/workflows/release.yml

@@ -45,6 +45,15 @@ jobs:
           node-version: '20'
           registry-url: 'https://registry.npmjs.org'
 
+      - name: Download checksums from release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF_NAME}"
+          gh release download "${TAG}" --pattern checksums.txt --dir .
+          test -s checksums.txt || { echo "checksums.txt missing or empty for ${TAG}"; exit 1; }
+
       - name: Publish to npm
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/tests.yml

@@ -1,43 +0,0 @@
-name: Tests
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - .github/workflows/tests.yml
-  pull_request:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - .github/workflows/tests.yml
-
-permissions:
-  contents: read
-
-jobs:
-  unit-test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-
-      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
-        with:
-          go-version-file: go.mod
-
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
-        with:
-          python-version: '3.x'
-
-      - name: Fetch meta data
-        run: python3 scripts/fetch_meta.py
-
-      - name: Run tests
-        run: go test -v -race -count=1 -timeout=5m ./cmd/... ./internal/... ./shortcuts/...
-
-      - name: Build
-        run: go build -v ./...

.gitignore

@@ -36,3 +36,5 @@ tests/mail/reports/
 internal/registry/meta_data.json
 cmd/api/download.bin
 app.log
+/sidecar-server-demo
+/server-demo

.golangci.yml

@@ -70,6 +70,14 @@ linters:
               desc: >-
                 shortcuts must not import internal/vfs/localfileio directly.
                 Use runtime.FileIO() for file operations or runtime.ValidatePath() for path validation.
+        shortcuts-no-raw-http:
+          files:
+            - "**/shortcuts/**"
+          deny:
+            - pkg: "net/http"
+              desc: >-
+                use RuntimeContext.DoAPI/CallAPI/DoAPIJSON instead of raw net/http.
+                The client layer handles auth, headers, and error normalization.
     forbidigo:
       forbid:
         # ── os: already wrapped in internal/vfs ──
@@ -100,6 +108,16 @@ linters:
           msg: >-
             Do not use os.Exit in shortcuts/. Return an error instead and let
             the caller (cmd layer) decide how to terminate.
+        # ── output: shortcuts must use ctx.Out() ──
+        - pattern: fmt\.Print(f|ln)?\b
+          msg: >-
+            use ctx.Out() or ctx.OutFormat() for structured JSON output.
+            fmt.Print* bypasses the output envelope and breaks --jq/--format.
+        # ── logging: shortcuts must return errors, not log.Fatal ──
+        - pattern: log\.(Print|Fatal|Panic)(f|ln)?\b
+          msg: >-
+            use structured error return, not log.Fatal/Panic.
+            Shortcuts must return errors to the framework for proper exit code handling.
         # ── filepath: functions that access the filesystem ──
         - pattern: filepath\.(EvalSymlinks|Walk|WalkDir|Glob|Abs)\b
           msg: >-

AGENTS.md

@@ -18,9 +18,11 @@ make test           # Full: vet + unit + integration
 ## Pre-PR Checks (match CI gates)
 
 1. `make unit-test`
-2. `go mod tidy` — must not change `go.mod`/`go.sum`
-3. `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main`
-4. If dependencies changed: `go run github.com/google/go-licenses/v2@v2.0.1 check ./... --disallowed_types=forbidden,restricted,reciprocal,unknown`
+2. `go vet ./...`
+3. `gofmt -l .` — must produce no output
+4. `go mod tidy` — must not change `go.mod`/`go.sum`
+5. `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main`
+6. If dependencies changed: `go run github.com/google/go-licenses/v2@v2.0.1 check ./... --disallowed_types=forbidden,restricted,reciprocal,unknown`
 
 ## Commit & PR
 
@@ -76,3 +78,26 @@ CLI arguments are untrusted (they come from AI agents). Call `validate.SafeInput
 - Every behavior change needs a test alongside the change.
 - `cmdutil.TestFactory(t, config)` for test factories.
 - `t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())` to isolate config state.
+
+### E2E Testing
+
+**Dry-run E2E (required for every shortcut change)**
+- Validates request structure without calling real APIs
+- Place in `tests/cli_e2e/dryrun/` or the corresponding domain directory
+- Set env vars `LARKSUITE_CLI_APP_ID`/`APP_SECRET`/`BRAND`, use `--dry-run`, assert method/URL/params
+- No secrets needed — runs on fork PRs
+- Explore correct params with `lark-cli <domain> --help` and `lark-cli schema` first
+
+**Live E2E (required for new flows or behavior changes)**
+- Validates real API round-trips
+- Place in `tests/cli_e2e/<domain>/`
+- Must be self-contained: create -> use -> cleanup
+- Needs bot credentials (CI secrets, skipped on fork PRs)
+- Reference: `tests/cli_e2e/task/task_status_workflow_test.go`
+
+| Change | Dry-run E2E | Live E2E |
+|--------|:-----------:|:--------:|
+| New shortcut | Required | Required |
+| Modify shortcut flags/params | Required | If behavior changes |
+| Shortcut bug fix | Required | If regression risk |
+| Internal refactor (no shortcut impact) | Not needed | Not needed |

CHANGELOG.md

@@ -2,6 +2,191 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.18] - 2026-04-23
+
+### Features
+
+- **base**: Support `.base` import and export for bitable (#599)
+- **config**: Add `config bind` for per-Agent credential isolation (#515)
+- **slides**: Add `+replace-slide` shortcut for block-level XML edits (#516)
+- **wiki**: Add `+delete-space` shortcut with async task polling (#610)
+- **doc**: Add `--from-clipboard` flag to `docs +media-insert` (#508)
+- **minutes**: Unify minute artifacts output to `./minutes/{minute_token}/` (#604)
+- Add configurable content-safety scanning (#606)
+- **install**: Add SHA-256 checksum verification to `install.js` (#592)
+- **whiteboard**: Pin `whiteboard-cli` to `^0.2.9` (#617)
+
+### Bug Fixes
+
+- **drive**: Escape angle brackets in comment text (#632)
+- **im**: Unify `messages-search` pagination int flags (#446)
+- **im**: Fix markdown URL rendering issues in post content (#206)
+
+### Documentation
+
+- **base**: Refine record cell value guidance (#636)
+
+## [v1.0.17] - 2026-04-22
+
+### Features
+
+- **im**: Use `Content-Disposition` filename when downloading message resources (#536)
+- **drive**: Add `+apply-permission` to request doc access (#588)
+- Support record share link (#466)
+- **whiteboard**: Add image support to `whiteboard-cli` skill (#553)
+- **cmdutil**: Add `X-Cli-Build` header for CLI build classification (#596)
+
+### Bug Fixes
+
+- **base**: Add default-table follow-up hint to `base-create` (#600)
+- Skip flag-completion registration outside completion path (#598)
+- Add `record-share-link-create` in `SKILL.md` (#597)
+- **mail**: Remove leftover conflict marker in skill docs (#594)
+
+### Documentation
+
+- **drive**: Clarify that comment listing defaults to unresolved comments only (#609)
+- **doc**: Fix `--markdown` examples that teach literal `\n` (#602)
+- **mail**: Remove `get_signatures` from skill reference, exposed via `+signature` instead (#545)
+
+## [v1.0.16] - 2026-04-21
+
+### Features
+
+- **mail**: Support large email attachments (#537)
+- **mail**: Add draft preview URL to draft operations (#438)
+- **doc**: Add pre-write semantic warnings to `docs +update` (#569)
+- **doc**: Add `--selection-with-ellipsis` position flag to `+media-insert` (#335)
+- **calendar**: Support event share link and error details (#583)
+
+### Bug Fixes
+
+- **doc**: Preserve round-trip formatting in `+fetch` output (#469)
+- **docs**: Validate `--selection-by-title` format early (#256)
+- **whiteboard**: Register `+media-upload` shortcut and add whiteboard parent type
+
+### Refactor
+
+- Split `Execute` into `Build` + `Execute` with explicit IO and keychain injection (#371)
+- **auth**: Simplify scope reporting in login flow (#582)
+
+## [v1.0.15] - 2026-04-20
+
+### Features
+
+- **sheets**: Add float image shortcuts (#494)
+- **approval**: Document `remind` and `initiated` methods in skill (#554)
+
+### Bug Fixes
+
+- **base**: Preserve attachment metadata on base uploads (#563)
+- **base**: Fix role view and record default permission on edit (#530)
+- **sheets**: Normalize single-cell range in `+set-style` and `+batch-set-style` (#548)
+- **im**: Cap `basic_batch` user_ids at 10 per API limit (#551)
+- **install**: Refine install wizard messages (#529)
+- **whiteboard**: Deprecate old `lark-whiteboard-cli` skill (#547)
+
+## [v1.0.14] - 2026-04-17
+
+### Features
+
+- **mail**: Add email priority support for compose and read (#538)
+- **mail**: Support scheduled send (#534)
+- **drive**: Support sheet cell comments in `+add-comment` (#518)
+- **doc**: Add `--file-view` flag to `+media-insert` (#419)
+- **base**: Auto grant current user for bot create and copy (#497)
+- **base**: Add identity priority strategy and error handling (#505)
+- **auth**: Improve login scope handling and messages (#523)
+- Add OKR business domain (#522)
+
+### Documentation
+
+- **wiki**: Improve wiki skill docs and add wiki domain template (#512)
+- **task**: Document `custom_fields` and `custom_field_options` API resources and permissions (#524)
+
+### Refactor
+
+- **skills**: Introduce `lark-doc-whiteboard.md` and streamline whiteboard workflow (#502)
+
+## [v1.0.13] - 2026-04-16
+
+### Features
+
+- **im**: Support user access token for file, image, audio, and video upload, aligning upload and send identity with `--as` flag (#474)
+- **drive**: Add `drive +create-folder` shortcut with root-folder fallback and bot-mode auto-grant (#470)
+- **wiki**: Add bot-mode auto-grant support to `wiki +node-create` (#470)
+- **doc**: Default `skip_task_detail` in `docs +fetch` to reduce unnecessary task detail expansion (#471)
+
+### Bug Fixes
+
+- **im**: Preserve original URL filename for uploaded file messages instead of generic `media.ext` names (#514)
+- **whiteboard**: Use atomic overwrite API parameter for `whiteboard +update`, replacing read-then-delete approach (#483)
+
+### Documentation
+
+- **base**: Unify record batch write limit to 200 and enforce serial writes for continuous operations (#499)
+- **base**: Remove redundant reference documentation and command grouping chapters from SKILL.md (#500)
+
+### CI
+
+- Consolidate workflows into layered CI pyramid with single `results` gate (#510)
+
+## [v1.0.12] - 2026-04-15
+
+### Features
+
+- Add guided npm install flow that installs or upgrades the CLI, installs AI skills, and walks through app config and auth login (#464)
+- **mail**: Add email signature support with `+signature`, `--signature-id` compose flags, and draft signature edit operations (#485)
+- **mail**: Return recall hints for sent emails when recall is available (#481)
+- **slides**: Add `+media-upload` and support `@path` image placeholders in `+create --slides` (#450)
+
+### Documentation
+
+- **mail**: Add recipient search guidance to the mail skill workflow (#437)
+- **calendar/vc**: Route past meeting queries to `lark-vc` and clarify historical date matching in skills (#482, #480)
+
+## [v1.0.11] - 2026-04-14
+
+### Features
+
+- **sheets**: Add dropdown shortcuts for data validation management (`+set-dropdown`, `+update-dropdown`, `+get-dropdown`, `+delete-dropdown`) (#461)
+- **task**: Add task search, tasklist search, related-task, set-ancestor, and subscribe-event shortcuts (#377)
+- Streamline interactive login by removing the extra auth confirmation step (#451)
+
+### Bug Fixes
+
+- **base**: Validate JSON object inputs for base shortcuts and reject `null` objects (#458)
+
+### Documentation
+
+- **sheets**: Document value formats for formulas and special field types (#456)
+- **readme**: Add Attendance to the features table (#460)
+
+## [v1.0.10] - 2026-04-13
+
+### Features
+
+- **im**: Support im oapi range download for large files (#283)
+- **sheets**: Add filter view and condition shortcuts (#422)
+- **wiki**: Add wiki move shortcut with async task polling (#436)
+- **drive**: Add drive `+create-shortcut` shortcut (#432)
+- **drive**: Add drive files patch metadata API (#444)
+- **task**: Support `--section-guid` flag in tasklist-task-add shortcut (#430)
+
+### Bug Fixes
+
+- **base**: Support large base attachment uploads (#441)
+- **config**: Clarify init copy for TTY, preserve original for AI (#448)
+- **im**: Reject `--user-id` under bot identity for chat-messages-list (#340)
+- **mail**: Add missing scopes for mail `+watch` shortcut (#357)
+- **mail**: Restrict `--output-dir` to current working directory (#376)
+
+### Documentation
+
+- **wiki**: Add wiki member operations to lark-wiki skill (#417)
+- **task**: Document sections API resources, permissions, and URL parsing (#430)
+- **doc**: Clarify when markdown escaping is needed (#312)
+
 ## [v1.0.9] - 2026-04-11
 
 ### Features
@@ -303,6 +488,15 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.18]: https://github.com/larksuite/cli/releases/tag/v1.0.18
+[v1.0.17]: https://github.com/larksuite/cli/releases/tag/v1.0.17
+[v1.0.16]: https://github.com/larksuite/cli/releases/tag/v1.0.16
+[v1.0.15]: https://github.com/larksuite/cli/releases/tag/v1.0.15
+[v1.0.14]: https://github.com/larksuite/cli/releases/tag/v1.0.14
+[v1.0.13]: https://github.com/larksuite/cli/releases/tag/v1.0.13
+[v1.0.12]: https://github.com/larksuite/cli/releases/tag/v1.0.12
+[v1.0.11]: https://github.com/larksuite/cli/releases/tag/v1.0.11
+[v1.0.10]: https://github.com/larksuite/cli/releases/tag/v1.0.10
 [v1.0.9]: https://github.com/larksuite/cli/releases/tag/v1.0.9
 [v1.0.8]: https://github.com/larksuite/cli/releases/tag/v1.0.8
 [v1.0.7]: https://github.com/larksuite/cli/releases/tag/v1.0.7

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, and more, with 200+ commands and 21 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, and more, with 200+ commands and 22 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** — 21 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
-- **Wide Coverage** — 13 business domains, 200+ curated commands, 21 AI Agent [Skills](./skills/)
+- **Agent-Native Design** — 22 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
+- **Wide Coverage** — 14 business domains, 200+ curated commands, 22 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
@@ -30,13 +30,15 @@ The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by t
 | 📁 Drive      | Upload and download files, search docs & wiki, manage comments                                                                    |
 | 📊 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                                             |
+| 🖼️ Slides     | Create and manage presentations, read presentation content, and add or remove slides                                              |
 | ✅ Tasks      | Create, query, update, and complete tasks; manage task lists, subtasks, comments & reminders                                      |
 | 📚 Wiki       | Create and manage knowledge spaces, nodes, and documents                                                                          |
 | 👤 Contact    | Search users by name/email/phone, get user profiles                                                                               |
 | 📧 Mail       | Browse, search, read emails, send, reply, forward, manage drafts, watch new mail                                                  |
 | 🎥 Meetings   | Search meeting records, query meeting minutes & recordings                                                                        |
+| 🕐 Attendance | Query personal attendance check-in records                                                                                        |
 | ✍️ Approval   | Query approval tasks, approve/reject/transfer tasks, cancel and CC instances                                                      |
+| 🎯 OKR        | Query, create, update OKRs; manage objective & key results, alignments and indicators.                                            |
 
 ## Installation & Quick Start
 
@@ -149,6 +151,7 @@ lark-cli auth status
 | `lark-minutes`                  | Minutes metadata & AI artifacts (summary, todos, chapters)                                                     |
 | `lark-openapi-explorer`         | Explore underlying APIs from official docs                                                                     |
 | `lark-skill-maker`              | Custom skill creation framework                                                                                |
+| `lark-attendance`               | Query personal attendance check-in records                                                                     |
 | `lark-approval`                 | Query approval tasks, approve/reject/transfer tasks, cancel and CC instances                                   |
 | `lark-workflow-meeting-summary` | Workflow: meeting minutes aggregation & structured report                                                      |
 | `lark-workflow-standup-report`  | Workflow: agenda & todo summary                                                                                |

README.zh.md

@@ -6,14 +6,14 @@
 
 [中文版](./README.zh.md) | [English](./README.md)
 
-飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议等核心业务域，提供 200+ 命令及 21 个 AI Agent [Skills](./skills/)。
+飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议等核心业务域，提供 200+ 命令及 22 个 AI Agent [Skills](./skills/)。
 
 [安装](#安装与快速开始) · [AI Agent Skills](#agent-skills) · [认证](#认证) · [命令](#三层命令调用) · [进阶用法](#进阶用法) · [安全](#安全与风险提示使用前必读) · [贡献](#贡献)
 
 ## 为什么选 lark-cli？
 
-- **为 Agent 原生设计** — 21 个 [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
-- **覆盖面广** — 13 大业务域、200+ 精选命令、21 个 AI Agent [Skills](./skills/)
+- **为 Agent 原生设计** — 22 个 [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
+- **覆盖面广** — 14 大业务域、200+ 精选命令、22 个 AI Agent [Skills](./skills/)
 - **AI 友好调优** — 每条命令经过 Agent 实测验证，提供更友好的参数、智能默认值和结构化输出，大幅提升 Agent 调用成功率
 - **开源零门槛** — MIT 协议，开箱即用，`npm install` 即可使用
 - **三分钟上手** — 一键创建应用、交互式登录授权，从安装到第一次 API 调用只需三步
@@ -36,7 +36,9 @@
 | 👤 通讯录   | 按姓名/邮箱/手机号搜索用户、获取用户信息                      |
 | 📧 邮箱     | 浏览、搜索、阅读邮件，发送、回复、转发邮件，管理草稿，监听新邮件           |
 | 🎥 视频会议 | 搜索会议记录、查询会议纪要与录制                           |
+| 🕐 考勤打卡 | 查询个人考勤打卡记录                                |
 | ✍️ 审批     | 查询审批任务、同意/拒绝/转交审批任务、撤回与抄送审批实例              |
+| 🎯 OKR  | 查询、创建、更新 OKR，管理目标、关键结果、对齐和指标               |
 
 ## 安装与快速开始
 
@@ -150,6 +152,7 @@ lark-cli auth status
 | `lark-minutes`                  | 妙记元数据与 AI 产物（总结、待办、章节）                    |
 | `lark-openapi-explorer`         | 从官方文档探索底层 API                             |
 | `lark-skill-maker`              | 自定义 skill 创建框架                            |
+| `lark-attendance`               | 查询个人考勤打卡记录                                |
 | `lark-approval`                 | 审批任务查询、同意/拒绝/转交审批任务、撤回与抄送审批实例             |
 | `lark-workflow-meeting-summary` | 工作流：会议纪要汇总与结构化报告                          |
 | `lark-workflow-standup-report`  | 工作流：日程待办摘要                                |

cmd/api/api.go

@@ -57,6 +57,10 @@ func normalisePath(raw string) string {
 
 // NewCmdApi creates the api command. If runF is non-nil it is called instead of apiRun (test hook).
 func NewCmdApi(f *cmdutil.Factory, runF func(*APIOptions) error) *cobra.Command {
+	return NewCmdApiWithContext(context.Background(), f, runF)
+}
+
+func NewCmdApiWithContext(ctx context.Context, f *cmdutil.Factory, runF func(*APIOptions) error) *cobra.Command {
 	opts := &APIOptions{Factory: f}
 	var asStr string
 
@@ -79,7 +83,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*APIOptions) error) *cobra.Command
 
 	cmd.Flags().StringVar(&opts.Params, "params", "", "query parameters JSON (supports - for stdin)")
 	cmd.Flags().StringVar(&opts.Data, "data", "", "request body JSON (supports - for stdin)")
-	cmd.Flags().StringVar(&asStr, "as", "auto", "identity type: user | bot | auto (default)")
+	cmdutil.AddAPIIdentityFlag(ctx, cmd, f, &asStr)
 	cmd.Flags().StringVarP(&opts.Output, "output", "o", "", "output file path for binary responses")
 	cmd.Flags().BoolVar(&opts.PageAll, "page-all", false, "automatically paginate through all pages")
 	cmd.Flags().IntVar(&opts.PageSize, "page-size", 0, "page size (0 = use API default)")
@@ -96,10 +100,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*APIOptions) error) *cobra.Command
 		}
 		return nil, cobra.ShellCompDirectiveNoFileComp
 	}
-	_ = cmd.RegisterFlagCompletionFunc("as", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
-		return []string{"user", "bot"}, cobra.ShellCompDirectiveNoFileComp
-	})
-	_ = cmd.RegisterFlagCompletionFunc("format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
 		return []string{"json", "ndjson", "table", "csv"}, cobra.ShellCompDirectiveNoFileComp
 	})
 
@@ -238,12 +239,13 @@ func apiRun(opts *APIOptions) error {
 		return output.MarkRaw(client.WrapDoAPIError(err))
 	}
 	err = client.HandleResponse(resp, client.ResponseOptions{
-		OutputPath: opts.Output,
-		Format:     format,
-		JqExpr:     opts.JqExpr,
-		Out:        out,
-		ErrOut:     f.IOStreams.ErrOut,
-		FileIO:     f.ResolveFileIO(opts.Ctx),
+		OutputPath:  opts.Output,
+		Format:      format,
+		JqExpr:      opts.JqExpr,
+		Out:         out,
+		ErrOut:      f.IOStreams.ErrOut,
+		FileIO:      f.ResolveFileIO(opts.Ctx),
+		CommandPath: opts.Cmd.CommandPath(),
 	})
 	// MarkRaw tells root error handler to skip enrichPermissionError,
 	// preserving the original API error detail (log_id, troubleshooter, etc.).

cmd/api/api_test.go

@@ -180,6 +180,24 @@ func TestApiValidArgsFunction(t *testing.T) {
 	}
 }
 
+func TestNewCmdApi_StrictModeHidesAsFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu, SupportedIdentities: 2,
+	})
+
+	cmd := NewCmdApi(f, nil)
+	flag := cmd.Flags().Lookup("as")
+	if flag == nil {
+		t.Fatal("expected --as flag to be registered")
+	}
+	if !flag.Hidden {
+		t.Fatal("expected --as flag to be hidden in strict mode")
+	}
+	if got := flag.DefValue; got != "bot" {
+		t.Fatalf("default value = %q, want %q", got, "bot")
+	}
+}
+
 func TestApiCmd_PageLimitDefault(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,

cmd/auth/login.go

@@ -72,7 +72,7 @@ browser. Run it in the background and retrieve the verification URL from its out
 	cmd.Flags().BoolVar(&opts.NoWait, "no-wait", false, "initiate device authorization and return immediately; use --device-code to complete")
 	cmd.Flags().StringVar(&opts.DeviceCode, "device-code", "", "poll and complete authorization with a device code from a previous --no-wait call")
 
-	_ = cmd.RegisterFlagCompletionFunc("domain", func(_ *cobra.Command, _ []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	cmdutil.RegisterFlagCompletion(cmd, "domain", func(_ *cobra.Command, _ []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		return completeDomain(toComplete), cobra.ShellCompDirectiveNoFileComp
 	})
 

cmd/auth/login_interactive.go

@@ -184,27 +184,6 @@ func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg) (*i
 	}
 	fmt.Fprintf(ios.ErrOut, msg.SummaryScopes, len(scopes), scopePreview)
 
-	// Phase 2: confirmation
-	var confirmed bool
-	form2 := huh.NewForm(
-		huh.NewGroup(
-			huh.NewConfirm().
-				Title(msg.ConfirmAuth).
-				Value(&confirmed),
-		),
-	).WithTheme(cmdutil.ThemeFeishu())
-
-	if err := form2.Run(); err != nil {
-		if err == huh.ErrUserAborted {
-			return nil, output.ErrBare(1)
-		}
-		return nil, err
-	}
-
-	if !confirmed {
-		return nil, output.ErrBare(1)
-	}
-
 	return &interactiveResult{
 		Domains:    selectedDomains,
 		ScopeLevel: permLevel,

cmd/auth/login_messages.go

@@ -24,11 +24,11 @@ type loginMsg struct {
 	WaitingAuth        string
 	AuthSuccess        string
 	LoginSuccess       string
+	AuthorizedUser     string
 	ScopeMismatch      string
 	ScopeHint          string
 	RequestedScopes    string
 	NewlyGrantedScopes string
-	MissingScopes      string
 	NoScopes           string
 	StatusHint         string
 
@@ -58,13 +58,13 @@ var loginMsgZh = &loginMsg{
 
 	OpenURL:            "在浏览器中打开以下链接进行认证:\n\n",
 	WaitingAuth:        "等待用户授权...",
-	AuthSuccess:        "授权成功，正在获取用户信息...",
-	LoginSuccess:       "登录成功! 用户: %s (%s)",
-	ScopeMismatch:      "授权完成，但以下请求 scopes 未被授予: %s",
+	AuthSuccess:        "已收到授权确认，正在获取用户信息并校验授权结果...",
+	LoginSuccess:       "授权成功! 用户: %s (%s)",
+	AuthorizedUser:     "当前授权账号: %s (%s)",
+	ScopeMismatch:      "授权结果异常: 以下请求 scopes 未被授予: %s",
 	ScopeHint:          "以上结果是本次授权请求用户最终确认后的结果，请勿持续重试；Scopes 未授予的原因是多样的，如 scope 被禁用；具体原因已通过授权页提示用户。可执行 `lark-cli auth status` 查看账号当前已授予的全部 scopes；",
 	RequestedScopes:    "  本次请求 scopes: %s\n",
 	NewlyGrantedScopes: "  本次新授予 scopes: %s\n",
-	MissingScopes:      "  本次未授予 scopes: %s\n",
 	NoScopes:           "（空）",
 	StatusHint:         "可执行 `lark-cli auth status` 查看账号当前已授予的全部 scopes；",
 
@@ -93,13 +93,13 @@ var loginMsgEn = &loginMsg{
 
 	OpenURL:            "Open this URL in your browser to authenticate:\n\n",
 	WaitingAuth:        "Waiting for user authorization...",
-	AuthSuccess:        "Authorization successful, fetching user info...",
-	LoginSuccess:       "Login successful! User: %s (%s)",
-	ScopeMismatch:      "authorization completed, but these requested scopes were not granted: %s",
+	AuthSuccess:        "Authorization confirmed, fetching user info and validating granted scopes...",
+	LoginSuccess:       "Authorization successful! User: %s (%s)",
+	AuthorizedUser:     "Authorized account: %s (%s)",
+	ScopeMismatch:      "authorization result is abnormal: these requested scopes were not granted: %s",
 	ScopeHint:          "The result above is the user's final confirmation for this authorization request. Do not retry continuously. Scopes may be not granted for various reasons, such as a scope being disabled. The specific reason has already been shown to the user on the authorization page. Run `lark-cli auth status` to inspect all scopes currently granted to the account.",
 	RequestedScopes:    "  Requested scopes: %s\n",
 	NewlyGrantedScopes: "  Newly granted scopes: %s\n",
-	MissingScopes:      "  Not granted scopes: %s\n",
 	NoScopes:           "(none)",
 	StatusHint:         "Run `lark-cli auth status` to inspect all scopes currently granted to the account.",
 

cmd/auth/login_messages_test.go

@@ -69,6 +69,12 @@ func TestLoginMsg_FormatStrings(t *testing.T) {
 			t.Errorf("%s LoginSuccess has no format verb", lang)
 		}
 
+		// AuthorizedUser should contain two %s placeholders (userName, openId)
+		got = fmt.Sprintf(msg.AuthorizedUser, "testuser", "ou_123")
+		if got == msg.AuthorizedUser {
+			t.Errorf("%s AuthorizedUser has no format verb", lang)
+		}
+
 		// SummaryDomains should contain %s
 		got = fmt.Sprintf(msg.SummaryDomains, "calendar, task")
 		if got == msg.SummaryDomains {

cmd/auth/login_result.go

@@ -128,7 +128,7 @@ func emptyIfNil(s []string) []string {
 	return s
 }
 
-// writeLoginScopeBreakdown renders the requested/newly granted/missing scope
+// writeLoginScopeBreakdown renders the requested/newly granted scope
 // breakdown to stderr.
 func writeLoginScopeBreakdown(errOut *cmdutil.IOStreams, msg *loginMsg, summary *loginScopeSummary) {
 	if summary == nil {
@@ -136,7 +136,6 @@ func writeLoginScopeBreakdown(errOut *cmdutil.IOStreams, msg *loginMsg, summary
 	}
 	fmt.Fprintf(errOut.ErrOut, msg.RequestedScopes, formatScopeList(summary.Requested, msg.NoScopes))
 	fmt.Fprintf(errOut.ErrOut, msg.NewlyGrantedScopes, formatScopeList(summary.NewlyGranted, msg.NoScopes))
-	fmt.Fprintf(errOut.ErrOut, msg.MissingScopes, formatScopeList(summary.Missing, msg.NoScopes))
 }
 
 // writeLoginSuccess emits the successful login payload in either JSON or text
@@ -190,11 +189,11 @@ func handleLoginScopeIssue(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory
 
 	fmt.Fprintln(f.IOStreams.ErrOut)
 	if loginSucceeded {
-		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf(msg.LoginSuccess, userName, openId))
-	} else {
 		fmt.Fprintln(f.IOStreams.ErrOut, issue.Message)
-	}
-	if loginSucceeded {
+		if msg.AuthorizedUser != "" {
+			fmt.Fprintf(f.IOStreams.ErrOut, "%s\n", fmt.Sprintf(msg.AuthorizedUser, userName, openId))
+		}
+	} else {
 		fmt.Fprintln(f.IOStreams.ErrOut, issue.Message)
 	}
 	writeLoginScopeBreakdown(f.IOStreams, msg, issue.Summary)

cmd/auth/login_test.go

@@ -363,7 +363,7 @@ func TestWriteLoginSuccess_JSONIncludesScopeDiff(t *testing.T) {
 func TestHandleLoginScopeIssue_NonJSONAlignsWithLoginSuccess(t *testing.T) {
 	f, _, stderr, _ := cmdutil.TestFactory(t, nil)
 	err := handleLoginScopeIssue(&LoginOptions{}, getLoginMsg("zh"), f, &loginScopeIssue{
-		Message: "授权完成，但以下请求 scopes 未被授予: im:message:send",
+		Message: "授权结果异常: 以下请求 scopes 未被授予: im:message:send",
 		Hint:    "以上结果是本次授权请求用户最终确认后的结果，请勿持续重试；Scopes 未授予的原因是多样的，如 scope 被禁用；具体原因已通过授权页提示用户。可执行 `lark-cli auth status` 查看账号当前已授予的全部 scopes；",
 		Summary: &loginScopeSummary{
 			Requested: []string{"im:message:send"},
@@ -376,11 +376,10 @@ func TestHandleLoginScopeIssue_NonJSONAlignsWithLoginSuccess(t *testing.T) {
 	}
 	got := stderr.String()
 	for _, want := range []string{
-		"OK: 登录成功! 用户: tester (ou_user)",
-		"授权完成，但以下请求 scopes 未被授予: im:message:send",
+		"授权结果异常: 以下请求 scopes 未被授予: im:message:send",
+		"当前授权账号: tester (ou_user)",
 		"本次请求 scopes: im:message:send",
 		"本次新授予 scopes: （空）",
-		"本次未授予 scopes: im:message:send",
 		"以上结果是本次授权请求用户最终确认后的结果，请勿持续重试",
 		"scope 被禁用",
 		"lark-cli auth status",
@@ -392,15 +391,18 @@ func TestHandleLoginScopeIssue_NonJSONAlignsWithLoginSuccess(t *testing.T) {
 	if strings.Contains(got, "最终已授权 scopes:") {
 		t.Fatalf("stderr should not contain final granted scopes, got:\n%s", got)
 	}
-	if strings.Contains(got, "ERROR:") {
-		t.Fatalf("stderr should not contain error prefix, got:\n%s", got)
+	if strings.Contains(got, "授权成功") {
+		t.Fatalf("stderr should not contain success wording, got:\n%s", got)
+	}
+	if strings.Contains(got, "本次未授予 scopes:") {
+		t.Fatalf("stderr should not duplicate missing scopes, got:\n%s", got)
 	}
 }
 
 func TestHandleLoginScopeIssue_JSONAlignsWithLoginSuccess(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
 	err := handleLoginScopeIssue(&LoginOptions{JSON: true}, getLoginMsg("en"), f, &loginScopeIssue{
-		Message: "authorization completed, but these requested scopes were not granted: im:message:send",
+		Message: "authorization result is abnormal: these requested scopes were not granted: im:message:send",
 		Hint:    "Granted scopes: base:app:copy. Check app scopes.",
 		Summary: &loginScopeSummary{
 			Requested: []string{"im:message:send"},
@@ -469,13 +471,13 @@ func TestWriteLoginSuccess_TextOutputScenarios(t *testing.T) {
 				Granted:        []string{"im:message:send", "im:message:reply"},
 			},
 			expectedPresent: []string{
-				"登录成功! 用户: tester (ou_user)",
+				"授权成功! 用户: tester (ou_user)",
 				"本次请求 scopes: im:message:send im:message:reply",
 				"本次新授予 scopes: im:message:send",
-				"本次未授予 scopes: （空）",
 				"可执行 `lark-cli auth status` 查看账号当前已授予的全部 scopes；",
 			},
 			expectedAbsent: []string{
+				"本次未授予 scopes:",
 				"最终已授权 scopes:",
 				"已有 scopes:",
 			},
@@ -490,10 +492,10 @@ func TestWriteLoginSuccess_TextOutputScenarios(t *testing.T) {
 			expectedPresent: []string{
 				"本次请求 scopes: im:message:send",
 				"本次新授予 scopes: （空）",
-				"本次未授予 scopes: （空）",
 				"可执行 `lark-cli auth status` 查看账号当前已授予的全部 scopes；",
 			},
 			expectedAbsent: []string{
+				"本次未授予 scopes:",
 				"最终已授权 scopes:",
 				"已有 scopes:",
 			},
@@ -508,9 +510,9 @@ func TestWriteLoginSuccess_TextOutputScenarios(t *testing.T) {
 			expectedPresent: []string{
 				"本次请求 scopes: im:message:send im:message:reply",
 				"本次新授予 scopes: （空）",
-				"本次未授予 scopes: im:message:send",
 			},
 			expectedAbsent: []string{
+				"本次未授予 scopes:",
 				"已有 scopes:",
 				"最终已授权 scopes:",
 				"可执行 `lark-cli auth status` 查看账号当前已授予的全部 scopes；",
@@ -619,10 +621,9 @@ func TestAuthLoginRun_MissingRequestedScopeAlignsWithLoginSuccess(t *testing.T)
 	}
 	got := stderr.String()
 	for _, want := range []string{
-		"OK: 登录成功! 用户: tester (ou_user)",
-		"授权完成，但以下请求 scopes 未被授予: im:message:send",
+		"授权结果异常: 以下请求 scopes 未被授予: im:message:send",
+		"当前授权账号: tester (ou_user)",
 		"本次请求 scopes: im:message:send",
-		"本次未授予 scopes: im:message:send",
 		"以上结果是本次授权请求用户最终确认后的结果，请勿持续重试",
 		"scope 被禁用",
 		"lark-cli auth status",
@@ -634,6 +635,12 @@ func TestAuthLoginRun_MissingRequestedScopeAlignsWithLoginSuccess(t *testing.T)
 	if strings.Contains(got, "最终已授权 scopes:") {
 		t.Fatalf("stderr should not contain final granted scopes, got:\n%s", got)
 	}
+	if strings.Contains(got, "OK: 授权成功") {
+		t.Fatalf("stderr should not contain success prefix when scopes are missing, got:\n%s", got)
+	}
+	if strings.Contains(got, "本次未授予 scopes:") {
+		t.Fatalf("stderr should not duplicate missing scopes, got:\n%s", got)
+	}
 	if strings.Contains(got, "ERROR:") {
 		t.Fatalf("stderr should not contain error prefix, got:\n%s", got)
 	}
@@ -743,7 +750,7 @@ func TestAuthLoginRun_DeviceCodeUsesCachedRequestedScopes(t *testing.T) {
 	}
 	got := stderr.String()
 	for _, want := range []string{
-		"OK: 登录成功! 用户: tester (ou_user)",
+		"OK: 授权成功! 用户: tester (ou_user)",
 		"本次请求 scopes: im:message:send",
 		"本次新授予 scopes: im:message:send",
 		"可执行 `lark-cli auth status` 查看账号当前已授予的全部 scopes；",
@@ -771,16 +778,18 @@ func TestWriteLoginSuccess_TextOutputEnglishIncludesStatusHintWhenNoMissingScope
 
 	got := stderr.String()
 	for _, want := range []string{
-		"Login successful! User: tester (ou_user)",
+		"Authorization successful! User: tester (ou_user)",
 		"Requested scopes: im:message:send",
 		"Newly granted scopes: im:message:send",
-		"Not granted scopes: (none)",
 		"Run `lark-cli auth status` to inspect all scopes currently granted to the account.",
 	} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("stderr missing %q, got:\n%s", want, got)
 		}
 	}
+	if strings.Contains(got, "Not granted scopes:") {
+		t.Fatalf("stderr should not contain not granted scopes, got:\n%s", got)
+	}
 }
 
 func TestAuthLoginRun_DeviceCodeTokenNilCleansScopeCache(t *testing.T) {

cmd/build.go

@@ -0,0 +1,129 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"context"
+	"io"
+
+	"github.com/larksuite/cli/cmd/api"
+	"github.com/larksuite/cli/cmd/auth"
+	"github.com/larksuite/cli/cmd/completion"
+	cmdconfig "github.com/larksuite/cli/cmd/config"
+	"github.com/larksuite/cli/cmd/doctor"
+	"github.com/larksuite/cli/cmd/profile"
+	"github.com/larksuite/cli/cmd/schema"
+	"github.com/larksuite/cli/cmd/service"
+	cmdupdate "github.com/larksuite/cli/cmd/update"
+	"github.com/larksuite/cli/internal/build"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/keychain"
+	"github.com/larksuite/cli/shortcuts"
+	"github.com/spf13/cobra"
+)
+
+// BuildOption configures optional aspects of the command tree construction.
+type BuildOption func(*buildConfig)
+
+type buildConfig struct {
+	streams  *cmdutil.IOStreams
+	keychain keychain.KeychainAccess
+	globals  GlobalOptions
+}
+
+// WithIO sets the IO streams for the CLI by wrapping raw reader/writers.
+// Terminal detection is delegated to cmdutil.NewIOStreams.
+func WithIO(in io.Reader, out, errOut io.Writer) BuildOption {
+	return func(c *buildConfig) {
+		c.streams = cmdutil.NewIOStreams(in, out, errOut)
+	}
+}
+
+// WithKeychain sets the secret storage backend. If not provided, the platform keychain is used.
+func WithKeychain(kc keychain.KeychainAccess) BuildOption {
+	return func(c *buildConfig) {
+		c.keychain = kc
+	}
+}
+
+// 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
+// HideProfile(isSingleAppMode()).
+func HideProfile(hide bool) BuildOption {
+	return func(c *buildConfig) {
+		c.globals.HideProfile = hide
+	}
+}
+
+// Build constructs the full command tree without executing.
+// Returns only the cobra.Command; Factory is internal.
+// Use Execute for the standard production entry point.
+func Build(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOption) *cobra.Command {
+	_, rootCmd := buildInternal(ctx, inv, opts...)
+	return rootCmd
+}
+
+// buildInternal is a pure assembly function: it wires the command tree from
+// inv and BuildOptions alone. Any state-dependent decision (disk, network,
+// env) belongs in the caller and must be threaded in via BuildOption.
+func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOption) (*cmdutil.Factory, *cobra.Command) {
+	// cfg.globals.Profile is left zero here; it's bound to the --profile
+	// flag in RegisterGlobalFlags and filled by cobra's parse step.
+	cfg := &buildConfig{}
+	for _, o := range opts {
+		if o != nil {
+			o(cfg)
+		}
+	}
+	// Default streams when WithIO is not supplied so the root command's
+	// SetIn/Out/Err calls below don't deref nil. NewDefault also normalizes
+	// partial streams internally; keep both in sync so cfg.streams reflects
+	// the same values the Factory ends up using.
+	if cfg.streams == nil {
+		cfg.streams = cmdutil.SystemIO()
+	}
+
+	f := cmdutil.NewDefault(cfg.streams, inv)
+	if cfg.keychain != nil {
+		f.Keychain = cfg.keychain
+	}
+	rootCmd := &cobra.Command{
+		Use:     "lark-cli",
+		Short:   "Lark/Feishu CLI — OAuth authorization, UAT management, API calls",
+		Long:    rootLong,
+		Version: build.Version,
+	}
+
+	rootCmd.SetContext(ctx)
+	rootCmd.SetIn(cfg.streams.In)
+	rootCmd.SetOut(cfg.streams.Out)
+	rootCmd.SetErr(cfg.streams.ErrOut)
+
+	installTipsHelpFunc(rootCmd)
+	rootCmd.SilenceErrors = true
+
+	RegisterGlobalFlags(rootCmd.PersistentFlags(), &cfg.globals)
+	rootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) {
+		cmd.SilenceUsage = true
+	}
+
+	rootCmd.AddCommand(cmdconfig.NewCmdConfig(f))
+	rootCmd.AddCommand(auth.NewCmdAuth(f))
+	rootCmd.AddCommand(profile.NewCmdProfile(f))
+	rootCmd.AddCommand(doctor.NewCmdDoctor(f))
+	rootCmd.AddCommand(api.NewCmdApiWithContext(ctx, f, nil))
+	rootCmd.AddCommand(schema.NewCmdSchema(f, nil))
+	rootCmd.AddCommand(completion.NewCmdCompletion(f))
+	rootCmd.AddCommand(cmdupdate.NewCmdUpdate(f))
+	service.RegisterServiceCommandsWithContext(ctx, rootCmd, f)
+	shortcuts.RegisterShortcutsWithContext(ctx, rootCmd, f)
+
+	// Prune commands incompatible with strict mode.
+	if mode := f.ResolveStrictMode(ctx); mode.IsActive() {
+		pruneForStrictMode(rootCmd, mode)
+	}
+
+	return f, rootCmd
+}

cmd/build_api_test.go

@@ -0,0 +1,63 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"bytes"
+	"context"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// noopKeychain is a zero-side-effect KeychainAccess for exercising
+// WithKeychain without touching the platform keychain.
+type noopKeychain struct{}
+
+func (noopKeychain) Get(service, account string) (string, error) { return "", nil }
+func (noopKeychain) Set(service, account, value string) error    { return nil }
+func (noopKeychain) Remove(service, account string) error        { return nil }
+
+// TestBuild_ExternalAPI asserts the library surface that external consumers
+// (e.g. cli-server) depend on: Build composes a root command from an
+// InvocationContext plus BuildOptions (WithIO, WithKeychain, HideProfile),
+// and SetDefaultFS swaps the global VFS. This test is the contract guard.
+func TestBuild_ExternalAPI(t *testing.T) {
+	// Exercise SetDefaultFS both directions. Passing nil restores the OS FS.
+	SetDefaultFS(vfs.OsFs{})
+	SetDefaultFS(nil)
+
+	var in, out, errOut bytes.Buffer
+	rootCmd := Build(
+		context.Background(),
+		cmdutil.InvocationContext{},
+		WithIO(&in, &out, &errOut),
+		WithKeychain(noopKeychain{}),
+		HideProfile(true),
+	)
+
+	if rootCmd == nil {
+		t.Fatal("Build returned nil root command")
+	}
+	if rootCmd.Use != "lark-cli" {
+		t.Errorf("rootCmd.Use = %q, want %q", rootCmd.Use, "lark-cli")
+	}
+	if len(rootCmd.Commands()) == 0 {
+		t.Error("Build produced a root command with no subcommands")
+	}
+}
+
+// TestBuild_NoOptions guards against regression of the nil-streams panic:
+// calling Build without WithIO must fall back to SystemIO rather than
+// deref nil at rootCmd.SetIn/Out/Err.
+func TestBuild_NoOptions(t *testing.T) {
+	rootCmd := Build(context.Background(), cmdutil.InvocationContext{})
+	if rootCmd == nil {
+		t.Fatal("Build returned nil root command")
+	}
+	if rootCmd.Use != "lark-cli" {
+		t.Errorf("rootCmd.Use = %q, want %q", rootCmd.Use, "lark-cli")
+	}
+}

cmd/config/bind.go

@@ -0,0 +1,586 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/charmbracelet/huh"
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keychain"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// BindOptions holds all inputs for config bind.
+type BindOptions struct {
+	Factory *cmdutil.Factory
+	Source  string
+	AppID   string
+	// Identity selects one of two presets — "bot-only" or "user-default" —
+	// that expand to underlying StrictMode + DefaultAs in applyPreferences.
+	// Empty means "decide later": TUI prompts, flag mode defaults to bot-only
+	// (the safer choice — bot acts under its own identity, no impersonation
+	// risk; users can still opt into "user-default" via --identity).
+	Identity string
+
+	// Force opts in to an otherwise-blocked flag-mode transition — currently
+	// only the bot-only → user-default identity escalation. TUI mode ignores
+	// this flag because its own prompts already require human confirmation.
+	Force bool
+
+	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
+	// that run before that (source / account selection) render brand-aware
+	// text with an empty value, which brandDisplay falls back to Feishu.
+	Brand string
+
+	// IsTUI is the resolved interactive-mode flag: true only when Source is
+	// empty and stdin is a terminal. Computed once at the top of
+	// configBindRun; downstream branches read this instead of rechecking
+	// IOStreams.IsTerminal. Do not set from outside — it is overwritten.
+	IsTUI bool
+}
+
+// NewCmdConfigBind creates the config bind subcommand.
+func NewCmdConfigBind(f *cmdutil.Factory, runF func(*BindOptions) error) *cobra.Command {
+	opts := &BindOptions{Factory: f}
+
+	cmd := &cobra.Command{
+		Use:   "bind",
+		Short: "Bind Agent config to a workspace (source / app-id / force)",
+		Long: `Bind an AI Agent's (OpenClaw / Hermes) Feishu credentials to a lark-cli workspace.
+
+For AI agents: pass --source and --app-id to bind non-interactively.
+Credentials are synced once; subsequent calls in the Agent's process
+context automatically use the bound workspace.`,
+		Example: `  lark-cli config bind --source openclaw --app-id <id>
+  lark-cli config bind --source hermes`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts.langExplicit = cmd.Flags().Changed("lang")
+			if runF != nil {
+				return runF(opts)
+			}
+			return configBindRun(opts)
+		},
+	}
+
+	cmd.Flags().StringVar(&opts.Source, "source", "", "Agent source to bind from (openclaw|hermes); auto-detected from env signals when omitted")
+	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", "zh", "language for interactive prompts (zh|en)")
+
+	return cmd
+}
+
+// configBindRun is the top-level orchestrator. Each step delegates to a named
+// helper whose signature declares its contract; the body reads as the shape of
+// the bind flow itself, not its mechanics.
+func configBindRun(opts *BindOptions) error {
+	if err := validateBindFlags(opts); err != nil {
+		return err
+	}
+
+	// Decide TUI-vs-flag mode exactly once; every downstream branch reads
+	// opts.IsTUI instead of re-checking IOStreams.IsTerminal.
+	opts.IsTUI = opts.Source == "" && opts.Factory.IOStreams.IsTerminal
+
+	source, err := finalizeSource(opts)
+	if err != nil {
+		return err
+	}
+	core.SetCurrentWorkspace(core.Workspace(source))
+	targetConfigPath := core.GetConfigPath()
+
+	existing, err := reconcileExistingBinding(opts, source, targetConfigPath)
+	if err != nil {
+		return err
+	}
+	if existing.Cancelled {
+		return nil
+	}
+
+	appConfig, err := resolveAccount(opts, source)
+	if err != nil {
+		return err
+	}
+	opts.Brand = string(appConfig.Brand)
+
+	if err := resolveIdentity(opts); err != nil {
+		return err
+	}
+	if err := warnIdentityEscalation(opts, existing.ConfigBytes); err != nil {
+		return err
+	}
+	applyPreferences(appConfig, opts)
+
+	return commitBinding(opts, appConfig, existing.ConfigBytes, source, targetConfigPath)
+}
+
+// existingBinding is the outcome of checking whether a workspace was already
+// bound. ConfigBytes is non-nil iff a previous binding existed (and the caller
+// should pass it to commitBinding for stale-keychain cleanup after the new
+// config is durably written). Cancelled is true iff the user declined to
+// replace it in the TUI prompt; the caller should exit cleanly.
+type existingBinding struct {
+	ConfigBytes []byte
+	Cancelled   bool
+}
+
+// finalizeSource returns the validated bind source, reconciling three inputs:
+//   - opts.Source: the value of --source (may be empty)
+//   - env signals: OPENCLAW_* / HERMES_* detected via DetectWorkspaceFromEnv
+//   - TUI mode: can prompt the user if neither flag nor env yields a source
+//
+// Resolution (in order):
+//  1. If --source is a non-empty invalid value → fail with ErrValidation.
+//  2. If both --source and an env signal are present and disagree → fail
+//     loud; the user almost certainly ran the command in the wrong context.
+//  3. TUI mode only: prompt for language first (so later prompts respect it).
+//  4. --source wins if set. Otherwise use the env-detected source. Otherwise
+//     fall back to a TUI prompt (TUI mode) or an error (flag mode).
+func finalizeSource(opts *BindOptions) (string, error) {
+	explicit := strings.TrimSpace(strings.ToLower(opts.Source))
+	if explicit != "" && explicit != "openclaw" && explicit != "hermes" {
+		return "", output.ErrValidation("invalid --source %q; valid values: openclaw, hermes", explicit)
+	}
+
+	var detected string
+	switch core.DetectWorkspaceFromEnv(os.Getenv) {
+	case core.WorkspaceOpenClaw:
+		detected = "openclaw"
+	case core.WorkspaceHermes:
+		detected = "hermes"
+	}
+
+	// Explicit and env detection must agree when both are present. Reject
+	// before any interactive prompts — running inside Hermes with
+	// --source openclaw (or vice versa) is almost always a mistake.
+	if explicit != "" && detected != "" && explicit != detected {
+		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.
+	if opts.IsTUI && !opts.langExplicit {
+		lang, err := promptLangSelection("")
+		if err != nil {
+			if err == huh.ErrUserAborted {
+				return "", output.ErrBare(1)
+			}
+			return "", err
+		}
+		opts.Lang = lang
+	}
+
+	if explicit != "" {
+		return explicit, nil
+	}
+	if detected != "" {
+		return detected, nil
+	}
+	if opts.IsTUI {
+		return tuiSelectSource(opts)
+	}
+	return "", output.ErrWithHint(output.ExitValidation, "bind",
+		"cannot determine Agent source: no --source flag and no Agent environment detected",
+		"pass --source openclaw|hermes, or run this command inside an OpenClaw or Hermes chat")
+}
+
+// reconcileExistingBinding reads any existing config at configPath and decides
+// how to proceed. In TUI mode the user is prompted to keep or replace. In flag
+// mode the existing binding is silently overwritten — commitBinding will emit a
+// notice on success so the caller still sees that a rebind happened.
+// See existingBinding for the returned fields.
+func reconcileExistingBinding(opts *BindOptions, source, configPath string) (existingBinding, error) {
+	oldConfigData, _ := vfs.ReadFile(configPath)
+	if oldConfigData == nil {
+		return existingBinding{}, nil
+	}
+
+	if opts.IsTUI {
+		action, err := tuiConflictPrompt(opts, source, configPath)
+		if err != nil {
+			return existingBinding{}, err
+		}
+		if action == "cancel" {
+			msg := getBindMsg(opts.Lang)
+			fmt.Fprintln(opts.Factory.IOStreams.ErrOut, msg.ConflictCancelled)
+			return existingBinding{Cancelled: true}, nil
+		}
+		return existingBinding{ConfigBytes: oldConfigData}, nil
+	}
+
+	return existingBinding{ConfigBytes: oldConfigData}, nil
+}
+
+// resolveAccount runs the source-agnostic bind flow: construct the binder,
+// enumerate candidates, pick one via the shared decision layer, and build a
+// ready-to-persist AppConfig. Adding a new bind source only requires
+// implementing SourceBinder — none of the logic below needs to change.
+func resolveAccount(opts *BindOptions, source string) (*core.AppConfig, error) {
+	binder, err := newBinder(source, opts)
+	if err != nil {
+		return nil, err
+	}
+	candidates, err := binder.ListCandidates()
+	if err != nil {
+		return nil, err
+	}
+	picked, err := selectCandidate(binder, candidates, opts.AppID, opts.IsTUI,
+		func(cs []Candidate) (*Candidate, error) { return tuiSelectApp(opts, source, cs) })
+	if err != nil {
+		return nil, err
+	}
+	return binder.Build(picked.AppID)
+}
+
+// resolveIdentity ensures opts.Identity is set before applyPreferences runs.
+// TUI mode prompts when empty; flag mode defaults to "bot-only" — the safer
+// preset (bot acts under its own identity, no impersonation). Users who
+// want the broader capability set can pass --identity user-default.
+func resolveIdentity(opts *BindOptions) error {
+	if opts.Identity != "" {
+		return nil
+	}
+	if opts.IsTUI {
+		id, err := tuiSelectIdentity(opts)
+		if err != nil {
+			return err
+		}
+		opts.Identity = id
+		return nil
+	}
+	opts.Identity = "bot-only"
+	return nil
+}
+
+// hasStrictBotLock reports whether the given config bytes declare a
+// bot-only lock on at least one app. Unparseable input returns false — it
+// signals "no enforceable lock to honor", consistent with how the rest of
+// the bind flow treats a corrupt previous config (commitBinding will
+// overwrite it cleanly).
+func hasStrictBotLock(data []byte) bool {
+	var multi core.MultiAppConfig
+	if err := json.Unmarshal(data, &multi); err != nil {
+		return false
+	}
+	for _, app := range multi.Apps {
+		if app.StrictMode != nil && *app.StrictMode == core.StrictModeBot {
+			return true
+		}
+	}
+	return false
+}
+
+// warnIdentityEscalation surfaces the risk of a flag-mode bot-only →
+// user-default identity change. Without --force, the CLI refuses so an AI
+// Agent has to relay the warning to the user and get explicit opt-in before
+// retrying. TUI mode is exempt: tuiConflictPrompt + tuiSelectIdentity
+// already require human confirmation in-flow.
+func warnIdentityEscalation(opts *BindOptions, previousConfigBytes []byte) error {
+	if opts.IsTUI || opts.Force || previousConfigBytes == nil {
+		return nil
+	}
+	if opts.Identity != "user-default" {
+		return nil
+	}
+	if !hasStrictBotLock(previousConfigBytes) {
+		return nil
+	}
+	msg := getBindMsg(opts.Lang)
+	return output.ErrWithHint(output.ExitValidation, "bind",
+		msg.IdentityEscalationMessage, msg.IdentityEscalationHint)
+}
+
+// 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.
+func applyPreferences(appConfig *core.AppConfig, opts *BindOptions) {
+	switch opts.Identity {
+	case "bot-only":
+		sm := core.StrictModeBot
+		appConfig.StrictMode = &sm
+		appConfig.DefaultAs = core.AsBot
+	case "user-default":
+		sm := core.StrictModeOff
+		appConfig.StrictMode = &sm
+		appConfig.DefaultAs = core.AsUser
+	}
+	if opts.Lang != "" {
+		appConfig.Lang = opts.Lang
+	}
+}
+
+// commitBinding finalizes the bind: atomic write of the new workspace config,
+// best-effort cleanup of stale keychain entries from the previous binding (if
+// any), and a JSON success envelope. Cleanup runs only after the new config
+// is durably written — if anything fails earlier, the old workspace stays
+// usable.
+func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigBytes []byte, source, configPath string) error {
+	multi := &core.MultiAppConfig{Apps: []core.AppConfig{*appConfig}}
+
+	if err := vfs.MkdirAll(core.GetConfigDir(), 0700); err != nil {
+		return output.Errorf(output.ExitInternal, "bind",
+			"failed to create workspace directory: %v", err)
+	}
+	data, err := json.MarshalIndent(multi, "", "  ")
+	if err != nil {
+		return output.Errorf(output.ExitInternal, "bind",
+			"failed to marshal config: %v", err)
+	}
+	if err := validate.AtomicWrite(configPath, append(data, '\n'), 0600); err != nil {
+		return output.Errorf(output.ExitInternal, "bind",
+			"failed to write config %s: %v", configPath, err)
+	}
+
+	replaced := previousConfigBytes != nil
+	msg := getBindMsg(opts.Lang)
+	display := sourceDisplayName(source)
+
+	if replaced {
+		cleanupKeychainFromData(opts.Factory.Keychain, previousConfigBytes, appConfig)
+	}
+
+	fmt.Fprintln(opts.Factory.IOStreams.ErrOut,
+		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
+	// noise. Flag mode (Agent orchestration, scripts, piped output) still
+	// gets the full envelope for programmatic consumption.
+	if opts.IsTUI {
+		return nil
+	}
+
+	envelope := map[string]interface{}{
+		"ok":          true,
+		"workspace":   source,
+		"app_id":      appConfig.AppId,
+		"config_path": configPath,
+		"replaced":    replaced,
+		"identity":    opts.Identity,
+	}
+	brand := brandDisplay(string(appConfig.Brand), opts.Lang)
+	switch opts.Identity {
+	case "bot-only":
+		envelope["message"] = fmt.Sprintf(msg.MessageBotOnly, appConfig.AppId, display, brand)
+	case "user-default":
+		envelope["message"] = fmt.Sprintf(msg.MessageUserDefault, appConfig.AppId, display, display)
+	}
+
+	resultJSON, _ := json.Marshal(envelope)
+	fmt.Fprintln(opts.Factory.IOStreams.Out, string(resultJSON))
+	return nil
+}
+
+// cleanupKeychainFromData removes keychain entries referenced by a previous
+// config snapshot, skipping any entry whose keychain ID is still in use by
+// the new app config. This prevents rebinding the same appId from deleting
+// the secret that ForStorage just wrote (old and new secret share the same
+// keychain key, derived from appId). Best-effort: errors are silently
+// ignored (same contract as config init's cleanup).
+func cleanupKeychainFromData(kc keychain.KeychainAccess, data []byte, keep *core.AppConfig) {
+	var multi core.MultiAppConfig
+	if err := json.Unmarshal(data, &multi); err != nil {
+		return
+	}
+	keepID := ""
+	if keep != nil && keep.AppSecret.Ref != nil && keep.AppSecret.Ref.Source == "keychain" {
+		keepID = keep.AppSecret.Ref.ID
+	}
+	for _, app := range multi.Apps {
+		if keepID != "" && app.AppSecret.Ref != nil && app.AppSecret.Ref.Source == "keychain" && app.AppSecret.Ref.ID == keepID {
+			continue
+		}
+		core.RemoveSecretStore(app.AppSecret, kc)
+	}
+}
+
+// ──────────────────────────────────────────────────────────────
+// TUI helpers (huh forms, matching config init interactive style)
+// ──────────────────────────────────────────────────────────────
+
+// tuiSelectSource prompts user to choose bind source.
+func tuiSelectSource(opts *BindOptions) (string, error) {
+	msg := getBindMsg(opts.Lang)
+	var source string
+
+	// Pre-select based on detected env signals
+	detected := core.DetectWorkspaceFromEnv(os.Getenv)
+	switch detected {
+	case core.WorkspaceOpenClaw:
+		source = "openclaw"
+	case core.WorkspaceHermes:
+		source = "hermes"
+	default:
+		source = "openclaw" // default first option
+	}
+
+	// Resolve actual paths for display
+	openclawPath := resolveOpenClawConfigPath()
+	hermesEnvPath := resolveHermesEnvPath()
+
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewSelect[string]().
+				Title(msg.SelectSource).
+				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"),
+				).
+				Value(&source),
+		),
+	).WithTheme(cmdutil.ThemeFeishu())
+
+	if err := form.Run(); err != nil {
+		if err == huh.ErrUserAborted {
+			return "", output.ErrBare(1)
+		}
+		return "", err
+	}
+	return source, nil
+}
+
+// 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.Lang)
+	options := make([]huh.Option[int], 0, len(candidates))
+	for i, c := range candidates {
+		label := c.AppID
+		if c.Label != "" {
+			label = fmt.Sprintf("%s (%s)", c.Label, c.AppID)
+		}
+		options = append(options, huh.NewOption(label, i))
+	}
+
+	var selected int
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewSelect[int]().
+				Title(fmt.Sprintf(msg.SelectAccount, sourceDisplayName(source), brandDisplay(opts.Brand, opts.Lang))).
+				Options(options...).
+				Value(&selected),
+		),
+	).WithTheme(cmdutil.ThemeFeishu())
+
+	if err := form.Run(); err != nil {
+		if err == huh.ErrUserAborted {
+			return nil, output.ErrBare(1)
+		}
+		return nil, err
+	}
+	return &candidates[selected], nil
+}
+
+// tuiConflictPrompt shows existing binding and asks user to Force or Cancel.
+func tuiConflictPrompt(opts *BindOptions, source, configPath string) (string, error) {
+	msg := getBindMsg(opts.Lang)
+
+	// Build existing binding summary
+	existingSummary := fmt.Sprintf(msg.ConflictDesc, source, "?", "?", configPath)
+	if data, err := vfs.ReadFile(configPath); err == nil {
+		var multi core.MultiAppConfig
+		if json.Unmarshal(data, &multi) == nil && len(multi.Apps) > 0 {
+			app := multi.Apps[0]
+			existingSummary = fmt.Sprintf(msg.ConflictDesc,
+				source, app.AppId, app.Brand, configPath)
+		}
+	}
+
+	var action string
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewNote().
+				Title(msg.ConflictTitle).
+				Description(existingSummary),
+			huh.NewSelect[string]().
+				Options(
+					huh.NewOption(msg.ConflictForce, "force"),
+					huh.NewOption(msg.ConflictCancel, "cancel"),
+				).
+				Value(&action),
+		),
+	).WithTheme(cmdutil.ThemeFeishu())
+
+	if err := form.Run(); err != nil {
+		if err == huh.ErrUserAborted {
+			return "cancel", nil
+		}
+		return "", err
+	}
+	return action, nil
+}
+
+// indent prepends two spaces to every line of s. Used to visually nest
+// multi-line option descriptions under their label in tuiSelectIdentity.
+func indent(s string) string {
+	return "  " + strings.ReplaceAll(s, "\n", "\n  ")
+}
+
+// validateBindFlags validates enum flags early, before any side effects.
+func validateBindFlags(opts *BindOptions) error {
+	if opts.Identity != "" {
+		switch opts.Identity {
+		case "bot-only", "user-default":
+		default:
+			return output.ErrValidation("invalid --identity %q; valid values: bot-only, user-default", opts.Identity)
+		}
+	}
+	return nil
+}
+
+// tuiSelectIdentity prompts user to pick one of two identity presets.
+// bot-only is listed first so Enter on the default highlight maps to the
+// flag-mode default for consistency across the two modes, and also because
+// bot-only is the safer preset (no impersonation risk).
+//
+// Layout: each option's description is embedded under its label using a
+// multi-line option value. huh styles the whole option block (label +
+// indented description) as selected / unselected, giving a clear visual
+// mapping between picker rows and their explanations — the dynamic
+// 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.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
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewSelect[string]().
+				Title(msg.SelectIdentity).
+				Options(
+					huh.NewOption(botLabel, "bot-only"),
+					huh.NewOption(userLabel, "user-default"),
+				).
+				Value(&value),
+		),
+	).WithTheme(cmdutil.ThemeFeishu())
+
+	if err := form.Run(); err != nil {
+		if err == huh.ErrUserAborted {
+			return "", output.ErrBare(1)
+		}
+		return "", err
+	}
+	return value, nil
+}

cmd/config/bind_messages.go

@@ -0,0 +1,172 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+// 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
+// should appear; callers pass brandDisplay(brand, lang) at that position.
+// English templates use %[N]s positional indices when the natural English
+// order puts brand before source.
+type bindMsg struct {
+	// Source selection.
+	// SelectSourceDesc format: brand.
+	SelectSource     string
+	SelectSourceDesc string
+	SourceOpenClaw   string // format: resolved config path.
+	SourceHermes     string // format: resolved dotenv path.
+
+	// Account selection (OpenClaw multi-account).
+	// Format: source display name ("OpenClaw" | "Hermes"), brand.
+	SelectAccount string
+
+	// Conflict prompt.
+	ConflictTitle     string
+	ConflictDesc      string // format: workspace, appId, brand, configPath.
+	ConflictForce     string
+	ConflictCancel    string
+	ConflictCancelled string
+
+	// Post-bind agent-friendly message emitted in the stdout JSON envelope's
+	// "message" field. Written as imperative instructions to the agent reading
+	// the JSON — not as description for a human reader.
+	// MessageBotOnly format: app_id, source display name, brand.
+	// MessageUserDefault format: app_id, source display name, source display
+	// name (second source ref anchors the "run in this chat" directive).
+	// MessageUserDefault directs the Agent at the blocking single-call
+	// `auth login --recommend` flow: the CLI streams verification_url to
+	// stderr, which Agent runtimes (OpenClaw, Hermes) relay to the user in
+	// real time, then blocks until the user authorizes in their own browser.
+	// The Agent also needs an explicit "do not navigate the URL yourself"
+	// guard — its own browser is sandboxed and cannot complete the user's
+	// authorization.
+	MessageBotOnly     string
+	MessageUserDefault string
+
+	// Identity preset (collapses strict-mode + default-as into one choice).
+	// IdentityBotOnly/IdentityUserDefault are short, single-line labels for
+	// the huh Select options. IdentityBotOnlyDesc / IdentityUserDefaultDesc
+	// carry the longer explanation for each choice; tuiSelectIdentity
+	// embeds the description under its label as a multi-line option value,
+	// so huh renders the whole "label + indented description" block as one
+	// picker row and styles it selected / unselected as a unit. Dynamic
+	// DescriptionFunc was tried first but breaks here: a longer description
+	// on hover pushes the field's initial viewport, clipping the selected
+	// option row on terminals that fit the smaller description.
+	// IdentityBotOnlyDesc format: brand.
+	// IdentityUserDefaultDesc format: brand, brand.
+	SelectIdentity          string
+	IdentityBotOnly         string
+	IdentityUserDefault     string
+	IdentityBotOnlyDesc     string
+	IdentityUserDefaultDesc string
+
+	// Post-bind success notice printed to stderr once the workspace config
+	// has been durably written. Rendered as two parts joined with "\n":
+	//   BindSuccessHeader — format: source display name.
+	//   BindSuccessNotice — caveat about one-time sync.
+	// We intentionally do NOT emit a "replaced" suffix here (the TUI already
+	// asked the user to confirm overwrite; flag mode carries `replaced:true`
+	// in the stdout JSON envelope), and we do NOT emit an inline "next step"
+	// line for user-default (stderr is the human channel; agents read the
+	// MessageUserDefault field in the JSON envelope).
+	BindSuccessHeader string
+	BindSuccessNotice string
+
+	// IdentityEscalationMessage / IdentityEscalationHint are returned when a
+	// previous bind set the workspace to bot-only and a flag-mode (AI-driven)
+	// caller tries to rebind with --identity user-default without --force.
+	// The error asks the Agent to surface the risk to the user and re-run
+	// with --force only after explicit user confirmation. TUI mode does not
+	// hit this code path — tuiConflictPrompt + tuiSelectIdentity already
+	// require in-flow human confirmation.
+	IdentityEscalationMessage string
+	IdentityEscalationHint    string
+}
+
+var bindMsgZh = &bindMsg{
+	SelectSource:     "你想在哪个 Agent 中使用 lark-cli?",
+	SelectSourceDesc: "从你选择的 Agent 中获取%s应用信息，并配置到 lark-cli 中",
+	SourceOpenClaw:   "OpenClaw — 配置文件: %s",
+	SourceHermes:     "Hermes — 配置文件: %s",
+
+	SelectAccount: "检测到 %s 中已配置多个%s应用，请选择一个",
+
+	ConflictTitle:     "检测到已有配置",
+	ConflictDesc:      "%q 已配置 lark-cli:\n  App ID:  %s\n  品牌:    %s\n  配置文件: %s",
+	ConflictForce:     "修改配置",
+	ConflictCancel:    "保留当前配置",
+	ConflictCancelled: "已保留当前配置",
+
+	MessageBotOnly:     "已绑定应用 %s 到 %s，可立即以应用（bot）身份调用%s API，现在可以继续执行用户的请求。",
+	MessageUserDefault: "已绑定应用 %s 到 %s。请接着在此 %s 对话中运行 `lark-cli auth login --recommend`。该命令会在 stderr 打出 verification_url 后阻塞等待用户授权；请将此链接原样发给用户在其浏览器中完成授权（不要自己调 browser_navigate 之类的工具打开，授权必须在用户的浏览器里完成），命令会在用户授权完成后自动返回。",
+
+	SelectIdentity:      "你希望 AI 如何与你协作？",
+	IdentityBotOnly:     "以机器人身份",
+	IdentityUserDefault: "以你的身份",
+	IdentityBotOnlyDesc: "AI 将在%s中以机器人的身份执行所有操作，适合作为团队助手，用于多人协作场景，如群聊问答、团队通知、公共文档维护。",
+	IdentityUserDefaultDesc: "AI 将在%s中以你的名义执行所有操作，如读写文档、搜索消息、修改日程等，建议仅限个人使用。\n" +
+		"⚠️  请勿将此机器人分享给他人或拉入群聊中使用，以免泄露你的%s数据。",
+
+	BindSuccessHeader: "配置成功！lark-cli 已可在 %s 中使用。",
+	BindSuccessNotice: "注意：这是一次性同步，后续 Agent 配置变更不会自动更新到 lark-cli。如需重新同步，请执行 `lark-cli config bind`",
+
+	IdentityEscalationMessage: "你正在从应用身份切换到用户身份 —— 切换后 AI 将以你的名义在飞书中执行所有操作（读写文档、搜索消息、修改日程等）。⚠️ 请勿将此机器人分享给他人或拉入群聊中使用，以免泄露你的飞书数据。",
+	IdentityEscalationHint:    "若用户确认切换，附加 --force 重新运行：`lark-cli config bind --identity user-default --force`",
+}
+
+var bindMsgEn = &bindMsg{
+	SelectSource:     "Which Agent are you running?",
+	SelectSourceDesc: "lark-cli will read your %s app credentials from the selected Agent and apply them automatically.",
+	SourceOpenClaw:   "OpenClaw — config: %s",
+	SourceHermes:     "Hermes — config: %s",
+
+	// Args order (source, brand) matches the Chinese template; %[N]s lets the
+	// English reading order differ while the caller passes args in one order.
+	SelectAccount: "Multiple %[2]s apps configured in %[1]s — select one to continue.",
+
+	ConflictTitle:     "Existing configuration found",
+	ConflictDesc:      "lark-cli is already set up for %q:\n  App ID:  %s\n  Brand:   %s\n  Config:  %s",
+	ConflictForce:     "Update config",
+	ConflictCancel:    "Keep current config",
+	ConflictCancelled: "Current config kept. No changes made.",
+
+	MessageBotOnly:     "Bound app %s to %s. The %s app (bot) identity is ready — you can now continue with the user's request.",
+	MessageUserDefault: "Bound app %s to %s. Next, in this %s chat, run `lark-cli auth login --recommend`. The command prints the verification URL to stderr and then blocks until the user authorizes it; relay the URL to the user so they can approve it in their own browser (do not call browser_navigate or any tool that opens a browser yourself — your browser is sandboxed and cannot complete the authorization). The command returns automatically once authorization completes.",
+
+	SelectIdentity:      "How should the AI work with you?",
+	IdentityBotOnly:     "As bot",
+	IdentityUserDefault: "As you",
+	IdentityBotOnlyDesc: "Works under its own identity in %s. Best for group chats, team notifications, and shared documents.",
+	IdentityUserDefaultDesc: "Works under your identity in %s, managing docs, messages, calendar, and more on your behalf. Personal use only.\n" +
+		"⚠️  Don't share this bot with others or add it to group chats. It has access to your personal %s data.",
+
+	BindSuccessHeader: "All set! lark-cli is now ready to use in %s.",
+	BindSuccessNotice: "Note: This is a one-time sync. To re-sync future changes, run `lark-cli config bind`",
+
+	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`",
+}
+
+func getBindMsg(lang string) *bindMsg {
+	if lang == "en" {
+		return bindMsgEn
+	}
+	return bindMsgZh
+}
+
+// brandDisplay returns the UI-friendly product name for the given brand
+// identifier and display language. "lark" maps to "Lark" in both zh and en.
+// "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, lang string) string {
+	if brand == "lark" || brand == "Lark" || brand == "LARK" {
+		return "Lark"
+	}
+	if lang == "en" {
+		return "Feishu"
+	}
+	return "飞书"
+}

cmd/config/binder.go

@@ -0,0 +1,414 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/larksuite/cli/internal/binding"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// Candidate is the source-agnostic view of a bindable account.
+// It carries only the identity fields needed by selectCandidate / TUI;
+// secrets remain inside the SourceBinder implementation.
+type Candidate struct {
+	AppID string
+	Label string
+}
+
+// SourceBinder abstracts a bind source (openclaw / hermes / future sources).
+// Implementations only list candidates and build an AppConfig for a chosen
+// candidate — they stay out of mode (TUI vs flag) and orchestration concerns.
+type SourceBinder interface {
+	// Name returns the source identifier (used in error envelopes).
+	Name() string
+	// ConfigPath returns the resolved path to the source's config file.
+	ConfigPath() string
+	// ListCandidates enumerates bindable accounts from the source config.
+	// An empty slice is valid (selectCandidate will turn it into a typed error).
+	ListCandidates() ([]Candidate, error)
+	// Build resolves secrets, persists to keychain, and returns a ready AppConfig
+	// for the chosen candidate AppID. Must be called after ListCandidates succeeds.
+	Build(appID string) (*core.AppConfig, error)
+}
+
+// newBinder constructs the SourceBinder for the given source name.
+func newBinder(source string, opts *BindOptions) (SourceBinder, error) {
+	switch source {
+	case "openclaw":
+		return &openclawBinder{opts: opts, path: resolveOpenClawConfigPath()}, nil
+	case "hermes":
+		return &hermesBinder{opts: opts, path: resolveHermesEnvPath()}, nil
+	default:
+		return nil, output.ErrValidation("unsupported source: %s", source)
+	}
+}
+
+// selectCandidate is the single source of truth for account-selection logic.
+// Every bind source funnels through this function, so the "how many
+// candidates × was --app-id given × is this TUI" policy is defined once.
+//
+// Decision matrix:
+//
+//	candidates=0                              → error "no app configured"
+//	appID set,   match                        → selected
+//	appID set,   no match                     → error + candidate list
+//	candidates=1, appID=""                    → auto-select
+//	candidates≥2, appID="", isTUI=true        → tuiPrompt
+//	candidates≥2, appID="", isTUI=false       → error + candidate list
+//
+// The last branch is the one that matters for flag-mode callers: an explicit
+// --source must never silently drop into an interactive prompt just because
+// stdin happens to be a terminal.
+func selectCandidate(
+	binder SourceBinder,
+	candidates []Candidate,
+	appIDFlag string,
+	isTUI bool,
+	tuiPrompt func([]Candidate) (*Candidate, error),
+) (*Candidate, error) {
+	src := binder.Name()
+	cfgBase := filepath.Base(binder.ConfigPath())
+
+	if len(candidates) == 0 {
+		// Reader succeeded but yielded nothing — e.g. every openclaw account
+		// is disabled. Missing-file / missing-field cases return typed errors
+		// from ListCandidates itself and never reach here.
+		switch src {
+		case "openclaw":
+			return nil, output.ErrWithHint(output.ExitValidation, src,
+				"no Feishu app configured in openclaw.json",
+				"configure channels.feishu.appId in openclaw.json")
+		default:
+			return nil, output.ErrValidation("%s: no app configured", src)
+		}
+	}
+
+	if appIDFlag != "" {
+		for i := range candidates {
+			if candidates[i].AppID == appIDFlag {
+				return &candidates[i], nil
+			}
+		}
+		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 {
+		return &candidates[0], nil
+	}
+
+	if isTUI {
+		return tuiPrompt(candidates)
+	}
+
+	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.
+func formatCandidates(candidates []Candidate) string {
+	ids := make([]string, 0, len(candidates))
+	for _, c := range candidates {
+		label := c.AppID
+		if c.Label != "" {
+			label = fmt.Sprintf("%s (%s)", c.AppID, c.Label)
+		}
+		ids = append(ids, label)
+	}
+	return strings.Join(ids, "\n  ")
+}
+
+// ──────────────────────────────────────────────────────────────
+// openclawBinder
+// ──────────────────────────────────────────────────────────────
+
+type openclawBinder struct {
+	opts *BindOptions
+	path string
+
+	// Cached between ListCandidates and Build so we don't re-read / re-parse.
+	cfg     *binding.OpenClawRoot
+	rawApps []binding.CandidateApp
+}
+
+func (b *openclawBinder) Name() string       { return "openclaw" }
+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, 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, output.ErrWithHint(output.ExitValidation, "openclaw",
+			"openclaw.json missing channels.feishu section",
+			"configure Feishu in OpenClaw first")
+	}
+
+	raw := binding.ListCandidateApps(cfg.Channels.Feishu)
+	b.cfg = cfg
+	b.rawApps = raw
+
+	result := make([]Candidate, 0, len(raw))
+	for _, c := range raw {
+		result = append(result, Candidate{AppID: c.AppID, Label: c.Label})
+	}
+	return result, nil
+}
+
+func (b *openclawBinder) Build(appID string) (*core.AppConfig, error) {
+	if b.cfg == nil {
+		return nil, output.Errorf(output.ExitInternal, "openclaw",
+			"internal: Build called before ListCandidates")
+	}
+
+	var selected *binding.CandidateApp
+	for i := range b.rawApps {
+		if b.rawApps[i].AppID == appID {
+			selected = &b.rawApps[i]
+			break
+		}
+	}
+	if selected == nil {
+		return nil, output.Errorf(output.ExitInternal, "openclaw",
+			"internal: appID %q not in candidates", appID)
+	}
+
+	if selected.AppSecret.IsZero() {
+		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, 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, output.Errorf(output.ExitInternal, "openclaw",
+			"keychain unavailable: %v\nhint: use file: reference in config to bypass keychain", err)
+	}
+
+	return &core.AppConfig{
+		AppId:     selected.AppID,
+		AppSecret: stored,
+		Brand:     core.LarkBrand(normalizeBrand(selected.Brand)),
+	}, nil
+}
+
+// ──────────────────────────────────────────────────────────────
+// hermesBinder
+// ──────────────────────────────────────────────────────────────
+
+type hermesBinder struct {
+	opts   *BindOptions
+	path   string
+	envMap map[string]string // cached between ListCandidates and Build
+}
+
+func (b *hermesBinder) Name() string       { return "hermes" }
+func (b *hermesBinder) ConfigPath() string { return b.path }
+
+func (b *hermesBinder) ListCandidates() ([]Candidate, error) {
+	envMap, err := readDotenv(b.path)
+	if err != nil {
+		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, 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
+}
+
+func (b *hermesBinder) Build(appID string) (*core.AppConfig, error) {
+	if b.envMap == nil {
+		return nil, output.Errorf(output.ExitInternal, "hermes",
+			"internal: Build called before ListCandidates")
+	}
+	if b.envMap["FEISHU_APP_ID"] != 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, 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, output.Errorf(output.ExitInternal, "hermes",
+			"keychain unavailable: %v\nhint: use file: reference in config to bypass keychain", err)
+	}
+
+	return &core.AppConfig{
+		AppId:     appID,
+		AppSecret: stored,
+		Brand:     core.LarkBrand(normalizeBrand(b.envMap["FEISHU_DOMAIN"])),
+	}, nil
+}
+
+// ──────────────────────────────────────────────────────────────
+// Source-specific helpers (path / dotenv / brand) — kept private to this package.
+// Moved here from bind.go so bind.go can focus on orchestration.
+// ──────────────────────────────────────────────────────────────
+
+// sourceDisplayName returns the user-facing label for a source identifier,
+// matching the casing used in bind_messages.go (OpenClaw / Hermes).
+func sourceDisplayName(source string) string {
+	switch source {
+	case "openclaw":
+		return "OpenClaw"
+	case "hermes":
+		return "Hermes"
+	default:
+		return source
+	}
+}
+
+// normalizeBrand applies .strip().lower() and defaults to "feishu".
+// Aligns with Hermes gateway/platforms/feishu.py:1119 behavior.
+func normalizeBrand(raw string) string {
+	s := strings.TrimSpace(strings.ToLower(raw))
+	if s == "" {
+		return "feishu"
+	}
+	return s
+}
+
+// resolveHermesEnvPath returns the path to Hermes's .env file.
+// Respects HERMES_HOME override; defaults to ~/.hermes/.env.
+//
+// Note: HERMES_HOME is typically unset when users run bind from a regular
+// terminal. When AI agents execute bind within a Hermes subprocess, HERMES_HOME
+// may be set and should be respected.
+func resolveHermesEnvPath() string {
+	hermesHome := os.Getenv("HERMES_HOME")
+	if hermesHome == "" {
+		home, err := vfs.UserHomeDir()
+		if err != nil || home == "" {
+			fmt.Fprintf(os.Stderr, "warning: unable to determine home directory: %v\n", err)
+		}
+		hermesHome = filepath.Join(home, ".hermes")
+	}
+	return filepath.Join(hermesHome, ".env")
+}
+
+// resolveOpenClawConfigPath resolves openclaw.json path using the same priority
+// chain as OpenClaw's src/config/paths.ts:
+//  1. OPENCLAW_CONFIG_PATH env → exact file path
+//  2. OPENCLAW_STATE_DIR env → <dir>/openclaw.json
+//  3. OPENCLAW_HOME env → <home>/.openclaw/openclaw.json
+//  4. ~/.openclaw/openclaw.json (default)
+//  5. Legacy: ~/.clawdbot/clawdbot.json, ~/.openclaw/clawdbot.json
+func resolveOpenClawConfigPath() string {
+	if p := os.Getenv("OPENCLAW_CONFIG_PATH"); p != "" {
+		return expandHome(p)
+	}
+
+	if stateDir := os.Getenv("OPENCLAW_STATE_DIR"); stateDir != "" {
+		dir := expandHome(stateDir)
+		return findConfigInDir(dir)
+	}
+
+	home := os.Getenv("OPENCLAW_HOME")
+	if home == "" {
+		h, err := vfs.UserHomeDir()
+		if err != nil || h == "" {
+			fmt.Fprintf(os.Stderr, "warning: unable to determine home directory: %v\n", err)
+		}
+		home = h
+	} else {
+		home = expandHome(home)
+	}
+
+	newDir := filepath.Join(home, ".openclaw")
+	if configFile := findConfigInDir(newDir); fileExists(configFile) {
+		return configFile
+	}
+
+	legacyDir := filepath.Join(home, ".clawdbot")
+	if configFile := findConfigInDir(legacyDir); fileExists(configFile) {
+		return configFile
+	}
+
+	return filepath.Join(newDir, "openclaw.json")
+}
+
+func findConfigInDir(dir string) string {
+	primary := filepath.Join(dir, "openclaw.json")
+	if fileExists(primary) {
+		return primary
+	}
+	legacy := filepath.Join(dir, "clawdbot.json")
+	if fileExists(legacy) {
+		return legacy
+	}
+	return primary
+}
+
+func fileExists(path string) bool {
+	_, err := vfs.Stat(path)
+	return err == nil
+}
+
+func expandHome(path string) string {
+	if strings.HasPrefix(path, "~/") || path == "~" {
+		home, err := vfs.UserHomeDir()
+		if err != nil {
+			return path
+		}
+		return filepath.Join(home, path[1:])
+	}
+	return path
+}
+
+// readDotenv reads a KEY=VALUE .env file. Comments (#) and blank lines skipped.
+// Matches Hermes's load_env() in hermes_cli/config.py.
+func readDotenv(path string) (map[string]string, error) {
+	data, err := vfs.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+
+	result := make(map[string]string)
+	lines := strings.Split(string(data), "\n")
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		idx := strings.IndexByte(line, '=')
+		if idx < 0 {
+			continue
+		}
+		key := strings.TrimSpace(line[:idx])
+		value := strings.TrimSpace(line[idx+1:])
+		if key != "" {
+			result[key] = value
+		}
+	}
+	return result, nil
+}

cmd/config/binder_test.go

@@ -0,0 +1,175 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+)
+
+// fakeBinder is a test double for SourceBinder. selectCandidate only touches
+// Name and ConfigPath (for error messages); ListCandidates/Build are not called
+// from selectCandidate, so we can leave them as no-ops.
+type fakeBinder struct {
+	name string
+	path string
+}
+
+func (b *fakeBinder) Name() string                                { return b.name }
+func (b *fakeBinder) ConfigPath() string                          { return b.path }
+func (b *fakeBinder) ListCandidates() ([]Candidate, error)        { return nil, nil }
+func (b *fakeBinder) Build(appID string) (*core.AppConfig, error) { return nil, nil }
+
+// tuiUnreachable is a tuiPrompt that fails the test if called. It's the
+// guardrail that proves the non-TUI decision paths really do stay out of the
+// interactive prompt — otherwise a green test could still hide a silent TUI.
+func tuiUnreachable(t *testing.T) func([]Candidate) (*Candidate, error) {
+	t.Helper()
+	return func([]Candidate) (*Candidate, error) {
+		t.Fatal("tuiPrompt must not be called in flag mode")
+		return nil, nil
+	}
+}
+
+// assertCandidate compares the full Candidate struct via DeepEqual so that
+// any future field added to Candidate is covered automatically.
+func assertCandidate(t *testing.T, got *Candidate, want Candidate) {
+	t.Helper()
+	if got == nil {
+		t.Fatal("expected non-nil Candidate")
+	}
+	if !reflect.DeepEqual(*got, want) {
+		t.Errorf("candidate mismatch:\n  got:  %+v\n  want: %+v", *got, want)
+	}
+}
+
+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.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
+		Message: "no Feishu app configured in openclaw.json",
+		Hint:    "configure channels.feishu.appId in openclaw.json",
+	})
+}
+
+func TestSelectCandidate_ZeroCandidates_GenericSource(t *testing.T) {
+	// Locks in the generic fallback so that any future source added to
+	// newBinder gets a well-formed validation error on "zero candidates"
+	// 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.ExitValidation, output.ErrDetail{
+		Type:    "validation",
+		Message: "hermes: no app configured",
+	})
+}
+
+func TestSelectCandidate_SingleCandidate_NoFlag_AutoSelect(t *testing.T) {
+	b := &fakeBinder{name: "openclaw", path: "/tmp/openclaw.json"}
+	candidates := []Candidate{{AppID: "cli_only", Label: "default"}}
+	got, err := selectCandidate(b, candidates, "", false, tuiUnreachable(t))
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	assertCandidate(t, got, Candidate{AppID: "cli_only", Label: "default"})
+}
+
+func TestSelectCandidate_AppIDFlag_ExactMatch(t *testing.T) {
+	b := &fakeBinder{name: "openclaw", path: "/tmp/openclaw.json"}
+	candidates := []Candidate{
+		{AppID: "cli_work", Label: "work"},
+		{AppID: "cli_home", Label: "home"},
+	}
+	got, err := selectCandidate(b, candidates, "cli_home", false, tuiUnreachable(t))
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	assertCandidate(t, got, Candidate{AppID: "cli_home", Label: "home"})
+}
+
+func TestSelectCandidate_AppIDFlag_NoMatch(t *testing.T) {
+	b := &fakeBinder{name: "openclaw", path: "/tmp/openclaw.json"}
+	candidates := []Candidate{
+		{AppID: "cli_work", Label: "work"},
+		{AppID: "cli_home", Label: "home"},
+	}
+	_, err := selectCandidate(b, candidates, "nonexistent", false, tuiUnreachable(t))
+	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)",
+	})
+}
+
+func TestSelectCandidate_MultiCandidate_NoFlag_NonTUI(t *testing.T) {
+	// Flag-mode with multiple candidates and no --app-id must produce a
+	// validation error and the candidate list, never an interactive prompt.
+	// isTUI is the single gate; a real terminal alone must not trigger TUI.
+	b := &fakeBinder{name: "openclaw", path: "/tmp/openclaw.json"}
+	candidates := []Candidate{
+		{AppID: "cli_work", Label: "work"},
+		{AppID: "cli_home", Label: "home"},
+	}
+	_, err := selectCandidate(b, candidates, "", false, tuiUnreachable(t))
+	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)",
+	})
+}
+
+func TestSelectCandidate_MultiCandidate_NoFlag_TUI(t *testing.T) {
+	b := &fakeBinder{name: "openclaw", path: "/tmp/openclaw.json"}
+	candidates := []Candidate{
+		{AppID: "cli_work", Label: "work"},
+		{AppID: "cli_home", Label: "home"},
+	}
+	var gotCandidates []Candidate
+	got, err := selectCandidate(b, candidates, "", true, func(cs []Candidate) (*Candidate, error) {
+		gotCandidates = cs
+		return &cs[1], nil
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// Whole-slice DeepEqual so additions to Candidate propagate to this check.
+	if !reflect.DeepEqual(gotCandidates, candidates) {
+		t.Errorf("tuiPrompt received %+v, want %+v", gotCandidates, candidates)
+	}
+	assertCandidate(t, got, Candidate{AppID: "cli_home", Label: "home"})
+}
+
+func TestSelectCandidate_SingleCandidate_WrongFlag(t *testing.T) {
+	// Even with only one candidate, a wrong --app-id must error rather than
+	// silently auto-selecting. An explicit mismatch is always a user mistake,
+	// not a reason to override their intent.
+	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, output.ErrDetail{
+		Type:    "openclaw",
+		Message: `--app-id "nonexistent" not found in openclaw.json`,
+		Hint:    "available app IDs:\n  cli_only",
+	})
+}
+
+func TestSelectCandidate_AppIDFlag_WinsOverTUI(t *testing.T) {
+	// An explicit --app-id short-circuits the prompt even in TUI mode: a
+	// flag the user typed should never be second-guessed by an interactive
+	// prompt asking the same question.
+	b := &fakeBinder{name: "openclaw", path: "/tmp/openclaw.json"}
+	candidates := []Candidate{
+		{AppID: "cli_a"},
+		{AppID: "cli_b"},
+	}
+	got, err := selectCandidate(b, candidates, "cli_b", true, tuiUnreachable(t))
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	assertCandidate(t, got, Candidate{AppID: "cli_b"})
+}

cmd/config/config.go

@@ -18,6 +18,7 @@ func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
 	cmdutil.DisableAuthCheck(cmd)
 
 	cmd.AddCommand(NewCmdConfigInit(f, nil))
+	cmd.AddCommand(NewCmdConfigBind(f, nil))
 	cmd.AddCommand(NewCmdConfigRemove(f, nil))
 	cmd.AddCommand(NewCmdConfigShow(f, nil))
 	cmd.AddCommand(NewCmdConfigDefaultAs(f))

cmd/config/init_messages.go

@@ -10,12 +10,12 @@ import (
 )
 
 type initMsg struct {
-	SelectAction       string
-	CreateNewApp       string
-	ConfigExistingApp  string
-	Platform           string
-	SelectPlatform     string
-	Feishu             string
+	SelectAction      string
+	CreateNewApp      string
+	ConfigExistingApp string
+	Platform          string
+	SelectPlatform    string
+	Feishu            string
 	// TTY (interactive) variants
 	ScanQRCode     string // header shown above QR code
 	ScanOrOpenLink string // post-QR alt link prompt ("or open...")
@@ -29,11 +29,11 @@ type initMsg struct {
 }
 
 var initMsgZh = &initMsg{
-	SelectAction:       "选择操作",
-	CreateNewApp:       "一键配置应用 (推荐) ",
-	ConfigExistingApp:  "手动输入应用凭证",
-	Platform:           "平台",
-	SelectPlatform:     "选择平台",
+	SelectAction:         "选择操作",
+	CreateNewApp:         "一键配置应用 (推荐) ",
+	ConfigExistingApp:    "手动输入应用凭证",
+	Platform:             "平台",
+	SelectPlatform:       "选择平台",
 	Feishu:               "飞书",
 	ScanQRCode:           "\n使用飞书 / Lark 扫码配置应用：\n\n",
 	ScanOrOpenLink:       "\n或打开以下链接完成配置：\n",
@@ -46,11 +46,11 @@ var initMsgZh = &initMsg{
 }
 
 var initMsgEn = &initMsg{
-	SelectAction:       "Select action",
-	CreateNewApp:       "Set up your app with one click (Recommended)",
-	ConfigExistingApp:  "Enter app credentials yourself",
-	Platform:           "Platform",
-	SelectPlatform:     "Select platform",
+	SelectAction:         "Select action",
+	CreateNewApp:         "Set up your app with one click (Recommended)",
+	ConfigExistingApp:    "Enter app credentials yourself",
+	Platform:             "Platform",
+	SelectPlatform:       "Select platform",
 	Feishu:               "Feishu",
 	ScanQRCode:           "\nScan the QR code with Feishu/Lark:\n\n",
 	ScanOrOpenLink:       "\nOr open the link below in your browser:\n",

cmd/config/init_messages_test.go

@@ -48,12 +48,12 @@ func TestInitMsgEn_AllFieldsNonEmpty(t *testing.T) {
 func assertAllFieldsNonEmpty(t *testing.T, msg *initMsg, label string) {
 	t.Helper()
 	fields := map[string]string{
-		"SelectAction":       msg.SelectAction,
-		"CreateNewApp":       msg.CreateNewApp,
-		"ConfigExistingApp":  msg.ConfigExistingApp,
-		"Platform":           msg.Platform,
-		"SelectPlatform":     msg.SelectPlatform,
-		"Feishu":             msg.Feishu,
+		"SelectAction":         msg.SelectAction,
+		"CreateNewApp":         msg.CreateNewApp,
+		"ConfigExistingApp":    msg.ConfigExistingApp,
+		"Platform":             msg.Platform,
+		"SelectPlatform":       msg.SelectPlatform,
+		"Feishu":               msg.Feishu,
 		"ScanQRCode":           msg.ScanQRCode,
 		"ScanOrOpenLink":       msg.ScanOrOpenLink,
 		"WaitingForScan":       msg.WaitingForScan,

cmd/config/show.go

@@ -44,7 +44,7 @@ func configShowRun(opts *ConfigShowOptions) error {
 	config, err := core.LoadMultiAppConfig()
 	if err != nil {
 		if errors.Is(err, os.ErrNotExist) {
-			return output.ErrWithHint(output.ExitValidation, "config", "not configured", "run: lark-cli config init")
+			return notConfiguredError()
 		}
 		return output.Errorf(output.ExitValidation, "config", "failed to load config: %v", err)
 	}
@@ -64,6 +64,7 @@ func configShowRun(opts *ConfigShowOptions) error {
 		users = strings.Join(userStrs, ", ")
 	}
 	output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+		"workspace": core.CurrentWorkspace().Display(),
 		"profile":   app.ProfileName(),
 		"appId":     app.AppId,
 		"appSecret": "****",
@@ -74,3 +75,18 @@ func configShowRun(opts *ConfigShowOptions) error {
 	fmt.Fprintf(f.IOStreams.ErrOut, "\nConfig file path: %s\n", core.GetConfigPath())
 	return nil
 }
+
+// notConfiguredError returns the "not configured" error with a hint that
+// points the user to the right next step: config init for the default local
+// workspace, config bind for an Agent workspace that has not been bound yet.
+func notConfiguredError() error {
+	ws := core.CurrentWorkspace()
+	if ws.IsLocal() {
+		return output.ErrWithHint(output.ExitValidation, "config",
+			"not configured",
+			"run: lark-cli config init")
+	}
+	return output.ErrWithHint(output.ExitValidation, ws.Display(),
+		fmt.Sprintf("%s context detected but lark-cli not bound to %s workspace", ws.Display(), ws.Display()),
+		fmt.Sprintf("run: lark-cli config bind --source %s", ws.Display()))
+}

cmd/doctor/doctor.go

@@ -253,8 +253,9 @@ func finishDoctor(f *cmdutil.Factory, checks []checkResult) error {
 	}
 
 	result := map[string]interface{}{
-		"ok":     allOK,
-		"checks": checks,
+		"ok":        allOK,
+		"workspace": core.CurrentWorkspace().Display(),
+		"checks":    checks,
 	}
 	output.PrintJson(f.IOStreams.Out, result)
 	if !allOK {

cmd/global_flags.go

@@ -3,15 +3,38 @@
 
 package cmd
 
-import "github.com/spf13/pflag"
+import (
+	"github.com/larksuite/cli/internal/core"
+	"github.com/spf13/pflag"
+)
 
 // GlobalOptions are the root-level flags shared by bootstrap parsing and the
-// actual Cobra command tree.
+// actual Cobra command tree. Profile is the parsed --profile value; HideProfile
+// is a build-time policy — when true, --profile stays parseable but is marked
+// hidden from help and shell completion.
 type GlobalOptions struct {
-	Profile string
+	Profile     string
+	HideProfile bool
 }
 
-// RegisterGlobalFlags registers the root-level persistent flags.
+// RegisterGlobalFlags registers the root-level persistent flags on fs and
+// applies any visibility policy encoded in opts. Pure function: no disk,
+// network, or environment reads — the caller decides HideProfile.
 func RegisterGlobalFlags(fs *pflag.FlagSet, opts *GlobalOptions) {
 	fs.StringVar(&opts.Profile, "profile", "", "use a specific profile")
+	if opts.HideProfile {
+		_ = fs.MarkHidden("profile")
+	}
+}
+
+// isSingleAppMode reports whether the on-disk config has at most one app.
+// Missing configs are treated as single-app since --profile is meaningless
+// until at least two profiles exist. Intended for the Execute entry point —
+// buildInternal must not call this directly to stay state-free.
+func isSingleAppMode() bool {
+	raw, err := core.LoadMultiAppConfig()
+	if err != nil || raw == nil {
+		return true
+	}
+	return len(raw.Apps) <= 1
 }

cmd/global_flags_test.go

@@ -0,0 +1,110 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/spf13/pflag"
+)
+
+func testStreams() BuildOption { return WithIO(os.Stdin, os.Stdout, os.Stderr) }
+
+func TestRegisterGlobalFlags_PolicyVisible(t *testing.T) {
+	fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
+	opts := &GlobalOptions{}
+	RegisterGlobalFlags(fs, opts)
+
+	flag := fs.Lookup("profile")
+	if flag == nil {
+		t.Fatal("profile flag should be registered")
+	}
+	if flag.Hidden {
+		t.Fatal("profile flag should be visible when HideProfile is false")
+	}
+}
+
+func TestRegisterGlobalFlags_PolicyHidden(t *testing.T) {
+	fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
+	opts := &GlobalOptions{HideProfile: true}
+	RegisterGlobalFlags(fs, opts)
+
+	flag := fs.Lookup("profile")
+	if flag == nil {
+		t.Fatal("profile flag should be registered")
+	}
+	if !flag.Hidden {
+		t.Fatal("profile flag should be hidden when HideProfile is true")
+	}
+	if err := fs.Parse([]string{"--profile", "x"}); err != nil {
+		t.Fatalf("Parse() error = %v; hidden flag should still parse", err)
+	}
+	if opts.Profile != "x" {
+		t.Fatalf("opts.Profile = %q, want %q", opts.Profile, "x")
+	}
+}
+
+func TestIsSingleAppMode_NoConfig(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if !isSingleAppMode() {
+		t.Fatal("isSingleAppMode() = false, want true when no config exists")
+	}
+}
+
+func TestIsSingleAppMode_SingleApp(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	saveAppsForTest(t, []core.AppConfig{
+		{Name: "default", AppId: "cli_a", AppSecret: core.PlainSecret("x"), Brand: core.BrandFeishu},
+	})
+	if !isSingleAppMode() {
+		t.Fatal("isSingleAppMode() = false, want true for single-app config")
+	}
+}
+
+func TestIsSingleAppMode_MultiApp(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	saveAppsForTest(t, []core.AppConfig{
+		{Name: "a", AppId: "cli_a", AppSecret: core.PlainSecret("x"), Brand: core.BrandFeishu},
+		{Name: "b", AppId: "cli_b", AppSecret: core.PlainSecret("y"), Brand: core.BrandFeishu},
+	})
+	if isSingleAppMode() {
+		t.Fatal("isSingleAppMode() = true, want false for multi-app config")
+	}
+}
+
+func TestBuildInternal_HideProfileOption(t *testing.T) {
+	_, root := buildInternal(context.Background(), cmdutil.InvocationContext{}, testStreams(), HideProfile(true))
+
+	flag := root.PersistentFlags().Lookup("profile")
+	if flag == nil {
+		t.Fatal("profile flag should be registered")
+	}
+	if !flag.Hidden {
+		t.Fatal("profile flag should be hidden when HideProfile(true) is applied")
+	}
+}
+
+func TestBuildInternal_DefaultShowsProfileFlag(t *testing.T) {
+	_, root := buildInternal(context.Background(), cmdutil.InvocationContext{}, testStreams())
+
+	flag := root.PersistentFlags().Lookup("profile")
+	if flag == nil {
+		t.Fatal("profile flag should be registered by default")
+	}
+	if flag.Hidden {
+		t.Fatal("profile flag should be visible by default")
+	}
+}
+
+func saveAppsForTest(t *testing.T, apps []core.AppConfig) {
+	t.Helper()
+	multi := &core.MultiAppConfig{CurrentApp: apps[0].Name, Apps: apps}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+}

cmd/init.go

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import "github.com/larksuite/cli/internal/vfs"
+
+// SetDefaultFS replaces the global filesystem implementation used by internal
+// packages. The provided fs must implement the vfs.FS interface. If fs is nil,
+// the default OS filesystem is restored.
+//
+// Call this before Build or Execute to take effect.
+func SetDefaultFS(fs vfs.FS) {
+	if fs == nil {
+		fs = vfs.OsFs{}
+	}
+	vfs.DefaultFS = fs
+}

cmd/root.go

@@ -14,15 +14,6 @@ import (
 	"os"
 	"strconv"
 
-	"github.com/larksuite/cli/cmd/api"
-	"github.com/larksuite/cli/cmd/auth"
-	"github.com/larksuite/cli/cmd/completion"
-	cmdconfig "github.com/larksuite/cli/cmd/config"
-	"github.com/larksuite/cli/cmd/doctor"
-	"github.com/larksuite/cli/cmd/profile"
-	"github.com/larksuite/cli/cmd/schema"
-	"github.com/larksuite/cli/cmd/service"
-	cmdupdate "github.com/larksuite/cli/cmd/update"
 	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -30,7 +21,6 @@ import (
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/internal/update"
-	"github.com/larksuite/cli/shortcuts"
 	"github.com/spf13/cobra"
 )
 
@@ -95,38 +85,13 @@ func Execute() int {
 		fmt.Fprintln(os.Stderr, "Error:", err)
 		return 1
 	}
-	f := cmdutil.NewDefault(inv)
+	configureFlagCompletions(os.Args)
 
-	globals := &GlobalOptions{Profile: inv.Profile}
-	rootCmd := &cobra.Command{
-		Use:     "lark-cli",
-		Short:   "Lark/Feishu CLI — OAuth authorization, UAT management, API calls",
-		Long:    rootLong,
-		Version: build.Version,
-	}
-	installTipsHelpFunc(rootCmd)
-	rootCmd.SilenceErrors = true
-
-	RegisterGlobalFlags(rootCmd.PersistentFlags(), globals)
-	rootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) {
-		cmd.SilenceUsage = true
-	}
-
-	rootCmd.AddCommand(cmdconfig.NewCmdConfig(f))
-	rootCmd.AddCommand(auth.NewCmdAuth(f))
-	rootCmd.AddCommand(profile.NewCmdProfile(f))
-	rootCmd.AddCommand(doctor.NewCmdDoctor(f))
-	rootCmd.AddCommand(api.NewCmdApi(f, nil))
-	rootCmd.AddCommand(schema.NewCmdSchema(f, nil))
-	rootCmd.AddCommand(completion.NewCmdCompletion(f))
-	rootCmd.AddCommand(cmdupdate.NewCmdUpdate(f))
-	service.RegisterServiceCommands(rootCmd, f)
-	shortcuts.RegisterShortcuts(rootCmd, f)
-
-	// Prune commands incompatible with strict mode.
-	if mode := f.ResolveStrictMode(context.Background()); mode.IsActive() {
-		pruneForStrictMode(rootCmd, mode)
-	}
+	f, rootCmd := buildInternal(
+		context.Background(), inv,
+		WithIO(os.Stdin, os.Stdout, os.Stderr),
+		HideProfile(isSingleAppMode()),
+	)
 
 	// --- Update check (non-blocking) ---
 	if !isCompletionCommand(os.Args) {
@@ -190,6 +155,12 @@ func isCompletionCommand(args []string) bool {
 	return false
 }
 
+// configureFlagCompletions enables cmdutil.RegisterFlagCompletion only when
+// the invocation will actually serve a __complete request.
+func configureFlagCompletions(args []string) {
+	cmdutil.SetFlagCompletionsDisabled(!isCompletionCommand(args))
+}
+
 // handleRootError dispatches a command error to the appropriate handler
 // and returns the process exit code.
 func handleRootError(f *cmdutil.Factory, err error) int {
@@ -277,10 +248,19 @@ func writeSecurityPolicyError(w io.Writer, spErr *internalauth.SecurityPolicyErr
 }
 
 // installTipsHelpFunc wraps the default help function to append a TIPS section
-// when a command has tips set via cmdutil.SetTips.
+// when a command has tips set via cmdutil.SetTips. It also force-shows global
+// flags that are normally hidden in single-app mode (currently --profile)
+// when rendering the root command's own help, so users discovering the CLI
+// still see them at `lark-cli --help`.
 func installTipsHelpFunc(root *cobra.Command) {
 	defaultHelp := root.HelpFunc()
 	root.SetHelpFunc(func(cmd *cobra.Command, args []string) {
+		if cmd == root {
+			if f := root.PersistentFlags().Lookup("profile"); f != nil && f.Hidden {
+				f.Hidden = false
+				defer func() { f.Hidden = true }()
+			}
+		}
 		defaultHelp(cmd, args)
 		tips := cmdutil.GetTips(cmd)
 		if len(tips) == 0 {

cmd/root_integration_test.go

@@ -135,10 +135,12 @@ func newStrictModeDefaultFactory(t *testing.T, profile string, mode core.StrictM
 		t.Fatalf("SaveMultiAppConfig() error = %v", err)
 	}
 
-	f := cmdutil.NewDefault(cmdutil.InvocationContext{Profile: profile})
 	stdout := &bytes.Buffer{}
 	stderr := &bytes.Buffer{}
-	f.IOStreams = &cmdutil.IOStreams{In: nil, Out: stdout, ErrOut: stderr}
+	f := cmdutil.NewDefault(
+		cmdutil.NewIOStreams(&bytes.Buffer{}, stdout, stderr),
+		cmdutil.InvocationContext{Profile: profile},
+	)
 	return f, stdout, stderr
 }
 

cmd/root_test.go

@@ -196,3 +196,28 @@ func TestRootLong_AgentSkillsLinkTargetsReadmeSection(t *testing.T) {
 		t.Fatalf("root help should not reference the removed install-ai-agent-skills anchor, got:\n%s", rootLong)
 	}
 }
+
+func TestConfigureFlagCompletions(t *testing.T) {
+	t.Cleanup(func() { cmdutil.SetFlagCompletionsDisabled(false) })
+
+	tests := []struct {
+		name         string
+		args         []string
+		wantDisabled bool
+	}{
+		{"plain command", []string{"im", "+send"}, true},
+		{"help flag", []string{"im", "--help"}, true},
+		{"no args", []string{}, true},
+		{"__complete request", []string{"__complete", "im", "+send", ""}, false},
+		{"completion subcommand", []string{"completion", "bash"}, false},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			cmdutil.SetFlagCompletionsDisabled(!tc.wantDisabled)
+			configureFlagCompletions(tc.args)
+			if got := cmdutil.FlagCompletionsDisabled(); got != tc.wantDisabled {
+				t.Fatalf("FlagCompletionsDisabled() = %v, want %v", got, tc.wantDisabled)
+			}
+		})
+	}
+}

cmd/schema/schema.go

@@ -4,12 +4,14 @@
 package schema
 
 import (
+	"context"
 	"fmt"
 	"io"
 	"sort"
 	"strings"
 
 	"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/internal/util"
@@ -19,6 +21,7 @@ import (
 // SchemaOptions holds all inputs for the schema command.
 type SchemaOptions struct {
 	Factory *cmdutil.Factory
+	Ctx     context.Context
 
 	// Positional args
 	Path string
@@ -41,7 +44,7 @@ func printServices(w io.Writer) {
 	fmt.Fprintf(w, "\n%sUsage: lark-cli schema <service>.<resource>.<method>%s\n", output.Dim, output.Reset)
 }
 
-func printResourceList(w io.Writer, spec map[string]interface{}) {
+func printResourceList(w io.Writer, spec map[string]interface{}, mode core.StrictMode) {
 	name := registry.GetStrFromMap(spec, "name")
 	version := registry.GetStrFromMap(spec, "version")
 	title := registry.GetStrFromMap(spec, "title")
@@ -55,9 +58,13 @@ func printResourceList(w io.Writer, spec map[string]interface{}) {
 
 	resources, _ := spec["resources"].(map[string]interface{})
 	for _, resName := range sortedKeys(resources) {
-		fmt.Fprintf(w, "  %s%s%s\n", output.Cyan, resName, output.Reset)
 		resMap, _ := resources[resName].(map[string]interface{})
 		methods, _ := resMap["methods"].(map[string]interface{})
+		methods = filterMethodsByStrictMode(methods, mode)
+		if len(methods) == 0 {
+			continue
+		}
+		fmt.Fprintf(w, "  %s%s%s\n", output.Cyan, resName, output.Reset)
 		for _, methodName := range sortedKeys(methods) {
 			m, _ := methods[methodName].(map[string]interface{})
 			httpMethod := registry.GetStrFromMap(m, "httpMethod")
@@ -359,6 +366,7 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 			if len(args) > 0 {
 				opts.Path = args[0]
 			}
+			opts.Ctx = cmd.Context()
 			if runF != nil {
 				return runF(opts)
 			}
@@ -367,9 +375,9 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	}
 	cmdutil.DisableAuthCheck(cmd)
 
-	cmd.ValidArgsFunction = completeSchemaPath
+	cmd.ValidArgsFunction = completeSchemaPath(f)
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json (default) | pretty")
-	_ = cmd.RegisterFlagCompletionFunc("format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
 		return []string{"json", "pretty"}, cobra.ShellCompDirectiveNoFileComp
 	})
 
@@ -379,78 +387,86 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 // completeSchemaPath provides tab-completion for the schema path argument.
 // It handles dotted resource names (e.g. app.table.fields) by iterating all
 // resources and classifying each as a prefix-match or fully-matched.
-func completeSchemaPath(_ *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
-	if len(args) > 0 {
-		return nil, cobra.ShellCompDirectiveNoFileComp
-	}
+func completeSchemaPath(f *cmdutil.Factory) func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
+	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		if len(args) > 0 {
+			return nil, cobra.ShellCompDirectiveNoFileComp
+		}
 
-	parts := strings.Split(toComplete, ".")
+		parts := strings.Split(toComplete, ".")
 
-	// Level 1: complete service names
-	if len(parts) <= 1 {
-		var completions []string
-		for _, s := range registry.ListFromMetaProjects() {
-			if strings.HasPrefix(s, toComplete) {
-				completions = append(completions, s+".")
+		// Level 1: complete service names
+		if len(parts) <= 1 {
+			var completions []string
+			for _, s := range registry.ListFromMetaProjects() {
+				if strings.HasPrefix(s, toComplete) {
+					completions = append(completions, s+".")
+				}
+			}
+			return completions, cobra.ShellCompDirectiveNoFileComp | cobra.ShellCompDirectiveNoSpace
+		}
+
+		serviceName := parts[0]
+		spec := registry.LoadFromMeta(serviceName)
+		if spec == nil {
+			return nil, cobra.ShellCompDirectiveNoFileComp
+		}
+		mode := f.ResolveStrictMode(cmd.Context())
+		spec = filterSpecByStrictMode(spec, mode)
+		resources, _ := spec["resources"].(map[string]interface{})
+		if resources == nil {
+			return nil, cobra.ShellCompDirectiveNoFileComp
+		}
+
+		afterService := strings.Join(parts[1:], ".")
+		completions := completeSchemaPathForSpec(serviceName, resources, afterService)
+
+		allTrailingDot := len(completions) > 0
+		for _, c := range completions {
+			if !strings.HasSuffix(c, ".") {
+				allTrailingDot = false
+				break
 			}
 		}
-		return completions, cobra.ShellCompDirectiveNoFileComp | cobra.ShellCompDirectiveNoSpace
+		directive := cobra.ShellCompDirectiveNoFileComp
+		if allTrailingDot {
+			directive |= cobra.ShellCompDirectiveNoSpace
+		}
+		return completions, directive
 	}
+}
 
-	serviceName := parts[0]
-	spec := registry.LoadFromMeta(serviceName)
-	if spec == nil {
-		return nil, cobra.ShellCompDirectiveNoFileComp
-	}
-	resources, _ := spec["resources"].(map[string]interface{})
-	if resources == nil {
-		return nil, cobra.ShellCompDirectiveNoFileComp
-	}
-
-	// afterService = everything user typed after "serviceName."
-	afterService := strings.Join(parts[1:], ".")
-
+func completeSchemaPathForSpec(serviceName string, resources map[string]interface{}, afterService string) []string {
 	var completions []string
 
 	for resName, resVal := range resources {
 		if strings.HasPrefix(resName, afterService) {
-			// afterService is a prefix of this resource name → resource candidate
 			completions = append(completions, serviceName+"."+resName+".")
-		} else if strings.HasPrefix(afterService, resName+".") {
-			// This resource is fully matched; remainder is method prefix
-			methodPrefix := afterService[len(resName)+1:]
-			resMap, _ := resVal.(map[string]interface{})
-			if resMap == nil {
-				continue
-			}
-			methods, _ := resMap["methods"].(map[string]interface{})
-			for methodName := range methods {
-				if strings.HasPrefix(methodName, methodPrefix) {
-					completions = append(completions, serviceName+"."+resName+"."+methodName)
-				}
+			continue
+		}
+		if !strings.HasPrefix(afterService, resName+".") {
+			continue
+		}
+		methodPrefix := afterService[len(resName)+1:]
+		resMap, _ := resVal.(map[string]interface{})
+		if resMap == nil {
+			continue
+		}
+		methods, _ := resMap["methods"].(map[string]interface{})
+		for methodName := range methods {
+			if strings.HasPrefix(methodName, methodPrefix) {
+				completions = append(completions, serviceName+"."+resName+"."+methodName)
 			}
 		}
 	}
 
 	sort.Strings(completions)
-
-	// If all completions end with ".", user is still navigating resources → NoSpace
-	allTrailingDot := len(completions) > 0
-	for _, c := range completions {
-		if !strings.HasSuffix(c, ".") {
-			allTrailingDot = false
-			break
-		}
-	}
-	directive := cobra.ShellCompDirectiveNoFileComp
-	if allTrailingDot {
-		directive |= cobra.ShellCompDirectiveNoSpace
-	}
-	return completions, directive
+	return completions
 }
 
 func schemaRun(opts *SchemaOptions) error {
 	out := opts.Factory.IOStreams.Out
+	mode := opts.Factory.ResolveStrictMode(opts.Ctx)
 
 	if opts.Path == "" {
 		printServices(out)
@@ -469,9 +485,9 @@ func schemaRun(opts *SchemaOptions) error {
 
 	if len(parts) == 1 {
 		if opts.Format == "pretty" {
-			printResourceList(out, spec)
+			printResourceList(out, spec, mode)
 		} else {
-			output.PrintJson(out, spec)
+			output.PrintJson(out, filterSpecByStrictMode(spec, mode))
 		}
 		return nil
 	}
@@ -492,6 +508,7 @@ func schemaRun(opts *SchemaOptions) error {
 		if opts.Format == "pretty" {
 			fmt.Fprintf(out, "%s%s.%s%s\n\n", output.Bold, serviceName, resName, output.Reset)
 			methods, _ := resource["methods"].(map[string]interface{})
+			methods = filterMethodsByStrictMode(methods, mode)
 			for _, mName := range sortedKeys(methods) {
 				m, _ := methods[mName].(map[string]interface{})
 				httpMethod := registry.GetStrFromMap(m, "httpMethod")
@@ -500,13 +517,26 @@ func schemaRun(opts *SchemaOptions) error {
 			}
 			fmt.Fprintf(out, "\n%sUsage: lark-cli schema %s.%s.<method>%s\n", output.Dim, serviceName, resName, output.Reset)
 		} else {
-			output.PrintJson(out, resource)
+			// For JSON output, filter methods in a copy to avoid mutating the registry.
+			if mode.IsActive() {
+				filtered := make(map[string]interface{})
+				for k, v := range resource {
+					filtered[k] = v
+				}
+				if methods, ok := resource["methods"].(map[string]interface{}); ok {
+					filtered["methods"] = filterMethodsByStrictMode(methods, mode)
+				}
+				output.PrintJson(out, filtered)
+			} else {
+				output.PrintJson(out, resource)
+			}
 		}
 		return nil
 	}
 
 	methodName := remaining[0]
 	methods, _ := resource["methods"].(map[string]interface{})
+	methods = filterMethodsByStrictMode(methods, mode)
 	method, ok := methods[methodName].(map[string]interface{})
 	if !ok {
 		var mNames []string
@@ -525,3 +555,67 @@ func schemaRun(opts *SchemaOptions) error {
 	}
 	return nil
 }
+
+// filterSpecByStrictMode returns a shallow copy of spec with each resource's methods
+// filtered by strict mode. Returns the original spec when strict mode is off.
+func filterSpecByStrictMode(spec map[string]interface{}, mode core.StrictMode) map[string]interface{} {
+	if !mode.IsActive() {
+		return spec
+	}
+	result := make(map[string]interface{}, len(spec))
+	for k, v := range spec {
+		result[k] = v
+	}
+	resources, _ := spec["resources"].(map[string]interface{})
+	if resources == nil {
+		return result
+	}
+	filteredRes := make(map[string]interface{}, len(resources))
+	for resName, resVal := range resources {
+		resMap, ok := resVal.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		methods, _ := resMap["methods"].(map[string]interface{})
+		filtered := filterMethodsByStrictMode(methods, mode)
+		if len(filtered) == 0 {
+			continue
+		}
+		resCopy := make(map[string]interface{}, len(resMap))
+		for k, v := range resMap {
+			resCopy[k] = v
+		}
+		resCopy["methods"] = filtered
+		filteredRes[resName] = resCopy
+	}
+	result["resources"] = filteredRes
+	return result
+}
+
+// filterMethodsByStrictMode removes methods incompatible with the active strict mode.
+// Returns the original map unmodified when strict mode is off.
+func filterMethodsByStrictMode(methods map[string]interface{}, mode core.StrictMode) map[string]interface{} {
+	if !mode.IsActive() || methods == nil {
+		return methods
+	}
+	token := registry.IdentityToAccessToken(string(mode.ForcedIdentity()))
+	filtered := make(map[string]interface{}, len(methods))
+	for name, val := range methods {
+		m, ok := val.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		tokens, _ := m["accessTokens"].([]interface{})
+		if tokens == nil {
+			filtered[name] = val
+			continue
+		}
+		for _, t := range tokens {
+			if ts, ok := t.(string); ok && ts == token {
+				filtered[name] = val
+				break
+			}
+		}
+	}
+	return filtered
+}

cmd/schema/schema_test.go

@@ -182,3 +182,49 @@ func TestHasFileFields(t *testing.T) {
 		})
 	}
 }
+
+func TestCompleteSchemaPathForSpec(t *testing.T) {
+	resources := map[string]interface{}{
+		"records": map[string]interface{}{
+			"methods": map[string]interface{}{
+				"create": map[string]interface{}{},
+				"list":   map[string]interface{}{},
+			},
+		},
+		"record_permissions": map[string]interface{}{
+			"methods": map[string]interface{}{
+				"get": map[string]interface{}{},
+			},
+		},
+	}
+
+	got := completeSchemaPathForSpec("base", resources, "records.cr")
+	if len(got) != 1 || got[0] != "base.records.create" {
+		t.Fatalf("completions = %v, want [base.records.create]", got)
+	}
+
+	got = completeSchemaPathForSpec("base", resources, "record")
+	if len(got) != 2 || got[0] != "base.record_permissions." || got[1] != "base.records." {
+		t.Fatalf("resource completions = %v", got)
+	}
+}
+
+func TestFilterSpecByStrictMode_RemovesIncompatibleMethodsFromCompletionSource(t *testing.T) {
+	spec := map[string]interface{}{
+		"resources": map[string]interface{}{
+			"records": map[string]interface{}{
+				"methods": map[string]interface{}{
+					"list":   map[string]interface{}{"accessTokens": []interface{}{"tenant"}},
+					"create": map[string]interface{}{"accessTokens": []interface{}{"user"}},
+				},
+			},
+		},
+	}
+
+	filtered := filterSpecByStrictMode(spec, core.StrictModeBot)
+	resources, _ := filtered["resources"].(map[string]interface{})
+	got := completeSchemaPathForSpec("base", resources, "records.")
+	if len(got) != 1 || got[0] != "base.records.list" {
+		t.Fatalf("filtered completions = %v, want [base.records.list]", got)
+	}
+}

cmd/service/service.go

@@ -24,6 +24,10 @@ import (
 
 // RegisterServiceCommands registers all service commands from from_meta specs.
 func RegisterServiceCommands(parent *cobra.Command, f *cmdutil.Factory) {
+	RegisterServiceCommandsWithContext(context.Background(), parent, f)
+}
+
+func RegisterServiceCommandsWithContext(ctx context.Context, parent *cobra.Command, f *cmdutil.Factory) {
 	for _, project := range registry.ListFromMetaProjects() {
 		spec := registry.LoadFromMeta(project)
 		if spec == nil {
@@ -38,11 +42,15 @@ func RegisterServiceCommands(parent *cobra.Command, f *cmdutil.Factory) {
 		if resources == nil {
 			continue
 		}
-		registerService(parent, spec, resources, f)
+		registerServiceWithContext(ctx, parent, spec, resources, f)
 	}
 }
 
 func registerService(parent *cobra.Command, spec map[string]interface{}, resources map[string]interface{}, f *cmdutil.Factory) {
+	registerServiceWithContext(context.Background(), parent, spec, resources, f)
+}
+
+func registerServiceWithContext(ctx context.Context, parent *cobra.Command, spec map[string]interface{}, resources map[string]interface{}, f *cmdutil.Factory) {
 	specName := registry.GetStrFromMap(spec, "name")
 	specDesc := registry.GetServiceDescription(specName, "en")
 	if specDesc == "" {
@@ -70,11 +78,11 @@ func registerService(parent *cobra.Command, spec map[string]interface{}, resourc
 		if resMap == nil {
 			continue
 		}
-		registerResource(svc, spec, resName, resMap, f)
+		registerResourceWithContext(ctx, svc, spec, resName, resMap, f)
 	}
 }
 
-func registerResource(parent *cobra.Command, spec map[string]interface{}, name string, resource map[string]interface{}, f *cmdutil.Factory) {
+func registerResourceWithContext(ctx context.Context, parent *cobra.Command, spec map[string]interface{}, name string, resource map[string]interface{}, f *cmdutil.Factory) {
 	res := &cobra.Command{
 		Use:   name,
 		Short: name + " operations",
@@ -87,7 +95,7 @@ func registerResource(parent *cobra.Command, spec map[string]interface{}, name s
 		if methodMap == nil {
 			continue
 		}
-		registerMethod(res, spec, methodMap, methodName, name, f)
+		registerMethodWithContext(ctx, res, spec, methodMap, methodName, name, f)
 	}
 }
 
@@ -101,16 +109,16 @@ type ServiceMethodOptions struct {
 	SchemaPath string
 
 	// Flags
-	Params    string
-	Data      string
-	As        core.Identity
-	Output    string
-	PageAll   bool
-	PageLimit int
-	PageDelay int
-	Format    string
-	JqExpr    string
-	DryRun    bool
+	Params     string
+	Data       string
+	As         core.Identity
+	Output     string
+	PageAll    bool
+	PageLimit  int
+	PageDelay  int
+	Format     string
+	JqExpr     string
+	DryRun     bool
 	File       string   // --file flag value
 	FileFields []string // auto-detected file field names from metadata
 }
@@ -120,12 +128,16 @@ func detectFileFields(method map[string]interface{}) []string {
 	return cmdutil.DetectFileFields(method)
 }
 
-func registerMethod(parent *cobra.Command, spec map[string]interface{}, method map[string]interface{}, name string, resName string, f *cmdutil.Factory) {
-	parent.AddCommand(NewCmdServiceMethod(f, spec, method, name, resName, nil))
+func registerMethodWithContext(ctx context.Context, parent *cobra.Command, spec map[string]interface{}, method map[string]interface{}, name string, resName string, f *cmdutil.Factory) {
+	parent.AddCommand(NewCmdServiceMethodWithContext(ctx, f, spec, method, name, resName, nil))
 }
 
 // NewCmdServiceMethod creates a command for a dynamically registered service method.
 func NewCmdServiceMethod(f *cmdutil.Factory, spec, method map[string]interface{}, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
+	return NewCmdServiceMethodWithContext(context.Background(), f, spec, method, name, resName, runF)
+}
+
+func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spec, method map[string]interface{}, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
 	desc := registry.GetStrFromMap(method, "description")
 	httpMethod := registry.GetStrFromMap(method, "httpMethod")
 	specName := registry.GetStrFromMap(spec, "name")
@@ -159,7 +171,7 @@ func NewCmdServiceMethod(f *cmdutil.Factory, spec, method map[string]interface{}
 	case "POST", "PUT", "PATCH", "DELETE":
 		cmd.Flags().StringVar(&opts.Data, "data", "", "request body JSON (supports - for stdin)")
 	}
-	cmd.Flags().StringVar(&asStr, "as", "auto", "identity type: user | bot | auto (default)")
+	cmdutil.AddAPIIdentityFlag(ctx, cmd, f, &asStr)
 	cmd.Flags().StringVarP(&opts.Output, "output", "o", "", "output file path for binary responses")
 	cmd.Flags().BoolVar(&opts.PageAll, "page-all", false, "automatically paginate through all pages")
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
@@ -177,11 +189,7 @@ func NewCmdServiceMethod(f *cmdutil.Factory, spec, method map[string]interface{}
 			cmd.Flags().StringVar(&opts.File, "file", "", "file to upload ([field=]path, supports - for stdin)")
 		}
 	}
-
-	_ = cmd.RegisterFlagCompletionFunc("as", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
-		return []string{"user", "bot"}, cobra.ShellCompDirectiveNoFileComp
-	})
-	_ = cmd.RegisterFlagCompletionFunc("format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
 		return []string{"json", "ndjson", "table", "csv"}, cobra.ShellCompDirectiveNoFileComp
 	})
 
@@ -264,13 +272,14 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 		return output.ErrNetwork("API call failed: %s", err)
 	}
 	return client.HandleResponse(resp, client.ResponseOptions{
-		OutputPath: opts.Output,
-		Format:     format,
-		JqExpr:     opts.JqExpr,
-		Out:        out,
-		ErrOut:     f.IOStreams.ErrOut,
-		FileIO:     f.ResolveFileIO(opts.Ctx),
-		CheckError: checkErr,
+		OutputPath:  opts.Output,
+		Format:      format,
+		JqExpr:      opts.JqExpr,
+		Out:         out,
+		ErrOut:      f.IOStreams.ErrOut,
+		FileIO:      f.ResolveFileIO(opts.Ctx),
+		CommandPath: opts.Cmd.CommandPath(),
+		CheckError:  checkErr,
 	})
 }
 

cmd/service/service_test.go

@@ -121,6 +121,24 @@ func TestRegisterService_MergesExistingCommand(t *testing.T) {
 	}
 }
 
+func TestNewCmdServiceMethod_StrictModeHidesAsFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu, SupportedIdentities: 2,
+	})
+
+	cmd := NewCmdServiceMethod(f, driveSpec(), driveMethod("GET", nil), "copy", "files", nil)
+	flag := cmd.Flags().Lookup("as")
+	if flag == nil {
+		t.Fatal("expected --as flag to be registered")
+	}
+	if !flag.Hidden {
+		t.Fatal("expected --as flag to be hidden in strict mode")
+	}
+	if got := flag.DefValue; got != "bot" {
+		t.Fatalf("default value = %q, want %q", got, "bot")
+	}
+}
+
 // ── NewCmdServiceMethod flags ──
 
 func TestNewCmdServiceMethod_GETHasNoDataFlag(t *testing.T) {

extension/contentsafety/registry.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package contentsafety
+
+import "sync"
+
+var (
+	mu       sync.Mutex
+	provider Provider
+)
+
+// Register installs a content-safety Provider. Later registrations
+// override earlier ones (last-write-wins).
+// Typically called from init() via blank import.
+func Register(p Provider) {
+	mu.Lock()
+	defer mu.Unlock()
+	provider = p
+}
+
+// GetProvider returns the currently registered Provider.
+// Returns nil if no provider has been registered.
+func GetProvider() Provider {
+	mu.Lock()
+	defer mu.Unlock()
+	return provider
+}

extension/contentsafety/types.go

@@ -0,0 +1,29 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package contentsafety
+
+import (
+	"context"
+	"io"
+)
+
+// Provider scans parsed response data for content-safety issues.
+// Implementations must be safe for concurrent use.
+type Provider interface {
+	Name() string
+	Scan(ctx context.Context, req ScanRequest) (*Alert, error)
+}
+
+// ScanRequest carries the data to scan.
+type ScanRequest struct {
+	Path   string    // normalized command path (e.g. "im.messages_search")
+	Data   any       // parsed response data (generic JSON shape)
+	ErrOut io.Writer // stderr for provider-level notices (e.g. lazy-config creation)
+}
+
+// Alert holds the result of a content-safety scan that detected issues.
+type Alert struct {
+	Provider     string   `json:"provider"`
+	MatchedRules []string `json:"matched_rules"`
+}

extension/contentsafety/types_test.go

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package contentsafety
+
+import (
+	"context"
+	"io"
+	"testing"
+)
+
+func TestAlertFields(t *testing.T) {
+	a := &Alert{
+		Provider:     "regex",
+		MatchedRules: []string{"rule_a", "rule_b"},
+	}
+	if a.Provider != "regex" {
+		t.Errorf("Provider = %q, want %q", a.Provider, "regex")
+	}
+	if len(a.MatchedRules) != 2 {
+		t.Errorf("MatchedRules length = %d, want 2", len(a.MatchedRules))
+	}
+}
+
+type stubProvider struct{}
+
+func (s *stubProvider) Name() string { return "stub" }
+func (s *stubProvider) Scan(_ context.Context, _ ScanRequest) (*Alert, error) {
+	return &Alert{Provider: "stub", MatchedRules: []string{"test"}}, nil
+}
+
+func TestProviderInterface(t *testing.T) {
+	var p Provider = &stubProvider{}
+	if p.Name() != "stub" {
+		t.Errorf("Name() = %q, want %q", p.Name(), "stub")
+	}
+	alert, err := p.Scan(context.Background(), ScanRequest{Path: "test", Data: nil, ErrOut: io.Discard})
+	if err != nil {
+		t.Fatalf("Scan() error = %v", err)
+	}
+	if alert.Provider != "stub" {
+		t.Errorf("alert.Provider = %q, want %q", alert.Provider, "stub")
+	}
+}
+
+func TestRegistryLastWriteWins(t *testing.T) {
+	mu.Lock()
+	old := provider
+	provider = nil
+	mu.Unlock()
+	defer func() {
+		mu.Lock()
+		provider = old
+		mu.Unlock()
+	}()
+
+	if GetProvider() != nil {
+		t.Fatal("expected nil provider initially")
+	}
+	p1 := &stubProvider{}
+	Register(p1)
+	if GetProvider() != p1 {
+		t.Fatal("expected p1 after first Register")
+	}
+	p2 := &stubProvider{}
+	Register(p2)
+	if GetProvider() != p2 {
+		t.Fatal("expected p2 after second Register (last-write-wins)")
+	}
+}

extension/credential/registry.go

@@ -3,7 +3,10 @@
 
 package credential
 
-import "sync"
+import (
+	"sort"
+	"sync"
+)
 
 var (
 	mu        sync.Mutex
@@ -11,12 +14,28 @@ var (
 )
 
 // Register registers a credential Provider.
-// Providers are consulted in registration order.
+// Providers are consulted in priority order (lowest value first).
+// Providers that implement Priority() int are sorted accordingly;
+// those that do not default to priority 10.
 // Typically called from init() via blank import.
 func Register(p Provider) {
 	mu.Lock()
 	defer mu.Unlock()
 	providers = append(providers, p)
+	sort.SliceStable(providers, func(i, j int) bool {
+		return providerPriority(providers[i]) < providerPriority(providers[j])
+	})
+}
+
+// providerPriority returns the priority of a provider.
+// If the provider implements interface{ Priority() int }, that value is used;
+// otherwise 10 is returned as the default priority.
+// Lower values are consulted first.
+func providerPriority(p Provider) int {
+	if pp, ok := p.(interface{ Priority() int }); ok {
+		return pp.Priority()
+	}
+	return 10
 }
 
 // Providers returns all registered providers (snapshot).

extension/credential/registry_test.go

@@ -37,6 +37,32 @@ func TestRegisterAndProviders(t *testing.T) {
 	}
 }
 
+type priorityProvider struct {
+	stubProvider
+	priority int
+}
+
+func (p *priorityProvider) Priority() int { return p.priority }
+
+func TestRegister_PriorityOrder(t *testing.T) {
+	mu.Lock()
+	old := providers
+	providers = nil
+	mu.Unlock()
+	defer func() { mu.Lock(); providers = old; mu.Unlock() }()
+
+	Register(&stubProvider{name: "env"})                                                  // priority 10 (default)
+	Register(&priorityProvider{stubProvider: stubProvider{name: "sidecar"}, priority: 0}) // priority 0 (first)
+
+	got := Providers()
+	if len(got) != 2 {
+		t.Fatalf("expected 2, got %d", len(got))
+	}
+	if got[0].Name() != "sidecar" || got[1].Name() != "env" {
+		t.Errorf("expected sidecar before env, got %s, %s", got[0].Name(), got[1].Name())
+	}
+}
+
 func TestProviders_ReturnsSnapshot(t *testing.T) {
 	mu.Lock()
 	old := providers

extension/credential/sidecar/provider.go

@@ -0,0 +1,131 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar
+
+// Package sidecar provides a noop credential provider for the auth sidecar
+// proxy mode. When LARKSUITE_CLI_AUTH_PROXY is set, this provider supplies
+// placeholder credentials so the CLI's auth pipeline can proceed normally.
+// Real tokens are never present in the sandbox; the sidecar transport
+// interceptor routes requests to the trusted sidecar process instead.
+package sidecar
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/envvars"
+	"github.com/larksuite/cli/sidecar"
+)
+
+// Provider is the noop credential provider for sidecar mode.
+type Provider struct{}
+
+func (p *Provider) Name() string  { return "sidecar" }
+func (p *Provider) Priority() int { return 0 }
+
+// ResolveAccount returns a minimal Account when sidecar mode is active.
+// The account contains AppID and Brand from environment variables, a
+// placeholder secret, and SupportedIdentities derived from STRICT_MODE.
+// Returns nil, nil when sidecar mode is not active (AUTH_PROXY not set).
+func (p *Provider) ResolveAccount(ctx context.Context) (*credential.Account, error) {
+	proxyAddr := os.Getenv(envvars.CliAuthProxy)
+	if proxyAddr == "" {
+		return nil, nil // not in sidecar mode, skip
+	}
+
+	if err := sidecar.ValidateProxyAddr(proxyAddr); err != nil {
+		return nil, &credential.BlockError{
+			Provider: "sidecar",
+			Reason:   fmt.Sprintf("invalid %s %q: %v", envvars.CliAuthProxy, proxyAddr, err),
+		}
+	}
+
+	appID := os.Getenv(envvars.CliAppID)
+	if appID == "" {
+		return nil, &credential.BlockError{
+			Provider: "sidecar",
+			Reason:   envvars.CliAuthProxy + " is set but " + envvars.CliAppID + " is missing",
+		}
+	}
+
+	if os.Getenv(envvars.CliProxyKey) == "" {
+		return nil, &credential.BlockError{
+			Provider: "sidecar",
+			Reason:   envvars.CliAuthProxy + " is set but " + envvars.CliProxyKey + " is missing",
+		}
+	}
+
+	brand := credential.Brand(os.Getenv(envvars.CliBrand))
+	if brand == "" {
+		brand = credential.BrandFeishu
+	}
+
+	acct := &credential.Account{
+		AppID:     appID,
+		AppSecret: credential.NoAppSecret,
+		Brand:     brand,
+	}
+
+	// Parse DefaultAs
+	switch id := credential.Identity(os.Getenv(envvars.CliDefaultAs)); id {
+	case "", credential.IdentityAuto:
+		acct.DefaultAs = id
+	case credential.IdentityUser, credential.IdentityBot:
+		acct.DefaultAs = id
+	default:
+		return nil, &credential.BlockError{
+			Provider: "sidecar",
+			Reason:   fmt.Sprintf("invalid %s %q (want user, bot, or auto)", envvars.CliDefaultAs, id),
+		}
+	}
+
+	// Parse SupportedIdentities from STRICT_MODE, default to SupportsAll.
+	switch strictMode := os.Getenv(envvars.CliStrictMode); strictMode {
+	case "bot":
+		acct.SupportedIdentities = credential.SupportsBot
+	case "user":
+		acct.SupportedIdentities = credential.SupportsUser
+	case "off", "":
+		acct.SupportedIdentities = credential.SupportsAll
+	default:
+		return nil, &credential.BlockError{
+			Provider: "sidecar",
+			Reason:   fmt.Sprintf("invalid %s %q (want bot, user, or off)", envvars.CliStrictMode, strictMode),
+		}
+	}
+
+	return acct, nil
+}
+
+// ResolveToken returns a sentinel token whose value encodes the token type.
+// The transport interceptor reads this sentinel to determine the identity
+// (user vs bot), strips it, and the sidecar injects the real token.
+// Returns nil, nil when sidecar mode is not active.
+func (p *Provider) ResolveToken(ctx context.Context, req credential.TokenSpec) (*credential.Token, error) {
+	if os.Getenv(envvars.CliAuthProxy) == "" {
+		return nil, nil
+	}
+
+	var sentinel string
+	switch req.Type {
+	case credential.TokenTypeUAT:
+		sentinel = sidecar.SentinelUAT
+	case credential.TokenTypeTAT:
+		sentinel = sidecar.SentinelTAT
+	default:
+		return nil, nil
+	}
+
+	return &credential.Token{
+		Value:  sentinel,
+		Scopes: "", // empty → scope pre-check is skipped
+		Source: "sidecar",
+	}, nil
+}
+
+func init() {
+	credential.Register(&Provider{})
+}

extension/credential/sidecar/provider_test.go

@@ -0,0 +1,188 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar
+
+package sidecar
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/envvars"
+	"github.com/larksuite/cli/sidecar"
+)
+
+func setEnv(t *testing.T, key, value string) {
+	t.Helper()
+	old, hadOld := os.LookupEnv(key)
+	os.Setenv(key, value)
+	t.Cleanup(func() {
+		if hadOld {
+			os.Setenv(key, old)
+		} else {
+			os.Unsetenv(key)
+		}
+	})
+}
+
+func unsetEnv(t *testing.T, key string) {
+	t.Helper()
+	old, hadOld := os.LookupEnv(key)
+	os.Unsetenv(key)
+	t.Cleanup(func() {
+		if hadOld {
+			os.Setenv(key, old)
+		}
+	})
+}
+
+func TestResolveAccount_NotActive(t *testing.T) {
+	unsetEnv(t, envvars.CliAuthProxy)
+
+	p := &Provider{}
+	acct, err := p.ResolveAccount(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if acct != nil {
+		t.Fatal("expected nil account when AUTH_PROXY not set")
+	}
+}
+
+func TestResolveAccount_Active(t *testing.T) {
+	setEnv(t, envvars.CliAuthProxy, "http://127.0.0.1:16384")
+	setEnv(t, envvars.CliProxyKey, "test-key")
+	setEnv(t, envvars.CliAppID, "cli_test123")
+	setEnv(t, envvars.CliBrand, "lark")
+	unsetEnv(t, envvars.CliDefaultAs)
+	unsetEnv(t, envvars.CliStrictMode)
+
+	p := &Provider{}
+	acct, err := p.ResolveAccount(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if acct == nil {
+		t.Fatal("expected non-nil account")
+	}
+	if acct.AppID != "cli_test123" {
+		t.Errorf("AppID = %q, want %q", acct.AppID, "cli_test123")
+	}
+	if acct.Brand != credential.BrandLark {
+		t.Errorf("Brand = %q, want %q", acct.Brand, credential.BrandLark)
+	}
+	if acct.AppSecret != credential.NoAppSecret {
+		t.Errorf("AppSecret should be NoAppSecret, got %q", acct.AppSecret)
+	}
+	if acct.SupportedIdentities != credential.SupportsAll {
+		t.Errorf("SupportedIdentities = %d, want %d (SupportsAll)", acct.SupportedIdentities, credential.SupportsAll)
+	}
+}
+
+func TestResolveAccount_MissingProxyKey(t *testing.T) {
+	setEnv(t, envvars.CliAuthProxy, "http://127.0.0.1:16384")
+	unsetEnv(t, envvars.CliProxyKey)
+	setEnv(t, envvars.CliAppID, "cli_test")
+
+	p := &Provider{}
+	_, err := p.ResolveAccount(context.Background())
+	if err == nil {
+		t.Fatal("expected error when PROXY_KEY is missing")
+	}
+	if _, ok := err.(*credential.BlockError); !ok {
+		t.Fatalf("expected BlockError, got %T: %v", err, err)
+	}
+}
+
+func TestResolveAccount_MissingAppID(t *testing.T) {
+	setEnv(t, envvars.CliAuthProxy, "http://127.0.0.1:16384")
+	setEnv(t, envvars.CliProxyKey, "test-key")
+	unsetEnv(t, envvars.CliAppID)
+
+	p := &Provider{}
+	_, err := p.ResolveAccount(context.Background())
+	if err == nil {
+		t.Fatal("expected error when APP_ID is missing")
+	}
+	if _, ok := err.(*credential.BlockError); !ok {
+		t.Fatalf("expected BlockError, got %T: %v", err, err)
+	}
+}
+
+func TestResolveAccount_StrictMode(t *testing.T) {
+	setEnv(t, envvars.CliAuthProxy, "http://127.0.0.1:16384")
+	setEnv(t, envvars.CliProxyKey, "test-key")
+	setEnv(t, envvars.CliAppID, "cli_test")
+
+	tests := []struct {
+		mode string
+		want credential.IdentitySupport
+	}{
+		{"bot", credential.SupportsBot},
+		{"user", credential.SupportsUser},
+		{"off", credential.SupportsAll},
+		{"", credential.SupportsAll},
+	}
+
+	p := &Provider{}
+	for _, tt := range tests {
+		t.Run("strict_"+tt.mode, func(t *testing.T) {
+			if tt.mode == "" {
+				unsetEnv(t, envvars.CliStrictMode)
+			} else {
+				setEnv(t, envvars.CliStrictMode, tt.mode)
+			}
+			acct, err := p.ResolveAccount(context.Background())
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if acct.SupportedIdentities != tt.want {
+				t.Errorf("SupportedIdentities = %d, want %d", acct.SupportedIdentities, tt.want)
+			}
+		})
+	}
+}
+
+func TestResolveToken_NotActive(t *testing.T) {
+	unsetEnv(t, envvars.CliAuthProxy)
+
+	p := &Provider{}
+	tok, err := p.ResolveToken(context.Background(), credential.TokenSpec{Type: credential.TokenTypeUAT})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if tok != nil {
+		t.Fatal("expected nil token when AUTH_PROXY not set")
+	}
+}
+
+func TestResolveToken_Sentinels(t *testing.T) {
+	setEnv(t, envvars.CliAuthProxy, "http://127.0.0.1:16384")
+	setEnv(t, envvars.CliProxyKey, "test-key")
+
+	p := &Provider{}
+
+	// UAT
+	tok, err := p.ResolveToken(context.Background(), credential.TokenSpec{Type: credential.TokenTypeUAT})
+	if err != nil {
+		t.Fatalf("UAT: unexpected error: %v", err)
+	}
+	if tok.Value != sidecar.SentinelUAT {
+		t.Errorf("UAT value = %q, want %q", tok.Value, sidecar.SentinelUAT)
+	}
+	if tok.Scopes != "" {
+		t.Errorf("UAT scopes should be empty, got %q", tok.Scopes)
+	}
+
+	// TAT
+	tok, err = p.ResolveToken(context.Background(), credential.TokenSpec{Type: credential.TokenTypeTAT})
+	if err != nil {
+		t.Fatalf("TAT: unexpected error: %v", err)
+	}
+	if tok.Value != sidecar.SentinelTAT {
+		t.Errorf("TAT value = %q, want %q", tok.Value, sidecar.SentinelTAT)
+	}
+}

extension/transport/errors.go

@@ -0,0 +1,51 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"errors"
+	"fmt"
+)
+
+// ErrAborted is a sentinel matched by errors.Is on any extension-triggered
+// round-trip abort. Callers that only need to know whether an error was
+// caused by an extension interception should use:
+//
+//	if errors.Is(err, transport.ErrAborted) { ... }
+var ErrAborted = errors.New("round trip aborted by extension")
+
+// AbortError is returned by the built-in middleware when an AbortableInterceptor
+// short-circuits a request via PreRoundTripE. It wraps the extension's original
+// reason and carries the extension's Provider.Name() for traceability.
+//
+// Use errors.As to recover the typed error:
+//
+//	var aErr *transport.AbortError
+//	if errors.As(err, &aErr) {
+//	    log.Printf("blocked by %s: %v", aErr.Extension, aErr.Reason)
+//	}
+//
+// errors.Is(err, transport.ErrAborted) also works, and errors.Is against the
+// inner reason still works via Unwrap.
+type AbortError struct {
+	// Extension is the name of the Provider whose interceptor aborted the
+	// request (from Provider.Name()). May be empty if the provider did not
+	// supply a name.
+	Extension string
+	// Reason is the original non-nil error returned by PreRoundTripE.
+	Reason error
+}
+
+func (e *AbortError) Error() string {
+	if e.Extension != "" {
+		return fmt.Sprintf("extension %q aborted round trip: %v", e.Extension, e.Reason)
+	}
+	return fmt.Sprintf("extension aborted round trip: %v", e.Reason)
+}
+
+// Unwrap lets errors.Is / errors.As traverse to the underlying Reason.
+func (e *AbortError) Unwrap() error { return e.Reason }
+
+// Is enables errors.Is(err, ErrAborted) at any nesting depth.
+func (e *AbortError) Is(target error) bool { return target == ErrAborted }

extension/transport/errors_test.go

@@ -0,0 +1,103 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestAbortError_Error(t *testing.T) {
+	tests := []struct {
+		name string
+		err  *AbortError
+		want string
+	}{
+		{
+			name: "with extension name",
+			err:  &AbortError{Extension: "audit", Reason: errors.New("bad")},
+			want: `extension "audit" aborted round trip: bad`,
+		},
+		{
+			name: "without extension name",
+			err:  &AbortError{Reason: errors.New("bad")},
+			want: "extension aborted round trip: bad",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.err.Error(); got != tt.want {
+				t.Fatalf("Error() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestAbortError_Unwrap(t *testing.T) {
+	reason := errors.New("bad")
+	e := &AbortError{Reason: reason}
+	if got := e.Unwrap(); got != reason {
+		t.Fatalf("Unwrap() = %v, want %v", got, reason)
+	}
+}
+
+func TestAbortError_IsErrAborted(t *testing.T) {
+	e := &AbortError{Reason: errors.New("bad")}
+	if !errors.Is(e, ErrAborted) {
+		t.Fatal("errors.Is(e, ErrAborted) = false, want true")
+	}
+	// Sanity: not matched by unrelated sentinels.
+	if errors.Is(e, errors.New("other")) {
+		t.Fatal("errors.Is matched unrelated sentinel")
+	}
+}
+
+func TestAbortError_UnwrapReachesInnerSentinel(t *testing.T) {
+	// Extensions often return typed/sentinel errors; callers should still be
+	// able to errors.Is against those after the middleware wraps them.
+	innerSentinel := errors.New("policy-deny-42")
+	e := &AbortError{Reason: fmt.Errorf("wrapped: %w", innerSentinel)}
+	if !errors.Is(e, innerSentinel) {
+		t.Fatal("errors.Is(e, innerSentinel) = false, want true (Unwrap chain broken)")
+	}
+}
+
+func TestAbortError_As(t *testing.T) {
+	reason := errors.New("bad")
+	base := &AbortError{Extension: "audit", Reason: reason}
+
+	// Direct As.
+	var aErr *AbortError
+	if !errors.As(base, &aErr) {
+		t.Fatal("errors.As(base, *AbortError) = false")
+	}
+	if aErr.Extension != "audit" || aErr.Reason != reason {
+		t.Fatalf("aErr = %+v, want {audit, bad}", aErr)
+	}
+
+	// Nested As: even when the *AbortError is wrapped in another error,
+	// errors.As must still find it via Unwrap chain.
+	wrapped := fmt.Errorf("outer: %w", base)
+	var aErr2 *AbortError
+	if !errors.As(wrapped, &aErr2) {
+		t.Fatal("errors.As(wrapped, *AbortError) = false")
+	}
+	if aErr2 != base {
+		t.Fatalf("aErr2 = %p, want %p", aErr2, base)
+	}
+
+	// errors.Is still matches the sentinel through the outer wrapper.
+	if !errors.Is(wrapped, ErrAborted) {
+		t.Fatal("errors.Is(wrapped, ErrAborted) = false via nested wrap")
+	}
+}
+
+func TestErrAborted_IsItselfSentinel(t *testing.T) {
+	// Guard against accidental re-assignment of ErrAborted: a bare ErrAborted
+	// value should still satisfy errors.Is(err, ErrAborted) for symmetry.
+	if !errors.Is(ErrAborted, ErrAborted) {
+		t.Fatal("errors.Is(ErrAborted, ErrAborted) = false")
+	}
+}

extension/transport/sidecar/interceptor.go

@@ -0,0 +1,178 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar
+
+// Package sidecar provides a transport interceptor for the auth sidecar
+// proxy mode. When LARKSUITE_CLI_AUTH_PROXY is set (an HTTP URL), all
+// outgoing requests are rewritten to the sidecar address. The interceptor
+// strips placeholder credentials, injects proxy headers, and signs each
+// request with HMAC-SHA256. No custom DialContext is needed — Go's
+// standard http.Transport connects to the sidecar via plain HTTP.
+package sidecar
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+
+	"github.com/larksuite/cli/extension/transport"
+	"github.com/larksuite/cli/internal/envvars"
+	"github.com/larksuite/cli/sidecar"
+)
+
+// Provider implements transport.Provider for the sidecar mode.
+type Provider struct{}
+
+func (p *Provider) Name() string { return "sidecar" }
+
+// ResolveInterceptor returns a SidecarInterceptor when sidecar mode is active.
+// Returns nil when sidecar mode is disabled or the proxy address is invalid;
+// in the latter case a warning is emitted to stderr and requests fall back to
+// the non-sidecar transport path (where the credential layer will typically
+// block them for lack of a valid account).
+func (p *Provider) ResolveInterceptor(ctx context.Context) transport.Interceptor {
+	proxyAddr := os.Getenv(envvars.CliAuthProxy)
+	if proxyAddr == "" {
+		return nil
+	}
+	if err := sidecar.ValidateProxyAddr(proxyAddr); err != nil {
+		fmt.Fprintf(os.Stderr, "WARNING: invalid %s, sidecar interceptor disabled: %v\n", envvars.CliAuthProxy, err)
+		return nil
+	}
+	key := os.Getenv(envvars.CliProxyKey)
+	return &Interceptor{
+		key:         []byte(key),
+		sidecarHost: sidecar.ProxyHost(proxyAddr),
+	}
+}
+
+// Interceptor rewrites requests for the sidecar proxy.
+type Interceptor struct {
+	key         []byte // HMAC signing key
+	sidecarHost string // sidecar host:port for URL rewriting
+}
+
+// PreRoundTrip rewrites the request for sidecar routing when it carries a
+// sentinel token. Requests without a sentinel token (e.g. pre-signed download
+// URLs) are passed through unmodified.
+//
+// Supports two auth patterns:
+//   - Standard OpenAPI: Authorization: Bearer <sentinel>
+//   - MCP protocol:     X-Lark-MCP-UAT/TAT: <sentinel>
+func (i *Interceptor) PreRoundTrip(req *http.Request) func(resp *http.Response, err error) {
+	identity, authHeader := detectSentinel(req)
+	if identity == "" {
+		return nil // not a sidecar-managed request, pass through
+	}
+
+	// 1. Buffer the body first, before mutating any request state. A partial
+	// read would sign a truncated body and cause a misleading HMAC mismatch
+	// on the sidecar side; bail out early and let the request fall through
+	// unmodified so the credential layer can surface an actionable error.
+	var bodyBytes []byte
+	if req.Body != nil {
+		var err error
+		bodyBytes, err = io.ReadAll(req.Body)
+		_ = req.Body.Close() // release original body (fd/pipe/etc.) after buffering
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "WARNING: sidecar interceptor failed to read request body: %v\n", err)
+			return nil
+		}
+		req.Body = io.NopCloser(bytes.NewReader(bodyBytes))
+		if req.GetBody != nil {
+			req.GetBody = func() (io.ReadCloser, error) {
+				return io.NopCloser(bytes.NewReader(bodyBytes)), nil
+			}
+		}
+	}
+
+	// 2. Save original target (scheme://host)
+	originalScheme := "https"
+	if req.URL.Scheme != "" {
+		originalScheme = req.URL.Scheme
+	}
+	originalHost := req.URL.Host
+	req.Header.Set(sidecar.HeaderProxyTarget, originalScheme+"://"+originalHost)
+
+	// 3. Set identity and tell sidecar which header to inject real token into
+	req.Header.Set(sidecar.HeaderProxyIdentity, identity)
+	req.Header.Set(sidecar.HeaderProxyAuthHeader, authHeader)
+
+	// 4. Strip placeholder auth header(s)
+	req.Header.Del("Authorization")
+	req.Header.Del(sidecar.HeaderMCPUAT)
+	req.Header.Del(sidecar.HeaderMCPTAT)
+
+	bodySHA := sidecar.BodySHA256(bodyBytes)
+	req.Header.Set(sidecar.HeaderBodySHA256, bodySHA)
+
+	pathAndQuery := req.URL.RequestURI()
+	ts := sidecar.Timestamp()
+	// Cover identity and authHeader in the signature so an on-path attacker
+	// within the replay window cannot flip the injected token's identity or
+	// redirect the token into a different header.
+	sig := sidecar.Sign(i.key, sidecar.CanonicalRequest{
+		Version:      sidecar.ProtocolV1,
+		Method:       req.Method,
+		Host:         originalHost,
+		PathAndQuery: pathAndQuery,
+		BodySHA256:   bodySHA,
+		Timestamp:    ts,
+		Identity:     identity,
+		AuthHeader:   authHeader,
+	})
+	req.Header.Set(sidecar.HeaderProxyVersion, sidecar.ProtocolV1)
+	req.Header.Set(sidecar.HeaderProxyTimestamp, ts)
+	req.Header.Set(sidecar.HeaderProxySignature, sig)
+
+	// 5. Rewrite URL to route through sidecar
+	req.URL.Scheme = "http"
+	req.URL.Host = i.sidecarHost
+
+	return nil // no post-hook needed
+}
+
+// detectSentinel checks both standard Authorization and MCP auth headers for
+// sentinel tokens. Returns the identity ("user"/"bot") and the header name
+// that carried the sentinel.
+//
+// Returns ("", "") when the request carries no sentinel token — typically
+// requests that require no auth (e.g. pre-signed download URLs where the
+// token is embedded in the URL query parameters).
+func detectSentinel(req *http.Request) (identity, authHeader string) {
+	// Check standard Authorization: Bearer <sentinel>
+	if auth := req.Header.Get("Authorization"); auth != "" {
+		token := strings.TrimPrefix(auth, "Bearer ")
+		switch token {
+		case sidecar.SentinelUAT:
+			return sidecar.IdentityUser, "Authorization"
+		case sidecar.SentinelTAT:
+			return sidecar.IdentityBot, "Authorization"
+		}
+	}
+	// Check MCP headers: X-Lark-MCP-UAT/TAT: <sentinel>
+	if v := req.Header.Get(sidecar.HeaderMCPUAT); v == sidecar.SentinelUAT {
+		return sidecar.IdentityUser, sidecar.HeaderMCPUAT
+	}
+	if v := req.Header.Get(sidecar.HeaderMCPTAT); v == sidecar.SentinelTAT {
+		return sidecar.IdentityBot, sidecar.HeaderMCPTAT
+	}
+	return "", ""
+}
+
+func init() {
+	proxyAddr := os.Getenv(envvars.CliAuthProxy)
+	if proxyAddr == "" {
+		return
+	}
+	if err := sidecar.ValidateProxyAddr(proxyAddr); err != nil {
+		fmt.Fprintf(os.Stderr, "WARNING: ignoring invalid %s: %v\n", envvars.CliAuthProxy, err)
+		return
+	}
+	transport.Register(&Provider{})
+}

extension/transport/sidecar/interceptor_test.go

@@ -0,0 +1,265 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar
+
+package sidecar
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+
+	"github.com/larksuite/cli/sidecar"
+)
+
+// failingBody is a ReadCloser that errors on Read and tracks Close calls.
+type failingBody struct {
+	err      error
+	closed   bool
+	readCall bool
+}
+
+func (b *failingBody) Read(p []byte) (int, error) {
+	b.readCall = true
+	return 0, b.err
+}
+
+func (b *failingBody) Close() error {
+	b.closed = true
+	return nil
+}
+
+func TestInterceptor_PreRoundTrip(t *testing.T) {
+	key := []byte("test-key-for-hmac-signing-32byte!")
+	interceptor := &Interceptor{key: key, sidecarHost: "127.0.0.1:16384"}
+
+	body := []byte(`{"msg":"hello"}`)
+	req, _ := http.NewRequest("POST", "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id", io.NopCloser(bytes.NewReader(body)))
+	req.Header.Set("Authorization", "Bearer "+sidecar.SentinelUAT)
+	req.Header.Set("X-Cli-Source", "lark-cli")
+
+	post := interceptor.PreRoundTrip(req)
+
+	if post != nil {
+		t.Error("expected nil post hook")
+	}
+
+	// URL should be rewritten to sidecar
+	if req.URL.Scheme != "http" {
+		t.Errorf("scheme = %q, want %q", req.URL.Scheme, "http")
+	}
+	if req.URL.Host != "127.0.0.1:16384" {
+		t.Errorf("host = %q, want %q", req.URL.Host, "127.0.0.1:16384")
+	}
+
+	// Original target should be preserved
+	target := req.Header.Get(sidecar.HeaderProxyTarget)
+	if target != "https://open.feishu.cn" {
+		t.Errorf("target = %q, want %q", target, "https://open.feishu.cn")
+	}
+
+	// Identity should be user (from SentinelUAT)
+	if identity := req.Header.Get(sidecar.HeaderProxyIdentity); identity != sidecar.IdentityUser {
+		t.Errorf("identity = %q, want %q", identity, sidecar.IdentityUser)
+	}
+
+	// Authorization should be stripped
+	if auth := req.Header.Get("Authorization"); auth != "" {
+		t.Errorf("Authorization header should be stripped, got %q", auth)
+	}
+
+	// HMAC headers should be set
+	if sig := req.Header.Get(sidecar.HeaderProxySignature); sig == "" {
+		t.Error("signature header should be set")
+	}
+	if ts := req.Header.Get(sidecar.HeaderProxyTimestamp); ts == "" {
+		t.Error("timestamp header should be set")
+	}
+	if sha := req.Header.Get(sidecar.HeaderBodySHA256); sha == "" {
+		t.Error("body SHA256 header should be set")
+	}
+	if v := req.Header.Get(sidecar.HeaderProxyVersion); v != sidecar.ProtocolV1 {
+		t.Errorf("version header = %q, want %q", v, sidecar.ProtocolV1)
+	}
+
+	// Non-proxy headers should be preserved
+	if src := req.Header.Get("X-Cli-Source"); src != "lark-cli" {
+		t.Errorf("X-Cli-Source should be preserved, got %q", src)
+	}
+
+	// Body should still be readable
+	readBody, _ := io.ReadAll(req.Body)
+	if !bytes.Equal(readBody, body) {
+		t.Errorf("body should be preserved after PreRoundTrip")
+	}
+}
+
+func TestInterceptor_BotIdentity(t *testing.T) {
+	interceptor := &Interceptor{key: []byte("key"), sidecarHost: "127.0.0.1:16384"}
+
+	req, _ := http.NewRequest("GET", "https://open.feishu.cn/open-apis/calendar/v4/events", nil)
+	req.Header.Set("Authorization", "Bearer "+sidecar.SentinelTAT)
+
+	interceptor.PreRoundTrip(req)
+
+	if identity := req.Header.Get(sidecar.HeaderProxyIdentity); identity != sidecar.IdentityBot {
+		t.Errorf("identity = %q, want %q", identity, sidecar.IdentityBot)
+	}
+}
+
+func TestInterceptor_NonSentinelToken_PassThrough(t *testing.T) {
+	interceptor := &Interceptor{key: []byte("key"), sidecarHost: "127.0.0.1:16384"}
+
+	origURL := "https://some-cdn.example.com/presigned-download?token=abc"
+	req, _ := http.NewRequest("GET", origURL, nil)
+	req.Header.Set("Authorization", "Bearer some-real-token")
+
+	post := interceptor.PreRoundTrip(req)
+
+	// Should NOT be rewritten — no sentinel token
+	if post != nil {
+		t.Error("expected nil post hook for pass-through")
+	}
+	if req.URL.String() != origURL {
+		t.Errorf("URL should be unchanged, got %q", req.URL.String())
+	}
+	if req.Header.Get(sidecar.HeaderProxyTarget) != "" {
+		t.Error("proxy target header should not be set for pass-through")
+	}
+	if req.Header.Get("Authorization") != "Bearer some-real-token" {
+		t.Error("Authorization should be preserved for pass-through")
+	}
+}
+
+func TestInterceptor_NoAuth_PassThrough(t *testing.T) {
+	interceptor := &Interceptor{key: []byte("key"), sidecarHost: "127.0.0.1:16384"}
+
+	origURL := "https://cdn.feishu.cn/download/file"
+	req, _ := http.NewRequest("GET", origURL, nil)
+
+	interceptor.PreRoundTrip(req)
+
+	// No Authorization header at all — should pass through
+	if req.URL.String() != origURL {
+		t.Errorf("URL should be unchanged for no-auth request, got %q", req.URL.String())
+	}
+}
+
+func TestInterceptor_MCP_UAT(t *testing.T) {
+	interceptor := &Interceptor{key: []byte("key"), sidecarHost: "127.0.0.1:16384"}
+
+	req, _ := http.NewRequest("POST", "https://mcp.feishu.cn/mcp/v1/tools/call", bytes.NewReader([]byte(`{"jsonrpc":"2.0"}`)))
+	req.Header.Set(sidecar.HeaderMCPUAT, sidecar.SentinelUAT)
+
+	interceptor.PreRoundTrip(req)
+
+	// Should be intercepted and rewritten
+	if req.URL.Host != "127.0.0.1:16384" {
+		t.Errorf("host = %q, want sidecar host", req.URL.Host)
+	}
+	if identity := req.Header.Get(sidecar.HeaderProxyIdentity); identity != sidecar.IdentityUser {
+		t.Errorf("identity = %q, want %q", identity, sidecar.IdentityUser)
+	}
+	if ah := req.Header.Get(sidecar.HeaderProxyAuthHeader); ah != sidecar.HeaderMCPUAT {
+		t.Errorf("auth header = %q, want %q", ah, sidecar.HeaderMCPUAT)
+	}
+	// MCP sentinel should be stripped
+	if v := req.Header.Get(sidecar.HeaderMCPUAT); v != "" {
+		t.Errorf("MCP-UAT should be stripped, got %q", v)
+	}
+}
+
+func TestInterceptor_MCP_TAT(t *testing.T) {
+	interceptor := &Interceptor{key: []byte("key"), sidecarHost: "127.0.0.1:16384"}
+
+	req, _ := http.NewRequest("POST", "https://mcp.feishu.cn/mcp/v1/tools/call", bytes.NewReader([]byte(`{}`)))
+	req.Header.Set(sidecar.HeaderMCPTAT, sidecar.SentinelTAT)
+
+	interceptor.PreRoundTrip(req)
+
+	if identity := req.Header.Get(sidecar.HeaderProxyIdentity); identity != sidecar.IdentityBot {
+		t.Errorf("identity = %q, want %q", identity, sidecar.IdentityBot)
+	}
+	if ah := req.Header.Get(sidecar.HeaderProxyAuthHeader); ah != sidecar.HeaderMCPTAT {
+		t.Errorf("auth header = %q, want %q", ah, sidecar.HeaderMCPTAT)
+	}
+}
+
+func TestInterceptor_StandardAuth_SetsAuthorizationHeader(t *testing.T) {
+	interceptor := &Interceptor{key: []byte("key"), sidecarHost: "127.0.0.1:16384"}
+
+	req, _ := http.NewRequest("GET", "https://open.feishu.cn/open-apis/test", nil)
+	req.Header.Set("Authorization", "Bearer "+sidecar.SentinelUAT)
+
+	interceptor.PreRoundTrip(req)
+
+	if ah := req.Header.Get(sidecar.HeaderProxyAuthHeader); ah != "Authorization" {
+		t.Errorf("auth header = %q, want %q", ah, "Authorization")
+	}
+}
+
+// TestInterceptor_BodyReadError verifies that when io.ReadAll on the request
+// body fails partway, PreRoundTrip skips the rewrite entirely rather than
+// signing a truncated body (which would produce a misleading HMAC mismatch on
+// the sidecar side) and releases the original body.
+func TestInterceptor_BodyReadError(t *testing.T) {
+	interceptor := &Interceptor{key: []byte("key"), sidecarHost: "127.0.0.1:16384"}
+
+	const origURL = "https://open.feishu.cn/open-apis/im/v1/messages"
+	body := &failingBody{err: errors.New("disk gremlin")}
+
+	req, _ := http.NewRequest("POST", origURL, body)
+	req.Header.Set("Authorization", "Bearer "+sidecar.SentinelUAT)
+
+	post := interceptor.PreRoundTrip(req)
+
+	if post != nil {
+		t.Error("expected nil post hook on body read failure")
+	}
+
+	// Original body must be closed to avoid leaking fd/pipe-like resources.
+	if !body.readCall {
+		t.Error("expected ReadAll to have attempted reading from the body")
+	}
+	if !body.closed {
+		t.Error("expected original body to be Close()'d after read failure")
+	}
+
+	// URL must NOT be rewritten — request should fall through to the next
+	// layer (credential) which can surface a meaningful error.
+	if req.URL.String() != origURL {
+		t.Errorf("URL should be unchanged on read failure, got %q", req.URL.String())
+	}
+
+	// No proxy/HMAC headers should leak onto the request.
+	for _, h := range []string{
+		sidecar.HeaderProxyVersion,
+		sidecar.HeaderProxyTarget,
+		sidecar.HeaderProxySignature,
+		sidecar.HeaderProxyTimestamp,
+		sidecar.HeaderBodySHA256,
+		sidecar.HeaderProxyIdentity,
+		sidecar.HeaderProxyAuthHeader,
+	} {
+		if v := req.Header.Get(h); v != "" {
+			t.Errorf("%s should not be set on read failure, got %q", h, v)
+		}
+	}
+}
+
+func TestInterceptor_EmptyBody(t *testing.T) {
+	interceptor := &Interceptor{key: []byte("key"), sidecarHost: "127.0.0.1:16384"}
+
+	req, _ := http.NewRequest("GET", "https://open.feishu.cn/path", nil)
+	req.Header.Set("Authorization", "Bearer "+sidecar.SentinelTAT)
+	interceptor.PreRoundTrip(req)
+
+	sha := req.Header.Get(sidecar.HeaderBodySHA256)
+	expectedEmpty := sidecar.BodySHA256(nil)
+	if sha != expectedEmpty {
+		t.Errorf("body SHA256 = %q, want empty-string SHA256 %q", sha, expectedEmpty)
+	}
+}

extension/transport/types.go

@@ -27,6 +27,31 @@ type Provider interface {
 //
 // The returned function (if non-nil) is called after the built-in chain
 // completes. Use it for logging, ending trace spans, or recording metrics.
+//
+// Body note: the middleware Clones the caller's request before invoking the
+// interceptor, which copies headers/URL/etc. but shares the underlying
+// io.ReadCloser. Extensions that read req.Body are responsible for restoring
+// a replayable body (e.g. via req.GetBody) before returning, otherwise the
+// built-in chain will see an exhausted stream.
 type Interceptor interface {
 	PreRoundTrip(req *http.Request) func(resp *http.Response, err error)
 }
+
+// AbortableInterceptor is an optional extension of Interceptor that lets an
+// extension reject a request before the built-in chain runs. Extensions that
+// implement this interface are detected by the built-in middleware via a
+// type assertion; both methods must be present, but when an extension
+// implements PreRoundTripE the middleware will NOT call PreRoundTrip.
+//
+// Returning a non-nil error from PreRoundTripE aborts the request: the
+// built-in chain is not executed and the middleware returns an *AbortError
+// wrapping the reason. The returned post function (if non-nil) is still
+// invoked with (nil, reason) so that extensions can unwind any state they
+// created in the pre hook (spans, metrics, audit records).
+//
+// Extensions that only care about the abortable variant can provide a no-op
+// PreRoundTrip method alongside PreRoundTripE to satisfy Interceptor.
+type AbortableInterceptor interface {
+	Interceptor
+	PreRoundTripE(req *http.Request) (post func(resp *http.Response, err error), err error)
+}

internal/auth/device_flow.go

@@ -200,7 +200,7 @@ func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSec
 		errStr := getStr(data, "error")
 
 		if errStr == "" && getStr(data, "access_token") != "" {
-			fmt.Fprintf(errOut, "[lark-cli] device-flow: token obtained successfully\n")
+			fmt.Fprintf(errOut, "[lark-cli] device-flow: token response received\n")
 			refreshToken := getStr(data, "refresh_token")
 			tokenExpiresIn := getInt(data, "expires_in", 7200)
 			refreshExpiresIn := getInt(data, "refresh_token_expires_in", 604800)

internal/binding/audit.go

@@ -0,0 +1,157 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// AuditParams holds parameters for AssertSecurePath.
+type AuditParams struct {
+	TargetPath            string
+	Label                 string // e.g. "secrets.providers.vault.command"
+	TrustedDirs           []string
+	AllowInsecurePath     bool
+	AllowReadableByOthers bool
+	AllowSymlinkPath      bool
+}
+
+// AssertSecurePath verifies that a file/command path is safe for use with
+// OpenClaw SecretRef resolution. On success it returns the effective path
+// (the symlink target, if the input was a symlink and allowed).
+//
+// The check is a short, ordered pipeline — each step below is both a read of
+// the contract and a pointer to the helper that enforces it.
+func AssertSecurePath(params AuditParams) (string, error) {
+	target := params.TargetPath
+	label := params.Label
+
+	if err := requireAbsolutePath(target, label); err != nil {
+		return "", err
+	}
+
+	linfo, err := lstatNonDir(target, label)
+	if err != nil {
+		return "", err
+	}
+
+	effectivePath, err := resolveSymlinkIfAllowed(target, linfo, params)
+	if err != nil {
+		return "", err
+	}
+
+	if err := requireInTrustedDirs(effectivePath, params.TrustedDirs, label); err != nil {
+		return "", err
+	}
+
+	if params.AllowInsecurePath {
+		return effectivePath, nil
+	}
+
+	if err := auditFilePermissions(effectivePath, params.AllowReadableByOthers, label); err != nil {
+		return "", err
+	}
+	if err := checkOwnerUID(effectivePath, label); err != nil {
+		return "", err
+	}
+	return effectivePath, nil
+}
+
+// requireAbsolutePath rejects relative paths; relative paths would depend on
+// the process cwd and defeat the point of a static audit.
+func requireAbsolutePath(target, label string) error {
+	if !filepath.IsAbs(target) {
+		return fmt.Errorf("%s: path must be absolute, got %q", label, target)
+	}
+	return nil
+}
+
+// lstatNonDir stats the path without following symlinks, rejecting
+// directories. Returns the stat info for downstream steps to reuse.
+func lstatNonDir(target, label string) (fs.FileInfo, error) {
+	info, err := vfs.Lstat(target)
+	if err != nil {
+		return nil, fmt.Errorf("%s: cannot stat %q: %w", label, target, err)
+	}
+	if info.IsDir() {
+		return nil, fmt.Errorf("%s: path %q is a directory, not a file", label, target)
+	}
+	return info, nil
+}
+
+// resolveSymlinkIfAllowed resolves a symlink to its target when
+// params.AllowSymlinkPath is true, or rejects it otherwise. When the input
+// is not a symlink, target is returned unchanged. A symlink that points to
+// another symlink is rejected so callers only deal with a single hop.
+func resolveSymlinkIfAllowed(target string, linfo fs.FileInfo, params AuditParams) (string, error) {
+	if linfo.Mode()&os.ModeSymlink == 0 {
+		return target, nil
+	}
+	if !params.AllowSymlinkPath {
+		return "", fmt.Errorf("%s: path %q is a symlink (not allowed)", params.Label, target)
+	}
+	resolved, err := vfs.EvalSymlinks(target)
+	if err != nil {
+		return "", fmt.Errorf("%s: cannot resolve symlink %q: %w", params.Label, target, err)
+	}
+	rinfo, err := vfs.Lstat(resolved)
+	if err != nil {
+		return "", fmt.Errorf("%s: cannot stat resolved path %q: %w", params.Label, resolved, err)
+	}
+	if rinfo.Mode()&os.ModeSymlink != 0 {
+		return "", fmt.Errorf("%s: resolved path %q is still a symlink", params.Label, resolved)
+	}
+	return resolved, nil
+}
+
+// requireInTrustedDirs enforces that effectivePath lives under one of the
+// caller-declared trusted directories, if any were declared. An empty
+// trustedDirs list disables the check.
+func requireInTrustedDirs(effectivePath string, trustedDirs []string, label string) error {
+	if len(trustedDirs) == 0 {
+		return nil
+	}
+	cleaned := filepath.Clean(effectivePath)
+	for _, dir := range trustedDirs {
+		cleanDir := filepath.Clean(dir)
+		if cleaned == cleanDir || strings.HasPrefix(cleaned, cleanDir+"/") {
+			return nil
+		}
+	}
+	return fmt.Errorf("%s: path %q is not inside any trusted directory", label, effectivePath)
+}
+
+// auditFilePermissions rejects world/group-writable modes (always) and
+// world/group-readable modes (unless allowReadableByOthers is true, which
+// exec commands typically need for their usual 755 mode).
+func auditFilePermissions(effectivePath string, allowReadableByOthers bool, label string) error {
+	info, err := vfs.Stat(effectivePath)
+	if err != nil {
+		return fmt.Errorf("%s: cannot stat %q: %w", label, effectivePath, err)
+	}
+	mode := info.Mode().Perm()
+
+	if mode&0o002 != 0 {
+		return fmt.Errorf("%s: path %q is world-writable (mode %04o)", label, effectivePath, mode)
+	}
+	if mode&0o020 != 0 {
+		return fmt.Errorf("%s: path %q is group-writable (mode %04o)", label, effectivePath, mode)
+	}
+	if allowReadableByOthers {
+		return nil
+	}
+	if mode&0o004 != 0 {
+		return fmt.Errorf("%s: path %q is world-readable (mode %04o)", label, effectivePath, mode)
+	}
+	if mode&0o040 != 0 {
+		return fmt.Errorf("%s: path %q is group-readable (mode %04o)", label, effectivePath, mode)
+	}
+	return nil
+}

internal/binding/audit_test.go

@@ -0,0 +1,363 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+func TestAssertSecurePath_NonAbsolutePath(t *testing.T) {
+	_, err := AssertSecurePath(AuditParams{
+		TargetPath:        "relative/path.txt",
+		Label:             "test",
+		AllowInsecurePath: true,
+	})
+	if err == nil {
+		t.Fatal("expected error for non-absolute path, got nil")
+	}
+	want := fmt.Sprintf("test: path must be absolute, got %q", "relative/path.txt")
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestAssertSecurePath_FileDoesNotExist(t *testing.T) {
+	nonexistent := filepath.Join(t.TempDir(), "nonexistent.txt")
+	_, err := AssertSecurePath(AuditParams{
+		TargetPath:        nonexistent,
+		Label:             "test",
+		AllowInsecurePath: true,
+	})
+	if err == nil {
+		t.Fatal("expected error for non-existent file, got nil")
+	}
+	wantPrefix := fmt.Sprintf("test: cannot stat %q: ", nonexistent)
+	if !strings.HasPrefix(err.Error(), wantPrefix) {
+		t.Errorf("error = %q, want prefix %q", err.Error(), wantPrefix)
+	}
+}
+
+func TestAssertSecurePath_ValidAbsolutePath(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "valid.txt")
+	if err := os.WriteFile(p, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	got, err := AssertSecurePath(AuditParams{
+		TargetPath:        p,
+		Label:             "test",
+		AllowInsecurePath: true,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != p {
+		t.Errorf("got %q, want %q", got, p)
+	}
+}
+
+func TestAssertSecurePath_WorldWritable_Rejected(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("permission tests not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	p := filepath.Join(dir, "insecure.txt")
+	if err := os.WriteFile(p, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+	if err := os.Chmod(p, 0o666); err != nil {
+		t.Fatalf("chmod: %v", err)
+	}
+
+	_, err := AssertSecurePath(AuditParams{
+		TargetPath:            p,
+		Label:                 "test",
+		AllowInsecurePath:     false,
+		AllowReadableByOthers: true, // only test writable check
+	})
+	if err == nil {
+		t.Fatal("expected error for world-writable file, got nil")
+	}
+	want := fmt.Sprintf("test: path %q is world-writable (mode 0666)", p)
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestAssertSecurePath_AllowInsecurePath_Bypasses(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("permission tests not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	p := filepath.Join(dir, "insecure.txt")
+	if err := os.WriteFile(p, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+	if err := os.Chmod(p, 0o666); err != nil {
+		t.Fatalf("chmod: %v", err)
+	}
+
+	got, err := AssertSecurePath(AuditParams{
+		TargetPath:        p,
+		Label:             "test",
+		AllowInsecurePath: true,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != p {
+		t.Errorf("got %q, want %q", got, p)
+	}
+}
+
+func TestAssertSecurePath_DirectoryRejected(t *testing.T) {
+	dir := t.TempDir()
+	_, err := AssertSecurePath(AuditParams{
+		TargetPath:        dir,
+		Label:             "test",
+		AllowInsecurePath: true,
+	})
+	if err == nil {
+		t.Fatal("expected error for directory path, got nil")
+	}
+	want := fmt.Sprintf("test: path %q is a directory, not a file", dir)
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestAssertSecurePath_GroupWritable_Rejected(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("permission tests not applicable on Windows")
+	}
+	dir := t.TempDir()
+	p := filepath.Join(dir, "groupw.txt")
+	if err := os.WriteFile(p, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	if err := os.Chmod(p, 0o620); err != nil {
+		t.Fatalf("chmod: %v", err)
+	}
+	_, err := AssertSecurePath(AuditParams{
+		TargetPath:            p,
+		Label:                 "test",
+		AllowInsecurePath:     false,
+		AllowReadableByOthers: true,
+	})
+	if err == nil {
+		t.Fatal("expected error for group-writable file, got nil")
+	}
+	want := fmt.Sprintf("test: path %q is group-writable (mode 0620)", p)
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestAssertSecurePath_WorldReadable_Rejected(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("permission tests not applicable on Windows")
+	}
+	dir := t.TempDir()
+	p := filepath.Join(dir, "worldr.txt")
+	if err := os.WriteFile(p, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	if err := os.Chmod(p, 0o604); err != nil {
+		t.Fatalf("chmod: %v", err)
+	}
+	_, err := AssertSecurePath(AuditParams{
+		TargetPath:            p,
+		Label:                 "test",
+		AllowInsecurePath:     false,
+		AllowReadableByOthers: false,
+	})
+	if err == nil {
+		t.Fatal("expected error for world-readable file, got nil")
+	}
+	want := fmt.Sprintf("test: path %q is world-readable (mode 0604)", p)
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestAssertSecurePath_AllowReadableByOthers_Passes(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("permission tests not applicable on Windows")
+	}
+	dir := t.TempDir()
+	p := filepath.Join(dir, "readable.txt")
+	if err := os.WriteFile(p, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	if err := os.Chmod(p, 0o644); err != nil {
+		t.Fatalf("chmod: %v", err)
+	}
+	got, err := AssertSecurePath(AuditParams{
+		TargetPath:            p,
+		Label:                 "test",
+		AllowInsecurePath:     false,
+		AllowReadableByOthers: true,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != p {
+		t.Errorf("got %q, want %q", got, p)
+	}
+}
+
+func TestAssertSecurePath_OwnerUID_Valid(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("owner UID tests not applicable on Windows")
+	}
+	dir := t.TempDir()
+	p := filepath.Join(dir, "owned.txt")
+	if err := os.WriteFile(p, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	got, err := AssertSecurePath(AuditParams{
+		TargetPath:            p,
+		Label:                 "test",
+		AllowInsecurePath:     false,
+		AllowReadableByOthers: true,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != p {
+		t.Errorf("got %q, want %q", got, p)
+	}
+}
+
+func TestAssertSecurePath_Symlink_Rejected(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("symlink tests not applicable on Windows")
+	}
+	dir := t.TempDir()
+	target := filepath.Join(dir, "real.txt")
+	if err := os.WriteFile(target, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	link := filepath.Join(dir, "link.txt")
+	if err := os.Symlink(target, link); err != nil {
+		t.Fatalf("symlink: %v", err)
+	}
+	_, err := AssertSecurePath(AuditParams{
+		TargetPath:        link,
+		Label:             "test",
+		AllowSymlinkPath:  false,
+		AllowInsecurePath: true,
+	})
+	if err == nil {
+		t.Fatal("expected error for symlink with AllowSymlinkPath=false, got nil")
+	}
+	want := fmt.Sprintf("test: path %q is a symlink (not allowed)", link)
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestAssertSecurePath_Symlink_Allowed(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("symlink tests not applicable on Windows")
+	}
+	dir := t.TempDir()
+	target := filepath.Join(dir, "real.txt")
+	if err := os.WriteFile(target, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	link := filepath.Join(dir, "link.txt")
+	if err := os.Symlink(target, link); err != nil {
+		t.Fatalf("symlink: %v", err)
+	}
+	got, err := AssertSecurePath(AuditParams{
+		TargetPath:        link,
+		Label:             "test",
+		AllowSymlinkPath:  true,
+		AllowInsecurePath: true,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// On macOS /var → /private/var, so compare resolved paths
+	wantResolved, err := filepath.EvalSymlinks(target)
+	if err != nil {
+		t.Fatalf("EvalSymlinks(target): %v", err)
+	}
+	if got != wantResolved {
+		t.Errorf("got %q, want resolved %q", got, wantResolved)
+	}
+}
+
+func TestAssertSecurePath_TrustedDirs_ExactMatch(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "file.txt")
+	if err := os.WriteFile(p, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	got, err := AssertSecurePath(AuditParams{
+		TargetPath:        p,
+		Label:             "test",
+		TrustedDirs:       []string{p},
+		AllowInsecurePath: true,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != p {
+		t.Errorf("got %q, want %q", got, p)
+	}
+}
+
+func TestAssertSecurePath_TrustedDirs(t *testing.T) {
+	trustedDir := t.TempDir()
+	untrustedDir := t.TempDir()
+
+	trustedFile := filepath.Join(trustedDir, "secret.txt")
+	if err := os.WriteFile(trustedFile, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	untrustedFile := filepath.Join(untrustedDir, "secret.txt")
+	if err := os.WriteFile(untrustedFile, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	// File outside trusted dir should fail
+	_, err := AssertSecurePath(AuditParams{
+		TargetPath:        untrustedFile,
+		Label:             "test",
+		TrustedDirs:       []string{trustedDir},
+		AllowInsecurePath: true,
+	})
+	if err == nil {
+		t.Fatal("expected error for file outside trusted dir, got nil")
+	}
+	want := fmt.Sprintf("test: path %q is not inside any trusted directory", untrustedFile)
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+
+	// File inside trusted dir should pass
+	got, err := AssertSecurePath(AuditParams{
+		TargetPath:        trustedFile,
+		Label:             "test",
+		TrustedDirs:       []string{trustedDir},
+		AllowInsecurePath: true,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != trustedFile {
+		t.Errorf("got %q, want %q", got, trustedFile)
+	}
+}

internal/binding/audit_unix.go

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !windows
+
+package binding
+
+import (
+	"fmt"
+	"os"
+	"syscall"
+
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// checkOwnerUID verifies the file is owned by the current user.
+func checkOwnerUID(path, label string) error {
+	stat, err := vfs.Stat(path)
+	if err != nil {
+		return fmt.Errorf("%s: cannot stat %q: %w", label, path, err)
+	}
+	sysStat, ok := stat.Sys().(*syscall.Stat_t)
+	if !ok {
+		return fmt.Errorf("%s: cannot retrieve file owner for %q", label, path)
+	}
+	if sysStat.Uid != uint32(os.Getuid()) {
+		return fmt.Errorf("%s: path %q is owned by uid %d, expected %d",
+			label, path, sysStat.Uid, os.Getuid())
+	}
+	return nil
+}

internal/binding/audit_windows.go

@@ -0,0 +1,11 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build windows
+
+package binding
+
+// checkOwnerUID is a no-op on Windows where Unix UID semantics don't apply.
+func checkOwnerUID(path, label string) error {
+	return nil
+}

internal/binding/json_pointer.go

@@ -0,0 +1,55 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"fmt"
+	"strings"
+)
+
+// ReadJSONPointer navigates a parsed JSON value (typically the result of
+// json.Unmarshal into interface{}) using an RFC 6901 JSON Pointer string.
+//
+// Supported pointer format: "/key/subkey/subsubkey".
+// An empty pointer ("") returns data as-is.
+// RFC 6901 escape sequences: ~1 → /, ~0 → ~.
+//
+// Limitation: only object (map) traversal is supported. Array index segments
+// (e.g., "/channels/0/appId") are not implemented because OpenClaw's
+// SecretRef file provider uses object-only paths in practice.
+func ReadJSONPointer(data interface{}, pointer string) (interface{}, error) {
+	if pointer == "" {
+		return data, nil
+	}
+
+	if !strings.HasPrefix(pointer, "/") {
+		return nil, fmt.Errorf("json pointer must start with '/' or be empty, got %q", pointer)
+	}
+
+	// Split after the leading "/" and decode each segment.
+	segments := strings.Split(pointer[1:], "/")
+	current := data
+
+	for i, raw := range segments {
+		// RFC 6901 unescaping: ~1 → /, ~0 → ~ (order matters).
+		key := strings.ReplaceAll(raw, "~1", "/")
+		key = strings.ReplaceAll(key, "~0", "~")
+
+		m, ok := current.(map[string]interface{})
+		if !ok {
+			traversed := "/" + strings.Join(segments[:i], "/")
+			return nil, fmt.Errorf("json pointer %q: value at %q is %T, not an object",
+				pointer, traversed, current)
+		}
+
+		val, exists := m[key]
+		if !exists {
+			return nil, fmt.Errorf("json pointer %q: key %q not found", pointer, key)
+		}
+
+		current = val
+	}
+
+	return current, nil
+}

internal/binding/json_pointer_test.go

@@ -0,0 +1,111 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"testing"
+)
+
+func TestReadJSONPointer_EmptyPointer(t *testing.T) {
+	data := map[string]interface{}{"key": "value"}
+	got, err := ReadJSONPointer(data, "")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	m, ok := got.(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected map, got %T", got)
+	}
+	if m["key"] != "value" {
+		t.Errorf("got %v, want map with key=value", m)
+	}
+}
+
+func TestReadJSONPointer_OneLevel(t *testing.T) {
+	data := map[string]interface{}{"key": "hello"}
+	got, err := ReadJSONPointer(data, "/key")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "hello" {
+		t.Errorf("got %v, want %q", got, "hello")
+	}
+}
+
+func TestReadJSONPointer_TwoLevels(t *testing.T) {
+	data := map[string]interface{}{
+		"key": map[string]interface{}{
+			"subkey": "deep_value",
+		},
+	}
+	got, err := ReadJSONPointer(data, "/key/subkey")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "deep_value" {
+		t.Errorf("got %v, want %q", got, "deep_value")
+	}
+}
+
+func TestReadJSONPointer_MissingKey(t *testing.T) {
+	data := map[string]interface{}{"key": "value"}
+	_, err := ReadJSONPointer(data, "/nonexistent")
+	if err == nil {
+		t.Fatal("expected error for missing key, got nil")
+	}
+	want := `json pointer "/nonexistent": key "nonexistent" not found`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestReadJSONPointer_NonMapIntermediate(t *testing.T) {
+	data := map[string]interface{}{"key": "scalar_string"}
+	_, err := ReadJSONPointer(data, "/key/subkey")
+	if err == nil {
+		t.Fatal("expected error for non-map intermediate, got nil")
+	}
+	want := `json pointer "/key/subkey": value at "/key" is string, not an object`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestReadJSONPointer_RFC6901_Escaping(t *testing.T) {
+	// ~1 decodes to / and ~0 decodes to ~
+	data := map[string]interface{}{
+		"a/b": "slash_value",
+		"c~d": "tilde_value",
+	}
+
+	// ~1 -> /
+	got, err := ReadJSONPointer(data, "/a~1b")
+	if err != nil {
+		t.Fatalf("unexpected error for ~1 escape: %v", err)
+	}
+	if got != "slash_value" {
+		t.Errorf("got %v, want %q", got, "slash_value")
+	}
+
+	// ~0 -> ~
+	got, err = ReadJSONPointer(data, "/c~0d")
+	if err != nil {
+		t.Fatalf("unexpected error for ~0 escape: %v", err)
+	}
+	if got != "tilde_value" {
+		t.Errorf("got %v, want %q", got, "tilde_value")
+	}
+}
+
+func TestReadJSONPointer_InvalidFormat(t *testing.T) {
+	data := map[string]interface{}{"key": "val"}
+	_, err := ReadJSONPointer(data, "no-leading-slash")
+	if err == nil {
+		t.Fatal("expected error for pointer without leading /")
+	}
+	want := `json pointer must start with '/' or be empty, got "no-leading-slash"`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}

internal/binding/reader.go

@@ -0,0 +1,26 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// ReadOpenClawConfig reads and parses an openclaw.json file at the given path.
+func ReadOpenClawConfig(path string) (*OpenClawRoot, error) {
+	data, err := vfs.ReadFile(path)
+	if err != nil {
+		return nil, err // caller (bind.go) formats user-facing message with path context
+	}
+
+	var root OpenClawRoot
+	if err := json.Unmarshal(data, &root); err != nil {
+		return nil, fmt.Errorf("invalid JSON in %s: %w", path, err)
+	}
+
+	return &root, nil
+}

internal/binding/reader_test.go

@@ -0,0 +1,182 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestReadOpenClawConfig_ValidSingleAccount(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "openclaw.json")
+	data := `{"channels":{"feishu":{"appId":"cli_abc","appSecret":"plain_secret","domain":"feishu"}}}`
+	if err := os.WriteFile(p, []byte(data), 0o644); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	root, err := ReadOpenClawConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if root.Channels.Feishu == nil {
+		t.Fatal("expected Channels.Feishu to be non-nil")
+	}
+	if got := root.Channels.Feishu.AppID; got != "cli_abc" {
+		t.Errorf("AppID = %q, want %q", got, "cli_abc")
+	}
+	if got := root.Channels.Feishu.AppSecret.Plain; got != "plain_secret" {
+		t.Errorf("AppSecret.Plain = %q, want %q", got, "plain_secret")
+	}
+	if root.Channels.Feishu.AppSecret.Ref != nil {
+		t.Error("AppSecret.Ref should be nil for a plain string")
+	}
+	if got := root.Channels.Feishu.Brand; got != "feishu" {
+		t.Errorf("Brand = %q, want %q", got, "feishu")
+	}
+}
+
+func TestReadOpenClawConfig_ValidMultiAccount(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "openclaw.json")
+	data := `{
+		"channels": {
+			"feishu": {
+				"domain": "feishu",
+				"accounts": {
+					"work": {"appId": "cli_work", "appSecret": "secret_work", "domain": "feishu"},
+					"personal": {"appId": "cli_personal", "appSecret": "secret_personal", "domain": "lark"}
+				}
+			}
+		}
+	}`
+	if err := os.WriteFile(p, []byte(data), 0o644); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	root, err := ReadOpenClawConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if root.Channels.Feishu == nil {
+		t.Fatal("expected Channels.Feishu to be non-nil")
+	}
+
+	apps := ListCandidateApps(root.Channels.Feishu)
+	if len(apps) != 2 {
+		t.Fatalf("ListCandidateApps returned %d apps, want 2", len(apps))
+	}
+
+	byLabel := make(map[string]CandidateApp, len(apps))
+	for _, a := range apps {
+		byLabel[a.Label] = a
+	}
+
+	work, ok := byLabel["work"]
+	if !ok {
+		t.Fatal("missing account label 'work'")
+	}
+	if work.AppID != "cli_work" {
+		t.Errorf("work.AppID = %q, want %q", work.AppID, "cli_work")
+	}
+
+	personal, ok := byLabel["personal"]
+	if !ok {
+		t.Fatal("missing account label 'personal'")
+	}
+	if personal.AppID != "cli_personal" {
+		t.Errorf("personal.AppID = %q, want %q", personal.AppID, "cli_personal")
+	}
+}
+
+func TestReadOpenClawConfig_MissingFeishu(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "openclaw.json")
+	data := `{"channels":{}}`
+	if err := os.WriteFile(p, []byte(data), 0o644); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	root, err := ReadOpenClawConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if root.Channels.Feishu != nil {
+		t.Error("expected Channels.Feishu to be nil when not present in JSON")
+	}
+}
+
+func TestReadOpenClawConfig_InvalidJSON(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "openclaw.json")
+	if err := os.WriteFile(p, []byte(`{not valid json`), 0o644); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	_, err := ReadOpenClawConfig(p)
+	if err == nil {
+		t.Fatal("expected error for invalid JSON, got nil")
+	}
+}
+
+func TestReadOpenClawConfig_FileNotFound(t *testing.T) {
+	_, err := ReadOpenClawConfig(filepath.Join(t.TempDir(), "nonexistent.json"))
+	if err == nil {
+		t.Fatal("expected error for non-existent file, got nil")
+	}
+}
+
+func TestReadOpenClawConfig_EnvTemplate(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "openclaw.json")
+	data := `{"channels":{"feishu":{"appId":"cli_env","appSecret":"${FEISHU_APP_SECRET}","domain":"feishu"}}}`
+	if err := os.WriteFile(p, []byte(data), 0o644); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	root, err := ReadOpenClawConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	secret := root.Channels.Feishu.AppSecret
+	if secret.Plain != "${FEISHU_APP_SECRET}" {
+		t.Errorf("SecretInput.Plain = %q, want %q", secret.Plain, "${FEISHU_APP_SECRET}")
+	}
+	if secret.Ref != nil {
+		t.Error("SecretInput.Ref should be nil for env template string")
+	}
+}
+
+func TestReadOpenClawConfig_SecretRefObject(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "openclaw.json")
+	data := `{"channels":{"feishu":{"appId":"cli_ref","appSecret":{"source":"file","provider":"fp","id":"/path"},"domain":"feishu"}}}`
+	if err := os.WriteFile(p, []byte(data), 0o644); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	root, err := ReadOpenClawConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	secret := root.Channels.Feishu.AppSecret
+	if secret.Plain != "" {
+		t.Errorf("SecretInput.Plain = %q, want empty for object form", secret.Plain)
+	}
+	if secret.Ref == nil {
+		t.Fatal("SecretInput.Ref should be non-nil for object form")
+	}
+	if secret.Ref.Source != "file" {
+		t.Errorf("Ref.Source = %q, want %q", secret.Ref.Source, "file")
+	}
+	if secret.Ref.Provider != "fp" {
+		t.Errorf("Ref.Provider = %q, want %q", secret.Ref.Provider, "fp")
+	}
+	if secret.Ref.ID != "/path" {
+		t.Errorf("Ref.ID = %q, want %q", secret.Ref.ID, "/path")
+	}
+}

internal/binding/secret_resolve.go

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"fmt"
+	"os"
+)
+
+// ResolveSecretInput resolves a SecretInput to a plain-text secret string.
+// This is the main dispatcher that handles all SecretInput forms:
+//   - Plain string passthrough
+//   - "${VAR_NAME}" env template expansion
+//   - SecretRef object routing to env/file/exec sub-resolvers
+//
+// The getenv parameter allows injection for testing (typically os.Getenv).
+// This function is only called during config bind (cold path).
+func ResolveSecretInput(input SecretInput, cfg *SecretsConfig, getenv func(string) string) (string, error) {
+	if getenv == nil {
+		getenv = os.Getenv
+	}
+
+	if input.IsZero() {
+		return "", fmt.Errorf("appSecret is missing or empty")
+	}
+
+	// Plain string form (includes env templates)
+	if input.IsPlain() {
+		return resolvePlainOrTemplate(input.Plain, getenv)
+	}
+
+	// SecretRef object form
+	return resolveSecretRef(input.Ref, cfg, getenv)
+}
+
+// resolvePlainOrTemplate handles plain strings and "${VAR}" templates.
+func resolvePlainOrTemplate(value string, getenv func(string) string) (string, error) {
+	if value == "" {
+		return "", fmt.Errorf("appSecret is empty string")
+	}
+
+	// Check for env template pattern: "${VAR_NAME}"
+	matches := EnvTemplateRe.FindStringSubmatch(value)
+	if matches != nil {
+		varName := matches[1]
+		envValue := getenv(varName)
+		if envValue == "" {
+			return "", fmt.Errorf("env variable %q referenced in openclaw.json is not set or empty", varName)
+		}
+		return envValue, nil
+	}
+
+	// Plain string: use as-is
+	return value, nil
+}
+
+// resolveSecretRef dispatches a SecretRef to the appropriate sub-resolver.
+func resolveSecretRef(ref *SecretRef, cfg *SecretsConfig, getenv func(string) string) (string, error) {
+	// Lookup provider configuration
+	providerConfig, err := LookupProvider(ref, cfg)
+	if err != nil {
+		return "", err
+	}
+
+	// Resolve the effective provider name once so downstream resolvers
+	// (notably the exec JSON payload) see the config-defaulted value instead
+	// of the unset literal on ref.Provider.
+	providerName := ResolveDefaultProvider(ref, cfg)
+
+	switch ref.Source {
+	case "env":
+		return resolveEnvRef(ref, providerConfig, getenv)
+	case "file":
+		return resolveFileRef(ref, providerConfig)
+	case "exec":
+		return resolveExecRef(ref, providerName, providerConfig, getenv)
+	default:
+		return "", fmt.Errorf("unsupported secret source %q", ref.Source)
+	}
+}
+
+// resolveEnvRef handles {source:"env"} SecretRef.
+func resolveEnvRef(ref *SecretRef, pc *ProviderConfig, getenv func(string) string) (string, error) {
+	// Check allowlist if configured
+	if len(pc.Allowlist) > 0 {
+		allowed := false
+		for _, name := range pc.Allowlist {
+			if name == ref.ID {
+				allowed = true
+				break
+			}
+		}
+		if !allowed {
+			return "", fmt.Errorf("environment variable %q is not allowlisted in provider", ref.ID)
+		}
+	}
+
+	value := getenv(ref.ID)
+	if value == "" {
+		return "", fmt.Errorf("environment variable %q is missing or empty", ref.ID)
+	}
+	return value, nil
+}

internal/binding/secret_resolve_exec.go

@@ -0,0 +1,241 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"os/exec"
+	"path/filepath"
+	"time"
+)
+
+// execRequest is the JSON payload sent to exec provider's stdin.
+type execRequest struct {
+	ProtocolVersion int      `json:"protocolVersion"`
+	Provider        string   `json:"provider"`
+	IDs             []string `json:"ids"`
+}
+
+// execResponse is the JSON payload expected from exec provider's stdout.
+type execResponse struct {
+	ProtocolVersion int                     `json:"protocolVersion"`
+	Values          map[string]interface{}  `json:"values"`
+	Errors          map[string]execRefError `json:"errors,omitempty"`
+}
+
+// execRefError is an optional per-id error in exec provider response.
+type execRefError struct {
+	Message string `json:"message"`
+}
+
+// execRun bundles everything runExecCommand needs to spawn the child process.
+// It is populated once by prepareExecRun and consumed exactly once by
+// runExecCommand; keeping the two stages pure data + pure side effect makes
+// each independently testable.
+type execRun struct {
+	Path    string        // absolute, already-audited path to the command
+	Args    []string      // command arguments (from pc.Args)
+	Env     []string      // minimal child env (passEnv + explicit env only)
+	Request []byte        // JSON payload to feed on the child's stdin
+	Timeout time.Duration // spawn deadline
+	MaxOut  int           // hard cap on stdout size, enforced post-Run
+}
+
+// resolveExecRef handles {source:"exec"} SecretRef resolution. It audits the
+// command path, runs the child under a timeout with a hard stdout cap, and
+// extracts the secret from the JSON response. providerName is the caller-
+// resolved effective alias (honours secrets.defaults.exec from openclaw.json).
+func resolveExecRef(ref *SecretRef, providerName string, pc *ProviderConfig, getenv func(string) string) (string, error) {
+	prep, err := prepareExecRun(ref, providerName, pc, getenv)
+	if err != nil {
+		return "", err
+	}
+	stdout, err := runExecCommand(prep)
+	if err != nil {
+		return "", err
+	}
+	return extractExecSecret(stdout, ref.ID, effectiveJSONOnly(pc))
+}
+
+// prepareExecRun audits the command path, marshals the JSON request,
+// assembles the minimal child env, and resolves timeout / output limits.
+// Never spawns a process — the returned execRun is pure data.
+func prepareExecRun(ref *SecretRef, providerName string, pc *ProviderConfig, getenv func(string) string) (*execRun, error) {
+	if pc.Command == "" {
+		return nil, fmt.Errorf("exec provider command is empty")
+	}
+
+	securePath, err := AssertSecurePath(AuditParams{
+		TargetPath:            pc.Command,
+		Label:                 "exec provider command",
+		TrustedDirs:           pc.TrustedDirs,
+		AllowInsecurePath:     pc.AllowInsecurePath,
+		AllowReadableByOthers: true, // exec commands are typically 755
+		AllowSymlinkPath:      pc.AllowSymlinkCommand,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("exec provider security audit failed: %w", err)
+	}
+
+	reqJSON, err := marshalExecRequest(ref, providerName)
+	if err != nil {
+		return nil, err
+	}
+
+	timeoutMs, maxOut := effectiveExecLimits(pc)
+	return &execRun{
+		Path:    securePath,
+		Args:    pc.Args,
+		Env:     buildExecEnv(pc, getenv),
+		Request: reqJSON,
+		Timeout: time.Duration(timeoutMs) * time.Millisecond,
+		MaxOut:  maxOut,
+	}, nil
+}
+
+// marshalExecRequest encodes the JSON protocol request sent to the child.
+// providerName is supplied by resolveSecretRef after consulting
+// secrets.defaults.exec; an empty value falls back to DefaultProviderAlias
+// so the function can still be reasoned about in isolation.
+func marshalExecRequest(ref *SecretRef, providerName string) ([]byte, error) {
+	if providerName == "" {
+		providerName = DefaultProviderAlias
+	}
+	data, err := json.Marshal(execRequest{
+		ProtocolVersion: 1,
+		Provider:        providerName,
+		IDs:             []string{ref.ID},
+	})
+	if err != nil {
+		return nil, fmt.Errorf("exec provider: failed to marshal request: %w", err)
+	}
+	return data, nil
+}
+
+// buildExecEnv assembles the child's environment: only variables listed in
+// pc.PassEnv (and non-empty in the parent) plus pc.Env entries. The child
+// never inherits the full parent env — always set cmd.Env explicitly.
+func buildExecEnv(pc *ProviderConfig, getenv func(string) string) []string {
+	env := make([]string, 0, len(pc.PassEnv)+len(pc.Env))
+	for _, key := range pc.PassEnv {
+		if val := getenv(key); val != "" {
+			env = append(env, key+"="+val)
+		}
+	}
+	for key, val := range pc.Env {
+		env = append(env, key+"="+val)
+	}
+	return env
+}
+
+// effectiveExecLimits returns (timeoutMs, maxOutputBytes), falling back to
+// package defaults for any non-positive value. The exec provider uses its
+// own NoOutputTimeoutMs field (pc.TimeoutMs is the file-provider field and
+// should not be consulted here); the value is applied as the overall
+// deadline for the child process.
+func effectiveExecLimits(pc *ProviderConfig) (timeoutMs, maxOutputBytes int) {
+	timeoutMs = pc.NoOutputTimeoutMs
+	if timeoutMs <= 0 {
+		timeoutMs = DefaultExecTimeoutMs
+	}
+	maxOutputBytes = pc.MaxOutputBytes
+	if maxOutputBytes <= 0 {
+		maxOutputBytes = DefaultExecMaxOutputBytes
+	}
+	return timeoutMs, maxOutputBytes
+}
+
+// effectiveJSONOnly returns pc.JSONOnly or its documented default (true).
+func effectiveJSONOnly(pc *ProviderConfig) bool {
+	if pc.JSONOnly != nil {
+		return *pc.JSONOnly
+	}
+	return true
+}
+
+// runExecCommand spawns the child per prep, feeds prep.Request on stdin, and
+// returns trimmed stdout on success. Failure modes:
+//   - timeout → typed error with the configured limit
+//   - non-zero exit → wrapped *exec.ExitError
+//   - stdout exceeds prep.MaxOut → typed error (size enforced post-Run)
+//   - empty trimmed stdout → typed error
+func runExecCommand(prep *execRun) ([]byte, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), prep.Timeout)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, prep.Path, prep.Args...)
+	cmd.Dir = filepath.Dir(prep.Path)
+	cmd.Env = prep.Env // always set — leaving nil would inherit the parent env
+	cmd.Stdin = bytes.NewReader(prep.Request)
+
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+
+	if err := cmd.Run(); err != nil {
+		if ctx.Err() == context.DeadlineExceeded {
+			return nil, fmt.Errorf("exec provider timed out after %dms", int(prep.Timeout/time.Millisecond))
+		}
+		return nil, fmt.Errorf("exec provider exited with error: %w", err)
+	}
+
+	if stdout.Len() > prep.MaxOut {
+		return nil, fmt.Errorf("exec provider output exceeded maxOutputBytes (%d)", prep.MaxOut)
+	}
+
+	trimmed := bytes.TrimSpace(stdout.Bytes())
+	if len(trimmed) == 0 {
+		return nil, fmt.Errorf("exec provider returned empty stdout")
+	}
+	return trimmed, nil
+}
+
+// extractExecSecret parses stdout as a JSON execResponse and returns the
+// string value at refID. When jsonOnly is false and the response is not valid
+// JSON (or the value is not a string), it falls back to the raw stdout or the
+// JSON encoding of the value respectively — mirroring OpenClaw's resolve.ts.
+func extractExecSecret(stdout []byte, refID string, jsonOnly bool) (string, error) {
+	var resp execResponse
+	if err := json.Unmarshal(stdout, &resp); err != nil {
+		if !jsonOnly {
+			return string(stdout), nil
+		}
+		return "", fmt.Errorf("exec provider returned invalid JSON: %w", err)
+	}
+
+	if resp.ProtocolVersion != 1 {
+		return "", fmt.Errorf("exec provider protocolVersion must be 1, got %d", resp.ProtocolVersion)
+	}
+
+	if refErr, ok := resp.Errors[refID]; ok {
+		msg := refErr.Message
+		if msg == "" {
+			msg = "unknown error"
+		}
+		return "", fmt.Errorf("exec provider failed for id %q: %s", refID, msg)
+	}
+
+	if resp.Values == nil {
+		return "", fmt.Errorf("exec provider response missing 'values'")
+	}
+	value, ok := resp.Values[refID]
+	if !ok {
+		return "", fmt.Errorf("exec provider response missing id %q", refID)
+	}
+
+	if str, ok := value.(string); ok {
+		return str, nil
+	}
+	if !jsonOnly {
+		data, err := json.Marshal(value)
+		if err != nil {
+			return "", fmt.Errorf("exec provider value for id %q is not JSON-serializable: %w", refID, err)
+		}
+		return string(data), nil
+	}
+	return "", fmt.Errorf("exec provider value for id %q is not a string", refID)
+}

internal/binding/secret_resolve_exec_test.go

@@ -0,0 +1,437 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+)
+
+// writeExecHelper writes a small shell script that mimics an exec provider.
+// The script reads stdin (the JSON request) and writes a JSON response to stdout.
+func writeExecHelper(t *testing.T, dir, body string) string {
+	t.Helper()
+	p := filepath.Join(dir, "helper.sh")
+	script := "#!/bin/sh\n" + body
+	if err := os.WriteFile(p, []byte(script), 0o700); err != nil {
+		t.Fatalf("write helper script: %v", err)
+	}
+	return p
+}
+
+func TestResolveExecRef_EmptyCommand(t *testing.T) {
+	ref := &SecretRef{Source: "exec", ID: "MY_KEY"}
+	pc := &ProviderConfig{Source: "exec", Command: ""}
+
+	_, err := resolveExecRef(ref, "", pc, nil)
+	if err == nil {
+		t.Fatal("expected error for empty command, got nil")
+	}
+	want := "exec provider command is empty"
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveExecRef_CommandNotFound(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("path audit not applicable on Windows")
+	}
+
+	ref := &SecretRef{Source: "exec", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           "/nonexistent/command",
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveExecRef(ref, "", pc, nil)
+	if err == nil {
+		t.Fatal("expected error for nonexistent command, got nil")
+	}
+}
+
+func TestResolveExecRef_JSONResponse(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	// Script reads stdin (ignores), writes valid JSON response
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+printf '{"protocolVersion":1,"values":{"MY_KEY":"exec_secret_123"}}'
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+	}
+
+	got, err := resolveExecRef(ref, "", pc, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "exec_secret_123" {
+		t.Errorf("got %q, want %q", got, "exec_secret_123")
+	}
+}
+
+func TestResolveExecRef_PerRefError(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+printf '{"protocolVersion":1,"values":{},"errors":{"MY_KEY":{"message":"secret not found"}}}'
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveExecRef(ref, "", pc, nil)
+	if err == nil {
+		t.Fatal("expected error for per-ref error, got nil")
+	}
+	want := `exec provider failed for id "MY_KEY": secret not found`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveExecRef_WrongProtocolVersion(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+printf '{"protocolVersion":99,"values":{"MY_KEY":"v"}}'
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveExecRef(ref, "", pc, nil)
+	if err == nil {
+		t.Fatal("expected error for wrong protocol version, got nil")
+	}
+	want := "exec provider protocolVersion must be 1, got 99"
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveExecRef_MissingValues(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+printf '{"protocolVersion":1}'
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveExecRef(ref, "", pc, nil)
+	if err == nil {
+		t.Fatal("expected error for missing values, got nil")
+	}
+	want := "exec provider response missing 'values'"
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveExecRef_MissingID(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+printf '{"protocolVersion":1,"values":{"OTHER":"val"}}'
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveExecRef(ref, "", pc, nil)
+	if err == nil {
+		t.Fatal("expected error for missing ID, got nil")
+	}
+	want := `exec provider response missing id "MY_KEY"`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveExecRef_EmptyStdout(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveExecRef(ref, "", pc, nil)
+	if err == nil {
+		t.Fatal("expected error for empty stdout, got nil")
+	}
+	want := "exec provider returned empty stdout"
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveExecRef_InvalidJSON_JSONOnly(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+echo "not json"
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+		// JSONOnly defaults to true (nil)
+	}
+
+	_, err := resolveExecRef(ref, "", pc, nil)
+	if err == nil {
+		t.Fatal("expected error for invalid JSON, got nil")
+	}
+}
+
+func TestResolveExecRef_NonJSON_RawString(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+echo "raw_secret_value"
+`)
+
+	jsonOnly := false
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+		JSONOnly:          &jsonOnly,
+	}
+
+	got, err := resolveExecRef(ref, "", pc, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "raw_secret_value" {
+		t.Errorf("got %q, want %q", got, "raw_secret_value")
+	}
+}
+
+func TestResolveExecRef_NonStringValue_JSONOnly(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+printf '{"protocolVersion":1,"values":{"MY_KEY":42}}'
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveExecRef(ref, "", pc, nil)
+	if err == nil {
+		t.Fatal("expected error for non-string value with jsonOnly=true, got nil")
+	}
+	want := `exec provider value for id "MY_KEY" is not a string`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveExecRef_NonStringValue_NoJSONOnly(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+printf '{"protocolVersion":1,"values":{"MY_KEY":42}}'
+`)
+
+	jsonOnly := false
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+		JSONOnly:          &jsonOnly,
+	}
+
+	got, err := resolveExecRef(ref, "", pc, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "42" {
+		t.Errorf("got %q, want %q", got, "42")
+	}
+}
+
+func TestResolveExecRef_CommandExitError(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	helper := writeExecHelper(t, dir, `exit 1
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveExecRef(ref, "", pc, nil)
+	if err == nil {
+		t.Fatal("expected error for command exit error, got nil")
+	}
+}
+
+func TestResolveExecRef_PassEnv(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	// Script uses TEST_SECRET env to produce value
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+printf '{"protocolVersion":1,"values":{"MY_KEY":"%s"}}' "$TEST_SECRET"
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+		PassEnv:           []string{"TEST_SECRET"},
+	}
+
+	getenv := func(key string) string {
+		if key == "TEST_SECRET" {
+			return "passed_env_value"
+		}
+		return ""
+	}
+
+	got, err := resolveExecRef(ref, "", pc, getenv)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "passed_env_value" {
+		t.Errorf("got %q, want %q", got, "passed_env_value")
+	}
+}
+
+func TestResolveExecRef_ExplicitEnv(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+printf '{"protocolVersion":1,"values":{"MY_KEY":"%s"}}' "$CUSTOM_VAR"
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+		Env:               map[string]string{"CUSTOM_VAR": "explicit_value"},
+	}
+
+	got, err := resolveExecRef(ref, "", pc, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "explicit_value" {
+		t.Errorf("got %q, want %q", got, "explicit_value")
+	}
+}
+
+func TestResolveExecRef_OutputExceedsMax(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("shell scripts not applicable on Windows")
+	}
+
+	dir := t.TempDir()
+	// Script outputs more than maxOutputBytes
+	helper := writeExecHelper(t, dir, `cat > /dev/null
+python3 -c "print('x' * 200)"
+`)
+
+	ref := &SecretRef{Source: "exec", Provider: "default", ID: "MY_KEY"}
+	pc := &ProviderConfig{
+		Source:            "exec",
+		Command:           helper,
+		AllowInsecurePath: true,
+		MaxOutputBytes:    10,
+	}
+
+	_, err := resolveExecRef(ref, "", pc, nil)
+	if err == nil {
+		t.Fatal("expected error for output exceeding maxOutputBytes, got nil")
+	}
+	want := fmt.Sprintf("exec provider output exceeded maxOutputBytes (%d)", 10)
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}

internal/binding/secret_resolve_file.go

@@ -0,0 +1,95 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// SingleValueFileRefID is the required ref.ID for singleValue file mode
+// (aligned with OpenClaw ref-contract.ts SINGLE_VALUE_FILE_REF_ID).
+const SingleValueFileRefID = "$SINGLE_VALUE"
+
+// resolveFileRef handles {source:"file"} SecretRef resolution.
+// Reads the file via assertSecurePath audit, then extracts the secret value
+// based on the provider's mode (singleValue or json with JSON Pointer).
+func resolveFileRef(ref *SecretRef, pc *ProviderConfig) (string, error) {
+	if pc.Path == "" {
+		return "", fmt.Errorf("file provider path is empty")
+	}
+
+	// Security audit on file path
+	securePath, err := AssertSecurePath(AuditParams{
+		TargetPath:            pc.Path,
+		Label:                 "secrets.providers file path",
+		TrustedDirs:           pc.TrustedDirs,
+		AllowInsecurePath:     pc.AllowInsecurePath,
+		AllowReadableByOthers: false, // file provider: strict by default
+		AllowSymlinkPath:      false,
+	})
+	if err != nil {
+		return "", fmt.Errorf("file provider security audit failed: %w", err)
+	}
+
+	// Read file content
+	maxBytes := pc.MaxBytes
+	if maxBytes <= 0 {
+		maxBytes = DefaultFileMaxBytes
+	}
+
+	// Note: vfs.ReadFile loads the entire file. maxBytes is enforced post-read
+	// because vfs does not expose a size-limited reader. For secret files this
+	// is acceptable (default limit 1 MiB; secrets are typically < 1 KB).
+	data, err := vfs.ReadFile(securePath)
+	if err != nil {
+		return "", fmt.Errorf("failed to read secret file %s: %w", securePath, err)
+	}
+
+	if len(data) > maxBytes {
+		return "", fmt.Errorf("file provider exceeded maxBytes (%d)", maxBytes)
+	}
+
+	content := string(data)
+	mode := pc.Mode
+	if mode == "" {
+		mode = "json" // default mode per OpenClaw
+	}
+
+	switch mode {
+	case "singleValue":
+		// OpenClaw requires ref.id == SINGLE_VALUE_FILE_REF_ID for singleValue mode
+		if ref.ID != SingleValueFileRefID {
+			return "", fmt.Errorf("singleValue file provider expects ref id %q, got %q",
+				SingleValueFileRefID, ref.ID)
+		}
+		// Entire file content is the secret; trim trailing newline
+		return strings.TrimRight(content, "\r\n"), nil
+
+	case "json":
+		// Parse as JSON, then navigate via JSON Pointer (ref.ID)
+		var parsed interface{}
+		if err := json.Unmarshal(data, &parsed); err != nil {
+			return "", fmt.Errorf("file provider JSON parse error: %w", err)
+		}
+
+		value, err := ReadJSONPointer(parsed, ref.ID)
+		if err != nil {
+			return "", fmt.Errorf("file provider JSON Pointer %q: %w", ref.ID, err)
+		}
+
+		// Value must be a string
+		strValue, ok := value.(string)
+		if !ok {
+			return "", fmt.Errorf("file provider JSON Pointer %q resolved to non-string value", ref.ID)
+		}
+		return strValue, nil
+
+	default:
+		return "", fmt.Errorf("unsupported file provider mode %q", mode)
+	}
+}

internal/binding/secret_resolve_file_test.go

@@ -0,0 +1,232 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestResolveFileRef_SingleValue(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "secret.txt")
+	if err := os.WriteFile(p, []byte("my_secret\n"), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	ref := &SecretRef{Source: "file", ID: SingleValueFileRefID}
+	pc := &ProviderConfig{
+		Source:            "file",
+		Path:              p,
+		Mode:              "singleValue",
+		AllowInsecurePath: true,
+	}
+
+	got, err := resolveFileRef(ref, pc)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "my_secret" {
+		t.Errorf("got %q, want %q", got, "my_secret")
+	}
+}
+
+func TestResolveFileRef_SingleValue_WrongRefID(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "secret.txt")
+	if err := os.WriteFile(p, []byte("my_secret\n"), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	ref := &SecretRef{Source: "file", ID: "WRONG_ID"}
+	pc := &ProviderConfig{
+		Source:            "file",
+		Path:              p,
+		Mode:              "singleValue",
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveFileRef(ref, pc)
+	if err == nil {
+		t.Fatal("expected error for wrong ref ID, got nil")
+	}
+	want := `singleValue file provider expects ref id "$SINGLE_VALUE", got "WRONG_ID"`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveFileRef_JSONMode(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "secrets.json")
+	content := `{"providers":{"feishu":{"key":"secret123"}}}`
+	if err := os.WriteFile(p, []byte(content), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	ref := &SecretRef{Source: "file", ID: "/providers/feishu/key"}
+	pc := &ProviderConfig{
+		Source:            "file",
+		Path:              p,
+		Mode:              "json",
+		AllowInsecurePath: true,
+	}
+
+	got, err := resolveFileRef(ref, pc)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "secret123" {
+		t.Errorf("got %q, want %q", got, "secret123")
+	}
+}
+
+func TestResolveFileRef_JSONMode_MissingPointer(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "secrets.json")
+	content := `{"providers":{"feishu":{"key":"secret123"}}}`
+	if err := os.WriteFile(p, []byte(content), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	ref := &SecretRef{Source: "file", ID: "/providers/nonexistent/key"}
+	pc := &ProviderConfig{
+		Source:            "file",
+		Path:              p,
+		Mode:              "json",
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveFileRef(ref, pc)
+	if err == nil {
+		t.Fatal("expected error for missing JSON pointer, got nil")
+	}
+	want := `file provider JSON Pointer "/providers/nonexistent/key": json pointer "/providers/nonexistent/key": key "nonexistent" not found`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveFileRef_FileNotFound(t *testing.T) {
+	nonexistent := filepath.Join(t.TempDir(), "no_such_file.txt")
+	ref := &SecretRef{Source: "file", ID: SingleValueFileRefID}
+	pc := &ProviderConfig{
+		Source:            "file",
+		Path:              nonexistent,
+		Mode:              "singleValue",
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveFileRef(ref, pc)
+	if err == nil {
+		t.Fatal("expected error for missing file, got nil")
+	}
+}
+
+func TestResolveFileRef_EmptyProviderPath(t *testing.T) {
+	ref := &SecretRef{Source: "file", ID: SingleValueFileRefID}
+	pc := &ProviderConfig{Source: "file", Path: "", Mode: "singleValue", AllowInsecurePath: true}
+	_, err := resolveFileRef(ref, pc)
+	if err == nil {
+		t.Fatal("expected error for empty provider path, got nil")
+	}
+	want := "file provider path is empty"
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveFileRef_JSONMode_NonStringValue(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "secrets.json")
+	if err := os.WriteFile(p, []byte(`{"count":42}`), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	ref := &SecretRef{Source: "file", ID: "/count"}
+	pc := &ProviderConfig{Source: "file", Path: p, Mode: "json", AllowInsecurePath: true}
+	_, err := resolveFileRef(ref, pc)
+	if err == nil {
+		t.Fatal("expected error for non-string JSON value, got nil")
+	}
+	want := `file provider JSON Pointer "/count" resolved to non-string value`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveFileRef_UnsupportedMode(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "secret.txt")
+	if err := os.WriteFile(p, []byte("data"), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	ref := &SecretRef{Source: "file", ID: SingleValueFileRefID}
+	pc := &ProviderConfig{Source: "file", Path: p, Mode: "yaml", AllowInsecurePath: true}
+	_, err := resolveFileRef(ref, pc)
+	if err == nil {
+		t.Fatal("expected error for unsupported mode, got nil")
+	}
+	want := `unsupported file provider mode "yaml"`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveFileRef_DefaultMode_IsJSON(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "secrets.json")
+	if err := os.WriteFile(p, []byte(`{"key":"value123"}`), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	ref := &SecretRef{Source: "file", ID: "/key"}
+	pc := &ProviderConfig{Source: "file", Path: p, Mode: "", AllowInsecurePath: true}
+	got, err := resolveFileRef(ref, pc)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "value123" {
+		t.Errorf("got %q, want %q", got, "value123")
+	}
+}
+
+func TestResolveFileRef_JSONMode_InvalidJSON(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "bad.json")
+	if err := os.WriteFile(p, []byte("not json"), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	ref := &SecretRef{Source: "file", ID: "/key"}
+	pc := &ProviderConfig{Source: "file", Path: p, Mode: "json", AllowInsecurePath: true}
+	_, err := resolveFileRef(ref, pc)
+	if err == nil {
+		t.Fatal("expected error for invalid JSON, got nil")
+	}
+}
+
+func TestResolveFileRef_ExceedsMaxBytes(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "big.txt")
+	if err := os.WriteFile(p, []byte("this content is longer than 5 bytes"), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	ref := &SecretRef{Source: "file", ID: SingleValueFileRefID}
+	pc := &ProviderConfig{
+		Source:            "file",
+		Path:              p,
+		Mode:              "singleValue",
+		MaxBytes:          5,
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveFileRef(ref, pc)
+	if err == nil {
+		t.Fatal("expected error for file exceeding maxBytes, got nil")
+	}
+	want := "file provider exceeded maxBytes (5)"
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}

internal/binding/secret_resolve_test.go

@@ -0,0 +1,153 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"testing"
+)
+
+func makeGetenv(m map[string]string) func(string) string {
+	return func(key string) string { return m[key] }
+}
+
+func TestResolve_PlainString(t *testing.T) {
+	got, err := ResolveSecretInput(SecretInput{Plain: "my_secret"}, nil, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "my_secret" {
+		t.Errorf("got %q, want %q", got, "my_secret")
+	}
+}
+
+func TestResolve_EmptyInput(t *testing.T) {
+	_, err := ResolveSecretInput(SecretInput{}, nil, nil)
+	if err == nil {
+		t.Fatal("expected error for empty input, got nil")
+	}
+	want := "appSecret is missing or empty"
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolve_EnvTemplate_Found(t *testing.T) {
+	getenv := makeGetenv(map[string]string{"MY_VAR": "resolved_value"})
+	got, err := ResolveSecretInput(SecretInput{Plain: "${MY_VAR}"}, nil, getenv)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "resolved_value" {
+		t.Errorf("got %q, want %q", got, "resolved_value")
+	}
+}
+
+func TestResolve_EnvTemplate_NotFound(t *testing.T) {
+	getenv := makeGetenv(map[string]string{})
+	_, err := ResolveSecretInput(SecretInput{Plain: "${MY_VAR}"}, nil, getenv)
+	if err == nil {
+		t.Fatal("expected error for unset env variable, got nil")
+	}
+	want := `env variable "MY_VAR" referenced in openclaw.json is not set or empty`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolve_EnvTemplate_InvalidFormat(t *testing.T) {
+	getenv := makeGetenv(map[string]string{})
+	got, err := ResolveSecretInput(SecretInput{Plain: "${lowercase}"}, nil, getenv)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "${lowercase}" {
+		t.Errorf("got %q, want %q (treated as plain string)", got, "${lowercase}")
+	}
+}
+
+func TestResolve_EnvRef(t *testing.T) {
+	getenv := makeGetenv(map[string]string{"MY_KEY": "env_val"})
+	input := SecretInput{Ref: &SecretRef{Source: "env", Provider: "default", ID: "MY_KEY"}}
+	got, err := ResolveSecretInput(input, nil, getenv)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "env_val" {
+		t.Errorf("got %q, want %q", got, "env_val")
+	}
+}
+
+func TestResolve_EnvRef_NotFound(t *testing.T) {
+	getenv := makeGetenv(map[string]string{})
+	input := SecretInput{Ref: &SecretRef{Source: "env", Provider: "default", ID: "MY_KEY"}}
+	_, err := ResolveSecretInput(input, nil, getenv)
+	if err == nil {
+		t.Fatal("expected error for missing env variable, got nil")
+	}
+}
+
+func TestResolve_EnvRef_Allowlisted(t *testing.T) {
+	getenv := makeGetenv(map[string]string{"MY_KEY": "allowed_val"})
+	cfg := &SecretsConfig{
+		Providers: map[string]*ProviderConfig{
+			"default": {Source: "env", Allowlist: []string{"MY_KEY"}},
+		},
+	}
+	input := SecretInput{Ref: &SecretRef{Source: "env", Provider: "default", ID: "MY_KEY"}}
+	got, err := ResolveSecretInput(input, cfg, getenv)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "allowed_val" {
+		t.Errorf("got %q, want %q", got, "allowed_val")
+	}
+}
+
+func TestResolve_EnvRef_NotAllowlisted(t *testing.T) {
+	getenv := makeGetenv(map[string]string{"MY_KEY": "some_val"})
+	cfg := &SecretsConfig{
+		Providers: map[string]*ProviderConfig{
+			"default": {Source: "env", Allowlist: []string{"OTHER"}},
+		},
+	}
+	input := SecretInput{Ref: &SecretRef{Source: "env", Provider: "default", ID: "MY_KEY"}}
+	_, err := ResolveSecretInput(input, cfg, getenv)
+	if err == nil {
+		t.Fatal("expected error for non-allowlisted key, got nil")
+	}
+	want := `environment variable "MY_KEY" is not allowlisted in provider`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolve_UnknownSource(t *testing.T) {
+	getenv := makeGetenv(map[string]string{})
+	cfg := &SecretsConfig{
+		Providers: map[string]*ProviderConfig{
+			"default": {Source: "unknown"},
+		},
+	}
+	input := SecretInput{Ref: &SecretRef{Source: "unknown", Provider: "default", ID: "some_id"}}
+	_, err := ResolveSecretInput(input, cfg, getenv)
+	if err == nil {
+		t.Fatal("expected error for unknown source, got nil")
+	}
+}
+
+func TestResolve_ProviderNotConfigured(t *testing.T) {
+	getenv := makeGetenv(map[string]string{})
+	cfg := &SecretsConfig{
+		Providers: map[string]*ProviderConfig{},
+	}
+	input := SecretInput{Ref: &SecretRef{Source: "file", Provider: "nonexistent", ID: "/some/path"}}
+	_, err := ResolveSecretInput(input, cfg, getenv)
+	if err == nil {
+		t.Fatal("expected error for non-configured provider, got nil")
+	}
+	want := `secret provider "nonexistent" is not configured (ref: file:nonexistent:/some/path)`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}

internal/binding/types.go

@@ -0,0 +1,306 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// OpenClawRoot captures the minimal subset of openclaw.json needed by config bind.
+// Unknown fields are silently ignored (forward-compatible with future OpenClaw versions).
+type OpenClawRoot struct {
+	Channels ChannelsRoot   `json:"channels"`
+	Secrets  *SecretsConfig `json:"secrets,omitempty"`
+}
+
+// ChannelsRoot holds channel configurations.
+type ChannelsRoot struct {
+	Feishu *FeishuChannel `json:"feishu,omitempty"`
+}
+
+// FeishuChannel represents the channels.feishu subtree.
+// Single-account: AppID + AppSecret + Brand at top level.
+// Multi-account: Accounts map (keyed by label like "work", "personal").
+//
+// Note: OpenClaw's canonical schema stores the brand under the key
+// `domain` (values "feishu" | "lark"), not `brand`. The Go field name
+// `Brand` stays aligned with our internal terminology, but the JSON
+// tag matches OpenClaw's on-disk format.
+type FeishuChannel struct {
+	Enabled   *bool                     `json:"enabled,omitempty"` // nil = default enabled
+	AppID     string                    `json:"appId,omitempty"`
+	AppSecret SecretInput               `json:"appSecret,omitempty"`
+	Brand     string                    `json:"domain,omitempty"`
+	Accounts  map[string]*FeishuAccount `json:"accounts,omitempty"`
+}
+
+// FeishuAccount is a single account entry within Accounts.
+// Like FeishuChannel, `Brand` maps to OpenClaw's `domain` key.
+type FeishuAccount struct {
+	Enabled   *bool       `json:"enabled,omitempty"` // nil = default enabled
+	AppID     string      `json:"appId,omitempty"`
+	AppSecret SecretInput `json:"appSecret,omitempty"`
+	Brand     string      `json:"domain,omitempty"`
+}
+
+// isEnabled returns true if the enabled field is nil (default) or explicitly true.
+func isEnabled(enabled *bool) bool {
+	return enabled == nil || *enabled
+}
+
+// SecretInput is a union type: either a plain string or a SecretRef object.
+// Implements custom JSON unmarshaling to handle both forms.
+type SecretInput struct {
+	Plain string     // non-empty when value is a plain string (including "${VAR}" templates)
+	Ref   *SecretRef // non-nil when value is a SecretRef object
+}
+
+// IsZero returns true if no value was provided.
+func (s SecretInput) IsZero() bool {
+	return s.Plain == "" && s.Ref == nil
+}
+
+// IsPlain returns true if this is a plain string (not a SecretRef object).
+func (s SecretInput) IsPlain() bool {
+	return s.Ref == nil
+}
+
+// SecretRef references a secret stored externally via OpenClaw's provider system.
+type SecretRef struct {
+	Source   string `json:"source"`             // "env" | "file" | "exec"
+	Provider string `json:"provider,omitempty"` // provider alias; defaults to config.secrets.defaults.<source> or "default"
+	ID       string `json:"id"`                 // lookup key (env var name / JSON pointer / exec ref id)
+}
+
+// validSources lists accepted SecretRef source values.
+var validSources = map[string]bool{
+	"env":  true,
+	"file": true,
+	"exec": true,
+}
+
+// EnvTemplateRe matches OpenClaw env template strings like "${FEISHU_APP_SECRET}".
+// Only uppercase letters, digits, and underscores; 1-128 chars; must start with uppercase.
+var EnvTemplateRe = regexp.MustCompile(`^\$\{([A-Z][A-Z0-9_]{0,127})\}$`)
+
+// UnmarshalJSON handles both string and object forms of SecretInput.
+func (s *SecretInput) UnmarshalJSON(data []byte) error {
+	// Try string first
+	var str string
+	if err := json.Unmarshal(data, &str); err == nil {
+		s.Plain = str
+		s.Ref = nil
+		return nil
+	}
+
+	// Try SecretRef object
+	var ref SecretRef
+	if err := json.Unmarshal(data, &ref); err == nil {
+		if !validSources[ref.Source] {
+			return fmt.Errorf("SecretRef.source must be env|file|exec, got %q", ref.Source)
+		}
+		if ref.ID == "" {
+			return fmt.Errorf("SecretRef.id must be non-empty")
+		}
+		s.Ref = &ref
+		s.Plain = ""
+		return nil
+	}
+
+	return fmt.Errorf("appSecret must be a string or {source, provider?, id} object")
+}
+
+// MarshalJSON serializes SecretInput back to JSON.
+func (s SecretInput) MarshalJSON() ([]byte, error) {
+	if s.Ref != nil {
+		return json.Marshal(s.Ref)
+	}
+	return json.Marshal(s.Plain)
+}
+
+// SecretsConfig captures the secrets.providers registry from openclaw.json.
+type SecretsConfig struct {
+	Providers map[string]*ProviderConfig `json:"providers,omitempty"`
+	Defaults  *ProviderDefaults          `json:"defaults,omitempty"`
+}
+
+// ProviderDefaults holds default provider aliases for each source type.
+type ProviderDefaults struct {
+	Env  string `json:"env,omitempty"`
+	File string `json:"file,omitempty"`
+	Exec string `json:"exec,omitempty"`
+}
+
+// DefaultProviderAlias is the fallback provider name when none is specified.
+const DefaultProviderAlias = "default"
+
+// ProviderConfig holds configuration for a secret provider.
+// Fields are source-specific; unused fields for other sources are ignored.
+type ProviderConfig struct {
+	Source string `json:"source"` // "env" | "file" | "exec"
+
+	// env source fields
+	Allowlist []string `json:"allowlist,omitempty"`
+
+	// file source fields
+	Path      string `json:"path,omitempty"`
+	Mode      string `json:"mode,omitempty"` // "singleValue" | "json"; default "json"
+	TimeoutMs int    `json:"timeoutMs,omitempty"`
+	MaxBytes  int    `json:"maxBytes,omitempty"`
+
+	// exec source fields
+	Command             string            `json:"command,omitempty"`
+	Args                []string          `json:"args,omitempty"`
+	NoOutputTimeoutMs   int               `json:"noOutputTimeoutMs,omitempty"`
+	MaxOutputBytes      int               `json:"maxOutputBytes,omitempty"`
+	JSONOnly            *bool             `json:"jsonOnly,omitempty"` // nil = default true
+	Env                 map[string]string `json:"env,omitempty"`
+	PassEnv             []string          `json:"passEnv,omitempty"`
+	TrustedDirs         []string          `json:"trustedDirs,omitempty"`
+	AllowInsecurePath   bool              `json:"allowInsecurePath,omitempty"`
+	AllowSymlinkCommand bool              `json:"allowSymlinkCommand,omitempty"`
+}
+
+// Default values for provider config fields (aligned with OpenClaw resolve.ts).
+const (
+	DefaultFileTimeoutMs      = 5000
+	DefaultFileMaxBytes       = 1024 * 1024 // 1 MiB
+	DefaultExecTimeoutMs      = 5000
+	DefaultExecMaxOutputBytes = 1024 * 1024 // 1 MiB
+)
+
+// ResolveDefaultProvider returns the effective provider alias for a SecretRef.
+// If ref.Provider is set, returns it; otherwise falls back to config defaults or "default".
+func ResolveDefaultProvider(ref *SecretRef, cfg *SecretsConfig) string {
+	if ref.Provider != "" {
+		return ref.Provider
+	}
+	if cfg != nil && cfg.Defaults != nil {
+		switch ref.Source {
+		case "env":
+			if cfg.Defaults.Env != "" {
+				return cfg.Defaults.Env
+			}
+		case "file":
+			if cfg.Defaults.File != "" {
+				return cfg.Defaults.File
+			}
+		case "exec":
+			if cfg.Defaults.Exec != "" {
+				return cfg.Defaults.Exec
+			}
+		}
+	}
+	return DefaultProviderAlias
+}
+
+// LookupProvider resolves a provider config from the registry.
+// Returns the provider config or an error if not found.
+// Special case: env source with "default" provider returns a synthetic empty env provider.
+func LookupProvider(ref *SecretRef, cfg *SecretsConfig) (*ProviderConfig, error) {
+	providerName := ResolveDefaultProvider(ref, cfg)
+
+	if cfg != nil && cfg.Providers != nil {
+		if pc, ok := cfg.Providers[providerName]; ok {
+			if pc == nil {
+				return nil, fmt.Errorf("secret provider %q is configured as null", providerName)
+			}
+			if pc.Source != ref.Source {
+				return nil, fmt.Errorf("secret provider %q has source %q but ref requests %q",
+					providerName, pc.Source, ref.Source)
+			}
+			return pc, nil
+		}
+	}
+
+	// Special case: default env provider (implicit, per OpenClaw resolve.ts)
+	if ref.Source == "env" && providerName == DefaultProviderAlias {
+		return &ProviderConfig{Source: "env"}, nil
+	}
+
+	return nil, fmt.Errorf("secret provider %q is not configured (ref: %s:%s:%s)",
+		providerName, ref.Source, providerName, ref.ID)
+}
+
+// CandidateApp represents a bindable app from OpenClaw's feishu channel config.
+type CandidateApp struct {
+	Label     string
+	AppID     string
+	AppSecret SecretInput
+	Brand     string
+}
+
+// ListCandidateApps enumerates all bindable (enabled) apps from a FeishuChannel.
+// Disabled accounts (enabled: false) are filtered out.
+func ListCandidateApps(ch *FeishuChannel) []CandidateApp {
+	if ch == nil {
+		return nil
+	}
+	if len(ch.Accounts) > 0 {
+		apps := make([]CandidateApp, 0, len(ch.Accounts)+1)
+
+		// When accounts exist AND top-level has its own appId+appSecret,
+		// include the top-level as a "default" candidate — aligned with
+		// openclaw-lark getLarkAccountIds() which adds DEFAULT_ACCOUNT_ID
+		// when top-level credentials are present and no explicit "default" exists.
+		hasDefault := false
+		for label := range ch.Accounts {
+			if strings.EqualFold(strings.TrimSpace(label), "default") {
+				hasDefault = true
+				break
+			}
+		}
+		if !hasDefault && ch.AppID != "" && !ch.AppSecret.IsZero() && isEnabled(ch.Enabled) {
+			apps = append(apps, CandidateApp{
+				Label:     "default",
+				AppID:     ch.AppID,
+				AppSecret: ch.AppSecret,
+				Brand:     ch.Brand,
+			})
+		}
+
+		for label, acct := range ch.Accounts {
+			if acct == nil || !isEnabled(acct.Enabled) {
+				continue // skip disabled accounts
+			}
+			appID := acct.AppID
+			if appID == "" {
+				appID = ch.AppID // inherit from top-level
+			}
+			if appID == "" {
+				continue // skip entries with no effective AppID
+			}
+			appSecret := acct.AppSecret
+			if appSecret.IsZero() {
+				appSecret = ch.AppSecret // inherit from top-level
+			}
+			brand := acct.Brand
+			if brand == "" {
+				brand = ch.Brand
+			}
+			apps = append(apps, CandidateApp{
+				Label:     label,
+				AppID:     appID,
+				AppSecret: appSecret,
+				Brand:     brand,
+			})
+		}
+		return apps
+	}
+
+	// Single account at top level — check if channel itself is enabled
+	if ch.AppID != "" && isEnabled(ch.Enabled) {
+		return []CandidateApp{{
+			Label:     "",
+			AppID:     ch.AppID,
+			AppSecret: ch.AppSecret,
+			Brand:     ch.Brand,
+		}}
+	}
+
+	return nil
+}

internal/binding/types_test.go

@@ -0,0 +1,419 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestSecretInput_MarshalJSON_PlainString(t *testing.T) {
+	input := SecretInput{Plain: "my_secret"}
+	data, err := input.MarshalJSON()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	want := `"my_secret"`
+	if string(data) != want {
+		t.Errorf("got %s, want %s", data, want)
+	}
+}
+
+func TestSecretInput_MarshalJSON_SecretRef(t *testing.T) {
+	input := SecretInput{Ref: &SecretRef{Source: "env", ID: "MY_VAR"}}
+	data, err := input.MarshalJSON()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var ref SecretRef
+	if err := json.Unmarshal(data, &ref); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if ref.Source != "env" {
+		t.Errorf("source = %q, want %q", ref.Source, "env")
+	}
+	if ref.ID != "MY_VAR" {
+		t.Errorf("id = %q, want %q", ref.ID, "MY_VAR")
+	}
+}
+
+func TestSecretInput_UnmarshalJSON_InvalidSource(t *testing.T) {
+	data := []byte(`{"source":"invalid","id":"key"}`)
+	var input SecretInput
+	err := json.Unmarshal(data, &input)
+	if err == nil {
+		t.Fatal("expected error for invalid source, got nil")
+	}
+}
+
+func TestSecretInput_UnmarshalJSON_EmptyID(t *testing.T) {
+	data := []byte(`{"source":"env","id":""}`)
+	var input SecretInput
+	err := json.Unmarshal(data, &input)
+	if err == nil {
+		t.Fatal("expected error for empty id, got nil")
+	}
+}
+
+func TestSecretInput_UnmarshalJSON_InvalidType(t *testing.T) {
+	data := []byte(`42`)
+	var input SecretInput
+	err := json.Unmarshal(data, &input)
+	if err == nil {
+		t.Fatal("expected error for numeric input, got nil")
+	}
+	want := "appSecret must be a string or {source, provider?, id} object"
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestResolveDefaultProvider_ExplicitProvider(t *testing.T) {
+	ref := &SecretRef{Source: "env", Provider: "my-custom", ID: "KEY"}
+	got := ResolveDefaultProvider(ref, nil)
+	if got != "my-custom" {
+		t.Errorf("got %q, want %q", got, "my-custom")
+	}
+}
+
+func TestResolveDefaultProvider_FromDefaults(t *testing.T) {
+	tests := []struct {
+		name     string
+		source   string
+		defaults *ProviderDefaults
+		want     string
+	}{
+		{
+			name:     "env default",
+			source:   "env",
+			defaults: &ProviderDefaults{Env: "my-env-prov"},
+			want:     "my-env-prov",
+		},
+		{
+			name:     "file default",
+			source:   "file",
+			defaults: &ProviderDefaults{File: "my-file-prov"},
+			want:     "my-file-prov",
+		},
+		{
+			name:     "exec default",
+			source:   "exec",
+			defaults: &ProviderDefaults{Exec: "my-exec-prov"},
+			want:     "my-exec-prov",
+		},
+		{
+			name:     "no defaults configured",
+			source:   "env",
+			defaults: &ProviderDefaults{},
+			want:     DefaultProviderAlias,
+		},
+		{
+			name:     "nil defaults",
+			source:   "env",
+			defaults: nil,
+			want:     DefaultProviderAlias,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ref := &SecretRef{Source: tt.source, ID: "KEY"}
+			cfg := &SecretsConfig{Defaults: tt.defaults}
+			got := ResolveDefaultProvider(ref, cfg)
+			if got != tt.want {
+				t.Errorf("got %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestResolveDefaultProvider_NilConfig(t *testing.T) {
+	ref := &SecretRef{Source: "env", ID: "KEY"}
+	got := ResolveDefaultProvider(ref, nil)
+	if got != DefaultProviderAlias {
+		t.Errorf("got %q, want %q", got, DefaultProviderAlias)
+	}
+}
+
+func TestLookupProvider_SourceMismatch(t *testing.T) {
+	cfg := &SecretsConfig{
+		Providers: map[string]*ProviderConfig{
+			"default": {Source: "file"},
+		},
+	}
+	ref := &SecretRef{Source: "env", ID: "KEY"}
+	_, err := LookupProvider(ref, cfg)
+	if err == nil {
+		t.Fatal("expected error for source mismatch, got nil")
+	}
+	want := `secret provider "default" has source "file" but ref requests "env"`
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestLookupProvider_ImplicitDefaultEnv(t *testing.T) {
+	// Default env provider is implicitly available even without explicit config
+	ref := &SecretRef{Source: "env", ID: "KEY"}
+	pc, err := LookupProvider(ref, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pc.Source != "env" {
+		t.Errorf("source = %q, want %q", pc.Source, "env")
+	}
+}
+
+func TestListCandidateApps_NilChannel(t *testing.T) {
+	got := ListCandidateApps(nil)
+	if got != nil {
+		t.Errorf("expected nil, got %v", got)
+	}
+}
+
+func TestListCandidateApps_SingleAccount(t *testing.T) {
+	ch := &FeishuChannel{
+		AppID:     "cli_single",
+		AppSecret: SecretInput{Plain: "secret"},
+		Brand:     "feishu",
+	}
+	got := ListCandidateApps(ch)
+	if len(got) != 1 {
+		t.Fatalf("count = %d, want 1", len(got))
+	}
+	if got[0].AppID != "cli_single" {
+		t.Errorf("appId = %q, want %q", got[0].AppID, "cli_single")
+	}
+	if got[0].Label != "" {
+		t.Errorf("label = %q, want empty", got[0].Label)
+	}
+	if got[0].Brand != "feishu" {
+		t.Errorf("brand = %q, want %q", got[0].Brand, "feishu")
+	}
+}
+
+func TestListCandidateApps_SingleAccount_Disabled(t *testing.T) {
+	disabled := false
+	ch := &FeishuChannel{
+		Enabled:   &disabled,
+		AppID:     "cli_disabled",
+		AppSecret: SecretInput{Plain: "secret"},
+	}
+	got := ListCandidateApps(ch)
+	if len(got) != 0 {
+		t.Errorf("expected 0 apps for disabled channel, got %d", len(got))
+	}
+}
+
+func TestListCandidateApps_MultiAccount_InheritTopLevel(t *testing.T) {
+	ch := &FeishuChannel{
+		AppID: "cli_top_level",
+		Brand: "lark",
+		Accounts: map[string]*FeishuAccount{
+			"work": {
+				// No AppID → inherits from top-level
+				AppSecret: SecretInput{Plain: "secret"},
+				// No Brand → inherits from top-level
+			},
+		},
+	}
+	got := ListCandidateApps(ch)
+	if len(got) != 1 {
+		t.Fatalf("count = %d, want 1", len(got))
+	}
+	if got[0].AppID != "cli_top_level" {
+		t.Errorf("inherited appId = %q, want %q", got[0].AppID, "cli_top_level")
+	}
+	if got[0].Brand != "lark" {
+		t.Errorf("inherited brand = %q, want %q", got[0].Brand, "lark")
+	}
+	if got[0].Label != "work" {
+		t.Errorf("label = %q, want %q", got[0].Label, "work")
+	}
+}
+
+func TestListCandidateApps_MultiAccount_InheritAppSecret(t *testing.T) {
+	// Reproduces the "default": {} edge case from real openclaw.json configs
+	// where an empty account object should inherit appSecret from the top-level channel.
+	ch := &FeishuChannel{
+		AppID:     "cli_fake_top_level",
+		AppSecret: SecretInput{Plain: "fake_top_level_secret"},
+		Brand:     "feishu",
+		Accounts: map[string]*FeishuAccount{
+			"default": {}, // empty — should inherit everything from top-level
+			"other": {
+				Enabled:   boolPtr(true),
+				AppID:     "cli_fake_other",
+				AppSecret: SecretInput{Plain: "fake_other_secret"},
+			},
+		},
+	}
+	got := ListCandidateApps(ch)
+	if len(got) != 2 {
+		t.Fatalf("count = %d, want 2", len(got))
+	}
+	// Find the "default" account
+	var def *CandidateApp
+	for i := range got {
+		if got[i].Label == "default" {
+			def = &got[i]
+		}
+	}
+	if def == nil {
+		t.Fatal("default account not found in candidates")
+	}
+	if def.AppID != "cli_fake_top_level" {
+		t.Errorf("default appId = %q, want inherited top-level", def.AppID)
+	}
+	if def.AppSecret.IsZero() {
+		t.Error("default appSecret should inherit from top-level, got zero")
+	}
+	if def.AppSecret.Plain != "fake_top_level_secret" {
+		t.Errorf("default appSecret = %q, want inherited top-level", def.AppSecret.Plain)
+	}
+	if def.Brand != "feishu" {
+		t.Errorf("default brand = %q, want inherited top-level", def.Brand)
+	}
+}
+
+func TestListCandidateApps_ImplicitDefault_WhenTopLevelHasCredentials(t *testing.T) {
+	// When accounts exist but none is named "default", and top-level has
+	// its own appId+appSecret, the top-level should be included as a
+	// synthetic "default" candidate (aligned with openclaw-lark plugin).
+	ch := &FeishuChannel{
+		AppID:     "cli_top",
+		AppSecret: SecretInput{Plain: "top_secret"},
+		Brand:     "feishu",
+		Accounts: map[string]*FeishuAccount{
+			"ethan": {
+				AppID:     "cli_ethan",
+				AppSecret: SecretInput{Plain: "ethan_secret"},
+				Brand:     "lark",
+			},
+		},
+	}
+	got := ListCandidateApps(ch)
+	if len(got) != 2 {
+		t.Fatalf("count = %d, want 2 (default + ethan)", len(got))
+	}
+	var def, ethan *CandidateApp
+	for i := range got {
+		switch got[i].Label {
+		case "default":
+			def = &got[i]
+		case "ethan":
+			ethan = &got[i]
+		}
+	}
+	if def == nil {
+		t.Fatal("implicit default candidate not found")
+	}
+	if def.AppID != "cli_top" {
+		t.Errorf("default appId = %q, want %q", def.AppID, "cli_top")
+	}
+	if ethan == nil {
+		t.Fatal("ethan candidate not found")
+	}
+	if ethan.AppID != "cli_ethan" {
+		t.Errorf("ethan appId = %q, want %q", ethan.AppID, "cli_ethan")
+	}
+}
+
+func TestListCandidateApps_NoImplicitDefault_WhenExplicitDefaultExists(t *testing.T) {
+	// When accounts already contain a "default" entry, don't duplicate it.
+	ch := &FeishuChannel{
+		AppID:     "cli_top",
+		AppSecret: SecretInput{Plain: "top_secret"},
+		Accounts: map[string]*FeishuAccount{
+			"default": {}, // inherits top-level
+			"other":   {AppID: "cli_other", AppSecret: SecretInput{Plain: "s"}},
+		},
+	}
+	got := ListCandidateApps(ch)
+	defaultCount := 0
+	for _, c := range got {
+		if c.Label == "default" {
+			defaultCount++
+		}
+	}
+	if defaultCount != 1 {
+		t.Errorf("expected exactly 1 default candidate, got %d", defaultCount)
+	}
+}
+
+func TestListCandidateApps_NoImplicitDefault_WhenTopLevelMissingSecret(t *testing.T) {
+	// Top-level has appId but no appSecret → no implicit default.
+	ch := &FeishuChannel{
+		AppID: "cli_top",
+		// no appSecret
+		Accounts: map[string]*FeishuAccount{
+			"ethan": {AppID: "cli_ethan", AppSecret: SecretInput{Plain: "s"}},
+		},
+	}
+	got := ListCandidateApps(ch)
+	if len(got) != 1 {
+		t.Fatalf("count = %d, want 1 (only ethan)", len(got))
+	}
+	if got[0].Label != "ethan" {
+		t.Errorf("label = %q, want %q", got[0].Label, "ethan")
+	}
+}
+
+func boolPtr(v bool) *bool { return &v }
+
+func TestListCandidateApps_MultiAccount_DisabledFiltered(t *testing.T) {
+	disabled := false
+	ch := &FeishuChannel{
+		Accounts: map[string]*FeishuAccount{
+			"active": {
+				AppID:     "cli_active",
+				AppSecret: SecretInput{Plain: "secret"},
+			},
+			"disabled": {
+				Enabled:   &disabled,
+				AppID:     "cli_disabled",
+				AppSecret: SecretInput{Plain: "secret"},
+			},
+			"nil_acct": nil,
+		},
+	}
+	got := ListCandidateApps(ch)
+	if len(got) != 1 {
+		t.Fatalf("count = %d, want 1 (disabled and nil filtered out)", len(got))
+	}
+	if got[0].AppID != "cli_active" {
+		t.Errorf("appId = %q, want %q", got[0].AppID, "cli_active")
+	}
+}
+
+func TestListCandidateApps_EmptyAppID(t *testing.T) {
+	ch := &FeishuChannel{
+		AppID: "",
+		// No accounts, no appId → no candidates
+	}
+	got := ListCandidateApps(ch)
+	if len(got) != 0 {
+		t.Errorf("expected 0 apps for empty appId, got %d", len(got))
+	}
+}
+
+func TestIsEnabled_Nil(t *testing.T) {
+	if !isEnabled(nil) {
+		t.Error("nil should default to enabled")
+	}
+}
+
+func TestIsEnabled_True(t *testing.T) {
+	v := true
+	if !isEnabled(&v) {
+		t.Error("explicit true should be enabled")
+	}
+}
+
+func TestIsEnabled_False(t *testing.T) {
+	v := false
+	if isEnabled(&v) {
+		t.Error("explicit false should be disabled")
+	}
+}

internal/client/response.go

@@ -23,12 +23,13 @@ import (
 
 // ResponseOptions configures how HandleResponse routes a raw API response.
 type ResponseOptions struct {
-	OutputPath string        // --output flag; "" = auto-detect
-	Format     output.Format // output format for JSON responses
-	JqExpr     string        // if set, apply jq filter instead of Format
-	Out        io.Writer     // stdout
-	ErrOut     io.Writer     // stderr
-	FileIO     fileio.FileIO // file transfer abstraction; required when saving files (--output or binary response)
+	OutputPath  string        // --output flag; "" = auto-detect
+	Format      output.Format // output format for JSON responses
+	JqExpr      string        // if set, apply jq filter instead of Format
+	Out         io.Writer     // stdout
+	ErrOut      io.Writer     // stderr
+	FileIO      fileio.FileIO // file transfer abstraction; required when saving files (--output or binary response)
+	CommandPath string        // raw cobra CommandPath() for content safety scanning
 	// CheckError is called on parsed JSON results. Nil defaults to CheckLarkResponse.
 	CheckError func(interface{}) error
 }
@@ -60,9 +61,20 @@ func HandleResponse(resp *larkcore.ApiResp, opts ResponseOptions) error {
 		if apiErr := check(result); apiErr != nil {
 			return apiErr
 		}
+		// Content safety scanning
+		scanResult := output.ScanForSafety(opts.CommandPath, result, opts.ErrOut)
+		if scanResult.Blocked {
+			return scanResult.BlockErr
+		}
 		if opts.OutputPath != "" {
+			if scanResult.Alert != nil {
+				output.WriteAlertWarning(opts.ErrOut, scanResult.Alert)
+			}
 			return saveAndPrint(opts.FileIO, resp, opts.OutputPath, opts.Out)
 		}
+		if scanResult.Alert != nil {
+			output.WriteAlertWarning(opts.ErrOut, scanResult.Alert)
+		}
 		if opts.JqExpr != "" {
 			return output.JqFilter(opts.Out, result, opts.JqExpr)
 		}

internal/cmdutil/completion.go

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"sync/atomic"
+
+	"github.com/spf13/cobra"
+)
+
+// Cobra keeps completion callbacks in a package-global map keyed by
+// *pflag.Flag with no removal path, so registrations made for a *cobra.Command
+// outlive the command itself. Skip registration when the current invocation
+// will not serve a completion request.
+var flagCompletionsDisabled atomic.Bool
+
+// SetFlagCompletionsDisabled switches RegisterFlagCompletion between
+// registering and no-op. Typically set once at process start.
+func SetFlagCompletionsDisabled(disabled bool) {
+	flagCompletionsDisabled.Store(disabled)
+}
+
+// FlagCompletionsDisabled reports the current switch state.
+func FlagCompletionsDisabled() bool {
+	return flagCompletionsDisabled.Load()
+}
+
+// RegisterFlagCompletion wraps (*cobra.Command).RegisterFlagCompletionFunc
+// and honors the package switch. The underlying error is swallowed to match
+// the `_ = cmd.RegisterFlagCompletionFunc(...)` style already used here.
+func RegisterFlagCompletion(cmd *cobra.Command, flagName string, fn cobra.CompletionFunc) {
+	if flagCompletionsDisabled.Load() {
+		return
+	}
+	_ = cmd.RegisterFlagCompletionFunc(flagName, fn)
+}

internal/cmdutil/completion_test.go

@@ -0,0 +1,78 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"runtime"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+func TestSetFlagCompletionsDisabled_RoundTrip(t *testing.T) {
+	t.Cleanup(func() { SetFlagCompletionsDisabled(false) })
+
+	if FlagCompletionsDisabled() {
+		t.Fatal("expected default false")
+	}
+	SetFlagCompletionsDisabled(true)
+	if !FlagCompletionsDisabled() {
+		t.Fatal("expected true after Set(true)")
+	}
+	SetFlagCompletionsDisabled(false)
+	if FlagCompletionsDisabled() {
+		t.Fatal("expected false after Set(false)")
+	}
+}
+
+// When disabled, a *cobra.Command must be collectable after the caller drops
+// its reference — i.e. the wrapper did not touch cobra's global map.
+func TestRegisterFlagCompletion_Disabled_DoesNotRetainCommand(t *testing.T) {
+	SetFlagCompletionsDisabled(true)
+	t.Cleanup(func() { SetFlagCompletionsDisabled(false) })
+
+	const N = 5
+	var collected atomic.Int32
+	func() {
+		for range N {
+			cmd := &cobra.Command{Use: "x"}
+			cmd.Flags().String("foo", "", "")
+			RegisterFlagCompletion(cmd, "foo", func(_ *cobra.Command, _ []string, _ string) ([]cobra.Completion, cobra.ShellCompDirective) {
+				return nil, cobra.ShellCompDirectiveNoFileComp
+			})
+			runtime.SetFinalizer(cmd, func(_ *cobra.Command) { collected.Add(1) })
+		}
+	}()
+	// Finalizers run on a dedicated goroutine after GC; loop to give it time.
+	for range 30 {
+		runtime.GC()
+		time.Sleep(20 * time.Millisecond)
+	}
+	if got := collected.Load(); int(got) != N {
+		t.Fatalf("expected %d *cobra.Command finalizers to fire when completions disabled, got %d", N, got)
+	}
+}
+
+// When enabled, the registered completion must be reachable via cobra.
+func TestRegisterFlagCompletion_Enabled_DoesRegister(t *testing.T) {
+	SetFlagCompletionsDisabled(false)
+
+	cmd := &cobra.Command{Use: "x"}
+	cmd.Flags().String("foo", "", "")
+	want := []cobra.Completion{"a", "b"}
+	RegisterFlagCompletion(cmd, "foo", func(_ *cobra.Command, _ []string, _ string) ([]cobra.Completion, cobra.ShellCompDirective) {
+		return want, cobra.ShellCompDirectiveNoFileComp
+	})
+
+	fn, ok := cmd.GetFlagCompletionFunc("foo")
+	if !ok {
+		t.Fatal("expected completion func to be registered")
+	}
+	got, _ := fn(cmd, nil, "")
+	if len(got) != 2 || got[0] != "a" || got[1] != "b" {
+		t.Fatalf("unexpected completion result: %v", got)
+	}
+}

internal/cmdutil/factory_default.go

@@ -14,7 +14,6 @@ import (
 
 	lark "github.com/larksuite/oapi-sdk-go/v3"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-	"golang.org/x/term"
 
 	extcred "github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/extension/fileio"
@@ -23,6 +22,7 @@ import (
 	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/registry"
+	_ "github.com/larksuite/cli/internal/security/contentsafety" // register content safety provider
 	"github.com/larksuite/cli/internal/util"
 	_ "github.com/larksuite/cli/internal/vfs/localfileio" // register default FileIO provider
 )
@@ -34,27 +34,34 @@ import (
 //	Phase 2: Credential (sole data source for account info)
 //	Phase 3: Config derived from Credential
 //	Phase 4: LarkClient derived from Credential
-func NewDefault(inv InvocationContext) *Factory {
+func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
+	streams = normalizeStreams(streams)
 	f := &Factory{
 		Keychain:   keychain.Default(),
 		Invocation: inv,
+		IOStreams:  streams,
 	}
-	f.IOStreams = &IOStreams{
-		In:         os.Stdin,
-		Out:        os.Stdout,
-		ErrOut:     os.Stderr,
-		IsTerminal: term.IsTerminal(int(os.Stdin.Fd())),
-	}
+
+	// Workspace detection: determines which config subtree to use.
+	// Must run before any config or credential load, since those paths are
+	// workspace-scoped. Default is WorkspaceLocal — existing behavior unchanged.
+	ws := core.DetectWorkspaceFromEnv(os.Getenv)
+	core.SetCurrentWorkspace(ws)
+
+	// Inject workspace-aware dir into keychain's log system.
+	// This breaks the core↔keychain import cycle by using a function variable.
+	keychain.RuntimeDirFunc = core.GetRuntimeDir
 
 	// Phase 0: FileIO provider (no dependency)
 	f.FileIOProvider = fileio.GetProvider()
 
 	// Phase 1: HttpClient (no credential dependency)
-	f.HttpClient = cachedHttpClientFunc()
+	f.HttpClient = cachedHttpClientFunc(f)
 
 	// Phase 2: Credential (sole data source)
+	// Keychain is read via closure so callers can replace f.Keychain after construction.
 	f.Credential = buildCredentialProvider(credentialDeps{
-		Keychain:   f.Keychain,
+		Keychain:   func() keychain.KeychainAccess { return f.Keychain },
 		Profile:    inv.Profile,
 		HttpClient: f.HttpClient,
 		ErrOut:     f.IOStreams.ErrOut,
@@ -93,11 +100,11 @@ func safeRedirectPolicy(req *http.Request, via []*http.Request) error {
 	return nil
 }
 
-func cachedHttpClientFunc() func() (*http.Client, error) {
+func cachedHttpClientFunc(f *Factory) func() (*http.Client, error) {
 	return sync.OnceValues(func() (*http.Client, error) {
-		util.WarnIfProxied(os.Stderr)
+		util.WarnIfProxied(f.IOStreams.ErrOut)
 
-		var transport http.RoundTripper = util.NewBaseTransport()
+		var transport http.RoundTripper = util.SharedTransport()
 		transport = &RetryTransport{Base: transport}
 		transport = &SecurityHeaderTransport{Base: transport}
 		transport = &auth.SecurityPolicyTransport{Base: transport} // Add our global response interceptor
@@ -122,7 +129,7 @@ func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
 			lark.WithLogLevel(larkcore.LogLevelError),
 			lark.WithHeaders(BaseSecurityHeaders()),
 		}
-		util.WarnIfProxied(os.Stderr)
+		util.WarnIfProxied(f.IOStreams.ErrOut)
 		opts = append(opts, lark.WithHttpClient(&http.Client{
 			Transport:     buildSDKTransport(),
 			CheckRedirect: safeRedirectPolicy,
@@ -134,15 +141,16 @@ func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
 }
 
 func buildSDKTransport() http.RoundTripper {
-	var sdkTransport http.RoundTripper = util.NewBaseTransport()
+	var sdkTransport http.RoundTripper = util.SharedTransport()
 	sdkTransport = &RetryTransport{Base: sdkTransport}
 	sdkTransport = &UserAgentTransport{Base: sdkTransport}
+	sdkTransport = &BuildHeaderTransport{Base: sdkTransport}
 	sdkTransport = &auth.SecurityPolicyTransport{Base: sdkTransport}
 	return wrapWithExtension(sdkTransport)
 }
 
 type credentialDeps struct {
-	Keychain   keychain.KeychainAccess
+	Keychain   func() keychain.KeychainAccess
 	Profile    string
 	HttpClient func() (*http.Client, error)
 	ErrOut     io.Writer

internal/cmdutil/factory_default_test.go

@@ -6,14 +6,10 @@ package cmdutil
 import (
 	"context"
 	"errors"
-	"net/http"
-	"net/http/httptest"
 	"testing"
 
 	_ "github.com/larksuite/cli/extension/credential/env"
 	"github.com/larksuite/cli/extension/fileio"
-	exttransport "github.com/larksuite/cli/extension/transport"
-	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/envvars"
@@ -63,7 +59,7 @@ func TestNewDefault_InvocationProfileUsedByStrictModeAndConfig(t *testing.T) {
 		t.Fatalf("SaveMultiAppConfig() error = %v", err)
 	}
 
-	f := NewDefault(InvocationContext{Profile: "target"})
+	f := NewDefault(nil, InvocationContext{Profile: "target"})
 	if got := f.ResolveStrictMode(context.Background()); got != core.StrictModeBot {
 		t.Fatalf("ResolveStrictMode() = %q, want %q", got, core.StrictModeBot)
 	}
@@ -103,7 +99,7 @@ func TestNewDefault_InvocationProfileMissingSticksAcrossEarlyStrictMode(t *testi
 		t.Fatalf("SaveMultiAppConfig() error = %v", err)
 	}
 
-	f := NewDefault(InvocationContext{Profile: "missing"})
+	f := NewDefault(nil, InvocationContext{Profile: "missing"})
 	if got := f.ResolveStrictMode(context.Background()); got != core.StrictModeOff {
 		t.Fatalf("ResolveStrictMode() = %q, want %q", got, core.StrictModeOff)
 	}
@@ -120,22 +116,6 @@ func TestNewDefault_InvocationProfileMissingSticksAcrossEarlyStrictMode(t *testi
 	}
 }
 
-func TestBuildSDKTransport_IncludesRetryTransport(t *testing.T) {
-	transport := buildSDKTransport()
-
-	sec, ok := transport.(*internalauth.SecurityPolicyTransport)
-	if !ok {
-		t.Fatalf("outer transport type = %T, want *auth.SecurityPolicyTransport", transport)
-	}
-	ua, ok := sec.Base.(*UserAgentTransport)
-	if !ok {
-		t.Fatalf("middle transport type = %T, want *UserAgentTransport", sec.Base)
-	}
-	if _, ok := ua.Base.(*RetryTransport); !ok {
-		t.Fatalf("inner transport type = %T, want *RetryTransport", ua.Base)
-	}
-}
-
 func TestNewDefault_ResolveAs_UsesDefaultAsFromEnvAccount(t *testing.T) {
 	t.Setenv(envvars.CliAppID, "env-app")
 	t.Setenv(envvars.CliAppSecret, "env-secret")
@@ -144,7 +124,7 @@ func TestNewDefault_ResolveAs_UsesDefaultAsFromEnvAccount(t *testing.T) {
 	t.Setenv(envvars.CliTenantAccessToken, "")
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
-	f := NewDefault(InvocationContext{})
+	f := NewDefault(nil, InvocationContext{})
 	cmd := newCmdWithAsFlag("auto", false)
 
 	got := f.ResolveAs(context.Background(), cmd, "auto")
@@ -164,7 +144,7 @@ func TestNewDefault_ConfigReturnsCliConfigCopyOfCredentialAccount(t *testing.T)
 	t.Setenv(envvars.CliTenantAccessToken, "")
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
-	f := NewDefault(InvocationContext{})
+	f := NewDefault(nil, InvocationContext{})
 
 	acct, err := f.Credential.ResolveAccount(context.Background())
 	if err != nil {
@@ -189,7 +169,7 @@ func TestNewDefault_ConfigUsesRuntimePlaceholderForTokenOnlyEnvAccount(t *testin
 	t.Setenv(envvars.CliTenantAccessToken, "")
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
-	f := NewDefault(InvocationContext{})
+	f := NewDefault(nil, InvocationContext{})
 
 	acct, err := f.Credential.ResolveAccount(context.Background())
 	if err != nil {
@@ -217,7 +197,7 @@ func TestNewDefault_FileIOProviderDoesNotResolveDuringInitialization(t *testing.
 	fileio.Register(provider)
 	t.Cleanup(func() { fileio.Register(prev) })
 
-	f := NewDefault(InvocationContext{})
+	f := NewDefault(nil, InvocationContext{})
 	if f.FileIOProvider != provider {
 		t.Fatalf("NewDefault() provider = %T, want %T", f.FileIOProvider, provider)
 	}
@@ -232,170 +212,3 @@ func TestNewDefault_FileIOProviderDoesNotResolveDuringInitialization(t *testing.
 		t.Fatalf("ResolveFileIO() calls after explicit resolve = %d, want 1", provider.resolveCalls)
 	}
 }
-
-type stubTransportProvider struct {
-	interceptor exttransport.Interceptor
-}
-
-func (s *stubTransportProvider) Name() string { return "stub" }
-func (s *stubTransportProvider) ResolveInterceptor(context.Context) exttransport.Interceptor {
-	if s.interceptor != nil {
-		return s.interceptor
-	}
-	return &stubTransportImpl{}
-}
-
-type stubTransportImpl struct{}
-
-func (s *stubTransportImpl) PreRoundTrip(req *http.Request) func(*http.Response, error) {
-	return nil
-}
-
-// headerCapturingInterceptor sets custom headers in PreRoundTrip and records
-// whether PostRoundTrip was called, to verify execution order.
-type headerCapturingInterceptor struct {
-	preCalled  bool
-	postCalled bool
-}
-
-func (h *headerCapturingInterceptor) PreRoundTrip(req *http.Request) func(*http.Response, error) {
-	h.preCalled = true
-	// Set a custom header that should survive (no built-in override)
-	req.Header.Set("X-Custom-Trace", "ext-trace-123")
-	// Try to override a security header — should be overwritten by SecurityHeaderTransport
-	req.Header.Set(HeaderSource, "ext-tampered")
-	return func(resp *http.Response, err error) {
-		h.postCalled = true
-	}
-}
-
-func TestExtensionInterceptor_ExecutionOrder(t *testing.T) {
-	var receivedHeaders http.Header
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		receivedHeaders = r.Header.Clone()
-		w.WriteHeader(http.StatusOK)
-	}))
-	defer srv.Close()
-
-	ic := &headerCapturingInterceptor{}
-	exttransport.Register(&stubTransportProvider{interceptor: ic})
-	t.Cleanup(func() { exttransport.Register(nil) })
-
-	// Use HTTP transport chain (has SecurityHeaderTransport)
-	var base http.RoundTripper = http.DefaultTransport
-	base = &RetryTransport{Base: base}
-	base = &SecurityHeaderTransport{Base: base}
-	transport := wrapWithExtension(base)
-	client := &http.Client{Transport: transport}
-
-	req, _ := http.NewRequest("GET", srv.URL, nil)
-	resp, err := client.Do(req)
-	if err != nil {
-		t.Fatalf("request failed: %v", err)
-	}
-	resp.Body.Close()
-
-	// PreRoundTrip was called
-	if !ic.preCalled {
-		t.Fatal("PreRoundTrip was not called")
-	}
-	// PostRoundTrip (closure) was called
-	if !ic.postCalled {
-		t.Fatal("PostRoundTrip closure was not called")
-	}
-	// Custom header set by extension survives (no built-in override)
-	if got := receivedHeaders.Get("X-Custom-Trace"); got != "ext-trace-123" {
-		t.Fatalf("X-Custom-Trace = %q, want %q", got, "ext-trace-123")
-	}
-	// Security header overridden by extension is restored by SecurityHeaderTransport
-	if got := receivedHeaders.Get(HeaderSource); got != SourceValue {
-		t.Fatalf("%s = %q, want %q (built-in should override extension)", HeaderSource, got, SourceValue)
-	}
-}
-
-func TestExtensionInterceptor_ContextTamperPrevented(t *testing.T) {
-	type ctxKeyType string
-	const testKey ctxKeyType = "original"
-
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(http.StatusOK)
-	}))
-	defer srv.Close()
-
-	var ctxValue any
-
-	// Use a custom transport that captures the context value seen by the built-in chain
-	capturer := roundTripFunc(func(req *http.Request) (*http.Response, error) {
-		ctxValue = req.Context().Value(testKey)
-		return http.DefaultTransport.RoundTrip(req)
-	})
-
-	// Interceptor that tries to tamper with context
-	tamperIC := interceptorFunc(func(req *http.Request) func(*http.Response, error) {
-		// Try to replace context with a new one
-		*req = *req.WithContext(context.WithValue(req.Context(), testKey, "tampered"))
-		return nil
-	})
-
-	mid := &extensionMiddleware{Base: capturer, Ext: tamperIC}
-
-	origCtx := context.WithValue(context.Background(), testKey, "original")
-	req, _ := http.NewRequestWithContext(origCtx, "GET", srv.URL, nil)
-	resp, err := mid.RoundTrip(req)
-	if err != nil {
-		t.Fatalf("request failed: %v", err)
-	}
-	resp.Body.Close()
-
-	// Built-in chain should see original context, not tampered
-	if ctxValue != "original" {
-		t.Fatalf("built-in chain saw context value %q, want %q", ctxValue, "original")
-	}
-}
-
-// interceptorFunc adapts a function to exttransport.Interceptor.
-type interceptorFunc func(*http.Request) func(*http.Response, error)
-
-func (f interceptorFunc) PreRoundTrip(req *http.Request) func(*http.Response, error) { return f(req) }
-
-func TestBuildSDKTransport_WithExtension(t *testing.T) {
-	exttransport.Register(&stubTransportProvider{})
-	t.Cleanup(func() { exttransport.Register(nil) })
-
-	transport := buildSDKTransport()
-
-	// Chain: extensionMiddleware → SecurityPolicy → UserAgent → Retry → Base
-	mid, ok := transport.(*extensionMiddleware)
-	if !ok {
-		t.Fatalf("outer transport type = %T, want *extensionMiddleware", transport)
-	}
-	sec, ok := mid.Base.(*internalauth.SecurityPolicyTransport)
-	if !ok {
-		t.Fatalf("transport type = %T, want *auth.SecurityPolicyTransport", mid.Base)
-	}
-	ua, ok := sec.Base.(*UserAgentTransport)
-	if !ok {
-		t.Fatalf("transport type = %T, want *UserAgentTransport", sec.Base)
-	}
-	if _, ok := ua.Base.(*RetryTransport); !ok {
-		t.Fatalf("innermost transport type = %T, want *RetryTransport", ua.Base)
-	}
-}
-
-func TestBuildSDKTransport_WithoutExtension(t *testing.T) {
-	exttransport.Register(nil)
-
-	transport := buildSDKTransport()
-
-	sec, ok := transport.(*internalauth.SecurityPolicyTransport)
-	if !ok {
-		t.Fatalf("outer transport type = %T, want *auth.SecurityPolicyTransport", transport)
-	}
-	ua, ok := sec.Base.(*UserAgentTransport)
-	if !ok {
-		t.Fatalf("middle transport type = %T, want *UserAgentTransport", sec.Base)
-	}
-	if _, ok := ua.Base.(*RetryTransport); !ok {
-		t.Fatalf("inner transport type = %T, want *RetryTransport", ua.Base)
-	}
-}

internal/cmdutil/factory_http_test.go

@@ -4,11 +4,12 @@
 package cmdutil
 
 import (
+	"io"
 	"testing"
 )
 
 func TestCachedHttpClientFunc_ReturnsSameInstance(t *testing.T) {
-	fn := cachedHttpClientFunc()
+	fn := cachedHttpClientFunc(&Factory{IOStreams: &IOStreams{ErrOut: io.Discard}})
 
 	c1, err := fn()
 	if err != nil {
@@ -28,7 +29,7 @@ func TestCachedHttpClientFunc_ReturnsSameInstance(t *testing.T) {
 }
 
 func TestCachedHttpClientFunc_HasTimeout(t *testing.T) {
-	fn := cachedHttpClientFunc()
+	fn := cachedHttpClientFunc(&Factory{IOStreams: &IOStreams{ErrOut: io.Discard}})
 	c, _ := fn()
 	if c.Timeout == 0 {
 		t.Error("expected non-zero timeout")
@@ -36,7 +37,7 @@ func TestCachedHttpClientFunc_HasTimeout(t *testing.T) {
 }
 
 func TestCachedHttpClientFunc_HasRedirectPolicy(t *testing.T) {
-	fn := cachedHttpClientFunc()
+	fn := cachedHttpClientFunc(&Factory{IOStreams: &IOStreams{ErrOut: io.Discard}})
 	c, _ := fn()
 	if c.CheckRedirect == nil {
 		t.Error("expected CheckRedirect to be set (safeRedirectPolicy)")

internal/cmdutil/fileupload.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"fmt"
 	"io"
+	"strconv"
 	"strings"
 
 	"github.com/larksuite/cli/extension/fileio"
@@ -122,9 +123,22 @@ func BuildFormdata(fileIO fileio.FileIO, fieldName, filePath string, isStdin boo
 	// Add top-level JSON keys as text form fields.
 	if m, ok := dataJSON.(map[string]any); ok {
 		for k, v := range m {
-			fd.AddField(k, fmt.Sprintf("%v", v))
+			fd.AddField(k, formatFormFieldValue(v))
 		}
 	}
 
 	return fd, nil
 }
+
+// formatFormFieldValue renders a JSON-unmarshalled value as a multipart form
+// field string. float64 is handled specially: fmt's default %v/%g switches to
+// scientific notation for values >= ~1e6 (e.g. "1.185356e+06"), which some
+// backends reject when parsing the field as an integer. Use decimal notation
+// instead so size / block_num / offset-style numeric fields round-trip cleanly.
+// All other types fall through to %v.
+func formatFormFieldValue(v any) string {
+	if n, ok := v.(float64); ok {
+		return strconv.FormatFloat(n, 'f', -1, 64)
+	}
+	return fmt.Sprintf("%v", v)
+}

internal/cmdutil/fileupload_test.go

@@ -336,3 +336,40 @@ func TestBuildFormdata(t *testing.T) {
 		}
 	})
 }
+
+// TestFormatFormFieldValue locks in the fix for the float64 -> scientific
+// notation bug. JSON numbers unmarshal to float64, and fmt's default %v for
+// float64 delegates to %g which switches to scientific notation at ~1e6
+// (e.g. 1185356 -> "1.185356e+06"). Backends that parse the form field as an
+// integer reject that, surfacing as a generic "params error".
+func TestFormatFormFieldValue(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		in   any
+		want string
+	}{
+		{"float64 large integer avoids scientific", float64(1185356), "1185356"},
+		{"float64 below scientific threshold", float64(358934), "358934"},
+		{"float64 zero", float64(0), "0"},
+		{"float64 huge", float64(20 * 1024 * 1024), "20971520"},
+		{"float64 negative", float64(-42), "-42"},
+		{"float64 fractional preserved", float64(3.14), "3.14"},
+		{"string pass-through", "hello", "hello"},
+		{"bool true", true, "true"},
+		{"int via %v", 42, "42"},
+		{"int64 via %v", int64(9007199254740992), "9007199254740992"},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := formatFormFieldValue(tt.in)
+			if got != tt.want {
+				t.Fatalf("formatFormFieldValue(%v) = %q, want %q", tt.in, got, tt.want)
+			}
+		})
+	}
+}

internal/cmdutil/identity_flag.go

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// AddAPIIdentityFlag registers the standard --as flag shape used by api/service commands.
+func AddAPIIdentityFlag(ctx context.Context, cmd *cobra.Command, f *Factory, target *string) {
+	addIdentityFlag(ctx, cmd, f, target, identityFlagConfig{
+		defaultValue:     "auto",
+		usage:            "identity type: user | bot | auto (default)",
+		completionValues: []string{"user", "bot"},
+	})
+}
+
+// AddShortcutIdentityFlag registers the standard --as flag shape used by shortcuts.
+func AddShortcutIdentityFlag(ctx context.Context, cmd *cobra.Command, f *Factory, authTypes []string) {
+	if len(authTypes) == 0 {
+		authTypes = []string{"user"}
+	}
+	addIdentityFlag(ctx, cmd, f, nil, identityFlagConfig{
+		defaultValue:     authTypes[0],
+		usage:            "identity type: " + strings.Join(authTypes, " | "),
+		completionValues: authTypes,
+	})
+}
+
+type identityFlagConfig struct {
+	defaultValue     string
+	usage            string
+	completionValues []string
+}
+
+// addIdentityFlag centralizes --as registration and strict-mode UX.
+// When strict mode is active, the flag is still accepted for compatibility
+// but hidden from help/completion and locked to the forced identity by default.
+func addIdentityFlag(ctx context.Context, cmd *cobra.Command, f *Factory, target *string, cfg identityFlagConfig) {
+	if forced := f.ResolveStrictMode(ctx).ForcedIdentity(); forced != "" {
+		// Keep registering --as in strict mode even though it is hidden.
+		// This preserves parser compatibility for existing invocations that still pass
+		// --as, and keeps downstream GetString("as") / ResolveAs paths stable.
+		// The usage text below is effectively placeholder text because the flag is hidden.
+		registerIdentityFlag(cmd, target, string(forced),
+			fmt.Sprintf("identity locked to %s by strict mode (admin-managed)", forced))
+		_ = cmd.Flags().MarkHidden("as")
+		return
+	}
+
+	registerIdentityFlag(cmd, target, cfg.defaultValue, cfg.usage)
+	RegisterFlagCompletion(cmd, "as", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+		return cfg.completionValues, cobra.ShellCompDirectiveNoFileComp
+	})
+}
+
+func registerIdentityFlag(cmd *cobra.Command, target *string, defaultValue, usage string) {
+	if target != nil {
+		cmd.Flags().StringVar(target, "as", defaultValue, usage)
+		return
+	}
+	cmd.Flags().String("as", defaultValue, usage)
+}

internal/cmdutil/identity_flag_test.go

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"context"
+	"testing"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/spf13/cobra"
+)
+
+func TestAddAPIIdentityFlag_NonStrictMode(t *testing.T) {
+	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "a", AppSecret: "s"})
+	cmd := &cobra.Command{Use: "test"}
+
+	AddAPIIdentityFlag(context.Background(), cmd, f, nil)
+
+	flag := cmd.Flags().Lookup("as")
+	if flag == nil {
+		t.Fatal("expected --as flag to be registered")
+	}
+	if flag.Hidden {
+		t.Fatal("expected --as flag to be visible outside strict mode")
+	}
+	if got := flag.DefValue; got != "auto" {
+		t.Fatalf("default value = %q, want %q", got, "auto")
+	}
+}
+
+func TestAddAPIIdentityFlag_StrictModeHidesFlagAndLocksDefault(t *testing.T) {
+	f, _, _, _ := TestFactory(t, &core.CliConfig{
+		AppID: "a", AppSecret: "s", SupportedIdentities: 2,
+	})
+	cmd := &cobra.Command{Use: "test"}
+
+	AddAPIIdentityFlag(context.Background(), cmd, f, nil)
+
+	flag := cmd.Flags().Lookup("as")
+	if flag == nil {
+		t.Fatal("expected --as flag to be registered")
+	}
+	if !flag.Hidden {
+		t.Fatal("expected --as flag to be hidden in strict mode")
+	}
+	if got := flag.DefValue; got != "bot" {
+		t.Fatalf("default value = %q, want %q", got, "bot")
+	}
+}
+
+func TestAddShortcutIdentityFlag_UsesAuthTypes(t *testing.T) {
+	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "a", AppSecret: "s"})
+	cmd := &cobra.Command{Use: "test"}
+
+	AddShortcutIdentityFlag(context.Background(), cmd, f, []string{"bot"})
+
+	flag := cmd.Flags().Lookup("as")
+	if flag == nil {
+		t.Fatal("expected --as flag to be registered")
+	}
+	if flag.Hidden {
+		t.Fatal("expected --as flag to be visible outside strict mode")
+	}
+	if got := flag.DefValue; got != "bot" {
+		t.Fatalf("default value = %q, want %q", got, "bot")
+	}
+}

internal/cmdutil/iostreams.go

@@ -3,7 +3,12 @@
 
 package cmdutil
 
-import "io"
+import (
+	"io"
+	"os"
+
+	"golang.org/x/term"
+)
 
 // IOStreams provides the standard input/output/error streams.
 // Commands should use these instead of os.Stdin/Stdout/Stderr
@@ -14,3 +19,45 @@ type IOStreams struct {
 	ErrOut     io.Writer
 	IsTerminal bool
 }
+
+// NewIOStreams builds an IOStreams from arbitrary readers/writers.
+// IsTerminal is derived from in's underlying *os.File, if any; non-file
+// readers (bytes.Buffer, strings.Reader, …) yield IsTerminal=false.
+func NewIOStreams(in io.Reader, out, errOut io.Writer) *IOStreams {
+	isTerminal := false
+	if f, ok := in.(*os.File); ok {
+		isTerminal = term.IsTerminal(int(f.Fd()))
+	}
+	return &IOStreams{In: in, Out: out, ErrOut: errOut, IsTerminal: isTerminal}
+}
+
+// SystemIO creates an IOStreams wired to the process's standard file descriptors.
+//
+//nolint:forbidigo // entry point for real stdio
+func SystemIO() *IOStreams {
+	return NewIOStreams(os.Stdin, os.Stdout, os.Stderr)
+}
+
+// normalizeStreams returns a fresh IOStreams with any nil field filled from
+// SystemIO(). Callers constructing a partial struct like &IOStreams{Out: buf}
+// get a usable result without nil writers leaking into RoundTripper warnings,
+// Cobra I/O, or credential-provider error paths.
+func normalizeStreams(s *IOStreams) *IOStreams {
+	if s == nil {
+		return SystemIO()
+	}
+	out := *s
+	if out.In == nil || out.Out == nil || out.ErrOut == nil {
+		sys := SystemIO()
+		if out.In == nil {
+			out.In = sys.In
+		}
+		if out.Out == nil {
+			out.Out = sys.Out
+		}
+		if out.ErrOut == nil {
+			out.ErrOut = sys.ErrOut
+		}
+	}
+	return &out
+}

internal/cmdutil/retry_transport_test.go

@@ -1,81 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmdutil
-
-import (
-	"io"
-	"net/http"
-	"strings"
-	"testing"
-	"time"
-)
-
-type roundTripFunc func(*http.Request) (*http.Response, error)
-
-func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
-	return f(req)
-}
-
-func TestRetryTransport_NoRetry(t *testing.T) {
-	calls := 0
-	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
-		calls++
-		return &http.Response{StatusCode: 200, Body: io.NopCloser(strings.NewReader("ok"))}, nil
-	})
-	rt := &RetryTransport{Base: base, MaxRetries: 0}
-	req, _ := http.NewRequest("GET", "http://example.com/test", nil)
-	resp, err := rt.RoundTrip(req)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if resp.StatusCode != 200 {
-		t.Errorf("expected 200, got %d", resp.StatusCode)
-	}
-	if calls != 1 {
-		t.Errorf("expected 1 call, got %d", calls)
-	}
-}
-
-func TestRetryTransport_RetryOn500(t *testing.T) {
-	calls := 0
-	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
-		calls++
-		if calls < 3 {
-			return &http.Response{StatusCode: 500, Body: io.NopCloser(strings.NewReader("error"))}, nil
-		}
-		return &http.Response{StatusCode: 200, Body: io.NopCloser(strings.NewReader("ok"))}, nil
-	})
-	rt := &RetryTransport{Base: base, MaxRetries: 3, Delay: 1 * time.Millisecond}
-	req, _ := http.NewRequest("GET", "http://example.com/test", nil)
-	resp, err := rt.RoundTrip(req)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if resp.StatusCode != 200 {
-		t.Errorf("expected 200 after retries, got %d", resp.StatusCode)
-	}
-	if calls != 3 {
-		t.Errorf("expected 3 calls, got %d", calls)
-	}
-}
-
-func TestRetryTransport_DefaultNoRetry(t *testing.T) {
-	calls := 0
-	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
-		calls++
-		return &http.Response{StatusCode: 500, Body: io.NopCloser(strings.NewReader("error"))}, nil
-	})
-	rt := &RetryTransport{Base: base} // default MaxRetries=0
-	req, _ := http.NewRequest("GET", "http://example.com/test", nil)
-	resp, err := rt.RoundTrip(req)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if resp.StatusCode != 500 {
-		t.Errorf("expected 500 with no retries, got %d", resp.StatusCode)
-	}
-	if calls != 1 {
-		t.Errorf("expected 1 call with default config, got %d", calls)
-	}
-}

internal/cmdutil/secheader.go

@@ -6,7 +6,14 @@ package cmdutil
 import (
 	"context"
 	"net/http"
+	"reflect"
+	"runtime/debug"
+	"strings"
+	"sync"
 
+	"github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/extension/fileio"
+	exttransport "github.com/larksuite/cli/extension/transport"
 	"github.com/larksuite/cli/internal/build"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
@@ -14,12 +21,21 @@ import (
 const (
 	HeaderSource      = "X-Cli-Source"
 	HeaderVersion     = "X-Cli-Version"
+	HeaderBuild       = "X-Cli-Build"
 	HeaderShortcut    = "X-Cli-Shortcut"
 	HeaderExecutionId = "X-Cli-Execution-Id"
 
 	SourceValue = "lark-cli"
 
 	HeaderUserAgent = "User-Agent"
+
+	// BuildKindOfficial / BuildKindExtended / BuildKindUnknown are the values
+	// reported in the X-Cli-Build header; see DetectBuildKind for semantics.
+	BuildKindOfficial = "official"
+	BuildKindExtended = "extended"
+	BuildKindUnknown  = "unknown"
+
+	officialModulePath = "github.com/larksuite/cli"
 )
 
 // UserAgentValue returns the User-Agent value: "lark-cli/{version}".
@@ -32,10 +48,108 @@ func BaseSecurityHeaders() http.Header {
 	h := make(http.Header)
 	h.Set(HeaderSource, SourceValue)
 	h.Set(HeaderVersion, build.Version)
+	h.Set(HeaderBuild, DetectBuildKind())
 	h.Set(HeaderUserAgent, UserAgentValue())
 	return h
 }
 
+var (
+	buildKindOnce sync.Once
+	buildKindVal  string
+)
+
+// DetectBuildKind reports whether this binary is the official CLI, an
+// extended/repackaged build, or unknown. The result is cached via sync.Once
+// so it is computed only on the first call.
+//
+// IMPORTANT: must NOT be called from any package init(). Go's init ordering
+// follows the import graph; ISV providers registered via blank import may not
+// have run yet, which would misclassify an extended build as official. Call
+// only when handling an actual request (e.g. from BaseSecurityHeaders).
+func DetectBuildKind() string {
+	buildKindOnce.Do(func() {
+		buildKindVal = computeBuildKind()
+	})
+	return buildKindVal
+}
+
+// computeBuildKind performs the actual detection without any caching.
+// Exposed for tests. Gathers runtime/global inputs and delegates the pure
+// branching logic to classifyBuild so that logic can be unit-tested without
+// mutating process-wide provider registries.
+func computeBuildKind() string {
+	info, ok := debug.ReadBuildInfo()
+	mainPath := ""
+	if ok {
+		mainPath = info.Main.Path
+	}
+
+	credProviders := credential.Providers()
+	creds := make([]any, len(credProviders))
+	for i, p := range credProviders {
+		creds[i] = p
+	}
+
+	var tp any
+	if p := exttransport.GetProvider(); p != nil {
+		tp = p
+	}
+	var fp any
+	if p := fileio.GetProvider(); p != nil {
+		fp = p
+	}
+	return classifyBuild(mainPath, ok, creds, tp, fp)
+}
+
+// classifyBuild is the pure classification logic used by computeBuildKind.
+// Callers supply concrete values so every branch is reachable from tests
+// without touching debug.ReadBuildInfo or the extension registries.
+//
+// Priority order mirrors the design doc:
+//  1. no build info → unknown
+//  2. main module path not the official one → extended (ISV wrapper)
+//  3. any non-builtin provider (credential / transport / fileio) → extended
+//  4. otherwise → official
+func classifyBuild(mainPath string, haveBuildInfo bool, credProviders []any, transportProvider, fileioProvider any) string {
+	if !haveBuildInfo {
+		return BuildKindUnknown
+	}
+	if mainPath != "" && mainPath != officialModulePath {
+		return BuildKindExtended
+	}
+	for _, p := range credProviders {
+		if !isBuiltinProvider(p) {
+			return BuildKindExtended
+		}
+	}
+	if transportProvider != nil && !isBuiltinProvider(transportProvider) {
+		return BuildKindExtended
+	}
+	if fileioProvider != nil && !isBuiltinProvider(fileioProvider) {
+		return BuildKindExtended
+	}
+	return BuildKindOfficial
+}
+
+// isBuiltinProvider reports whether p is declared under the official module
+// path. Third-party providers live under their own module and fail this check.
+// Using reflect.PkgPath makes this robust against Name() spoofing since
+// package paths are fixed at compile time.
+func isBuiltinProvider(p any) bool {
+	if p == nil {
+		return false
+	}
+	t := reflect.TypeOf(p)
+	if t == nil {
+		return false
+	}
+	if t.Kind() == reflect.Ptr {
+		t = t.Elem()
+	}
+	pkg := t.PkgPath()
+	return pkg == officialModulePath || strings.HasPrefix(pkg, officialModulePath+"/")
+}
+
 // ── Context utilities ──
 
 type ctxKey string

internal/cmdutil/secheader_sidecar_test.go

@@ -0,0 +1,34 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar
+
+package cmdutil
+
+import (
+	"testing"
+
+	sidecarcred "github.com/larksuite/cli/extension/credential/sidecar"
+	sidecartrans "github.com/larksuite/cli/extension/transport/sidecar"
+)
+
+// TestIsBuiltinProvider_SidecarProviders locks the classification for the
+// sidecar-mode providers enumerated in design doc §3.3.2 as "官方自带". These
+// types only compile when the `authsidecar` build tag is active, so the test
+// is guarded by the same tag.
+func TestIsBuiltinProvider_SidecarProviders(t *testing.T) {
+	cases := []struct {
+		name     string
+		provider any
+	}{
+		{"sidecar credential provider", &sidecarcred.Provider{}},
+		{"sidecar transport provider", &sidecartrans.Provider{}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if !isBuiltinProvider(tc.provider) {
+				t.Fatalf("%T must be classified as builtin (PkgPath under %s)", tc.provider, officialModulePath)
+			}
+		})
+	}
+}

internal/cmdutil/secheader_test.go

@@ -0,0 +1,262 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"context"
+	"net/http"
+	"testing"
+
+	"github.com/larksuite/cli/extension/credential"
+	envcred "github.com/larksuite/cli/extension/credential/env"
+	"github.com/larksuite/cli/internal/vfs/localfileio"
+)
+
+// ---------------------------------------------------------------------------
+// isBuiltinProvider
+// ---------------------------------------------------------------------------
+
+// cmdutilLocalProvider has PkgPath under the official module
+// ("github.com/larksuite/cli/internal/cmdutil") and should be classified
+// as builtin.
+type cmdutilLocalProvider struct{}
+
+// Name intentionally returns a value that mimics an external provider; the
+// PkgPath-based classifier must ignore it. See TestIsBuiltinProvider_PkgPathNotSpoofableByName.
+func (cmdutilLocalProvider) Name() string { return "external-spoofed-provider" }
+func (cmdutilLocalProvider) ResolveAccount(context.Context) (*credential.Account, error) {
+	return nil, nil
+}
+func (cmdutilLocalProvider) ResolveToken(context.Context, credential.TokenSpec) (*credential.Token, error) {
+	return nil, nil
+}
+
+func TestIsBuiltinProvider_Nil(t *testing.T) {
+	if isBuiltinProvider(nil) {
+		t.Fatal("isBuiltinProvider(nil) = true, want false")
+	}
+}
+
+func TestIsBuiltinProvider_TypeUnderOfficialModule(t *testing.T) {
+	if !isBuiltinProvider(&cmdutilLocalProvider{}) {
+		t.Fatal("type under github.com/larksuite/cli/... should be builtin")
+	}
+}
+
+func TestIsBuiltinProvider_StdlibTypeIsNotBuiltin(t *testing.T) {
+	// A standard library type has PkgPath "net/http" — outside official module.
+	// This covers the non-builtin branch, which we cannot trigger from inside
+	// this test file using a locally-defined type.
+	if isBuiltinProvider(&http.Server{}) {
+		t.Fatal("stdlib type classified as builtin, PkgPath check is broken")
+	}
+}
+
+func TestIsBuiltinProvider_PkgPathNotSpoofableByName(t *testing.T) {
+	// Name() returns a string, but classification uses reflect.Type.PkgPath
+	// which is compile-time fixed. The local type returns a name that looks
+	// like an ISV provider; it must still classify as builtin.
+	p := &cmdutilLocalProvider{}
+	if p.Name() != "external-spoofed-provider" {
+		t.Fatalf("sanity check: Name() = %q, spoof value lost", p.Name())
+	}
+	if !isBuiltinProvider(p) {
+		t.Fatal("isBuiltinProvider should decide by PkgPath, not Name()")
+	}
+}
+
+// TestIsBuiltinProvider_NonPointerValues covers the non-pointer reflect branch.
+// The existing tests only exercise pointer receivers (&T{}); when a provider
+// is passed by value the reflect.Kind is not Ptr and t.Elem() is skipped.
+func TestIsBuiltinProvider_NonPointerValues(t *testing.T) {
+	if !isBuiltinProvider(cmdutilLocalProvider{}) {
+		t.Fatal("non-pointer local type should be builtin (PkgPath still under official module)")
+	}
+	// http.Server as a non-pointer — PkgPath "net/http", not under official.
+	if isBuiltinProvider(http.Server{}) {
+		t.Fatal("non-pointer stdlib type should not be builtin")
+	}
+}
+
+// TestIsBuiltinProvider_RealBuiltinProviders locks down the classification
+// for the concrete providers enumerated in design doc §3.3.2 as "官方自带":
+// env credential provider and local fileio provider. If any of these is
+// moved out of the official module tree in the future, this test must flip
+// red so the new package path is explicitly considered.
+//
+// The sidecar providers (extension/credential/sidecar and
+// extension/transport/sidecar) are guarded by the `authsidecar` build tag
+// and covered in secheader_sidecar_test.go under that tag.
+func TestIsBuiltinProvider_RealBuiltinProviders(t *testing.T) {
+	cases := []struct {
+		name     string
+		provider any
+	}{
+		{"env credential provider", &envcred.Provider{}},
+		{"local fileio provider", &localfileio.Provider{}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if !isBuiltinProvider(tc.provider) {
+				t.Fatalf("%T must be classified as builtin (PkgPath under %s)", tc.provider, officialModulePath)
+			}
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// computeBuildKind
+// ---------------------------------------------------------------------------
+
+func TestComputeBuildKind_ReturnsKnownValue(t *testing.T) {
+	// Under `go test`, Main.Path is typically the module being tested
+	// ("github.com/larksuite/cli"); the concrete return may still be
+	// official, extended, or unknown depending on Main.Path and the
+	// registered providers. Just assert it's one of the defined values.
+	got := computeBuildKind()
+	switch got {
+	case BuildKindOfficial, BuildKindExtended, BuildKindUnknown:
+	default:
+		t.Fatalf("computeBuildKind() = %q, want one of official/extended/unknown", got)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// classifyBuild — pure branching logic
+// ---------------------------------------------------------------------------
+//
+// These tests cover every branch of classifyBuild with explicit inputs,
+// which is impossible from computeBuildKind alone because debug.ReadBuildInfo
+// and the process-wide provider registries can't be reshaped in a test.
+
+func TestClassifyBuild_NoBuildInfo_ReturnsUnknown(t *testing.T) {
+	if got := classifyBuild("", false, nil, nil, nil); got != BuildKindUnknown {
+		t.Fatalf("classifyBuild(haveBuildInfo=false) = %q, want %q", got, BuildKindUnknown)
+	}
+}
+
+func TestClassifyBuild_ExtendedMainPath_ReturnsExtended(t *testing.T) {
+	cases := []string{
+		"github.com/acme/lark-cli-wrapper",
+		"example.com/isv/lark",
+		"gitlab.mycorp.internal/tools/lark-cli-fork",
+	}
+	for _, mp := range cases {
+		t.Run(mp, func(t *testing.T) {
+			if got := classifyBuild(mp, true, nil, nil, nil); got != BuildKindExtended {
+				t.Fatalf("mainPath=%q classifyBuild = %q, want %q", mp, got, BuildKindExtended)
+			}
+		})
+	}
+}
+
+func TestClassifyBuild_OfficialMainPath_NoProviders_ReturnsOfficial(t *testing.T) {
+	if got := classifyBuild(officialModulePath, true, nil, nil, nil); got != BuildKindOfficial {
+		t.Fatalf("classifyBuild(official, no providers) = %q, want %q", got, BuildKindOfficial)
+	}
+}
+
+func TestClassifyBuild_EmptyMainPath_DoesNotTriggerExtended(t *testing.T) {
+	// An empty Main.Path (rare, e.g. `go run` pre-1.18) must not be treated
+	// as extended by itself — the classifier falls through to provider checks.
+	if got := classifyBuild("", true, nil, nil, nil); got != BuildKindOfficial {
+		t.Fatalf("classifyBuild(empty mainPath, no providers) = %q, want %q", got, BuildKindOfficial)
+	}
+}
+
+func TestClassifyBuild_NonBuiltinCredentialProvider_ReturnsExtended(t *testing.T) {
+	// Any non-builtin credential provider flips the verdict to extended.
+	got := classifyBuild(officialModulePath, true, []any{&http.Server{}}, nil, nil)
+	if got != BuildKindExtended {
+		t.Fatalf("classifyBuild with external credential = %q, want %q", got, BuildKindExtended)
+	}
+}
+
+func TestClassifyBuild_MixedCredentialProviders_ExtendedWins(t *testing.T) {
+	// Even if most providers are builtin, a single external one decides.
+	providers := []any{&cmdutilLocalProvider{}, &http.Server{}}
+	if got := classifyBuild(officialModulePath, true, providers, nil, nil); got != BuildKindExtended {
+		t.Fatalf("classifyBuild mixed providers = %q, want %q", got, BuildKindExtended)
+	}
+}
+
+func TestClassifyBuild_NonBuiltinTransportProvider_ReturnsExtended(t *testing.T) {
+	got := classifyBuild(officialModulePath, true, nil, &http.Server{}, nil)
+	if got != BuildKindExtended {
+		t.Fatalf("classifyBuild with external transport = %q, want %q", got, BuildKindExtended)
+	}
+}
+
+func TestClassifyBuild_NonBuiltinFileioProvider_ReturnsExtended(t *testing.T) {
+	got := classifyBuild(officialModulePath, true, nil, nil, &http.Server{})
+	if got != BuildKindExtended {
+		t.Fatalf("classifyBuild with external fileio = %q, want %q", got, BuildKindExtended)
+	}
+}
+
+func TestClassifyBuild_AllBuiltinProviders_ReturnsOfficial(t *testing.T) {
+	// All three slots filled with builtin providers must still classify as official.
+	got := classifyBuild(
+		officialModulePath, true,
+		[]any{&cmdutilLocalProvider{}},
+		&cmdutilLocalProvider{},
+		&cmdutilLocalProvider{},
+	)
+	if got != BuildKindOfficial {
+		t.Fatalf("classifyBuild all-builtin = %q, want %q", got, BuildKindOfficial)
+	}
+}
+
+// TestClassifyBuild_MainPathPriorityOverProviders documents that the main
+// module path takes precedence: even with only builtin providers, a non-
+// official main path still yields extended.
+func TestClassifyBuild_MainPathPriorityOverProviders(t *testing.T) {
+	got := classifyBuild(
+		"github.com/acme/lark-wrapper", true,
+		[]any{&cmdutilLocalProvider{}},
+		&cmdutilLocalProvider{},
+		&cmdutilLocalProvider{},
+	)
+	if got != BuildKindExtended {
+		t.Fatalf("main-path override failed: got %q, want %q", got, BuildKindExtended)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// DetectBuildKind — sync.Once caching
+// ---------------------------------------------------------------------------
+
+func TestDetectBuildKind_StableAcrossCalls(t *testing.T) {
+	a := DetectBuildKind()
+	b := DetectBuildKind()
+	if a != b {
+		t.Fatalf("DetectBuildKind() returned different values on repeat: %q vs %q", a, b)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// BaseSecurityHeaders
+// ---------------------------------------------------------------------------
+
+func TestBaseSecurityHeaders_IncludesBuildHeader(t *testing.T) {
+	h := BaseSecurityHeaders()
+	v := h.Get(HeaderBuild)
+	if v == "" {
+		t.Fatal("BaseSecurityHeaders missing X-Cli-Build header")
+	}
+	switch v {
+	case BuildKindOfficial, BuildKindExtended, BuildKindUnknown:
+	default:
+		t.Fatalf("X-Cli-Build = %q, want one of official/extended/unknown", v)
+	}
+}
+
+func TestBaseSecurityHeaders_AllRequiredHeaders(t *testing.T) {
+	h := BaseSecurityHeaders()
+	for _, key := range []string{HeaderSource, HeaderVersion, HeaderBuild, HeaderUserAgent} {
+		if h.Get(key) == "" {
+			t.Errorf("BaseSecurityHeaders missing %s", key)
+		}
+	}
+}

internal/cmdutil/transport.go

@@ -72,6 +72,24 @@ func (t *UserAgentTransport) RoundTrip(req *http.Request) (*http.Response, error
 	return util.FallbackTransport().RoundTrip(req)
 }
 
+// BuildHeaderTransport is an http.RoundTripper that force-writes the
+// X-Cli-Build header before every request. Used in the SDK transport chain,
+// where SecurityHeaderTransport is not installed, to prevent extensions from
+// tampering with the build classification. The direct HTTP chain is already
+// covered by SecurityHeaderTransport iterating BaseSecurityHeaders.
+type BuildHeaderTransport struct {
+	Base http.RoundTripper
+}
+
+func (t *BuildHeaderTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	req = req.Clone(req.Context())
+	req.Header.Set(HeaderBuild, DetectBuildKind())
+	if t.Base != nil {
+		return t.Base.RoundTrip(req)
+	}
+	return util.FallbackTransport().RoundTrip(req)
+}
+
 // SecurityHeaderTransport is an http.RoundTripper that injects CLI security
 // headers into every request. Shortcut headers are read from the request context.
 type SecurityHeaderTransport struct {
@@ -104,20 +122,47 @@ func (t *SecurityHeaderTransport) RoundTrip(req *http.Request) (*http.Response,
 }
 
 // extensionMiddleware wraps the built-in transport chain with pre/post hooks.
-// The built-in chain always executes and cannot be skipped or overridden.
-// The original request context is restored after PreRoundTrip to prevent
+// The built-in chain always executes unless the extension is an
+// exttransport.AbortableInterceptor and its PreRoundTripE returns a non-nil
+// error; it cannot otherwise be skipped or overridden.
+//
+// The original request context is restored after the pre hook to prevent
 // extensions from tampering with cancellation, deadlines, or built-in values.
+// Cloning the request isolates header/URL/etc. mutations from the caller's
+// request object; req.Body is intentionally shared — extensions that consume
+// it are responsible for rewinding (see Interceptor doc).
 type extensionMiddleware struct {
-	Base http.RoundTripper
-	Ext  exttransport.Interceptor
+	Base    http.RoundTripper
+	Ext     exttransport.Interceptor
+	ExtName string // Provider.Name(), captured at wrap time for *AbortError.Extension
 }
 
-// RoundTrip calls PreRoundTrip, restores the original context, executes
-// the built-in chain, then calls the post hook if non-nil.
+// RoundTrip invokes the interceptor pre hook, restores the original context,
+// executes the built-in chain (unless aborted), then calls the post hook if
+// non-nil. When the extension implements AbortableInterceptor and returns a
+// non-nil error from PreRoundTripE, the built-in chain is skipped and an
+// *exttransport.AbortError is returned; the post hook is still invoked with
+// (nil, reason) so extensions can unwind resources.
 func (m *extensionMiddleware) RoundTrip(req *http.Request) (*http.Response, error) {
 	origCtx := req.Context()
-	req = req.Clone(origCtx) // isolate caller's request before extension mutations
-	post := m.Ext.PreRoundTrip(req)
+	req = req.Clone(origCtx)
+
+	var (
+		post    func(*http.Response, error)
+		abortEr error
+	)
+	if a, ok := m.Ext.(exttransport.AbortableInterceptor); ok {
+		post, abortEr = a.PreRoundTripE(req)
+	} else {
+		post = m.Ext.PreRoundTrip(req)
+	}
+	if abortEr != nil {
+		if post != nil {
+			post(nil, abortEr)
+		}
+		return nil, &exttransport.AbortError{Extension: m.ExtName, Reason: abortEr}
+	}
+
 	req = req.WithContext(origCtx) // restore original context
 	resp, err := m.Base.RoundTrip(req)
 	if post != nil {
@@ -137,5 +182,5 @@ func wrapWithExtension(transport http.RoundTripper) http.RoundTripper {
 	if tr == nil {
 		return transport
 	}
-	return &extensionMiddleware{Base: transport, Ext: tr}
+	return &extensionMiddleware{Base: transport, Ext: tr, ExtName: p.Name()}
 }

internal/cmdutil/transport_test.go

@@ -0,0 +1,531 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	exttransport "github.com/larksuite/cli/extension/transport"
+	internalauth "github.com/larksuite/cli/internal/auth"
+)
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
+
+// ---------------------------------------------------------------------------
+// RetryTransport
+// ---------------------------------------------------------------------------
+
+func TestRetryTransport_NoRetry(t *testing.T) {
+	calls := 0
+	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		calls++
+		return &http.Response{StatusCode: 200, Body: io.NopCloser(strings.NewReader("ok"))}, nil
+	})
+	rt := &RetryTransport{Base: base, MaxRetries: 0}
+	req, _ := http.NewRequest("GET", "http://example.com/test", nil)
+	resp, err := rt.RoundTrip(req)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if resp.StatusCode != 200 {
+		t.Errorf("expected 200, got %d", resp.StatusCode)
+	}
+	if calls != 1 {
+		t.Errorf("expected 1 call, got %d", calls)
+	}
+}
+
+func TestRetryTransport_RetryOn500(t *testing.T) {
+	calls := 0
+	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		calls++
+		if calls < 3 {
+			return &http.Response{StatusCode: 500, Body: io.NopCloser(strings.NewReader("error"))}, nil
+		}
+		return &http.Response{StatusCode: 200, Body: io.NopCloser(strings.NewReader("ok"))}, nil
+	})
+	rt := &RetryTransport{Base: base, MaxRetries: 3, Delay: 1 * time.Millisecond}
+	req, _ := http.NewRequest("GET", "http://example.com/test", nil)
+	resp, err := rt.RoundTrip(req)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if resp.StatusCode != 200 {
+		t.Errorf("expected 200 after retries, got %d", resp.StatusCode)
+	}
+	if calls != 3 {
+		t.Errorf("expected 3 calls, got %d", calls)
+	}
+}
+
+func TestRetryTransport_DefaultNoRetry(t *testing.T) {
+	calls := 0
+	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		calls++
+		return &http.Response{StatusCode: 500, Body: io.NopCloser(strings.NewReader("error"))}, nil
+	})
+	rt := &RetryTransport{Base: base} // default MaxRetries=0
+	req, _ := http.NewRequest("GET", "http://example.com/test", nil)
+	resp, err := rt.RoundTrip(req)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if resp.StatusCode != 500 {
+		t.Errorf("expected 500 with no retries, got %d", resp.StatusCode)
+	}
+	if calls != 1 {
+		t.Errorf("expected 1 call with default config, got %d", calls)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// buildSDKTransport chain composition
+// ---------------------------------------------------------------------------
+
+func TestBuildSDKTransport_IncludesRetryTransport(t *testing.T) {
+	transport := buildSDKTransport()
+
+	// Chain: SecurityPolicy → BuildHeader → UserAgent → Retry → Base
+	sec, ok := transport.(*internalauth.SecurityPolicyTransport)
+	if !ok {
+		t.Fatalf("outer transport type = %T, want *auth.SecurityPolicyTransport", transport)
+	}
+	bh, ok := sec.Base.(*BuildHeaderTransport)
+	if !ok {
+		t.Fatalf("layer after SecurityPolicy = %T, want *BuildHeaderTransport", sec.Base)
+	}
+	ua, ok := bh.Base.(*UserAgentTransport)
+	if !ok {
+		t.Fatalf("layer after BuildHeader = %T, want *UserAgentTransport", bh.Base)
+	}
+	if _, ok := ua.Base.(*RetryTransport); !ok {
+		t.Fatalf("inner transport type = %T, want *RetryTransport", ua.Base)
+	}
+}
+
+func TestBuildSDKTransport_WithExtension(t *testing.T) {
+	exttransport.Register(&stubTransportProvider{})
+	t.Cleanup(func() { exttransport.Register(nil) })
+
+	transport := buildSDKTransport()
+
+	// Chain: extensionMiddleware → SecurityPolicy → BuildHeader → UserAgent → Retry → Base
+	mid, ok := transport.(*extensionMiddleware)
+	if !ok {
+		t.Fatalf("outer transport type = %T, want *extensionMiddleware", transport)
+	}
+	sec, ok := mid.Base.(*internalauth.SecurityPolicyTransport)
+	if !ok {
+		t.Fatalf("transport type = %T, want *auth.SecurityPolicyTransport", mid.Base)
+	}
+	bh, ok := sec.Base.(*BuildHeaderTransport)
+	if !ok {
+		t.Fatalf("layer after SecurityPolicy = %T, want *BuildHeaderTransport", sec.Base)
+	}
+	ua, ok := bh.Base.(*UserAgentTransport)
+	if !ok {
+		t.Fatalf("layer after BuildHeader = %T, want *UserAgentTransport", bh.Base)
+	}
+	if _, ok := ua.Base.(*RetryTransport); !ok {
+		t.Fatalf("innermost transport type = %T, want *RetryTransport", ua.Base)
+	}
+}
+
+func TestBuildSDKTransport_WithoutExtension(t *testing.T) {
+	exttransport.Register(nil)
+
+	transport := buildSDKTransport()
+
+	// Chain: SecurityPolicy → BuildHeader → UserAgent → Retry → Base
+	sec, ok := transport.(*internalauth.SecurityPolicyTransport)
+	if !ok {
+		t.Fatalf("outer transport type = %T, want *auth.SecurityPolicyTransport", transport)
+	}
+	bh, ok := sec.Base.(*BuildHeaderTransport)
+	if !ok {
+		t.Fatalf("layer after SecurityPolicy = %T, want *BuildHeaderTransport", sec.Base)
+	}
+	ua, ok := bh.Base.(*UserAgentTransport)
+	if !ok {
+		t.Fatalf("layer after BuildHeader = %T, want *UserAgentTransport", bh.Base)
+	}
+	if _, ok := ua.Base.(*RetryTransport); !ok {
+		t.Fatalf("inner transport type = %T, want *RetryTransport", ua.Base)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// extensionMiddleware — legacy Interceptor path
+// ---------------------------------------------------------------------------
+
+type stubTransportProvider struct {
+	interceptor exttransport.Interceptor
+}
+
+func (s *stubTransportProvider) Name() string { return "stub" }
+func (s *stubTransportProvider) ResolveInterceptor(context.Context) exttransport.Interceptor {
+	if s.interceptor != nil {
+		return s.interceptor
+	}
+	return &stubTransportImpl{}
+}
+
+type stubTransportImpl struct{}
+
+func (s *stubTransportImpl) PreRoundTrip(req *http.Request) func(*http.Response, error) {
+	return nil
+}
+
+// headerCapturingInterceptor sets custom headers in PreRoundTrip and records
+// whether PostRoundTrip was called, to verify execution order.
+type headerCapturingInterceptor struct {
+	preCalled  bool
+	postCalled bool
+}
+
+func (h *headerCapturingInterceptor) PreRoundTrip(req *http.Request) func(*http.Response, error) {
+	h.preCalled = true
+	// Set a custom header that should survive (no built-in override)
+	req.Header.Set("X-Custom-Trace", "ext-trace-123")
+	// Try to override a security header — should be overwritten by SecurityHeaderTransport
+	req.Header.Set(HeaderSource, "ext-tampered")
+	return func(resp *http.Response, err error) {
+		h.postCalled = true
+	}
+}
+
+func TestExtensionInterceptor_ExecutionOrder(t *testing.T) {
+	var receivedHeaders http.Header
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		receivedHeaders = r.Header.Clone()
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	ic := &headerCapturingInterceptor{}
+	exttransport.Register(&stubTransportProvider{interceptor: ic})
+	t.Cleanup(func() { exttransport.Register(nil) })
+
+	// Use HTTP transport chain (has SecurityHeaderTransport)
+	var base http.RoundTripper = http.DefaultTransport
+	base = &RetryTransport{Base: base}
+	base = &SecurityHeaderTransport{Base: base}
+	transport := wrapWithExtension(base)
+	client := &http.Client{Transport: transport}
+
+	req, _ := http.NewRequest("GET", srv.URL, nil)
+	resp, err := client.Do(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	resp.Body.Close()
+
+	// PreRoundTrip was called
+	if !ic.preCalled {
+		t.Fatal("PreRoundTrip was not called")
+	}
+	// PostRoundTrip (closure) was called
+	if !ic.postCalled {
+		t.Fatal("PostRoundTrip closure was not called")
+	}
+	// Custom header set by extension survives (no built-in override)
+	if got := receivedHeaders.Get("X-Custom-Trace"); got != "ext-trace-123" {
+		t.Fatalf("X-Custom-Trace = %q, want %q", got, "ext-trace-123")
+	}
+	// Security header overridden by extension is restored by SecurityHeaderTransport
+	if got := receivedHeaders.Get(HeaderSource); got != SourceValue {
+		t.Fatalf("%s = %q, want %q (built-in should override extension)", HeaderSource, got, SourceValue)
+	}
+}
+
+// buildTamperingInterceptor tries to delete and spoof X-Cli-Build via
+// PreRoundTrip. The SDK chain's BuildHeaderTransport must restore the real
+// value before the request leaves the process.
+type buildTamperingInterceptor struct{}
+
+func (buildTamperingInterceptor) PreRoundTrip(req *http.Request) func(*http.Response, error) {
+	req.Header.Del(HeaderBuild)
+	req.Header.Set(HeaderBuild, "ext-tampered-build")
+	return nil
+}
+
+// TestBuildHeaderTransport_SDKChain_OverridesTamperedHeader verifies that the
+// X-Cli-Build header is force-written by BuildHeaderTransport in the SDK
+// transport chain, even when an extension tries to delete or spoof it. This
+// closes the gap where the SDK chain had no equivalent of
+// SecurityHeaderTransport (see design doc §3.3.3).
+func TestBuildHeaderTransport_SDKChain_OverridesTamperedHeader(t *testing.T) {
+	var receivedBuild string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		receivedBuild = r.Header.Get(HeaderBuild)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	exttransport.Register(&stubTransportProvider{interceptor: buildTamperingInterceptor{}})
+	t.Cleanup(func() { exttransport.Register(nil) })
+
+	// Replicate the SDK chain layering used by buildSDKTransport.
+	var base http.RoundTripper = http.DefaultTransport
+	base = &RetryTransport{Base: base}
+	base = &UserAgentTransport{Base: base}
+	base = &BuildHeaderTransport{Base: base}
+	transport := wrapWithExtension(base)
+	client := &http.Client{Transport: transport}
+
+	req, _ := http.NewRequest("GET", srv.URL, nil)
+	resp, err := client.Do(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	resp.Body.Close()
+
+	if receivedBuild == "ext-tampered-build" {
+		t.Fatalf("%s = %q, extension tampering leaked to network", HeaderBuild, receivedBuild)
+	}
+	want := DetectBuildKind()
+	if receivedBuild != want {
+		t.Fatalf("%s = %q, want %q", HeaderBuild, receivedBuild, want)
+	}
+}
+
+// TestBuildHeaderTransport_OverridesEvenWithoutTamper verifies that even if
+// no extension is registered, BuildHeaderTransport writes X-Cli-Build.
+func TestBuildHeaderTransport_OverridesEvenWithoutTamper(t *testing.T) {
+	var receivedBuild string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		receivedBuild = r.Header.Get(HeaderBuild)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	transport := &BuildHeaderTransport{Base: http.DefaultTransport}
+	client := &http.Client{Transport: transport}
+
+	req, _ := http.NewRequest("GET", srv.URL, nil)
+	resp, err := client.Do(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	resp.Body.Close()
+
+	if receivedBuild == "" {
+		t.Fatalf("%s header missing, BuildHeaderTransport did not inject", HeaderBuild)
+	}
+	want := DetectBuildKind()
+	if receivedBuild != want {
+		t.Fatalf("%s = %q, want %q", HeaderBuild, receivedBuild, want)
+	}
+}
+
+// TestBuildHeaderTransport_NilBase_UsesFallback verifies that when Base is nil,
+// the transport still sets X-Cli-Build and routes the request through
+// util.FallbackTransport rather than panicking. This covers the fallback
+// branch in RoundTrip that is otherwise unreachable with a non-nil Base.
+func TestBuildHeaderTransport_NilBase_UsesFallback(t *testing.T) {
+	var receivedBuild string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		receivedBuild = r.Header.Get(HeaderBuild)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	transport := &BuildHeaderTransport{Base: nil}
+	client := &http.Client{Transport: transport}
+
+	req, _ := http.NewRequest("GET", srv.URL, nil)
+	resp, err := client.Do(req)
+	if err != nil {
+		t.Fatalf("request via nil-Base transport failed: %v", err)
+	}
+	resp.Body.Close()
+
+	want := DetectBuildKind()
+	if receivedBuild != want {
+		t.Fatalf("%s = %q, want %q (header must be set even on nil-Base path)",
+			HeaderBuild, receivedBuild, want)
+	}
+}
+
+// interceptorFunc adapts a function to exttransport.Interceptor.
+type interceptorFunc func(*http.Request) func(*http.Response, error)
+
+func (f interceptorFunc) PreRoundTrip(req *http.Request) func(*http.Response, error) { return f(req) }
+
+func TestExtensionInterceptor_ContextTamperPrevented(t *testing.T) {
+	type ctxKeyType string
+	const testKey ctxKeyType = "original"
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	var ctxValue any
+
+	// Use a custom transport that captures the context value seen by the built-in chain
+	capturer := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		ctxValue = req.Context().Value(testKey)
+		return http.DefaultTransport.RoundTrip(req)
+	})
+
+	// Interceptor that tries to tamper with context
+	tamperIC := interceptorFunc(func(req *http.Request) func(*http.Response, error) {
+		// Try to replace context with a new one
+		*req = *req.WithContext(context.WithValue(req.Context(), testKey, "tampered"))
+		return nil
+	})
+
+	mid := &extensionMiddleware{Base: capturer, Ext: tamperIC}
+
+	origCtx := context.WithValue(context.Background(), testKey, "original")
+	req, _ := http.NewRequestWithContext(origCtx, "GET", srv.URL, nil)
+	resp, err := mid.RoundTrip(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	resp.Body.Close()
+
+	// Built-in chain should see original context, not tampered
+	if ctxValue != "original" {
+		t.Fatalf("built-in chain saw context value %q, want %q", ctxValue, "original")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// extensionMiddleware — PreRoundTripE abort path
+// ---------------------------------------------------------------------------
+
+// abortingInterceptor implements exttransport.AbortableInterceptor and
+// records invocation of the pre and post hooks. These middleware tests only
+// assert middleware-level integration; pure *AbortError behavior
+// (Error/Unwrap/Is/As) is covered in extension/transport/errors_test.go.
+type abortingInterceptor struct {
+	reason     error // if non-nil, PreRoundTripE returns this to abort
+	nilPost    bool  // if true, PreRoundTripE returns a nil post func
+	preECalled bool
+	postCalled bool
+	postResp   *http.Response
+	postErr    error
+}
+
+// PreRoundTrip is a no-op that satisfies the legacy Interceptor method; the
+// middleware never calls it when PreRoundTripE is present.
+func (*abortingInterceptor) PreRoundTrip(*http.Request) func(*http.Response, error) {
+	return nil
+}
+
+func (a *abortingInterceptor) PreRoundTripE(req *http.Request) (func(*http.Response, error), error) {
+	a.preECalled = true
+	if a.nilPost {
+		return nil, a.reason
+	}
+	return func(resp *http.Response, err error) {
+		a.postCalled = true
+		a.postResp = resp
+		a.postErr = err
+	}, a.reason
+}
+
+func TestExtensionMiddleware_PreRoundTripEAbort(t *testing.T) {
+	innerErr := errors.New("denied by policy")
+
+	t.Run("skips base and wires AbortError fields", func(t *testing.T) {
+		ic := &abortingInterceptor{reason: innerErr}
+		baseCalls := 0
+		base := roundTripFunc(func(*http.Request) (*http.Response, error) {
+			baseCalls++
+			return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+		})
+
+		mid := &extensionMiddleware{Base: base, Ext: ic, ExtName: "stub"}
+		req, _ := http.NewRequest("GET", "http://example.invalid/", nil)
+		resp, err := mid.RoundTrip(req)
+
+		if resp != nil {
+			t.Fatalf("resp = %v, want nil on abort", resp)
+		}
+		if baseCalls != 0 {
+			t.Fatalf("base RoundTrip called %d times on abort, want 0", baseCalls)
+		}
+		if !ic.preECalled {
+			t.Fatal("PreRoundTripE was not called")
+		}
+
+		var aErr *exttransport.AbortError
+		if !errors.As(err, &aErr) {
+			t.Fatalf("errors.As(*AbortError) = false, err = %v (%T)", err, err)
+		}
+		if aErr.Extension != "stub" || aErr.Reason != innerErr {
+			t.Fatalf("AbortError = %+v, want {Extension:stub Reason:%v}", aErr, innerErr)
+		}
+
+		// Post must see the original inner err, not the *AbortError wrapper.
+		if !ic.postCalled {
+			t.Fatal("post hook was not called on abort")
+		}
+		if ic.postResp != nil {
+			t.Fatalf("post resp = %v, want nil", ic.postResp)
+		}
+		if ic.postErr != innerErr {
+			t.Fatalf("post err = %v, want original inner err %v", ic.postErr, innerErr)
+		}
+	})
+
+	t.Run("nil post still returns AbortError", func(t *testing.T) {
+		ic := &abortingInterceptor{reason: innerErr, nilPost: true}
+		base := roundTripFunc(func(*http.Request) (*http.Response, error) {
+			t.Fatal("base must not be called on abort")
+			return nil, nil
+		})
+
+		mid := &extensionMiddleware{Base: base, Ext: ic, ExtName: "stub"}
+		req, _ := http.NewRequest("GET", "http://example.invalid/", nil)
+		_, err := mid.RoundTrip(req)
+
+		var aErr *exttransport.AbortError
+		if !errors.As(err, &aErr) {
+			t.Fatalf("errors.As(*AbortError) = false, err = %v", err)
+		}
+	})
+}
+
+func TestExtensionMiddleware_PreRoundTripEHappyPath(t *testing.T) {
+	ic := &abortingInterceptor{} // reason == nil → no abort
+	baseCalls := 0
+	base := roundTripFunc(func(*http.Request) (*http.Response, error) {
+		baseCalls++
+		return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+	})
+
+	mid := &extensionMiddleware{Base: base, Ext: ic, ExtName: "stub"}
+	req, _ := http.NewRequest("GET", "http://example.invalid/", nil)
+	resp, err := mid.RoundTrip(req)
+	if err != nil {
+		t.Fatalf("happy path returned err: %v", err)
+	}
+	if resp == nil || resp.StatusCode != http.StatusOK {
+		t.Fatalf("resp = %v, want 200", resp)
+	}
+	if baseCalls != 1 {
+		t.Fatalf("base RoundTrip called %d times, want 1", baseCalls)
+	}
+	if !ic.preECalled {
+		t.Fatal("PreRoundTripE was not called")
+	}
+	if !ic.postCalled || ic.postErr != nil {
+		t.Fatalf("post hook not called or err != nil: called=%v err=%v", ic.postCalled, ic.postErr)
+	}
+}

internal/core/config.go

@@ -7,7 +7,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"os"
 	"path/filepath"
 	"strings"
 	"unicode/utf8"
@@ -173,21 +172,15 @@ func (c *CliConfig) CanBot() bool {
 	return c.SupportedIdentities == 0 || c.SupportedIdentities&identityBotBit != 0
 }
 
-// GetConfigDir returns the config directory path.
-// If the home directory cannot be determined, it falls back to a relative path
-// and prints a warning to stderr.
+// GetConfigDir returns the config directory path for the current workspace.
+// When workspace is local (default), this returns the same path as before
+// (LARKSUITE_CLI_CONFIG_DIR or ~/.lark-cli) — fully backward-compatible.
+// When workspace is openclaw/hermes, returns base/openclaw or base/hermes.
 func GetConfigDir() string {
-	if dir := os.Getenv("LARKSUITE_CLI_CONFIG_DIR"); dir != "" {
-		return dir
-	}
-	home, err := vfs.UserHomeDir()
-	if err != nil || home == "" {
-		fmt.Fprintf(os.Stderr, "warning: unable to determine home directory: %v\n", err)
-	}
-	return filepath.Join(home, ".lark-cli")
+	return GetRuntimeDir()
 }
 
-// GetConfigPath returns the config file path.
+// GetConfigPath returns the config file path for the current workspace.
 func GetConfigPath() string {
 	return filepath.Join(GetConfigDir(), "config.json")
 }

internal/core/workspace.go

@@ -0,0 +1,149 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package core
+
+import (
+	"os"
+	"path/filepath"
+	"sync/atomic"
+
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// Workspace identifies a config isolation context.
+// Each non-local workspace maps to a subdirectory under the base config dir.
+type Workspace string
+
+const (
+	// WorkspaceLocal is the default workspace. GetConfigDir returns the base
+	// config dir without any subdirectory — identical to pre-workspace behavior.
+	WorkspaceLocal Workspace = ""
+
+	// WorkspaceOpenClaw activates when any OpenClaw-specific env signal is
+	// present (see DetectWorkspaceFromEnv for the full list).
+	WorkspaceOpenClaw Workspace = "openclaw"
+
+	// WorkspaceHermes activates when any Hermes-specific env signal is
+	// present (see DetectWorkspaceFromEnv for the full list).
+	WorkspaceHermes Workspace = "hermes"
+)
+
+// currentWorkspace holds the workspace for the current process invocation.
+// Set once during Factory initialization; config bind's RunE may re-set it
+// to the workspace being bound. Uses atomic.Value for goroutine safety
+// (background registry refresh reads GetRuntimeDir concurrently with the
+// Factory init that writes workspace).
+var currentWorkspace atomic.Value // stores Workspace; zero value → Load returns nil → treated as Local
+
+// SetCurrentWorkspace sets the active workspace for this process.
+func SetCurrentWorkspace(ws Workspace) {
+	currentWorkspace.Store(ws)
+}
+
+// CurrentWorkspace returns the active workspace.
+// Returns WorkspaceLocal if not yet set (safe default, backward-compatible).
+func CurrentWorkspace() Workspace {
+	v := currentWorkspace.Load()
+	if v == nil {
+		return WorkspaceLocal
+	}
+	return v.(Workspace)
+}
+
+// Display returns the user-visible workspace label.
+// Used in config show, doctor, and error messages.
+func (w Workspace) Display() string {
+	if w == WorkspaceLocal || w == "" {
+		return "local"
+	}
+	return string(w)
+}
+
+// IsLocal returns true if this is the default local workspace.
+func (w Workspace) IsLocal() bool {
+	return w == WorkspaceLocal || w == ""
+}
+
+// DetectWorkspaceFromEnv determines the workspace from process environment.
+//
+// Detection is signal-based, not credential-based: we look for environment
+// variables that the host Agent itself sets when launching a subprocess.
+// Generic FEISHU_APP_ID / FEISHU_APP_SECRET are intentionally NOT used —
+// any third-party Feishu script can set those, so they would cause
+// false-positive routing into a Hermes workspace.
+//
+// Priority:
+//  1. Any OpenClaw signal → WorkspaceOpenClaw
+//     - OPENCLAW_CLI == "1":  subprocess marker (added 2026-03-09 via
+//     OpenClaw PR #41411). Most precise, but absent on older builds.
+//     - OPENCLAW_HOME / OPENCLAW_STATE_DIR / OPENCLAW_CONFIG_PATH non-empty:
+//     user-facing paths introduced with the 2026-01-30 rename. Detected
+//     so that OpenClaw builds predating the subprocess marker — or
+//     invocation paths that do not propagate the marker — still route
+//     correctly.
+//  2. Any Hermes signal → WorkspaceHermes. All of the checked variables are
+//     set by Hermes itself (hermes_cli/main.py, gateway/run.py). No
+//     unrelated tool uses the HERMES_* namespace.
+//     - HERMES_HOME:          exported by the CLI at startup
+//     - HERMES_QUIET == "1":  exported by the gateway
+//     - HERMES_EXEC_ASK == "1": exported by the gateway (paired w/ QUIET)
+//     - HERMES_GATEWAY_TOKEN: injected into every gateway subprocess
+//     - HERMES_SESSION_KEY:   session identifier scoped to the current chat
+//  3. Otherwise → WorkspaceLocal
+func DetectWorkspaceFromEnv(getenv func(string) string) Workspace {
+	if getenv("OPENCLAW_CLI") == "1" ||
+		getenv("OPENCLAW_HOME") != "" ||
+		getenv("OPENCLAW_STATE_DIR") != "" ||
+		getenv("OPENCLAW_CONFIG_PATH") != "" ||
+		getenv("OPENCLAW_SERVICE_MARKER") != "" ||
+		getenv("OPENCLAW_SERVICE_VERSION") != "" ||
+		getenv("OPENCLAW_GATEWAY_PORT") != "" ||
+		getenv("OPENCLAW_SHELL") != "" {
+		return WorkspaceOpenClaw
+	}
+	if getenv("HERMES_HOME") != "" ||
+		getenv("HERMES_QUIET") == "1" ||
+		getenv("HERMES_EXEC_ASK") == "1" ||
+		getenv("HERMES_GATEWAY_TOKEN") != "" ||
+		getenv("HERMES_SESSION_KEY") != "" {
+		return WorkspaceHermes
+	}
+	return WorkspaceLocal
+}
+
+// GetBaseConfigDir returns the root config directory, ignoring workspace.
+// Priority: LARKSUITE_CLI_CONFIG_DIR env → ~/.lark-cli.
+// If the home directory cannot be determined and no override is set, a
+// warning is written to stderr and the path falls back to a relative
+// ".lark-cli" — callers will then see an explicit I/O error at first use
+// instead of a silent misconfiguration.
+func GetBaseConfigDir() string {
+	if dir := os.Getenv("LARKSUITE_CLI_CONFIG_DIR"); dir != "" {
+		return dir
+	}
+	home, err := vfs.UserHomeDir()
+	if err != nil || home == "" {
+		// Fall back to a relative ".lark-cli" so the first I/O operation
+		// surfaces a clear "no such file or directory" error. We cannot
+		// emit a stderr warning here — this package has no IOStreams in
+		// scope, and direct writes to os.Stderr violate the IOStreams
+		// injection boundary (enforced by lint). Users who hit this path
+		// should set LARKSUITE_CLI_CONFIG_DIR explicitly.
+		home = ""
+	}
+	return filepath.Join(home, ".lark-cli")
+}
+
+// GetRuntimeDir returns the workspace-aware config directory.
+//   - WorkspaceLocal → GetBaseConfigDir() (unchanged, backward-compatible)
+//   - WorkspaceOpenClaw → GetBaseConfigDir()/openclaw
+//   - WorkspaceHermes → GetBaseConfigDir()/hermes
+func GetRuntimeDir() string {
+	base := GetBaseConfigDir()
+	ws := CurrentWorkspace()
+	if ws.IsLocal() {
+		return base
+	}
+	return filepath.Join(base, string(ws))
+}

internal/core/workspace_test.go

@@ -0,0 +1,228 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package core
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+func TestDetectWorkspaceFromEnv(t *testing.T) {
+	tests := []struct {
+		name   string
+		env    map[string]string
+		expect Workspace
+	}{
+		{
+			name:   "no agent env → local",
+			env:    map[string]string{},
+			expect: WorkspaceLocal,
+		},
+		{
+			name:   "OPENCLAW_CLI=1 → openclaw",
+			env:    map[string]string{"OPENCLAW_CLI": "1"},
+			expect: WorkspaceOpenClaw,
+		},
+		{
+			name:   "OPENCLAW_CLI=true → local (strict ==1 check)",
+			env:    map[string]string{"OPENCLAW_CLI": "true"},
+			expect: WorkspaceLocal,
+		},
+		{
+			name:   "OPENCLAW_CLI=yes → local",
+			env:    map[string]string{"OPENCLAW_CLI": "yes"},
+			expect: WorkspaceLocal,
+		},
+		{
+			name:   "OPENCLAW_CLI=0 → local",
+			env:    map[string]string{"OPENCLAW_CLI": "0"},
+			expect: WorkspaceLocal,
+		},
+		{
+			name:   "OPENCLAW_CLI empty → local",
+			env:    map[string]string{"OPENCLAW_CLI": ""},
+			expect: WorkspaceLocal,
+		},
+		{
+			name:   "OPENCLAW_CLI=1 with trailing space → local (strict)",
+			env:    map[string]string{"OPENCLAW_CLI": "1 "},
+			expect: WorkspaceLocal,
+		},
+		{
+			name:   "generic FEISHU_APP_ID + SECRET → local (not a Hermes signal)",
+			env:    map[string]string{"FEISHU_APP_ID": "cli_abc", "FEISHU_APP_SECRET": "xxx"},
+			expect: WorkspaceLocal,
+		},
+		{
+			name:   "HERMES_HOME set → hermes",
+			env:    map[string]string{"HERMES_HOME": "/Users/me/.hermes"},
+			expect: WorkspaceHermes,
+		},
+		{
+			name:   "HERMES_QUIET=1 → hermes (set by gateway)",
+			env:    map[string]string{"HERMES_QUIET": "1"},
+			expect: WorkspaceHermes,
+		},
+		{
+			name:   "HERMES_EXEC_ASK=1 → hermes",
+			env:    map[string]string{"HERMES_EXEC_ASK": "1"},
+			expect: WorkspaceHermes,
+		},
+		{
+			name:   "HERMES_GATEWAY_TOKEN set → hermes",
+			env:    map[string]string{"HERMES_GATEWAY_TOKEN": "69ce6b...6065"},
+			expect: WorkspaceHermes,
+		},
+		{
+			name:   "HERMES_SESSION_KEY set → hermes",
+			env:    map[string]string{"HERMES_SESSION_KEY": "agent:main:feishu:dm:oc_xxx"},
+			expect: WorkspaceHermes,
+		},
+		{
+			name:   "HERMES_QUIET=0 alone → local (strict ==1 check)",
+			env:    map[string]string{"HERMES_QUIET": "0"},
+			expect: WorkspaceLocal,
+		},
+		{
+			name:   "OPENCLAW_CLI=1 + HERMES_HOME both set → openclaw wins (priority)",
+			env:    map[string]string{"OPENCLAW_CLI": "1", "HERMES_HOME": "/Users/me/.hermes"},
+			expect: WorkspaceOpenClaw,
+		},
+		{
+			name:   "FEISHU_APP_ID + HERMES_HOME → hermes (HERMES_ signals suffice)",
+			env:    map[string]string{"FEISHU_APP_ID": "cli_abc", "FEISHU_APP_SECRET": "xxx", "HERMES_HOME": "/Users/me/.hermes"},
+			expect: WorkspaceHermes,
+		},
+		{
+			name:   "OPENCLAW_HOME set → openclaw (older OpenClaw builds without subprocess marker)",
+			env:    map[string]string{"OPENCLAW_HOME": "/Users/me/.openclaw"},
+			expect: WorkspaceOpenClaw,
+		},
+		{
+			name:   "OPENCLAW_STATE_DIR set → openclaw",
+			env:    map[string]string{"OPENCLAW_STATE_DIR": "/srv/openclaw/state"},
+			expect: WorkspaceOpenClaw,
+		},
+		{
+			name:   "OPENCLAW_CONFIG_PATH set → openclaw",
+			env:    map[string]string{"OPENCLAW_CONFIG_PATH": "/etc/openclaw/openclaw.json"},
+			expect: WorkspaceOpenClaw,
+		},
+		{
+			name:   "OPENCLAW_HOME + FEISHU both set → openclaw wins (priority)",
+			env:    map[string]string{"OPENCLAW_HOME": "/Users/me/.openclaw", "FEISHU_APP_ID": "cli_abc", "FEISHU_APP_SECRET": "xxx"},
+			expect: WorkspaceOpenClaw,
+		},
+		{
+			name:   "LARKSUITE_CLI_APP_ID does not affect workspace",
+			env:    map[string]string{"LARKSUITE_CLI_APP_ID": "cli_local", "LARKSUITE_CLI_APP_SECRET": "local_secret"},
+			expect: WorkspaceLocal,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			getenv := func(key string) string { return tt.env[key] }
+			got := DetectWorkspaceFromEnv(getenv)
+			if got != tt.expect {
+				t.Errorf("DetectWorkspaceFromEnv() = %q, want %q", got, tt.expect)
+			}
+		})
+	}
+}
+
+func TestWorkspaceDisplay(t *testing.T) {
+	tests := []struct {
+		ws     Workspace
+		expect string
+	}{
+		{WorkspaceLocal, "local"},
+		{Workspace(""), "local"},
+		{WorkspaceOpenClaw, "openclaw"},
+		{WorkspaceHermes, "hermes"},
+	}
+	for _, tt := range tests {
+		if got := tt.ws.Display(); got != tt.expect {
+			t.Errorf("Workspace(%q).Display() = %q, want %q", tt.ws, got, tt.expect)
+		}
+	}
+}
+
+func TestWorkspaceIsLocal(t *testing.T) {
+	if !WorkspaceLocal.IsLocal() {
+		t.Error("WorkspaceLocal.IsLocal() should be true")
+	}
+	if !Workspace("").IsLocal() {
+		t.Error(`Workspace("").IsLocal() should be true`)
+	}
+	if WorkspaceOpenClaw.IsLocal() {
+		t.Error("WorkspaceOpenClaw.IsLocal() should be false")
+	}
+}
+
+func TestSetCurrentWorkspace(t *testing.T) {
+	orig := CurrentWorkspace()
+	defer SetCurrentWorkspace(orig)
+
+	SetCurrentWorkspace(WorkspaceOpenClaw)
+	if got := CurrentWorkspace(); got != WorkspaceOpenClaw {
+		t.Errorf("CurrentWorkspace() = %q, want %q", got, WorkspaceOpenClaw)
+	}
+
+	SetCurrentWorkspace(WorkspaceLocal)
+	if got := CurrentWorkspace(); got != WorkspaceLocal {
+		t.Errorf("CurrentWorkspace() = %q, want %q", got, WorkspaceLocal)
+	}
+}
+
+func TestGetRuntimeDir(t *testing.T) {
+	tmp := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
+
+	orig := CurrentWorkspace()
+	defer SetCurrentWorkspace(orig)
+
+	// Local → base dir (same as pre-workspace behavior)
+	SetCurrentWorkspace(WorkspaceLocal)
+	if got := GetRuntimeDir(); got != tmp {
+		t.Errorf("local: GetRuntimeDir() = %q, want %q", got, tmp)
+	}
+	if got := GetConfigDir(); got != tmp {
+		t.Errorf("local: GetConfigDir() = %q, want %q", got, tmp)
+	}
+
+	// OpenClaw → base/openclaw
+	SetCurrentWorkspace(WorkspaceOpenClaw)
+	want := filepath.Join(tmp, "openclaw")
+	if got := GetRuntimeDir(); got != want {
+		t.Errorf("openclaw: GetRuntimeDir() = %q, want %q", got, want)
+	}
+
+	// Hermes → base/hermes
+	SetCurrentWorkspace(WorkspaceHermes)
+	want = filepath.Join(tmp, "hermes")
+	if got := GetRuntimeDir(); got != want {
+		t.Errorf("hermes: GetRuntimeDir() = %q, want %q", got, want)
+	}
+}
+
+func TestGetConfigPath(t *testing.T) {
+	tmp := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
+
+	orig := CurrentWorkspace()
+	defer SetCurrentWorkspace(orig)
+
+	SetCurrentWorkspace(WorkspaceLocal)
+	want := filepath.Join(tmp, "config.json")
+	if got := GetConfigPath(); got != want {
+		t.Errorf("local: GetConfigPath() = %q, want %q", got, want)
+	}
+
+	SetCurrentWorkspace(WorkspaceOpenClaw)
+	want = filepath.Join(tmp, "openclaw", "config.json")
+	if got := GetConfigPath(); got != want {
+		t.Errorf("openclaw: GetConfigPath() = %q, want %q", got, want)
+	}
+}

internal/credential/default_provider.go

@@ -21,11 +21,14 @@ import (
 
 // DefaultAccountProvider resolves account from config.json via keychain.
 type DefaultAccountProvider struct {
-	keychain keychain.KeychainAccess
+	keychain func() keychain.KeychainAccess
 	profile  string
 }
 
-func NewDefaultAccountProvider(kc keychain.KeychainAccess, profile string) *DefaultAccountProvider {
+func NewDefaultAccountProvider(kc func() keychain.KeychainAccess, profile string) *DefaultAccountProvider {
+	if kc == nil {
+		kc = keychain.Default
+	}
 	return &DefaultAccountProvider{keychain: kc, profile: profile}
 }
 
@@ -36,7 +39,7 @@ func (p *DefaultAccountProvider) ResolveAccount(ctx context.Context) (*Account,
 		return nil, &core.ConfigError{Code: 2, Type: "config", Message: "not configured", Hint: "run `lark-cli config init --new` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete setup."}
 	}
 
-	cfg, err := core.ResolveConfigFromMulti(multi, p.keychain, p.profile)
+	cfg, err := core.ResolveConfigFromMulti(multi, p.keychain(), p.profile)
 	if err != nil {
 		return nil, err
 	}

internal/credential/integration_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/envvars"
+	"github.com/larksuite/cli/internal/keychain"
 )
 
 type noopKC struct{}
@@ -99,7 +100,7 @@ func TestFullChain_ConfigStrictMode(t *testing.T) {
 	}
 
 	ep := &envprovider.Provider{}
-	defaultAcct := credential.NewDefaultAccountProvider(&noopKC{}, "")
+	defaultAcct := credential.NewDefaultAccountProvider(func() keychain.KeychainAccess { return &noopKC{} }, "")
 
 	cp := credential.NewCredentialProvider(
 		[]extcred.Provider{ep},

internal/envvars/envvars.go

@@ -11,4 +11,11 @@ const (
 	CliTenantAccessToken = "LARKSUITE_CLI_TENANT_ACCESS_TOKEN"
 	CliDefaultAs         = "LARKSUITE_CLI_DEFAULT_AS"
 	CliStrictMode        = "LARKSUITE_CLI_STRICT_MODE"
+
+	// Sidecar proxy (auth proxy mode)
+	CliAuthProxy = "LARKSUITE_CLI_AUTH_PROXY" // sidecar HTTP address, e.g. "http://127.0.0.1:16384"
+	CliProxyKey  = "LARKSUITE_CLI_PROXY_KEY"  // HMAC signing key shared with sidecar
+
+	// Content safety scanning mode
+	CliContentSafetyMode = "LARKSUITE_CLI_CONTENT_SAFETY_MODE"
 )