Files
gstack/docs/autoplan-guard-troubleshooting.md
T
garrytanandcapy-ai[bot] efed592e0b docs(autoplan): permission cards after a background reviewer, and where /autoplan keeps its files
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-10-08 08:08:28 +00:00

368 lines
15 KiB
Markdown

# /autoplan publication guard: troubleshooting
`/autoplan` installs a `PreToolUse` hook (`autoplan/bin/phase-publication-hook`)
at its phase boundaries. Before it lets a phase-entry `Read` or a reviewer
`Agent` dispatch run, it reads this session's own Claude Code journal
(`~/.claude/projects/<project>/<session>.jsonl`) and checks that the previous
phase's report was published as parent assistant text.
Every guard message names a **code**, the Claude Code version that wrote the
journal, and a link to the section below for that code. Include the code and
version when you report a problem. The guard's decision log (see
[The decision log](#the-decision-log)) holds the same information.
Each code has one of four dispositions:
| Disposition | What it means | What you do |
|-------------|---------------|-------------|
| Unverified allow | Claude Code left this call uncheckable. The call runs, with a visible warning. | Nothing, unless it keeps happening (then report it). |
| Fallback | Retrying cannot help. | Run the fallback below. |
| Corrective | One named action must happen first. | Take that action. |
| Transient | Something is still in progress. | Wait for the named thing, then continue. |
**The fallback** (printed in every fallback denial):
1. Run the reviews by hand: `/plan-ceo-review`, then `/plan-devex-review`,
then `/plan-eng-review`.
2. Or move to a fresh session and keep your work: `/context-save`, start a new
Claude Code session in the project (not `--resume`), `/context-restore`,
then `/autoplan <plan path>`.
There is no environment variable that turns the guard off.
## How a phase transition is published
Claude Code can write a tool call to the journal after the hook has already
run, and text in the same assistant message as a tool call can be invisible
to the hook. So the guard counts a phase report only when a later journaled
record follows it: a tool result, or a record from another assistant message.
The phase-close procedure therefore publishes each report in a message whose
only tool call is the Bash no-op `true autoplan-published <phase>` (it prints
nothing and needs no permission; Claude Code 2.1.292 asks for approval of a bare
`:` command, so the no-op is `true`), and makes the next phase's `Read` or `Agent`
call in a later message. Sessions that put the report and the next phase's
call in one message get one [`publication_unflushed`](#publication-unflushed)
denial naming that fix.
When Claude Code has not yet written the current call, the guard evaluates the
call from the hook payload instead (Claude Code's own parsed input), placed
after the last journaled record. The previous phase's report must still be in
the journal.
## Unverified allows
These states are caused by Claude Code, not by the model. The guard lets the
call run without a permission decision (Claude Code's own permission check
still runs), prints a warning to you that names the code, and logs the allow
with `disposition: "unverified"`. For that one call it does **not** check that
the previous phase's report was published.
> [autoplan] phase publication was NOT verified for this session (journal_lag): ...
<a id="unrecognized-shape"></a>
### `unrecognized_shape:<detail>`
The journal root has a shape the guard does not know, usually because Claude
Code changed its journal format. The guard reads the journal twice and allows
only when both reads agree. `unrecognized_shape:cwd_spelling` means the
journal's directory is the same folder as the project, spelled differently.
Please report the detail and version.
<a id="journal-lag"></a>
### `journal_lag`
Claude Code had not written the previous assistant message to the journal
(a tool in an earlier message still has no result, or an ancestor record is
missing) and did not catch up within 2 seconds.
<a id="rewritten"></a>
### `rewritten`
The journal bytes the guard had already read changed during one hook call:
a later read's sha256 of bytes [0, first size) differs from the first read's,
or a record pass two reloads no longer parses to the record pass one indexed.
Claude Code normally only appends, and appends never fail a read. Rewrites
between hook calls are not detected (an accepted limit).
<a id="too-large"></a><a id="journal-too-large"></a>
### `too_large`
A single journal record is over the 32 MiB record limit (`OWNED_RECORD_MAX_BYTES`).
The guard reads long journals record by record, so a large journal alone
never triggers this; one enormous record (for example a huge pasted file) does.
A record still being written (no newline yet) is not read at all.
<a id="unseen-version"></a>
### `unseen_version`
A Claude Code release newer than the one gstack has checked passes the hook a
reviewer dispatch without a key the journal has (a schema strip). The daily
`autoplan-schema-canary` case catches these within a day of a release.
## Fallback denials
<a id="competing-root"></a>
### `competing_root`
The journal has more than one conversation root, or two records share one UUID.
<a id="foreign-cwd"></a>
### `foreign_cwd`
The journal's root was written in another project directory, after spelling
and symlinks are taken into account. Linked git worktrees of the project are
accepted.
<a id="sidechain"></a>
### `sidechain`
The first turn or its ancestry is a sidechain (subagent) record, not the parent session.
<a id="agent"></a>
### `agent`
The conversation ancestry passes through a subagent record.
<a id="cycle"></a>
### `cycle`
The journal's parent links form a loop.
<a id="identity"></a>
### `identity`
The journal path, its directories or the file failed the identity checks: a
symlink, a foreign session, the wrong directory layout, a different file, or a
journal that shrank. A rerun hits the same check.
<a id="oversized-invocation"></a>
### `oversized_invocation`
The current `/autoplan` invocation needs more journal records read in full
than the 32 MiB retained-data bound (`OWNED_RETAINED_MAX_BYTES`). The guard
indexes every record without its content and reloads in full only what it
evaluates: snapshot init results, guarded and close-packet Reads, structured
Bash results, error results, assistant text after the first close-packet Read
and edits of the active plan. A rerun reads the same records; use the fallback.
<a id="malformed"></a>
### `malformed`
A complete journal line is not valid JSON or UTF-8, or its records contradict
each other.
<a id="journal-missing"></a>
### `journal_missing`
The session journal named by the hook does not exist after 2 seconds.
<a id="event-order"></a>
### `event_order`
The journal's events could not be put in a consistent order for this session.
<a id="tool-identity"></a>
### `tool_identity`
Two journal records claim the same tool call identity.
<a id="current-mismatch"></a>
### `current_mismatch`
The journal records the current call with a different tool or input than
Claude Code passed to the hook. Only `run_in_background` (which Claude Code's
fork-subagent schema drops) and the spelling of `file_path` may differ.
<a id="agent-key"></a>
### `agent_key`
The reviewer dispatch carries a key outside `prompt`, `description`,
`subagent_type` (`general-purpose` only) and `run_in_background`. A model
override is not allowed for /autoplan reviewer dispatch. The log records the
key names, never their values.
<a id="cross-phase-batch"></a>
### `cross_phase_batch`
One assistant message enters two different phases. Calls that enter the same
phase may share a message; another phase needs its own message after the
previous report.
<a id="init-mismatch"></a>
### `init_mismatch`
The snapshot init result or its artifacts (restore point, active plan header)
do not match this invocation.
<a id="snapshot"></a>
### `snapshot`
A phase snapshot, methodology or other immutable artifact is missing, aliased,
writable or changed.
<a id="dispatch-prompt"></a>
### `dispatch_prompt`
The reviewer prompt differs from the snapshot's exact `nativeDispatchPrompt`.
<a id="evidence"></a>
### `evidence`
An artifact the guard needed could not be parsed.
<a id="publication-repeat"></a>
### `publication_repeat`
The report was published separately once in this invocation and still cannot
be verified, so Claude Code is not writing it to the journal in time.
## Corrective denials
<a id="publication-missing"></a>
### `publication_missing`
No filled report for the previous phase appears after its close packet Read.
Publish it as your own assistant text in a message whose only tool call is
`true autoplan-published <phase>`, then enter the next phase in a later message.
<a id="publication-unflushed"></a>
### `publication_unflushed`
The report shares the current call's message, or nothing journaled follows it
yet. Publish it in its own message with the no-op call, then enter the next
phase in a later message. A second occurrence in one invocation becomes
[`publication_repeat`](#publication-repeat).
<a id="close-required"></a>
### `close_required`
Finish the previous phase's close procedure and Read its close packet.
<a id="close-incomplete"></a>
### `close_incomplete`
Read every line of the current close packet.
<a id="close-stale"></a>
### `close_stale`
The close packet or its checkpoint no longer matches the current phase input.
Prepare a fresh packet and read it.
<a id="close-edits"></a>
### `close_edits`
The plan changed after the close Read in a way the guard cannot reconstruct,
or it fails its phase check. Repeat the close procedure.
<a id="init-required"></a>
### `init_required`
No successful snapshot init for this invocation. Run the existing init step.
<a id="init-own"></a>
### `init_own`
A new `/autoplan` turn needs its own init (it may answer `reused: true`).
<a id="init-failed"></a>
### `init_failed`
The init step failed. Complete it first.
<a id="init-unbindable"></a>
### `init_unbindable`
Init ran through a shell variable, substitution, chaining, a pipe or a
redirect. Re-run it as one Bash call with literal absolute paths.
<a id="phase-order"></a>
### `phase_order`
Enter Phase 1 (CEO) before a later phase.
<a id="hook-input"></a>
### `hook_input`
The hook could not read its input. Restore the installation (`./setup`).
<a id="installation"></a>
### `installation`
The hook failed unexpectedly. Restore the installation (`./setup`).
<a id="foreign-install"></a>
### `foreign_install`
The phase file belongs to another gstack installation than the hook. Restore
this installation (`./setup`).
## Transient denials
<a id="entry-pending"></a>
### `entry_pending`
A phase-entry call from an earlier message has no result yet. Wait for it.
<a id="mutation-pending"></a>
### `mutation_pending`
An edit to the active plan after the close Read has no result yet. Wait for it.
## Removed codes
<a id="changing"></a>
### `changing`
Before the October 7, 2026 release, `changing` denied a call when Claude Code
appended to the journal while the guard read it. The bounded reader reads the
bytes present at open and ignores a trailing record still being written, so
appends never fail a read; a changed prefix is [`rewritten`](#rewritten).
<a id="current-missing"></a><a id="pending-read"></a>
Before the October 7, 2026 release, "Native parent evidence has not reached
the journal yet" (no code) and "Current native phase-entry identity is
required before entering a new phase" denied calls Claude Code had not yet
journaled. The payload path replaced both.
## Claude Code settings
`CLAUDE_CODE_FORK_SUBAGENT=false` is no longer needed (keeping it is harmless).
With the fork-subagent gate on, reviewer dispatches may run in the background:
the dispatch returns a launch receipt and the review arrives later as a
completion notice. Wait for that notice before closing the phase. A background
reviewer keeps the invocation armed, so a typed message while it runs does not
end `/autoplan`.
### Permission cards after a background reviewer
A skill's `allowed-tools` applies only to the turn that invoked it, and a
background reviewer's completion notice starts a new turn. From then on Claude
Code's normal permission rules apply, so Reads outside the session's working
directory can show a card, and in Manual mode so do Bash commands that are not
read-only. Skill hooks stay registered for the whole session but do not run
inside subagents.
`/autoplan` therefore keeps its own files readable without a card:
- The restore point and every phase artifact (methodology, reviewer input,
snapshots, close packet) live in the project's `.gstack/tmp/autoplan/`, which
Step 1 adds to `.git/info/exclude`. Claude Code reads files in the working
directory without a card, for `/autoplan` and for its reviewer subagents. A
`git clean -x` deletes them, restore point included.
- The publication hook approves `/autoplan`'s own Reads outside the working
directory: this installation's `autoplan/sections/*.md`, and the immutable
artifacts in `<repo>/.gstack/tmp/autoplan/` when the session started in a
subdirectory of the repository. It approves nothing else, and never a call
the guard denies.
A session started in a repository subdirectory still shows a card when a
reviewer reads its input: subagents run without the skill's hook. Start the
session at the repository root, or answer the card with "Yes, allow reading
from ... during this session". In Manual mode, `/autoplan`'s Bash commands
after the first background reviewer also show cards; auto mode, the default
starting mode on current Claude Code for supported models, sends them to its
classifier instead.
## Supported journal roots
The guard accepts exactly one root per journal file:
- A user message with no parent (sessions without hooks).
- An unbroken chain of message-less `SessionStart` hook attachments
(`hook_success`, `hook_additional_context`, ...) that starts at a null parent
and ends at the first user turn. Claude Code writes this when any
`SessionStart` hook is installed, including hooks that plugins add. It also
writes one after `/clear`.
- A `compact_boundary` record whose logical parent is not in the file, but only
when it is the file's first record. Claude Code writes this when you resume a
compacted session with `--fork-session`.
`--continue`, `--resume` and `/compact` append to the same journal, and the
guard follows them through their existing parent links. The real journals
these rules were checked against came from Claude Code 2.1.284
(`test/fixtures/claude-native-journal-roots-2.1.284.json`); the periodic
`autoplan-journal-drift` canary re-checks the pinned Claude Code.
## The decision log
Every guarded decision appends one line to
`<state root>/analytics/autoplan-guard.jsonl` (normally
`~/.gstack/analytics/autoplan-guard.jsonl`): `schema`, time, `decision`
(`allow` or `deny`), `disposition`, `code`, `path` (`journal`, `payload` or
`none`) and the Claude Code version. It never holds content; an `agent_key`
denial adds the key names, and an unrecognized shape adds record type names.
The file keeps the newest 1,000 lines once it passes 256 KiB. A failure to
write it never changes a decision.
## Windows paths
Claude Code and Git Bash can spell one path as `C:\x`, `c:\x`, `C:/x` or `/c/x`.
The guard treats these as the same path. It does not resolve `.` or `..`, so a
path containing them is still rejected.