Harness Overview

The harness is Polygent Code, the built-in agent runtime that runs every session; operators choose the model and control the context, tools, delegation, and safety policy available to it. For model credentials and availability, see Models & Backends.

Core capabilities

The harness combines the controls that determine what an agent can know and do.

Capability	Operator use
Skills	Publish reusable instruction packs and restrict which sessions can load them.
Subagents	Define named helpers with bounded models, tools, and MCP access.
MCP Server	Expose approved Polygent tools and connect external MCP servers.
Memory	Preserve workspace knowledge across sessions.
AI Cost Budgets	Apply global, workspace, and ticket cost limits.
Tool controls	Limit file, command, web, skill, subagent, and MCP capabilities by session source.
Bash policy	Block critical destructive actions, then apply administrator and repository rules.

The harness pages are under Developer Tools → PolygentCode (tabs: Settings, User Settings, Permissions, Skills, Subagents). MCP servers are under Developer Tools → MCPs.

User settings

User settings are installation-wide defaults for context loading, delegation, web access, and guard behavior in every Polygent Code session.

Open Developer Tools → PolygentCode → User Settings. The tab requires administrator access or Manage PolygentCode User Settings. Despite the name, the values apply to all users.

Context loading

Context loading controls which sources are added to the agent's context automatically.

Setting	Default	Effect
Repository instruction files	On	Loads AGENTS.md / CLAUDE.md project memory files from the repository. See project memory files.
Workspace memory	On	Loads the host-level global memory files (~/.config/polygent/AGENTS.md, ~/.claude/CLAUDE.md) of the account running the session host. Memory stores are not loaded automatically; agents reach them through the memory tools.
Selected skills	On	Exposes the skills selected by the session source. Off exposes no managed skills.

Capabilities

Capability defaults control delegation and web retrieval; stricter restrictions elsewhere still win.

Setting	Default	Values and effect
Built-in subagent behavior	Auto-assign by session type	Auto-assign by session type (sessions that can edit files get general, others get explorer), Always expose general, Always expose explorer, or Do not expose built-in subagents by default (also hides custom subagents).
Custom subagents by default	Off	When on, custom subagents selected by the session source are exposed.
Web access behavior	Allow	Allow direct web retrieval, Ask first, or Block. There is no interactive approval prompt: with Ask first the web tool returns an "approval required" error, so it behaves like Block. Use Block when outbound web access is prohibited.

Safety

Safety settings determine how untrusted content and large operations are handled.

Setting	Default	Values and effect
Read/write guard strictness	Standard	Standard refuses the first overwrite of an existing file the agent has not read and allows a deliberate retry; Strict always refuses it.
Prompt-injection guard behavior	Warn	Warn marks suspicious instructions found in file, web, command, or search output as untrusted; Block withholds that output from the agent. Defense in depth, not a substitute for least privilege.
Large-read behavior	Truncate near context limit	Truncate near context limit, Always truncate large reads, or Refuse large reads near context limit.

Subagents inherit the parent session's read/write guard, prompt-injection guard, and web-access behavior.

Tool and MCP scoping

Tool scoping limits the capabilities exposed by bots, templates, automations, subagents, and AI jobs.

• An explicit empty selection means none.
• A non-empty selection exposes only the selected entries.
• For skills, Unrestricted (all enabled skills) exposes every enabled skill.
• Built-in subagents may still be available according to Built-in subagent behavior and the parent session's capabilities.
• The workspace capability ceiling can only reduce a session's effective capabilities.

Grant command execution, file writes, web access, and write-capable MCP tools only to trusted session sources.

Bash command policy

The harness checks every shell command against three layers before it runs; a blocked command never starts and the agent receives the reason.

1. Built-in safety floor — always rejects destructive root operations, execution of downloaded or dynamically generated scripts, and ambiguous shell constructions, including when hidden behind environment wrappers or nested shells. It cannot be disabled.
2. Administrator denylist — Developer Tools → PolygentCode → Permissions → Blocked Bash Commands (view with View Settings, save with Manage Settings). Applies to every session in every workspace.
3. Repository rules — permissions.deny entries in .claude/settings.json and .claude/settings.local.json in the working copy, and ~/.claude/settings.json of the host account.

Administrator pattern	Example	Behavior
Substring	git stash	Case-insensitive match anywhere in the command.
Glob	git stash*	* and ? wildcards, matched anywhere in the command (not anchored).
Regular expression	/^rm\s+-rf/	Case-insensitive; an invalid expression is rejected on save, and an expression that takes too long to evaluate blocks the command.

Repository rules use the native forms Bash, Bash(*), Bash(prefix:*), Bash(prefix *), and Bash(exact command); they are case-sensitive, only deny is read (allow and ask are ignored), and each part of a compound command (&&, ;, |) is checked separately. A malformed repository settings file blocks all Bash commands in that session until it is fixed.

Rules are global; there are no workspace-level Bash rules. Remove Bash from the tool selection when a session does not need a shell.

Guard escalation

Repeated blocked actions stop the run and ask a human instead of letting the agent retry indefinitely.

When the agent's actions are denied by guards or Bash policy 3 times in a row, or 20 times in one run, the session stops and waits for the user. Tune with Harness:DenialEscalationMaxConsecutive and Harness:DenialEscalationMaxTotal (0 disables) in the API and Session Worker configuration. Tool-loop detection separately warns the agent about repeated identical actions and then blocks them.

Context management

When a conversation approaches the model's context window, the harness trims older tool output and summarizes earlier history automatically so the session can continue. There is no UI setting. Harness:CompactionModel can name a lower-cost model for the summary. If a session repeatedly loses important context, reduce large inputs, choose a model with a larger window, or use Reset Context with a focused message.

MCP network boundary

The built-in MCP endpoint is an authenticated agent integration surface; every call carries a temporary credential issued for one run. Keep /mcp reachable only from the API and Session Worker networks and require TLS. See MCP Server security.

Troubleshooting

Use this sequence to isolate common harness configuration failures.

Symptom	Check
A custom subagent is missing	Custom subagents by default is off by default; enable it, select the subagent in the session source, and check the capability ceiling. Start a new session.
A skill is missing	Confirm it is enabled, selected (or unrestricted), Selected skills is on, and the capability ceiling permits it. Start a new session.
A tool is unavailable	Check the session source's tool selection, the capability ceiling, User Settings, and subagent tool selection. An explicit empty selection allows no tools.
Every Bash command is rejected	A repository .claude/settings.json is malformed, or a Bash / Bash(*) deny rule exists. Read the reason in the tool result.
A specific Bash command is rejected	Review the reason, the administrator denylist, and repository permissions.deny rules.
Web retrieval is unavailable	Web access behavior is Ask first or Block, or the web tool is not in the effective tool selection.
Session stops and asks for help	Guard escalation triggered after repeated denied actions; review the denials, adjust policy or instructions, and continue.
The agent loses earlier context	Reduce large inputs, select a model with a larger context window, and review Large-read behavior.
A remote worker cannot use Polygent MCP tools	Verify McpUrl is valid and reachable from the worker, and that the proxy forwards the Authorization header.
A run stops unexpectedly	Check session messages, system logs, and budget enforcement.