DSHarness Systems Dissection Pinned baseline 47f943859b · 36 verified / 0 in progress / 36 chapters
中文
Tool System·Chapter 17

Complete Tool Catalog and Capability Taxonomy

Inputs, outputs, policy, and UI intent for every model-visible tool

VerifiedUpstream 47f943859bScope: Enumerate tool names, provider packages, schemas, parallel modes, risk surfaces, and backend seams from generated catalogs and source.

Conclusion: DeepSeek Harness has no single fixed “default tool list”; it has a provably complete shipped-package ceiling and a runtime view resolved by composition

At the pinned baseline, the upstream generated catalog covers 24 shipped tool packages, 52 schema entries, and 51 unique generated names. The only duplicate is bash, registered by both a one-shot shell implementation and a persistent PTY implementation. The generator also records the shipped configured alias subagent_fork without giving it a separate schema heading, so the catalog represents 52 distinct shipped names. Those names never appear together by default: the standard Web preset resolves to 25 root tools on the baseline Linux composition with an attachment service, the minimal preset has 2, and Code/Cordis/custom presets, scope restrictions, dynamic plugins, and child identity change the set further.

Reproducible counting rule

This chapter counts package and tool headings in the generated catalog and checks every package-map row. It derives each actual set again from the shipped preset and host-service conditions. The generator boots every package in a separate real Context, reads ctx.tools.schemas(), and uses an on-disk glob to prevent a new tool package from being omitted. TOOLCAT-GENERATEDTOOLCAT-GENERATOR

1. Three Sets That Must Not Be Conflated

SetPinned-baseline resultQuestion answeredWhat it does not prove
Generated catalog ceiling24 package sections; 52 schema entries; 51 unique generated names; 1 additional shipped aliasWhat every shipped packages/*/tool-* package can contribute under the selected configThat one Agent sees everything at once
Composition setPreset + host services + platform + feature flagsWhich definitions a deployment mountedThat every scope may see them
Request setScope view + restrictions + native/code/both projectionWhich schemas this model request actually receivesThat a call will be approved or its backend is ready

There is also a fourth, temporal dimension: definitions are live Cordis effects. Hot mounting or disposal after queueing but before start can change visibility or parallel classification. Auditing therefore needs the request header and durable call/result records; the process's current catalog cannot reconstruct history by itself.

2. Why the Generated Catalog Is Stronger Than Static Grep—and Still Not Runtime Truth

glob packages/*/tool-* → completeness guard
for each manifest entry:
  fresh Context → SystemPrompt → ToolRuntime → package-specific seams
  → mount plugin → ctx.tools.schemas(scope) → sort → dispose
render package map + name + description + JSON Schema + source link
Two failure guards

Omitting an on-disk tool package from the manifest fails. Listing a package that remains pending for a missing service and registers zero schemas also fails. Each package boots independently so registrations from one package cannot be attributed to the next. TOOLCAT-GENERATOR

3. Complete Package/Name Map (24 Packages, 51 Generated Names + 1 Shipped Configured Alias)

Capability family / packageModel-visible namesMain seam / effect
Human · tool-ask-userask_user_questionWaits for a human answer from a UI/provider; the call remains open while waiting
Code transport · toolsrun_codeReserved Code Mode transport; nested subcalls re-enter the complete tool pipeline
Plan · plan-modeexit_plan_modeReviews a plan and writes plan/mode inactive after approval
One-shot shellbash / pwshFresh process, optional background job; platform selects one
Runtime self-modification · tool-cordiscordis_define, cordis_inspect_list, cordis_inspect_query, cordis_inspect_self, cordis_run, cordis_stop, cordis_undefineDefines, inspects, starts, and disposes process-local dynamic packages; absent from shipped trees by default
Persistent shellbashOwner-isolated PTY state; same name as one-shot bash, different definition
Standalone editorstr_replace_editorView/create/literal replace/insert over ctx.fs
Filesystemread, read_image, write, editObservation events, write/edit intents, durable attachments; image registration requires an attachment service
Filesystem discoveryglob, grepFixed argv invokes packaged ripgrep; complete capped output may spill
Terminalterminal_open, terminal_read, terminal_send, terminal_signal, terminal_list, terminal_closePersistent PTY lifecycle; send can register a background job
Goalcreate_goal, get_goal, update_goalSession-owned durable goal, revision, and round state with authority checks
Scheduleschedule_create, schedule_delete, schedule_listOpt-in live root scope only; writes schedule/change
Language serverlspStable schema and a structured refusal when no provider exists
Fixed iterationralphCreates a fresh structured child per round in a fixed foreground workflow
SkillskillLoads a trusted instruction catalog/body and can inject replacement catalogs
Session querysession_search, session_event_search, session_trace, session_event_trace, session_event_readExplicitly authorized lexical search, lineage, and exact event reads; absent from the default standard preset
Delegationsubagent (shipped alias subagent_fork)Provider, name, and background mode are configured; the child owns a separate Session
Child controlsend_message, interrupt_agent, list_agentsFollow-up, interruption, and listing for continuable children
Child return channelreportRegistered only inside a continuable in-process child; writes a user-role message to its direct parent
Background jobsjob_list, job_output, job_killUnified control for shell, PTY-send, and one-shot-subagent jobs
Todotodo_writeWrites todo/write; allowing multiple in-progress items is a required deployment choice
Programmable orchestrationworkflowRestricted worker script orchestrates Agents; the script itself has no filesystem, network, or timers
Webweb_search, web_fetchProvider-neutral seam; composition selects search and fetch availability
Per-package attribution

The upstream package map records Requires, Writes/Affects, shipped aliases, and a deployment note for every package. Exact descriptions, parameter JSON Schemas, and production-source links follow. This table is the complete index without copying more than 1,800 lines of schemas. TOOLCAT-PACKAGE-MAP

4. The Standard Web Root's Actual 25 Tools

SourceNamesCount
Platform shellbash on Linux/macOS; pwsh on Windows1
Filesystem + searchread, read_image, write, edit, glob, grep6
Jobs + skilljob_list, job_output, job_kill, skill4
Goal + plancreate_goal, get_goal, update_goal, exit_plan_mode4
Delegationsubagent, subagent_fork, send_message, interrupt_agent, list_agents5
Workflowworkflow, ralph2
Interaction/state/webask_user_question, todo_write, web_search3
Total25
Conditions are part of the conclusion

The standard preset selects one platform shell; mounts fs/search/jobs/skill/goal/plan, two delegation names, three controls, workflow/Ralph/ask/todo; and sets fetch:false. The baseline host mounts a local attachment store, so read_image registers. TOOLCAT-STANDARD-BASETOOLCAT-STANDARD-ORCHESTRATIONTOOLCAT-ATTACHMENT

exit_plan_mode remains in the schema even when planning is inactive so changing mode does not churn the tool catalog and request-cache prefix; execution rejects invalid state instead. Codex and Claude Code delegation rows are explicitly disabled in this preset, and web_fetch is absent.

5. Minimal Is Not Merely “A Smaller Standard”; It Encodes a Different Complete Product Assumption

Exact set

Minimal uses a complete persona, suppresses runtime-context snapshots, omits compaction, and exposes only persistent bash and str_replace_editor. It creates isolated realms for its PTY and bare local filesystem. TOOLCAT-MINIMAL

This is why “the Harness supports 51 tools” and “this Agent has 2 tools” can both be true. Capability is not a binary product checklist; it is the language a profile/preset composes for an Agent.

6. Same Name Does Not Mean Same Semantics: Two bash Definitions

ImplementationProcess modelStateTypical composition
dsh-tool-bashFresh process per call through ctx.shellcwd/env come from request and executor; no continuous PTY statestandard/base
dsh-tool-bash-persistentReuses an owner-isolated PTY through ctx.terminalsShell state survives across callsminimal

7. Filesystem Family: Discovery, Reads, Mutation, and Observation Are Separated

ToolActionKey policyPresentation intent
glob/grepFixed-argv discovery through packaged rgTimeout/cap/spill; neither shell nor ctx.fsSearch-result groups
readBounded UTF-8 line windowRecords present/absent version observationRead card + locations
read_imageBounded bytes → content-addressed attachmentExtension/media/model-route gates before I/ODurable image block + metadata
write/editCreate/overwrite and literal replacementDefault observation policy requires an unchanged version; sandbox can escalate approvalDiff intent + durable metadata
str_replace_editorCombines view/create/replace/insert in one toolCompressed interface for minimal; still uses the fs seamGeneric/diff

Notably, glob/grep are semantically read-only but do not opt into parallelism. Read/write semantics and scheduler classification are independent dimensions.

8. Shell, Terminal, and Job: Execution Capability Is Orthogonal to Lifecycle Control

bash/pwsh --run_in_background--> Job Registry <--terminal_send / one-shot subagent
                                        |
                           job_list / job_output / job_kill

terminal_open/read/send/signal/list/close → persistent PTY registry

Job tools are not a shell-specific API; they form one control plane across producers. The six terminal tools explicitly expose session creation, I/O, signaling, and close in exchange for stronger statefulness. Standard does not mount them. Minimal does not expose terminal controls either; it wraps a persistent PTY as the same bash name.

9. Plan, Goal, Todo, and Ask: Four Human/Collaboration States, Not One Task List

PrimitiveLifetimeSource of truthTool action
Plan modeAgent mode across stepsplan/mode events + reviewerexit_plan_mode submits a complete plan
GoalMulti-round and continuable within a SessionGoal service/projectionCreate/get/update
TodoLatest checklist projection within a Sessiontodo/writeWhole-list replacement write
QuestionSuspension of one tool callUserQuestion providerWaits for and returns an answer

Chapter 15 analyzes their durable semantics. Here the important point is that similar names do not justify merging their tool surfaces.

10. Delegation, Workflow, and Ralph: Three Degrees of Orchestration Freedom

ToolThe model choosesThe runtime fixesResult channel
subagent*One child prompt, label, foreground/backgroundProvider, depth, background modeTool result, job settlement, or continuable child
workflowFan-out/control flow in restricted JavaScriptWorker isolation, Agent bridge, concurrency/total capsForeground aggregated result
ralphObjective and optional round countFixed iteration script with a fresh child per roundForeground final result

send_message/interrupt_agent/list_agents manage continuable children. report exists in the reverse direction inside child scope, not in the root catalog. Chapters 24–26 trace Sessions, activation, and inboxes.

11. Web, LSP, Session Query, and Skill: Stable Schemas, Potentially Absent Provider Capability

These tools separate their model-facing contracts from backends: web_search/web_fetch use ctx.web, lsp uses ctx.lsp, Session Query uses ctx.sessionQuery whose FTS can be disabled, and Skill uses a scope-layered catalog. Schemas may remain prefix-stable while execution returns unavailable/disabled. A visible tool never proves provider success.

Design assessment

This stable surface favors KV caching and provider replacement. The cost is that capability discovery cannot stop at schemas. A strong host should also surface provider readiness, policy mode, and failure reasons in UI/telemetry instead of making the model probe with failed calls.

12. The Cordis Toolset Is a Deliberately Opt-in “Modify My Runtime” Capability

The seven cordis_* tools define, inspect, run, stop, and undefine dynamic packages. A running package can register more model-visible tools until stop, undefine, or restart, so the 51-name ceiling is naturally non-closed once this facility is enabled.

Default safety posture

The generated package map explicitly says this toolset appears in no shipped tree. Without dynamicCordisRunner it never activates. It is not a hidden default superpower; it is a real runtime-code trust boundary a deployment must opt into. TOOLCAT-PACKAGE-MAP

13. Parallel Classification: Only 8 Unique Names/Definitions Explicitly Opt In; Everything Else Fails Closed to Exclusive

Explicitly parallel-safeRationaleIn standard root?
read, read_imageReads only; later mutation closes observation races with an in-lock version check; attachments are content-addressedYes
web_search, web_fetchProvider reads do not mutate parent-Agent stateSearch only
session_trace, session_event_trace, session_event_readAuthorized exact/lineage readsNo; query package is opt-in
subagent definition (including configured aliases)A child does not mutate the parent Session; the only parent write is a synchronous commutative task insertionsubagent and subagent_fork
Fail-closed classifier

After excluding helpers, generated code, and tests, production source contains only these eight isConcurrencySafe: () => true declarations. The registry returns parallel only for an exact true; absence, invalid input, or a thrown classifier is exclusive. Seemingly read-only operations such as glob/grep, goal reads, and job listing therefore remain barriers. TOOLCAT-PARALLEL-OPTINSTOOL-SCHEMA-PROJECTION

14. “Dangerous” Is Not One Boolean on a Tool Name

Risk axisRepresentative toolsActual control point
File mutationwrite/edit/editorfs intent, observed version, sandbox escalation, approval
Arbitrary processbash/pwsh/terminalSandbox provider, shell policy, timeout, signal/job kill
External data flowweb/MCP/LSPProvider URL/credential/SSRF boundary and output retention
Cross-Agentsubagent/control/workflowParent authority, depth/caps, workspace effects, continuation ownership
Durable stategoal/todo/scheduleSession/root authority, event validation, durability barrier
Runtime coderun_code/cordis_*VM/worker surface, nested pipeline, opt-in composition

This table is a threat-model classification, not a source-level risk score. Harness distributes controls across provider confinement, pre approval, monotonic guards, tool-specific event gates, and execution ownership. Chapters 19, 20, and 31 verify those boundaries.

15. Inputs, Outputs, and UI Intent: The Catalog Promises Model Schemas; the Execution Contract Still Lives in ToolDefinition

Catalog contents

The generator emits name, description, parameter JSON Schema, and source for each item. Output schemas, canonical values, timeout/concurrency metadata, presenters, and finalizers are outside the generated catalog page. The ToolDefinition analysis in Chapter 16 and this package map must be read together. TOOLCAT-GENERATORTOOL-DEFINITION

The UI does not hard-code every card by tool name either. Tools return provider-neutral generic/terminal/diff/search/read/web render intents. The Host pairs calls and results through the current scoped definition; missing pairing or presenter failure preserves the raw event and falls back to a generic card. TOOL-PRESENTATION-INTENTSTOOL-HOST-PRESENTER

16. Availability Matrix: Registration, Visibility, Scheduling, Approval, and Backend Readiness Are Five Gates

package mounted?
  → required service satisfied and tool registered?
    → current Agent scope can see it?
      → presentation mode exposes native name or Code SDK?
        → pre-policy + approval + guards allow this call?
          → provider/runtime is ready and body succeeds?

A “no” at any layer can appear as no schema, UNKNOWN_TOOL, approval required, provider unavailable, or an ordinary error result. Calling all of them “permission failures” sends diagnosis to the wrong layer.

17. Confirmed Documentation/Composition Drift and Audit Traps

TrapCorrect reading
Treating the generated catalog as the standard defaultIt is an isolated per-package boot ceiling; derive standard from its preset
Guessing parallelism from “read-only”Only an explicit classifier returning true is parallel; everything else is exclusive
Inferring implementation from tool namebash has two shipped definitions, and subagent names are configurable
Assuming schema presence means provider readinessLSP/Web/Query can keep stable schemas and fail as unavailable at execution
Using today's presenter to reconstruct historical UIThe Host reads the current definition; a call on an older page gets generic fallback
Assuming Code Mode deletes capabilitiesIt changes the wire entrance; the SDK retains end capabilities and subcalls re-enter the pipeline

18. Design Assessment and Verification Status

ChoiceBenefitCost
Separate tool package from provider seamStable schemas with replaceable backendsSchemas cannot express readiness
Collect the generated catalog by real bootCaptures dynamic schemas, configured names, and injection conditionsStill represents the generator's selected config branches
Let presets define the capability languageOne runtime spans a two-tool minimal Agent and a full AgentAny “default count” needs surface/platform/service qualifiers
Make parallelism explicit opt-inUnknown third-party tools serialize safelyRead-only tools that omit the declaration lose throughput
Provider-neutral presentationWeb and CLI share semantics with replay fallbackHot-changing a presenter can change the current rendering of old events
Verification scope

This chapter checked the generated tool catalog, generator completeness/boot logic, all 24 package-map rows, standard and minimal shipped presets, the attachment condition, every production isConcurrencySafe declaration, and the ToolRuntime classifier. Counts come from reproducible heading statistics over the pinned-baseline text. Upstream dependencies are absent, so this chapter does not claim a local generator or upstream-test run. The site's own build and consistency checks run before publication.

My Learning Notes

Autosaved only in this browser. Nothing is uploaded or committed. Export Markdown whenever you want to keep a copy.