💡 Workspace Trust Gate: Avatar Folder Safety Check Against Planted Agent Instructions and Hooks

[github-actions[bot]]

Summary

The first time a user opens a folder, TalkTerm should check it (and its parent directories) for agent configuration that third parties can plant: .claude/settings.json hooks, CLAUDE.md and .claude/rules/, skills and commands, .mcp.json, AGENTS.md. The avatar explains in plain language what it found ("This folder contains instructions written for AI assistants. One of them would run a program every time I edit a file. Should I ignore it?") and asks before trusting any of it. Alongside this, set the SDK's settingSources explicitly, so third-party instructions never load silently.

Market Signal

• The attack is in the wild: Forever Security captured a live attack using a malicious AGENTS.md planted in a Downloads folder to hijack Codex and Claude Code, steal tokens and install malware (timeline, Adversa Oct 2026 roundup).
• Desktop agents for non-technical users are a known target: PromptArmor showed Claude Cowork uploading a user's confidential real estate files to an attacker's account through instructions hidden in a .docx "skill" file, "at no point… is human approval required" (PromptArmor, The Decoder). Critics pointed out that telling regular users to "watch for suspicious actions" is not fair.
• More October 2026 evidence: Unit 42 documented web-based indirect prompt injection in the wild (Unit 42), and Salt Labs took over a Manus session holding a Gmail token with one email.
• SDK default behavior: "When you omit settingSources, query() reads the same filesystem settings as the Claude Code CLI: user, project, and local settings, CLAUDE.md files, and .claude/ skills, agents, and commands." Project settings include filesystem hooks, which are shell commands, and CLAUDE.md loads from "<cwd> and every parent directory" (SDK docs: Claude Code features). Claude Code's docs also say workspace trust verification is disabled in non-interactive mode, and whether project hooks are trust-gated there is undocumented (issue discussion).

User Signal

• PRD NFR8: file system access must be scoped to user-approved directories only.
• PR fix(agent): scope read-only tools and context files to the workspace #570 just hardened read tools and BMAD context loading so they stay inside the workspace. This idea covers the configuration-injection side of the same threat.
• src/main/agent/claude-sdk-backend.ts never sets settingSources (grep returns nothing in src/ or test/).
• The personas are non-technical people who will pick Downloads, a shared drive or an emailed project folder as their workspace.

Technical Opportunity

• One-line baseline: set settingSources explicitly in buildSdkOptions (e.g. [], or ['user'] only). TalkTerm already supplies its own context through systemPrompt.append, getMemoryContext and the readContextFile loader from fix(agent): scope read-only tools and context files to the workspace #570, so nothing the product depends on is lost.
• Workspace trust module (Security context): on first open, scan for known agent-config files, fingerprint them (path plus SHA-256), and persist trusted fingerprints through the storage layer. If a file changes later, ask again.
• Avatar dialogue: summarise each file in plain language (the model can summarise it as untrusted data, never executing it) and offer "Ignore these instructions" (default), "Use them", or "Show me".
• Audit trail: log trust decisions (security:workspace-trusted, security:workspace-config-ignored).
• Later: once the SDK is upgraded, add permissions.blockWritesOutsideWorkingDirectories (TS SDK 0.3.314) and the blockReadsOutsideWorkingDirectories exemptions (0.3.316) as defense in depth.

Assessment

Dimension	Score	Rationale
Feasibility	high	The baseline is one option. The scan and dialogue fit the existing Security and Overlay contexts.
Impact	high	Closes a direct path from planted files to command execution or instruction hijacking for the users least able to spot it.
Urgency	high	Attacks using exactly this vector were seen in the wild in 2026, and TalkTerm relies on an SDK default that loads project config.

Adversarial Review

Strongest objection: canUseTool already asks before write and execute tools, so this is redundant. A "trust this folder?" prompt is also friction that non-technical users will click through.

Rebuttal: Filesystem hooks and CLAUDE.md never go through canUseTool. Hooks run as configured commands, and CLAUDE.md shapes the model before any tool call happens, so it sits outside the permission layer TalkTerm built. The prompt only appears when agent config is actually present, which should be rare in ordinary document folders, so it does not train users to click through. The avatar explains what the file would do instead of showing a bare yes/no, and the safe default is to ignore. Even if the dialogue is dropped, setting settingSources alone is a near-zero-cost fix.

Suggested Next Step

1. Extend the real-SDK integration test from fix(agent): scope read-only tools and context files to the workspace #570: create a temp workspace with a .claude/settings.json hook that writes a marker file and a CLAUDE.md with a canary instruction. Assert that neither takes effect on the pinned SDK 0.2.83. (If the test fails, this is a security fix, not just a feature.)
2. Set settingSources explicitly and keep the test as a regression guard.
3. Write a quick-spec for the trust scan, fingerprint storage and avatar dialogue.