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

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

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 (22, 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

Reuses the current session's provider / model (injected implicitly; falls back to AVL-Zero if unset). Returns answer + citations[] (file / start_line / end_line / name) + hit_count + 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 plan (running tests has write side-effects); available in assess, so the acceptance stage can actually run the tests.

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 sub-agent 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 (sub-agent 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 service 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.