Part III — Tool catalogue

This part covers Chapters 11–14: parameter lookup for the smart-coding and security-analysis tools, external-tool-service fields, and the tool permission policy.

11. Smart-coding tools

[!ref] Full details in the User Manual, "Smart-coding tools".

11.1 Tools

11.2 Common return fields

Read / search tools return:

Slimmer results (saves tokens / quota): workspace tools return paths relative to the workspace root (relPath), strip the root-path prefix from error strings (no leaking the absolute root), drop duplicate line_hashes, and emit pagination bookkeeping (next_offset, etc.) only when truncated=true.

11.3 fs.read

Encoding detection: a BOM takes priority; without one, common encodings such as GBK / GB18030 / UTF-16 are detected and decoded to UTF-8 before delivery. grep uses the same decoding path. Files judged to be binary are refused by default (override with as_text).

11.4 fs.write

11.5 fs.patch

11.6 fs.list

11.7 fs.glob

11.8 fs.grep

11.9 fs.exec / fs.exec.start

Shell syntax supported (outside unrestricted mode too):

• samples/ blocks execution only — reading files there, or passing them as arguments, is no longer refused.
• Commands issued through test.run / lint.run / sast.run go through the same guardrails and the same tokeniser.
• Path handling: absolute paths inside the workspace are judged exactly like relative ones; absolute paths are no longer refused outright.
• The allowlist now includes the cc family (cc / gcc / clang, …): write-out channels (-o, -MF, …) are confined to the workspace, and dangerous flag prefixes are blocked.
• Command-name normalisation (Windows): case and a .exe suffix no longer change the allowlist verdict; policy rejections carry the offending command and rule in the error.
• Output encoding: on Windows, GBK / UTF-16 output is normalised to UTF-8 at the collection point (both fs.exec and fs.exec.tail).
• Echo: the command echoed back in the result keeps its original quoting instead of being re-joined with spaces.
• Windows batch files (.bat / .cmd) have dedicated argument-injection guards.
• The working directory cannot be hijacked: a same-named file inside the workspace is never resolved as the program to run.

11.10 fs.exec.tail / .kill / .list

Local background-session caps: at most 16 concurrent; per-session disk log 256 MiB (overflow drops the tail); logs remain tailable after the process exits; auto-GC after 1 hour; sessions end with the Interpreter's lifecycle.

SSH remote background sessions are not subject to the above: state and logs live on the remote under <root>/.avlcode/sessions/, logs are complete files (no 256 MiB ring-buffer tail loss), and they survive reconnects and app restarts (see §22.4).

11.11 web.bing / web.fetch

11.12 code.* — Code-intelligence toolset (LSP-based)

Position parameters are 1-based (matching fs.read line mode / cat -n); converted to 0-based at the interpret layer before LSP.

Capability degradation: optional capabilities (implementation / type_definition / document_highlight / completion / signature_help / formatting, etc.) aren't implemented by every language server. Support is decided by the actual response, not predicted from the server's declaration (which avoids false rejections when a declaration is missing); once judged unsupported, the result is cached across sessions so the same server isn't probed again.

11.12.1 Built-in languages (24, by ID)

go · ts · py · c (cpp) · rust · java · deno · eslint (js linting) · lua · bash · yaml · php · ruby · vue · zig · dart · kotlin · clojure · elixir · haskell · fsharp · csharp · gleam · astro

Each language binds to an LSP command (gopls / typescript-language-server / pyright-langserver / clangd / rust-analyzer / jdtls / …); missing servers auto-download on demand (go install / npm etc.) with install-progress display.

11.12.2 User config file lsp.yaml / lsp.json

In workspace .avlcode/ or ~/.avlcode/, the first existing of lsp.yaml > lsp.yml > lsp.json wins:

lsp:
  rust:
    disabled: true              # disable
  go:
    cmd: gopls                  # override launch command
    args: ["-rpc.trace"]
    root_markers: ["go.mod", "go.work"]
  custom_lang:                  # add a custom server
    extensions: [".myx"]
    cmd: my-langserver
    install_via: npm
    install_pkgs: [my-langserver]

Hot reload: mtime/size changes re-read automatically — no workspace restart needed. Crashed server processes / dropped SSH sessions auto-restart.

11.12.3 Whole-repo RAG search and Q&A (code.search / code.ask)

Non-vector (zero-embedding) symbol-level whole-repo search: BM25 + identifier tokenization (camelCase / snake_case / kebab-case) + CJK bigram tokenization (so Chinese comments and Chinese questions match too), local and offline. The index lives in <base>/.avlcode/rag/symbols.jsonl (in-memory only for remote workspaces); after the first build it incrementally syncs by file mtime (edit / add / delete). Only definition-kind symbols are indexed (functions / methods / types / interfaces / constants, etc.).

The index covers at most 4000 files (not configurable). Beyond that the result reports the shortfall honestly rather than truncating silently: it carries index_covers_all_files=false, files_not_indexed (how many files were left out of the index) and a readable truncated_hint, so you can tell whether "no hits" means it really isn't there or simply wasn't covered.

code.search parameters

Returns hits[] (file / start_line / end_line / name / kind / score / why[] (matched keywords) / optional container·signature), count, indexed_symbols, indexed_files; a hint when empty.

code.ask parameters

Model: chosen by the model routing strategy among enabled 澜砥 models with an API key (Best quality by default); when none is available, the current session's provider / model (injected implicitly) is used; in local mode only the session's model is used; if neither is available the call errors. Timeout and output limit follow the chosen model's configuration. Retrieved snippets are sent to the chosen model.

Returns answer + citations[] (file / start_line / end_line / name) + hit_count + model + provider + routed (whether routing chose a 澜砥 model); says so plainly when nothing is found, never fabricates. Applies the structure-aware smart rerank to expanded retrieval by default (no explicit expand needed).

Caps: index files ≤ 4000, full-build timeout 120 s, ≤ 400 symbols / ≤ 4 MiB per file; structure rerank takes the top 8 hits. The incremental-refresh scope is corrected (no over-/under-refresh after file changes).

11.13 test.run — Test runner + structured failure feedback

Returns: failures[] (up to 50 {test, file, line, message}) + a small raw tail. Unknown frameworks degrade to exit code + tail. Disabled in both plan and assess (running tests has write side-effects).

11.13.1 Self-check gate (opt-in, generalised multi-checker)

testgate.yaml schema:

enabled: true
checks:                              # list of checkers (any combination)
  - name: test                       # test | diagnostics | lint | sast
    mode: block                      # block | report
    submode: changed                 # test: changed | full
    scope: changed                   # changed | workspace
  - name: lint
    mode: block
    submode: strict                  # lint: strict | lenient
    linters: [errcheck, govet]       # subset (optional)
  - name: sast
    mode: report
    submode: quick                   # sast: quick | deep
    config: .semgrep.yml             # offline rules (optional)
modes:                               # per-work-mode override
  plan:    { enabled: false }
  prepare: { enabled: false }

11.13.2 CheckSpec fields

11.13.2a testgen — Auto-add tests when edits lack them (opt-in)

• Not in the default set: you must explicitly add testgen to checks.
• Covered languages: Go / Python / JavaScript / TypeScript; other extensions (.c / .java, …) aren't judged.
• Skips test files themselves and generated artifacts: avoids "writing tests for tests" / "writing tests for .pb.go".
• Existence check via the zMCP gateway (fs.glob) — works correctly on SSH remote.
• Shares the 3-injection hard cap (MaxTestGateRetries): worst-case mis-fire is 3 rounds before the gate disengages.

11.13.2b judge — LLM end-of-turn self-review (opt-in, defaults to report)

• Independent fresh-context model call (reusing agentFacade.CompactSummaryStream); carries none of the agent's own conversation history, removing self-justification bias.
• Looks at: this turn's goal + diff — catches logic / semantic / security-intent issues machine checks miss.
• Few-shot examples + this turn's diagnostics injected as prompt background — sharper judgment, fewer false positives.
• Gating: judge runs after every cheap checker and only when all block-mode checkers are green.
• Model gibberish / dirty JSON / timeout → non-authoritative pass-through, never false-blocks.
• Return shape: {ok: bool, issues: [{file, line, severity, confidence, message}]} — severity ∈ error / warning / info, confidence ∈ 0..1. Block-mode confidence / severity thresholds are planned for Phase 2.

11.13.3 lint.run — Static linting (read-only)

Returns: findings[] ({file, line, rule, severity, message}), same shape as test.run. golangci-lint v1 / v2 JSON output flags adapt automatically. Read-only; available in plan / assess.

11.13.4 sast.run — Security static analysis (read-only)

Returns: findings[] same shape. Backend: semgrep. Read-only; available in plan / assess.

11.14 tools.list / tools.describe / tools.load — Tool introspection and on-demand loading

Introspection results are trimmed to what is actually available in this session (affected by the three-state tool permissions and by category lazy loading); the returned notes point out that "not in the list ≠ doesn't exist — try tools.load first". These two introspection tools themselves always pass through the subagent allowlist, but their output is still trimmed to that allowlist, and they can't override a user-configured deny list.

11.14.1 Tool category lazy loading

On by default (Settings.ToolLazyLoad, since schema v9). The switch lives in the agent manager → "Configure tools" tab → "Tool category lazy loading", not on the Settings page.

• Always-resident categories: fs (read/write / glob / grep / exec), tools (list / describe / load), agent (delegation + EnterPlanMode / ExitPlanMode / TodoWrite).
• 16 loadable categories: code / git / sec / vt / sbom / mcp / web / skill / test / lint / sast / market / plugin / gh / sys / time.
• Loading paths: ① implicit — categories are preloaded from keywords in each new user message (English and Chinese keyword tables); ② explicit — tools.load names a category. Categories from MCP backends connected mid-session are admitted automatically.
• Bypass: when there are ≤ 32 visible candidates, the whole table is admitted (subagent allowlist mode usually takes this path).
• When enabled, the system prompt carries a note telling the assistant the tool list is deliberately trimmed and can be extended on demand.
• Each MCP server can be configured individually for lazy loading (Settings.MCPLazyLoad, defaults to following the global switch) — see §13.1.

11.15 Python venv auto-detection

fs.exec / fs.exec.start follow the workspace virtual environment automatically when running Python commands:

Mechanism: rewrites the first command to the absolute path inside the venv and injects VIRTUAL_ENV / PATH. Out-of-tree discoveries cache for 5 min / 15s probe timeout. Global disable: AVLCODE_DISABLE_VENV_AUTODETECT=1.

pyright (code.*) is venv-aware too — consistent across local + SSH remote.

Exception: background commands on an SSH remote (fs.exec.start) are not venv-aware — venv detection reads the local machine's directory layout, so on a remote it would resolve to the wrong, local paths. Name the interpreter explicitly when running Python background tasks on a remote.