The readers of this page are the task subagent of a ticket, and the orchestrator for the plain-form rule, the orchestrator-command rule and the tool-block rule. Each other actor of the table also reads the tool-block rule: the planner subagent, the issue-draft, issue-review and issue-post subagents, the write subagent, the opener subagent, the reuse subagent and a question session. The planner and the operator also read it.
This rule applies to each tasker command that the task subagent runs and that changes a task. Examples are start,
plan, refine, approve, execute, verify, review, dismiss-review, accept, merge, finish,
update-branch, retry and resume. The task subagent runs each such command alone in its own Bash call (one call of
the Bash tool of the task subagent). The call has the plain form: tasker <command> <issue> and the options of the
command, for example tasker accept codeguru42/tasker#81. The issue key has no quotes. No cd comes before the
command, no pipe comes after it, and no other command is in the same call. A feedback text goes in as one argument, as
in tasker refine <issue> "<feedback>". Inside double quotes, the shell expands backticks and $. Put the feedback
text in single quotes, or keep backticks and $ out of it. For feedback text from a file, the one allowed form is
tasker refine <issue> "$(cat <absolute path of the file>)". tasker review <issue> "<feedback>" takes the same form.
No other command substitution is allowed. The shell does not expand backticks or $ in the text of the file. As a
result, the warning above covers only the text on the command line.
The reason: the repo file .claude/settings.json allows Bash(tasker *). A Bash call matches this permission rule only
when the call is one tasker command. Claude Code sends a call that does not match to the classifier of its auto mode
(the check that allows or denies a tool call). The classifier can deny the call. A form that ran before can still get a
denial.
If the classifier denies a tasker command in the plain form, the task subagent does not try another form. The task
subagent follows the tool-block rule. The command did not run.
The plain-form rule does not cover these:
- A read-only
taskercommand, which does not change a task. Examples aretasker show,tasker status,tasker show-plan,tasker show-review,tasker show-quotaandtasker doctor. The orchestrator-command rule gives the list of read-only commands. Such a command can have a pipe, for exampletasker show-quota | jqin "Quota". - A change to
.claude/settings.json. The rule does not change the permission rules of the repo.
A read-only command is a tasker command that changes no task, no configuration file and no installed file. A task
change is a tasker command that changes the state or the record of a task, its worktree or its branch. The task
subagent of a task is the task subagent that the orchestrator started for the ticket of that task.
The orchestrator runs only read-only commands itself. A task subagent runs each task change. The reason: the plain-form rule and the command rules cover the task subagent. So does "What the task subagent does".
These commands are read-only:
tasker show-config,tasker show-config-schema,tasker show-quotaandtasker status.tasker show,tasker show-bootstrap,tasker show-plan,tasker show-questions,tasker show-verifyandtasker show-review.tasker doctor.tasker modelwith no new model and no--effort.tasker --version,tasker --helpandtasker help.
These commands are task changes: start, plan, refine, reopen, approve, unapprove, execute, verify,
review, dismiss-review, retry, resume, approve-credits, accept, merge, push, open-pr, mark-landed,
update-branch, finish and abort. No session runs approve-credits, as Limits says.
A command that neither list names is not a read-only command. The orchestrator does not run it.
tasker status and each show-* command that reads one task stay read-only after they find a dead run. They only
report the dead run, as A dead run says. A schema migration after an install also keeps a command
read-only, because the migration comes from the install. See Schema versions.
The rule has two exceptions:
- An installing orchestrator runs
npm run install:global, which runstasker install-skills, as the hold before an install says. - The orchestrator runs
tasker modelwith a new model or with--effortitself, only on the words of the user in a settled decision message of its question pane. This command writes the configuration file of tasker. If the user types such a request in the tab of the orchestrator, the orchestrator does not run the command. It asks the question in its question pane, and it runs the command only after the settled decision message.
The rule covers only tasker commands. The gh, git and herdr commands keep their own rules.
To run a task change, the orchestrator sends the command to the task subagent of the task. The task subagent runs it
under the plain-form rule and the command rules, and it reports the result. An ended task subagent gets the command in a
message, because a message starts it again, as "Terms" in "Quota" says. A task with no task subagent
of this orchestrator gets a new task subagent for this one task change. An example is a parked task of an earlier
session. The prompt of a task subagent gives the prompt for this
task subagent. Each step after a task change stays. An example is Delete the job after the
final report of an abort. If the send or the start fails, the failure rule applies. The
command did not run, and the orchestrator does not run it itself. The write subagent of a question pane runs no tasker
command.
The orchestrator never runs a denied task change. On the word of the user, the task subagent runs the call again in the form that the user names. Or the user runs the exact call. The tool-block rule links here.
A tool block is a denial of a tool call. The permission rules, the classifier of auto mode or the user can deny a call. The user denies a call when the user declines it at a permission prompt.
Each actor of the table follows these steps for a denial. The report chain gives the path of each report.
- After a denial, the actor runs the denied action in no other form and no part of it. It stops that step. It reports the exact call, the exact text of the denial, the folder of the call, the step and the purpose to its starter.
- After a check failure, the actor first runs the same call again one time, in the same form. A second check failure is a denial of step 1.
- A starter that gets the report sends it on to its own starter, up to the orchestrator.
- On the word of the user, the actor that got the denial runs the call again one time, in the form of the word. For a task subagent, the orchestrator relays the word. For a write subagent, the steps of the paragraph of the question pane that starts "The commands after the denied call wait" apply. For an issue subagent, the orchestrator relays the word to the planner subagent, and the planner subagent relays it to the issue subagent.
- No third actor runs the denied call. The one exception: the orchestrator runs a call of a task subagent on the word of the user, as the paragraph that starts "After a tool block" says, but never a task change. Without a word of the user, no actor runs a form of the call.
- The orchestrator brings each denial to the user in its question pane. It gives the choices of
A denied command of the operator, with no
!run. For a check failure, the check-failure bullets below apply. - Only the user approves a permission prompt, in the session where Claude Code shows it. A word of the user in a decision message or in a relayed message approves no permission prompt. The recommendation mode of A decision of the user never covers a denial.
A task subagent runs a git command in the local clone of the orchestrator with git -C <clone>, not with
cd <clone> && git ... in a chain.
A delete with a lease of a task branch on origin can get a denial of the classifier of auto mode. If the classifier
denies this delete, the task subagent reports the exact text and the exact call, as the paragraph that starts "After a
tool block" says.
A denial covers the whole action of the call, not only its form. After a tool block, the task subagent runs the denied
action in no other form, and no part of it, until the orchestrator sends the answer. Other forms include a script file
with the same commands, a split of the action into several calls, and the same commands with other paths or names. On
2026-10-17, the user declined a fact test with rm -rf, and the task subagent of #231 ran it from two script files
before the answer came.
Claude Code checks a Bash call against the allow rules part by part. A compound call is one Bash call that holds two or
more commands, for example a chain with &&, || or ;, or a pipe. A part is one command of a compound call. For a
match, each part of the call must match an allow rule. Claude Code splits a call at &&, ||, ;, |, |&, & and
newlines. This holds for each allow rule, not only for gh.
On 2026-11-12, the section "Compound commands" of https://code.claude.com/docs/en/permissions said:
Claude Code is aware of shell operators, so a rule like
Bash(safe-cmd *)won't give it permission to run the commandsafe-cmd && other-cmd. The recognized command separators are&&,||,;,|,|&,&, and newlines. Every subcommand must be allowed for a compound command to run without a prompt, for example because the subcommand matches an allow rule or is a read-only command.
Claude Code checks the target of a redirect by itself. A redirect is a > file, >> file or 2> file in a Bash call.
The check uses the Edit rules, the protected paths and the working directories. A working directory is a folder where
Claude Code allows file edits with no prompt. An allow rule of the command does not cover its target. A target outside
the working directories, with no Edit allow rule, matches no rule.
On the same day, the section "Redirections" of the same page said:
When a command redirects output or input, Claude Code checks the redirect target against your file rules as if Claude wrote or read that file directly:
- Output redirects: for
> file,>> file, or2> file, the check covers yourEditallow and deny rules, protected paths, and the working directories. A rule such asBash(git commit *)allows the command, not the target. A target that starts with~or contains a glob character needs your approval.
A call that matches no rule goes to the classifier. The classifier decides from the context of the conversation. In a subagent, the same decision order and the same rules apply as in the parent session.
A background subagent is a subagent of the Agent tool that runs in the background of a top-level session. The user types no message in the conversation of a background subagent. A word of the user reaches it only in the prompt or in a message of the parent session.
On the same day, the section "How the classifier evaluates actions" of https://code.claude.com/docs/en/permission-modes said:
Each action goes through a fixed decision order. The first matching step wins:
- Actions matching your allow, ask, or deny rules resolve immediately, with these exceptions:
The list of exceptions names no gh command. Step 3 of the same list said:
Everything else goes to the classifier, apart from critical-path removals under their default handling.
After the list, the same section said:
In the classifier requests sent by Claude Code itself, the classifier sees user messages, tool calls other than read-only lookups such as file reads and searches, and your CLAUDE.md content.
The section "How auto mode handles subagents" of the same page said:
While the subagent runs, each of its actions goes through the same decision order as in the parent session, with the same block and allow rules.
No part of a denied call runs. This includes a redirect or a command before the denied part.
After a tool block, the task subagent stops. It reports the exact text of the denial, the exact command, the step of the work that the command belongs to, and the purpose of the command. The orchestrator tells the user these facts. For a denied task change, the orchestrator never runs the blocked action, as the orchestrator-command rule says. For each other denied call, the orchestrator does not run the blocked action for the task subagent, unless the user tells it to. The recommendation mode of A decision of the user does not cover a tool block: the orchestrator always waits for the user. The report says that the denied call did not run. It names no file and no output of the denied call as made. This also applies to each other report of a denial, as the paragraph that starts "Each report of a denial quotes" lists them.
Each report of a denial quotes the exact denied call word for word, as the transcript of the session that ran the call
holds it. A short form or a description of the call does not take its place. This also applies to an item, a later
correction of a report, a summary of past denials and a short question to the user. If a report of a denial gives no
exact call, the session that gets the report asks the sender for the exact call. It asks before it states or changes a
conclusion that rests on the call, for example before the operator tells the user such a conclusion. In the quote, a
token, a key or a password becomes [redacted], and on GitHub, $HOME replaces the path of the home folder.
On 2026-11-07, planner-m16 first gave a denied call to operator-m16 as "a plain comment with no guard". The exact call
was
tail -n +3 /tmp/tasker/m16/drafts/768-comment.md > /tmp/tasker/m16/drafts/768-comment-body.md && gh issue comment 768 --body-file /tmp/tasker/m16/drafts/768-comment-body.md.
On that short form, operator-m16 told the user that the denials of that day did not fit the guess that a chain caused
them. Then operator-m16 withdrew that guess. The exact call later showed that the denied call was a chain.
The classifier of auto mode can deny a gh write of a follow-up planner. The follow-up planner sends the exact command,
the folder and the exact text of the denial to orchestrator-<slug>, which asks in its
question pane. The user runs the command and gives the exit code and the output to the
question session in the pane. The question session sends them in its decision message, as
Send a decision says.
The message to the planner gives the output of the command, or says that the command did not run. The output goes with the words of the user. If the command ran, the planner goes on with its work. If it did not run, the step stays open, and the planner runs the action in no other form.
An initial planner gives the user the command directly. A check failure keeps its own bullets. On 2026-10-30, the
classifier denied gh issue comment and gh issue edit of planner-m26, and the user ran each command.
A check failure is a denial whose text says that the classifier of auto mode gave no verdict. A check failure is a tool block, with these differences:
- After a check failure, the task subagent runs the same call again one time, in the same form. The text of the failure permits this one try. For a check failure, this one try wins over the paragraph that starts "A denial covers the whole action" and over the stop of the paragraph that starts "After a tool block". Apart from this one try, the task subagent runs the action in no other form, and no part of it, as the paragraph that starts "A denial covers the whole action" says.
- If the second try runs, the task subagent continues its work. If the second try also fails with a check failure, the task subagent stops, as the paragraph that starts "After a tool block" says. In its report, the task subagent also says that the denial is a check failure. If the second try gets a denial that is not a check failure, that denial is a tool block with none of these differences.
- For a check failure, the orchestrator tells the user the exact command and the link https://status.claude.com/. The
task subagent also gives the folder where the call ran, and the orchestrator tells the user that folder. The user can
run the command with the
!prefix of Claude Code, which does not go through the classifier. If the user runs the command, the orchestrator tells the task subagent in its answer that the command ran, with its output. - The orchestrator follows the same steps for a check failure of its own call: it runs the same call again one time, in
the same form. If that try also fails with a check failure, the orchestrator tells the user the exact command and the
link, so that the user can run the command with the
!prefix. - A planner follows the same steps for a check failure of its own call. If the second try also fails with a check
failure, a follow-up planner sends the question to
orchestrator-<slug>, which gives the user the link in its pane. The paragraph that starts "The classifier of auto mode can deny" and the paragraphs after it give the steps of the question. An initial planner gives the user the command and the link directly. - Each other actor follows the same steps for a check failure of its own call. A second check failure goes up the report chain to the orchestrator.
A check failure is the one case where the user can run the call with the ! prefix, because the classifier gave no
verdict.
On 2026-10-25, in the session of #428, each Bash call that no permission rule allowed failed with this text:
The server-side auto mode classifier gave no verdict (error), so auto mode cannot determine the safety of Bash. This is a transient failure of the check, not a judgment about the action: a later response may get a verdict. You may try the action again once, as-is. Repeated attempts are slowed by a growing delay, and after 10 responses in a row without a verdict the turn stops.
The user then ran gh issue create with the ! prefix, and the posts of #482 and #483 worked.
The script scripts/denial-records.ts finds each denial of the classifier of auto mode in the transcripts of Claude
Code on the machine of the user. It makes one record for each denial. It keeps the records in a file outside any
session, $HOME/Documents/tasker/denials/store.jsonl. The reason: a transcript is a file of one session, and no session
reads all of them. The file holds the text of the assistant, so it stays on the machine of the user.
The script replaces each known form of a token, a key or a password with the mark [redacted]. It does this before it
writes a record. The script holds the list of the forms. The list is a guard, not a proof, because a token of another
form stays in the record. A form can also replace text that is no token.
The script makes a record only for a session that started in the local clone of this repo.
The script reads the transcripts in the form of Claude Code 2.1.318. It keeps the fields serverClassifierContext and
serverClassifierRequest out of each record, because they can hold the text that Claude Code sends to the classifier.
The script also says whether an allow rule matches each part of a denied call. That match is a guess of the script, not
the match of Claude Code.
A planner makes the records on the word of the user, with these steps:
- In the local clone, run
node scripts/denial-records.ts scan --store $HOME/Documents/tasker/denials/store.jsonl --out /tmp/tasker/<slug>/denials. The scan prints one line for each new record, a record that is not in the store file yet. - If the scan exits with an error, tell the user the output and stop.
- If the scan lists no new record, tell the user so and stop.
- Show the user the lines of the new records and the path of
/tmp/tasker/<slug>/denials/records.jsonl. Also show thestorecommand of step 5 with the id of each new record, and its undo step. A follow-up planner sends the question of step 4 toorchestrator-<slug>with these parts. - On the word of the user, run
node scripts/denial-records.ts store --store $HOME/Documents/tasker/denials/store.jsonl --out /tmp/tasker/<slug>/denials <id>..., with the id of each new record that the user keeps. If the user keeps no record, run nostore. - If
storeexits with an error, tell the user the output and stop. - Tell the user the output
<new> stored. A follow-up planner sends it as a report toorchestrator-<slug>.
Before step 4, the planner runs stat -c %s $HOME/Documents/tasker/denials/store.jsonl. It also runs test -d on
$HOME/Documents/tasker/denials, $HOME/Documents/tasker and $HOME/Documents. It keeps the results. If the store
file exists, the undo step of the store is truncate -s <size> $HOME/Documents/tasker/denials/store.jsonl. If no
store file exists, the undo step is rm $HOME/Documents/tasker/denials/store.jsonl. Then the undo step runs rmdir on
each of the three folders that did not exist, the deepest folder first.
Before step 5, the user can change a line of records.jsonl. Then store keeps the changed line, after it replaces
each known form again. <slug> is the slug of the planner, as docs/dev/GLOSSARY.md defines it.
The store file is state of the user, as The state of the user defines it. Only a
planner runs store on this file, and only the user approves step 5. So the question of step 4 is a question for the
user alone, as The open items says. A task subagent, the orchestrator, a ticket
subagent and a review agent run no store on this file.
If the classifier denies scan or store, the planner runs that step in no other form and in no part. It tells the
user the exact command and the exact text of the denial, and a follow-up planner sends them to orchestrator-<slug>.
The planner gives the user no command with the ! prefix for these steps.
An issue that uses the records says that its task subagent reads the store file. A record goes to no issue, no comment
and no doc. An issue, a comment or a doc gives only counts and conclusions from the records. A count or a conclusion can
name a list form.kinds or a write key. It names no write key of a record with otherProject true.
These rules apply to each tasker command that the task subagent runs, also to a read-only one. They add to the
plain-form rule and do not change it.
-
Give the full issue key, for example
codeguru42/tasker#90. A bare number such as90does not resolve to an issue. As a result, eachtaskercommand that takes an issue key fails, alsotasker status --issue. Issue keys gives the forms of a key, and Shared errors gives the error and its exit code. -
Never wrap a
taskercommand intimeout. At the end of the time,timeoutsends SIGTERM, and tasker moves the task tointerrupted. -
Run a long
taskercommand in the background. The long commands includeplan,refine,execute,verify,reviewandresume. The task subagent sets therun_in_backgroundoption of its Bash tool. The call keeps the plain form. -
To wait for the end of a long command, wait for the report of the Bash tool that the background job of the command ended. Do not wait with a loop that reads the state in
tasker status. Such a loop is not reliable. For example, a review run can end inawaiting_work_reviewor inreviewed, so a loop that waits while the state isreviewingcannot tell the end from the start. The Bash tool gives its report after a Bash call of the task subagent ends. While the task subagent waits, it runs a short wait in another Bash call, for exampletimeout 100 bash -c 'while :; do sleep 15; done'. This call always exits with 124. If no report came, the task subagent runs the same wait again. After the report, the task subagent reads the state withtasker show <issue>. When the orchestrator starts the task subagent again, the task subagent follows "What the task subagent does" in "Quota". -
Do not wait for a process with
pgrep -f. -
Start a
taskercommand that reads a feedback file only after the result of the last write of that file. A feedback file holds the feedback text of ataskercommand in the form"$(cat <absolute path of the file>)"of the plain-form rule. Never send the write of the file and the command as parallel calls of one message. If the result of the write reports a problem in the text of the file, fix the file first. Then wait for the result of the write of the fix too.The session gets the results of the calls of one message only after it sends all of them. A hook of Claude Code is a command that Claude Code runs at an event of a session. The setup of a user can have such a hook that checks the text of each file that the Write tool writes. As a result, a report of such a hook can reach the session after the
taskercommand of the same message read the file. -
When the output of a read-only
taskercommand goes into a pipe, start the call withset -o pipefail. As a result, a failedtaskercommand stops the chain. To keep only some lines, usesed -n, for examplesed -n '1,20p', nothead. Withpipefail,headcan make the pipe exit with 141 when tasker succeeded, becauseheadstops reading early. -
The output of
tasker startcan say that it moved the card of the issue. If it does not say so, do not expect that move.
The installed tasker is a build of this repo, as the intro of docs/orchestrator.md says.
tasker --version prints the version of the build. The intro of docs/dev/release.md gives the forms of
the version.
Each fact of this page that names the installed tasker, for example each fact of this section, describes a behavior of
the installed tasker. The fact is not a requirement for later work. If a ticket depends on such a fact, the task
subagent first does the fact test against the installed tasker. The reason, in the
words of the user: "We need to verify that the tasker behavior we are changing actually exists before trying to change
it."
The fact test can show that the installed tasker does not have the behavior. Then the fact is out of date. The task subagent gives the fact, the command and the output in the feedback text and in the lessons of its final report. The lesson goes to the planner, and the planner files a ticket for the fact. If an open issue already covers an out-of-date fact, the task subagent names that issue in place of the lesson.
The task subagent cannot always measure such a behavior, for example when no task of its own is in the state that the fact needs. Then the task subagent reports the fact as a fact that it cannot test, in the feedback text and in its final report. A ticket that only records such a fact does no fact test, as the user decided for #366. Such a ticket depends on no fact of the list. As a result, the rule that the task subagent first does the fact test does not apply to it.
tasker plancan fail with "planning returned no structured output; the assistant produced no plan object". The task goes tofailed. This failure does not come from the code. Onetasker retry <issue>plans again.- When the login of the Claude account expires during
tasker execute, the execute session ends.tasker executethen fails withexecuting todo '<todo>' ... failed: claude exited 1. The task goes tofailed, and the task branch is unchanged. This failure does not come from the code. After the user logs in to Claude again,tasker retry <issue>moves the task toapprovedand runstasker executeagain. tasker startcan wait about 10 minutes ongit ls-remoteover ssh and then fail with a git transport error. Iftasker doctorthen passes, the task subagent runstasker startagain.tasker update-branchprintsorigin/<branch> does not exist; nothing to sync fromfor a task branch that was never pushed. This output is normal.tasker dismiss-reviewprintsdismissed findings <positions> of review <number> of <issue key>. This output is normal.tasker mergeprintslanded: <commit> on origin/main.tasker finishprints that it marked the issue done on the tracker, and it closes the issue.tasker startcan print a GraphQL warning that the assign of the issue on the tracker failed. The warning does no harm.tasker startrefuses a ticket whose parent is not ready to stack. It exits with 1 and prints<parent issue key>: blocking issue is still open. No task exists after the refusal.tasker refine,tasker execute,tasker verify,tasker reviewandtasker acceptrefuse a stacked task whose parent has landed. They printthe parent <parent key> of <issue key> has landed; run tasker update-branch <issue key> to move the task onto <base that the walk ends on> first. The task keeps its state.tasker mergeprints the same error, and it printsthe parent <parent key> of <issue key> has not landed; land the parent first, then run tasker update-branch <issue key>while the parent is in flight (see the stacked-task guards).tasker update-branchrebases only the commits of the task onto the base that the walk ends on.- A stacked task in
awaiting_plan_reviewloses its base whentasker finishof the parent deletes the branch of the parent.tasker refinethen fails with exit code 1 and the landed error of the moved-base guard, and it changes nothing.tasker update-branchmoves the task onto the base that the walk ends on, and the task stays inawaiting_plan_review. tasker marks the plan as stale, so a refine comes beforetasker approve, also when the new base changes no fact of the plan. - A task can fail in
executingwhile its base ismainand its task branch holds no commit of the task. For such a task,tasker update-branchmoves the task branch by fast-forward. The approved plan of such a task stays approved, and the task stays infailed. After the update,tasker showprintsnext: tasker retry. tasker update-branch <issue> --take-remoteof a stacked task whose parent landed moves the base of the task to the base that the walk ends on, for examplebase: main, and the task toexecuted, in one run.- If a task is stacked on the same parent as another task, the shared-file warning of
tasker refineandtasker approvefor that task lists the files of the parent too. The warning reads the files that the branch of the other task changes against the base, and that branch holds the commits of the parent. tasker update-branchprints the command that undoes the update after each run that moved the head, also with--strategyor--take-remote. A run moved the head when its base step or its sync step moved it. The output givesprevious HEAD was <hash>, and the command istasker update-branch <issue> --undo.- When the rebase of
tasker update-branchstops with a conflict, the output names each conflicting path. - After
tasker update-branch, the bootstrap of the task does not run again. If the new base changespackage-lock.json,tasker verifyfails on the oldnode_modulesof the worktree of tasker. The fix is a refine that tells the execute session to runnpm ci. For the verify-failure rule, this failure comes from the code. The task subagent sends one refine whose feedback tells the execute session to runnpm ci, and it runs notasker retry. A commit check that finds no broken commit does not change this case.
Since #833, an execute run of a plan with many todos can reach the deadline of limits.executeTimeoutMin before all
todos are done. This timeout is expected. The run fails with an error that ends with timed out after <n> min, and the
task goes to failed. A done todo stays done, as Execute of docs/dev/tasks.md says.
If tasker execute fails with a timeout, run tasker retry <issue> one time for that run. Run it in the background, as
the command rules say for a long command. The retry runs tasker execute again with a new
deadline, and a done todo gets no turn. If the execute run of the retry also fails with a timeout,
stop. Otherwise, run tasker show <issue> after the retry. Follow the commands that
it prints.
The user can raise limits.executeTimeoutMin in the configuration file of tasker. limits of
docs/config.md gives the default of 90 minutes.