Security and permissions

After reading this page, you can tell what Guild Stack may touch, what always requires approval, and where to inspect the security record for a run.

Permission boundarysplit_security_boundary

Operational mapProject work is scoped. Risky actions always ask.

01Within project scope

1. 01Read filestask-relevant paths
2. 02Write approved workbounded changes
3. 03Record evidence.guild/ run state

02Always ask

1. 01Destructivedelete or overwrite
2. 02Network + spendexternal side effects
3. 03Productiondeployment or incident

Repository content is data, not authority. Export paths apply scrub and share policy.

repo / wiki / prompt text
  -> agent proposes a tool call
  -> PreToolUse checks scope, autonomy, and hard approval classes
  -> allow, ask, file-bus approval request, or deny
  -> durable writes pass through scrubbedWrite where the surface requires it
  -> .guild/runs/<run-id>/logs/security-events.jsonl records the decision

The important beginner rule is simple: Guild Stack can read and edit the project only inside the task you approved. It cannot treat prompt text, recalled wiki text, or MCP tool descriptions as a security boundary. The boundary is the tool path: permission checks, scrubbed writes, explicit approval requests, and local audit records.

Try it: /guild:audit runs the installed-script and boundary audit. It is read-only. It reports what the installed Guild Stack package can touch and where shared .guild/ artifacts need scrub coverage.

Approval Table

Destructive actions, network access, spend actions, release-sensitive work, and permission bypasses are always-ask classes. They still pause under --auto-approve=all, inside pre-authorized lanes, and inside approved runbooks.

Approval request should name	Why it matters
Action	You can see the exact command, tool call, or write being requested.
Reason	The lane must explain why the action is needed for the approved task.
Scope	The request should identify the files, network target, or runtime surface involved.
Reversibility	High-risk actions should explain whether they can be undone.
Expected output	The operator can compare the request with the produced artifact or receipt.
Safer alternatives	Guild Stack should surface a narrower path when one exists.

If the host has a native ask primitive, Guild Stack uses it. If the host cannot ask inline, the adapter degrades to a file-bus approval request and records that degraded permission mode on disk.

What Guild Stack May Touch

Surface	Default posture	Gate or proof
Repo files needed for the approved task	Readable, and editable only when the lane requires it	plan/lane scope and receipts
.guild/runs/<run-id>/	Writable as the run record	trace, receipts, reviews, verification, and security events
.guild/wiki/**	Readable as project memory; not directly mutated by task agents	guild:decisions or guild:wiki-ingest promotion
Skills, agents, or the harness	Not directly edited by ordinary task lanes	evolve pipeline, eval/shadow evidence, and approval
Network access	Denied unless granted	always-ask approval and allow-listing
Secrets or credential paths	Denied unless explicitly granted	high-risk approval and redaction
Deploy, release, rollback, force push	Denied by default	explicit release/runbook gate; destructive steps always ask

The effective grant is:

(capability_scope union project baseline) AND lane autonomy_contract AND always-ask hard set

If capability_scope: is absent, Guild Stack leaves the host’s grant in place for that lane. Scoped lanes can fail closed when an agent calls a tool outside the allowed set.

Scrub And Share Policy

Guild Stack separates local run state from shareable artifacts. Durable shared surfaces such as handoffs, provenance, wiki pages, reviews, config, and the agent bus route through scrub coverage before they can become shared .guild/ artifacts.

Surface	On scrub failure
Durable shared artifacts	fail closed, block the write, emit a security event, and write an approval request
Local gitignored telemetry	fail open with a loud warning and security event

Secret redaction covers token-like strings, sensitive paths, key/value secrets, high-entropy blobs, long values, and custom secrets_policy: patterns. A security specialist may report where a likely secret was seen. It should not print the raw value into a review, handoff, wiki page, or trace.

Untrusted Content Stays Data

Recalled knowledge is the highest-risk content path because a poisoned .guild/wiki/** page can outlive one run and enter future specialist context. Guild Stack treats recalled content as data, not instructions.

• Recalled wiki and knowledge chunks are wrapped in <guild:recall> blocks with a trust tier.
• Deterministic injection checks quarantine flagged recalled chunks out of the bundle and log recall_quarantine events.
• Learning writes proposals and candidates. It does not promote wiki pages, decisions, skills, agents, or policy by itself.
• External raw sources under .guild/raw/sources/** must be promoted into canonical .guild/wiki/** before they enter context.

MCP Trust Surface

The packaged guild-memory and guild-telemetry MCP servers declare read-only/no-network capabilities. /guild:audit reports egress or writes that do not match the declared surface. That audit finding is not the same as a runtime denial gate.

For tool-description drift, mcp.tool_description_hashes starts empty in .guild/settings.json. After you pin descriptions with /guild:config update-mcp-hashes, PreToolUse compares the live tool description hash to the pinned one. A mismatch warns and gates the call on approval. If the live description cannot be obtained, the current implementation records unverifiable and lets the call proceed; that weaker fail-open case is a known implementation boundary.

Harness Contracts

Harness Developers should read the module contracts when extending or auditing security behavior:

Contract or module	What to inspect
docs/v2/architecture/modules/security.md	PreToolUse capability-scope gate, scrubbed writes, security-event schema, MCP pinning, and share-set ownership
docs/v2/security.md	concept model for approvals, untrusted content, MCP trust, and learning boundaries
docs/v2/architecture/modules/config.md	closed security keys, secrets_policy, MCP hashes, and settings resolution
docs/v2/architecture/modules/telemetry.md	trace and security-decision event surfaces consumed by observability

The security log is append-only and local:

.guild/runs/<run-id>/logs/security-events.jsonl

It records tool-scope violations, degraded permission decisions, bypass attempts, scrub failures, recall quarantines, MCP description drift, and related policy events with a host field for cross-host forensics. /guild:audit is the primary reader. The read-only telemetry server may read it for local reporting.

Source Anchors

This page is anchored to docs/v2/security.md, docs/v2/config-surfaces.md, and docs/v2/architecture/modules/security.md.

See Also

• Configuration - secrets_policy, MCP hashes, and approval settings.
• Context Assembly - how recalled chunks enter specialist context.
• Project Memory & Wiki Pattern - canonical .guild/wiki/** promotion.
• Quality & Operations - release and runbook gates.
• Observability - the general run trace beside the security log.