Levandor

Obsidian Subagent Improvements (Permission Fix + LOG/TOPICS Convention)

4 min read

Three coordinated changes to the Obsidian subagent system: fixed a long-standing permission bug that caused silent write failures, introduced per-project LOG.md / TOPICS.md index files for faster context retrieval, and recorded follow-ups for vault hygiene.

For Agents

If you are the obsidian-documenter or historian subagent, the conventions described in this note are the source of truth. Read this before changing your own behavior.

1. Writer Permission Fix

The obsidian-documenter subagent had been silently failing on writes for an extended period. Symptom: spawned, did the work, then hit "Permission to use Write/Edit/Bash has been denied" and fell back to dumping markdown to the parent agent for manual saving. Investigation surfaced three distinct denial sources, each requiring its own fix.

Three Denial Sources (read this before debugging future permission issues)

  1. Compound git commands — cd /vault && git X never matched any allowlist pattern. Claude Code’s Bash matcher checks the start of the command. Here the command starts with cd, not git, so no Bash(git ...:*) rule could ever match.
  2. obsidian CLI not allowlisted anywhere — the entire CLI was being denied even though it is the documented preferred tool.
  3. Vault Write/Edit rules in the wrong settings file — Write(/Users/levander/levandor_obsidian/**) and the matching Edit(...) rule existed only in ~/.claude/settings.local.json. That file does not reliably propagate to subagents, and being machine-local, the second Mac was completely broken.

Fix Applied

Permissions consolidated into the user-global ~/.claude/settings.json (which propagates to subagents and syncs across machines via dotfiles):

"permissions": {
  "allow": [
    "Write(/Users/levander/levandor_obsidian/**)",
    "Edit(/Users/levander/levandor_obsidian/**)",
    "Bash(git -C /Users/levander/levandor_obsidian:*)",
    "Bash(obsidian:*)"
  ]
}

Subagent definitions refactored:

  • historian.md and obsidian-documenter.md git commands changed from cd /vault && git X to git -C /vault X. The new form starts with git, so it cleanly matches Bash(git -C /Users/levander/levandor_obsidian:*).
  • Multi-step commit/push split into separate Bash calls so each independently matches the allowlist pattern.
  • New rule added to obsidian-documenter’s <communication> section: never fall back to printing content for the parent to save when a permission denial occurs. STOP and report via SendMessage instead. The fallback behavior masked the bug for months.

Verified

Spawned a fresh obsidian-documenter probe after the changes. All three patterns succeeded with zero denials:

  • git -C /Users/levander/levandor_obsidian status
  • obsidian vault="levandor_obsidian" read file="..."
  • Write to a path under the vault

2. Per-Project LOG.md and TOPICS.md Convention

Goal: give the historian faster recency and theme context when picking up past work in a project, without forcing it to scan every note.

File Specs

projects/<project>/LOG.md — reverse-chronological session log.

  • Newest dates at top using ## YYYY-MM-DD headings.
  • One bullet per piece of work, each linking to the canonical note via wikilink.
  • Cap at 50 date entries; older entries roll into LOG-ARCHIVE-YYYY.md.

projects/<project>/TOPICS.md — living theme index.

  • ## <Topic> headings, alphabetical.
  • Bullets are wikilinks to notes belonging to that theme.
  • A single note can appear under multiple topics.

Maintainer Behavior

AgentAction
obsidian-documenterWrites to both files as part of every project documentation pass, before the commit/push step. Appends a new entry to LOG.md and updates the matching theme(s) in TOPICS.md.
historianAt bootstrap, when a project is identified, reads the top ~15 entries of LOG.md and the full TOPICS.md in addition to the project’s agent context file.

Dev-setup is NOT a project

dev-setup/ does not get LOG.md / TOPICS.md. The convention is for projects/<project>/ only. This very note is dev-tooling work and intentionally does not touch any project’s index files.

Files Updated

  • obsidian-documenter.md gained a <log_and_topics> section with the spec and scaffolds.
  • historian.md bootstrap step 3 expanded to read LOG.md / TOPICS.md alongside agent context.
  • Agent Landing.md got a new “Per-Project Index Files” section and the directory tree was updated.

Scaffolded Across All Projects

LOG.md and TOPICS.md were created (empty scaffolds with frontmatter) for all six project folders:

  • projects/alpiq-bess/
  • projects/facekom/
  • projects/levandor-crm/
  • projects/ai-trading/
  • projects/eu-hu-tender-scraping/
  • projects/networker/

Future documenter runs will populate these organically.

3. Known Follow-Ups (Recorded, Not Fixed Today)

Vault hygiene debt

These were observed during this work but intentionally left for a separate change set.

  • .obsidian/workspace.json is git-tracked — Obsidian rewrites it constantly. Every documenter run hits cannot pull with rebase: You have unstaged changes on the pull step. Not blocking (writes still succeed because the working tree resolves cleanly), but noisy. Should be added to vault .gitignore and git rm --cached’d.
  • Stale entries in settings.local.json — lines 102-103 still hold the old Write(/Users/levander/levandor_obsidian/**) and Edit(...) rules. Harmless duplicates of what’s now in settings.json. Can be cleaned up later.
  • Agent Landing — vault structure and the new “Per-Project Index Files” section reflect this work

Graph View