mosaicstack/stack
6
0
Fork 1
Code Issues 297 Pull Requests 19 Actions Packages Projects Releases 15 Wiki Activity

Hook enforcement: deny file creation in fleet-agent /var/home/jason.woltje root (scratch/work/notes convention) #1289

New Issue
Open
opened 2026-08-17 20:34:54 +00:00 by Ghost · 0 comments
Ghost commented 2026-08-17 20:34:54 +00:00
Copy Link
Copy Source

Summary

Mechanical enforcement for agent home hygiene: agents MUST NOT create files in the root of their $HOME (~/.mosaic/fleet/agents/$MOSAIC_AGENT_NAME/). Root holds identity files only (SOUL.md, README.md); scratch/temp/work output belongs in scratch/, work/, notes/.

Prose-level rule ships in the generic SOUL.md template (parent issue #1288, comment 22990). Per the Constitution ("Hooks are the gate" — a checkable rule belongs in a hook, not only instructions), this needs mechanical denial.

Enforcement spec

Deny file-creation tool calls (write/edit/mkdir equivalents) where the resolved target path is inside the agent home root directory itself — not its subfolders. Paths must be resolved (symlinks, .., relative) before matching. Creating the standard subfolders is allowed; writing to existing identity files (SOUL.md, README.md) stays allowed. Denial message must state the rule and the correct subfolder.

Agent home root derives from $MOSAIC_AGENT_NAME (launcher-exported; see #1288 G4). If unset, the check is a no-op for that session (nothing to protect) — but the launcher must fail closed on unset, per #1288.

Per-harness mechanism

Harness Mechanism Precedent in tree
pi extension intercepting write/edit tool calls (spawnHook / tool-call interception) runtime/pi/mosaic-extension.ts, goal-extension.ts
Claude Code PreToolUse hook denying Write/Edit runtime/claude/hooks-config.json, prevent-memory-write.sh (same pattern: rule alone proved insufficient, hook is the gate)
OpenCode plugin / permission hook adapter work, ties to #1288 G5
Codex exec-tool env / sandbox rule if no hook API exists — else capability-stated absence adapter work, ties to #1288 G5

Where a harness offers no interception point, the adapter must state the absence explicitly (capability-verb contract) rather than silently relying on prose.

Out of scope

  • Installer scaffolding of subfolders (#1288 item 2 / comment 22990)
  • Moving env files out of the flat fleet/agents/ root (#1288 item 6)
  • Global ~/.mosaic/ root hygiene (separate concern; fleet agents' homes only here)

Refs #1288

## Summary Mechanical enforcement for agent home hygiene: agents MUST NOT create files in the root of their $HOME (`~/.mosaic/fleet/agents/$MOSAIC_AGENT_NAME/`). Root holds identity files only (`SOUL.md`, `README.md`); scratch/temp/work output belongs in `scratch/`, `work/`, `notes/`. Prose-level rule ships in the generic SOUL.md template (parent issue #1288, comment 22990). Per the Constitution ("Hooks are the gate" — a checkable rule belongs in a hook, not only instructions), this needs mechanical denial. ## Enforcement spec Deny file-creation tool calls (write/edit/mkdir equivalents) where the resolved target path is inside the agent home root directory itself — not its subfolders. Paths must be resolved (symlinks, `..`, relative) before matching. Creating the standard subfolders is allowed; writing to existing identity files (`SOUL.md`, `README.md`) stays allowed. Denial message must state the rule and the correct subfolder. Agent home root derives from `$MOSAIC_AGENT_NAME` (launcher-exported; see #1288 G4). If unset, the check is a no-op for that session (nothing to protect) — but the launcher must fail closed on unset, per #1288. ## Per-harness mechanism | Harness | Mechanism | Precedent in tree | |---|---|---| | pi | extension intercepting write/edit tool calls (spawnHook / tool-call interception) | `runtime/pi/mosaic-extension.ts`, `goal-extension.ts` | | Claude Code | PreToolUse hook denying Write/Edit | `runtime/claude/hooks-config.json`, `prevent-memory-write.sh` (same pattern: rule alone proved insufficient, hook is the gate) | | OpenCode | plugin / permission hook | adapter work, ties to #1288 G5 | | Codex | exec-tool env / sandbox rule if no hook API exists — else capability-stated absence | adapter work, ties to #1288 G5 | Where a harness offers no interception point, the adapter must state the absence explicitly (capability-verb contract) rather than silently relying on prose. ## Out of scope - Installer scaffolding of subfolders (#1288 item 2 / comment 22990) - Moving env files out of the flat `fleet/agents/` root (#1288 item 6) - Global `~/.mosaic/` root hygiene (separate concern; fleet agents' homes only here) Refs #1288
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
fargo fred happy jason.woltje (Jason Woltje) merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) pepper rev-code-01 rev-code-02 rev-security-01 rev-security-02 sanity scooby (Scooby) scrappy shaggy tiny velma vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1289