This glossary defines cross-cutting terms for Netclaw engineering documents. PRDs, engineering specs, OpenSpec files, and reviews use these meanings.
A code anchor shows the current implementation owner. It does not freeze the class name or prevent a later refactor.
- Link to this file instead of copying a definition into another document.
- Define a local term when only one capability uses it.
- Add a term here when two or more capabilities need the same meaning.
- State an explicit exception when a specification narrows a glossary term.
- Prefer a plain term over an internal class name in descriptive text.
This flow shows a normal tool return:
model
-> tool call
-> dispatcher
-> authorization
-> optional approval request
-> tool implementation
-> factual tool result -> redaction and output bound --+
-> internal tool receipt ------------------------------+---> remediation presenter
-> model-facing result
internal tool receipt
-> optional actor working-context update
The result and receipt are sibling outputs of execution. The remediation presenter can use both to build the final model-facing result. The actor uses a successful receipt only when that receipt contains a defined state effect.
A terminal non-cancellation exception follows a different delivery branch:
dispatcher classifies the receipt and throws
-> parent or child actor creates the factual failure result
-> remediation presenter
-> model-facing result
An approval request remains non-terminal, and caller cancellation propagates. Neither case creates this terminal receipt and failure result.
An actor owns mutable runtime state and processes one message at a time. Netclaw uses actors for sessions, subagents, reminders, and other runtime components.
The main session is the actor that owns the user conversation. Some code and specs call it the parent session when they compare it with a subagent.
Code anchor: LlmSessionActor
A subagent is a child actor that performs one delegated task. It has its own model requests, tool exposure set, and ephemeral working context.
Code anchors: SubAgentActor, SubAgentSpawner
The working context is actor-local state that helps later model turns. It
contains the optional declared project directory and a bounded list of recently
used files. The main session persists its WorkingContext. A subagent keeps its
working context only for the child run. Git branch and worktree facts come from
a separate inspection and are not fields in either working context.
Code anchors: WorkingContext, ChildFileActivityTracker
Durable data survives actor restart because Netclaw stores it. Ephemeral data exists only in memory for the current call, turn, actor, or process.
Example:
durable: a stored tool-role chat message
ephemeral: the ToolInvocationReceipt for that tool call
A local-control proof shows that a process can use the Netclaw host key ring. It authorizes one named and time-bounded host operation. It is not a device token, source-address claim, or general operator session. Processes share this authority only when they use the same Netclaw home and key ring.
Code anchor: LocalControlPairingProofProtector
A pairing code is a temporary credential for one device registration.
The daemon keeps one code in process memory for five minutes.
A successful exchange consumes the code.
An expired code requires a new netclaw daemon pair command.
Code anchor: PairingActor
A device token is a bearer credential that identifies one paired device. The client stores the raw token as a protected secret. The daemon stores a salted hash in the durable device registry. The token remains valid until the operator revokes the device. The token has no refresh flow, and pairing-code expiration does not affect it.
Code anchor: DeviceRegistry
A tool definition is the name, description, and argument schema that the model can see. It tells the model how to author a tool call.
A first-party tool is implemented and registered by Netclaw. An MCP tool comes from an external Model Context Protocol server. Both kinds still pass Netclaw's exposure and authorization boundaries.
A policy-visible tool passes ToolAccessPolicy.IsToolExposed for the current
audience. This check applies feature gates, audience rules, approval-mode
denies, and shell-coupled limits. MCP registrations also apply MCP server and
tool rules. A policy-visible tool can still be Deferred and absent from the
current model request. Policy visibility does not grant execution authority.
Example:
list_reminders passes ToolAccessPolicy.IsToolExposed
-> policy-visible
-> still absent until the actor loads its Deferred schema
-> normal authorization still controls a later call
Code anchor: ToolAccessPolicy.IsToolExposed
A native Netclaw tool is a first-party structured tool in ToolRegistry. In
this phrase, native does not mean a host executable or a native binary.
Code anchors: ToolRegistry, NativeToolShellCorrectionDetector
A skill resource is an additional file inside a registered file-backed skill
directory. The skill_read_resource tool resolves it from a logical skill name
and a permitted relative path. The skill_load tool reads SKILL.md instead.
skill_read_resource("netclaw-operations", "references/tools.md")
-> read references/tools.md inside the netclaw-operations skill folder
skill_read_resource("netclaw-operations", "SKILL.md")
-> reject the request and direct the model to skill_load
Code anchors: SkillReadResourceTool, FileSkillSource
A workspace tool reads, lists, writes, edits, attaches, or selects files and directories. It uses the project and session path rules in this glossary.
A core tool is eligible for the initial model-visible tool set. Policy can still hide it from a specific audience or session.
A deferred tool is registered but absent from the initial model-visible set. An allowed actor can find it and load its schema later.
Schema exposure means that the model can see a tool definition. Exposure does not grant permission to execute the tool.
Example:
load_tool("list_reminders")
-> the next model request can see the list_reminders schema
-> a later list_reminders call still runs normal authorization
A tool call is the model-authored tool name, arguments, and call identifier. It is a request, not proof that Netclaw executed the tool.
The dispatcher is the shared execution boundary for registered tools. It finds the registration, runs authorization, invokes the tool, and records an outcome.
Code anchor: DispatchingToolExecutor
Authorization is the runtime decision that allows, denies, or pauses a tool call. It evaluates the current audience, policy, path, and approval state.
An authorization attempt is one tool call's authorization lifecycle. It starts before the first policy evaluation and ends with a correction, denial, or tool result. An interactive prompt, its decision, and a retry of that same call stay inside the same attempt. A replacement call that the model authors after a correction starts a new attempt.
AuthorizationAttemptId is opaque diagnostic metadata for joining lifecycle
events. It contains no user data and grants no authority. It is distinct from
the provider-authored tool-call identifier and from a trace identifier.
call c1 -> policy -> prompt -> approve -> retry -> result = attempt a1
call c2 after a correction = attempt a2
Code anchor: AuthorizationAttemptId
Authority is the set of actions that the current session is permitted to take. Tool exposure, a receipt, and a correction instruction do not add authority.
Approval is an operator decision for a call that requires consent. Approval is one input to authorization. It is not the same as schema exposure.
Example:
schema exposed + approval required + no approval
-> the model can author the call
-> Netclaw does not execute the tool
Reviewed-safe policy is a shell approval rule for a small configured set of read-only command phrases. It can avoid a prompt only after parsing succeeds and the shared path access policy allows every relevant path. It does not define trusted roots or grant filesystem authority by itself.
Code anchors: ReviewedSafeShellPolicy, ReviewedSafePolicy
The tool result is the text that Netclaw returns to the model. Normal dispatcher results pass output redaction and bounding before delivery. A result can contain data, an error, or a factual explanation of a correctable problem.
A tool receipt is trusted internal data about one completed invocation attempt. The attempt can end before the tool implementation runs. An actor uses the receipt to update state without parsing model-facing text or authored arguments.
Success carries file activity and an optional project declaration. A correction carries its remediation code. Other outcomes carry no success payload. The internal cases preserve the constructor guards and collection ownership.
Code anchor: ToolInvocationReceipt
Example:
result:
"README content..."
receipt:
category = Success
file activity = Read("/workspace/project/README.md")
File activity is a canonical path and file operation recorded in a successful receipt. The working context uses it instead of guessing paths from authored arguments or result text.
The outcome category is the closed status in a tool receipt. Current categories include success, invalid input, access denied, not found, transient failure, and recoverable correction.
Code anchor: ToolInvocationOutcomeCategory
A remediation is bounded advice for the model after a denied or correctable request. It does not change the path access decision or grant authority.
A remediation code is a closed internal value that selects one remediation. It contains no path or free-form instruction.
Code anchor: ToolRemediationCode
Example:
result:
"No project or session directory is available."
receipt:
category = RecoverableCorrection
remediation = SetWorkingDirectory
The prose phrase "typed remediation" means that the receipt uses this enum. It does not mean that Netclaw executes the action or grants new authority.
The remediation presenter converts a valid remediation code into one fixed model instruction. It does not inspect arguments, execute tools, or grant authority.
Code anchor: ToolRemediationPresenter
Example:
input result: "No project or session directory is available."
input code: SetWorkingDirectory
tool visible: true
final message:
"No project or session directory is available.
Next action: call set_working_directory ..."
If the named tool is hidden, the presenter leaves the factual result unchanged. This prevents an instruction that the current model cannot follow.
These terms classify what an MCP server's answer means for the client. The
netclaw-mcp and netclaw-tools capabilities share them. The examples come
from a link-shortener MCP server observed on 2026-08-26.
A transport or session failure means the request got no usable answer. The connection broke, the request timed out, or the server reported that the session is gone (HTTP 404 under Streamable HTTP). A new session can repair it. Netclaw reconnects once for later calls and never replays the failed call.
Example:
HttpRequestException with no status code -> transport failure
HttpRequestException with HTTP 404 -> session failure
IOException, ClientTransportClosedException -> transport failure
Code anchor: McpClientManager.IsTransportOrSessionFailure
An application error is an answer from a server that received the request: an HTTP status other than 404, a JSON-RPC error, or a tool-declared error. A new session cannot change the answer, so Netclaw returns it without a reconnect.
Example:
HTTP 429 {"statusCode":429,"error":"Too Many Requests","message":"Rate limit exceeded, retry in 52 seconds"}
HTTP 401 {"jsonrpc":"2.0","error":{"code":-32000,"message":"Unauthorized: No API key provided"},"id":null}
Both are application errors. Neither triggers a reconnect.
A tool-declared error is a successful JSON-RPC response whose result carries
isError: true. The tool ran and reported a failure in its own words. Netclaw
formats it as a tool result and logs it at Warning. It is not an exception and
does not produce an exception outcome.
Example (search-links called with only its one required argument):
HTTP 200
{"result":{"content":[{"type":"text","text":"Internal Server Error"}],"isError":true},"jsonrpc":"2.0","id":70}
tool result: "Error: MCP tool 'shortio/search-links' reported a failure: Internal Server Error"
daemon log: [WRN] McpClientManager: MCP tool 'shortio/search-links' reported a failure: Internal Server Error
Code anchors: McpClientManager.ReportToolFailure, McpToolResultFormatter
An OAuth-managed server is one for which Netclaw uses OAuth. The daemon knows
this from two facts, not from header names: it holds OAuth tokens for the
server, or the server answered with a genuine OAuth challenge that the SDK
turned into a Bearer-scheme McpException. Only an OAuth-managed server gets
the netclaw mcp auth remedy. A 401 from any other server means the operator
must check the configured credentials or headers, whatever those headers are
named.
Example:
http, stored OAuth tokens, tool call -> 401 -> OAuth-managed; "Run: netclaw mcp auth"
http, no tokens, SDK reports a Bearer challenge -> OAuth-managed; "Run: netclaw mcp auth"
http, X-Api-Key header, no tokens, tool call -> 401 -> not OAuth-managed; "Check configured credentials or headers."
http, no headers, no tokens, isError "token expired" -> not OAuth-managed; stays Connected
Code anchors: McpClientManager.HasStoredOAuthTokens, McpClientManager.IsOAuthChallenge
Project scope is the declared project directory for a main session or subagent run. Workspace tools use it as the first base for relative paths.
A session storage envelope is the one physical directory that contains all session-owned files for a new-layout session. Its path is fixed when the session binds its versioned storage binding. Its contents are mutable.
The envelope contains distinct working, artifact, temporary, worktree, log, and child-run areas. Netclaw supplies the current envelope as an implicit trusted root. It is not a project scope, the default shell cwd, or an unconditional shell grant.
<session-envelope>/
├── attachment-staging/ # untrusted inbound bytes before admission
├── workspace/ # default no-project working directory
├── artifacts/ # retained parent outputs
├── tmp/parent/ # disposable parent files
├── worktrees/ # managed source worktrees
├── logs/session.log # raw parent log
└── subagents/<run-id>/
├── artifacts/
├── tmp/
└── logs/session.log # raw child log
An attachment staging directory holds inbound bytes before the attachment
pipeline accepts them. A version-2 session stores this directory below its
session storage envelope and outside workspace/.
The storage location does not mark the content as trusted. The attachment
pipeline scans each file before it moves an accepted file to
workspace/inbox/. A rejected file does not become agent-visible media.
A session storage binding is the durable layout version and absolute envelope root for a new-layout session. It has one root. A later configuration change does not recompute that root. Existing sessions keep the binding absent and use their established path behavior; absence is not a second descriptor shape.
The Netclaw database is the single SQLite database at
NetclawPaths.SqliteDbPath. It is the source of truth for all SQLite-backed
production data, including actor journal and snapshots, durable reminders, the
session catalog, daily statistics, memory, and session storage bindings.
Production configuration cannot select another database path or an in-memory
persistence provider. Test harnesses may replace actor persistence internally,
but that test seam is not part of the runtime configuration contract. A
supplied Persistence section is invalid and fails daemon startup.
The session directory is the agent-facing workspace/ area inside the session
storage envelope. It is the relative-path base when the session has no valid
project directory. It is not the complete storage envelope.
The phrase session scratch is a legacy term that mixed the session directory
with disposable storage. Current designs use session directory for the working
and relative-path base, and managed temporary directory for disposable work.
Current runtime text and identifiers must use the specific term.
A raw session log is the diagnostic file for one main session or subagent run. New-layout raw logs are physically inside the session storage envelope but are outside the session directory.
Personal retains the shared session roots. Public and Team receive the current session envelope and workspace roots. Each legacy run can access its exact raw log, but this grants no access to adjacent files or separate parent/child logs. Children inherit parent roots and restrictions. The operation profile, explicit configured roots, link checks, and protected paths still control each request.
These reads return normal bounded file-tool output. A raw session log does not use a separate activity projection or log-specific redaction layer.
A managed temporary directory contains disposable files for one parent or subagent run. Netclaw places it inside the session storage envelope. Each run receives a different directory.
Netclaw sets TMPDIR, TMP, and TEMP to this directory for child processes.
The managed temporary directory is not a project scope or an authority grant.
An artifact directory contains outputs that a parent or user must keep or attach. It is separate from the session directory and managed temporary directory. Netclaw does not apply a retention policy to either directory yet.
A worktree directory is the worktree_dir area inside the session storage
envelope. It is separate from each run's managed temporary directory because a
Git worktree can contain valuable source state.
Netclaw announces this path in the existing session context. Agents compose
shell_execute and set_working_directory to create and adopt Git worktrees.
The path uses the ordinary shell path access decision. It does not create a
special worktree tool or bypass shell syntax, hard-deny, or approval policy.
A child run directory is the area below
<session-envelope>/subagents/<run-id> for one subagent run. Its artifact,
temporary, and raw-log areas share the same opaque run identifier. The parent
and child use the ordinary path access decision to inspect it.
A session-owned directory has a storage lifetime tied to one session or run. Session directories, managed temporary directories, artifact directories, and managed worktree directories are session-owned, but the label grants no filesystem authority. Authorization still comes from a path access decision.
A trusted root is a configured or context-derived directory boundary that can supply filesystem authority. A path below this root can still fail an audience, file-operation, link, or protected-path check.
The netclaw-tools capability owns the trusted-root interpretation and the
filesystem authorization decision. Session and cwd capabilities only supply
roots and candidate paths.
Stable machine-readable reason codes can retain legacy tokens such as
trust_zone. These tokens are compatibility keys, not current engineering
terms. Specifications and operator prose must use the canonical terms here.
Ordinary configuration is the non-secret persisted configuration in
netclaw.json. It can be read through structured file tools when normal roots,
audience policy, and operation permissions allow it. Read authority does not
grant write, attach, or shell authority.
Secret configuration belongs in protected stores such as
secrets.json, key storage, OAuth credential files, or webhook secret files.
Those stores and control-plane state remain read-denied.
A canonical path is a fully qualified, normalized path with no unresolved dot segments. Canonical form does not by itself grant access.
A path relationship states whether a canonical path is the trusted root, is a descendant of that root, or is outside that root. This fact does not grant access.
A file operation is the requested authorization category for a path. Read
includes reading, listing, and searching. Write includes creating and
editing. Attach and DeclareProjectScope remain distinct because they have
different policy rules. One path can have a different decision for each
operation.
A path access decision is the typed allow or deny result for one canonical
path and file operation. A denied decision contains a failure category and
human-readable detail. The netclaw-tools capability owns this decision and
applies these inputs:
- the path relationship to each trusted root;
- the file operation;
- the audience policy;
- link and protected-path facts.
Structured file tools and project-directory declarations provide their exact
file operation to this decision. A shell call first passes tool capability and
shell command policy. Every known shell path then uses the conservative Write
operation because Netclaw does not infer whether arbitrary shell syntax reads or
mutates a path.
This dependency is one-way. File protection can deny an otherwise eligible
shell call, but file authority cannot grant shell capability or bypass shell
policy. A denial is terminal. Approval does not widen an explicit Roots or
None file profile. An unresolved interactive shell path may still reach the
existing one-shot approval flow, but it cannot receive reviewed-safe or
persistent coverage.
Temporary-path correction does not consume, make, or override a path access decision. After terminal authorization checks pass, it may use path and syntax facts to offer remediation before an approval prompt. The replacement call is authorized from the beginning.
Relative base availability states whether session-cwd can select a base for a
relative path. An available base can enter filesystem authorization. An
unavailable base is absent or unusable before authorization starts.
Availability does not mean that a path is safe or authorized. After
session-cwd selects a base, netclaw-tools creates the path access decision.
Netclaw does not try another base after that decision denies access.
Example:
project base unavailable
-> try the session directory
project ancestor is a link to /outside
-> selected project base
-> path access decision = Denied(link boundary)
-> do not try the session directory
A spill is the full redacted result stored in session-owned output after the
result exceeds its inline budget. The model receives an opaque call identifier.
It uses tool_output_read to read another bounded window.
large result
-> bounded inline preview
-> opaque call id
-> tool_output_read(CallId, Start, Limit)
The model does not receive the internal spill path.