Harness tools and permissions

Tools and permissions

Harness separates what work was requested from whether that work may run. The daemon records tool work in the session; authorization applies to the individual tool leaf. The client can present a pending request and record a human decision, but does not execute the tool itself.

Status: Permission and tool behavior below is current as documented in the runtime and operator guides. docs/canon/proposals.md describes the current PEW/Proposal mechanism, not a draft design. Files under docs/working-proposals/ are design work; docs/runtime/approval.md is the current authorization authority.

What counts as a tool call?

A tool call emitted during a turn becomes an approvable leaf (a ToolCallJob / ApprovableJob). Examples include system tools, file mutation, MCP, web search/extract, and agent-related tool calls. Turns and programmatic jobs are containers; they are not the unit that receives the approval decision. Authorization fields live on the leaf.

The standard toolkit is the current inventory/reference for built-in tools. Plugin command files are a separate extension surface: their existence does not imply that a plugin can bypass daemon authorization or add a driver.

Authorization in brief

The policy result for a leaf can be:

• allow — permitted by the applicable rule.
• deny — denied by the applicable rule, but some cases can be covered by the configured permission mode or a human decision.
• block — hard denial; permission mode and human approval cannot lift it.
• ask — no decisive floor rule (or a defer rule); policy/mode determines whether it requires human attention.

The permission mode is manual, auto, or yolo. It governs the unresolved/remainder decision; it is not a replacement for policy and does not turn a hard block into an allow. SessionRoot.currentPolicy is the active session mode. The last-choice default comes from project policy when set, otherwise kernel config.json defaultPolicy; it is not a session key/value setting. New sessions inherit that default.

Mode	Mental model
manual	Unresolved work is handled through a human approval prompt.
auto	The auto classifier may decide eligible remainder; otherwise a prompt can still be needed.
yolo	Allows the eligible remainder rather than prompting; hard blocks still stand.

“Eligible remainder” matters: a policy allow is already allowed, a block is never coverable, and mode does not erase the policy result. Do not treat these modes as permission to bypass platform or tool-specific rules.

Human approvals and remembered reads

When a human decision is needed, the client writes approved on the pending leaf. Approval is not a separate job. A human-approved file read can also add the prepared path to the session read allowlist; later reads of that path and descendants may avoid another prompt during that session. This is a read allowance, not a write grant, and it does not lift a hard block.

Extra-root access and file operations have more specific rules than this overview. Consult docs/runtime/approval.md before inferring whether a particular path or operation is approvable.

Safe mental checklist

1. Identify the specific tool leaf, not just the turn or transcript line.
2. Check the policy result (allow, deny, block, or ask).
3. Apply the active mode only to eligible remainder; never assume it overrides block.
4. If the daemon asks, the human decision is recorded on that leaf.
5. Distinguish a remembered read path from write permission.

Source paths

Paths are relative to the Harness repository root:

• docs/canon/standard-toolkit.md — standard tool inventory and semantics.
• docs/canon/grain.md — tool/job geometry and durable authorization fields.
• docs/runtime/approval.md — authoritative LICENSE WHEN and authorization rules.
• docs/runtime/README.md — map to runtime approval and control-effect references.
• docs/client/operate.md — operator permission modes and approval interaction.
• docs/plugins/install.md, docs/plugins/commands.md — plugin enablement and command boundaries.
• docs/canon/proposals.md — current PEW/Proposal mechanism (distinct from working design proposals).