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
An open child run is a child run whose result has not yet had its follow-up
parent turn. It becomes open at durable acceptance. It closes when the parent
records the turn that consumes its result. A failed follow-up turn also closes
it, because the session records the failure as the decision for that result.
The session reports its open child runs in each TurnCompleted.
A headless run ends only on a completed turn that reports none. A background
shell job is not a child run.
Code anchors: TurnCompleted.OpenChildRunIds, ChildRunLifecycle,
HeadlessChannel
An agent event is a typed fact between the agents of one session, for example
"child approval requested". It has an envelope with a sender, a target, and a
send time. Only the session that owns a child run builds an event about that
run. An event never carries consent and never holds text that an agent wrote.
The model sees a notice that the runtime renders from events. Added by
child-approval-events-and-parent-pause (#2583).
Code anchors: AgentEvent, AgentEnvelope, AgentAddress,
AgentEventFactory, AgentEventRenderer (src/Netclaw.Actors/Sessions/AgentEvents.cs)
The child consent pause is the state of a whole session while any child
consent request of the session is open. The session refuses spawn_agent, and
automated input waits. The current turn can finish. A person's message starts a
turn, but it does not end the pause. No request expires. Only the close of
every open child request (an answer, a refusal, or a withdrawal) ends the pause.
Added by child-approval-events-and-parent-pause (#2583).
Code anchors: SessionToolWorkflow.IsChildConsentPaused,
SessionInputFlow.MoveHeldInputBehind, LlmSessionActor.StartInputsHeldByThePause
A parked child run is a child run that waits for consent with no actor. The
parent run record holds its park (the conversation, the loop guard, the working
directories, the file activity, and the skill overlay), its consent requests,
and their answers, so the session journal and the snapshot keep it across a
restart and passivation. When every parked request has an answer, the session
records the resume and starts a new child from the park, under the authority of
the run record, and runs only the parked calls, each once
(durable-child-consent-wait and durable-child-park-recovery, #2572).
A parked run can hold zero consent requests. This is a drain park: a child that
ran at a graceful drain stopped at a safe point, after its tool batch or in
place of its model call. A drain park asks nobody. The session resumes it after
the restart, and the new child starts with a model call
(running-child-drain-park, #2655).
Code anchors: ChildRunLifecycle.Parked, ChildRunEvent.Parked, ChildRunEvent.Resumed, ChildParkRules
A child journal is the Akka.Persistence journal of one child run, with the
persistence ID subagent-{escaped session ID}/{run ID}. A run writes it at its
first park only, so a run that never parks has none. Its first event freezes
the system prompt, the resolved provider and model, the tool set, the project
instructions, the operating rules, and the findings flag. The parent purges it
last: after the run end, result.md, and the result notice, with a closing
event and then a delete of all messages. Match the prefix of one session with
an ordinal comparison, because the escaped ID can hold %. Planned in PR 3 of
child-approval-events-and-parent-pause (#2572). This part is not on dev yet.
Code anchor (planned): SubAgentRunProtocol
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
Text admission occurs when the daemon journal stores an InputAdmitted record.
It preserves the input and its original authority before the model completes a turn.
It does not grant tool permission or confirm model completion.
Code anchors: LlmSessionActor.AdmitInput, SessionRegistry.SendMessageAsync
Delivery is unconfirmed when a dispatched request has no reliable admission response. The input may already exist in the daemon journal. The client must check the session before it resends that input.
Code anchors: ChatClientActor, ChatCloseReceipt
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
The Operator is the person who runs a Netclaw host and answers its consent requests. This entry defines the person. The Operator principal entry defines the value that the daemon gives to a request.
The Operator principal is the PrincipalClassification.Operator value in the
claims of an authenticated request. It states that the request has the authority
of the Operator. A local-trust scheme or a paired device gives the
value. The daemon gives it to a loopback request in local
exposure mode only after the Host and Origin test passes.
Code anchor: PrincipalClassification.Operator
A loopback request reaches the daemon from a loopback source address
(127.0.0.0/8 or ::1). The source address alone does not prove that the
Operator made the request, because a web page in the Operator's browser can
reach the same address. The daemon also checks the Host and Origin headers.
Code anchor: LoopbackAuthenticationHandler
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 reminder tombstone is the durable record of an ended one-shot reminder.
The reminder manager writes it before it deletes the definition.
It keeps the id, the title, the audience, the fire time, the outcome, the end time, and the last error.
A tombstone with the outcome Failed also keeps the reminder prompt. No tombstone keeps the delivery target, and a tombstone never runs.
The audience gates every history and status read of the ended reminder, and the read of the prompt.
The manager deletes the history and then the tombstone 12 days after the end time.
Code anchors: ReminderTombstone, ReminderManagerActor, ReminderDefinitionStore
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
-> return "path: <absolute path of that file>", then the file contents
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 the operator's consent act for a call that requires consent. The operator gives a consent answer. Approval is one input to authorization. It is not the same as schema exposure.
Do not use "approval" for the consent mode (ApprovalPolicy in config), for a
stored grant, or for the whole authorization gate. Use
consent mode, grant, and "authorization". The code
names ApprovalPolicy, ToolApprovalActor, and IsApproved stay as they are.
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
These terms name the stages and parts of tool authorization. The tool authorization architecture shows which context owns each term. Each term has one meaning. The table under each term maps the term to current code names. This glossary does not rename code.
An audience is the trust level of the person or system that talks to Netclaw:
Personal, Team, or Public. The audience selects a tool profile and a
consent mode. Do not call an audience a "trust".
Code anchor: TrustAudience
A requester is the person or system that asks for an action in a session. Six facts identify a requester: the session, the audience, the trust boundary, the channel type, the sender ID, and the principal classification.
A requester is not the full turn authority. The turn ID, provenance, delivery targets, and adopted context belong to one message. They can change between turns of the same requester. Work that a requester starts, such as a child run, belongs to that requester in each later turn.
The consent answer check (ApprovalButtonValueCodec.CanApprove) is different.
It compares only the sender ID of the answer with the recorded requester sender
ID. It lets any sender answer when the requester principal is
VerifiedAutomation or when the recorded requester has no sender ID.
Example:
Alice starts a child in turn 1 (quotes thread context)
Alice asks for status in turn 2 (no quoted context) -> same requester, allowed
Bob asks for status in the same thread -> other requester, denied
One exception covers child status and cancel. A reminder turn (principal
VerifiedAutomation, source kind reminder, transport authenticity
LocalProcess) and any other turn of one session manage each other's child
runs. The other turn can be a person turn or an automated turn, such as the
delivery turn of a background job. A webhook turn can carry the source kind
reminder, but it has the authenticity Verified, so it is not a reminder turn. When the requester or the turn that started the
run is a reminder turn, the check ignores the sender ID and the principal
classification. It still requires the same session, audience, trust boundary,
and channel type.
An operator starts a child in a TUI session
A reminder fire in the same session asks for status -> allowed
A reminder fire starts a child; the operator asks -> allowed
A background job delivery turn asks for that status -> allowed
A reminder fire in another session asks for status -> denied
A webhook with the event header "reminder" asks -> denied
Alice starts a child; Bob asks (both people) -> denied
Code anchors: TurnContext.HasSameRequester, TurnContext.CanControlChildRunOf,
ApprovalButtonValueCodec.CanApprove
A consent mode states what a tool call needs before it runs, per audience and
tool: Auto (no consent), Approval (operator consent), or Deny (never).
The configuration key is ApprovalPolicy and stays so.
Code anchors: ToolApprovalMode, ToolApprovalConfig
A candidate is one unit of a tool call that needs coverage. A shell call has one candidate per command occurrence. A non-shell tool has one candidate: its tool name.
Code anchors: ApprovalCandidate, ShellPolicyCandidate
Coverage is the reason that a candidate needs no prompt: a one-time consent, a chat grant, a persistent grant, reviewed-safe policy, or an approval-exempt output command. A call can run without a prompt only when every candidate has coverage.
Code anchors: ShellCoverageKind, ToolAllowReason
A grant is a stored operator consent. A chat grant lives in memory for one
session. A persistent grant lives in tool-approvals.json. A grant applies
only to the audience and tool that it names.
A one-time consent is not a grant. An MCP server or tool allow list is not a
grant; it is audience profile data. McpServerToolGrants and GrantCategory
keep their code names.
Code anchors: ApprovalEntry, ToolApprovalGrant, ToolApprovalStore
A grant scope states where a grant applies: this chat, one folder, one Git repository, or everywhere. "Scope" in new prose means a grant scope only. Use "boundary" for a filesystem check, "run" for a run context, and "project directory" for a project declaration.
Code anchors: ApprovalGrantScope, ApprovalEntry.Directory,
ApprovalEntry.Repository
A one-time consent lets the exact blocked call run once. Netclaw stores nothing. The retry passes every check again.
Code anchors: OneTimeApprovalKeys, ToolApprovalAttempt
A consent request asks the operator to answer for the uncovered candidates of one call. It carries the options that the operator can choose and a display text with secrets removed.
Code anchors: ToolApprovalContext, ToolInteractionRequest
A consent answer is the option that the operator chooses: once, a grant with a scope, or a refusal. Do not call it a "decision".
Code anchors: ApprovalDecision, ParentApprovalDecision,
ApprovalOptionKeys
A decision is the authorization outcome of one call: allowed, requires consent, requires correction, or denied.
Code anchors: ToolAuthorizationDecision, ToolAuthorizationOutcome
Policy data is configuration that authorization reads: audience profiles,
consent modes, deny rules, the reviewed-safe catalog, and protected paths.
Name an evaluator class after its context, not "policy", in new prose. Current
class names such as ToolAccessPolicy stay.
A phrase is the display and match unit of a shell candidate, for example
git status. A stored shell grant stores phrase tokens.
Code anchors: ApprovalCandidate.Verb, VerbTokens, ApprovalPhrase
A pattern is a glob path pattern only. Use phrase for a shell
display or match unit and "deny rule" for a hard-deny entry. The code names
Patterns, HardDenyPatterns, and DenyPattern stay.
Code anchor: PathPattern
A deny rule forbids a command or a path whatever consent exists. No operator answer can override a deny rule.
Code anchors: HardDenyRule, ShellCommandPolicy, ToolPathPolicy
Unresolved syntax is a shell fact: the parser cannot prove the full effect of a command, for example a dynamic command name. A call with unresolved syntax can get only a one-time consent. A non-interactive run denies it. Do not use the word "messy" in new prose.
Code anchor: IsMessy
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, worktree, log, and child-run areas. On Windows it also contains the temporary areas. On Linux and macOS the managed temporary directory is outside the envelope. 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 (Windows only)
├── worktrees/ # managed source worktrees
├── logs/session.log # raw parent log
└── subagents/<run-id>/
├── artifacts/
├── tmp/ # Windows only
└── 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. Each run receives a different directory.
- On Linux and macOS it is
<base>/<key>/pfor a parent and<base>/<key>/c<h>for a child. The base is/tmp/netclaw-<uid>(/private/tmp/...on macOS). All runs of one session share the key folder<base>/<key>. - On Windows it is inside the session storage envelope.
Netclaw sets TMPDIR, TMP, and TEMP to this directory for child processes.
The directory is not a project scope. Its key folder is an implicit trusted root
of its session for every audience. The base is not a root.
Code anchors: ManagedTemporaryLocation, ManagedTemporaryLayout,
ManagedTemporaryEnvironment
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 tool-authorization capability owns the trusted-root interpretation and
the filesystem authorization decision. Session and cwd capabilities only supply
roots and candidate paths. "Trust" in new prose means a trusted root only. Use
"audience" for TrustAudience.
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 each file under the config directory except
secrets.json and the webhook route files, for example netclaw.json and the grant store
tool-approvals.json (owner decision D6). It can be read through structured file tools when normal roots,
audience policy, and operation permissions allow it. A shell program that
only reads its operands can read it by its exact path (decision D6). Read
authority does not grant write, attach, or other shell authority.
Secret configuration belongs in protected stores such as secrets.json,
webhook route files, and key storage. Those stores and the database and process-control state remain
read-denied.
A canonical path is a fully qualified, normalized path with no unresolved dot
segments. Canonical form does not resolve links. A shell canonical path also
carries its path style (CanonicalShellPath). Canonical form does not by
itself grant access.
A resolved path is a canonical path after link resolution. Do not call a resolved path "canonical".
A resolved home path is the full path of a Netclaw home with no trailing separator and every link resolved,
one path component at a time, as realpath(3) does. A relative link target is joined to the folder that the
walk already resolved, so a .. in a target leaves that folder. A walk that follows more than 40 links fails.
HomeIdentity.Canonical returns it. The daemon and the CLI compare two home paths only through this form
(HomeIdentity.Same), so two different folders never compare as one home. The method name says "canonical"
for historical reasons. By the term "Canonical path" above, this value is a resolved path, not a canonical path.
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 tool-authorization 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, the path access decision starts
(tool-authorization).
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.
A thinking level is the provider-neutral thinking depth of a model
definition: Off, Low, Medium, High, or Max. Max is the highest
level that the provider offers. An unset level means the model's default. A
call site can set its own level, and that level wins.
Code anchor: ThinkingLevel (Netclaw.Configuration).
A thinking dialect is the wire form that a provider uses for a thinking level and for the reasoning suppression intent. It states the levels that the wire can send. Netclaw rejects a level that the dialect cannot send. It never sends a nearby level instead.
Native -> ChatOptions.Reasoning; the SDK writes the wire field
DeepSeek -> thinking.type + reasoning_effort (no medium)
ReasoningEffort -> reasoning_effort (no max)
ChatTemplateKwargs -> chat_template_kwargs.enable_thinking (off only)
OllamaThink -> think (no max)
None, Unresolved -> no level
The provider descriptor owns the dialect. An OpenAI-compatible provider reads
it from Providers:<name>:VendorOptions:ThinkingDialect.
Code anchor: ThinkingDialectMap (Netclaw.Providers).
A thinking capability is what a model accepts: Unknown, None, AlwaysOn,
or Controllable with a set of levels. A capability resolver or a provider
probe reports it. Netclaw offers a level only when the dialect can send it and
the capability includes it.
Example:
dialect DeepSeek, capability Controllable(all levels)
-> offered: off, low, high, max
-> medium: "the DeepSeek dialect cannot send medium"
dialect ReasoningEffort, capability Unknown
-> offered: off
-> low: "thinking support unknown for this endpoint"
Code anchor: ThinkingSupport (Netclaw.Configuration).